aztec-packages/docs/docs-operate/operators/setup/sequencer-setup.md at 2ee327c332ccfc71d771b0a3c7e8d2ea85df4019 · AztecProtocol/aztec-packages

id	sequencer_management
displayed_sidebar	operatorsSidebar
title	Running a Sequencer
description	Learn how to manage your sequencer on the Aztec network, including registration, keystore configuration, stake management, and status monitoring.

Overview

This guide covers sequencer lifecycle management on the Aztec network: keystore configuration, node setup, registration, ongoing operations, and eventual exit.

:::danger Minimum Stake Requirement To participate as a sequencer on the Aztec network, you must stake a minimum of 200,000 AZTEC tokens. Ensure you have sufficient tokens before proceeding with sequencer setup and registration. :::

Sequencer nodes are critical infrastructure responsible for ordering transactions and producing blocks. They perform three key actions:

Assemble unprocessed transactions and propose the next block
Attest to correct execution of transactions in proposed blocks (when part of the sequencer committee)
Submit successfully attested blocks to L1

Before publication, blocks must be validated by a committee of sequencer nodes who re-execute public transactions and verify private function proofs. Committee members attest to validity by signing the block header.

Once sufficient attestations are collected (two-thirds of the committee plus one), the block can be submitted to L1.

Minimum Hardware Requirements

8 core / 16 vCPU (released in 2015 or later)
16 GB RAM
1 TB NVMe SSD
25 Mbps network connection

These requirements are subject to change as the network throughput increases.

Before proceeding: Ensure you've reviewed and completed the prerequisites.

Keystore Explanation

Sequencers require private keys to identify themselves as valid proposers and attesters. These keys are configured through a private keystore file.

Private Keystore Structure

The private keystore file (keystore.json) uses the following structure:

{
  "schemaVersion": 1,
  "validators": [
    {
      "attester": {
        "eth": "ETH_PRIVATE_KEY",
        "bls": "BLS_PRIVATE_KEY"
      },
      "publisher": ["PUBLISHER_PRIVATE_KEY"],  // Optional: defaults to attester key
      "feeRecipient": "0x0000000000000000000000000000000000000000000000000000000000000000",  // Not currently used, set to all zeros
      "coinbase": "ETH_ADDRESS"
    }
  ]
}

:::info The attester field contains both Ethereum and BLS keys:

ETH key: Derives the address that serves as your sequencer's unique identifier in the protocol
BLS key: Used to sign proposals and attestations, as well as for staking operations :::

Field Descriptions

attester (required)

Your sequencer's identity. Contains both Ethereum and BLS keys:

Format: Object with eth and bls fields
eth: Ethereum private key - the derived address serves as your sequencer's unique identifier in the protocol
bls: BLS private key - actually signs proposals and attestations, and is used for staking operations (validator registration and proof of possession)
Purpose: The ETH address identifies your sequencer, while the BLS key performs the cryptographic signing of consensus messages

publisher (optional)

Separate private key(s) for submitting BLS-signed messages to L1. The publisher just pays gas to post already-signed proposals and attestations.

Format: Array of Ethereum private keys
Default: Uses attester key if not specified
Purpose: Posts signed messages to L1 and pays for gas (doesn't participate in signing)
Rule of thumb: Ensure every publisher account maintains at least 0.1 ETH per attester account it serves. This balance allows the selected publisher to successfully post transactions when chosen.

:::tip If you're using the attester ETH key for publishing (no separate publisher keys), you can omit the publisher field entirely from your keystore, but you will still need to fund the attester account according to the rule of thumb above. :::

feeRecipient

Aztec address that would receive L2 transaction fees.

Format: 32-byte Aztec address (64 hex characters)
Current status: Not currently used by the protocol - set to 0x0000000000000000000000000000000000000000000000000000000000000000
Purpose: Reserved for future fee distribution mechanisms

coinbase (optional)

Ethereum address that receives all L1 block rewards and tx fees.

Format: Ethereum address
Default: Uses attester address if not specified

Generating Keys

Use the Aztec CLI's keystore utility to generate both your private and public keystores:

#if(testnet)

aztec validator-keys new \
  --fee-recipient 0x0000000000000000000000000000000000000000000000000000000000000000 \
  --staker-output \
  --gse-address 0xb6a38a51a6c1de9012f9d8ea9745ef957212eaac \
  --l1-rpc-urls $ETH_RPC

Relevant parameters:

--fee-recipient: Set to all zeros (not currently used by the protocol)
--staker-output: Generate the public keystore for the staking dashboard
--gse-address: The GSE (Governance Staking Escrow) contract address (0xb6a38a51a6c1de9012f9d8ea9745ef957212eaac for Sepolia testnet)
--l1-rpc-urls: Your Ethereum Sepolia L1 RPC endpoint
- Set ETH_RPC environment variable, or replace $ETH_RPC with your RPC URL (e.g., https://sepolia.infura.io/v3/YOUR_API_KEY) #else

aztec validator-keys new \
  --fee-recipient 0x0000000000000000000000000000000000000000000000000000000000000000 \
  --staker-output \
  --gse-address 0xa92ecFD0E70c9cd5E5cd76c50Af0F7Da93567a4f \
  --l1-rpc-urls $ETH_RPC

Relevant parameters:

--fee-recipient: Set to all zeros (not currently used by the protocol)
--staker-output: Generate the public keystore for the staking dashboard
--gse-address: The GSE (Governance Staking Escrow) contract address (0xa92ecFD0E70c9cd5E5cd76c50Af0F7Da93567a4f for mainnet)
--l1-rpc-urls: Your Ethereum mainnet RPC endpoint
- Set ETH_RPC environment variable, or replace $ETH_RPC with your Ethereum mainnet RPC URL (e.g., https://mainnet.infura.io/v3/YOUR_API_KEY) #endif
--count: Number of validator identities to generate (default: 1)
- Use this to generate multiple attester identities in a single keystore
- Example: --count 5 generates 5 validator identities with sequential addresses
- All identities are derived from the same mnemonic using different derivation paths
- Useful for operators running multiple sequencer identities or delegated staking providers #if(testnet)
--publisher-count Number of publisher accounts per validator (default 1) #else
--publisher-count Number of publisher accounts per validator (default 0) #endif

This command creates two JSON files:

Private keystore (~/.aztec/keystore/keyN.json) - Contains your ETH and BLS private keys for running the node
Public keystore (~/.aztec/keystore/keyN_staker_output.json) - Contains only public information (public keys and proof of possession) for the staking dashboard

Where N is an auto-incrementing number (e.g., key1.json, key2.json, etc.)

What gets generated:

Automatically generates a mnemonic for key derivation (or provide your own with --mnemonic)
Creates an ETH key (for your sequencer identifier) and BLS key (for signing)
Computes BLS public keys (G1 and G2) and proof of possession
Outputs your attester address, publisher address and BLS public keys to the console

Example output (single validator):

No mnemonic provided, generating new one...
Using new mnemonic:

word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12

Wrote validator keystore to /Users/aztec/.aztec/keystore/key1.json
Wrote staker output for 1 validator(s) to /Users/aztec/.aztec/keystore/key1_staker_output.json

acc1:
  attester:
    eth: 0xA55aB561877E479361BA033c4ff7B516006CF547
    bls: 0xa931139040533679ff3990bfc4f40b63f50807815d77346e3c02919d71891dc1

Example output (multiple validators with --count 3):

No mnemonic provided, generating new one...
Using new mnemonic:

word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12

Wrote validator keystore to /Users/aztec/.aztec/keystore/key1.json
Wrote staker output for 3 validator(s) to /Users/aztec/.aztec/keystore/key1_staker_output.json

acc1:
  attester:
    eth: 0xA55aB561877E479361BA033c4ff7B516006CF547
    bls: 0xa931139040533679ff3990bfc4f40b63f50807815d77346e3c02919d71891dc1
acc2:
  attester:
    eth: 0xB66bC672988F590472CA144e5D8d9F82307DA658
    bls: 0xb842240151644780ff4991cfd5f51c74f61918926e88457f4d13020e82902ed2
acc3:
  attester:
    eth: 0xC77cD783999F601583DB255f6E9e0F93418EB769
    bls: 0xc953351262755891ff5aa2dfe6f62d85f72a29a37f99568f5e24131f93a13fe3

Critical: Save your mnemonic phrase!

The mnemonic is the only thing you must save - it can regenerate all your keys, addresses, and keystores
Store it securely offline (not on the server running the node)

For convenience, note:

Attester address (eth): Your sequencer's identifier (e.g., 0xA55aB...F547) - useful for registration and monitoring
File paths: Where the keystores were saved

All other information (BLS keys, public keys, addresses) can be re-derived from the mnemonic if needed.

#if(testnet) :::tip Provide Your Own Mnemonic For deterministic key generation or to recreate keys later, provide your own mnemonic:

aztec validator-keys new \
  --fee-recipient 0x0000000000000000000000000000000000000000000000000000000000000000 \
  --staker-output \
  --gse-address 0xb6a38a51a6c1de9012f9d8ea9745ef957212eaac \
  --l1-rpc-urls $ETH_RPC \
  --mnemonic "your twelve word mnemonic phrase here"

::: #else :::tip Provide Your Own Mnemonic For deterministic key generation or to recreate keys later, provide your own mnemonic:

aztec validator-keys new \
  --fee-recipient 0x0000000000000000000000000000000000000000000000000000000000000000 \
  --staker-output \
  --gse-address 0xa92ecFD0E70c9cd5E5cd76c50Af0F7Da93567a4f \
  --l1-rpc-urls $ETH_RPC \
  --mnemonic "your twelve word mnemonic phrase here"

::: #endif

#if(testnet) :::tip Generate Multiple Validator Identities To generate multiple validator identities (useful for delegated staking providers or operators running multiple sequencers):

# Generate 5 validator identities from the same mnemonic
aztec validator-keys new \
  --fee-recipient 0x0000000000000000000000000000000000000000000000000000000000000000 \
  --staker-output \
  --gse-address 0xb6a38a51a6c1de9012f9d8ea9745ef957212eaac \
  --l1-rpc-urls $ETH_RPC \
  --count 5

#else :::tip Generate Multiple Validator Identities To generate multiple validator identities (useful for delegated staking providers or operators running multiple sequencers):

# Generate 5 validator identities from the same mnemonic
aztec validator-keys new \
  --fee-recipient 0x0000000000000000000000000000000000000000000000000000000000000000 \
  --staker-output \
  --gse-address 0xa92ecFD0E70c9cd5E5cd76c50Af0F7Da93567a4f \
  --l1-rpc-urls $ETH_RPC \
  --count 5

#endif

Each identity gets a unique attester address derived from sequential derivation paths. All identities are included in:

The same private keystore file (keyN.json)
The same public keystore file (keyN_staker_output.json) :::

For detailed instructions, advanced options, and complete examples, see the Creating Sequencer Keystores guide.

Setup with Docker Compose

Step 1: Set Up Directory Structure

Create the directory structure for sequencer data storage:

mkdir -p aztec-sequencer/keys aztec-sequencer/data
cd aztec-sequencer
touch .env

Step 2: Generate and Move Private Keystore to Docker Directory

If you haven't already generated your private and public keystores, do so now (see Generating Keys above).

Move the private keystore (not the public keystore) into the Docker directory:

# Move the private keystore to Docker directory (replace N with your key number)
cp ~/.aztec/keystore/keyN.json aztec-sequencer/keys/keystore.json

# Keep the public keystore for later use with the staking dashboard
# It will be at ~/.aztec/keystore/keyN_staker_output.json

Step 3: Fund Your Publisher Account

Your sequencer needs ETH to pay for gas when submitting blocks to L1. Fund the account that will act as the publisher.

Determine which address to fund:

# Get your attester address (this will be your publisher if no separate publisher is configured)
jq -r '.[0].attester' ~/.aztec/keystore/keyN_staker_output.json

# If you have a separate publisher configured: (Note this returns the publisher private key)
jq -r '.validators[0].publisher[0]' aztec-sequencer/keys/keystore.json

Funding requirements:

Rule of thumb: Maintain at least 0.1 ETH per attester account in each publisher account
Publisher accounts submit blocks to L1 and pay for gas fees
The system does not retry with another publisher if a transaction fails due to insufficient funds

Examples:

1 attester with 1 publisher (or using attester as publisher) → Maintain ≥ 0.1 ETH
3 attesters with 1 publisher → Maintain ≥ 0.3 ETH in that publisher account
3 attesters with 2 publishers → Maintain ≥ 0.15 ETH in each publisher account (0.3 ETH total)

:::tip Set up monitoring or alerts to notify you when the publisher balance falls below the recommended threshold to prevent failed block publications. :::

Step 4: Configure Environment Variables

Add the following to your .env file:

#if(testnet)

DATA_DIRECTORY=./data
KEY_STORE_DIRECTORY=./keys
LOG_LEVEL=info
ETHEREUM_HOSTS=[your Ethereum Sepolia execution endpoint, or a comma separated list if you have multiple]
L1_CONSENSUS_HOST_URLS=[your Ethereum Sepolia consensus endpoint, or a comma separated list if you have multiple]
ETHEREUM_DEBUG_HOSTS=[your trace capable L1 execution endpoint]
P2P_IP=[your external IP address]
P2P_PORT=40400
AZTEC_PORT=8080
AZTEC_ADMIN_PORT=8880

#else

DATA_DIRECTORY=./data
KEY_STORE_DIRECTORY=./keys
LOG_LEVEL=info
ETHEREUM_HOSTS=[your Ethereum mainnet execution endpoint, or a comma separated list if you have multiple]
L1_CONSENSUS_HOST_URLS=[your Ethereum mainnet consensus endpoint, or a comma separated list if you have multiple]
ETHEREUM_DEBUG_HOSTS=[your trace capable L1 execution endpoint]
P2P_IP=[your external IP address]
P2P_PORT=40400
AZTEC_PORT=8080
AZTEC_ADMIN_PORT=8880

#endif

:::tip Find your public IP address with: curl ipv4.icanhazip.com :::

:::warning Nethermind Users (versions before v1.36.0) If you are using Nethermind as your L1 execution client with a version before v1.36.0, you must add the following environment variable:

# Required for Nethermind versions before v1.36.0
L1_FIXED_PRIORITY_FEE_PER_GAS=1

This issue was fixed in Nethermind v1.36.0, so users on that version or later do not need this setting. :::

:::warning In order to retrieve blocks posted to L1 via non-standard contract interactions, it is necessary to have access to an L1 rpc endpoint with 'trace' capability (either trace_transaction or debug_traceTransaction). The variable ETHEREUM_DEBUG_HOSTS is used to provide these url/s to the node. If not provided, the value of this will default to that set in ETHEREUM_HOSTS. The node will validate whether it is able to execute a trace call on the provided url/s, if not, it looks to the value set in ETHEREUM_ALLOW_NO_DEBUG_HOSTS to determine whether this should prevent the node from starting. By default ETHEREUM_ALLOW_NO_DEBUG_HOSTS is true, allowing the node to start. Any url provided in ETHEREUM_DEBUG_HOSTS will only be used in the case of having to execute a trace, it won't be used in regular L1 interactions.

Note - if the node does not have access to an rpc url that is capable of trace calls and it encounters a block posted via a transaction using non-standard contract interactions, it may become stuck and unable to progress the chain. :::

Step 5: Create Docker Compose File

Create a docker-compose.yml file in your aztec-sequencer directory:

services:
  aztec-sequencer:
    image: "aztecprotocol/aztec:#release_version"
    container_name: "aztec-sequencer"
    ports:
      - ${AZTEC_PORT}:${AZTEC_PORT}
      - ${P2P_PORT}:${P2P_PORT}
      - ${P2P_PORT}:${P2P_PORT}/udp
    volumes:
      - ${DATA_DIRECTORY}:/var/lib/data
      - ${KEY_STORE_DIRECTORY}:/var/lib/keystore
    environment:
      KEY_STORE_DIRECTORY: /var/lib/keystore
      DATA_DIRECTORY: /var/lib/data
      LOG_LEVEL: ${LOG_LEVEL}
      ETHEREUM_HOSTS: ${ETHEREUM_HOSTS}
      L1_CONSENSUS_HOST_URLS: ${L1_CONSENSUS_HOST_URLS}
      ETHEREUM_DEBUG_HOSTS: ${ETHEREUM_DEBUG_HOSTS}
      P2P_IP: ${P2P_IP}
      P2P_PORT: ${P2P_PORT}
      AZTEC_PORT: ${AZTEC_PORT}
      AZTEC_ADMIN_PORT: ${AZTEC_ADMIN_PORT}
    entrypoint: >-
      node
      --no-warnings
      /usr/src/yarn-project/aztec/dest/bin/index.js
      start
      --node
      --archiver
      --sequencer
      --network #release_network
    networks:
      - aztec
    restart: always

networks:
  aztec:
    name: aztec

:::warning Security: Admin Port Not Exposed The admin port (8880) is intentionally not exposed to the host machine for security reasons. The admin API provides sensitive operations like configuration changes and database rollbacks that should never be accessible from outside the container.

If you need to access admin endpoints, use docker exec:

docker exec -it aztec-sequencer curl -X POST http://localhost:8880 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"nodeAdmin_getConfig","params":[],"id":1}'

:::

This configuration includes only essential settings. The --network #release_network flag applies network-specific defaults—see the CLI reference for all available configuration options.

Step 6: Start the Sequencer

Start the sequencer:

docker compose up -d

Verification

Once your sequencer is running, verify it's working correctly:

Check Sync Status

Check the current sync status (this may take a few minutes):

curl -s -X POST -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","method":"node_getL2Tips","params":[],"id":67}' \
http://localhost:8080 | jq -r ".result.proven.number"

Compare the output with block explorers (see Networks page for explorer links).

Check Node Status

curl http://localhost:8080/status

View Logs

docker compose logs -f --tail 100 aztec-sequencer

Next Steps: Registering Your Sequencer

Now that your sequencer node is set up and running, you need to register it with the network. There are two ways to participate as a sequencer:

Option 1: Self-Staking via Staking Dashboard

Register your sequencer and provide your own stake through the staking dashboard. This is the most common approach for individual operators.

→ Register Your Sequencer (Self-Staking)

You'll use the public keystore file (keyN_staker_output.json) that was generated when you created your keys.

Option 2: Running with Delegated Stake

Operate sequencers backed by tokens from delegators. This non-custodial system allows you to run sequencer infrastructure while delegators provide the economic backing.

→ Run as a Staking Provider

As a provider, you'll register with the Staking Registry and manage a queue of sequencer identities that activate when delegators stake to you.

:::tip Which Option Should I Choose?

Self-staking: You have tokens and want to run your own sequencer
Delegated staking: You want to operate sequencer infrastructure and earn commission from delegators' stake

Both options use the same node setup from this guide. :::

Monitoring Sequencer Status

You can query the status of any sequencer (attester) using the Rollup and GSE (Governance Staking Escrow) contracts on L1.

Prerequisites

Foundry installed (cast command)
Ethereum RPC endpoint
Registry contract address for your network

Get Contract Addresses

First, get the canonical Rollup contract address from the Registry:

# Get the canonical rollup address
cast call [REGISTRY_CONTRACT_ADDRESS] "getCanonicalRollup()" --rpc-url [YOUR_RPC_URL]

Then get the GSE contract address from the Rollup:

# Get the GSE contract address
cast call [ROLLUP_ADDRESS] "getGSE()" --rpc-url [YOUR_RPC_URL]

Query Sequencer Status

Check the complete status and information for a specific sequencer:

# Get full attester view (status, balance, exit info, config)
cast call [ROLLUP_ADDRESS] "getAttesterView(address)" [ATTESTER_ADDRESS] --rpc-url [YOUR_RPC_URL]

This returns an AttesterView struct containing:

status - The sequencer's current status (see Status Codes below)
effectiveBalance - The sequencer's effective stake balance
exit - Exit information (if the sequencer is exiting)
config - Attester configuration (withdrawer address and public key)

Status Codes

Status	Name	Meaning
0	NONE	The sequencer does not exist in the sequencer set
1	VALIDATING	The sequencer is currently active and participating in consensus
2	ZOMBIE	The sequencer is not active (balance fell below ejection threshold, possibly due to slashing) but still has funds in the system
3	EXITING	The sequencer has initiated withdrawal and is in the exit delay period

Performance Monitoring

Track your sequencer's performance by monitoring:

Effective balance - Should remain above the ejection threshold
Status - Should be VALIDATING for active participation
Attestation rate - How many attestations you've successfully submitted
Proposal success rate - How many of your proposed blocks were accepted
Network participation metrics - Overall participation in network consensus

Exiting a Sequencer

:::warning Information about the exit process will be added when the mechanism is finalized. Check the Aztec Discord for the latest information on exiting the sequencer set. :::

Troubleshooting

Port forwarding not working

Issue: Your node cannot connect to peers.

Solutions:

Verify your external IP address matches the P2P_IP setting
Check firewall rules on your router and local machine
Test connectivity using: nc -zv [your-ip] 40400

Sequencer not syncing

Issue: Your node is not synchronizing with the network.

Solutions:

Check L1 endpoint connectivity
Verify both execution and consensus clients are fully synced
Review logs for specific error messages
Ensure L1 endpoints support high throughput

Private keystore issues

Issue: Private keystore not loading or errors about invalid keys.

Solutions:

Ensure keystore.json is properly formatted
Verify private keys are valid Ethereum private keys
Check file permissions on the keys directory

Docker issues

Issue: Container won't start or crashes.

Solutions:

Ensure Docker and Docker Compose are up to date
Check disk space availability
Verify the .env file is properly formatted
Review container logs: docker compose logs aztec-sequencer

Common Issues

See the Operator FAQ for additional common issues and resolutions.

Additional Resources

After setting up and registering your sequencer:

Register Your Sequencer - Complete registration via staking dashboard
Monitor Sequencer Status - Track performance and attestation rate
Operator FAQ - Common issues and resolutions
Governance Participation - Participate in governance
High Availability Setup - Run your sequencer across multiple nodes for redundancy
Advanced Keystore Patterns - Manage multiple sequencer identities

Community support:

Join the Aztec Discord for operator support and network updates

Uh oh!

FilesExpand file tree

sequencer-setup.md

Latest commit

History

sequencer-setup.md

File metadata and controls

Overview

Minimum Hardware Requirements

Keystore Explanation

Private Keystore Structure

Field Descriptions

attester (required)

publisher (optional)

feeRecipient

coinbase (optional)

Generating Keys

Setup with Docker Compose

Step 1: Set Up Directory Structure

Step 2: Generate and Move Private Keystore to Docker Directory

Step 3: Fund Your Publisher Account

Step 4: Configure Environment Variables

Step 5: Create Docker Compose File

Step 6: Start the Sequencer

Verification

Check Sync Status

Check Node Status

View Logs

Next Steps: Registering Your Sequencer

Option 1: Self-Staking via Staking Dashboard

Option 2: Running with Delegated Stake

Monitoring Sequencer Status

Prerequisites

Get Contract Addresses

Query Sequencer Status

Status Codes

Performance Monitoring

Exiting a Sequencer

Troubleshooting

Port forwarding not working

Sequencer not syncing

Private keystore issues

Docker issues

Common Issues

Additional Resources