Merge pull request #5219 from ethereum-optimism/qbzzt/230321-stop-start

feat(docs/op-stack): Errors related to starting and stopping the blockchain

docs/op-stack/src/docs/build/getting-started.md

@@ -390,9 +390,7 @@ Head over to the `op-node` package and start the `op-node` using the following c
 	--rollup.config=./rollup.json \
 	--rpc.addr=0.0.0.0 \
 	--rpc.port=8547 \
-	--p2p.listen.ip=0.0.0.0 \
-	--p2p.listen.tcp=9003 \
-	--p2p.listen.udp=9003 \
+	--p2p.disable \
 	--rpc.enable-admin \
 	--p2p.sequencer.key=<SEQUENCERKEY> \
 	--l1=<RPC> \
@@ -402,6 +400,26 @@ Head over to the `op-node` package and start the `op-node` using the following c
 Once you run this command, you should start seeing the `op-node` begin to process all of the L1 information after the starting block number that you picked earlier. Once the `op-node` has enough information, it’ll begin sending Engine API payloads to `op-geth`. At that point, you’ll start to see blocks being created inside of `op-geth`. We’re live!
 
 
+::: tip Peer to peer synchronization
+
+If you use a chain ID that is also used by others, for example the default (42069), your `op-node` will try to use peer to peer to speed up synchronization.
+These attempts will fail, because they will be signed with the wrong key, but they will waste time and network resources.
+
+To avoid this , we start with peer to peer synchronization disabled (`--p2p.disable`).
+Once you have multiple nodes, it makes sense to use these command line parameters to synchronize between them without getting confused by other blockchains.
+
+```
+	--p2p.static=<nodes> \
+	--p2p.listen.ip=0.0.0.0 \
+	--p2p.listen.tcp=9003 \
+	--p2p.listen.udp=9003 \
+```
+
+:::
+
+
+
+
 ## Run op-batcher
 
 The final component necessary to put all the pieces together is the `op-batcher`. The `op-batcher` takes transactions from the Sequencer and publishes those transactions to L1. Once transactions are on L1, they’re officially part of the Rollup. Without the `op-batcher`, transactions sent to the Sequencer would never make it to L1 and wouldn’t become part of the canonical chain. The `op-batcher` is critical!
@@ -516,15 +534,47 @@ To use any other development stack, see the getting started tutorial, just repla
 
 ### Stopping your Rollup
 
-To stop `op-geth` you should use Ctrl-C. 
+An orderly shutdown is done in the reverse order to the order in which components were started:
+
+1. Stop `op-batcher`.
+1. Stop `op-node`.
+1. Stop `op-geth`.
+
+
+### Starting your Rollup
+
+To restart the blockchain, use the same order of components you did when you initialized it.
+
+1. `op-geth`
+1. `op-node`
+1. `op-batcher`
+
+::: tip Synchronization takes time
+
+`op-batcher` might have warning messages similar to:
+
+```
+WARN [03-21|14:13:55.248] Error calculating L2 block range         err="failed to get sync status: Post \"http://localhost:8547\": context deadline exceeded"
+WARN [03-21|14:13:57.328] Error calculating L2 block range         err="failed to get sync status: Post \"http://localhost:8547\": context deadline exceeded"
+```
+
+This means that `op-node` is not yet synchronized up to the present time.
+Just wait until it is.
+
+:::
 
-If `op-geth` aborts (for example, because the computer it is running on crashes), you will get these errors on `op-node`: 
+
+### Errors
+
+#### Corrupt data directory
+
+If `op-geth` aborts (for example, because the computer it is running on crashes), you might get these errors on `op-node`: 
 
 ```
 WARN [02-16|21:22:02.868] Derivation process temporary error       attempts=14 err="stage 0 failed resetting: temp: failed to find the L2 Heads to start from: failed to fetch L2 block by hash 0x0000000000000000000000000000000000000000000000000000000000000000: failed to determine block-hash of hash 0x0000000000000000000000000000000000000000000000000000000000000000, could not get payload: not found"
 ```
 
-In that case, you need to remove `datadir`, reinitialize it:
+This means that the data directory is corrupt and you need to reinitialize it:
 
 ```bash
 cd ~/op-geth
@@ -536,17 +586,23 @@ echo "<SEQUENCER KEY HERE>" > datadir/block-signer-key
 ./build/bin/geth init --datadir=./datadir ./genesis.json
 ```
 
-### Starting your Rollup
 
-To restart the blockchain, use the same order of components you did when you initialized it.
+#### Batcher out of ETH
 
-1. `op-geth`
-2. `op-node`
-3. `op-batcher`
+If `op-batcher` runs out of ETH, it cannot submit write new transaction batches to L1.
+You will get error messages similar to this one:
+
+```
+INFO [03-21|14:22:32.754] publishing transaction                   service=batcher txHash=2ace6d..7eb248 nonce=2516 gasTipCap=2,340,741 gasFeeCap=172,028,434,515
+ERROR[03-21|14:22:32.844] unable to publish transaction            service=batcher txHash=2ace6d..7eb248 nonce=2516 gasTipCap=2,340,741 gasFeeCap=172,028,434,515 err="insufficient funds for gas * price + value"
+```
+
+Just send more ETH and to the batcher, and the problem will be resolved.
 
 ## Adding nodes
 
-To add nodes to the rollup, you need to initialize `op-node` and `op-geth`, similar to what you did for the first node:
+To add nodes to the rollup, you need to initialize `op-node` and `op-geth`, similar to what you did for the first node.
+You should *not* add an `op-bathcer`, there should be only one.
 
 1. Configure the OS and prerequisites as you did for the first node.
 1. Build the Optimism monorepo and `op-geth` as you did for the first node.
@@ -574,7 +630,7 @@ To add nodes to the rollup, you need to initialize `op-node` and `op-geth`, simi
     
 1. Start `op-geth` (using the same command line you used on the initial node)
 1. Start `op-node` (using the same command line you used on the initial node)
-1. Wait while the node synchronizes
+
 
 ## What’s next?