Search
K

Running a Sequencer Node

Information on the different ways to run a sequencer node.

Basic Usage

Visit the espresso-sequencer repository for instructions on how to run a sequencer node natively or with docker. Find the latest docker images here.
Usage:
# Run a node natively
target/release/sequencer [options] -- <module>
# Run a node with the sequencer docker image
docker run -it \
--name sequencer1 \
-e <env_variable> \
ghcr.io/espressosystems/espresso-sequencer/sequencer:main \
sequencer [options] -- <module>
For brevity, we will omit the full sequencer path from here and simply refer to the executable as sequencer going forward.
The sequencer docker compose file is a great reference point for configuring an entire local sequencer network, including a few sequencer nodes, an L1 client, and the HotShot data availability and orchestrator servers.
Parameters:
Env Variable
CLI Flag
Description
ESPRESSO_SEQUENCER_L1_WS_PROVIDER
None
WebSocket URI of the L1 provider (e.g. ws://localhost:8545.
ESPRESSO_SEQUENCER_ORCHESTRATOR_URL
--orchestrator-url
URL of the HotShot orchestrator. This service will be provided by Espresso.
ESPRESSO_SEQUENCER_DA_SERVER_URL
--da-server-url
URL of the HotShot DA web server. This service will be provided by Espresso.
ESPRESSO_SEQUENCER_WEBSERVER_POLL_INTERVAL
--webserver-poll-interval
The amount of time to wait between each request to the HotShot consensus or DA web servers during polling.

Optional Modules

The sequencer node supports a set of optional modules that extend the node with useful APIs (e.g. transaction submission or query functionality). Here we describe what these modules do and how to enable them.
In general, modules are enabled in the following way:
# Run a sequencer node with a couple of modules enabled
sequencer -- <module1_name> --<arg1_name> <arg1_value> -- <module2_name>

HTTP

This module runs a basic HTTP server that comes with healthcheck and version endpoints. Additional endpoints can be enabled with the modules listed below.
Usage:
sequencer -- http --port 50000
Parameters:
Env Variable
CLI Flag
Description
ESPRESSO_SEQUENCER_API_PORT
--port
Port that the HTTP API will use.

Query

This module enables a HotShot query service API that connects to a persistent store containing the history of the blockchain. This API provides endpoints that rollups can use to integrate with the sequencer.
This module must be enabled alongside the http module. The query API can be accessed at the port specified by the http module. This option also requires a storage module, which defaults to storage-fs (see below for more details on storage options).
Usage:
sequencer -- http -- query
Env Variable
CLI Flag
Description
ESPRESSO_SEQUENCER_API_PEERS
--peers
A comma-separated list of peer query service URLs to fetch missing data from.

Filesystem Storage

This module enables a local storage backend for the query service and consensus state. Eventually, the backend will also store DA blocks and VID shares. This setting is useful for testing and debugging, but is not recommended for production nodes because it is currently not very stable or performant. Long term, we hope to improve this storage option.
Usage:
sequencer -- http -- query -- storage-fs --path ./storage-path
Parameters:
Env Variable
CLI Flag
Description
ESPRESSO_SEQUENCER_STORAGE_PATH
--path
Storage path for persistent data.

SQL Storage

This module enables a postgres storage backend for the query service and consensus state. Eventually, the backend will also store DA blocks and VID shares. This setting is recommended for production nodes.
Usage:
sequencer -- http -- query -- storage-sql
Parameters:
Env Variable
CLI Flag
Description
N/A
--uri
This is a shorthand for setting a number of other options all at once in URI form. Components of this URI can overridden by the parameters below. Example: postgres[ql]://[username[:password]@][host[:port],]/database[?parameter_list].
ESPRESSO_SEQUENCER_POSTGRES_HOST
--host
Hostname for the remote Postgres database server.
ESPRESSO_SEQUENCER_POSTGRES_PORT
--port
Port for the remote Postgres database server.
ESPRESSO_SEQUENCER_POSTGRES_DATABASE
--database
Name of database to connect to.
ESPRESSO_SEQUENCER_POSTGRES_USER
--user
Postgres user to connect as.
ESPRESSO_SEQUENCER_POSTGRES_PASSWORD
--password
Password for Postgres user.
ESPRESSO_SEQUENCER_POSTGRES_USE_TLS
--use-tls
Use TLS for an encrypted connection to the database.

Submit

This module extends the HTTP API with a POST endpoint to submit a transaction for sequencing.
Usage:
sequencer -- http -- submit

Status

This module extends the HTTP API with telemetry and consensus metrics (e.g. an endpoint to retrieve the latest block height).
Usage:
sequencer -- http -- status

DA Nodes vs. non-DA Nodes

Eventually, it will be possible to run a DA node. DA nodes will need to store a certain number of blocks at a time on demand until an archival node can obtain the DA data. We give very rough storage estimates for DA nodes below. The 3 TB scaling recommendation assumes conservative conditions of maximum network throughput. In practice, storage requirements should be much lower than 3 TB.
Non-DA nodes have no need to persist block data and therefore have negligible storage requirements.

Hardware Requirements

Hardware requirements are still in flux as we refine our testnets and add new features, but for now we recommend the following:
RAM: 16-32 GB.
CPU: 2-4 Cores.
Storage (DA node): 20 GB minimum, ability to scale to 3 TB on demand.
Storage (non-DA Node): Negligible, 10s - 100s of bytes.
Last modified 17d ago