From 2b5fcbf5526ccf0aa381d3cc1c44e3883fead35d Mon Sep 17 00:00:00 2001
From: "loki-hermes-agent[bot]"
 <3150032+loki-hermes-agent[bot]@users.noreply.github.com>
Date: Sat, 13 Jun 2026 11:19:59 +0300
Subject: [PATCH] feat: add aztec sequencer integration

- 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
- Add docs/aztec-sequencer.md with operator setup and verification steps

Depends on web3signer, execution, and consensus services.
---
 .gitignore                 |  3 +++
 aztec-sequencer.yml        | 45 ++++++++++++++++++++++++++++++++++++++
 aztec/keys/.gitkeep        |  0
 aztec/keystore.sample.json | 15 +++++++++++++
 default.env                | 10 +++++++++
 docs/aztec-sequencer.md    | 39 +++++++++++++++++++++++++++++++++
 6 files changed, 112 insertions(+)
 create mode 100644 aztec-sequencer.yml
 create mode 100644 aztec/keys/.gitkeep
 create mode 100644 aztec/keystore.sample.json
 create mode 100644 docs/aztec-sequencer.md

diff --git a/.gitignore b/.gitignore
index 2241b1b8d..8d0d1bdcf 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,3 +13,6 @@ blox-ssv-config.yaml.bak
 .motd
 post-ethd-update.sh
 pre-ethd-update.sh
+
+# Aztec Sequencer Keys
+/aztec/keys/keystore.json
diff --git a/aztec-sequencer.yml b/aztec-sequencer.yml
new file mode 100644
index 000000000..5baad3d78
--- /dev/null
+++ b/aztec-sequencer.yml
@@ -0,0 +1,45 @@
+x-logging: &logging
+  logging:
+    driver: json-file
+    options:
+      max-size: 100m
+      max-file: "3"
+      tag: '{{.ImageName}}|{{.Name}}|{{.ImageFullID}}|{{.FullID}}'
+
+services:
+  aztec-sequencer:
+    restart: "unless-stopped"
+    image: "aztecprotocol/aztec:${AZTEC_DOCKER_TAG:-latest}"
+    environment:
+      - KEY_STORE_DIRECTORY=/var/lib/keystore
+      - 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}
+      - P2P_IP=${AZTEC_P2P_IP:-0.0.0.0}
+      - P2P_PORT=${AZTEC_P2P_PORT:-40400}
+      - AZTEC_PORT=${AZTEC_PORT:-8080}
+      - AZTEC_ADMIN_PORT=${AZTEC_ADMIN_PORT:-8880}
+    ports:
+      - "${AZTEC_PORT:-8080}:${AZTEC_PORT:-8080}"
+      - "${AZTEC_P2P_PORT:-40400}:${AZTEC_P2P_PORT:-40400}"
+      - "${AZTEC_P2P_PORT:-40400}:${AZTEC_P2P_PORT:-40400}/udp"
+    volumes:
+      - aztec-data:/var/lib/data
+      - ./aztec/keys:/var/lib/keystore:ro
+      - /etc/localtime:/etc/localtime:ro
+    depends_on:
+      - web3signer
+      - execution
+      - consensus
+    <<: *logging
+    labels:
+      - metrics.scrape=true
+      - metrics.path=/metrics
+      - metrics.port=8080
+      - metrics.instance=aztec-sequencer
+      - metrics.network=${NETWORK}
+      - logs.collect=true
+
+volumes:
+  aztec-data:
diff --git a/aztec/keys/.gitkeep b/aztec/keys/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/aztec/keystore.sample.json b/aztec/keystore.sample.json
new file mode 100644
index 000000000..3551cd608
--- /dev/null
+++ b/aztec/keystore.sample.json
@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "remoteSigner": "http://web3signer:9000",
+  "validators": [
+    {
+      "attester": {
+        "eth": "0x0000000000000000000000000000000000000000",
+        "bls": "0x0000000000000000000000000000000000000000000000000000000000000000"
+      },
+      "publisher": ["0x0000000000000000000000000000000000000000"],
+      "feeRecipient": "0x0000000000000000000000000000000000000000000000000000000000000000",
+      "coinbase": "0x0000000000000000000000000000000000000000"
+    }
+  ]
+}
diff --git a/default.env b/default.env
index ec09148d2..3bb763245 100644
--- a/default.env
+++ b/default.env
@@ -570,3 +570,13 @@ DOCKER_SOCK=/var/run/docker.sock
 
 # Used by ethd update - please do not adjust
 ENV_VERSION=58
+
+# ==========================================
+# Aztec Sequencer Configuration
+# ==========================================
+AZTEC_DOCKER_TAG=latest
+AZTEC_PORT=8080
+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
diff --git a/docs/aztec-sequencer.md b/docs/aztec-sequencer.md
new file mode 100644
index 000000000..107a30e58
--- /dev/null
+++ b/docs/aztec-sequencer.md
@@ -0,0 +1,39 @@
+# Aztec Sequencer Integration
+
+This guide covers enabling and configuring the Aztec Sequencer within the `eth-docker` stack.
+
+## Prerequisites
+1. An active `eth-docker` stack with `execution`, `consensus`, and `web3signer` running.
+2. At least **200,000 AZTEC tokens** staked for the sequencer identity.
+3. **≥ 0.1 ETH** funded in the publisher account(s) for L1 gas.
+
+## 1. Enable the Services
+Add `web3signer.yml` and `aztec-sequencer.yml` to your `.env` file:
+```env
+COMPOSE_FILE=...existing files...,web3signer.yml,aztec-sequencer.yml
+```
+
+## 2. Configure Keys
+1. Copy the sample keystore: `cp aztec/keystore.sample.json aztec/keys/keystore.json`
+2. Edit `aztec/keys/keystore.json`:
+   - Replace `"eth"` and `"publisher"` 42-character addresses with those managed by your Web3Signer instance.
+   - Replace the `"bls"` 66-character value with your actual BLS private key.
+3. Ensure the file is readable by the Docker user (UID 10000 by default for Aztec, but mounted read-only so standard permissions apply).
+
+## 3. Update Environment Variables
+In your `.env` file, set:
+```env
+AZTEC_P2P_IP=<YOUR_PUBLIC_IP> # Required for P2P discovery
+LOG_LEVEL=info
+```
+
+## 4. Deploy and Verify
+```bash
+./ethd up
+```
+Verify the container is healthy and metrics are being scraped:
+```bash
+./ethd ps aztec-sequencer
+curl http://localhost:8080/metrics # Should return Prometheus metrics
+```
+Metrics and logs will automatically be collected by Grafana Alloy (if enabled via `grafana.yml` or `grafana-cloud.yml`) and forwarded to your configured Grafana Cloud or local stack.