Running a Mainnet 1 Node

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

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

  • The new container image version is TBD

  • 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

  • TBD (if using Espresso's images)

  • built off of the branch TBD (if building from source)

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 1, 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-sequencer/staking-cli:main \
	staking-cli register-validator \
	--commission $COMMISSION

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 TBD

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, expressed as a decimal between 0 and 1 with up to two decimal places. The remaining rewards will be distributed proportionally to delegators

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.

  • The commission cannot be changed later. One would need to deregister the validator, register another one, and direct delegators to redelegate in order to change it.

  • 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:

Deregistering a Node

At any time after registration, you may choose to stop participating by deregistering. This will automatically remove all of your delegators.

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.

To delegate to a registered node, the staking-clican also be used:

The delegation can always be removed using the undelegatecommand with the same arguments.

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

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, 2GB memory DA Node: (Sequencer) 4 core CPU, 8GB memory + (Database) 2 Core, 4GB memory.

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

Storage (non-DA Node): Negligible, kilobytes

PreviousMainnet 1NextContracts

Last updated