From 71dfda740055d286e12359b217dd60d87805d122 Mon Sep 17 00:00:00 2001 From: Aaron DeRuvo Date: Thu, 13 Jun 2024 13:56:10 +0300 Subject: [PATCH 1/3] Celo block properties explanation --- src/celo/new-celo-interfaces.d.ts | 154 ++++++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 src/celo/new-celo-interfaces.d.ts diff --git a/src/celo/new-celo-interfaces.d.ts b/src/celo/new-celo-interfaces.d.ts new file mode 100644 index 0000000000..078e7c7fa8 --- /dev/null +++ b/src/celo/new-celo-interfaces.d.ts @@ -0,0 +1,154 @@ +import type { OpStackBlock } from '~viem/chains/index.ts' + +/* + * A comparison how block structures on Celo. There are essentially 5, + * - Blocks produced by Celo as a Layer 1 + * & Pre GingerBread + * & Post GingerBread + * - Blocks produced by Celo as a Layer 1 when fetched thru Cel2 node + * & Pre GingerBread + * & Post GingerBread + * - Blocks Produced by Celo as a Layer 2 + * + */ + +// biome-ignore lint/correctness/noUnusedVariables: +interface PreGingerBreadCel1Block { + baseFeePerGas: quantity | null + difficulty: quantity + extraData: Hex + gasLimit: quantity + gasUsed: quantity + hash: TBlockTag extends 'pending' ? null : Hash + logsBloom: TBlockTag extends 'pending' ? null : Hex + miner: Address + // mixHash is not on these blocks + // Nonce was not on these blocks + number: TBlockTag extends 'pending' ? null : quantity + parentHash: Hash + receiptsRoot: Hex + size: quantity + stateRoot: Hash + timestamp: quantity + totalDifficulty: quantity | null + transactions: TIncludeTransactions extends true ? TTransaction[] : Hash[] + transactionsRoot: Hash + // No uncles or sha3Uncles + // + randomness: { + committed: Hex + revealed: Hex + } +} + +// biome-ignore lint/correctness/noUnusedVariables: +interface PostGingerBreadCel1Block { + baseFeePerGas: quantity | null + difficulty: quantity + extraData: Hex + gasLimit: quantity + gasUsed: quantity + hash: TBlockTag extends 'pending' ? null : Hash + logsBloom: TBlockTag extends 'pending' ? null : Hex + miner: Address + // Note that mixHash is not here + nonce: TBlockTag extends 'pending' ? null : Hex + number: TBlockTag extends 'pending' ? null : quantity + parentHash: Hash + receiptsRoot: Hex + sha3Uncles: Hash + size: quantity + stateRoot: Hash + timestamp: quantity + totalDifficulty: quantity | null + transactions: TIncludeTransactions extends true ? TTransaction[] : Hash[] + transactionsRoot: Hash + uncles: [] + // + randomness: { + committed: Hex + revealed: Hex + } +} + +interface PreGingerbreadBlockOCel2 { + difficulty: quantity + extraData: Hex + gasLimit: quantity + gasUsed: quantity + hash: TBlockTag extends 'pending' ? null : Hash + logsBloom: TBlockTag extends 'pending' ? null : Hex + miner: Address + mixHash: Hash + nonce: TBlockTag extends 'pending' ? null : Hex + number: TBlockTag extends 'pending' ? null : quantity + parentHash: Hash + receiptsRoot: Hex + sha3Uncles: Hash + size: quantity + stateRoot: Hash + timestamp: quantity + totalDifficulty: quantity | null + transactions: TIncludeTransactions extends true ? TTransaction[] : Hash[] + transactionsRoot: Hash + uncles: [] +} + +// biome-ignore lint/correctness/noUnusedVariables: +interface PostGinerbreadPreCel2BlockOnCel2 extends PreGingerbreadBlockOCel2 { + baseFeePerGas: quantity | null +} +// biome-ignore lint/correctness/noUnusedVariables: +interface Cel2Block extends OpStackBlock {} + +// biome-ignore lint/style/useEnumInitializers: +// biome-ignore lint/correctness/noUnusedVariables: Summary of attributes that do not appear on all celo blocks +enum SometimesNullAttributes { + baseFeePerGas, // will be missing for older blocks after move to cel2 + randomness, // removed from all blocks post cel2 + sha3Uncles, // included in all blocks post ginger bread + uncles, // included in all blocks post ginger bread + nonce, // included in all blocks post ginger brea + mixHash, // included in all blocks fetched thru cel2, missing on cel1 +} + +/* + * For viem purposes the important changes are the eventual removal of randomness, and the presence of once missing block attributes + * We would like for viem to be usable both for celo as an L1 and for Celo as L2 at the same time + * as there will be Cel2 testnets available while celo itself remains in L1 mode for a while + * So i envision Intermediate Step where celo block has all possible field with some marked optional. + * And then a Post Cel2 mainnet launch phase + */ + +// the union of all possible block attributes block on celo as l1 and as l2 can have +// biome-ignore lint/correctness/noUnusedVariables: +interface ViemCeloTransitoryBlockInterface { + baseFeePerGas?: quantity | null + difficulty: quantity + extraData: Hex + gasLimit: quantity + gasUsed: quantity + hash: TBlockTag extends 'pending' ? null : Hash + logsBloom: TBlockTag extends 'pending' ? null : Hex + miner: Address + mixHash?: Hash + randomness?: { + committed: Hex + revealed: Hex + } + nonce?: TBlockTag extends 'pending' ? null : Hex + number: TBlockTag extends 'pending' ? null : quantity + parentHash: Hash + receiptsRoot: Hex + sha3Uncles?: Hash + size: quantity + stateRoot: Hash + timestamp: quantity + totalDifficulty: quantity | null + transactions: TIncludeTransactions extends true ? TTransaction[] : Hash[] + transactionsRoot: Hash + uncles?: [] +} + +// biome-ignore lint/correctness/noUnusedVariables: Summary of attributes that do not appear on all celo blocks +interface ViemCeloBlockInterFacePostCel2Launch extends OpStackBlock {} From f1eee8be3de2258a623be9e6c872fb4119c07f51 Mon Sep 17 00:00:00 2001 From: Aaron DeRuvo Date: Thu, 13 Jun 2024 15:11:00 +0300 Subject: [PATCH 2/3] add transaction info --- .../cel2-transaction-interfaces-example.md | 65 +++++++++++++++++++ ....ts => celo-block-interfaces-example.d.ts} | 0 2 files changed, 65 insertions(+) create mode 100644 src/celo/cel2-transaction-interfaces-example.md rename src/celo/{new-celo-interfaces.d.ts => celo-block-interfaces-example.d.ts} (100%) diff --git a/src/celo/cel2-transaction-interfaces-example.md b/src/celo/cel2-transaction-interfaces-example.md new file mode 100644 index 0000000000..e86bf0e757 --- /dev/null +++ b/src/celo/cel2-transaction-interfaces-example.md @@ -0,0 +1,65 @@ + + +# Transactions + +## creating api + +### cip66 + +The new transaction type for paying for gas in fee currencies cip66. +the TLDR is it denominiate fees in CELO instead of FeeToken, which makes is behavior +much more like eip1559 transactions. maxFeePerGas/MaxPriorityFee can now be calculated / built the exact same way as eip1559 transactions. But it has an additional field `maxFeePerFeeCurrency` which serves as the limit / a hedge against exchange rate risk. as the transaction is "billed" in native celo but paid in the fee token. + + +```typescript + +// Explicitly +// here the sender / dev must calculate the maxFeePerFeeCurrency by hand +// this is what https://github.com/celo-org/viem/pull/13 enables +sendTransaction({ + ...typicalEIP1559TransactionParams, + feeCurrency: '0xTokenAddress', + maxFeePerFeeCurrency: 10000000n, +}) + + +// Implicitly +// Today this creates a cip64 transaction, eventually we'd like it to default +// to creating a cip66 by calculating maxFeePerFeeCurrency for the user +// this requires knowing and multiply together +// the maxFeePerGas, the gasLimit, and the exchange rate of CELO to feeToken. +sendTransaction({ + ...typicalEIP1559TransactionParams, + feeCurrency: '0xTokenAddress', +}) +``` + +### op deposit transactions + +finally add the ability to serialize deposit transactions. + +```typescript +sendTransaction({ + from: '0x977f82a600a1414e583f7f13623f1ac5d58b1c0b', + sourceHash: + '0x18040f35752170c3339ddcd850f185c9cc46bdef4d6e1f2ab323f4d3d7104319', + type: 'deposit' +}) + +``` + +this is of course not the same as actually building a deposit transaction, which would be part of celo inclusion in op-stack extensions. + + +## reading api + +The changes here are minimal and it come down to + +1. dont add properties to transactions that dont exist on them (ie `feeCurrency` was added to transactions in viem which did not have have ) + +2. add maxFeePerGas as optional property when it is on the args. + + +`maxFeeInFeeCurrency?: bigint` +`feeCurrency?: Address | undefined` // instead of or in addition to `null`. + diff --git a/src/celo/new-celo-interfaces.d.ts b/src/celo/celo-block-interfaces-example.d.ts similarity index 100% rename from src/celo/new-celo-interfaces.d.ts rename to src/celo/celo-block-interfaces-example.d.ts From 434160b77657a847adb7e3e35d6bcd3429f77a45 Mon Sep 17 00:00:00 2001 From: Aaron DeRuvo Date: Thu, 13 Jun 2024 17:28:30 +0300 Subject: [PATCH 3/3] improve wording --- src/celo/cel2-transaction-interfaces-example.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/celo/cel2-transaction-interfaces-example.md b/src/celo/cel2-transaction-interfaces-example.md index e86bf0e757..5f839da1ff 100644 --- a/src/celo/cel2-transaction-interfaces-example.md +++ b/src/celo/cel2-transaction-interfaces-example.md @@ -55,7 +55,7 @@ this is of course not the same as actually building a deposit transaction, which The changes here are minimal and it come down to -1. dont add properties to transactions that dont exist on them (ie `feeCurrency` was added to transactions in viem which did not have have ) +1. dont add properties to transactions which dont exist on those transactions (ie `feeCurrency` was added to all transactions in returned from rpc despite only existing on the source in a few) 2. add maxFeePerGas as optional property when it is on the args.