|
| 1 | +# Scroll Sequencer Migration |
| 2 | +This module contains documentation and scripts for Scroll's sequencer migration from `l2geth` to rollup node (RN) aka `l2reth`. |
| 3 | + |
| 4 | +### Risks |
| 5 | +We want to minimize risks and minimize service disruption. For this we need to consider following risks: |
| 6 | +- invalid L2 blocks produced |
| 7 | +- L2 reorg (e.g. different blocks issued at same L2 block height) |
| 8 | +- L1 messages skipped/reverted |
| 9 | +- general service interruption |
| 10 | + |
| 11 | +## Migration Procedure |
| 12 | + |
| 13 | +To instill confidence we will do many repeated transitions from `l2geth` -> `l2reth` -> `l2geth` with the time that `l2reth` sequences increasing. |
| 14 | + |
| 15 | +The high-level flow of the transition will look like this: |
| 16 | +1. `l2geth` is sequencing currently |
| 17 | +2. Turn off `l2geth` sequencing |
| 18 | +3. Get block height of `l2geth` |
| 19 | +4. Wait until `l2reth` has same block height |
| 20 | +5. Turn on `l2reth` sequencing |
| 21 | +6. Wait until `l2reth` has sequenced until block X or for some time |
| 22 | +7. Turn off `l2reth` sequencing |
| 23 | +8. Wait until `l2geth` has same block height |
| 24 | +9. Turn on `l2geth` sequencing |
| 25 | + |
| 26 | +## Usage |
| 27 | +Make sure the `L2RETH_RPC_URL` and `L2GETH_RPC_URL` env variables are properly configured. Simply run the script and follow the instructions. |
| 28 | + |
| 29 | +```bash |
| 30 | +./migrate-sequencer.sh <blocks_to_produce> |
| 31 | +./revert-l2geth-to-block.sh <block_number> |
| 32 | +./switch-to-l2geth.sh |
| 33 | + |
| 34 | +# make common functions available on bash |
| 35 | +source common-functions.sh |
| 36 | + |
| 37 | +start_l2geth_mining |
| 38 | +get_block_info $L2GETH_RPC_URL |
| 39 | +[...] |
| 40 | +``` |
| 41 | + |
| 42 | +### Testing locally |
| 43 | +To test locally run the test `docker_test_migrate_sequencer` and execute the `migrate-sequencer.sh` script. |
| 44 | +```bash |
| 45 | +# this test runs for ~60 seconds and starts with l2geth sequencing and expects all nodes to reach the same block at block number 120. |
| 46 | +RUST_LOG=info,docker-compose=off cargo test --package tests --test migrate_sequencer -- docker_test_migrate_sequencer --exact --show-output |
| 47 | + |
| 48 | +source local.env |
| 49 | +./migrate-sequencer.sh <blocks_to_produce> |
| 50 | + |
| 51 | +# if necessary, reset l2geth block height and start sequencing on l2geth. |
| 52 | +./revert-l2geth-to-block.sh <block_number> |
| 53 | +``` |
| 54 | + |
| 55 | +**Simulating failure case**: |
| 56 | +- To simulate the case where `l2reth` produces invalid blocks we can adjust to `--builder.gaslimit=40000000` in `launch_rollup_node_sequencer.bash`. This will produce a block with a too big jump of the gas limit and `l2geth` will reject it. In a simulation we can then "revert" `l2geth` to its latest block and start sequencing on `l2geth` again. |
| 57 | +- Continuing on the above case we can fabricate a L2 reorg by simply resetting to any previous block. For all `l2geth` nodes the reorg will be shallow (ie before the invalid `l2reth` blocks) and for `l2reth` it will be deeper (ie all `l2reth` produced blocks + reset to previous block). |
| 58 | + |
| 59 | +### Running with Docker |
| 60 | +```bash |
| 61 | +docker run -it --rm sequencer-migration:latest |
| 62 | + |
| 63 | +# then just use the scripts as before |
| 64 | +./migrate-sequencer.sh <blocks_to_produce> |
| 65 | + |
| 66 | +# or call any of the common functions |
| 67 | +start_l2geth_mining |
| 68 | +get_block_info $L2GETH_RPC_URL |
| 69 | +[...] |
| 70 | +``` |
| 71 | + |
| 72 | +If running on Linux you might need to specify `-e L2GETH_RPC_URL=http://your-l2geth:8547 -e L2RETH_RPC_URL=http://your-l2reth:8545` as the default URLs might not work. |
0 commit comments