Merge pull request #5259 from ethereum-optimism/qbzzt/230324-integrate-runbook

feat(docs/op-stack): Add an operations page

docs/op-stack/src/.vuepress/config.js

@@ -149,6 +149,7 @@ module.exports = {
         children: [
           '/docs/build/getting-started.md',
           '/docs/build/conf.md',
+          '/docs/build/operations.md',
           '/docs/build/explorer.md',
           '/docs/build/sdk.md',
           {

docs/op-stack/src/docs/build/conf.md

@@ -50,7 +50,7 @@ These fields apply to L2 blocks: Their timing, when do they need to be written t
 
 | Key | Type | Description | Default value |
 | --- | --- | --- | --- |
-| `l2BlockTime` | Number of seconds | Number of seconds between each L2 block. | 2 |
+| `l2BlockTime` | Number of seconds | Number of seconds between each L2 block. Must be <= L1 block time (12 on mainnet and Goerli) | 2 |
 | `maxSequencerDrift` | Number of seconds | How far the L2 timestamp can differ from the actual L1 timestamp | 600 (10 minutes) |
 | `sequencerWindowSize` | Number of blocks | Maximum number of L1 blocks that a Sequencer can wait to incorporate the information in a specific L1 block. For example, if the window is `10` then the information in L1 block `n` must be incorporated by L1 block `n+10`. | 3600 (12 hours) |
 | `channelTimeout` | Number of blocks | Maximum number of L1 blocks that a transaction channel frame can be considered valid. A transaction channel frame is a chunk of a compressed batch of transactions. After the timeout, the frame is dropped. | 300 (1 hour) |

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

@@ -39,7 +39,7 @@ This tutorial was checked on:
 | Software | Version    | Installation command(s) |
 | -------- | ---------- | - |
 | Ubuntu   | 20.04 LTS  | |
-| git, curl, and make | OS default | `sudo apt install -y git curl make` |
+| git, curl, jq, and make | OS default | `sudo apt install -y git curl make jq` |
 | Go       | 1.20       | `sudo apt update` <br> `wget https://go.dev/dl/go1.20.linux-amd64.tar.gz` <br> `tar xvzf go1.20.linux-amd64.tar.gz` <br> `sudo cp go/bin/go /usr/bin/go` <br> `sudo mv go /usr/lib` <br> `echo export GOROOT=/usr/lib/go >> ~/.bashrc`
 | Node     | 16.19.0    | `curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -` <br> `sudo apt-get install -y nodejs npm`
 | yarn     | 1.22.19    | `sudo npm install -g yarn`
@@ -430,7 +430,9 @@ The final component necessary to put all the pieces together is the `op-batcher`
     cd ~/optimism/op-batcher
     ```
 
-1. And run the `op-batcher` using the following command. Replace `<RPC>` with your L1 node URL and replace `<BATCHERKEY>` with the private key for the `Batcher` account that you created and funded earlier. It’s best to give the `Batcher` at least 1 Goerli ETH to ensure that it can continue operating without running out of ETH for gas.
+1. And run the `op-batcher` using the following command. 
+   Replace `<RPC>` with your L1 node URL and replace `<BATCHERKEY>` with the private key for the `Batcher` account that you created and funded earlier. 
+   It’s best to give the `Batcher` at least 1 Goerli ETH to ensure that it can continue operating without running out of ETH for gas.
 
     ```bash
     ./bin/op-batcher \
@@ -443,11 +445,22 @@ The final component necessary to put all the pieces together is the `op-batcher`
         --resubmission-timeout=30s \
         --rpc.addr=0.0.0.0 \
         --rpc.port=8548 \
+        --rpc.enable-admin \
+        --max-channel-duration=1 \
         --target-l1-tx-size-bytes=2048 \
         --l1-eth-rpc=<RPC> \
         --private-key=<BATCHERKEY>
     ```
 
+   ::: tip Controlling batcher costs
+
+   The `--max-channel-duration=n` setting tells the batcher to write all the data to L1 every `n` L1 blocks. 
+   When it is low, transactions are written to L1 frequently, withdrawals are quick, and other nodes can synchronize from L1 fast.
+   When it is high, transactions are written to L1 less frequently, and the batcher spends less ETH.
+
+   :::
+
+
 ## Get some ETH on your Rollup
 
 Once you’ve connected your wallet, you’ll probably notice that you don’t have any ETH on your Rollup. You’ll need some ETH to pay for gas on your Rollup. The easiest way to deposit Goerli ETH into your chain is to send funds directly to the `OptimismPortalProxy` contract. You can find the address of the `OptimismPortalProxy` contract for your chain by looking inside the `deployments` folder in the `contracts-bedrock` package.
@@ -461,21 +474,13 @@ Once you’ve connected your wallet, you’ll probably notice that you don’t h
 1. Grab the address of the proxy to the L1 standard bridge contract:
 
     ```bash
-    cat deployments/getting-started/Proxy__OVM_L1StandardBridge.json.json | grep \"address\":
+    cat deployments/getting-started/Proxy__OVM_L1StandardBridge.json | grep \"address\":
     ```
 
-    You should see a result like the following (**your address will be different**):
+    You should see a result similar to the following (**your address will be different**):
 
     ```
     "address": "0x874f2E16D803c044F10314A978322da3c9b075c7",
-            "internalType": "address",
-            "type": "address"
-            "internalType": "address",
-            "type": "address"
-            "internalType": "address",
-            "type": "address"
-            "internalType": "address",
-            "type": "address"
     ```
 
 1. Grab the L1 bridge proxy contract address and, using the wallet that you want to have ETH on your Rollup, send that address a small amount of ETH on Goerli (0.1 or less is fine). It may take up to 5 minutes for that ETH to appear in your wallet on L2.
@@ -530,39 +535,6 @@ To see your rollup in action, you can use the [Optimism Mainnet Getting Started
 
 To use any other development stack, see the getting started tutorial, just replace the Greeter address with the address of your rollup, and the Optimism Goerli URL with `http://localhost:8545`.
 
-## Rollup operations
-
-### Stopping your Rollup
-
-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.
-
-:::
-
 
 ### Errors
 
@@ -599,37 +571,6 @@ ERROR[03-21|14:22:32.844] unable to publish transaction            service=batch
 
 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.
-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.
-1. Copy from the first node these files:
-    
-    ```bash
-    ~/op-geth/genesis.json
-    ~/optimism/op-node/rollup.json
-    ```
-    
-1. Create a new `jwt.txt` file as a shared secret:
-    
-    ```bash
-    cd ~/op-geth
-    openssl rand -hex 32 > jwt.txt
-    cp jwt.txt ~/optimism/op-node
-    ```
-    
-1. Initialize the new op-geth:
-    
-    ```bash
-    cd ~/op-geth
-    ./build/bin/geth init --datadir=./datadir ./genesis.json
-    ```
-    
-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)
 
 
 ## What’s next?

docs/op-stack/src/docs/build/operations.md

+---
+title: Rollup Operations
+lang: en-US
+---
+
+## Stopping your Rollup
+
+An orderly shutdown is done in the reverse order to the order in which components were started:
+
+1. To stop the batcher, use this command:
+
+   ```sh
+   curl -d '{"id":0,"jsonrpc":"2.0","method":"admin_stopBatcher","params":[]}' \
+       -H "Content-Type: application/json" http://localhost:8548 | jq
+   ```
+
+   This way the batcher knows to save any data it has cached to L1.
+   Wait until you see `Batch Submitter stopped` in batcher's output before you stop the process.
+
+1. Stop `op-node`.
+   This component is stateless, so you can just stop the process.
+
+1. Stop `op-geth`.
+   Make sure you use **CTRL-C** to avoid database corruption.
+
+
+## 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`
+
+   If `op-batcher` is still running and you just stopped it using RPC, you can start it with this command:
+
+   ```sh
+   curl -d '{"id":0,"jsonrpc":"2.0","method":"admin_startBatcher","params":[]}' \
+       -H "Content-Type: application/json" http://localhost:8548 | jq   
+   ```
+
+::: 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.
+
+:::
+
+
+## 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.
+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.
+1. Copy from the first node these files:
+    
+    ```bash
+    ~/op-geth/genesis.json
+    ~/optimism/op-node/rollup.json
+    ```
+    
+1. Create a new `jwt.txt` file as a shared secret:
+    
+    ```bash
+    cd ~/op-geth
+    openssl rand -hex 32 > jwt.txt
+    cp jwt.txt ~/optimism/op-node
+    ```
+    
+1. Initialize the new op-geth:
+    
+    ```bash
+    cd ~/op-geth
+    ./build/bin/geth init --datadir=./datadir ./genesis.json
+    ```
+
+1. To enable L2 nodes to synchronize directly, rather than wait until the transactions are written to L1, turn on [peer to peer synchronization](http://localhost:8081/docs/build/getting-started/#run-op-node).
+   If you already have peer to peer synchronization, add the new node to the `--p2p.static` list so it can synchronize.
+
+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)