feat: add aztec sequencer integration by itenev · Pull Request #2638 · ethstaker/eth-docker

itenev · 2026-06-13T08:26:25Z

Summary

This PR introduces support for running an Aztec Sequencer node within the eth-docker stack.

> Note: Comprehensive setup and key migration documentation has been added to the eth-docker-docs repository. See companion PR: https://github.com/ethstaker/eth-docker-docs/pull/584

Key Changes

- aztec-sequencer.yml: A new modular compose file that integrates the sequencer with the existing execution, consensus, and web3signer services. It includes native Grafana Alloy auto-discovery labels (metrics.scrape=true, logs.collect=true).
- default.env: Added default AZTEC_* environment variables for operator configuration.
- Keystore Template: Added aztec/keystore.sample.json demonstrating the hybrid key storage approach required by Aztec:
  - 42-character ETH/publisher addresses are delegated to web3signer.
  - 66-character BLS private keys are stored inline (as Aztec's BLS requirements are incompatible with Web3Signer's consensus-layer implementation).
- .gitignore: Added /aztec/keys/keystore.json to prevent accidental key commits.

Operator Checklist

Before enabling this service, operators should ensure:
1. web3signer, execution, and consensus are active and healthy.
2. web3signer.yml,aztec-sequencer.yml is appended to the COMPOSE_FILE variable in .env.
3. AZTEC_P2P_IP is set to the node's public IP address for P2P discovery.
4. A valid keystore.json (generated via the Aztec CLI) is placed in aztec/keys/.
5. The sequencer identity has the required 200,000 AZTEC tokens staked, and the publisher account holds ≥0.1 ETH for L1 gas.

Testing

- Validated compose syntax: docker-compose -f aztec-sequencer.yml config.
- Verified metrics endpoint is exposed and scraped by Grafana Alloy.

- Add aztec-sequencer.yml compose file with alloy observability labels - Add AZTEC_* environment variables to default.env template - Add hybrid keystore.sample.json (Web3Signer for ETH, inline for BLS) and update .gitignore - Documentation moved to eth-docker-docs repository Depends on web3signer, execution, and consensus services.

yorickdowne · 2026-06-16T15:00:41Z

This is a decent start, I can suggest edits that make it work more like Eth Docker does.

Before going there, though: What is the use case? Aztec have their own supported compose stack. Would that not be a be a better option?

itenev · 2026-06-17T05:54:09Z

Couple of reasons for the PR. With Coincashew not seen recently around the EthPillar project, I thought Eth-Docker would be a great project to adopt the Aztec Sequencer. Also, I am working on Agentic Ops for ETH nodes: https://github.com/itenev/agentic-node-ops and I thought it would be a good idea to include the Aztec Sequencer in the Eth-Docker observability stack.

Tbh, I wasn't aware Aztec have their own compose stack, so if you think it is better suited for the purpose, I am ok to abandon both this and the docs PR.

yorickdowne · 2026-06-18T03:42:59Z

Their compose stack is controlled by their aztec command as described here: https://docs.aztec.network/operate/operators/setup/sequencer_management

I don't run an Aztec Sequencer. If you think that there's value in having this in Eth Docker because it's got better observability, or is less opaque than what Aztec does, then by all means let's. For better or worse, you'd be the one maintaining this integration.

yorickdowne · 2026-06-18T03:45:42Z

+      - KEY_STORE_DIRECTORY=/var/lib/keystore
+      - DATA_DIRECTORY=/var/lib/data
+      - LOG_LEVEL=${LOG_LEVEL:-info}
+      - ETHEREUM_HOSTS=http://execution:${EL_RPC_PORT:-8545}


Use ${EL_NODE} here, that's what it is for. You can't rely on there only being one execution or on execution existing locally

yorickdowne · 2026-06-18T03:45:59Z

+      - DATA_DIRECTORY=/var/lib/data
+      - LOG_LEVEL=${LOG_LEVEL:-info}
+      - ETHEREUM_HOSTS=http://execution:${EL_RPC_PORT:-8545}
+      - L1_CONSENSUS_HOST_URLS=http://consensus:${CL_REST_PORT:-5052}


Use ${CL_NODE} here, that's what it is for. You can't rely on there only being one consensus or on consensus existing locally. Tbf you also can't rely on CL_NODE being just one entry, it could be multiple comma-separated. That's where an entrypoint script comes in handy, to maybe just grab the first.

yorickdowne · 2026-06-18T03:49:24Z

+      - LOG_LEVEL=${LOG_LEVEL:-info}
+      - ETHEREUM_HOSTS=http://execution:${EL_RPC_PORT:-8545}
+      - L1_CONSENSUS_HOST_URLS=http://consensus:${CL_REST_PORT:-5052}
+      - P2P_IP=${AZTEC_P2P_IP:-0.0.0.0}


I don't love having the user hard-code their IP address. Two questions:

Can the Aztec sequencer auto-detect its external? That is friendliest to users that are on residential ISPs, where the external changes

If that's not possible, does the image come with a shell? If it has a shell, you could run a small entrypoint script (even just via command: in the yml, need not be baked into a :local image) that gets the IP from a service. Something like public_v4=$(curl -s -m5 -4 ifconfig.me)

yorickdowne · 2026-06-18T03:50:24Z

+      - AZTEC_ADMIN_PORT=${AZTEC_ADMIN_PORT:-8880}
+    ports:
+      - "${AZTEC_PORT:-8080}:${AZTEC_PORT:-8080}"
+      - "${AZTEC_P2P_PORT:-40400}:${AZTEC_P2P_PORT:-40400}"


I prefer making /tcp explicit for ports.

Also add HOST_IP and for the one below, see other yml files for reference

yorickdowne · 2026-06-18T03:51:17Z

+      - AZTEC_PORT=${AZTEC_PORT:-8080}
+      - AZTEC_ADMIN_PORT=${AZTEC_ADMIN_PORT:-8880}
+    ports:
+      - "${AZTEC_PORT:-8080}:${AZTEC_PORT:-8080}"


This should go into an aztec-shared.yml. I prefer only mapping P2P ports to host by default. I'm assuming the Aztec port need not be exposed to host for normal operations.

Add the SHARE_IP when you do

yorickdowne · 2026-06-18T03:52:14Z

+AZTEC_ADMIN_PORT=8880
+AZTEC_P2P_PORT=40400
+# Set to your public IP for P2P discovery, or leave 0.0.0.0 for local testing
+AZTEC_P2P_IP=0.0.0.0


See comment above. Better if this is dynamic

yorickdowne · 2026-06-18T03:52:50Z

+# ==========================================
+# Aztec Sequencer Configuration
+# ==========================================
+AZTEC_DOCKER_TAG=latest


The ports should go to the ports section. The tag goes into the tags section. Please don't just append to the end of the file

yorickdowne · 2026-06-18T03:53:17Z

@@ -570,3 +570,13 @@ DOCKER_SOCK=/var/run/docker.sock

 # Used by ethd update - please do not adjust
 ENV_VERSION=58


When variables are being added, this version needs to be bumped by one, so the new variables are picked up by ./ethd update

yorickdowne · 2026-06-18T03:56:37Z

 pre-ethd-update.sh
+
+# Aztec Sequencer Keys
+/aztec/keys/keystore.json


That's not how .gitignore works. This won't be in the root of the file system. Better to create ./aztec/keys and then have a .gitignore inside there

itenev marked this pull request as ready for review June 13, 2026 08:27

loki-hermes-agent Bot force-pushed the feat/aztec-sequencer branch from 2b5fcbf to 5ab7f43 Compare June 13, 2026 08:37

itenev marked this pull request as draft June 13, 2026 08:38

loki-hermes-agent Bot force-pushed the feat/aztec-sequencer branch from 5ab7f43 to cf85dd6 Compare June 13, 2026 08:50

yorickdowne reviewed Jun 18, 2026

View reviewed changes

		@@ -570,3 +570,13 @@ DOCKER_SOCK=/var/run/docker.sock

		# Used by ethd update - please do not adjust
		ENV_VERSION=58

Conversation

itenev commented Jun 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yorickdowne commented Jun 16, 2026

Uh oh!

itenev commented Jun 17, 2026

Uh oh!

yorickdowne commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yorickdowne Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

itenev commented Jun 13, 2026 •

edited

Loading

yorickdowne commented Jun 18, 2026 •

edited

Loading

yorickdowne Jun 18, 2026 •

edited

Loading