From 606df5ad192ef28dbc44f2dbb140be34ce9e26c7 Mon Sep 17 00:00:00 2001 From: Jonas Theis <4181434+jonastheis@users.noreply.github.com> Date: Thu, 19 Dec 2024 20:13:35 +0700 Subject: [PATCH] feat: add docs about L1 follower node (#374) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: add docs about L1 follower node * Update src/content/docs/en/developers/guides/running-a-scroll-node.mdx Co-authored-by: isabellewei * Apply suggestions from code review Co-authored-by: isabellewei * address review comments * minor fixed and rephrasing * fix * update version and rephrase paragraph --------- Co-authored-by: isabellewei Co-authored-by: Péter Garamvölgyi --- .../guides/running-a-scroll-node.mdx | 167 +++++++++++++++++- 1 file changed, 166 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/developers/guides/running-a-scroll-node.mdx b/src/content/docs/en/developers/guides/running-a-scroll-node.mdx index f040b9ace..d2c8e0de5 100644 --- a/src/content/docs/en/developers/guides/running-a-scroll-node.mdx +++ b/src/content/docs/en/developers/guides/running-a-scroll-node.mdx @@ -19,7 +19,7 @@ For most developers, using [our official RPC endpoint](/en/developers/developer- We recommend using the latest release at https://github.com/scroll-tech/go-ethereum/releases. The required version for Scroll Mainnet is `scroll-v5.5.0` or higher, and for Scroll Sepolia it is `scroll-v5.4.2` or higher. If you'd like to keep up with new node releases, go to https://github.com/scroll-tech/go-ethereum, click on **Watch**, **Custom**, and make sure that **Releases** is selected. -For the remainder of this guide, `VERSION` will denote the version tag. For example, `scroll-v5.7.0`. +For the remainder of this guide, `VERSION` will denote the version tag. For example, `scroll-v5.8.0`. ### Hardware Requirements @@ -139,6 +139,171 @@ Running the node in Docker might have a significant impact on node performance. - Check logs: `docker logs --tail 10 -f l2geth-docker` - Stop the container: `docker stop l2geth-docker` +--- + +## Run L2geth in L1 Follower Mode + + + +Run `l2geth` with the `--da.sync` flag. +Provide blob APIs and beacon node by configuring one or more of the following flags: +- `--da.blob.beaconnode ""` (recommended, if beacon node supports historical blobs) +- `--da.blob.blobscan "https://api.blobscan.com/blobs/"` `--da.blob.blocknative "https://api.ethernow.xyz/v1/blob/"` for Mainnet +- `--da.blob.blobscan "https://api.sepolia.blobscan.com/blobs/"` for Sepolia. + +Strictly speaking a single blob provider is sufficient. +However, configuring multiple providers can help avoid reliability issues. +Using a beacon node with historical blob data is the recommended option (can be in addition to the Blobscan and Blocknative APIs). + + +### Mainnet +```bash +./build/bin/geth --scroll \ + --datadir "tmp/mainnet-l2geth-datadir" \ + --gcmode archive \ + --http --http.addr "0.0.0.0" --http.port 8545 --http.api "eth,net,web3,debug,scroll" \ + --da.sync=true \ + --da.blob.blobscan "https://api.blobscan.com/blobs/" --da.blob.blocknative "https://api.ethernow.xyz/v1/blob/" \ + --da.blob.beaconnode "" \ + --l1.endpoint "" \ + --verbosity 3 +``` + + +### Sepolia +```bash +./build/bin/geth --scroll-sepolia \ + --datadir "tmp/sepolia-l2geth-datadir" \ + --gcmode archive \ + --http --http.addr "0.0.0.0" --http.port 8545 --http.api "eth,net,web3,debug,scroll" \ + --da.sync=true \ + --da.blob.blobscan "https://api.sepolia.blobscan.com/blobs/" \ + --da.blob.beaconnode "" \ + --l1.endpoint "" \ + --verbosity 3 +``` + +A full sync will take about 2 weeks for Scroll mainnet and 2-3 days for Scroll Sepolia depending on the speed of the RPC node, beacon node and the local machine. +Progress is reported as follows for every 1000 blocks applied: + +```bash +INFO [08-01|16:44:42.173] L1 sync progress blockchain height=87000 block hash=608eec..880ebd root=218215..9a58a2 +``` + + +### Troubleshooting +- The node (APIs, geth console, etc) will not be responsive until all the L1 messages have been synced. +- However, the derivation pipeline is already started during the initial sync phase, which can be seen through `L1 sync progress [...]` logs. +- For Scroll Sepolia it might take a little longer (10-20mins) for the first `L1 sync progress [...]` logs to appear as the L1 blocks are more sparse at the beginning. + +You should see something like this shortly after starting: +```bash +INFO [09-18|13:41:34.039] Starting L1 message sync service latestProcessedBlock=20,633,529 +WARN [09-18|13:41:34.551] Running initial sync of L1 messages before starting l2geth, this might take a while... +INFO [09-18|13:41:45.249] Syncing L1 messages processed=20,634,929 confirmed=20,777,179 collected=71 progress(%)=99.315 +INFO [09-18|13:41:55.300] Syncing L1 messages processed=20,637,029 confirmed=20,777,179 collected=145 progress(%)=99.325 +INFO [09-18|13:42:05.400] Syncing L1 messages processed=20,638,329 confirmed=20,777,179 collected=220 progress(%)=99.332 +INFO [09-18|13:42:15.610] Syncing L1 messages processed=20,640,129 confirmed=20,777,179 collected=303 progress(%)=99.340 +INFO [09-18|13:42:24.324] L1 sync progress "blockchain height"=1000 "block hash"=a28c48..769cee root=174edb..9d9fbd +INFO [09-18|13:42:25.555] Syncing L1 messages processed=20,641,529 confirmed=20,777,179 collected=402 progress(%)=99.347 +``` + +#### Temporary Errors + +Especially at the beginning some errors like below might appear in the console. +This is expected, as the pipeline relies on the L1 messages but in case they are not synced fast enough such an error might pop up. +The chain derivation will continue once the L1 messages are available. +``` +WARN [09-18|13:52:25.843] syncing pipeline step failed due to temporary error, retrying err="temporary: failed to process logs to DA, error: failed to get commit batch da: 7, err: failed to get L1 messages for v0 batch 7: EOF: " +``` + +### Limitations + +L1 follower nodes can reproduce the correct `state root` of L2 blocks. +However, currently the derived `block hash` will not match the one seen on L2 follower nodes or Scrollscan. +This is due to the fact that currently the header fields `difficulty` and `extraData` are not stored on DA but these fields are utilized by [Clique consensus](https://eips.ethereum.org/EIPS/eip-225) which is used by the Scroll protocol. +This will be fixed in a future upgrade. + +To verify the locally created `state root` against mainnet, we can do the following: + +```bash +# query local block info +curl localhost:8545 -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_getHeaderByNumber","params":["0x2AF8"],"id":0}' | jq + +# query mainnet block info +curl https://rpc.scroll.io -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_getHeaderByNumber","params":["0x2AF8"],"id":0}' | jq +``` + +By comparing the headers we can most importantly see that **`state root` , `receiptsRoot` and everything that has to do with the state match**. +However, the following fields will be different: + +- `difficulty` and therefore `totalDifficulty` +- `extraData` +- `size` due to differences in header size +- `hash` and therefore `parentHash` + +Example local output for block 11000: + +```bash +{ + "jsonrpc": "2.0", + "id": 0, + "result": { + "difficulty": "0xa", + "extraData": "0x0102030405060708", + "gasLimit": "0x989680", + "gasUsed": "0xa410", + "hash": "0xf3cdafbe35d5e7c18d8274bddad9dd12c94b83a81cefeb82ebb73fa799ff9fcc", + "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "miner": "0x0000000000000000000000000000000000000000", + "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000", + "nonce": "0x0000000000000000", + "number": "0x2af8", + "parentHash": "0xde244f7e8bc54c8809e6c2ce65c439b58e90baf11f6cf9aaf8df33a827bd01ab", + "receiptsRoot": "0xd95b673818fa493deec414e01e610d97ee287c9421c8eff4102b1647c1a184e4", + "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347", + "size": "0x252", + "stateRoot": "0x0f387e78e4a7457a318c7bce7cde0b05c3609347190144a7e105ef05194ae218", + "timestamp": "0x6526db8e", + "totalDifficulty": "0x1adb1", + "transactionsRoot": "0x6a81c9342456693d57963883983bba024916f4d277392c9c1dc497e3518a78e3" + } +} +``` + +Example remote output: + +```bash +{ + "id": 0, + "jsonrpc": "2.0", + "result": { + "difficulty": "0x2", + "extraData": "0xd883050000846765746888676f312e31392e31856c696e7578000000000000009920319c246ec8ae4d4f73f07d79f68b2890e9c2033966efe5a81aedddae12875c3170f0552f48b7e5d8e92ac828a6008b2ba7c5b9c4a0af1692337bbdc792be01", + "gasLimit": "0x989680", + "gasUsed": "0xa410", + "hash": "0xb7848d5b300247d7c33aeba0f1b33375e1cb3113b950dffc140945e9d3d88d58", + "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "miner": "0x0000000000000000000000000000000000000000", + "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000", + "nonce": "0x0000000000000000", + "number": "0x2af8", + "parentHash": "0xa93e6143ab213a044eb834cdd391a6ef2c818de25b04a3839ee44a75bd28a2c7", + "receiptsRoot": "0xd95b673818fa493deec414e01e610d97ee287c9421c8eff4102b1647c1a184e4", + "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347", + "size": "0x2ab", + "stateRoot": "0x0f387e78e4a7457a318c7bce7cde0b05c3609347190144a7e105ef05194ae218", + "timestamp": "0x6526db8e", + "totalDifficulty": "0x55f1", + "transactionsRoot": "0x6a81c9342456693d57963883983bba024916f4d277392c9c1dc497e3518a78e3" + } +} +``` + --- ## Configuration Reference