From 11d1049acfe3c1630dc58755e7bbbef554b60613 Mon Sep 17 00:00:00 2001 From: Prathamesh Musale Date: Tue, 30 Apr 2024 19:17:39 +0530 Subject: [PATCH] Add instructions to run stack with an external L1 chain --- stack/fixturenet-optimism/README.md | 6 +- stack/fixturenet-optimism/l2-only.md | 130 +++++++++++++++++++++++++++ 2 files changed, 134 insertions(+), 2 deletions(-) create mode 100644 stack/fixturenet-optimism/l2-only.md diff --git a/stack/fixturenet-optimism/README.md b/stack/fixturenet-optimism/README.md index a43cf50..144ecf1 100644 --- a/stack/fixturenet-optimism/README.md +++ b/stack/fixturenet-optimism/README.md @@ -2,6 +2,8 @@ Instructions to setup and deploy an end-to-end L1+L2 stack with [fixturenet-plugeth](https://git.vdb.to/cerc-io/stack-orchestrator/src/branch/main/stack_orchestrator/data/stacks/fixturenet-plugeth) (L1) and [Optimism](https://stack.optimism.io) (L2) +We support running just the L2 part of stack, given an external L1 endpoint. Follow the [L2 only doc](./l2-only.md) for the same. + ## Setup Clone the stack repo: @@ -119,8 +121,8 @@ laconic-so deployment --dir fixturenet-plugeth-deployment start laconic-so deployment --dir fixturenet-optimism-deployment start ``` -1. The `fixturenet-eth` L1 chain will start up first and begin producing blocks. -2. The `fixturenet-optimism-contracts` service will configure and deploy the Optimism contracts to L1, exiting when complete. This may take several minutes; you can follow the progress by following the container's logs (see below). +1. The `fixturenet-eth` L1 chain will start up first and begin producing blocks +2. The `fixturenet-optimism-contracts` service will configure and deploy the Optimism contracts to L1, exiting when complete. This may take several minutes; you can follow the progress by following the container's logs (see below) 3. The `op-node` and `op-geth` services will initialize themselves (if not already initialized) and start 4. The remaining services, `op-batcher` and `op-proposer` will start diff --git a/stack/fixturenet-optimism/l2-only.md b/stack/fixturenet-optimism/l2-only.md new file mode 100644 index 0000000..a4ae95a --- /dev/null +++ b/stack/fixturenet-optimism/l2-only.md @@ -0,0 +1,130 @@ +# fixturenet-optimism (L2-only) + +Instructions to setup and deploy L2 fixturenet using [Optimism](https://stack.optimism.io) + +Prerequisite: An L1 Ethereum RPC endpoint (with unprotected txs enabled) + +## Setup + +Clone the stack repo: + +```bash +laconic-so fetch-stack git.vdb.to/cerc-io/fixturenet-optimism-stack +``` + +Clone required repositories: + +```bash +laconic-so --stack ~/cerc/fixturenet-optimism-stack/stack/fixturenet-optimism setup-repositories + +# If this throws an error as a result of being already checked out to a branch/tag in a repo, remove concerned repositories and re-run the command +``` + +Build the container images: + +```bash +laconic-so --stack ~/cerc/fixturenet-optimism-stack/stack/fixturenet-optimism build-containers +``` + +This should create the required docker images in the local image registry: +* `cerc/optimism-contracts` +* `cerc/optimism-l2geth` +* `cerc/optimism-op-node` +* `cerc/optimism-op-batcher` +* `cerc/optimism-op-proposer` + +## Create a deployment + +First, create a spec file for the deployment, which will map the stack's ports and volumes to the host: + +```bash +laconic-so --stack ~/cerc/fixturenet-optimism-stack/stack/fixturenet-optimism deploy init --map-ports-to-host any-fixed-random --output fixturenet-optimism-spec.yml +``` + +### Ports and Data volumes + +The default port and volume mappings to host can be customized by editing the "spec" file generated by `laconic-so deploy init` + +--- + +Once you've made any needed changes to the spec file, create a deployment from it: + +```bash +laconic-so --stack ~/cerc/fixturenet-optimism-stack/stack/fixturenet-optimism deploy create --spec-file fixturenet-optimism-spec.yml --deployment-dir fixturenet-optimism-deployment +``` + +## Set chain env variables + +Inside the deployment directory, open the file `config.env` and add the following variables to point the stack at your L1 rpc and provide account credentials ([defaults](../../config/fixturenet-optimism/l1-params.env)): + + ```bash + # External L1 endpoint + CERC_L1_CHAIN_ID= + CERC_L1_RPC= + CERC_L1_HOST= + CERC_L1_PORT= + + # URL to get CSV with credentials for accounts on L1 + # that are used to send balance to Optimism Proxy contract + # (enables them to do transactions on L2) + CERC_L1_ACCOUNTS_CSV_URL= + + # OR + # Specify the required account credentials for the Admin account + # Other generated accounts will be funded from this account, so it should contain ~20 Eth + CERC_L1_ADDRESS= + CERC_L1_PRIV_KEY= + ``` + +* NOTE: If L1 is running on the host machine, use `host.docker.internal` as the hostname to access the host port, or use the `ip a` command to find the IP address of the `docker0` interface (this will usually be something like `172.17.0.1` or `172.18.0.1`) + +## Start the stack + +Start the deployment: + +```bash +laconic-so deployment --dir fixturenet-optimism-deployment start +``` + +1. The stack will check for a response from the L1 endpoint specified in your env file +2. The `fixturenet-optimism-contracts` service will configure and deploy the Optimism contracts to L1, exiting when complete. This may take several minutes; you can follow the progress by following the container's logs (see below) +3. The `op-node` and `op-geth` services will initialize themselves (if not already initialized) and start +4. The remaining services, `op-batcher` and `op-proposer` will start + +### Logs + +To list and monitor the running containers: + +```bash +laconic-so --stack fixturenet-optimism deploy ps + +# With status +docker ps + +# Check logs for a container +docker logs -f +``` + +## Example + +Try out the [example](./README.md#example-bridge-some-eth-from-l1-to-l2) to bridge ETH from L1 to L2 + +Note: Use external L1 endpoint as `L1_RPC` and add flag `--add-host="host.docker.internal:host-gateway"` to `docker run` commands if necessary + +## Clean up + +To stop all L2 services running in the background, while preserving chain data: + +```bash +laconic-so deployment --dir fixturenet-optimism-deployment stop +``` + +To stop all L2 services and also delete chain data: + +```bash +laconic-so deployment --dir fixturenet-optimism-deployment stop --delete-volumes +``` + +## Troubleshooting + +See [Troubleshooting](./README.md#troubleshooting)