Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Running a Mainnet Node

This page provides the specific configuration used to run different types of nodes in Mainnet.

🫵 TL;DR: For operator running Mainnet 0 nodes, the critical changes from that configuration are as follows:

  • The new container image version is https://github.com/EspressoSystems/espresso-network/releases/tag/20260512

  • Use v1 APIs for all peer URLs

  • The stateAPI module is now required. It will be enabled automatically and should no longer be specified on the command line.

  • Both ESPRESSO_SEQUENCER_L1_PROVIDER and ESPRESSO_SEQUENCER_L1_WS_PROVIDER now need to be provided. See the variables listed below for details

The container image to use for this deployment is

The configuration for all node types includes ESPRESSO_SEQUENCER_GENESIS_FILE=/genesis/mainnet.toml. This file is built into the official Docker images. Operators building their own images will need to ensure this file is included and their nodes are pointed at it.

Staking

Regardless of the type of node being operated, if you are starting a node for the first time, it will need to be registered in the stake table and have some stake delegated to it in order to participate in consensus.

With the initial release of Mainnet, participation is limited to a dynamic, permissionless set of 100 nodes. In each epoch (period of roughly 24 hours) the 100 nodes with the most delegated stake form the active participation set.

Registering a Node

In order for a node to participate, it must be registered in the stake table contract on Ethereum. During this process, the node's consensus keys are associated with a unique Ethereum address. This Ethereum address will receive commission, but does not exist on the node itself.

Interfacing with the stake table can be done using the staking-cli. Here is the command to use to register a node in the stake table:

docker run -e L1_PROVIDER -e STAKE_TABLE_ADDRESS -e MNEMONIC -e ACCOUNT_INDEX \
	-e CONSENSUS_PRIVATE_KEY -e STATE_PRIVATE_KEY \
	ghcr.io/espressosystems/espresso-network/staking-cli:main \
	staking-cli register-validator \
	--commission $COMMISSION \
    --metadata-uri $METADATA_URI

Where:

Environment Variable
Meaning

L1_PROVIDER

The RPC provider URL to use when interacting with the L1

STAKE_TABLE_ADDRESS

The Mainnet stake table address. This is 0xCeF474D372B5b09dEfe2aF187bf17338Dc704451

MNEMONIC

The Ethereum mnemonic to use in combination with ACCOUNT_INDEX to derive an Ethereum keypair unique to this node

ACCOUNT_INDEX

The Ethereum account index to use in combination with MNEMONIC to derive an Ethereum keypair unique to this node

CONSENSUS_PRIVATE_KEY

The node's staking-specific consensus key. This key looks something like: BLS_SIGNING_KEY~...

STATE_PRIVATE_KEY

The node's state-specific consensus key. This key looks something like: SCHNORR_SIGNING_KEY~...

COMMISSION

The proportion of rewards that the validator will earn, in percentage points with up to 2 decimals places (e.g. for a commission rate of 12.34%, set COMMISSION=12.34). The remaining rewards will be distributed proportionally to delegators

METADATA_URI

The URL where validator metadata is hosted, formatted in either JSON or OpenMetrics.

Here are some additional requirements:

  • Each Ethereum account used (derived from MNEMONIC + ACCOUNT_INDEX) must have enough gas funds on the L1 to call the registration method of the contract.

  • Each BLS (Espresso) key can be registered only once.

  • Remember, each Ethereum account can only be used to register a single validator once. For multiple validators, at a minimum, different account indices (or mnemonics) must be used.

The output of a successful register transaction command should be of the following form:

Updating your commission

Validators can update their commission rate, subject to the following rate limits (note that these may be adjusted by governance):

  • Commission updates are limited to once per week (7 days by default)

  • Commission increases are capped at 5% per update (e.g., from 10% to 15%)

  • Commission decreases have no limit

For example, to update your commission to 2.54%:

The commission value is in percentage points with up to 2 decimal places, ranging from 0.00 to 100.00.

Deregistering a Node

At any time after registration, you may choose to stop participating by deregistering. Deregistration is a two-step process: a deregister-validator transaction that exits the active set and unbonds all delegators, followed after the exit escrow period (~7 days) by a claim-validator-exit that returns the validator's principal to the operator address.

Any accumulated staking rewards must be claimed separately via claim-rewards (see Claiming staking rewards). Deregistration does not auto-claim rewards.

Step 1: Submit the deregistration transaction. This immediately removes the node from the active validator set and starts the exit escrow:

Step 2: Claim the validator exit after the escrow period. Once the exit escrow elapses, withdraw the principal back to the operator wallet:

VALIDATOR_ADDRESS is the Ethereum address that was associated with this validator at registration time (derived from MNEMONIC + ACCOUNT_INDEX).

Delegation

In order for a node to participate after it is registered, it must have Espresso tokens delegated to it. These can come from any users who hold Espresso tokens and wish to secure the network and earn rewards through staking. To bootstrap, it is possible for the node operator themselves to delegate to their own node, if they hold Espresso tokens.

Most delegators should use the Espresso staking UI at https://stake.espresso.network/ to delegate, undelegate, and claim withdrawals through a wallet (e.g. MetaMask, Ledger). See Delegate $ESP Tokens for a walkthrough. The staking-cli commands below are equivalent and useful for scripting, multisigs, or node operators.

Delegate

To delegate to a registered node:

Delegations become active 2 epochs after the L1 transaction is finalized.

Undelegate (unstake)

Removing delegated tokens is a two-step process: an undelegate transaction that starts the exit escrow, followed (after ~7 days) by a claim-withdrawal that moves the tokens back to your wallet.

You can only have one pending undelegation per validator at a time. Claim each withdrawal before starting another undelegation from the same validator.

Step 1: Initiate the undelegation. The tokens enter the exit escrow and your effective stake decreases 2 epochs after L1 finalization:

Step 2: Claim the withdrawal after the escrow period. Once the exit escrow elapses, move the tokens back to your wallet:

Claiming staking rewards

Both validators and delegators accrue staking rewards every block their validator successfully proposes. Rewards do not auto-compound: they must be claimed manually and, if desired, re-delegated.

You can also check and claim rewards from the Espresso staking UI at https://stake.espresso.network/. The staking-cli commands below are equivalent and useful for scripting or multisig flows.

To check your unclaimed reward balance:

To claim accumulated rewards to the wallet derived from MNEMONIC + ACCOUNT_INDEX:

The claim transaction interacts with the Reward Claim contract on L1; see Networks for the contract address. For details on how rewards are calculated and distributed, see the staking-cli README.

More commands (+ Ledger support)

For more information on the staking CLI (including information on how to use it with a Ledger device), visit the README here.

Environment

When starting a node for the first time, set ESPRESSO_SEQUENCER_CONFIG_PEERSto the URL of a trusted node. This is used to fetch configuration required to join the P2P network. For example, this could be set to https://cache.main.net.espresso.network to use the Espresso Systems-operated nodes to fetch the config.

Once your node has successfully joined the network once, it should store the config locally, and this parameter will not be required on future restarts.

1. Regular Node

Command

Environment

Same for all nodes

Chosen by operators

Volumes

  • $ESPRESSO_SEQUENCER_STORAGE_PATH

  • $ESPRESSO_SEQUENCER_KEY_FILE

Note: Instead of using the above variable $ESPRESSO_SEQUENCER_KEY_FILE to load your keys from a file, you can also set the following two individually:

  • $ESPRESSO_SEQUENCER_PRIVATE_STAKING_KEY -> BLS_SIGNING_KEY~...

  • $ESPRESSO_SEQUENCER_PRIVATE_STATE_KEY -> SCHNORR_SIGNING_KEY~...

2. DA Node

Requires operator to additionally run a Postgres server. There is no need to run a DA node unless you are included in the DA committee. Most operators can ignore this.

Command

sequencer -- storage-sql -- http -- catchup -- status -- query

Environment

Same for all nodes

Chosen by operators

Volumes

  • $ESPRESSO_SEQUENCER_KEY_FILE

Requires operator to additionally run a Postgres server

Command

sequencer -- storage-sql -- http -- catchup -- status -- query

Environment

Same for all nodes

Chosen by operators

Volumes

  • $ESPRESSO_SEQUENCER_KEY_FILE

Note: Instead of using the above variable $ESPRESSO_SEQUENCER_KEY_FILE to load your keys from a file, you can also set the following two individually:

  • $ESPRESSO_SEQUENCER_PRIVATE_STAKING_KEY -> BLS_SIGNING_KEY~...

  • $ESPRESSO_SEQUENCER_PRIVATE_STATE_KEY -> SCHNORR_SIGNING_KEY~...

Hardware requirements

Hardware requirements are still in flux, but for now we recommend the following:

Non-DA Node: 1 Core CPU, 8GB memory DA Node: (Espresso node) 4 core CPU, 8GB memory + (Database) 2 Core, 4GB memory.

Storage (DA node): 1.2 TB SSD minimum, ability to scale on demand.

Storage (Pruning DA node): 100 GB

Storage (non-DA Node): Negligible, kilobytes

PreviousRun a Validator NodeNextRunning a Decaf Node

Last updated