OP Stack genesis creation

The following guide shows you how to generate the L2 genesis file genesis.json. This is a JSON file that represents the L2 genesis. You will provide this file to the execution client (op-geth) to initialize your network. There is also the rollup configuration file, rollup.json, which will be provided to the consensus client (op-node).

Solidity script

At the time of this writing, the preferred method for genesis generation is to use the foundry script located in the monorepo to generate an "L2 state dump" and then pass this into the op-node genesis subcommand. The foundry script can be found at packages/contracts-bedrock/scripts/L2Genesis.s.sol (opens in a new tab).

Configuration

Create or modify a file <network-name>.json inside the deploy-config folder in the monorepo. The script will read the latest active fork from the deploy config and the L2 genesis allocs generated will be compatible with this fork. The automatically detected fork can be overwritten by setting the environment variable FORK either to the lower-case fork name (currently delta, ecotone, or fjord) or to latest, which will select the latest fork available (currently fjord).

By default, the script will dump the L2 genesis allocs (aka "state dump") of the detected or selected fork only, to the file at STATE_DUMP_PATH. The optional environment variable OUTPUT_MODE allows you to modify this behavior by setting it to one of the following values:

• latest (default) - only dump the selected fork's allocs.
• all - also dump all intermediary fork's allocs. This only works if STATE_DUMP_PATH is not set. In this case, all allocs will be written to files /state-dump-<fork>.json. Another path cannot currently be specified for this use case.
• none - won't dump any allocs. Only makes sense for internal test usage.

Creation

• CONTRACT_ADDRESSES_PATH represents the deployment artifact that was generated during a contract deployment.
• DEPLOY_CONFIG_PATH represents a path on the filesystem that points to a deployment config. The same deploy config JSON file should be used for L1 contracts deployment as when generating the L2 genesis allocs.
• STATE_DUMP_PATH represents the filepath at which the allocs will be written to on disk.

CONTRACT_ADDRESSES_PATH=<CONTRACT_ADDRESSES_PATH> \
DEPLOY_CONFIG_PATH=<PATH_TO_MY_DEPLOY_CONFIG> \
STATE_DUMP_PATH=<PATH_TO_WRITE_L2_ALLOCS> \
  forge script scripts/L2Genesis.s.sol:L2Genesis \
  --sig 'runWithStateDump()'

Subcommand (op-node genesis l2)

The genesis file creation is handled by the genesis l2 subcommand, provided by the op-node. The following is an example of its usage from v1.7.6 (opens in a new tab) -- note that you need to pass the path to the l2 genesis state dump file output by the foundry script above:

go run cmd/main.go genesis l2 \
  --deploy-config=<Path to deploy config file> \
  --l1-deployments=<Path to L1 deployments JSON file as in superchain-registry> \
  --l2-allocs=<Path to L2 genesis state dump> \
  --outfile.l2=<Path to L2 genesis output file: i.e. ./genesis.json> \
  --outfile.rollup=<Path to rollup output file: i.e. ./rollup.json> \
  --l1-rpc=<RPC URL for an Ethereum L1 node. Cannot be used with --l1-starting-block>>

Next steps

• Learn how to initialize op-geth with your genesis.json file.
• Learn how to initialize (opens in a new tab) op-node with your rollup.json file.
• Learn more about the off chain architecture.