From 0bd8235e1d32e80333fde65e5577a9d7f861b442 Mon Sep 17 00:00:00 2001
From: jonastheis <4181434+jonastheis@users.noreply.github.com>
Date: Fri, 18 Oct 2024 08:30:14 +0800
Subject: [PATCH 1/4] feat: add docs about L1 follower node
---
.../guides/running-a-scroll-node.mdx | 155 ++++++++++++++++++
1 file changed, 155 insertions(+)
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..d85b86f01 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
@@ -139,6 +139,161 @@ 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 with
+- `--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 only one of the blob providers is necessary, but during testing blobscan and blocknative were not fully reliable. That's why using a beacon node with historical blob data is recommended (can be additionally to blobscan and blobnative).
+
+### 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
+```
+
+A full sync will take about 2 weeks depending on the speed of the RPC node, beacon node and the local machine. Progess is reported as follows for every 1000 blocks applied:
+
+```bash
+INFO [08-01|16:44:42.173] L1 sync progress blockhain height=87000 block hash=608eec..880ebd root=218215..9a58a2
+```
+
+### 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-3 days depending on the speed of the RPC node, beacon node and the local machine. Progess is reported as follows for every 1000 blocks applied:
+
+```bash
+INFO [08-01|16:44:42.173] L1 sync progress blockhain height=87000 block hash=608eec..880ebd root=218215..9a58a2
+```
+
+
+### Troubleshooting
+You should see something like this shortly after starting:
+- the node (APIs, geth console, etc) will not be responsive until all the L1 messages have been synced
+- but it is already starting the derivation pipeline which can be seen through `L1 sync progress [...]`.
+- for Sepolia it might take a little longer (10-20mins) for the first `L1 sync progress [...]` to appear as the L1 blocks are more sparse at the beginning
+```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 "blockhain 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're not synced fast enough such an error might pop up. It 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
+
+The `state root` of a block can be reproduced when using this mode of syncing but currently not the `block hash`. 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 where the main implementation on l2geth is already done: https://github.com/scroll-tech/go-ethereum/pull/903 https://github.com/scroll-tech/go-ethereum/pull/913.
+
+To verify the locally created `state root` against mainnet (`https://sepolia-rpc.scroll.io/` for Sepolia), 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 matches**. 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
From cc2951f7527bb4738f2fb4dd321a7ac037f163b5 Mon Sep 17 00:00:00 2001
From: Jonas Theis <4181434+jonastheis@users.noreply.github.com>
Date: Mon, 28 Oct 2024 16:33:23 +0800
Subject: [PATCH 2/4] Update
src/content/docs/en/developers/guides/running-a-scroll-node.mdx
Co-authored-by: isabellewei
---
src/content/docs/en/developers/guides/running-a-scroll-node.mdx | 2 +-
1 file changed, 1 insertion(+), 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 d85b86f01..6f1530e73 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
@@ -154,7 +154,7 @@ Run `l2geth` with the `--da.sync` flag. Provide blob APIs and beacon node with
Strictly speaking only one of the blob providers is necessary, but during testing blobscan and blocknative were not fully reliable. That's why using a beacon node with historical blob data is recommended (can be additionally to blobscan and blobnative).
-### mainnet
+### Mainnet
```bash
./build/bin/geth --scroll \
--datadir "tmp/mainnet-l2geth-datadir" \
From b55d7fd6fb30f4363c6a3770f4b795aafdee33a3 Mon Sep 17 00:00:00 2001
From: Jonas Theis <4181434+jonastheis@users.noreply.github.com>
Date: Mon, 28 Oct 2024 16:33:57 +0800
Subject: [PATCH 3/4] Apply suggestions from code review
Co-authored-by: isabellewei
---
.../docs/en/developers/guides/running-a-scroll-node.mdx | 9 +++++----
1 file changed, 5 insertions(+), 4 deletions(-)
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 6f1530e73..b117b9f64 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
@@ -149,10 +149,10 @@ This mode is useful for reconstructing the L2 state by only following the L1.
Run `l2geth` with the `--da.sync` flag. Provide blob APIs and beacon node with
- `--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.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 only one of the blob providers is necessary, but during testing blobscan and blocknative were not fully reliable. That's why using a beacon node with historical blob data is recommended (can be additionally to blobscan and blobnative).
+Strictly speaking only one of the blob providers is necessary, but during testing blobscan and blocknative were not fully reliable. That's why using a beacon node with historical blob data is recommended (can be in addition to blobscan and blobnative).
### Mainnet
```bash
@@ -209,7 +209,8 @@ INFO [09-18|13:42:24.324] L1 sync progress "blockhain he
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**
+#### 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're not synced fast enough such an error might pop up. It 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: "
@@ -217,7 +218,7 @@ WARN [09-18|13:52:25.843] syncing pipeline step failed due to temporary error, r
## Limitations
-The `state root` of a block can be reproduced when using this mode of syncing but currently not the `block hash`. 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 where the main implementation on l2geth is already done: https://github.com/scroll-tech/go-ethereum/pull/903 https://github.com/scroll-tech/go-ethereum/pull/913.
+The `state root` of a block can be reproduced when using this mode of syncing but currently not the `block hash`. 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](https://github.com/scroll-tech/go-ethereum/pull/903 https://github.com/scroll-tech/go-ethereum/pull/913) where the main implementation on l2geth is already done.
To verify the locally created `state root` against mainnet (`https://sepolia-rpc.scroll.io/` for Sepolia), we can do the following:
From 99fa1122f0a6cad3303d2d6d266b8b20f9dfd4cc Mon Sep 17 00:00:00 2001
From: jonastheis <4181434+jonastheis@users.noreply.github.com>
Date: Mon, 28 Oct 2024 16:38:47 +0800
Subject: [PATCH 4/4] address review comments
---
.../en/developers/guides/running-a-scroll-node.mdx | 10 +++-------
1 file changed, 3 insertions(+), 7 deletions(-)
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 b117b9f64..ffdbb1b06 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
@@ -167,11 +167,6 @@ Strictly speaking only one of the blob providers is necessary, but during testin
--verbosity 3
```
-A full sync will take about 2 weeks depending on the speed of the RPC node, beacon node and the local machine. Progess is reported as follows for every 1000 blocks applied:
-
-```bash
-INFO [08-01|16:44:42.173] L1 sync progress blockhain height=87000 block hash=608eec..880ebd root=218215..9a58a2
-```
### Sepolia
```bash
@@ -186,7 +181,7 @@ INFO [08-01|16:44:42.173] L1 sync progress blockhain hei
--verbosity 3
```
-A full sync will take about 2-3 days depending on the speed of the RPC node, beacon node and the local machine. Progess is reported as follows for every 1000 blocks applied:
+A full sync will take about 2 weeks for Mainnet and 2-3 days for Sepolia depending on the speed of the RPC node, beacon node and the local machine. Progess is reported as follows for every 1000 blocks applied:
```bash
INFO [08-01|16:44:42.173] L1 sync progress blockhain height=87000 block hash=608eec..880ebd root=218215..9a58a2
@@ -194,10 +189,11 @@ INFO [08-01|16:44:42.173] L1 sync progress blockhain hei
### Troubleshooting
-You should see something like this shortly after starting:
- the node (APIs, geth console, etc) will not be responsive until all the L1 messages have been synced
- but it is already starting the derivation pipeline which can be seen through `L1 sync progress [...]`.
- for Sepolia it might take a little longer (10-20mins) for the first `L1 sync progress [...]` 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...