Skip to content

Commit

Permalink
Removed spec style info from the operator guide (#1461)
Browse files Browse the repository at this point in the history 
The info removed works better in the specs repo.
  • Loading branch information
@piersy
piersy authored Sep 12, 2024
1 parent 00aef47 commit 9e3f5f9
Showing 1 changed file with 0 additions and 274 deletions.
274 changes: 0 additions & 274 deletions docs/cel2/l2-operator-guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -343,277 +343,3 @@ celo-migrate full --old-db /path/to/old/datadir/chaindata --new-db /path/to/new

- Start the l2 node using the migrated chaindata written to the new-db path.
- Exact command is TBD. Right now we run both op-node and op-geth from source seperately and pass in a bunch of flags to each. We will provide a more user friendly way to start the entire node.

## A history of Celo block structure

Celo started as a fork of go-ethereum but initially made some significant changes to the structure of headers and blocks because it was operating with a proof of stake consensus mechanism.

At the outset Celo blocks lacked the following fields that ethereum blocks had, they were:

- sha3Uncles
- uncles
- difficulty
- gasLimit (the gasLimit was defined by a contract and so had to be retrieved from state)
- mixHash
- nonce

Later in the [Espresso hardfork](https://github.com/celo-org/celo-blockchain/releases/tag/v1.5.0) we introduced dynamic fee transactions but didn’t introduce the baseFeePerGas field on the block header, similar to gasLimit the baseFeePerGas was also retrieved from state via a contract call.

Lacking these fields harmed our compatibility with ethereum tooling (For example ethers.js would crash when trying to work with our blocks) so in our [1.7.0 release](https://github.com/celo-org/celo-blockchain/releases/tag/v1.7.0) we started amending blocks returned over the RPC API by adding gasLimit and baseFeePerGas, however these fields could only be reliably returned by archive nodes since they needed to be looked up in the state, non archive nodes would only be able to return these fields for the most recent 128 blocks.

So further to that in the [Gingerbread hardfork](https://github.com/celo-org/celo-blockchain/releases/tag/v1.8.0) (block 21616000) we added all the fields listed above plus baseFeePerGas to our internal block representation to bring our future blocks into alignment with ethereum. We also added a constant difficulty field of 0x0 to all pre-gingerbread RPC API block responses.

Unfortunately some tooling was still facing problems correctly retrieving the gasLimit for pre-gingerbread blocks so in our [1.8.1 release](https://github.com/celo-org/celo-blockchain/releases/tag/v1.8.1) we hardcoded the historical gas limits for mainnet and our testnets alfajores and baklava, so that all blocks on non archive nodes could correctly and consistently return the correct gasLimit. This was possible since the gasLimit had only been changed a handful of times since genesis.

Celo also added the following fields to block bodies

- randomness
- epochSnarkData

As additions they didn’t damage compatibility at the RPC API level, (API clients would generally ignore them) but in the transition to Celo L2 we plan to remove these fields because they will no longer be needed.

In the transition to Celo L2 we decided to try to improve the situation for our historical blocks with respect to RPC API compatibility by returning all post-gingerbread fields for all blocks. So pre-gingerbread and post-gingerbread blocks retrieved from the Celo L2 RPC API should look the same with the exception of baseFeePerGas which for now we are planning to simply not return for pre-gingerbread blocks.

## Post Celo L2 Block Structure

Going forward, blocks occurring after the transition point will gain an extra field, parentBeaconBlockRoot, which will bring our block structure fully up to date with ethereum’s block structure.

As ethereum evolves in the time before we make the transition to Celo L2 we could end up with additional fields being added to the Post Celo L2 Block Structure, and this document will be updated accordingly.

## RPC API diffs

The diffs here show how the responses for historical blocks or transactions will change going from Celo to Celo L2, so added lines are things that have been added by Celo L2 and removed lines are things that were returned from Celo but will no longer be returned.

### Blocks

#### Pre-Gingerbread hardfork block

The new representation will lack the no longer needed randomness and epochSnarkData fields and gain sha3Uncles, uncles, mixHash and nonce.

Note that baseFeePerGas is not present at all because that value was served from state in celo-blockchain up until the gingerbread fork and so isn’t present after state has been pruned. Currently we don’t have any plan to make this field available in pre-gingerbread blocks on Celo L2.

Note that the size will be different because of the missing epochSnarkData and randomness fields and also the underlying rlp datastructure in Celo L2 differs from the rlp datastructure in Celo.

```diff
"result" : {
"difficulty" : "0x0",
- "epochSnarkData" : null,
"extraData" : "0xd9830...58080",
"gasLimit" : "0x1312d00",
"gasUsed" : "0x9a972",
"hash" : "0xffb7d0446304b765c125381d8b2a37fbf0a5059f82c838cc002144e8fe8905cc",
"logsBloom" : "0x00000...00000",
"miner" : "0x0f5640bd556b0be19262d1817b213ddb3424d91d",
+ "mixHash" : "0x0000000000000000000000000000000000000000000000000000000000000000",
+ "nonce" : "0x0000000000000000",
"number" : "0xb8d",
"parentHash" : "0x6ff6382d2c5a8f64f69d0832fc9dc8bf291e9b89206eee51c9a0c38859b26c70",
- "randomness" : {
- "committed" : "0x0000000000000000000000000000000000000000000000000000000000000000",
- "revealed" : "0x0000000000000000000000000000000000000000000000000000000000000000"
- },
"receiptsRoot" : "0x40eccc03a5ac54b456085a3e6bff9531757bbfa1b4914c8cbb38e1ea34cfd0f4",
- "size" : "0xeab",
+ "sha3Uncles" : "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
+ "size" : "0xe65",
"stateRoot" : "0x13d16289a1d51a0e530c17bc3565f300e67b00a522ec9391f1c5e8dea935efb9",
"timestamp" : "0x5ea0a71b",
"totalDifficulty" : "0xb8e",
"transactions" : [
"0x26a54dbc310f972b9604b2485dcab6c0000ec4f1ddee63f0830ea45be1732b3e"
],
"transactionsRoot" : "0x21148321055f8ef3cb99fa6f45236873b0ebcec61e71f56fa736d6e810ce8149",
+ "uncles" : []
}
```
#### Post-Gingerbread hardfork, pre Celo L2 block
In this case the new representation will lack the no longer needed randomness and epochSnarkData fields.
Note that size will be different, because of those missing fields and also because the underlying rlp datastructure in Celo L2 differs from the rlp datastructure in Celo.
```diff
{
"baseFeePerGas" : "0x12a05f200",
"difficulty" : "0x0",
- "epochSnarkData" : null,
"extraData" : "0xd9830...e8080",
"gasLimit" : "0x2faf080",
"gasUsed" : "0xc6324",
"hash" : "0x0788d066c9ec5f9be68e4c5ae3b0b21ac5117397f7ded16681173a822dd5d0ac",
"logsBloom" : "0x00000...40000",
"miner" : "0x0cdf34e216dab593f00a95b2a4aab735a1b421fc",
"mixHash" : "0x0000000000000000000000000000000000000000000000000000000000000000",
"nonce" : "0x0000000000000000",
"number" : "0x186f055",
"parentHash" : "0xb78d715b3259307f5a4b666a37f40c6e78c492e766c76890738c09560ae63d8e",
- "randomness" : {
- "committed" : "0xeee08bdeb9a5d66a46622f71ada9caef674cbf95995622d0baf5b02fd6d3a4bc",
- "revealed" : "0x4ce6d0a061e32a493369ab843fdb3aad1ef8fcc6f5538bc21b67e7e31c8ac94d"
- },
"receiptsRoot" : "0x2d2b08dc1bfd4dd6b869d689de58e1e84599182391d097576dfc173df4e73372",
"sha3Uncles" : "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
- "size" : "0x93e",
+ "size" : "0x8e4",
"stateRoot" : "0x6032db46a5f98d29363a3ae8fdf4372478585412b09b25daea09f767948d95ba",
"timestamp" : "0x6644a17d",
"totalDifficulty" : "0x186f056",
"transactions" : [
"0xa1a376697cf567f9aaf8d0ebc55e0dbbaf38f1176371da232f2d18242abc6945",
"0x4e40948c406bff9ec14c1191c644df3333d623af821f649e89ca20b0b0a822cf",
"0x030a8962883a822c633f4c7f637730cc38ae950819e59bc32ace21275913dcf8",
"0x515f367706a440dbb2e1f28a765563c0cc6f3b4998340bd681a64467e9df0d25"
],
"transactionsRoot" : "0x330816f861032e379a345d616411ea51e7dadf379d5ae0ebf0b6a92af303070c",
"uncles" : []
}
```
### Transactions
See this page for a summary of transaction types in Celo.
At genesis type 0 transactions on Celo contained 3 extra fields, those were feeCurrency, gatewayFee and gatewayFeeRecipient. These extra fields rendered Celo transactions incompatible with any existing ethereum wallets. To mitigate this and allow use of existing ethereum wallets we extended the definition of type 0 transactions to support the original ethereum transaction format (I.E without the 3 extra fields).
Since it was valid for the celo type 0 transaction to not set the three extra fields in order to distinguish between the two forms of type 0 transaction an extra field (ethCompatible) was added to RPC API responses for type 0 transactions.
Historically we would return these 3 extra fields and ethCompatible on RPC API responses for all transaction types. But this was leading to some confusion since those fields were only relevant for some transaction types.
On our current master branch we have updated the RPC API to omit feeCurrency, gatewayFee, gatewayFeeRecipient and ethCompatible if they are unset and to ensure that ethCompatible is set on all type 0 transactions.
So the mechanism that to determine the specific type of transaction from the RPC response is to:
First consult the type field, if that is non 0 then you are done.
If type is 0 then consult ethCompatible to determine if this transaction has the 3 extra fields.
Transitioning to Celo L2 should have a minimal impact on transaction responses over the RPC API, the Celo L2 node will additionally return chainId for type 0 transactions and yParity for non 0 transaction types.
Note that the gatewayFee and gatewayFeeRecipient fields were never used, so now that we are omitting these unset fields, they will never be returned from either a Celo node or a Celo L2 node.
#### Type 0 eth compatible
```diff
{
"blockHash" : "0x06613bb2a5c75748035e20c06c577669cd4d78f9a1d36ae79eb26ce72dda9c18",
"blockNumber" : "0x16b8f4a",
"ethCompatible" : true,
+ "chainId" : "0xaef3",
"from" : "0x994532b8f186949d7217d7b843509c19e78b9584",
"gas" : "0xa5c6",
"gasPrice" : "0x2540be400",
"hash" : "0xe152376f4b2d3a81f3631cf5830fb820118de3cb3ef5ddb068978829c2712b08",
"input" : "0x3798c...e3083",
"nonce" : "0x2b714",
"r" : "0x1cbba1e5b0c6d9155a56f7f690d59ca46a7deab2bc6aefa4fe89542dbc779c5f",
"s" : "0x66aff5220a9228352bee2a7ac07e9c723bc6bc00311d02338d15ed106b07a608",
"to" : "0x3d00dea966314e47ac3d4acd2f00121351cec1c5",
"transactionIndex" : "0x0",
"type" : "0x0",
"v" : "0x15e09",
"value" : "0x0"
}
```
#### Type 0 not eth compatible with no fee currency
```diff
{
"blockHash" : "0x11d497cf96f94c62db173e27a9aebe7db559d9675e58a9ac268c5c934bffe441",
"blockNumber" : "0x16b8efc",
"ethCompatible" : false,
+ "chainId" : "0xaef3",
"from" : "0x473a3be7c2a42452ed0b521614b3b76bc59d2d1d",
"gas" : "0x8160d",
"gasPrice" : "0x1bf08eb00",
"hash" : "0x6ba6fb0f75a38112bada3a8d3e789d9a5fdce4ea11f35a7ef8b550bcc356d202",
"input" : "0x80e50...00000",
"nonce" : "0x72ce1",
"r" : "0x28ec2e7d544ad737ce7ee4c7d756f00335a764451b5036b44a5bd06cf50262af",
"s" : "0x1d62168d50945e7457d74c095ccca0fbcafb6e5f86d30d1725fad089d1a4c435",
"to" : "0xfdd8bd58115ffbf04e47411c1d228ecc45e93075",
"transactionIndex" : "0x0",
"type" : "0x0",
"v" : "0x15e0a",
"value" : "0x0"
}
```
#### Type 0 not eth compatible with fee currency
```diff
{
"blockHash" : "0x3cd3ee79cd8e1a97e8979ee4d896256a5e369d6c7e3f66e631c8387f561bbbe8",
"blockNumber" : "0x16b8ef1",
"ethCompatible" : false,
"feeCurrency" : "0x874069fa1eb16d44d622f2e0ca25eea172369bc1",
+ "chainId" : "0xaef3",
"from" : "0x0ac70692e0146522dd89dbf99831beaddcd57e8c",
"gas" : "0x31e9e",
"gasPrice" : "0x464abf343",
"hash" : "0x86ba696a70eaf0f973313b0877f611f6500d9673eb51952a4a99c3200af0d249",
"input" : "0xe1d6a...00000",
"nonce" : "0x1",
"r" : "0xb3fdfa10b8faaf1642e7e6e7c04f8e1d3051e61a4e79c4da1bb1f112e72607d2",
"s" : "0x6114be273d1dcb45e485a8f7731666e3c36bfde385c8b47439c92b92d8ceb47f",
"to" : "0x874069fa1eb16d44d622f2e0ca25eea172369bc1",
"transactionIndex" : "0x0",
"type" : "0x0",
"v" : "0x15e09",
"value" : "0x0"
}
```
#### Type 2 (dynamic fee transaction)
```diff
{
"accessList" : [],
"blockHash" : "0x5b77a681e7ff2fc015e074ece54877c50a6ed1e093cc76aabb109846e4544420",
"blockNumber" : "0x16b8f3f",
"chainId" : "0xaef3",
"from" : "0x48cc4c4133cbf40def64b95b002d4ee4d24df846",
"gas" : "0x1ff04",
"gasPrice" : "0x1a13b8600",
"hash" : "0x169500202b491733092159a496f535a9364f69d4059b9b26f39ea8896364ab26",
"input" : "0xa87a2...00068",
"maxFeePerGas" : "0x1dcd65000",
"maxPriorityFeePerGas" : "0x77359400",
"nonce" : "0x6779",
"r" : "0xe76c97eb3184a45d96563bfeca470e9c5f4410f6815a81e1df42ecc2f84d9f7c",
"s" : "0x550fede7177a20024a76cc02dc5fbd6cdefa163ff861441cd9617afceee824",
"to" : "0x4330b35a355c24ac8e544ade2d531050b5b9be7b",
"transactionIndex" : "0x0",
"type" : "0x2",
"v" : "0x1",
"value" : "0x0",
+ "yParity" : "0x1"
}
```
#### Type 123 (Celo dynamic fee transaction v2)
```diff
{
"accessList" : [],
"blockHash" : "0x9abe488547e2e3195dc6e69fbf7e378056f98b3608b69309ef99c358a825cf37",
"blockNumber" : "0x16b8f03",
"chainId" : "0xaef3",
"feeCurrency" : "0x874069fa1eb16d44d622f2e0ca25eea172369bc1",
"from" : "0x06502700eac7123676a7332ba2015dffba021af6",
"gas" : "0x1ec78",
"gasPrice" : null,
"hash" : "0xbe98d102295d6a5c7a26487a6ed7a5d2278cc30c2c8fb065f46bb78a6258090e",
"input" : "0xe1d6a...00000",
"maxFeePerGas" : "0x21b83c7d5",
"maxPriorityFeePerGas" : "0x59eb4bf9",
"nonce" : "0x1f9b",
"r" : "0x68940dd91c0574638344927b53015752c78bc9cf67387f0d0c1f6d22559eeec3",
"s" : "0x412aa02bd215cd0353dd1ffa1f99bbe2ee218e9e7ae3c5b462a568b705534f46",
"to" : "0x874069fa1eb16d44d622f2e0ca25eea172369bc1",
"transactionIndex" : "0x1",
"type" : "0x7b",
"v" : "0x1",
"value" : "0x0",
+ "yParity" : "0x1"
}
```

0 comments on commit 9e3f5f9

Please sign in to comment.