Node Configuration Reference
Reference for espresso-node modules, environment variables, CLI flags, and the genesis file format.
This page lists the espresso-node options that Run a Validator Node refers to. For the recommended configuration, image tag, and network values, start from that page.
Every option can be set as an environment variable or a CLI flag. Environment variables named ESPRESSO_SEQUENCER_* are still accepted with a deprecation warning; use the ESPRESSO_NODE_* names.
Durations take one integer and one unit, for example 500ms, 7s, 1m, 14d.
Command syntax
espresso-node [options] -- <module> [module options] -- <module> [module options]A module that depends on another must come after it on the command line, for example -- http -- query.
With the Docker image, ESPRESSO_NODE_EMBEDDED_DB=true makes the entrypoint prepend -- storage-sql with SQLite. Do not pass a storage module again in that mode. See Command.
Modules
http
HTTP server with healthcheck and version endpoints. The other API modules attach to it.
catchup
http
Serves consensus state to peers that fell behind. Included in query.
config
http
Serves /config/hotshot (HotShot config without private keys), /config/env (public Espresso environment variables), and /config/runtime (effective configuration with secrets redacted).
query
http, a storage module
Query service backed by the historical database: availability, node, and state APIs.
light-client
http, storage-sql
Leaves, headers, and stake tables with proofs that a client verifies against the light client contract on Ethereum.
explorer
http, storage-sql
Block explorer API.
submit
http
POST endpoint for submitting transactions.
storage-sql
Postgres or SQLite storage for consensus state and the query database. Recommended.
storage-fs
Filesystem storage. Used when no storage module is given. No pruning, no state catchup.
hotshot-events is retired. It is still accepted on the command line and serves nothing.
http options
ESPRESSO_NODE_API_PORT
--port
8080
Port for the HTTP API, metrics, and healthcheck.
ESPRESSO_NODE_API_MAX_CONNECTIONS
--max-connections
unlimited
Maximum concurrent HTTP connections. Further connections receive 429.
query options
ESPRESSO_NODE_API_PEERS
--peers
none
Comma-separated peer query service URLs to fetch missing data from.
storage-sql options
Connection to Postgres, used when ESPRESSO_NODE_EMBEDDED_DB=false:
ESPRESSO_NODE_POSTGRES_HOST
--host
Postgres server hostname.
ESPRESSO_NODE_POSTGRES_PORT
--port
Postgres server port.
ESPRESSO_NODE_POSTGRES_DATABASE
--database
Database name.
ESPRESSO_NODE_POSTGRES_USER
--user
Database user.
ESPRESSO_NODE_POSTGRES_PASSWORD
--password
Database password.
ESPRESSO_NODE_POSTGRES_USE_TLS
--use-tls
Connect over TLS.
With SQLite, ESPRESSO_NODE_STORAGE_PATH (--path) sets the data directory and the database is created at <ESPRESSO_NODE_STORAGE_PATH>/sqlite/database. storage-fs uses the same option.
Storage mode and connection pool:
ESPRESSO_NODE_ARCHIVE
false
Retain all history and backfill pruned data from peers. Conflicts with ESPRESSO_NODE_DATABASE_PRUNE. See Archival nodes.
ESPRESSO_NODE_LIGHTWEIGHT
false
Store leaves only. Conflicts with ESPRESSO_NODE_ARCHIVE.
ESPRESSO_NODE_DATABASE_MAX_CONNECTIONS
25
Maximum connections in the node's pool.
ESPRESSO_NODE_DATABASE_QUERY_MAX_CONNECTIONS
node pool size
Maximum connections in the separate query pool. Postgres only.
ESPRESSO_NODE_DATABASE_STATEMENT_TIMEOUT
10m
Abort statements running longer than this.
Fetching missing data from peers:
ESPRESSO_NODE_FETCH_RATE_LIMIT
Maximum simultaneous requests to peers when fetching missing data, for example 25.
ESPRESSO_NODE_ACTIVE_FETCH_DELAY
Minimum delay between fetch requests to a peer, to stay within its rate limit, for example 50ms.
ESPRESSO_NODE_CHUNK_FETCH_DELAY
Minimum delay between loading chunks from the local database in a sequential stream, for example 100ms.
Node options
ESPRESSO_NODE_STATE_PEERS
--state-peers
Comma-separated peer URLs used to fetch missing consensus state.
ESPRESSO_NODE_CONFIG_PEERS
--config-peers
Peers to fetch the network config from when none is stored locally. See First start.
ESPRESSO_STATE_RELAY_SERVER_URL
--state-relay-server-url
URL of the state relay server, provided by Espresso.
ESPRESSO_NODE_CLIQUENET_BIND_ADDRESS
--cliquenet-bind-address
0.0.0.0:9977
host:port that cliquenet binds for the validator mesh. TCP, reachable from the public internet.
Keys
Instead of a key file, keys can be given directly or derived from a mnemonic. A key file cannot be combined with these options.
ESPRESSO_NODE_PRIVATE_STAKING_KEY
--private-staking-key
BLS staking key, BLS_SIGNING_KEY~.... Signs consensus messages.
ESPRESSO_NODE_PRIVATE_STATE_KEY
--private-state-key
Schnorr state key, SCHNORR_SIGNING_KEY~.... Signs finalized states for the light client.
ESPRESSO_NODE_PRIVATE_X25519_KEY
--private-x25519-key
x25519 key, X25519_SK~.... Authenticates the node on cliquenet.
ESPRESSO_NODE_KEY_MNEMONIC
--mnemonic
Mnemonic to derive keys from. Explicit keys take precedence over derived ones.
ESPRESSO_NODE_KEY_INDEX
--index
Derivation index for --mnemonic.
The staking and state keys are required. Without an x25519 key the node generates a random one on each start, which does not match the key registered in the stake table, so peers reject its connections. Always set a persistent x25519 key.
L1 client
ESPRESSO_L1_PROVIDER
--l1-provider-url
Comma-separated HTTP JSON-RPC endpoints. Further entries are failover providers.
ESPRESSO_L1_WS_PROVIDER
--l1-ws-provider
Comma-separated ws:// or wss:// endpoints. Used to stream blocks instead of polling.
ESPRESSO_L1_POLLING_INTERVAL
--l1-polling-interval
7s
Interval for polling-based streams.
ESPRESSO_L1_RETRY_DELAY
--l1-retry-delay
1s
Delay after a failed request.
ESPRESSO_L1_RATE_LIMIT_DELAY
--l1-rate-limit-delay
retry delay
Delay after a 429 response.
ESPRESSO_L1_EVENTS_MAX_BLOCK_RANGE
--l1-events-max-block-range
10000
Maximum blocks in one eth_getLogs call. Lower it if the provider rejects large ranges.
ESPRESSO_L1_EVENTS_MAX_RETRY_DURATION
--l1-events-max-retry-duration
20m
The node exits after retrying an L1 event fetch for this long.
ESPRESSO_L1_SUBSCRIPTION_TIMEOUT
--subscription-timeout
1m
Reset the block stream after this long without a new block.
ESPRESSO_L1_FREQUENT_FAILURE_TOLERANCE
--l1-frequent-failure-tolerance
1m
Two failures within this interval trigger failover to the next provider.
ESPRESSO_L1_CONSECUTIVE_FAILURE_TOLERANCE
--l1-consecutive-failure-tolerance
10
This many consecutive failures trigger failover.
ESPRESSO_L1_FAILOVER_REVERT
--l1-failover-revert
30m
Return to the first provider this long after a failover.
ESPRESSO_L1_BLOCKS_CACHE_SIZE
--l1-blocks-cache-size
100
Finalized L1 blocks cached in memory.
ESPRESSO_L1_EVENTS_CHANNEL_CAPACITY
--l1-events-channel-capacity
100
New block events buffered before events are dropped.
ESPRESSO_L1_FINALIZED_SAFETY_MARGIN
--l1-finalized-safety-margin
none
Depth below a known finalized block at which all providers are assumed finalized. Older blocks are fetched by number; newer ones by hash chain from a known finalized block. Without it, every block is fetched by hash chain.
ESPRESSO_NODE_L1_STAKE_TABLE_UPDATE_INTERVAL
--stake-table-update-interval
60m
Interval for syncing stake table events from L1.
Telemetry
ESPRESSO_NODE_TELEMETRY_LOGS_ENABLE
false
Ship logs to Espresso.
ESPRESSO_NODE_TELEMETRY_METRICS_ENABLE
false
Ship metrics to Espresso.
ESPRESSO_NODE_TELEMETRY_LOG
warn
Filter for shipped logs, in RUST_LOG syntax.
ESPRESSO_NODE_TELEMETRY_METRICS_INTERVAL
60
Seconds between metrics pushes.
Identity
Identity values are published in the node_identity_* metrics on /status/metrics. NODE_NAME and COMPANY_NAME also label the node's telemetry.
ESPRESSO_NODE_IDENTITY_NODE_NAME
--node-name
Display name of the node, for example acme-mainnet-01.
ESPRESSO_NODE_IDENTITY_NODE_DESCRIPTION
--node-description
Free-text description of the node.
ESPRESSO_NODE_IDENTITY_COMPANY_NAME
--company-name
Operator organization, for example Acme Staking.
ESPRESSO_NODE_IDENTITY_COMPANY_WEBSITE
--company-website
Operator homepage URL.
ESPRESSO_NODE_IDENTITY_NETWORK_TYPE
--network-type
Hosting type: Residential, Hosted, AWS, GCP, Azure, or Cloud Provider, optionally with a region, for example AWS us-west-2.
ESPRESSO_NODE_IDENTITY_LATITUDE
--latitude
Approximate latitude as a decimal, for example 40.4173. Set together with longitude.
ESPRESSO_NODE_IDENTITY_LONGITUDE
--longitude
Approximate longitude as a decimal, for example -82.9071. Set together with latitude.
ESPRESSO_NODE_IDENTITY_OPERATING_SYSTEM
--operating-system
Defaults to the OS name, for example linux. uname -sr gives a more specific value.
ESPRESSO_NODE_IDENTITY_NODE_TYPE
--node-type
Defaults to espresso-sequencer <version>.
ESPRESSO_NODE_IDENTITY_ICON_14x14_1x ... ESPRESSO_NODE_IDENTITY_ICON_24x24_3x
--icon-14x14-1x ...
Icon URLs at 14x14 and 24x24 pixels, for 1x, 2x, and 3x displays.
Genesis file
The genesis file holds settings that must be identical on all nodes: protocol versions, the genesis state, and the parameters that decide block validity. Genesis files for the supported networks (source) are bundled in the image under /genesis. Set ESPRESSO_NODE_GENESIS_FILE=/genesis/mainnet.toml or /genesis/decaf.toml; operators of these networks never edit a genesis file.
A custom network uses its own genesis file, mounted into the container or served over HTTP(S).
Format
The file is TOML. Abridged from mainnet.toml:
Top-level keys
genesis_version: protocol version of the genesis block. Must not exceedbase_version.base_version,upgrade_version: protocol version the node starts on, and the version it upgrades to through an[[upgrade]]entry. Equal when no upgrade is scheduled.epoch_height,epoch_start_block: blocks per epoch and the first epoch block. Required from version0.3.drb_difficulty,drb_upgrade_difficulty: difficulty of the distributed randomness beacon. Required from version0.4.
[stake_table]
capacity: maximum number of validators the light client stake table commitment represents. Expanding it after genesis requires a network upgrade. The validator set itself comes from the stake table contract on Ethereum.
[chain_config]: parameters that decide block validity. Hashed into every block header, so a client can check that a block belongs to the expected chain.
chain_id: identifier of this Espresso network. Protocol transactions reference it to prevent replay across networks.max_block_size: blocks with a larger payload are rejected. Bytes as an integer, or a number with a unit such askb,KiB,mb.base_fee: fee per byte of data, in wei, or a number with unitwei,gwei, oreth.fee_recipient: address that receives fees.fee_contract(optional): L1 contract for depositing ETH into the Espresso fee state. Omitted means deposits are disabled. Required in thechain_configof every[[upgrade]]entry, and never the zero address.stake_table_contract(optional): address of the stake table contract on Ethereum.
[header]
timestamp: timestamp of the genesis header, as an RFC 3339 string or Unix seconds. Later blocks take the proposer's time.[header.chain_config]: chain config of the genesis header. Required.
[l1_finalized]: the finalized Ethereum block from which the node processes L1 events. One of:
number,timestamp, andhash: the node accepts only this exact block.numberonly: the node fetches the block once it is finalized.timestamponly: the node starts from the first L1 block at or after this time.
The first Espresso block processes all L1 events from this block up to the current finalized block, so choose a block recent enough for those events to be processed within one view timeout. If the block is not finalized yet, the node waits before starting consensus.
Upgrade
An [[upgrade]] entry schedules a protocol upgrade from base_version to upgrade_version. Only the entry whose version equals upgrade_version applies.
The window is either view-based (
start_proposing_view,stop_proposing_view) or time-based (start_proposing_time,stop_proposing_time). Exactly one form is allowed. Optionalstart_voting_*andstop_voting_*bound the voting window the same way.Leaders propose the upgrade inside the window. Leave enough time for it to succeed, for example 300 views or 5 to 10 minutes.
Upgrade types:
fee,epoch,drb_and_header,epoch_reward,new_protocol. Each takes achain_configtable with the post-upgrade chain config.
More detail: upgrades.md.
Last updated

