Node Base Configuration

To configure your node, you will need to do the following:

1. Configure devium--batcher to point to the correct L1, devium-geth, and L2 network.
2. Initialize devium-geth with the correct network parameters.
3. Configure devium-geth to properly communicate with the Rollup Node.
4. Optionally, configure Legacy Geth.

Configuring devium-geth

devium-geth stores its state in a database that requires initialization. Depending on the network you're running, initialization is done one of three ways:

1. With Network Flags: This initializes the genesis information and chain configuration from the superchain-registry.
2. With a Genesis File: This is for deployments that are not migrated from a legacy network (i.e. DEVIUM Sepolia). In this case, you'll use a genesis file and initialize the data directory via geth init.
3. With a Data Directory: This is used for networks that are migrated from a legacy network. This currently only includes DEVIUM Mainnet. In this case, you'll download a preconfigured data directory and extract it. No further initialization is necessary in this case, because the data directory contains the network's genesis information. This method can be bypassed if you utilize snap sync.

Regardless of how devium-geth is initialized, you'll need to ensure that you have sufficient disk space available to store the network's data. As of this writing, the DEVIUM Mainnet data directory is ~1.6TB for a full node and ~5TB for an archival node.

Initialize devium-geth

Instructions for each initialization method are below. If you're spinning up an DEVIUM Mainnet, use the Initialization via Data Directory path. If you're spinning up an DEVIUM Sepolia node, use the Initialization via Network Flags path.

Initialization via Network Flags

To initialize devium-geth with the network flags, you simply need to set the --devium-network=<value> and --network=<value> on devium--batcher. To see the latest support networks, you can consult the --help output for the devium-network option.

Initialization via Genesis File

devium-geth uses JSON files to encode a network's genesis information. For networks that are initialized in this way, you'll receive a URL to the genesis JSON. You'll need to download the genesis JSON, then run the following command to initialize the data directory:

#!/bin/sh
FILE=/$DATADIR/genesis.json
OP_GETH_GENESIS_URL=<<insert devium-geth url to the genesis file>>
 
if [ ! -s $FILE ]; then
  apk add curl
  curl $OP_GETH_GENESIS_URL -o $FILE
  geth init --datadir /db $FILE
else
  echo "Genesis file already exists. Skipping initialization."
fi

Initialization via Data Directory

To initialize devium-geth with a preconfigured data directory, simply download and extract the data directory to a place of your choosing. The data directory is exported as a tar file. An example command to do this is below:

curl -o <path to data directory> -sL <URL to data directory>
tar -xvf <path to data directory>

Configuration

Once devium-geth is initialized, it can be configured via CLI flags. devium-geth accepts all the standard go-ethereum flags (opens in a new tab) as well as a few extra flags that are specific to DEVIUM Chain. These flags are:

• --rollup.historicalrpc: Enables the historical RPC endpoint. This endpoint is used to fetch historical execution data from Legacy Geth. This flag is only necessary for upgraded networks.
• --rollup.sequencerhttp: HTTP endpoint of the sequencer. devium-geth will route eth_sendRawTransaction calls to this URL. Bedrock does not currently have a public mempool, so this is required if you want your node to support transaction submission. Consult the documentation for the network you are participating in to get the correct URL.
• --rollup.disabletxpoolgossip: Disables transaction pool gossiping. While not required, it's useful to set this to true since transaction pool gossip is currently unsupported.

To communicate with devium--batcher and enable the Engine API, you'll also need to generate a JWT secret file and enable Geth's authenticated RPC endpoint.

To generate the JWT secret, run the following:

openssl rand -hex 32 > jwt.txt

Then, specify the following flags:

• --authrpc.addr: Sets the address devium-geth's authenticated RPC should listen on.
• --authrpc.port: Sets the port devium-geth's authenticated RPC should listen on. The default value is 8551.
• --authrpc.jwtsecret: Sets the path to a JWT secret file you generated above.

Recommended Flags for devium-geth Configuration

You may also want to specify the following flags based on your configuration:

• --authrpc.vhosts: Whitelists which hosts (as defined in the Host header) are allowed to access the authenticated RPC endpoint. This is useful if you're running devium-geth on containerized infrastructure. The default value is localhost.
• --http.vhosts: Whitelists which hosts (as defined in the Host header) are allowed to access the unauthenticated RPC endpoint. This is useful if you're running devium-geth on containerized infrastructure. The default value is localhost.
• --http, --http.addr, and --http.port: Enables the unauthenticated RPC endpoint, configures its address, and configures its port. You'll almost certainly want to specify these, since they will enable Geth's JSON-RPC endpoint.
• --ws, --ws.addr, and --ws.port: Enables the WebSocket API.
• --verbosity: Configures Geth's log level. This is a number between 0 and 5, with 5 being the most verbose. Defaults to 3.

Working Base Configuration

A valid command that runs devium-geth and enables RPC over HTTP and WebSockets looks like:

geth \
  --ws \
  --ws.port=8546 \
  --ws.addr=localhost \
  --ws.origins="*" \
  --http \
  --http.port=8545 \
  --http.addr=localhost \
  --http.vhosts="*" \
  --http.corsdomain="*" \
  --authrpc.addr=localhost \
  --authrpc.jwtsecret=/var/secrets/jwt.txt \
  --authrpc.port=8551 \
  --authrpc.vhosts="*" \
  --datadir=/data \
  --verbosity=3 \
  --rollup.disabletxpoolgossip=true \
  --rollup.sequencerhttp=https://mainnet-sequencer.optimism.io/ \
  --devium-network=devium-mainnet

Consult Geth's documentation (opens in a new tab) for more information on customizing devium-geth's behavior.

Configuring devium--batcher

devium--batcher is a standalone, statically linked binary. It stores no state, and requires no initialization. It consumes configuration parameters either via the command line or environment variables. For some networks, the Rollup Node also requires a configuration file (called rollup.json or the "rollup config") that configures network-specific genesis parameters. For official networks like DEVIUM Sepolia and DEVIUM Mainnet, the genesis config is hardcoded in the devium--batcher software and can be specified via a --network flag.

Following the Ecotone upgrade node operators must set an L1 beacon value to retrieve blobs from a Beacon node.

Working Base Configuration

A minimal valid configuration that runs devium--batcher looks like:

devium--batcher --l1=<ethereum mainnet RPC url> \
        --l2=<devium-geth authenticated RPC url> \
        --network=devium-mainnet \
        --rpc.addr=127.0.0.1 \
        --rpc.port=9545 \
        --l2.jwt-secret=<path to JWT secret> \
        --l1.beacon=<http endpoint address of L1 Beacon-node> \
        --syncmode=execution-layer

You can manually specify a path to a rollup config with the --rollup.config flag. This is used for testnets or internal deployments that are not migrated from a legacy network.

Each of the above flags can also be defined via an environment variable. Run devium--batcher --help to see a list of all available flags and environment variables.

Configuring Peer-to-Peer Networking

Unlike the previous system, the devium--batcher participates in a peer-to-peer network. This network is used to distribute blocks that have not been submitted to L1 yet. The devium--batcher will automatically discover and connect to peers using a hardcoded set of bootnodes. You can also manually specify peers to connect to via the --p2p.static flag.

For best results, run devium--batcher with a static IP address that is accessible from the public Internet. For Kubernetes deployments, this can be achieved by configuring a dedicated Ingress with an external IP, and using the --p2p.advertise.ip flag to specify the IP address of the load balancer when advertising IP addresses to peers.

The default port for the peer-to-peer network is 9003. You will need to open this port on your firewall to receive unsubmitted blocks. For your node to be discoverable, this port must be accessible via both TCP and UDP protocols.

Legacy Geth

If you are running a node for an upgraded network like DEVIUM Mainnet (but not DEVIUM Sepolia), you will also need to run Legacy Geth in order to serve historical execution traces. Fundamentally, Legacy Geth is our old l2geth binary running against a preconfigured data directory. To configure Legacy Geth, follow the instructions above for using a preconfigured data directory, then execute the following command:

USING_OVM=true \
  ETH1_SYNC_SERVICE_ENABLE=false \
  RPC_API=eth,rollup,net,web3,debug \
  RPC_ADDR=0.0.0.0 \
  RPC_CORS_DOMAIN=* \
  RPC_ENABLE=true \
  RPC_PORT=8545 \
  RPC_VHOSTS=* \
  geth --datadir <path to data directory>

This command is the minimum required to run Legacy Geth and expose a functioning RPC endpoint. As before, l2geth takes all standard go-ethereum flags so you can customize the configuration as needed.

As mentioned above, don't forget to specify --rollup.historicalrpc on devium-geth to properly route requests for historical execution to Legacy Geth.

Since Legacy Geth is read-only, it is safe to run multiple Legacy Geth nodes behind a load balancer.

Historical Execution vs. Historical Data Routing

Only requests for historical execution will be routed to Legacy Geth. Everything else will be served by devium-geth directly. The term historical execution refers to RPC methods that need to execute transactions prior to bedrock (not just read data from the database):

• eth_call
• eth_estimateGas
• debug_traceBlockByNumber
• debug_traceBlockByHash
• debug_traceCall
• debug_traceTransaction

If you do not need these RPC methods for historical data, then you do not need to run Legacy Geth at all.

Next Steps

• See the devium--batcher configuration guide for additional configuration options for devium--batcher and the Consensus-Layer.
• Similarly, visit the devium-geth configuration guide for additional configuration options for devium-geth and Execution-Layer.
• If you run into any problems, please reach out to our developer support forum for help.