diff --git a/docs/docs-words.txt b/docs/docs-words.txt index 00004900c1d0..7a0dd434ff41 100644 --- a/docs/docs-words.txt +++ b/docs/docs-words.txt @@ -59,6 +59,7 @@ colums Commiting comsumer connectionless +containrrr contarct coruscant crosschain diff --git a/docs/docs/the_aztec_network/concepts/deployments/what_is_deployment.md b/docs/docs/the_aztec_network/concepts/deployments/what_is_deployment.md index 579195808353..75003e1e66e4 100644 --- a/docs/docs/the_aztec_network/concepts/deployments/what_is_deployment.md +++ b/docs/docs/the_aztec_network/concepts/deployments/what_is_deployment.md @@ -22,7 +22,7 @@ Hypothetical Asset would live on Ethereum L1. It may have a minter which would b This is brought up to the community for discussion purposes only to illustrate how proposed governance mechanisms could work with a Hypothetical Asset. -- **Validators** must stake the Hypothetical Asset within the instance's contract to join that instance's validator set. +- **Sequencers** must stake the Hypothetical Asset within the instance's contract to join that instance's sequencer set. - **Holders** must lock Hypothetical Asset with the Governance contract to be able to vote on proposals. - **Provers** must deposit Hypothetical Asset in the escrow contract in order to bid for the right to create a proof for an epoch. diff --git a/docs/docs/the_aztec_network/concepts/governance/putting_forward_proposals.md b/docs/docs/the_aztec_network/concepts/governance/putting_forward_proposals.md index da6d58e7a3b6..270f69e3c8be 100644 --- a/docs/docs/the_aztec_network/concepts/governance/putting_forward_proposals.md +++ b/docs/docs/the_aztec_network/concepts/governance/putting_forward_proposals.md @@ -10,9 +10,9 @@ Sequencers can only nominate a proposal during an L2 slot for which they’ve be A mechanism is also proposed whereby any Hypothetical Asset holder (“Holderˮ) can burn a large quantity of Hypothetical Asset to trigger a vote on a proposal, without having the sequencers nominating the proposal. Note that Hypothetical Asset holders would still need to vote to approve any proposals nominated via this mechanism. -To nominate a proposal, a validator of the current canonical rollup would deploy two sets of contracts: +To nominate a proposal, a sequencer of the current canonical rollup would deploy two sets of contracts: 1. The upgraded contracts they wish to upgrade to 2. `code` which can be executed by governance to upgrade into these contracts -Then when it is their turn as the proposer, they call `vote(address _proposal)` on the `Proposals` contract, where `_proposal ` is the address of the `code` payload. Alternatively, validators can set the `GOVERNANCE_PROPOSAL_PAYLOAD=_proposal` env variable which will call `vote(address _proposal)` during a slot they're eligible to signal in. +Then when it is their turn as the proposer, they call `vote(address _proposal)` on the `Proposals` contract, where `_proposal ` is the address of the `code` payload. Alternatively, sequencers can set the `GOVERNANCE_PROPOSAL_PAYLOAD=_proposal` env variable which will call `vote(address _proposal)` during a slot they're eligible to signal in. diff --git a/docs/docs/the_aztec_network/concepts/governance/upgrades.md b/docs/docs/the_aztec_network/concepts/governance/upgrades.md index a87f1642ca74..77f8f2f3614f 100644 --- a/docs/docs/the_aztec_network/concepts/governance/upgrades.md +++ b/docs/docs/the_aztec_network/concepts/governance/upgrades.md @@ -38,4 +38,4 @@ After governance approval and a delay period, the proposal becomes executable: - Any Ethereum account can call `execute(_proposalId)` on the Governance contract. - The `execute` function calls the proposal code, transitioning the network to the new Rollup instance. -For a more hands-on guide to reacting to upgrades as a sequencer/validators, read [this](../../reference/reacting_to_upgrades.md). +For a more hands-on guide to reacting to upgrades as a sequencer, read [this](../../reference/reacting_to_upgrades.md). diff --git a/docs/docs/the_aztec_network/concepts/governance/voting.md b/docs/docs/the_aztec_network/concepts/governance/voting.md index 9a03e739c7c5..e21008876b37 100644 --- a/docs/docs/the_aztec_network/concepts/governance/voting.md +++ b/docs/docs/the_aztec_network/concepts/governance/voting.md @@ -8,4 +8,4 @@ Holders have the ability to vote on proposals as long as they lock any Hypotheti Hypothetical Assets locked in the Governance contract are simply locked and not “at stakeˮ i.e. there are no slashing conditions. -Since sequencers may be able to stake Hypothetical Assets with the rollup instances in order to join the validator set, the rollup instance could in turn lock those Hypothetical Assets in the Governance contract and vote on behalf of the sequencers. This is expected behavior. +Since sequencers may be able to stake Hypothetical Assets with the rollup instances in order to join the sequencer set, the rollup instance could in turn lock those Hypothetical Assets in the Governance contract and vote on behalf of the sequencers. This is expected behavior. diff --git a/docs/docs/the_aztec_network/concepts/proof_of_stake/slashing.md b/docs/docs/the_aztec_network/concepts/proof_of_stake/slashing.md index af8e9c76ea36..e196cb36e10c 100644 --- a/docs/docs/the_aztec_network/concepts/proof_of_stake/slashing.md +++ b/docs/docs/the_aztec_network/concepts/proof_of_stake/slashing.md @@ -17,21 +17,21 @@ There are some actions that impact the chainʼs ability to finalize new blocks: ### Insufficient quorum -In the event that a significant portion of the validator set goes offline (i.e. large internet outage) and proposers are unable to get enough attestations on block proposals, the Aztec Rollup will be unable to finalize new blocks. This will require the community to engage to fix the issue and make sure new blocks are being finalized. +In the event that a significant portion of the sequencer set goes offline (i.e. large internet outage) and proposers are unable to get enough attestations on block proposals, the Aztec Rollup will be unable to finalize new blocks. This will require the community to engage to fix the issue and make sure new blocks are being finalized. In the event of a prolonged period where the Aztec Rollup is not finalizing new blocks, it may enter Based Fallback mode. The conditions that lead to [Based Fallback (forum link)](https://forum.aztec.network/t/request-for-comments-aztecs-block-production-system/6155) mode are expected to be well defined by the community of sequencers, provers, client teams and all other Aztec Rollup stakeholders and participants. -During Based Fallback mode, anyone can propose blocks if they supply proofs for these blocks alongside them. This is in contrast to the usual condition that only the sequencer assigned to a particular slot can propose blocks during that slot. This means that the inactive validator set is bypassed and anyone can advance the chain in the event of an inactive / non-participating validator set. +During Based Fallback mode, anyone can propose blocks if they supply proofs for these blocks alongside them. This is in contrast to the usual condition that only the sequencer assigned to a particular slot can propose blocks during that slot. This means that the inactive sequencer set is bypassed and anyone can advance the chain in the event of an inactive / non-participating sequencer set. -But terminally inactive validators must be removed from the validator set or otherwise we end up in Based Fallback too often. Slashing is a method whereby the validator set votes to “slash” the stake of inactive validators down to a point where they are kicked off the validator set. For example, if we set `MINIMUM_STAKING_BALANCE=50%` then as soon as 50% or more of a validator’s balance is slashed, they will be kicked out of the set. +But terminally inactive sequencers must be removed from the sequencer set or otherwise we end up in Based Fallback too often. Slashing is a method whereby the sequencer set votes to “slash” the stake of inactive sequencers down to a point where they are kicked off the sequencer set. For example, if we set `MINIMUM_STAKING_BALANCE=50%` then as soon as 50% or more of a sequencer's balance is slashed, they will be kicked out of the set. ### Committee withholding data from the provers Provers need the transaction data (i.e. `TxObjects`) plus the client-side generated proofs to produce the final rollup proof, none of which are posted onchain. Client side proofs + transaction data are gossiped on the p2p instead so that committee members can re-execute block proposals and verify that the proposed state root is correct. -Recall from the [RFC (forum link)](https://forum.aztec.network/t/request-for-comments-aztecs-block-production-system/6155) on block production that the committee is a subset of validators, randomly sampled from the entire validator set. Block proposers are sampled from this committee. ⅔ + 1 of this committee must attest to L2 block proposals before they are posted to the L1 by the block proposer. +Recall from the [RFC (forum link)](https://forum.aztec.network/t/request-for-comments-aztecs-block-production-system/6155) on block production that the committee is a subset of sequencers, randomly sampled from the entire sequencer set. Block proposers are sampled from this committee. ⅔ + 1 of this committee must attest to L2 block proposals before they are posted to the L1 by the block proposer. -A malicious committee may not gossip the transaction data or proofs to the rest of the validator set, nor to the provers. As a result, no prover can produce the proof and the epoch in question will reorg by design. Recall from the RFC on block production that if no proof for epoch N is submitted to L1 by the end of epoch N+1, then epoch N + any blocks built in epoch N+1 are reorged. +A malicious committee may not gossip the transaction data or proofs to the rest of the sequencer set, nor to the provers. As a result, no prover can produce the proof and the epoch in question will reorg by design. Recall from the RFC on block production that if no proof for epoch N is submitted to L1 by the end of epoch N+1, then epoch N + any blocks built in epoch N+1 are reorged. ### Committee proposing an invalid state root @@ -48,6 +48,6 @@ An honest prover who has funds at stake (i.e. posted a bond to produce the epoch In all the previous cases, it is very hard to verify and automatically slash for these events onchain. This is mainly due to the fact that neither TxObjects nor client side proofs are posted onchain. Committee members also gossip attestations on the p2p and do not post them directly on chain. -Therefore a slashing mechanism is required as a deterrence against the malicious behaviour by validators and to make sure that the Aztec Rollup retains liveness. The validator set votes to slash dishonest validators based on evidence that is collected onchain + offchain, and discussed and analyzed offchain (i.e. on a forum). +Therefore a slashing mechanism is required as a deterrence against the malicious behaviour by sequencers and to make sure that the Aztec Rollup retains liveness. The sequencer set votes to slash dishonest sequencers based on evidence that is collected onchain + offchain, and discussed and analyzed offchain (i.e. on a forum). -A validator must aggregate BLS signatures on slashing proposals and post them to the L1 for slash execution. +A sequencer must aggregate BLS signatures on slashing proposals and post them to the L1 for slash execution. diff --git a/docs/docs/the_aztec_network/concepts/provers-and-sequencers/index.md b/docs/docs/the_aztec_network/concepts/provers-and-sequencers/index.md index 7cf48c011e51..fee2125afb3e 100644 --- a/docs/docs/the_aztec_network/concepts/provers-and-sequencers/index.md +++ b/docs/docs/the_aztec_network/concepts/provers-and-sequencers/index.md @@ -13,4 +13,4 @@ Sequencers will be chosen via a random election, while provers will be selected The proposers in the first `C=13` slots in epoch `N+1` will accept quotes to prove epoch N from provers. The winning prover will have until the end of epoch `N+1` to produce and submit the proof to L1. -If are you interested in running a validator node (also known as a sequencer node) or a prover node, you can refer to [the guides section](./../../guides/run_nodes/index.md). +If are you interested in running a sequencer node or a prover node, you can refer to [the guides section](./../../guides/run_nodes/index.md). diff --git a/docs/docs/the_aztec_network/guides/run_nodes/how_to_run_prover.md b/docs/docs/the_aztec_network/guides/run_nodes/how_to_run_prover.md index 8660b2902c51..e68abd8ddfd7 100644 --- a/docs/docs/the_aztec_network/guides/run_nodes/how_to_run_prover.md +++ b/docs/docs/the_aztec_network/guides/run_nodes/how_to_run_prover.md @@ -1,6 +1,6 @@ --- sidebar_position: 3 -title: How to Run a Prover Node +title: How to Run an Aztec Prover description: A comprehensive guide to setting up and running an Aztec Prover node on testnet or mainnet, including hardware requirements, configuration options, and performance optimization tips. keywords: [ @@ -23,115 +23,274 @@ tags: - infrastructure --- -import { AztecTestnetVersion } from '@site/src/components/Snippets/general_snippets'; - ## Background -Prover nodes are a critical part of the Aztec network's infrastructure. They generate cryptographic proofs that attest to the correctness of public transactions, ultimately producing a single rollup proof that is submitted to Ethereum. +This guide covers the steps required to run a prover on the Aztec network. Before you begin, you should understand that operating a prover is a resource-intensive role typically undertaken by experienced engineers due to its technical complexity and hardware requirements. -Operating a prover node requires a solid grasp of blockchain protocols, cryptographic systems, DevOps best practices, and high-performance hardware. It’s a resource-intensive role typically undertaken by experienced engineers or specialized teams due to its technical and operational complexity. +Aztec provers are critical infrastructure components that generate cryptographic proofs attesting to transaction correctness, ultimately producing a single rollup proof submitted to Ethereum. -## Prerequisites +The prover consists of three main components: -Before following this guide, make sure you: +1. **Prover node**: Polls L1 for unproven epochs, creates proving jobs, distributes them to the broker, and submits the final rollup proof to the rollup contract. -- Have the `aztec` tool [installed](../../../developers/getting_started/getting_started_on_sandbox.md#install-the-sandbox) -- Have sufficient hardware resources for proving operations -- Your confidence level is expected to be around "I'd be able to run a Prover _without_ this guide" +2. **Prover broker**: Manages the job queue, distributing work to agents and collecting results. -## Understanding Prover Architecture +3. **Prover agent(s)**: Executes proof generation jobs in a stateless manner. -The Aztec prover involves three key components: the Prover Node, the Proving Broker, and the Proving Agent. +## Prerequisites + +The minimum hardware specifications for each of the components is listed below. #### Prover Node -The Prover Node is responsible for polling the L1 for unproven epochs and initiating the proof process. When an epoch is ready to be proven, the prover node creates proving jobs and distributes them to the broker. The Prover Node is also responsible for submitting the final rollup proof to the rollup contract. +Minimum specifications: -- **Resources**: Up to 8 cores, 16GB RAM, ~1TB disk for storing state. +- 2 core / 4 vCPU +- 16 GB RAM +- 1 TB NVMe SSD +- 25 Mbps network connection #### Proving Broker -Manages a queue of proving jobs, distributing them to available agents and forwarding results back to the node. +Minimum specifications: -- **Resources**: Up to 4 cores, 16GB RAM, ~1GB disk. +- 2 core / 4 vCPU +- 16 GB RAM +- 10 GB SSD #### Proving Agents -Executes the actual proof jobs. Agents are stateless, fetch work from the broker, and return the results. +Minimum specifications: + +- 32 core / 64 vCPU +- 128 GB RAM +- 10 GB SSD + +This guide outlines a basic, non-distributed setup with all components on a single machine. Your hardware must meet or exceed the proving agent requirements listed above. + +This guide assumes you are using a standard Linux distribution (Debian or Ubuntu). + +### Required Software + +- Docker and the Aztec toolchain installed via aztec-up (see the [getting started section](../../index.md)) +- Docker Compose ([installation guide](https://docs.docker.com/compose/install/)) +- Access to L1 node endpoints (execution and consensus clients). See [Eth Docker's guide](https://ethdocker.com/Usage/QuickStart) if you need to set these up. + +## Configure the Prover + +Setting up a prover involves configuring three components through environment variables and Docker Compose. + +### Setup Steps + +1. Configure components via environment variables +2. Enable auto-update and auto-restart functionality +3. Deploy with Docker Compose + +First, create the directory structure for prover data storage: + +```sh +mkdir -p aztec-prover/prover-node-data aztec-prover/prover-broker-data +cd aztec-prover +touch .env +``` + +### Component Configuration -- **Resources**: Each agent may use up to 16 cores and 128GB RAM. +Each prover component requires specific environment variables. Configure them as follows: + +#### Prover Node + +Required environment variables: + +- `DATA_DIRECTORY`: the folder where the data of the prover node is stored +- `P2P_IP`: the IP address of this prover node +- `P2P_PORT`: the port that P2P communication happens on +- `ETHEREUM_HOSTS`: the execution RPC endpoints +- `L1_CONSENSUS_HOST_URLS`: the consensus RPC endpoints +- `LOG_LEVEL`: the desired level of logging for the prover node. It defaults to `INFO` +- `PROVER_BROKER_HOST`: the endpoint of the prover broker that this node sends prover jobs to +- `PROVER_PUBLISHER_PRIVATE_KEY`: the private key of the Ethereum EOA used for publishing the proofs to L1 +- `AZTEC_PORT`: the port that the prover node API is exposed on + +Add the following to your `.env` file (assuming default ports of 8080 for the prover node, and 40400 for p2p connectivity): + +```sh +DATA_DIRECTORY=./prover-node-data +P2P_IP= +P2P_PORT=40400 +ETHEREUM_HOSTS= +L1_CONSENSUS_HOST_URLS= +LOG_LEVEL=info +PROVER_BROKER_HOST=http://prover-broker:8080 +PROVER_PUBLISHER_PRIVATE_KEY= +AZTEC_PORT=8080 +``` + +**Note**: The broker URL `http://prover-broker:8080` references the Docker Compose service name defined later. + +:::tip +You MUST forward ports for P2P connectivity. Configure your router to forward both UDP and TCP traffic on the port specified by `P2P_PORT` to your local IP address. + +To find your public IP address, run: `curl ipv4.icanhazip.com` +::: + +#### Prover Broker + +Required environment variables: + +- `DATA_DIRECTORY`: the folder where the data of the prover broker is stored +- `LOG_LEVEL`: the desired level of logging for the prover broker. It defaults to `INFO` +- `ETHEREUM_HOSTS`: the execution RPC endpoints +- `P2P_IP`: the IP address of this prover broker +- `P2P_PORT`: the port that P2P communication happens on + +**Note**: Some variables overlap with the prover node configuration. If running components on separate machines, adjust accordingly. Since `DATA_DIRECTORY` is used by both components, define a separate variable for the broker: + +Add to your `.env` file: + +```sh +PROVER_BROKER_DATA_DIRECTORY=./prover-broker-data +``` -## Setting Up Your Prover +#### Prover Agent -### Using Docker Compose +Required environment variables: + +- `PROVER_AGENT_COUNT`: Number of agents to run (each requires ~10GB RAM) +- `PROVER_AGENT_POLL_INTERVAL_MS`: Polling interval for job requests (milliseconds) +- `PROVER_BROKER_HOST`: Broker endpoint for job submission +- `PROVER_ID`: Ethereum address corresponding to `PROVER_PUBLISHER_PRIVATE_KEY` + +**Note**: Some variables overlap with the prover node configuration. In this case we use the same value for `PROVER_BROKER_HOST`, so we will not duplicate it in our `.env` file. + +Add to your `.env` file: + +```sh +PROVER_AGENT_COUNT=10 +PROVER_AGENT_POLL_INTERVAL_MS=10000 +PROVER_ID= +``` + +### Enable Auto-Update and Auto-Restart + +The prover's auto-update functionality is critical for network coordination. This background module enables: + +- Configuration updates across all nodes +- Automated image updates via controlled shutdowns +- Rapid hot-fix deployment +- Coordinated resets after governance upgrades + +**Important**: Do NOT set `AUTO_UPDATE_URL` or `AUTO_UPDATE` environment variables. These must use their default values for proper operation. + +Since Docker Compose doesn't respect pull policies on container restarts, install Watchtower for automatic updates: + +```sh +docker run -d \ + --name watchtower \ + -v /var/run/docker.sock:/var/run/docker.sock \ + containrrr/watchtower +``` + +### Deploy with Docker Compose + +Create a `docker-compose.yml` file in your `aztec-prover` directory with the following content: ```yml name: aztec-prover services: prover-node: - image: aztecprotocol/aztec:latest # Always refer to the docs to check that you're using the correct image. - command: - - node - - --no-warnings - - /usr/src/yarn-project/aztec/dest/bin/index.js - - start - - --prover-node - - --archiver - - --network - - alpha-testnet + image: aztecprotocol/aztec:latest + entrypoint: >- + node + --no-warnings + /usr/src/yarn-project/aztec/dest/bin/index.js + start + --prover-node + --archiver + --network testnet depends_on: - broker: + prover-broker: condition: service_started required: true environment: - # PROVER_COORDINATION_NODE_URL: "http://:8080" # this can point to your own validator - using this replaces the need for the prover node to be on the P2P network and uses your validator as a sentry node of some sort. - # P2P_ENABLED: "false" # Switch to false if you provide a PROVER_COORDINATION_NODE_URL - DATA_DIRECTORY: /data - DATA_STORE_MAP_SIZE_KB: "134217728" - ETHEREUM_HOSTS: # EL RPC endpoint - L1_CONSENSUS_HOST_URLS: # CL RPC endpoint - LOG_LEVEL: info - PROVER_BROKER_HOST: http://broker:8080 - PROVER_PUBLISHER_PRIVATE_KEY: # The node needs to publish proofs to L1. Replace with your private key + DATA_DIRECTORY: /var/lib/data + ETHEREUM_HOSTS: ${ETHEREUM_HOSTS} + L1_CONSENSUS_HOST_URLS: ${L1_CONSENSUS_HOST_URLS} + LOG_LEVEL: ${LOG_LEVEL} + PROVER_BROKER_HOST: ${PROVER_BROKER_HOST} + PROVER_PUBLISHER_PRIVATE_KEY: ${PROVER_PUBLISHER_PRIVATE_KEY} + P2P_IP: ${P2P_IP} + P2P_PORT: ${P2P_PORT} + AZTEC_PORT: ${AZTEC_PORT} ports: - - "8080:8080" - - "40400:40400" - - "40400:40400/udp" + - ${AZTEC_PORT}:${AZTEC_PORT} + - ${P2P_PORT}:${P2P_PORT} + - ${P2P_PORT}:${P2P_PORT}/udp volumes: - - /home/my-node/node:/data # Local directory - - agent: - image: aztecprotocol/aztec:latest # Always refer to the docs to check that you're using the correct image. - command: - - node - - --no-warnings - - /usr/src/yarn-project/aztec/dest/bin/index.js - - start - - --prover-agent - - --network - - alpha-testnet + - ${DATA_DIRECTORY}:/var/lib/data + + prover-broker: + image: aztecprotocol/aztec:latest + entrypoint: >- + node + --no-warnings + /usr/src/yarn-project/aztec/dest/bin/index.js + start + --prover-broker + --network testnet environment: - PROVER_AGENT_COUNT: "1" - PROVER_AGENT_POLL_INTERVAL_MS: "10000" # Just to reduce the log spamming if you're using debug logging. - PROVER_BROKER_HOST: http://broker:8080 - PROVER_ID: # this should be the address corresponding to the PROVER_PUBLISHER_PRIVATE_KEY you set on the node. + DATA_DIRECTORY: /var/lib/data + ETHEREUM_HOSTS: ${ETHEREUM_HOSTS} + P2P_IP: ${P2P_IP} + LOG_LEVEL: ${LOG_LEVEL} + volumes: + - ${PROVER_BROKER_DATA_DIRECTORY}:/var/lib/data + + prover-agent: + image: aztecprotocol/aztec:latest + entrypoint: >- + node + --no-warnings + /usr/src/yarn-project/aztec/dest/bin/index.js + start + --prover-agent + --network testnet + environment: + PROVER_AGENT_COUNT: ${PROVER_AGENT_COUNT} + PROVER_AGENT_POLL_INTERVAL_MS: ${PROVER_AGENT_POLL_INTERVAL_MS} + PROVER_BROKER_HOST: ${PROVER_BROKER_HOST} + PROVER_ID: ${PROVER_ID} pull_policy: always restart: unless-stopped +``` - broker: - image: aztecprotocol/aztec:latest # Always refer to the docs to check that you're using the correct image. - command: - - node - - --no-warnings - - /usr/src/yarn-project/aztec/dest/bin/index.js - - start - - --prover-broker - - --network - - alpha-testnet - environment: - DATA_DIRECTORY: /data - ETHEREUM_HOSTS: # Your EL RPC endpoint - LOG_LEVEL: info - volumes: - - /home/my-node/node:/data # Local directory +**Note**: This configuration includes only essential settings. The `--network testnet` flag applies network-specific defaults. See the [CLI reference](../../reference/cli_reference.md) for all available options. + +Start the prover: + +```sh +docker compose up -d +``` + +## Verification + +To verify your prover is running correctly: + +1. Check that all services are running: + +```sh +docker compose ps +``` + +2. View logs for each component: + +```sh +# Prover node logs +docker compose logs -f prover-node + +# Broker logs +docker compose logs -f prover-broker + +# Agent logs +docker compose logs -f prover-agent ``` diff --git a/docs/docs/the_aztec_network/guides/run_nodes/how_to_run_sequencer.md b/docs/docs/the_aztec_network/guides/run_nodes/how_to_run_sequencer.md index 7b91300e317a..917dd59e1e1f 100644 --- a/docs/docs/the_aztec_network/guides/run_nodes/how_to_run_sequencer.md +++ b/docs/docs/the_aztec_network/guides/run_nodes/how_to_run_sequencer.md @@ -24,280 +24,253 @@ tags: ## Background +This guide covers the steps required to run a sequencer node on the Aztec network. + The Aztec sequencer node is critical infrastructure responsible for ordering transactions and producing blocks. -The sequencer node takes part in three key actions: +The sequencer node performs three key actions: -1. Assemble unprocessed transactions and propose the next block -2. Attest to correct execution of txs in the proposed block (if part of validator committee) -3. Submit the successfully attested block to L1 +1. Assembles unprocessed transactions and proposes the next block +2. Attests to correct execution of transactions in proposed blocks (when part of the sequencer committee) +3. Submits successfully attested blocks to L1 -When transactions are sent to the Aztec network, sequencer nodes bundles them into blocks, checking various constraints such as gas limits, block size, and transaction validity. Before a block can be published, it must be validated by a committee of other sequencer nodes (validators in this context) who re-execute public transactions and verify private function proofs so they can attest to correct execution. These validators attest to the block's validity by signing it, and once enough attestations are collected (two-thirds of the committee plus one), the sequencer can submit the block to L1. +Sequencer nodes bundle transactions into blocks while checking constraints like gas limits, block size, and validity. 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. The archiver component complements this process by maintaining historical chain data. It continuously monitors L1 for new blocks, processes them, and maintains a synchronized view of the chain state. This includes managing contract data, transaction logs, and L1-to-L2 messages, making it essential for network synchronization and data availability. -## Setup - -### Requirements - -A computer running Linux or MacOS with the following specifictions: - -- CPU: 8-cores -- RAM: 16 GiB -- Storage: 1 TB SSD +## Prerequisites -A Network connection of at least 25 Mbps up/down. +Minimum hardware requirements: -### Installation +- 2 core / 4 vCPU +- 16 GB RAM +- 1TB NVMe SSD +- 25 Mbps network connection -import { General, Fees } from '@site/src/components/Snippets/general_snippets'; +Please note that these requirements are subject to change as the network throughput increases. - +This guide assumes you are using a standard Linux distribution (Debian or Ubuntu). -Now install the latest testnet version of aztec: `aztec-up -v latest` +### Required Software -Join the [Discord](https://discord.gg/aztec) to connect with the community and get help with your setup. +- Docker and the Aztec toolchain installed via aztec-up (see the [getting started section](../../index.md)) +- Docker Compose ([installation guide](https://docs.docker.com/compose/install/)) +- Access to L1 node endpoints (execution and consensus clients). See [Eth Docker's guide](https://ethdocker.com/Usage/QuickStart) if you need to set these up. -## Sequencer Quickstart +## Configure the Sequencer -With the alpha-testnet version of the aztec tools, you now need to define required variables for your node. +Setting up a sequencer involves configuring keys, environment variables, and Docker Compose. -The following variable names are specific to the `aztec start` command, set them as variables in the terminal or inline before the command. +### Setup Steps -- `ETHEREUM_HOSTS=`: One or more comma-separated public rpc provider url(s). NB - don't share your access token -- `L1_CONSENSUS_HOST_URLS=`: One or more comma-separated public rpc provider url(s) that supports consensus client requests -- `VALIDATOR_PRIVATE_KEY="Ox"`: Private key of testnet L1 EOA that holds Sepolia ETH (0.01 Sepolia ETH can get you started) -- `COINBASE="0x"`: Recipient of block rewards (for node security on mainnet, this should be a different address to the validator eoa) -- `P2P_IP="x.x.x.x"`: IP address of computer running the node (you can get this by running, `curl api.ipify.org`, on your node) +1. Define private keys and accounts for sequencer duties +2. Configure node settings via environment variables +3. Enable auto-update and auto-restart functionality +4. Deploy with Docker Compose -Now in a terminal start your node as a sequencer and archiver: +First, create the directory structure for sequencer data storage: -If the above variables are set you can simply use: `aztec start --node --archiver --sequencer --network testnet` - -Otherwise you can specify values via the CLI flags (using values in place of the variable names): - -```bash -aztec start --node --archiver --sequencer \ - --network testnet \ - --l1-rpc-urls $ETHEREUM_HOSTS \ - --l1-consensus-host-urls $L1_CONSENSUS_HOST_URLS \ - --sequencer.validatorPrivateKeys $VALIDATOR_PRIVATE_KEY \ - --sequencer.coinbase $COINBASE \ - --p2p.p2pIp $P2P_IP +```sh +mkdir -p aztec-sequencer/keys aztec-sequencer/data +cd aztec-sequencer +touch .env ``` -**Additional Parameters**: The comprehensive list of parameters can be seen via: `aztec help start`. For example: +### Define Private Keys and Accounts -``` ---p2p.p2pPort (default: 40400) ($P2P_PORT) - The port for the P2P service. -``` +Sequencers require private keys to identify themselves as valid proposers or attesters. Configure these through a keystore file. -### Port forwarding +Create a `keystore.json` file in your `aztec-sequencer/keys` folder: -For some restricted environments, you may need to explicity forward the p2p port (default: 40400) to your local node ip address. - -This is often in a router's advanced network settings if required. - -### Next steps - -To add your sequencer you'll need the following few values, as well as `ETHEREUM_HOSTS` from before: - -- `STAKING_ASSET_HANDLER="0xF739D03e98e23A7B65940848aBA8921fF3bAc4b2"`: Constant L1 contract address -- `L1_CHAIN_ID="11155111"`: Sepolia chainid -- `PRIVATE_KEY="0x`: private key of account with sepolia eth to make transaction (eg can use funded validator key) - -Then run the aztec command to add your address as an L1 validator, with rpc url(s) for Etheruem L1 execution requests: - -```bash -aztec add-l1-validator --staking-asset-handler=0xF739D03e98e23A7B65940848aBA8921fF3bAc4b2 \ - --l1-rpc-urls $ETHEREUM_HOSTS \ - --l1-chain-id 11155111 \ - --private-key "0x" \ - --attester "0x" \ - --proposer-eoa "0x" +```json +{ + "schemaVersion": 1, + "validators": [ + { + "attester": ["ETH_PRIVATE_KEY_0"], + "publisher": ["ETH_PRIVATE_KEY_1"], + "coinbase": "ETH_ADDRESS_2", + "feeRecipient": "AZTEC_ADDRESS_0" + } + ] +} ``` -**Tip**: Use `aztec help add-l1-validator` for further parameter details. - -:::note Validator Quota Filled - -In the absence of real-world staking incentives, becoming a validator is throttled with time, so you may see `ValidatorQuotaFilledUntil(uint256 _timestamp)` at the beginning of the text returned. - -The timestamp is when the next round of sequencers can be added as validators, so try again right after that. - -::: - -## Deeper dive - -This guide will describe how to setup your sequencer using the `aztec start` command. For more advanced setups, refer to the Advanced Configuration section below. - -The `aztec start` tool is a one-stop-shop for running your sequencer on any Aztec Network. It assigns default values to several config variables based on a `--network` flag and launches a docker container running the sequencer software. - -To use the `aztec start` command, you need to obtain the following: - -#### RPCs - -- An L1 execution client (for reading transactions and state). It can be specified via the `--l1-rpc-urls` flag when using `aztec start` or via the env var `ETHEREUM_HOSTS`. Popular execution clients include [Geth](https://geth.ethereum.org/) or [Nethermind](https://nethermind.io/). You can run your own node or use a service like [Alchemy](https://www.alchemy.com/) or [Infura](https://www.infura.io/). - -- An L1 consensus client (for blobs). It can be specified via the `--l1-consensus-host-urls` flag when using `aztec start` or via the env var `L1_CONSENSUS_HOST_URLS`. Popular consensus clients include [Lighthouse](https://lighthouse.sigmaprime.io/) or [Prysm](https://prysmaticlabs.com/). Not all RPC providers support consensus endpoints, [Quicknode](https://www.quicknode.com/) and [dRPC](https://drpc.org/) have been known to work for consensus endpoints. - -- To reduce load on your consensus endpoint, the Aztec sequencer supports an optional remote server that serves blobs to the client. This is often called a "blob sink" or "blob storage service". You can pass your own or use one provided by a trusted party via the `--sequencer.blobSinkUrl` flag when using `aztec start`, or via the env var `BLOB_SINK_URL`. Some providers like [Alchemy](https://www.alchemy.com/) offer blob storage services as part of their infrastructure offerings. - -#### Ethereum Keys +The keystore defines keys and addresses for sequencer operation: -You will need an Ethereum private key and the corresponding public address. The private key is set via the `--sequencer.validatorPrivateKeys` flag while the public address should be specified via the `--sequencer.coinbase ` flag. +- `attester`: Private key for signing block proposals and attestations. The corresponding Ethereum address identifies the sequencer. +- `publisher`: Private key for sending block proposals to L1. Defaults to attester key if not set. +- `coinbase`: Ethereum address receiving L1 rewards and fees. Defaults to attester address if not set. +- `feeRecipient`: Aztec address receiving unburnt transaction fees from blocks. -The private key is needed as your validator will post blocks to Ethereum, and the public address will be the recipient of any block rewards. +Replace the placeholder values with your actual keys and addresses. -Disclaimer: you may want to generate and use a new Ethereum private key. +### Node Configuration -#### Networking +Required environment variables: -You MUST forward your ports. Your router must send UDP and TCP traffic on port `40400` (unless you changed the default) to your IP address on your local network. Failure to do so may result in your sequencer not participating on the p2p network. +- `DATA_DIRECTORY`: the folder where the data of the sequencer is stored +- `KEY_STORE_DIRECTORY`: can be a path to the file or directory where keystores are located. In our case it is the path to the folder containing the `keystore.json` file created above +- `LOG_LEVEL`: the desired level of logging for the sequencer. It defaults to `INFO`. +- `ETHEREUM_HOSTS`: The execution RPC endpoints +- `L1_CONSENSUS_HOST_URLS`: The consensus RPC endpoints +- `P2P_IP`: The IP address of this sequencer +- `P2P_PORT`: The port that P2P communication happens on +- `AZTEC_PORT`: The port that the sequencer node API is exposed on -As a tip, configure your router to give your MAC address the same IP address every time it does a DHCP refresh. +Add the following to your `.env` file (using default ports 8080 and 40400): -You also need to grab your external IP address and pass it along to the `--p2p.p2pIp` when using `aztec start`. - -#### Sepolia ETH - -You'll need Sepolia ETH to cover gas costs. Here are some options: - -- Use a PoW faucet like [Sepolia PoW Faucet](https://sepolia-faucet.pk910.de/) -- Ask in our Discord community (and remember to pay it forward when you can!) - -### Now Start Your Sequencer - -To boot up a sequencer using `aztec start`, run the following command: - -```bash -aztec start --node --archiver --sequencer \ - --network testnet \ - --l1-rpc-urls https://example.com \ - --l1-consensus-host-urls https://example.com \ - --sequencer.validatorPrivateKeys 0xYourPrivateKey \ - --sequencer.coinbase 0xYourAddress \ - --p2p.p2pIp 999.99.999.99 \ - --p2p.maxTxPoolSize 1000000000 +```sh +DATA_DIRECTORY=./data +KEY_STORE_DIRECTORY=./keys +LOG_LEVEL=info +ETHEREUM_HOSTS= +L1_CONSENSUS_HOST_URLS= +P2P_IP= +P2P_PORT=40400 +AZTEC_PORT=8080 ``` :::tip +You MUST forward ports for P2P connectivity. Configure your router to forward both UDP and TCP traffic on the port specified by `P2P_PORT` to your local IP address. -For a full overview of all available commands, check out the [CLI reference sheet](../../reference/cli_reference.md). +To find your public IP address, run: `curl ipv4.icanhazip.com` ::: -:::tip +### Enable Auto-Update and Auto-Restart -If you are unable to determine your public ip. Running the command `curl ipv4.icanhazip.com` can retrieve it for you. -::: +The sequencer's auto-update functionality is critical for network coordination. This background module enables: + +- Configuration updates across all nodes +- Automated image updates via controlled shutdowns +- Rapid hot-fix deployment +- Coordinated resets after governance upgrades -### Register as a Validator +**Important**: Do NOT set `AUTO_UPDATE_URL` or `AUTO_UPDATE` environment variables. These must use their default values for proper operation. -Once your node is fully synced, you can register as a validator using the `add-l1-validator` command: +Since Docker Compose doesn't respect pull policies on container restarts, install Watchtower for automatic updates: -```bash -aztec add-l1-validator \ - --l1-rpc-urls https://eth-sepolia.g.example.com/example/your-key \ - --private-key your-private-key \ - --attester your-validator-address \ - --proposer-eoa your-validator-address \ - --staking-asset-handler 0xF739D03e98e23A7B65940848aBA8921fF3bAc4b2 \ - --l1-chain-id 11155111 +```sh +docker run -d \ + --name watchtower \ + -v /var/run/docker.sock:/var/run/docker.sock \ + containrrr/watchtower ``` -:::warning +### Deploy with Docker Compose -You may see a warning when trying to register as a validator. To maintain network health there is a daily quota for validators to join the validator set. If you are not able to join, it could mean that today's quota of validators has already been added to the set. If you see this, you can try again later. Read [our blog post](https://aztec.network/blog/what-is-aztec-testnet) for more info. +Create a `docker-compose.yml` file in your `aztec-sequencer` directory: -::: +```yaml +services: + aztec-sequencer: + image: "aztecprotocol/aztec:latest" + 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} + P2P_IP: ${P2P_IP} + P2P_PORT: ${P2P_PORT} + AZTEC_PORT: ${AZTEC_PORT} + entrypoint: >- + node + --no-warnings + /usr/src/yarn-project/aztec/dest/bin/index.js + start + --node + --archiver + --sequencer + --network testnet + networks: + - aztec + restart: always + +networks: + aztec: + name: aztec +``` -## Advanced Configuration +**Note**: This configuration includes only essential settings. The `--network testnet` flag applies network-specific defaults. See the [CLI reference](../../reference/cli_reference.md) for all available options. -### Using Environment Variables +Start the sequencer: -Every flag in the `aztec start` command corresponds to an environment variable. You can see the variable names by running `aztec start --help`. A reference is provided [here](../../reference/cli_reference.md). +```sh +docker compose up -d +``` -For example: +## Verification -- `--l1-rpc-urls` maps to `ETHEREUM_HOSTS` -- `--l1-consensus-host-urls` maps to `L1_CONSENSUS_HOSTS_URLS` +To verify your sequencer is running correctly: -You can create a `.env` file with these variables: +1. Check the current sync status (this may take a few minutes): -```bash -ETHEREUM_HOSTS=https://example.com -L1_CONSENSUS_HOST_URLS=https://example.com -# Add other configuration variables as needed +```sh +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" ``` -Then source this file before running your command: +Compare the output with block explorers like [Aztec Scan](https://aztecscan.xyz/) or [Aztec Explorer](https://aztecexplorer.xyz/). -```bash -source .env -aztec start --network testnet --archiver --node --sequencer # other flags... -``` +2. View sequencer logs: -### Using a Docker Compose - -If you would like to run in a docker compose, you can use a configuration like the one below: +```sh +docker compose logs -f aztec-sequencer +``` -```yml -name: aztec-node -services: - node: - network_mode: host # Optional, run with host networking - image: aztecprotocol/aztec:latest - environment: - ETHEREUM_HOSTS: "" - L1_CONSENSUS_HOST_URLS: "" - DATA_DIRECTORY: /data - VALIDATOR_PRIVATE_KEY: $VALIDATOR_PRIVATE_KEY - P2P_IP: $P2P_IP - LOG_LEVEL: debug - entrypoint: > - sh -c 'node --no-warnings /usr/src/yarn-project/aztec/dest/bin/index.js start --network testnet start --node --archiver --sequencer' - ports: - - 40400:40400/tcp - - 40400:40400/udp - - 8080:8080 +3. Check node status: - volumes: - - /home/my-node/node:/data # Local directory +```sh +curl http://localhost:8080/status ``` ## Troubleshooting -### L1 Access +### Common Issues -If you're hosting your own Ethereum execution or consensus client locally (rather than using an external RPC like Alchemy), you need to ensure that the prover node inside Docker can reach it. +**Port forwarding not working:** -By default, Docker runs containers on a bridge network that isolates them from the host machine's network interfaces. This means localhost inside the container won't point to the host's localhost. +- Verify your external IP address matches the `P2P_IP` setting +- Check firewall rules on your router and local machine +- Test connectivity using: `nc -zv ` -To fix this: +**Sequencer not syncing:** -Option 1: Use the special hostname host.docker.internal -This tells Docker to route traffic from the container to the host machine. For example: +- Check L1 endpoint connectivity +- Verify both execution and consensus clients are fully synced +- Review logs for specific error messages -```bash ---l1-rpc-urls http://host.docker.internal:8545 -``` +**Keystore issues:** -Option 2: Add a host network entry to your Docker Compose file (advanced users) -This gives your container direct access to the host's network stack, but removes Docker's network isolation. Add to your `docker-compose.yml` +- Ensure keystore.json is properly formatted +- Verify private keys are valid Ethereum private keys +- Check file permissions on the keys directory -```yaml -network_mode: "host" -``` +**Docker issues:** -⚠️ Note: network_mode: "host" only works on Linux. On macOS and Windows, use `host.docker.internal`. +- Ensure Docker and Docker Compose are up to date +- Check disk space availability +- Verify container has sufficient resources -:::info +## Join the Sequencer Set -You can run your own Sepolia ETH Node. However, at the moment only [`geth`](https://github.com/ethereum/go-ethereum) and [`reth`](https://github.com/paradigmxyz/reth) nodes are confirmed to work reliably with the Aztec client. +After setting up your node, you must request to be added to the sequencer set. -::: +Complete the onboarding process at [testnet.aztec.network](https://testnet.aztec.network) using zkPassport. -Once you have your node running, head to the [Aztec Discord](https://discord.gg/aztec) to interact with other network operators. +## Next Steps -Happy sequencing! +- Monitor your sequencer's performance and attestation rate +- Join the [Aztec Discord](https://discord.gg/aztec) for operator support +- Review [Reacting to Upgrades](../../reference/reacting_to_upgrades.md) guide +- Consider implementing monitoring and alerting for production deployments diff --git a/docs/docs/the_aztec_network/guides/run_nodes/index.md b/docs/docs/the_aztec_network/guides/run_nodes/index.md index 0cb9469bccdd..59e8926f9623 100644 --- a/docs/docs/the_aztec_network/guides/run_nodes/index.md +++ b/docs/docs/the_aztec_network/guides/run_nodes/index.md @@ -8,20 +8,20 @@ description: Learn how to participate in the Aztec Network by running different ## Running Aztec Nodes
- +

Run Aztec Sequencer Nodes

 - Participate in the Aztec protocol as a sequencer that orders transactions in a block and proposed them to the L1. Runs on consumer hardware. + Participate in the Aztec protocol as a sequencer that orders transactions in blocks and proposes them to L1. Runs on consumer hardware. - +

Run Aztec Prover Nodes

 - Participate in the Aztec protocol as a prover, proving the rollup integrity that is pivotal to the protocol. Runs on hardware fit for data centers. + Participate in the Aztec protocol as a prover, generating proofs that ensure rollup integrity. Requires high-performance hardware suitable for data centers.
diff --git a/docs/docs/the_aztec_network/index.md b/docs/docs/the_aztec_network/index.md index 517502d8175f..669f75a6ba33 100644 --- a/docs/docs/the_aztec_network/index.md +++ b/docs/docs/the_aztec_network/index.md @@ -5,6 +5,8 @@ title: Running a Full Node description: A guide about how to run a full node on the Aztec network. --- +## Background + This guide will go over the steps required to run a full node on Aztec with a basic setup. A full node allows users to connect and interact with the network. It provides users an interface to send and receive transactions and state updates without relying on a third party. @@ -18,24 +20,24 @@ Please note that there are two other types of nodes available that we are not co Minimum hardware requirements: - 2 core / 4 vCPU -- 8 GB RAM -- 10 GB SDD +- 16 GB RAM +- 1 TB NVMe SDD - 25 Mbps network connection Please note that these requirements are subject to change as the network throughput increases. -Along with the above minimum hardware requirements, it is assumed that the user has access to a performant ethereum RPC endpoint. Furthermore, this guide expects the user to be using a "standard" Linux distribution like Debian / Ubuntu when following along with the steps. +Along with the above minimum hardware requirements, it is assumed that the user has access to a performant Ethereum RPC endpoint. Furthermore, this guide expects the user to be using a "standard" Linux distribution like Debian / Ubuntu when following along with the steps. -Overview +## Overview 1. Install Docker -2. Install aztec +2. Install Aztec 3. Configure the node 4. Start the node! ## Install and set up Docker -Please ensure that docker is installed. If not, here is a convenient way to install it. +Ensure Docker is installed. If not, here is a convenient way to install it. This uses the script at [https://get.docker.com/](https://get.docker.com/) to install the latest stable release of Docker on Linux: @@ -45,7 +47,7 @@ curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh ``` -Afterwards, the currently logged in user must be added to the docker group, so sudo is not needed to invoke docker. +Afterwards, the currently logged in user must be added to the docker group, so `sudo` is not needed to invoke docker. ```console sudo groupadd docker @@ -57,21 +59,21 @@ docker run hello-world ## Install Aztec -Run these commands to grab the aztec stack and add them to path. +Run these commands to grab the Aztec stack and add them to path. ```console bash -i <(curl -s https://install.aztec.network) # Users should check that it is installed by using ls ~/.aztec/bin -# aztec, aztec-up aztec-nargo and aztec-wallet should show up here +# aztec, aztec-up, aztec-nargo and aztec-wallet should show up here echo 'export PATH="$HOME/.aztec/bin:$PATH"' >> ~/.bashrc source ~/.bashrc ``` -The next step is to install the correct version of aztec that is running on testnet. The correct version of the aztec network currently is `1.2.0`. If that is not the version that was installed in the previous step, please run this to ensure the correct version is installed. +The next step is to install the correct version of aztec that is running on testnet. The correct version of the aztec network currently is #include_testnet_version. If that is not the version that was installed in the previous step, please run this to ensure the correct version is installed. ```console -aztec-up 1.2.0 +aztec-up #include_testnet_version ``` The user can confirm that they are running on the correct version with: @@ -88,17 +90,21 @@ Now that the correct version of the node is installed, it needs to be configured mkdir aztec-node && cd ./aztec-node ``` -Next, set some required configuration options. This guide will use `custom_named` environment variables (e.g. `AZTEC_NODE_P2P_IP`) but this is not necessary; you can pass valued directly into the command without specifying them as environment variables. The external IP address of the node, and the L1 RPC endpoints must be defined when starting a node. Also, configuration defining the network version should be set, as this will let the node define the other required protocol variables, like rollup address, registry address etc. Please note that the specified RPC endpoints must support high throughput, otherwise the node will suffer degraded performance. +Next, set some required configuration options. This guide will use `custom_named` environment variables (e.g. `AZTEC_NODE_P2P_IP`) but this is not necessary; you can pass values directly into the command without specifying them as environment variables. The external IP address of the node, and the L1 RPC endpoints must be defined when starting a node. Also, configuration defining the network version should be set, as this will let the node define the other required protocol variables, like rollup address, registry address etc. Note that the specified RPC endpoints must support high throughput, otherwise the node will suffer degraded performance. ```console -# If the external IP of the machine the node is running on is unknown, it can be obtained by running `curl ifconfig.me`. -export AZTEC_NODE_P2P_IP=IP export AZTEC_NODE_NETWORK=testnet +export AZTEC_NODE_P2P_IP=IP export AZTEC_NODE_ETH_HOSTS= export AZTEC_NODE_CONSENSUS_HOSTS= ``` -Finally, the ports used by the node must be accessible to other Aztec nodes on the internet. This will require disabling the firewall for and / or forwarding these ports. The router must be able to send UDP and TCP traffic on port 40400 (unless the defaults were changed) to the node IP address on its local network. Failure to do so may result in the node not participating in p2p duties. +:::tip + +The ports used by the node must be accessible to other Aztec nodes on the internet. This will require disabling the firewall for and / or forwarding these ports. The router must be able to send UDP and TCP traffic on port 40400 (unless the defaults were changed) to the node IP address on its local network. Failure to do so may result in the node not participating in p2p duties. + +Running the command `curl ipv4.icanhazip.com` can retrieve your public IP address for you. +::: ## Run the node @@ -110,16 +116,16 @@ To verify the node is working, run these commands in another terminal window: ```console # Rule 1: For HTTP traffic on port 8080 -curl -X POST --data '{"method": "node_getL2Tips"}' +curl -X POST http://localhost:8080 --data '{"method": "node_getL2Tips"}' # should return JSON data in the format of "{"result":{"latest":{"number":"...}}}" # Rule 2: For TCP traffic on port 40400 (set by default) -nc -vz IP 40400 -# should return "Connection to IP 40400 port [tcp/*] succeeded!" if port open +nc -vz [YOUR_EXTERNAL_IP] 40400 +# should return "Connection to [YOUR_EXTERNAL_IP] 40400 port [tcp/*] succeeded!" if port open # Rule 3: For UDP traffic on port 40400 (set by default) -nc - vu IP 40400 -# should return "Connection to IP 40400 port [udp/*] succeeded!" if port open +nc -vu [YOUR_EXTERNAL_IP] 40400 +# should return "Connection to [YOUR_EXTERNAL_IP] 40400 port [udp/*] succeeded!" if port open ``` Congrats, the node should be up, running, and connected to the network! diff --git a/docs/docs/the_aztec_network/reference/operator_faq.md b/docs/docs/the_aztec_network/reference/operator_faq.md index 3861c7a4c7ef..91561e5c7f83 100644 --- a/docs/docs/the_aztec_network/reference/operator_faq.md +++ b/docs/docs/the_aztec_network/reference/operator_faq.md @@ -16,9 +16,9 @@ Here is a list of common issues node operators may face. If you don't find your If it is regarding a beacon call, it has failed to the beacon rpc call. If it is regarding the execution endpoint, then it is likely just reporting. -## Update aztec alpha-testnet version +## Update aztec testnet version -To make sure you're using the latest version, run: `aztec-up alpha-testnet`, then restart your node. +To make sure you're using the latest version, run: `aztec-up latest`, then restart your node. ## "rpc rate", "quota limit" diff --git a/docs/docs/the_aztec_network/reference/reacting_to_upgrades.md b/docs/docs/the_aztec_network/reference/reacting_to_upgrades.md index a1507ceb843a..d272f1e69425 100644 --- a/docs/docs/the_aztec_network/reference/reacting_to_upgrades.md +++ b/docs/docs/the_aztec_network/reference/reacting_to_upgrades.md @@ -4,18 +4,89 @@ title: Reacting to Upgrades description: Learn how to react to upgrades on the Aztec network. --- -This is a guide for sequencer operators to understand how to react to protocol upgrades. To learn about how upgrades work, read the [concept section](../concepts/governance/upgrades.md). +This guide helps sequencer operators understand and respond to protocol upgrades on the Aztec network. -## Sequencers signal for governance upgrades +## Overview -To signal for governance upgrades, sequencers must set their `GOVERNANCE_PROPOSER_PAYLOAD` on their sequencer node to the address of a `payload`. This will register their signal with the GovernanceProposer contract. +Protocol upgrades on Aztec require coordination between sequencers to ensure smooth transitions. This process involves signaling support for upgrades and executing them once consensus is reached. -:::info -the `payload` is a contract on L1 that specifies the address of the new rollup contract to be upgraded to. The payloads to be voted on during alpha-testnet will be communicated to sequencers on the forum and on community channels like discord. -::: +## Signaling for Governance Upgrades + +Sequencers participate in governance by signaling support for proposed upgrades. + +### How to Signal -This signalling phase will pass once `N` sequencers in a round of `M` L2 blocks have signalled for the same payload. Once the quorum is met, anyone can call the `executeProposal(roundNumber)` function on the Governance Proposer contract to advance the upgrade into the next stage. +Set the `GOVERNANCE_PROPOSER_PAYLOAD` environment variable on your sequencer node to the address of the proposed `payload` contract. This registers your support with the GovernanceProposer contract. + +```sh +# Example: Set the governance payload in your environment +export GOVERNANCE_PROPOSER_PAYLOAD= + +# Restart your sequencer to apply the change +docker compose restart aztec-sequencer +``` :::info -The `N` and `M` are public variables on the Governance Proposer contract, and can be read by anyone (i.e. using a `cast call`). To get the round number, you can call the `computeRound(slotNumber)` on the Governance Proposer contract. +The `payload` is an L1 contract specifying the new rollup contract address for the upgrade. Payloads for voting during alpha-testnet are communicated through official channels including the forum and Discord. ::: + +### Quorum Requirements + +The signaling phase completes when: + +- `N` sequencers signal for the same payload +- Within a round of `M` L2 blocks + +Once quorum is reached, anyone can execute the proposal by calling `executeProposal(roundNumber)` on the Governance Proposer contract. + +## Monitoring Upgrades + +Stay informed about upcoming upgrades: + +1. **Monitor official channels:** + + - Aztec forum for formal proposals + - Discord for discussions and announcements + - GitHub for technical details + +2. **Check upgrade status:** + - Query the Governance Proposer contract for active proposals + - Monitor signaling progress toward quorum + - Track execution status + +## Post-Upgrade Actions + +After an upgrade executes: + +1. **Verify your node updates automatically** - The auto-update module should handle this +2. **Monitor logs** for any issues during the transition +3. **Confirm your sequencer reconnects** to the network successfully +4. **Resume normal operations** once synchronized + +## Troubleshooting + +### Common Issues + +**Node not updating after upgrade:** + +- Verify auto-update is enabled (check `AUTO_UPDATE` is not set) +- Ensure Watchtower is running for automatic container updates +- Manually pull latest image if needed: `docker pull aztecprotocol/aztec:latest` + +**Sequencer not reconnecting:** + +- Check network configuration matches new requirements +- Review logs for connection errors +- Verify L1 endpoints are accessible + +**Missing governance signals:** + +- Confirm `GOVERNANCE_PROPOSER_PAYLOAD` is set correctly +- Restart sequencer after setting environment variable +- Verify transaction was sent to L1 + +## Next Steps + +- Join the [governance forum](https://forum.aztec.network) to participate in discussions +- Review the [Sequencer Guide](../guides/run_nodes/how_to_run_sequencer.md) for setup details +- Monitor the [Aztec Discord](https://discord.gg/aztec) for real-time updates diff --git a/docs/docs/the_aztec_network/reference/useful_commands.md b/docs/docs/the_aztec_network/reference/useful_commands.md index bac4ea535565..1148a0127900 100644 --- a/docs/docs/the_aztec_network/reference/useful_commands.md +++ b/docs/docs/the_aztec_network/reference/useful_commands.md @@ -9,7 +9,7 @@ These commands are useful to sequencer operators. If you're trying to do somethi ## Prerequisites - You'll need a way to query the L1 contracts, this guide assumes you have `foundry` installed. -- Have the `aztec` tool [installed](../../developers/getting_started/getting_started_on_sandbox.md#install-the-sandbox) +- Have the `aztec` tool [installed](../../developers/getting_started/getting_started.md#install-the-sandbox) - Ethereum EL RPC endpoint ## Basics @@ -18,7 +18,7 @@ These commands are useful to sequencer operators. If you're trying to do somethi The Registry contract is your entrypoint into almost all other contracts for a particular deployment of the Aztec Network. Armed with this address, you can retrieve almost all other useful contracts. -Assume there are two "deployments" of Aztec i.e. an `alpha-testnet` and a `ignition-testnet`. Then each deployment will have a unique Registry contract that does not change with upgrades. If a governance upgrade on `alpha-testnet` deploys a new rollup contract, the Registry contract for the `alpha-testnet` deployment will not change. +Assume there are two "deployments" of Aztec i.e. an `testnet` and a `ignition-testnet`. Then each deployment will have a unique Registry contract that does not change with upgrades. If a governance upgrade on `testnet` deploys a new rollup contract, the Registry contract for the `testnet` deployment will not change. @@ -34,9 +34,9 @@ cast call "getCanonicalRollup()" --rpc-url https://exa The rest of the guide will omit the `--rpc-url` flag for legibility. ::: -## Query the Validator Set +## Query the Sequencer Set -### Retrieve a list of all validators +### Retrieve a list of all sequencers Run @@ -44,22 +44,22 @@ Run cast call "getAttesters()" --rpc-url ``` -### What is the status of a particular validator? +### What is the status of a particular sequencer? Run ```bash -cast call "getInfo(address)" +cast call "getInfo(address)" ``` -This will return in order: 1) the validator's balance 2) their `withdrawer` address 3) their `proposer` address and 4) their current status. +This will return in order: 1) the sequencer's balance 2) their `withdrawer` address 3) their `proposer` address and 4) their current status. | Status | Meaning | | ------ | -------------------------------------------------------------------------------------------------------------------- | -| 0 | The validator is not in the validator set | -| 1 | The validator is currently in the validator set. | -| 2 | The validator is not active in the set. This could mean that they initiated a withdrawal and are awaiting final exit | -| 3 | The validator has completed their exit delay and can be exited from the validator set | +| 0 | The sequencer is not in the sequencer set | +| 1 | The sequencer is currently in the sequencer set. | +| 2 | The sequencer is not active in the set. This could mean that they initiated a withdrawal and are awaiting final exit | +| 3 | The sequencer has completed their exit delay and can be exited from the sequencer set | ## Governance Upgrades diff --git a/docs/versioned_docs/version-v2.0.1/the_aztec_network/guides/run_nodes/how_to_run_prover.md b/docs/versioned_docs/version-v2.0.1/the_aztec_network/guides/run_nodes/how_to_run_prover.md index 8660b2902c51..e68abd8ddfd7 100644 --- a/docs/versioned_docs/version-v2.0.1/the_aztec_network/guides/run_nodes/how_to_run_prover.md +++ b/docs/versioned_docs/version-v2.0.1/the_aztec_network/guides/run_nodes/how_to_run_prover.md @@ -1,6 +1,6 @@ --- sidebar_position: 3 -title: How to Run a Prover Node +title: How to Run an Aztec Prover description: A comprehensive guide to setting up and running an Aztec Prover node on testnet or mainnet, including hardware requirements, configuration options, and performance optimization tips. keywords: [ @@ -23,115 +23,274 @@ tags: - infrastructure --- -import { AztecTestnetVersion } from '@site/src/components/Snippets/general_snippets'; - ## Background -Prover nodes are a critical part of the Aztec network's infrastructure. They generate cryptographic proofs that attest to the correctness of public transactions, ultimately producing a single rollup proof that is submitted to Ethereum. +This guide covers the steps required to run a prover on the Aztec network. Before you begin, you should understand that operating a prover is a resource-intensive role typically undertaken by experienced engineers due to its technical complexity and hardware requirements. -Operating a prover node requires a solid grasp of blockchain protocols, cryptographic systems, DevOps best practices, and high-performance hardware. It’s a resource-intensive role typically undertaken by experienced engineers or specialized teams due to its technical and operational complexity. +Aztec provers are critical infrastructure components that generate cryptographic proofs attesting to transaction correctness, ultimately producing a single rollup proof submitted to Ethereum. -## Prerequisites +The prover consists of three main components: -Before following this guide, make sure you: +1. **Prover node**: Polls L1 for unproven epochs, creates proving jobs, distributes them to the broker, and submits the final rollup proof to the rollup contract. -- Have the `aztec` tool [installed](../../../developers/getting_started/getting_started_on_sandbox.md#install-the-sandbox) -- Have sufficient hardware resources for proving operations -- Your confidence level is expected to be around "I'd be able to run a Prover _without_ this guide" +2. **Prover broker**: Manages the job queue, distributing work to agents and collecting results. -## Understanding Prover Architecture +3. **Prover agent(s)**: Executes proof generation jobs in a stateless manner. -The Aztec prover involves three key components: the Prover Node, the Proving Broker, and the Proving Agent. +## Prerequisites + +The minimum hardware specifications for each of the components is listed below. #### Prover Node -The Prover Node is responsible for polling the L1 for unproven epochs and initiating the proof process. When an epoch is ready to be proven, the prover node creates proving jobs and distributes them to the broker. The Prover Node is also responsible for submitting the final rollup proof to the rollup contract. +Minimum specifications: -- **Resources**: Up to 8 cores, 16GB RAM, ~1TB disk for storing state. +- 2 core / 4 vCPU +- 16 GB RAM +- 1 TB NVMe SSD +- 25 Mbps network connection #### Proving Broker -Manages a queue of proving jobs, distributing them to available agents and forwarding results back to the node. +Minimum specifications: -- **Resources**: Up to 4 cores, 16GB RAM, ~1GB disk. +- 2 core / 4 vCPU +- 16 GB RAM +- 10 GB SSD #### Proving Agents -Executes the actual proof jobs. Agents are stateless, fetch work from the broker, and return the results. +Minimum specifications: + +- 32 core / 64 vCPU +- 128 GB RAM +- 10 GB SSD + +This guide outlines a basic, non-distributed setup with all components on a single machine. Your hardware must meet or exceed the proving agent requirements listed above. + +This guide assumes you are using a standard Linux distribution (Debian or Ubuntu). + +### Required Software + +- Docker and the Aztec toolchain installed via aztec-up (see the [getting started section](../../index.md)) +- Docker Compose ([installation guide](https://docs.docker.com/compose/install/)) +- Access to L1 node endpoints (execution and consensus clients). See [Eth Docker's guide](https://ethdocker.com/Usage/QuickStart) if you need to set these up. + +## Configure the Prover + +Setting up a prover involves configuring three components through environment variables and Docker Compose. + +### Setup Steps + +1. Configure components via environment variables +2. Enable auto-update and auto-restart functionality +3. Deploy with Docker Compose + +First, create the directory structure for prover data storage: + +```sh +mkdir -p aztec-prover/prover-node-data aztec-prover/prover-broker-data +cd aztec-prover +touch .env +``` + +### Component Configuration -- **Resources**: Each agent may use up to 16 cores and 128GB RAM. +Each prover component requires specific environment variables. Configure them as follows: + +#### Prover Node + +Required environment variables: + +- `DATA_DIRECTORY`: the folder where the data of the prover node is stored +- `P2P_IP`: the IP address of this prover node +- `P2P_PORT`: the port that P2P communication happens on +- `ETHEREUM_HOSTS`: the execution RPC endpoints +- `L1_CONSENSUS_HOST_URLS`: the consensus RPC endpoints +- `LOG_LEVEL`: the desired level of logging for the prover node. It defaults to `INFO` +- `PROVER_BROKER_HOST`: the endpoint of the prover broker that this node sends prover jobs to +- `PROVER_PUBLISHER_PRIVATE_KEY`: the private key of the Ethereum EOA used for publishing the proofs to L1 +- `AZTEC_PORT`: the port that the prover node API is exposed on + +Add the following to your `.env` file (assuming default ports of 8080 for the prover node, and 40400 for p2p connectivity): + +```sh +DATA_DIRECTORY=./prover-node-data +P2P_IP= +P2P_PORT=40400 +ETHEREUM_HOSTS= +L1_CONSENSUS_HOST_URLS= +LOG_LEVEL=info +PROVER_BROKER_HOST=http://prover-broker:8080 +PROVER_PUBLISHER_PRIVATE_KEY= +AZTEC_PORT=8080 +``` + +**Note**: The broker URL `http://prover-broker:8080` references the Docker Compose service name defined later. + +:::tip +You MUST forward ports for P2P connectivity. Configure your router to forward both UDP and TCP traffic on the port specified by `P2P_PORT` to your local IP address. + +To find your public IP address, run: `curl ipv4.icanhazip.com` +::: + +#### Prover Broker + +Required environment variables: + +- `DATA_DIRECTORY`: the folder where the data of the prover broker is stored +- `LOG_LEVEL`: the desired level of logging for the prover broker. It defaults to `INFO` +- `ETHEREUM_HOSTS`: the execution RPC endpoints +- `P2P_IP`: the IP address of this prover broker +- `P2P_PORT`: the port that P2P communication happens on + +**Note**: Some variables overlap with the prover node configuration. If running components on separate machines, adjust accordingly. Since `DATA_DIRECTORY` is used by both components, define a separate variable for the broker: + +Add to your `.env` file: + +```sh +PROVER_BROKER_DATA_DIRECTORY=./prover-broker-data +``` -## Setting Up Your Prover +#### Prover Agent -### Using Docker Compose +Required environment variables: + +- `PROVER_AGENT_COUNT`: Number of agents to run (each requires ~10GB RAM) +- `PROVER_AGENT_POLL_INTERVAL_MS`: Polling interval for job requests (milliseconds) +- `PROVER_BROKER_HOST`: Broker endpoint for job submission +- `PROVER_ID`: Ethereum address corresponding to `PROVER_PUBLISHER_PRIVATE_KEY` + +**Note**: Some variables overlap with the prover node configuration. In this case we use the same value for `PROVER_BROKER_HOST`, so we will not duplicate it in our `.env` file. + +Add to your `.env` file: + +```sh +PROVER_AGENT_COUNT=10 +PROVER_AGENT_POLL_INTERVAL_MS=10000 +PROVER_ID= +``` + +### Enable Auto-Update and Auto-Restart + +The prover's auto-update functionality is critical for network coordination. This background module enables: + +- Configuration updates across all nodes +- Automated image updates via controlled shutdowns +- Rapid hot-fix deployment +- Coordinated resets after governance upgrades + +**Important**: Do NOT set `AUTO_UPDATE_URL` or `AUTO_UPDATE` environment variables. These must use their default values for proper operation. + +Since Docker Compose doesn't respect pull policies on container restarts, install Watchtower for automatic updates: + +```sh +docker run -d \ + --name watchtower \ + -v /var/run/docker.sock:/var/run/docker.sock \ + containrrr/watchtower +``` + +### Deploy with Docker Compose + +Create a `docker-compose.yml` file in your `aztec-prover` directory with the following content: ```yml name: aztec-prover services: prover-node: - image: aztecprotocol/aztec:latest # Always refer to the docs to check that you're using the correct image. - command: - - node - - --no-warnings - - /usr/src/yarn-project/aztec/dest/bin/index.js - - start - - --prover-node - - --archiver - - --network - - alpha-testnet + image: aztecprotocol/aztec:latest + entrypoint: >- + node + --no-warnings + /usr/src/yarn-project/aztec/dest/bin/index.js + start + --prover-node + --archiver + --network testnet depends_on: - broker: + prover-broker: condition: service_started required: true environment: - # PROVER_COORDINATION_NODE_URL: "http://:8080" # this can point to your own validator - using this replaces the need for the prover node to be on the P2P network and uses your validator as a sentry node of some sort. - # P2P_ENABLED: "false" # Switch to false if you provide a PROVER_COORDINATION_NODE_URL - DATA_DIRECTORY: /data - DATA_STORE_MAP_SIZE_KB: "134217728" - ETHEREUM_HOSTS: # EL RPC endpoint - L1_CONSENSUS_HOST_URLS: # CL RPC endpoint - LOG_LEVEL: info - PROVER_BROKER_HOST: http://broker:8080 - PROVER_PUBLISHER_PRIVATE_KEY: # The node needs to publish proofs to L1. Replace with your private key + DATA_DIRECTORY: /var/lib/data + ETHEREUM_HOSTS: ${ETHEREUM_HOSTS} + L1_CONSENSUS_HOST_URLS: ${L1_CONSENSUS_HOST_URLS} + LOG_LEVEL: ${LOG_LEVEL} + PROVER_BROKER_HOST: ${PROVER_BROKER_HOST} + PROVER_PUBLISHER_PRIVATE_KEY: ${PROVER_PUBLISHER_PRIVATE_KEY} + P2P_IP: ${P2P_IP} + P2P_PORT: ${P2P_PORT} + AZTEC_PORT: ${AZTEC_PORT} ports: - - "8080:8080" - - "40400:40400" - - "40400:40400/udp" + - ${AZTEC_PORT}:${AZTEC_PORT} + - ${P2P_PORT}:${P2P_PORT} + - ${P2P_PORT}:${P2P_PORT}/udp volumes: - - /home/my-node/node:/data # Local directory - - agent: - image: aztecprotocol/aztec:latest # Always refer to the docs to check that you're using the correct image. - command: - - node - - --no-warnings - - /usr/src/yarn-project/aztec/dest/bin/index.js - - start - - --prover-agent - - --network - - alpha-testnet + - ${DATA_DIRECTORY}:/var/lib/data + + prover-broker: + image: aztecprotocol/aztec:latest + entrypoint: >- + node + --no-warnings + /usr/src/yarn-project/aztec/dest/bin/index.js + start + --prover-broker + --network testnet environment: - PROVER_AGENT_COUNT: "1" - PROVER_AGENT_POLL_INTERVAL_MS: "10000" # Just to reduce the log spamming if you're using debug logging. - PROVER_BROKER_HOST: http://broker:8080 - PROVER_ID: # this should be the address corresponding to the PROVER_PUBLISHER_PRIVATE_KEY you set on the node. + DATA_DIRECTORY: /var/lib/data + ETHEREUM_HOSTS: ${ETHEREUM_HOSTS} + P2P_IP: ${P2P_IP} + LOG_LEVEL: ${LOG_LEVEL} + volumes: + - ${PROVER_BROKER_DATA_DIRECTORY}:/var/lib/data + + prover-agent: + image: aztecprotocol/aztec:latest + entrypoint: >- + node + --no-warnings + /usr/src/yarn-project/aztec/dest/bin/index.js + start + --prover-agent + --network testnet + environment: + PROVER_AGENT_COUNT: ${PROVER_AGENT_COUNT} + PROVER_AGENT_POLL_INTERVAL_MS: ${PROVER_AGENT_POLL_INTERVAL_MS} + PROVER_BROKER_HOST: ${PROVER_BROKER_HOST} + PROVER_ID: ${PROVER_ID} pull_policy: always restart: unless-stopped +``` - broker: - image: aztecprotocol/aztec:latest # Always refer to the docs to check that you're using the correct image. - command: - - node - - --no-warnings - - /usr/src/yarn-project/aztec/dest/bin/index.js - - start - - --prover-broker - - --network - - alpha-testnet - environment: - DATA_DIRECTORY: /data - ETHEREUM_HOSTS: # Your EL RPC endpoint - LOG_LEVEL: info - volumes: - - /home/my-node/node:/data # Local directory +**Note**: This configuration includes only essential settings. The `--network testnet` flag applies network-specific defaults. See the [CLI reference](../../reference/cli_reference.md) for all available options. + +Start the prover: + +```sh +docker compose up -d +``` + +## Verification + +To verify your prover is running correctly: + +1. Check that all services are running: + +```sh +docker compose ps +``` + +2. View logs for each component: + +```sh +# Prover node logs +docker compose logs -f prover-node + +# Broker logs +docker compose logs -f prover-broker + +# Agent logs +docker compose logs -f prover-agent ``` diff --git a/docs/versioned_docs/version-v2.0.1/the_aztec_network/guides/run_nodes/how_to_run_sequencer.md b/docs/versioned_docs/version-v2.0.1/the_aztec_network/guides/run_nodes/how_to_run_sequencer.md index 7b91300e317a..917dd59e1e1f 100644 --- a/docs/versioned_docs/version-v2.0.1/the_aztec_network/guides/run_nodes/how_to_run_sequencer.md +++ b/docs/versioned_docs/version-v2.0.1/the_aztec_network/guides/run_nodes/how_to_run_sequencer.md @@ -24,280 +24,253 @@ tags: ## Background +This guide covers the steps required to run a sequencer node on the Aztec network. + The Aztec sequencer node is critical infrastructure responsible for ordering transactions and producing blocks. -The sequencer node takes part in three key actions: +The sequencer node performs three key actions: -1. Assemble unprocessed transactions and propose the next block -2. Attest to correct execution of txs in the proposed block (if part of validator committee) -3. Submit the successfully attested block to L1 +1. Assembles unprocessed transactions and proposes the next block +2. Attests to correct execution of transactions in proposed blocks (when part of the sequencer committee) +3. Submits successfully attested blocks to L1 -When transactions are sent to the Aztec network, sequencer nodes bundles them into blocks, checking various constraints such as gas limits, block size, and transaction validity. Before a block can be published, it must be validated by a committee of other sequencer nodes (validators in this context) who re-execute public transactions and verify private function proofs so they can attest to correct execution. These validators attest to the block's validity by signing it, and once enough attestations are collected (two-thirds of the committee plus one), the sequencer can submit the block to L1. +Sequencer nodes bundle transactions into blocks while checking constraints like gas limits, block size, and validity. 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. The archiver component complements this process by maintaining historical chain data. It continuously monitors L1 for new blocks, processes them, and maintains a synchronized view of the chain state. This includes managing contract data, transaction logs, and L1-to-L2 messages, making it essential for network synchronization and data availability. -## Setup - -### Requirements - -A computer running Linux or MacOS with the following specifictions: - -- CPU: 8-cores -- RAM: 16 GiB -- Storage: 1 TB SSD +## Prerequisites -A Network connection of at least 25 Mbps up/down. +Minimum hardware requirements: -### Installation +- 2 core / 4 vCPU +- 16 GB RAM +- 1TB NVMe SSD +- 25 Mbps network connection -import { General, Fees } from '@site/src/components/Snippets/general_snippets'; +Please note that these requirements are subject to change as the network throughput increases. - +This guide assumes you are using a standard Linux distribution (Debian or Ubuntu). -Now install the latest testnet version of aztec: `aztec-up -v latest` +### Required Software -Join the [Discord](https://discord.gg/aztec) to connect with the community and get help with your setup. +- Docker and the Aztec toolchain installed via aztec-up (see the [getting started section](../../index.md)) +- Docker Compose ([installation guide](https://docs.docker.com/compose/install/)) +- Access to L1 node endpoints (execution and consensus clients). See [Eth Docker's guide](https://ethdocker.com/Usage/QuickStart) if you need to set these up. -## Sequencer Quickstart +## Configure the Sequencer -With the alpha-testnet version of the aztec tools, you now need to define required variables for your node. +Setting up a sequencer involves configuring keys, environment variables, and Docker Compose. -The following variable names are specific to the `aztec start` command, set them as variables in the terminal or inline before the command. +### Setup Steps -- `ETHEREUM_HOSTS=`: One or more comma-separated public rpc provider url(s). NB - don't share your access token -- `L1_CONSENSUS_HOST_URLS=`: One or more comma-separated public rpc provider url(s) that supports consensus client requests -- `VALIDATOR_PRIVATE_KEY="Ox"`: Private key of testnet L1 EOA that holds Sepolia ETH (0.01 Sepolia ETH can get you started) -- `COINBASE="0x"`: Recipient of block rewards (for node security on mainnet, this should be a different address to the validator eoa) -- `P2P_IP="x.x.x.x"`: IP address of computer running the node (you can get this by running, `curl api.ipify.org`, on your node) +1. Define private keys and accounts for sequencer duties +2. Configure node settings via environment variables +3. Enable auto-update and auto-restart functionality +4. Deploy with Docker Compose -Now in a terminal start your node as a sequencer and archiver: +First, create the directory structure for sequencer data storage: -If the above variables are set you can simply use: `aztec start --node --archiver --sequencer --network testnet` - -Otherwise you can specify values via the CLI flags (using values in place of the variable names): - -```bash -aztec start --node --archiver --sequencer \ - --network testnet \ - --l1-rpc-urls $ETHEREUM_HOSTS \ - --l1-consensus-host-urls $L1_CONSENSUS_HOST_URLS \ - --sequencer.validatorPrivateKeys $VALIDATOR_PRIVATE_KEY \ - --sequencer.coinbase $COINBASE \ - --p2p.p2pIp $P2P_IP +```sh +mkdir -p aztec-sequencer/keys aztec-sequencer/data +cd aztec-sequencer +touch .env ``` -**Additional Parameters**: The comprehensive list of parameters can be seen via: `aztec help start`. For example: +### Define Private Keys and Accounts -``` ---p2p.p2pPort (default: 40400) ($P2P_PORT) - The port for the P2P service. -``` +Sequencers require private keys to identify themselves as valid proposers or attesters. Configure these through a keystore file. -### Port forwarding +Create a `keystore.json` file in your `aztec-sequencer/keys` folder: -For some restricted environments, you may need to explicity forward the p2p port (default: 40400) to your local node ip address. - -This is often in a router's advanced network settings if required. - -### Next steps - -To add your sequencer you'll need the following few values, as well as `ETHEREUM_HOSTS` from before: - -- `STAKING_ASSET_HANDLER="0xF739D03e98e23A7B65940848aBA8921fF3bAc4b2"`: Constant L1 contract address -- `L1_CHAIN_ID="11155111"`: Sepolia chainid -- `PRIVATE_KEY="0x`: private key of account with sepolia eth to make transaction (eg can use funded validator key) - -Then run the aztec command to add your address as an L1 validator, with rpc url(s) for Etheruem L1 execution requests: - -```bash -aztec add-l1-validator --staking-asset-handler=0xF739D03e98e23A7B65940848aBA8921fF3bAc4b2 \ - --l1-rpc-urls $ETHEREUM_HOSTS \ - --l1-chain-id 11155111 \ - --private-key "0x" \ - --attester "0x" \ - --proposer-eoa "0x" +```json +{ + "schemaVersion": 1, + "validators": [ + { + "attester": ["ETH_PRIVATE_KEY_0"], + "publisher": ["ETH_PRIVATE_KEY_1"], + "coinbase": "ETH_ADDRESS_2", + "feeRecipient": "AZTEC_ADDRESS_0" + } + ] +} ``` -**Tip**: Use `aztec help add-l1-validator` for further parameter details. - -:::note Validator Quota Filled - -In the absence of real-world staking incentives, becoming a validator is throttled with time, so you may see `ValidatorQuotaFilledUntil(uint256 _timestamp)` at the beginning of the text returned. - -The timestamp is when the next round of sequencers can be added as validators, so try again right after that. - -::: - -## Deeper dive - -This guide will describe how to setup your sequencer using the `aztec start` command. For more advanced setups, refer to the Advanced Configuration section below. - -The `aztec start` tool is a one-stop-shop for running your sequencer on any Aztec Network. It assigns default values to several config variables based on a `--network` flag and launches a docker container running the sequencer software. - -To use the `aztec start` command, you need to obtain the following: - -#### RPCs - -- An L1 execution client (for reading transactions and state). It can be specified via the `--l1-rpc-urls` flag when using `aztec start` or via the env var `ETHEREUM_HOSTS`. Popular execution clients include [Geth](https://geth.ethereum.org/) or [Nethermind](https://nethermind.io/). You can run your own node or use a service like [Alchemy](https://www.alchemy.com/) or [Infura](https://www.infura.io/). - -- An L1 consensus client (for blobs). It can be specified via the `--l1-consensus-host-urls` flag when using `aztec start` or via the env var `L1_CONSENSUS_HOST_URLS`. Popular consensus clients include [Lighthouse](https://lighthouse.sigmaprime.io/) or [Prysm](https://prysmaticlabs.com/). Not all RPC providers support consensus endpoints, [Quicknode](https://www.quicknode.com/) and [dRPC](https://drpc.org/) have been known to work for consensus endpoints. - -- To reduce load on your consensus endpoint, the Aztec sequencer supports an optional remote server that serves blobs to the client. This is often called a "blob sink" or "blob storage service". You can pass your own or use one provided by a trusted party via the `--sequencer.blobSinkUrl` flag when using `aztec start`, or via the env var `BLOB_SINK_URL`. Some providers like [Alchemy](https://www.alchemy.com/) offer blob storage services as part of their infrastructure offerings. - -#### Ethereum Keys +The keystore defines keys and addresses for sequencer operation: -You will need an Ethereum private key and the corresponding public address. The private key is set via the `--sequencer.validatorPrivateKeys` flag while the public address should be specified via the `--sequencer.coinbase ` flag. +- `attester`: Private key for signing block proposals and attestations. The corresponding Ethereum address identifies the sequencer. +- `publisher`: Private key for sending block proposals to L1. Defaults to attester key if not set. +- `coinbase`: Ethereum address receiving L1 rewards and fees. Defaults to attester address if not set. +- `feeRecipient`: Aztec address receiving unburnt transaction fees from blocks. -The private key is needed as your validator will post blocks to Ethereum, and the public address will be the recipient of any block rewards. +Replace the placeholder values with your actual keys and addresses. -Disclaimer: you may want to generate and use a new Ethereum private key. +### Node Configuration -#### Networking +Required environment variables: -You MUST forward your ports. Your router must send UDP and TCP traffic on port `40400` (unless you changed the default) to your IP address on your local network. Failure to do so may result in your sequencer not participating on the p2p network. +- `DATA_DIRECTORY`: the folder where the data of the sequencer is stored +- `KEY_STORE_DIRECTORY`: can be a path to the file or directory where keystores are located. In our case it is the path to the folder containing the `keystore.json` file created above +- `LOG_LEVEL`: the desired level of logging for the sequencer. It defaults to `INFO`. +- `ETHEREUM_HOSTS`: The execution RPC endpoints +- `L1_CONSENSUS_HOST_URLS`: The consensus RPC endpoints +- `P2P_IP`: The IP address of this sequencer +- `P2P_PORT`: The port that P2P communication happens on +- `AZTEC_PORT`: The port that the sequencer node API is exposed on -As a tip, configure your router to give your MAC address the same IP address every time it does a DHCP refresh. +Add the following to your `.env` file (using default ports 8080 and 40400): -You also need to grab your external IP address and pass it along to the `--p2p.p2pIp` when using `aztec start`. - -#### Sepolia ETH - -You'll need Sepolia ETH to cover gas costs. Here are some options: - -- Use a PoW faucet like [Sepolia PoW Faucet](https://sepolia-faucet.pk910.de/) -- Ask in our Discord community (and remember to pay it forward when you can!) - -### Now Start Your Sequencer - -To boot up a sequencer using `aztec start`, run the following command: - -```bash -aztec start --node --archiver --sequencer \ - --network testnet \ - --l1-rpc-urls https://example.com \ - --l1-consensus-host-urls https://example.com \ - --sequencer.validatorPrivateKeys 0xYourPrivateKey \ - --sequencer.coinbase 0xYourAddress \ - --p2p.p2pIp 999.99.999.99 \ - --p2p.maxTxPoolSize 1000000000 +```sh +DATA_DIRECTORY=./data +KEY_STORE_DIRECTORY=./keys +LOG_LEVEL=info +ETHEREUM_HOSTS= +L1_CONSENSUS_HOST_URLS= +P2P_IP= +P2P_PORT=40400 +AZTEC_PORT=8080 ``` :::tip +You MUST forward ports for P2P connectivity. Configure your router to forward both UDP and TCP traffic on the port specified by `P2P_PORT` to your local IP address. -For a full overview of all available commands, check out the [CLI reference sheet](../../reference/cli_reference.md). +To find your public IP address, run: `curl ipv4.icanhazip.com` ::: -:::tip +### Enable Auto-Update and Auto-Restart -If you are unable to determine your public ip. Running the command `curl ipv4.icanhazip.com` can retrieve it for you. -::: +The sequencer's auto-update functionality is critical for network coordination. This background module enables: + +- Configuration updates across all nodes +- Automated image updates via controlled shutdowns +- Rapid hot-fix deployment +- Coordinated resets after governance upgrades -### Register as a Validator +**Important**: Do NOT set `AUTO_UPDATE_URL` or `AUTO_UPDATE` environment variables. These must use their default values for proper operation. -Once your node is fully synced, you can register as a validator using the `add-l1-validator` command: +Since Docker Compose doesn't respect pull policies on container restarts, install Watchtower for automatic updates: -```bash -aztec add-l1-validator \ - --l1-rpc-urls https://eth-sepolia.g.example.com/example/your-key \ - --private-key your-private-key \ - --attester your-validator-address \ - --proposer-eoa your-validator-address \ - --staking-asset-handler 0xF739D03e98e23A7B65940848aBA8921fF3bAc4b2 \ - --l1-chain-id 11155111 +```sh +docker run -d \ + --name watchtower \ + -v /var/run/docker.sock:/var/run/docker.sock \ + containrrr/watchtower ``` -:::warning +### Deploy with Docker Compose -You may see a warning when trying to register as a validator. To maintain network health there is a daily quota for validators to join the validator set. If you are not able to join, it could mean that today's quota of validators has already been added to the set. If you see this, you can try again later. Read [our blog post](https://aztec.network/blog/what-is-aztec-testnet) for more info. +Create a `docker-compose.yml` file in your `aztec-sequencer` directory: -::: +```yaml +services: + aztec-sequencer: + image: "aztecprotocol/aztec:latest" + 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} + P2P_IP: ${P2P_IP} + P2P_PORT: ${P2P_PORT} + AZTEC_PORT: ${AZTEC_PORT} + entrypoint: >- + node + --no-warnings + /usr/src/yarn-project/aztec/dest/bin/index.js + start + --node + --archiver + --sequencer + --network testnet + networks: + - aztec + restart: always + +networks: + aztec: + name: aztec +``` -## Advanced Configuration +**Note**: This configuration includes only essential settings. The `--network testnet` flag applies network-specific defaults. See the [CLI reference](../../reference/cli_reference.md) for all available options. -### Using Environment Variables +Start the sequencer: -Every flag in the `aztec start` command corresponds to an environment variable. You can see the variable names by running `aztec start --help`. A reference is provided [here](../../reference/cli_reference.md). +```sh +docker compose up -d +``` -For example: +## Verification -- `--l1-rpc-urls` maps to `ETHEREUM_HOSTS` -- `--l1-consensus-host-urls` maps to `L1_CONSENSUS_HOSTS_URLS` +To verify your sequencer is running correctly: -You can create a `.env` file with these variables: +1. Check the current sync status (this may take a few minutes): -```bash -ETHEREUM_HOSTS=https://example.com -L1_CONSENSUS_HOST_URLS=https://example.com -# Add other configuration variables as needed +```sh +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" ``` -Then source this file before running your command: +Compare the output with block explorers like [Aztec Scan](https://aztecscan.xyz/) or [Aztec Explorer](https://aztecexplorer.xyz/). -```bash -source .env -aztec start --network testnet --archiver --node --sequencer # other flags... -``` +2. View sequencer logs: -### Using a Docker Compose - -If you would like to run in a docker compose, you can use a configuration like the one below: +```sh +docker compose logs -f aztec-sequencer +``` -```yml -name: aztec-node -services: - node: - network_mode: host # Optional, run with host networking - image: aztecprotocol/aztec:latest - environment: - ETHEREUM_HOSTS: "" - L1_CONSENSUS_HOST_URLS: "" - DATA_DIRECTORY: /data - VALIDATOR_PRIVATE_KEY: $VALIDATOR_PRIVATE_KEY - P2P_IP: $P2P_IP - LOG_LEVEL: debug - entrypoint: > - sh -c 'node --no-warnings /usr/src/yarn-project/aztec/dest/bin/index.js start --network testnet start --node --archiver --sequencer' - ports: - - 40400:40400/tcp - - 40400:40400/udp - - 8080:8080 +3. Check node status: - volumes: - - /home/my-node/node:/data # Local directory +```sh +curl http://localhost:8080/status ``` ## Troubleshooting -### L1 Access +### Common Issues -If you're hosting your own Ethereum execution or consensus client locally (rather than using an external RPC like Alchemy), you need to ensure that the prover node inside Docker can reach it. +**Port forwarding not working:** -By default, Docker runs containers on a bridge network that isolates them from the host machine's network interfaces. This means localhost inside the container won't point to the host's localhost. +- Verify your external IP address matches the `P2P_IP` setting +- Check firewall rules on your router and local machine +- Test connectivity using: `nc -zv ` -To fix this: +**Sequencer not syncing:** -Option 1: Use the special hostname host.docker.internal -This tells Docker to route traffic from the container to the host machine. For example: +- Check L1 endpoint connectivity +- Verify both execution and consensus clients are fully synced +- Review logs for specific error messages -```bash ---l1-rpc-urls http://host.docker.internal:8545 -``` +**Keystore issues:** -Option 2: Add a host network entry to your Docker Compose file (advanced users) -This gives your container direct access to the host's network stack, but removes Docker's network isolation. Add to your `docker-compose.yml` +- Ensure keystore.json is properly formatted +- Verify private keys are valid Ethereum private keys +- Check file permissions on the keys directory -```yaml -network_mode: "host" -``` +**Docker issues:** -⚠️ Note: network_mode: "host" only works on Linux. On macOS and Windows, use `host.docker.internal`. +- Ensure Docker and Docker Compose are up to date +- Check disk space availability +- Verify container has sufficient resources -:::info +## Join the Sequencer Set -You can run your own Sepolia ETH Node. However, at the moment only [`geth`](https://github.com/ethereum/go-ethereum) and [`reth`](https://github.com/paradigmxyz/reth) nodes are confirmed to work reliably with the Aztec client. +After setting up your node, you must request to be added to the sequencer set. -::: +Complete the onboarding process at [testnet.aztec.network](https://testnet.aztec.network) using zkPassport. -Once you have your node running, head to the [Aztec Discord](https://discord.gg/aztec) to interact with other network operators. +## Next Steps -Happy sequencing! +- Monitor your sequencer's performance and attestation rate +- Join the [Aztec Discord](https://discord.gg/aztec) for operator support +- Review [Reacting to Upgrades](../../reference/reacting_to_upgrades.md) guide +- Consider implementing monitoring and alerting for production deployments diff --git a/docs/versioned_docs/version-v2.0.1/the_aztec_network/index.md b/docs/versioned_docs/version-v2.0.1/the_aztec_network/index.md index 517502d8175f..7577a29649bd 100644 --- a/docs/versioned_docs/version-v2.0.1/the_aztec_network/index.md +++ b/docs/versioned_docs/version-v2.0.1/the_aztec_network/index.md @@ -5,6 +5,8 @@ title: Running a Full Node description: A guide about how to run a full node on the Aztec network. --- +## Background + This guide will go over the steps required to run a full node on Aztec with a basic setup. A full node allows users to connect and interact with the network. It provides users an interface to send and receive transactions and state updates without relying on a third party. @@ -18,24 +20,24 @@ Please note that there are two other types of nodes available that we are not co Minimum hardware requirements: - 2 core / 4 vCPU -- 8 GB RAM -- 10 GB SDD +- 16 GB RAM +- 1 TB NVMe SDD - 25 Mbps network connection Please note that these requirements are subject to change as the network throughput increases. -Along with the above minimum hardware requirements, it is assumed that the user has access to a performant ethereum RPC endpoint. Furthermore, this guide expects the user to be using a "standard" Linux distribution like Debian / Ubuntu when following along with the steps. +Along with the above minimum hardware requirements, it is assumed that the user has access to a performant Ethereum RPC endpoint. Furthermore, this guide expects the user to be using a "standard" Linux distribution like Debian / Ubuntu when following along with the steps. -Overview +## Overview 1. Install Docker -2. Install aztec +2. Install Aztec 3. Configure the node 4. Start the node! ## Install and set up Docker -Please ensure that docker is installed. If not, here is a convenient way to install it. +Ensure Docker is installed. If not, here is a convenient way to install it. This uses the script at [https://get.docker.com/](https://get.docker.com/) to install the latest stable release of Docker on Linux: @@ -45,7 +47,7 @@ curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh ``` -Afterwards, the currently logged in user must be added to the docker group, so sudo is not needed to invoke docker. +Afterwards, the currently logged in user must be added to the docker group, so `sudo` is not needed to invoke docker. ```console sudo groupadd docker @@ -57,21 +59,21 @@ docker run hello-world ## Install Aztec -Run these commands to grab the aztec stack and add them to path. +Run these commands to grab the Aztec stack and add them to path. ```console bash -i <(curl -s https://install.aztec.network) # Users should check that it is installed by using ls ~/.aztec/bin -# aztec, aztec-up aztec-nargo and aztec-wallet should show up here +# aztec, aztec-up, aztec-nargo and aztec-wallet should show up here echo 'export PATH="$HOME/.aztec/bin:$PATH"' >> ~/.bashrc source ~/.bashrc ``` -The next step is to install the correct version of aztec that is running on testnet. The correct version of the aztec network currently is `1.2.0`. If that is not the version that was installed in the previous step, please run this to ensure the correct version is installed. +The next step is to install the correct version of aztec that is running on testnet. The correct version of the aztec network currently is `2.0.1`. If that is not the version that was installed in the previous step, please run this to ensure the correct version is installed. ```console -aztec-up 1.2.0 +aztec-up 2.0.1 ``` The user can confirm that they are running on the correct version with: @@ -88,17 +90,21 @@ Now that the correct version of the node is installed, it needs to be configured mkdir aztec-node && cd ./aztec-node ``` -Next, set some required configuration options. This guide will use `custom_named` environment variables (e.g. `AZTEC_NODE_P2P_IP`) but this is not necessary; you can pass valued directly into the command without specifying them as environment variables. The external IP address of the node, and the L1 RPC endpoints must be defined when starting a node. Also, configuration defining the network version should be set, as this will let the node define the other required protocol variables, like rollup address, registry address etc. Please note that the specified RPC endpoints must support high throughput, otherwise the node will suffer degraded performance. +Next, set some required configuration options. This guide will use `custom_named` environment variables (e.g. `AZTEC_NODE_P2P_IP`) but this is not necessary; you can pass values directly into the command without specifying them as environment variables. The external IP address of the node, and the L1 RPC endpoints must be defined when starting a node. Also, configuration defining the network version should be set, as this will let the node define the other required protocol variables, like rollup address, registry address etc. Note that the specified RPC endpoints must support high throughput, otherwise the node will suffer degraded performance. ```console -# If the external IP of the machine the node is running on is unknown, it can be obtained by running `curl ifconfig.me`. -export AZTEC_NODE_P2P_IP=IP export AZTEC_NODE_NETWORK=testnet +export AZTEC_NODE_P2P_IP=IP export AZTEC_NODE_ETH_HOSTS= export AZTEC_NODE_CONSENSUS_HOSTS= ``` -Finally, the ports used by the node must be accessible to other Aztec nodes on the internet. This will require disabling the firewall for and / or forwarding these ports. The router must be able to send UDP and TCP traffic on port 40400 (unless the defaults were changed) to the node IP address on its local network. Failure to do so may result in the node not participating in p2p duties. +:::tip + +The ports used by the node must be accessible to other Aztec nodes on the internet. This will require disabling the firewall for and / or forwarding these ports. The router must be able to send UDP and TCP traffic on port 40400 (unless the defaults were changed) to the node IP address on its local network. Failure to do so may result in the node not participating in p2p duties. + +Running the command `curl ipv4.icanhazip.com` can retrieve your public IP address for you. +::: ## Run the node @@ -110,16 +116,16 @@ To verify the node is working, run these commands in another terminal window: ```console # Rule 1: For HTTP traffic on port 8080 -curl -X POST --data '{"method": "node_getL2Tips"}' +curl -X POST http://localhost:8080 --data '{"method": "node_getL2Tips"}' # should return JSON data in the format of "{"result":{"latest":{"number":"...}}}" # Rule 2: For TCP traffic on port 40400 (set by default) -nc -vz IP 40400 -# should return "Connection to IP 40400 port [tcp/*] succeeded!" if port open +nc -vz [YOUR_EXTERNAL_IP] 40400 +# should return "Connection to [YOUR_EXTERNAL_IP] 40400 port [tcp/*] succeeded!" if port open # Rule 3: For UDP traffic on port 40400 (set by default) -nc - vu IP 40400 -# should return "Connection to IP 40400 port [udp/*] succeeded!" if port open +nc -vu [YOUR_EXTERNAL_IP] 40400 +# should return "Connection to [YOUR_EXTERNAL_IP] 40400 port [udp/*] succeeded!" if port open ``` Congrats, the node should be up, running, and connected to the network! diff --git a/docs/versioned_docs/version-v2.0.1/the_aztec_network/reference/operator_faq.md b/docs/versioned_docs/version-v2.0.1/the_aztec_network/reference/operator_faq.md index d70a1f771bf6..39b6c55ebb32 100644 --- a/docs/versioned_docs/version-v2.0.1/the_aztec_network/reference/operator_faq.md +++ b/docs/versioned_docs/version-v2.0.1/the_aztec_network/reference/operator_faq.md @@ -16,9 +16,9 @@ Here is a list of common issues node operators may face. If you don't find your If it is regarding a beacon call, it has failed to the beacon rpc call. If it is regarding the execution endpoint, then it is likely just reporting. -## Update aztec alpha-testnet version +## Update aztec testnet version -To make sure you're using the latest version, run: `aztec-up alpha-testnet`, then restart your node. +To make sure you're using the latest version, run: `aztec-up latest`, then restart your node. ## "rpc rate", "quota limit" @@ -42,6 +42,6 @@ Ignore. `ERROR: world-state:database Call SYNC_BLOCK failed: Error: Can't synch block: block state does not match world state` - Stop aztec -- Delete current snapshot: `rm -rf ~/.aztec/1.2.0/data/archiver` +- Delete current snapshot: `rm -rf ~/.aztec/2.0.1/data/archiver` - Update to latest version: `aztec-up -v latest` - Start aztec diff --git a/docs/versioned_docs/version-v2.0.1/the_aztec_network/reference/reacting_to_upgrades.md b/docs/versioned_docs/version-v2.0.1/the_aztec_network/reference/reacting_to_upgrades.md index a1507ceb843a..32caaa45efbd 100644 --- a/docs/versioned_docs/version-v2.0.1/the_aztec_network/reference/reacting_to_upgrades.md +++ b/docs/versioned_docs/version-v2.0.1/the_aztec_network/reference/reacting_to_upgrades.md @@ -11,7 +11,7 @@ This is a guide for sequencer operators to understand how to react to protocol u To signal for governance upgrades, sequencers must set their `GOVERNANCE_PROPOSER_PAYLOAD` on their sequencer node to the address of a `payload`. This will register their signal with the GovernanceProposer contract. :::info -the `payload` is a contract on L1 that specifies the address of the new rollup contract to be upgraded to. The payloads to be voted on during alpha-testnet will be communicated to sequencers on the forum and on community channels like discord. +the `payload` is a contract on L1 that specifies the address of the new rollup contract to be upgraded to. The payloads to be voted on during testnet will be communicated to sequencers on the forum and on community channels like discord. ::: This signalling phase will pass once `N` sequencers in a round of `M` L2 blocks have signalled for the same payload. Once the quorum is met, anyone can call the `executeProposal(roundNumber)` function on the Governance Proposer contract to advance the upgrade into the next stage. diff --git a/docs/versioned_docs/version-v2.0.1/the_aztec_network/reference/useful_commands.md b/docs/versioned_docs/version-v2.0.1/the_aztec_network/reference/useful_commands.md index bac4ea535565..2a8066fd1c49 100644 --- a/docs/versioned_docs/version-v2.0.1/the_aztec_network/reference/useful_commands.md +++ b/docs/versioned_docs/version-v2.0.1/the_aztec_network/reference/useful_commands.md @@ -18,7 +18,7 @@ These commands are useful to sequencer operators. If you're trying to do somethi The Registry contract is your entrypoint into almost all other contracts for a particular deployment of the Aztec Network. Armed with this address, you can retrieve almost all other useful contracts. -Assume there are two "deployments" of Aztec i.e. an `alpha-testnet` and a `ignition-testnet`. Then each deployment will have a unique Registry contract that does not change with upgrades. If a governance upgrade on `alpha-testnet` deploys a new rollup contract, the Registry contract for the `alpha-testnet` deployment will not change. +Assume there are two "deployments" of Aztec i.e. an `testnet` and a `ignition-testnet`. Then each deployment will have a unique Registry contract that does not change with upgrades. If a governance upgrade on `testnet` deploys a new rollup contract, the Registry contract for the `testnet` deployment will not change. diff --git a/docs/versioned_docs/version-v2.0.2/the_aztec_network/guides/run_nodes/how_to_run_prover.md b/docs/versioned_docs/version-v2.0.2/the_aztec_network/guides/run_nodes/how_to_run_prover.md index 8660b2902c51..e68abd8ddfd7 100644 --- a/docs/versioned_docs/version-v2.0.2/the_aztec_network/guides/run_nodes/how_to_run_prover.md +++ b/docs/versioned_docs/version-v2.0.2/the_aztec_network/guides/run_nodes/how_to_run_prover.md @@ -1,6 +1,6 @@ --- sidebar_position: 3 -title: How to Run a Prover Node +title: How to Run an Aztec Prover description: A comprehensive guide to setting up and running an Aztec Prover node on testnet or mainnet, including hardware requirements, configuration options, and performance optimization tips. keywords: [ @@ -23,115 +23,274 @@ tags: - infrastructure --- -import { AztecTestnetVersion } from '@site/src/components/Snippets/general_snippets'; - ## Background -Prover nodes are a critical part of the Aztec network's infrastructure. They generate cryptographic proofs that attest to the correctness of public transactions, ultimately producing a single rollup proof that is submitted to Ethereum. +This guide covers the steps required to run a prover on the Aztec network. Before you begin, you should understand that operating a prover is a resource-intensive role typically undertaken by experienced engineers due to its technical complexity and hardware requirements. -Operating a prover node requires a solid grasp of blockchain protocols, cryptographic systems, DevOps best practices, and high-performance hardware. It’s a resource-intensive role typically undertaken by experienced engineers or specialized teams due to its technical and operational complexity. +Aztec provers are critical infrastructure components that generate cryptographic proofs attesting to transaction correctness, ultimately producing a single rollup proof submitted to Ethereum. -## Prerequisites +The prover consists of three main components: -Before following this guide, make sure you: +1. **Prover node**: Polls L1 for unproven epochs, creates proving jobs, distributes them to the broker, and submits the final rollup proof to the rollup contract. -- Have the `aztec` tool [installed](../../../developers/getting_started/getting_started_on_sandbox.md#install-the-sandbox) -- Have sufficient hardware resources for proving operations -- Your confidence level is expected to be around "I'd be able to run a Prover _without_ this guide" +2. **Prover broker**: Manages the job queue, distributing work to agents and collecting results. -## Understanding Prover Architecture +3. **Prover agent(s)**: Executes proof generation jobs in a stateless manner. -The Aztec prover involves three key components: the Prover Node, the Proving Broker, and the Proving Agent. +## Prerequisites + +The minimum hardware specifications for each of the components is listed below. #### Prover Node -The Prover Node is responsible for polling the L1 for unproven epochs and initiating the proof process. When an epoch is ready to be proven, the prover node creates proving jobs and distributes them to the broker. The Prover Node is also responsible for submitting the final rollup proof to the rollup contract. +Minimum specifications: -- **Resources**: Up to 8 cores, 16GB RAM, ~1TB disk for storing state. +- 2 core / 4 vCPU +- 16 GB RAM +- 1 TB NVMe SSD +- 25 Mbps network connection #### Proving Broker -Manages a queue of proving jobs, distributing them to available agents and forwarding results back to the node. +Minimum specifications: -- **Resources**: Up to 4 cores, 16GB RAM, ~1GB disk. +- 2 core / 4 vCPU +- 16 GB RAM +- 10 GB SSD #### Proving Agents -Executes the actual proof jobs. Agents are stateless, fetch work from the broker, and return the results. +Minimum specifications: + +- 32 core / 64 vCPU +- 128 GB RAM +- 10 GB SSD + +This guide outlines a basic, non-distributed setup with all components on a single machine. Your hardware must meet or exceed the proving agent requirements listed above. + +This guide assumes you are using a standard Linux distribution (Debian or Ubuntu). + +### Required Software + +- Docker and the Aztec toolchain installed via aztec-up (see the [getting started section](../../index.md)) +- Docker Compose ([installation guide](https://docs.docker.com/compose/install/)) +- Access to L1 node endpoints (execution and consensus clients). See [Eth Docker's guide](https://ethdocker.com/Usage/QuickStart) if you need to set these up. + +## Configure the Prover + +Setting up a prover involves configuring three components through environment variables and Docker Compose. + +### Setup Steps + +1. Configure components via environment variables +2. Enable auto-update and auto-restart functionality +3. Deploy with Docker Compose + +First, create the directory structure for prover data storage: + +```sh +mkdir -p aztec-prover/prover-node-data aztec-prover/prover-broker-data +cd aztec-prover +touch .env +``` + +### Component Configuration -- **Resources**: Each agent may use up to 16 cores and 128GB RAM. +Each prover component requires specific environment variables. Configure them as follows: + +#### Prover Node + +Required environment variables: + +- `DATA_DIRECTORY`: the folder where the data of the prover node is stored +- `P2P_IP`: the IP address of this prover node +- `P2P_PORT`: the port that P2P communication happens on +- `ETHEREUM_HOSTS`: the execution RPC endpoints +- `L1_CONSENSUS_HOST_URLS`: the consensus RPC endpoints +- `LOG_LEVEL`: the desired level of logging for the prover node. It defaults to `INFO` +- `PROVER_BROKER_HOST`: the endpoint of the prover broker that this node sends prover jobs to +- `PROVER_PUBLISHER_PRIVATE_KEY`: the private key of the Ethereum EOA used for publishing the proofs to L1 +- `AZTEC_PORT`: the port that the prover node API is exposed on + +Add the following to your `.env` file (assuming default ports of 8080 for the prover node, and 40400 for p2p connectivity): + +```sh +DATA_DIRECTORY=./prover-node-data +P2P_IP= +P2P_PORT=40400 +ETHEREUM_HOSTS= +L1_CONSENSUS_HOST_URLS= +LOG_LEVEL=info +PROVER_BROKER_HOST=http://prover-broker:8080 +PROVER_PUBLISHER_PRIVATE_KEY= +AZTEC_PORT=8080 +``` + +**Note**: The broker URL `http://prover-broker:8080` references the Docker Compose service name defined later. + +:::tip +You MUST forward ports for P2P connectivity. Configure your router to forward both UDP and TCP traffic on the port specified by `P2P_PORT` to your local IP address. + +To find your public IP address, run: `curl ipv4.icanhazip.com` +::: + +#### Prover Broker + +Required environment variables: + +- `DATA_DIRECTORY`: the folder where the data of the prover broker is stored +- `LOG_LEVEL`: the desired level of logging for the prover broker. It defaults to `INFO` +- `ETHEREUM_HOSTS`: the execution RPC endpoints +- `P2P_IP`: the IP address of this prover broker +- `P2P_PORT`: the port that P2P communication happens on + +**Note**: Some variables overlap with the prover node configuration. If running components on separate machines, adjust accordingly. Since `DATA_DIRECTORY` is used by both components, define a separate variable for the broker: + +Add to your `.env` file: + +```sh +PROVER_BROKER_DATA_DIRECTORY=./prover-broker-data +``` -## Setting Up Your Prover +#### Prover Agent -### Using Docker Compose +Required environment variables: + +- `PROVER_AGENT_COUNT`: Number of agents to run (each requires ~10GB RAM) +- `PROVER_AGENT_POLL_INTERVAL_MS`: Polling interval for job requests (milliseconds) +- `PROVER_BROKER_HOST`: Broker endpoint for job submission +- `PROVER_ID`: Ethereum address corresponding to `PROVER_PUBLISHER_PRIVATE_KEY` + +**Note**: Some variables overlap with the prover node configuration. In this case we use the same value for `PROVER_BROKER_HOST`, so we will not duplicate it in our `.env` file. + +Add to your `.env` file: + +```sh +PROVER_AGENT_COUNT=10 +PROVER_AGENT_POLL_INTERVAL_MS=10000 +PROVER_ID= +``` + +### Enable Auto-Update and Auto-Restart + +The prover's auto-update functionality is critical for network coordination. This background module enables: + +- Configuration updates across all nodes +- Automated image updates via controlled shutdowns +- Rapid hot-fix deployment +- Coordinated resets after governance upgrades + +**Important**: Do NOT set `AUTO_UPDATE_URL` or `AUTO_UPDATE` environment variables. These must use their default values for proper operation. + +Since Docker Compose doesn't respect pull policies on container restarts, install Watchtower for automatic updates: + +```sh +docker run -d \ + --name watchtower \ + -v /var/run/docker.sock:/var/run/docker.sock \ + containrrr/watchtower +``` + +### Deploy with Docker Compose + +Create a `docker-compose.yml` file in your `aztec-prover` directory with the following content: ```yml name: aztec-prover services: prover-node: - image: aztecprotocol/aztec:latest # Always refer to the docs to check that you're using the correct image. - command: - - node - - --no-warnings - - /usr/src/yarn-project/aztec/dest/bin/index.js - - start - - --prover-node - - --archiver - - --network - - alpha-testnet + image: aztecprotocol/aztec:latest + entrypoint: >- + node + --no-warnings + /usr/src/yarn-project/aztec/dest/bin/index.js + start + --prover-node + --archiver + --network testnet depends_on: - broker: + prover-broker: condition: service_started required: true environment: - # PROVER_COORDINATION_NODE_URL: "http://:8080" # this can point to your own validator - using this replaces the need for the prover node to be on the P2P network and uses your validator as a sentry node of some sort. - # P2P_ENABLED: "false" # Switch to false if you provide a PROVER_COORDINATION_NODE_URL - DATA_DIRECTORY: /data - DATA_STORE_MAP_SIZE_KB: "134217728" - ETHEREUM_HOSTS: # EL RPC endpoint - L1_CONSENSUS_HOST_URLS: # CL RPC endpoint - LOG_LEVEL: info - PROVER_BROKER_HOST: http://broker:8080 - PROVER_PUBLISHER_PRIVATE_KEY: # The node needs to publish proofs to L1. Replace with your private key + DATA_DIRECTORY: /var/lib/data + ETHEREUM_HOSTS: ${ETHEREUM_HOSTS} + L1_CONSENSUS_HOST_URLS: ${L1_CONSENSUS_HOST_URLS} + LOG_LEVEL: ${LOG_LEVEL} + PROVER_BROKER_HOST: ${PROVER_BROKER_HOST} + PROVER_PUBLISHER_PRIVATE_KEY: ${PROVER_PUBLISHER_PRIVATE_KEY} + P2P_IP: ${P2P_IP} + P2P_PORT: ${P2P_PORT} + AZTEC_PORT: ${AZTEC_PORT} ports: - - "8080:8080" - - "40400:40400" - - "40400:40400/udp" + - ${AZTEC_PORT}:${AZTEC_PORT} + - ${P2P_PORT}:${P2P_PORT} + - ${P2P_PORT}:${P2P_PORT}/udp volumes: - - /home/my-node/node:/data # Local directory - - agent: - image: aztecprotocol/aztec:latest # Always refer to the docs to check that you're using the correct image. - command: - - node - - --no-warnings - - /usr/src/yarn-project/aztec/dest/bin/index.js - - start - - --prover-agent - - --network - - alpha-testnet + - ${DATA_DIRECTORY}:/var/lib/data + + prover-broker: + image: aztecprotocol/aztec:latest + entrypoint: >- + node + --no-warnings + /usr/src/yarn-project/aztec/dest/bin/index.js + start + --prover-broker + --network testnet environment: - PROVER_AGENT_COUNT: "1" - PROVER_AGENT_POLL_INTERVAL_MS: "10000" # Just to reduce the log spamming if you're using debug logging. - PROVER_BROKER_HOST: http://broker:8080 - PROVER_ID: # this should be the address corresponding to the PROVER_PUBLISHER_PRIVATE_KEY you set on the node. + DATA_DIRECTORY: /var/lib/data + ETHEREUM_HOSTS: ${ETHEREUM_HOSTS} + P2P_IP: ${P2P_IP} + LOG_LEVEL: ${LOG_LEVEL} + volumes: + - ${PROVER_BROKER_DATA_DIRECTORY}:/var/lib/data + + prover-agent: + image: aztecprotocol/aztec:latest + entrypoint: >- + node + --no-warnings + /usr/src/yarn-project/aztec/dest/bin/index.js + start + --prover-agent + --network testnet + environment: + PROVER_AGENT_COUNT: ${PROVER_AGENT_COUNT} + PROVER_AGENT_POLL_INTERVAL_MS: ${PROVER_AGENT_POLL_INTERVAL_MS} + PROVER_BROKER_HOST: ${PROVER_BROKER_HOST} + PROVER_ID: ${PROVER_ID} pull_policy: always restart: unless-stopped +``` - broker: - image: aztecprotocol/aztec:latest # Always refer to the docs to check that you're using the correct image. - command: - - node - - --no-warnings - - /usr/src/yarn-project/aztec/dest/bin/index.js - - start - - --prover-broker - - --network - - alpha-testnet - environment: - DATA_DIRECTORY: /data - ETHEREUM_HOSTS: # Your EL RPC endpoint - LOG_LEVEL: info - volumes: - - /home/my-node/node:/data # Local directory +**Note**: This configuration includes only essential settings. The `--network testnet` flag applies network-specific defaults. See the [CLI reference](../../reference/cli_reference.md) for all available options. + +Start the prover: + +```sh +docker compose up -d +``` + +## Verification + +To verify your prover is running correctly: + +1. Check that all services are running: + +```sh +docker compose ps +``` + +2. View logs for each component: + +```sh +# Prover node logs +docker compose logs -f prover-node + +# Broker logs +docker compose logs -f prover-broker + +# Agent logs +docker compose logs -f prover-agent ``` diff --git a/docs/versioned_docs/version-v2.0.2/the_aztec_network/guides/run_nodes/how_to_run_sequencer.md b/docs/versioned_docs/version-v2.0.2/the_aztec_network/guides/run_nodes/how_to_run_sequencer.md index 7b91300e317a..917dd59e1e1f 100644 --- a/docs/versioned_docs/version-v2.0.2/the_aztec_network/guides/run_nodes/how_to_run_sequencer.md +++ b/docs/versioned_docs/version-v2.0.2/the_aztec_network/guides/run_nodes/how_to_run_sequencer.md @@ -24,280 +24,253 @@ tags: ## Background +This guide covers the steps required to run a sequencer node on the Aztec network. + The Aztec sequencer node is critical infrastructure responsible for ordering transactions and producing blocks. -The sequencer node takes part in three key actions: +The sequencer node performs three key actions: -1. Assemble unprocessed transactions and propose the next block -2. Attest to correct execution of txs in the proposed block (if part of validator committee) -3. Submit the successfully attested block to L1 +1. Assembles unprocessed transactions and proposes the next block +2. Attests to correct execution of transactions in proposed blocks (when part of the sequencer committee) +3. Submits successfully attested blocks to L1 -When transactions are sent to the Aztec network, sequencer nodes bundles them into blocks, checking various constraints such as gas limits, block size, and transaction validity. Before a block can be published, it must be validated by a committee of other sequencer nodes (validators in this context) who re-execute public transactions and verify private function proofs so they can attest to correct execution. These validators attest to the block's validity by signing it, and once enough attestations are collected (two-thirds of the committee plus one), the sequencer can submit the block to L1. +Sequencer nodes bundle transactions into blocks while checking constraints like gas limits, block size, and validity. 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. The archiver component complements this process by maintaining historical chain data. It continuously monitors L1 for new blocks, processes them, and maintains a synchronized view of the chain state. This includes managing contract data, transaction logs, and L1-to-L2 messages, making it essential for network synchronization and data availability. -## Setup - -### Requirements - -A computer running Linux or MacOS with the following specifictions: - -- CPU: 8-cores -- RAM: 16 GiB -- Storage: 1 TB SSD +## Prerequisites -A Network connection of at least 25 Mbps up/down. +Minimum hardware requirements: -### Installation +- 2 core / 4 vCPU +- 16 GB RAM +- 1TB NVMe SSD +- 25 Mbps network connection -import { General, Fees } from '@site/src/components/Snippets/general_snippets'; +Please note that these requirements are subject to change as the network throughput increases. - +This guide assumes you are using a standard Linux distribution (Debian or Ubuntu). -Now install the latest testnet version of aztec: `aztec-up -v latest` +### Required Software -Join the [Discord](https://discord.gg/aztec) to connect with the community and get help with your setup. +- Docker and the Aztec toolchain installed via aztec-up (see the [getting started section](../../index.md)) +- Docker Compose ([installation guide](https://docs.docker.com/compose/install/)) +- Access to L1 node endpoints (execution and consensus clients). See [Eth Docker's guide](https://ethdocker.com/Usage/QuickStart) if you need to set these up. -## Sequencer Quickstart +## Configure the Sequencer -With the alpha-testnet version of the aztec tools, you now need to define required variables for your node. +Setting up a sequencer involves configuring keys, environment variables, and Docker Compose. -The following variable names are specific to the `aztec start` command, set them as variables in the terminal or inline before the command. +### Setup Steps -- `ETHEREUM_HOSTS=`: One or more comma-separated public rpc provider url(s). NB - don't share your access token -- `L1_CONSENSUS_HOST_URLS=`: One or more comma-separated public rpc provider url(s) that supports consensus client requests -- `VALIDATOR_PRIVATE_KEY="Ox"`: Private key of testnet L1 EOA that holds Sepolia ETH (0.01 Sepolia ETH can get you started) -- `COINBASE="0x"`: Recipient of block rewards (for node security on mainnet, this should be a different address to the validator eoa) -- `P2P_IP="x.x.x.x"`: IP address of computer running the node (you can get this by running, `curl api.ipify.org`, on your node) +1. Define private keys and accounts for sequencer duties +2. Configure node settings via environment variables +3. Enable auto-update and auto-restart functionality +4. Deploy with Docker Compose -Now in a terminal start your node as a sequencer and archiver: +First, create the directory structure for sequencer data storage: -If the above variables are set you can simply use: `aztec start --node --archiver --sequencer --network testnet` - -Otherwise you can specify values via the CLI flags (using values in place of the variable names): - -```bash -aztec start --node --archiver --sequencer \ - --network testnet \ - --l1-rpc-urls $ETHEREUM_HOSTS \ - --l1-consensus-host-urls $L1_CONSENSUS_HOST_URLS \ - --sequencer.validatorPrivateKeys $VALIDATOR_PRIVATE_KEY \ - --sequencer.coinbase $COINBASE \ - --p2p.p2pIp $P2P_IP +```sh +mkdir -p aztec-sequencer/keys aztec-sequencer/data +cd aztec-sequencer +touch .env ``` -**Additional Parameters**: The comprehensive list of parameters can be seen via: `aztec help start`. For example: +### Define Private Keys and Accounts -``` ---p2p.p2pPort (default: 40400) ($P2P_PORT) - The port for the P2P service. -``` +Sequencers require private keys to identify themselves as valid proposers or attesters. Configure these through a keystore file. -### Port forwarding +Create a `keystore.json` file in your `aztec-sequencer/keys` folder: -For some restricted environments, you may need to explicity forward the p2p port (default: 40400) to your local node ip address. - -This is often in a router's advanced network settings if required. - -### Next steps - -To add your sequencer you'll need the following few values, as well as `ETHEREUM_HOSTS` from before: - -- `STAKING_ASSET_HANDLER="0xF739D03e98e23A7B65940848aBA8921fF3bAc4b2"`: Constant L1 contract address -- `L1_CHAIN_ID="11155111"`: Sepolia chainid -- `PRIVATE_KEY="0x`: private key of account with sepolia eth to make transaction (eg can use funded validator key) - -Then run the aztec command to add your address as an L1 validator, with rpc url(s) for Etheruem L1 execution requests: - -```bash -aztec add-l1-validator --staking-asset-handler=0xF739D03e98e23A7B65940848aBA8921fF3bAc4b2 \ - --l1-rpc-urls $ETHEREUM_HOSTS \ - --l1-chain-id 11155111 \ - --private-key "0x" \ - --attester "0x" \ - --proposer-eoa "0x" +```json +{ + "schemaVersion": 1, + "validators": [ + { + "attester": ["ETH_PRIVATE_KEY_0"], + "publisher": ["ETH_PRIVATE_KEY_1"], + "coinbase": "ETH_ADDRESS_2", + "feeRecipient": "AZTEC_ADDRESS_0" + } + ] +} ``` -**Tip**: Use `aztec help add-l1-validator` for further parameter details. - -:::note Validator Quota Filled - -In the absence of real-world staking incentives, becoming a validator is throttled with time, so you may see `ValidatorQuotaFilledUntil(uint256 _timestamp)` at the beginning of the text returned. - -The timestamp is when the next round of sequencers can be added as validators, so try again right after that. - -::: - -## Deeper dive - -This guide will describe how to setup your sequencer using the `aztec start` command. For more advanced setups, refer to the Advanced Configuration section below. - -The `aztec start` tool is a one-stop-shop for running your sequencer on any Aztec Network. It assigns default values to several config variables based on a `--network` flag and launches a docker container running the sequencer software. - -To use the `aztec start` command, you need to obtain the following: - -#### RPCs - -- An L1 execution client (for reading transactions and state). It can be specified via the `--l1-rpc-urls` flag when using `aztec start` or via the env var `ETHEREUM_HOSTS`. Popular execution clients include [Geth](https://geth.ethereum.org/) or [Nethermind](https://nethermind.io/). You can run your own node or use a service like [Alchemy](https://www.alchemy.com/) or [Infura](https://www.infura.io/). - -- An L1 consensus client (for blobs). It can be specified via the `--l1-consensus-host-urls` flag when using `aztec start` or via the env var `L1_CONSENSUS_HOST_URLS`. Popular consensus clients include [Lighthouse](https://lighthouse.sigmaprime.io/) or [Prysm](https://prysmaticlabs.com/). Not all RPC providers support consensus endpoints, [Quicknode](https://www.quicknode.com/) and [dRPC](https://drpc.org/) have been known to work for consensus endpoints. - -- To reduce load on your consensus endpoint, the Aztec sequencer supports an optional remote server that serves blobs to the client. This is often called a "blob sink" or "blob storage service". You can pass your own or use one provided by a trusted party via the `--sequencer.blobSinkUrl` flag when using `aztec start`, or via the env var `BLOB_SINK_URL`. Some providers like [Alchemy](https://www.alchemy.com/) offer blob storage services as part of their infrastructure offerings. - -#### Ethereum Keys +The keystore defines keys and addresses for sequencer operation: -You will need an Ethereum private key and the corresponding public address. The private key is set via the `--sequencer.validatorPrivateKeys` flag while the public address should be specified via the `--sequencer.coinbase ` flag. +- `attester`: Private key for signing block proposals and attestations. The corresponding Ethereum address identifies the sequencer. +- `publisher`: Private key for sending block proposals to L1. Defaults to attester key if not set. +- `coinbase`: Ethereum address receiving L1 rewards and fees. Defaults to attester address if not set. +- `feeRecipient`: Aztec address receiving unburnt transaction fees from blocks. -The private key is needed as your validator will post blocks to Ethereum, and the public address will be the recipient of any block rewards. +Replace the placeholder values with your actual keys and addresses. -Disclaimer: you may want to generate and use a new Ethereum private key. +### Node Configuration -#### Networking +Required environment variables: -You MUST forward your ports. Your router must send UDP and TCP traffic on port `40400` (unless you changed the default) to your IP address on your local network. Failure to do so may result in your sequencer not participating on the p2p network. +- `DATA_DIRECTORY`: the folder where the data of the sequencer is stored +- `KEY_STORE_DIRECTORY`: can be a path to the file or directory where keystores are located. In our case it is the path to the folder containing the `keystore.json` file created above +- `LOG_LEVEL`: the desired level of logging for the sequencer. It defaults to `INFO`. +- `ETHEREUM_HOSTS`: The execution RPC endpoints +- `L1_CONSENSUS_HOST_URLS`: The consensus RPC endpoints +- `P2P_IP`: The IP address of this sequencer +- `P2P_PORT`: The port that P2P communication happens on +- `AZTEC_PORT`: The port that the sequencer node API is exposed on -As a tip, configure your router to give your MAC address the same IP address every time it does a DHCP refresh. +Add the following to your `.env` file (using default ports 8080 and 40400): -You also need to grab your external IP address and pass it along to the `--p2p.p2pIp` when using `aztec start`. - -#### Sepolia ETH - -You'll need Sepolia ETH to cover gas costs. Here are some options: - -- Use a PoW faucet like [Sepolia PoW Faucet](https://sepolia-faucet.pk910.de/) -- Ask in our Discord community (and remember to pay it forward when you can!) - -### Now Start Your Sequencer - -To boot up a sequencer using `aztec start`, run the following command: - -```bash -aztec start --node --archiver --sequencer \ - --network testnet \ - --l1-rpc-urls https://example.com \ - --l1-consensus-host-urls https://example.com \ - --sequencer.validatorPrivateKeys 0xYourPrivateKey \ - --sequencer.coinbase 0xYourAddress \ - --p2p.p2pIp 999.99.999.99 \ - --p2p.maxTxPoolSize 1000000000 +```sh +DATA_DIRECTORY=./data +KEY_STORE_DIRECTORY=./keys +LOG_LEVEL=info +ETHEREUM_HOSTS= +L1_CONSENSUS_HOST_URLS= +P2P_IP= +P2P_PORT=40400 +AZTEC_PORT=8080 ``` :::tip +You MUST forward ports for P2P connectivity. Configure your router to forward both UDP and TCP traffic on the port specified by `P2P_PORT` to your local IP address. -For a full overview of all available commands, check out the [CLI reference sheet](../../reference/cli_reference.md). +To find your public IP address, run: `curl ipv4.icanhazip.com` ::: -:::tip +### Enable Auto-Update and Auto-Restart -If you are unable to determine your public ip. Running the command `curl ipv4.icanhazip.com` can retrieve it for you. -::: +The sequencer's auto-update functionality is critical for network coordination. This background module enables: + +- Configuration updates across all nodes +- Automated image updates via controlled shutdowns +- Rapid hot-fix deployment +- Coordinated resets after governance upgrades -### Register as a Validator +**Important**: Do NOT set `AUTO_UPDATE_URL` or `AUTO_UPDATE` environment variables. These must use their default values for proper operation. -Once your node is fully synced, you can register as a validator using the `add-l1-validator` command: +Since Docker Compose doesn't respect pull policies on container restarts, install Watchtower for automatic updates: -```bash -aztec add-l1-validator \ - --l1-rpc-urls https://eth-sepolia.g.example.com/example/your-key \ - --private-key your-private-key \ - --attester your-validator-address \ - --proposer-eoa your-validator-address \ - --staking-asset-handler 0xF739D03e98e23A7B65940848aBA8921fF3bAc4b2 \ - --l1-chain-id 11155111 +```sh +docker run -d \ + --name watchtower \ + -v /var/run/docker.sock:/var/run/docker.sock \ + containrrr/watchtower ``` -:::warning +### Deploy with Docker Compose -You may see a warning when trying to register as a validator. To maintain network health there is a daily quota for validators to join the validator set. If you are not able to join, it could mean that today's quota of validators has already been added to the set. If you see this, you can try again later. Read [our blog post](https://aztec.network/blog/what-is-aztec-testnet) for more info. +Create a `docker-compose.yml` file in your `aztec-sequencer` directory: -::: +```yaml +services: + aztec-sequencer: + image: "aztecprotocol/aztec:latest" + 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} + P2P_IP: ${P2P_IP} + P2P_PORT: ${P2P_PORT} + AZTEC_PORT: ${AZTEC_PORT} + entrypoint: >- + node + --no-warnings + /usr/src/yarn-project/aztec/dest/bin/index.js + start + --node + --archiver + --sequencer + --network testnet + networks: + - aztec + restart: always + +networks: + aztec: + name: aztec +``` -## Advanced Configuration +**Note**: This configuration includes only essential settings. The `--network testnet` flag applies network-specific defaults. See the [CLI reference](../../reference/cli_reference.md) for all available options. -### Using Environment Variables +Start the sequencer: -Every flag in the `aztec start` command corresponds to an environment variable. You can see the variable names by running `aztec start --help`. A reference is provided [here](../../reference/cli_reference.md). +```sh +docker compose up -d +``` -For example: +## Verification -- `--l1-rpc-urls` maps to `ETHEREUM_HOSTS` -- `--l1-consensus-host-urls` maps to `L1_CONSENSUS_HOSTS_URLS` +To verify your sequencer is running correctly: -You can create a `.env` file with these variables: +1. Check the current sync status (this may take a few minutes): -```bash -ETHEREUM_HOSTS=https://example.com -L1_CONSENSUS_HOST_URLS=https://example.com -# Add other configuration variables as needed +```sh +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" ``` -Then source this file before running your command: +Compare the output with block explorers like [Aztec Scan](https://aztecscan.xyz/) or [Aztec Explorer](https://aztecexplorer.xyz/). -```bash -source .env -aztec start --network testnet --archiver --node --sequencer # other flags... -``` +2. View sequencer logs: -### Using a Docker Compose - -If you would like to run in a docker compose, you can use a configuration like the one below: +```sh +docker compose logs -f aztec-sequencer +``` -```yml -name: aztec-node -services: - node: - network_mode: host # Optional, run with host networking - image: aztecprotocol/aztec:latest - environment: - ETHEREUM_HOSTS: "" - L1_CONSENSUS_HOST_URLS: "" - DATA_DIRECTORY: /data - VALIDATOR_PRIVATE_KEY: $VALIDATOR_PRIVATE_KEY - P2P_IP: $P2P_IP - LOG_LEVEL: debug - entrypoint: > - sh -c 'node --no-warnings /usr/src/yarn-project/aztec/dest/bin/index.js start --network testnet start --node --archiver --sequencer' - ports: - - 40400:40400/tcp - - 40400:40400/udp - - 8080:8080 +3. Check node status: - volumes: - - /home/my-node/node:/data # Local directory +```sh +curl http://localhost:8080/status ``` ## Troubleshooting -### L1 Access +### Common Issues -If you're hosting your own Ethereum execution or consensus client locally (rather than using an external RPC like Alchemy), you need to ensure that the prover node inside Docker can reach it. +**Port forwarding not working:** -By default, Docker runs containers on a bridge network that isolates them from the host machine's network interfaces. This means localhost inside the container won't point to the host's localhost. +- Verify your external IP address matches the `P2P_IP` setting +- Check firewall rules on your router and local machine +- Test connectivity using: `nc -zv ` -To fix this: +**Sequencer not syncing:** -Option 1: Use the special hostname host.docker.internal -This tells Docker to route traffic from the container to the host machine. For example: +- Check L1 endpoint connectivity +- Verify both execution and consensus clients are fully synced +- Review logs for specific error messages -```bash ---l1-rpc-urls http://host.docker.internal:8545 -``` +**Keystore issues:** -Option 2: Add a host network entry to your Docker Compose file (advanced users) -This gives your container direct access to the host's network stack, but removes Docker's network isolation. Add to your `docker-compose.yml` +- Ensure keystore.json is properly formatted +- Verify private keys are valid Ethereum private keys +- Check file permissions on the keys directory -```yaml -network_mode: "host" -``` +**Docker issues:** -⚠️ Note: network_mode: "host" only works on Linux. On macOS and Windows, use `host.docker.internal`. +- Ensure Docker and Docker Compose are up to date +- Check disk space availability +- Verify container has sufficient resources -:::info +## Join the Sequencer Set -You can run your own Sepolia ETH Node. However, at the moment only [`geth`](https://github.com/ethereum/go-ethereum) and [`reth`](https://github.com/paradigmxyz/reth) nodes are confirmed to work reliably with the Aztec client. +After setting up your node, you must request to be added to the sequencer set. -::: +Complete the onboarding process at [testnet.aztec.network](https://testnet.aztec.network) using zkPassport. -Once you have your node running, head to the [Aztec Discord](https://discord.gg/aztec) to interact with other network operators. +## Next Steps -Happy sequencing! +- Monitor your sequencer's performance and attestation rate +- Join the [Aztec Discord](https://discord.gg/aztec) for operator support +- Review [Reacting to Upgrades](../../reference/reacting_to_upgrades.md) guide +- Consider implementing monitoring and alerting for production deployments diff --git a/docs/versioned_docs/version-v2.0.2/the_aztec_network/index.md b/docs/versioned_docs/version-v2.0.2/the_aztec_network/index.md index 517502d8175f..118183cd71a3 100644 --- a/docs/versioned_docs/version-v2.0.2/the_aztec_network/index.md +++ b/docs/versioned_docs/version-v2.0.2/the_aztec_network/index.md @@ -5,6 +5,8 @@ title: Running a Full Node description: A guide about how to run a full node on the Aztec network. --- +## Background + This guide will go over the steps required to run a full node on Aztec with a basic setup. A full node allows users to connect and interact with the network. It provides users an interface to send and receive transactions and state updates without relying on a third party. @@ -18,24 +20,24 @@ Please note that there are two other types of nodes available that we are not co Minimum hardware requirements: - 2 core / 4 vCPU -- 8 GB RAM -- 10 GB SDD +- 16 GB RAM +- 1 TB NVMe SDD - 25 Mbps network connection Please note that these requirements are subject to change as the network throughput increases. -Along with the above minimum hardware requirements, it is assumed that the user has access to a performant ethereum RPC endpoint. Furthermore, this guide expects the user to be using a "standard" Linux distribution like Debian / Ubuntu when following along with the steps. +Along with the above minimum hardware requirements, it is assumed that the user has access to a performant Ethereum RPC endpoint. Furthermore, this guide expects the user to be using a "standard" Linux distribution like Debian / Ubuntu when following along with the steps. -Overview +## Overview 1. Install Docker -2. Install aztec +2. Install Aztec 3. Configure the node 4. Start the node! ## Install and set up Docker -Please ensure that docker is installed. If not, here is a convenient way to install it. +Ensure Docker is installed. If not, here is a convenient way to install it. This uses the script at [https://get.docker.com/](https://get.docker.com/) to install the latest stable release of Docker on Linux: @@ -45,7 +47,7 @@ curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh ``` -Afterwards, the currently logged in user must be added to the docker group, so sudo is not needed to invoke docker. +Afterwards, the currently logged in user must be added to the docker group, so `sudo` is not needed to invoke docker. ```console sudo groupadd docker @@ -57,21 +59,21 @@ docker run hello-world ## Install Aztec -Run these commands to grab the aztec stack and add them to path. +Run these commands to grab the Aztec stack and add them to path. ```console bash -i <(curl -s https://install.aztec.network) # Users should check that it is installed by using ls ~/.aztec/bin -# aztec, aztec-up aztec-nargo and aztec-wallet should show up here +# aztec, aztec-up, aztec-nargo and aztec-wallet should show up here echo 'export PATH="$HOME/.aztec/bin:$PATH"' >> ~/.bashrc source ~/.bashrc ``` -The next step is to install the correct version of aztec that is running on testnet. The correct version of the aztec network currently is `1.2.0`. If that is not the version that was installed in the previous step, please run this to ensure the correct version is installed. +The next step is to install the correct version of aztec that is running on testnet. The correct version of the aztec network currently is `2.0.2`. If that is not the version that was installed in the previous step, please run this to ensure the correct version is installed. ```console -aztec-up 1.2.0 +aztec-up 2.0.2 ``` The user can confirm that they are running on the correct version with: @@ -88,17 +90,21 @@ Now that the correct version of the node is installed, it needs to be configured mkdir aztec-node && cd ./aztec-node ``` -Next, set some required configuration options. This guide will use `custom_named` environment variables (e.g. `AZTEC_NODE_P2P_IP`) but this is not necessary; you can pass valued directly into the command without specifying them as environment variables. The external IP address of the node, and the L1 RPC endpoints must be defined when starting a node. Also, configuration defining the network version should be set, as this will let the node define the other required protocol variables, like rollup address, registry address etc. Please note that the specified RPC endpoints must support high throughput, otherwise the node will suffer degraded performance. +Next, set some required configuration options. This guide will use `custom_named` environment variables (e.g. `AZTEC_NODE_P2P_IP`) but this is not necessary; you can pass values directly into the command without specifying them as environment variables. The external IP address of the node, and the L1 RPC endpoints must be defined when starting a node. Also, configuration defining the network version should be set, as this will let the node define the other required protocol variables, like rollup address, registry address etc. Note that the specified RPC endpoints must support high throughput, otherwise the node will suffer degraded performance. ```console -# If the external IP of the machine the node is running on is unknown, it can be obtained by running `curl ifconfig.me`. -export AZTEC_NODE_P2P_IP=IP export AZTEC_NODE_NETWORK=testnet +export AZTEC_NODE_P2P_IP=IP export AZTEC_NODE_ETH_HOSTS= export AZTEC_NODE_CONSENSUS_HOSTS= ``` -Finally, the ports used by the node must be accessible to other Aztec nodes on the internet. This will require disabling the firewall for and / or forwarding these ports. The router must be able to send UDP and TCP traffic on port 40400 (unless the defaults were changed) to the node IP address on its local network. Failure to do so may result in the node not participating in p2p duties. +:::tip + +The ports used by the node must be accessible to other Aztec nodes on the internet. This will require disabling the firewall for and / or forwarding these ports. The router must be able to send UDP and TCP traffic on port 40400 (unless the defaults were changed) to the node IP address on its local network. Failure to do so may result in the node not participating in p2p duties. + +Running the command `curl ipv4.icanhazip.com` can retrieve your public IP address for you. +::: ## Run the node @@ -110,16 +116,16 @@ To verify the node is working, run these commands in another terminal window: ```console # Rule 1: For HTTP traffic on port 8080 -curl -X POST --data '{"method": "node_getL2Tips"}' +curl -X POST http://localhost:8080 --data '{"method": "node_getL2Tips"}' # should return JSON data in the format of "{"result":{"latest":{"number":"...}}}" # Rule 2: For TCP traffic on port 40400 (set by default) -nc -vz IP 40400 -# should return "Connection to IP 40400 port [tcp/*] succeeded!" if port open +nc -vz [YOUR_EXTERNAL_IP] 40400 +# should return "Connection to [YOUR_EXTERNAL_IP] 40400 port [tcp/*] succeeded!" if port open # Rule 3: For UDP traffic on port 40400 (set by default) -nc - vu IP 40400 -# should return "Connection to IP 40400 port [udp/*] succeeded!" if port open +nc -vu [YOUR_EXTERNAL_IP] 40400 +# should return "Connection to [YOUR_EXTERNAL_IP] 40400 port [udp/*] succeeded!" if port open ``` Congrats, the node should be up, running, and connected to the network! diff --git a/docs/versioned_docs/version-v2.0.2/the_aztec_network/reference/operator_faq.md b/docs/versioned_docs/version-v2.0.2/the_aztec_network/reference/operator_faq.md index d70a1f771bf6..ebdf90ac64c0 100644 --- a/docs/versioned_docs/version-v2.0.2/the_aztec_network/reference/operator_faq.md +++ b/docs/versioned_docs/version-v2.0.2/the_aztec_network/reference/operator_faq.md @@ -16,9 +16,9 @@ Here is a list of common issues node operators may face. If you don't find your If it is regarding a beacon call, it has failed to the beacon rpc call. If it is regarding the execution endpoint, then it is likely just reporting. -## Update aztec alpha-testnet version +## Update aztec testnet version -To make sure you're using the latest version, run: `aztec-up alpha-testnet`, then restart your node. +To make sure you're using the latest version, run: `aztec-up latest`, then restart your node. ## "rpc rate", "quota limit" @@ -42,6 +42,6 @@ Ignore. `ERROR: world-state:database Call SYNC_BLOCK failed: Error: Can't synch block: block state does not match world state` - Stop aztec -- Delete current snapshot: `rm -rf ~/.aztec/1.2.0/data/archiver` +- Delete current snapshot: `rm -rf ~/.aztec/2.0.2/data/archiver` - Update to latest version: `aztec-up -v latest` - Start aztec diff --git a/docs/versioned_docs/version-v2.0.2/the_aztec_network/reference/reacting_to_upgrades.md b/docs/versioned_docs/version-v2.0.2/the_aztec_network/reference/reacting_to_upgrades.md index a1507ceb843a..32caaa45efbd 100644 --- a/docs/versioned_docs/version-v2.0.2/the_aztec_network/reference/reacting_to_upgrades.md +++ b/docs/versioned_docs/version-v2.0.2/the_aztec_network/reference/reacting_to_upgrades.md @@ -11,7 +11,7 @@ This is a guide for sequencer operators to understand how to react to protocol u To signal for governance upgrades, sequencers must set their `GOVERNANCE_PROPOSER_PAYLOAD` on their sequencer node to the address of a `payload`. This will register their signal with the GovernanceProposer contract. :::info -the `payload` is a contract on L1 that specifies the address of the new rollup contract to be upgraded to. The payloads to be voted on during alpha-testnet will be communicated to sequencers on the forum and on community channels like discord. +the `payload` is a contract on L1 that specifies the address of the new rollup contract to be upgraded to. The payloads to be voted on during testnet will be communicated to sequencers on the forum and on community channels like discord. ::: This signalling phase will pass once `N` sequencers in a round of `M` L2 blocks have signalled for the same payload. Once the quorum is met, anyone can call the `executeProposal(roundNumber)` function on the Governance Proposer contract to advance the upgrade into the next stage. diff --git a/docs/versioned_docs/version-v2.0.2/the_aztec_network/reference/useful_commands.md b/docs/versioned_docs/version-v2.0.2/the_aztec_network/reference/useful_commands.md index bac4ea535565..2a8066fd1c49 100644 --- a/docs/versioned_docs/version-v2.0.2/the_aztec_network/reference/useful_commands.md +++ b/docs/versioned_docs/version-v2.0.2/the_aztec_network/reference/useful_commands.md @@ -18,7 +18,7 @@ These commands are useful to sequencer operators. If you're trying to do somethi The Registry contract is your entrypoint into almost all other contracts for a particular deployment of the Aztec Network. Armed with this address, you can retrieve almost all other useful contracts. -Assume there are two "deployments" of Aztec i.e. an `alpha-testnet` and a `ignition-testnet`. Then each deployment will have a unique Registry contract that does not change with upgrades. If a governance upgrade on `alpha-testnet` deploys a new rollup contract, the Registry contract for the `alpha-testnet` deployment will not change. +Assume there are two "deployments" of Aztec i.e. an `testnet` and a `ignition-testnet`. Then each deployment will have a unique Registry contract that does not change with upgrades. If a governance upgrade on `testnet` deploys a new rollup contract, the Registry contract for the `testnet` deployment will not change. diff --git a/docs/versioned_docs/version-v2.0.3/the_aztec_network/guides/run_nodes/how_to_run_prover.md b/docs/versioned_docs/version-v2.0.3/the_aztec_network/guides/run_nodes/how_to_run_prover.md index 8660b2902c51..e68abd8ddfd7 100644 --- a/docs/versioned_docs/version-v2.0.3/the_aztec_network/guides/run_nodes/how_to_run_prover.md +++ b/docs/versioned_docs/version-v2.0.3/the_aztec_network/guides/run_nodes/how_to_run_prover.md @@ -1,6 +1,6 @@ --- sidebar_position: 3 -title: How to Run a Prover Node +title: How to Run an Aztec Prover description: A comprehensive guide to setting up and running an Aztec Prover node on testnet or mainnet, including hardware requirements, configuration options, and performance optimization tips. keywords: [ @@ -23,115 +23,274 @@ tags: - infrastructure --- -import { AztecTestnetVersion } from '@site/src/components/Snippets/general_snippets'; - ## Background -Prover nodes are a critical part of the Aztec network's infrastructure. They generate cryptographic proofs that attest to the correctness of public transactions, ultimately producing a single rollup proof that is submitted to Ethereum. +This guide covers the steps required to run a prover on the Aztec network. Before you begin, you should understand that operating a prover is a resource-intensive role typically undertaken by experienced engineers due to its technical complexity and hardware requirements. -Operating a prover node requires a solid grasp of blockchain protocols, cryptographic systems, DevOps best practices, and high-performance hardware. It’s a resource-intensive role typically undertaken by experienced engineers or specialized teams due to its technical and operational complexity. +Aztec provers are critical infrastructure components that generate cryptographic proofs attesting to transaction correctness, ultimately producing a single rollup proof submitted to Ethereum. -## Prerequisites +The prover consists of three main components: -Before following this guide, make sure you: +1. **Prover node**: Polls L1 for unproven epochs, creates proving jobs, distributes them to the broker, and submits the final rollup proof to the rollup contract. -- Have the `aztec` tool [installed](../../../developers/getting_started/getting_started_on_sandbox.md#install-the-sandbox) -- Have sufficient hardware resources for proving operations -- Your confidence level is expected to be around "I'd be able to run a Prover _without_ this guide" +2. **Prover broker**: Manages the job queue, distributing work to agents and collecting results. -## Understanding Prover Architecture +3. **Prover agent(s)**: Executes proof generation jobs in a stateless manner. -The Aztec prover involves three key components: the Prover Node, the Proving Broker, and the Proving Agent. +## Prerequisites + +The minimum hardware specifications for each of the components is listed below. #### Prover Node -The Prover Node is responsible for polling the L1 for unproven epochs and initiating the proof process. When an epoch is ready to be proven, the prover node creates proving jobs and distributes them to the broker. The Prover Node is also responsible for submitting the final rollup proof to the rollup contract. +Minimum specifications: -- **Resources**: Up to 8 cores, 16GB RAM, ~1TB disk for storing state. +- 2 core / 4 vCPU +- 16 GB RAM +- 1 TB NVMe SSD +- 25 Mbps network connection #### Proving Broker -Manages a queue of proving jobs, distributing them to available agents and forwarding results back to the node. +Minimum specifications: -- **Resources**: Up to 4 cores, 16GB RAM, ~1GB disk. +- 2 core / 4 vCPU +- 16 GB RAM +- 10 GB SSD #### Proving Agents -Executes the actual proof jobs. Agents are stateless, fetch work from the broker, and return the results. +Minimum specifications: + +- 32 core / 64 vCPU +- 128 GB RAM +- 10 GB SSD + +This guide outlines a basic, non-distributed setup with all components on a single machine. Your hardware must meet or exceed the proving agent requirements listed above. + +This guide assumes you are using a standard Linux distribution (Debian or Ubuntu). + +### Required Software + +- Docker and the Aztec toolchain installed via aztec-up (see the [getting started section](../../index.md)) +- Docker Compose ([installation guide](https://docs.docker.com/compose/install/)) +- Access to L1 node endpoints (execution and consensus clients). See [Eth Docker's guide](https://ethdocker.com/Usage/QuickStart) if you need to set these up. + +## Configure the Prover + +Setting up a prover involves configuring three components through environment variables and Docker Compose. + +### Setup Steps + +1. Configure components via environment variables +2. Enable auto-update and auto-restart functionality +3. Deploy with Docker Compose + +First, create the directory structure for prover data storage: + +```sh +mkdir -p aztec-prover/prover-node-data aztec-prover/prover-broker-data +cd aztec-prover +touch .env +``` + +### Component Configuration -- **Resources**: Each agent may use up to 16 cores and 128GB RAM. +Each prover component requires specific environment variables. Configure them as follows: + +#### Prover Node + +Required environment variables: + +- `DATA_DIRECTORY`: the folder where the data of the prover node is stored +- `P2P_IP`: the IP address of this prover node +- `P2P_PORT`: the port that P2P communication happens on +- `ETHEREUM_HOSTS`: the execution RPC endpoints +- `L1_CONSENSUS_HOST_URLS`: the consensus RPC endpoints +- `LOG_LEVEL`: the desired level of logging for the prover node. It defaults to `INFO` +- `PROVER_BROKER_HOST`: the endpoint of the prover broker that this node sends prover jobs to +- `PROVER_PUBLISHER_PRIVATE_KEY`: the private key of the Ethereum EOA used for publishing the proofs to L1 +- `AZTEC_PORT`: the port that the prover node API is exposed on + +Add the following to your `.env` file (assuming default ports of 8080 for the prover node, and 40400 for p2p connectivity): + +```sh +DATA_DIRECTORY=./prover-node-data +P2P_IP= +P2P_PORT=40400 +ETHEREUM_HOSTS= +L1_CONSENSUS_HOST_URLS= +LOG_LEVEL=info +PROVER_BROKER_HOST=http://prover-broker:8080 +PROVER_PUBLISHER_PRIVATE_KEY= +AZTEC_PORT=8080 +``` + +**Note**: The broker URL `http://prover-broker:8080` references the Docker Compose service name defined later. + +:::tip +You MUST forward ports for P2P connectivity. Configure your router to forward both UDP and TCP traffic on the port specified by `P2P_PORT` to your local IP address. + +To find your public IP address, run: `curl ipv4.icanhazip.com` +::: + +#### Prover Broker + +Required environment variables: + +- `DATA_DIRECTORY`: the folder where the data of the prover broker is stored +- `LOG_LEVEL`: the desired level of logging for the prover broker. It defaults to `INFO` +- `ETHEREUM_HOSTS`: the execution RPC endpoints +- `P2P_IP`: the IP address of this prover broker +- `P2P_PORT`: the port that P2P communication happens on + +**Note**: Some variables overlap with the prover node configuration. If running components on separate machines, adjust accordingly. Since `DATA_DIRECTORY` is used by both components, define a separate variable for the broker: + +Add to your `.env` file: + +```sh +PROVER_BROKER_DATA_DIRECTORY=./prover-broker-data +``` -## Setting Up Your Prover +#### Prover Agent -### Using Docker Compose +Required environment variables: + +- `PROVER_AGENT_COUNT`: Number of agents to run (each requires ~10GB RAM) +- `PROVER_AGENT_POLL_INTERVAL_MS`: Polling interval for job requests (milliseconds) +- `PROVER_BROKER_HOST`: Broker endpoint for job submission +- `PROVER_ID`: Ethereum address corresponding to `PROVER_PUBLISHER_PRIVATE_KEY` + +**Note**: Some variables overlap with the prover node configuration. In this case we use the same value for `PROVER_BROKER_HOST`, so we will not duplicate it in our `.env` file. + +Add to your `.env` file: + +```sh +PROVER_AGENT_COUNT=10 +PROVER_AGENT_POLL_INTERVAL_MS=10000 +PROVER_ID= +``` + +### Enable Auto-Update and Auto-Restart + +The prover's auto-update functionality is critical for network coordination. This background module enables: + +- Configuration updates across all nodes +- Automated image updates via controlled shutdowns +- Rapid hot-fix deployment +- Coordinated resets after governance upgrades + +**Important**: Do NOT set `AUTO_UPDATE_URL` or `AUTO_UPDATE` environment variables. These must use their default values for proper operation. + +Since Docker Compose doesn't respect pull policies on container restarts, install Watchtower for automatic updates: + +```sh +docker run -d \ + --name watchtower \ + -v /var/run/docker.sock:/var/run/docker.sock \ + containrrr/watchtower +``` + +### Deploy with Docker Compose + +Create a `docker-compose.yml` file in your `aztec-prover` directory with the following content: ```yml name: aztec-prover services: prover-node: - image: aztecprotocol/aztec:latest # Always refer to the docs to check that you're using the correct image. - command: - - node - - --no-warnings - - /usr/src/yarn-project/aztec/dest/bin/index.js - - start - - --prover-node - - --archiver - - --network - - alpha-testnet + image: aztecprotocol/aztec:latest + entrypoint: >- + node + --no-warnings + /usr/src/yarn-project/aztec/dest/bin/index.js + start + --prover-node + --archiver + --network testnet depends_on: - broker: + prover-broker: condition: service_started required: true environment: - # PROVER_COORDINATION_NODE_URL: "http://:8080" # this can point to your own validator - using this replaces the need for the prover node to be on the P2P network and uses your validator as a sentry node of some sort. - # P2P_ENABLED: "false" # Switch to false if you provide a PROVER_COORDINATION_NODE_URL - DATA_DIRECTORY: /data - DATA_STORE_MAP_SIZE_KB: "134217728" - ETHEREUM_HOSTS: # EL RPC endpoint - L1_CONSENSUS_HOST_URLS: # CL RPC endpoint - LOG_LEVEL: info - PROVER_BROKER_HOST: http://broker:8080 - PROVER_PUBLISHER_PRIVATE_KEY: # The node needs to publish proofs to L1. Replace with your private key + DATA_DIRECTORY: /var/lib/data + ETHEREUM_HOSTS: ${ETHEREUM_HOSTS} + L1_CONSENSUS_HOST_URLS: ${L1_CONSENSUS_HOST_URLS} + LOG_LEVEL: ${LOG_LEVEL} + PROVER_BROKER_HOST: ${PROVER_BROKER_HOST} + PROVER_PUBLISHER_PRIVATE_KEY: ${PROVER_PUBLISHER_PRIVATE_KEY} + P2P_IP: ${P2P_IP} + P2P_PORT: ${P2P_PORT} + AZTEC_PORT: ${AZTEC_PORT} ports: - - "8080:8080" - - "40400:40400" - - "40400:40400/udp" + - ${AZTEC_PORT}:${AZTEC_PORT} + - ${P2P_PORT}:${P2P_PORT} + - ${P2P_PORT}:${P2P_PORT}/udp volumes: - - /home/my-node/node:/data # Local directory - - agent: - image: aztecprotocol/aztec:latest # Always refer to the docs to check that you're using the correct image. - command: - - node - - --no-warnings - - /usr/src/yarn-project/aztec/dest/bin/index.js - - start - - --prover-agent - - --network - - alpha-testnet + - ${DATA_DIRECTORY}:/var/lib/data + + prover-broker: + image: aztecprotocol/aztec:latest + entrypoint: >- + node + --no-warnings + /usr/src/yarn-project/aztec/dest/bin/index.js + start + --prover-broker + --network testnet environment: - PROVER_AGENT_COUNT: "1" - PROVER_AGENT_POLL_INTERVAL_MS: "10000" # Just to reduce the log spamming if you're using debug logging. - PROVER_BROKER_HOST: http://broker:8080 - PROVER_ID: # this should be the address corresponding to the PROVER_PUBLISHER_PRIVATE_KEY you set on the node. + DATA_DIRECTORY: /var/lib/data + ETHEREUM_HOSTS: ${ETHEREUM_HOSTS} + P2P_IP: ${P2P_IP} + LOG_LEVEL: ${LOG_LEVEL} + volumes: + - ${PROVER_BROKER_DATA_DIRECTORY}:/var/lib/data + + prover-agent: + image: aztecprotocol/aztec:latest + entrypoint: >- + node + --no-warnings + /usr/src/yarn-project/aztec/dest/bin/index.js + start + --prover-agent + --network testnet + environment: + PROVER_AGENT_COUNT: ${PROVER_AGENT_COUNT} + PROVER_AGENT_POLL_INTERVAL_MS: ${PROVER_AGENT_POLL_INTERVAL_MS} + PROVER_BROKER_HOST: ${PROVER_BROKER_HOST} + PROVER_ID: ${PROVER_ID} pull_policy: always restart: unless-stopped +``` - broker: - image: aztecprotocol/aztec:latest # Always refer to the docs to check that you're using the correct image. - command: - - node - - --no-warnings - - /usr/src/yarn-project/aztec/dest/bin/index.js - - start - - --prover-broker - - --network - - alpha-testnet - environment: - DATA_DIRECTORY: /data - ETHEREUM_HOSTS: # Your EL RPC endpoint - LOG_LEVEL: info - volumes: - - /home/my-node/node:/data # Local directory +**Note**: This configuration includes only essential settings. The `--network testnet` flag applies network-specific defaults. See the [CLI reference](../../reference/cli_reference.md) for all available options. + +Start the prover: + +```sh +docker compose up -d +``` + +## Verification + +To verify your prover is running correctly: + +1. Check that all services are running: + +```sh +docker compose ps +``` + +2. View logs for each component: + +```sh +# Prover node logs +docker compose logs -f prover-node + +# Broker logs +docker compose logs -f prover-broker + +# Agent logs +docker compose logs -f prover-agent ``` diff --git a/docs/versioned_docs/version-v2.0.3/the_aztec_network/guides/run_nodes/how_to_run_sequencer.md b/docs/versioned_docs/version-v2.0.3/the_aztec_network/guides/run_nodes/how_to_run_sequencer.md index 7b91300e317a..917dd59e1e1f 100644 --- a/docs/versioned_docs/version-v2.0.3/the_aztec_network/guides/run_nodes/how_to_run_sequencer.md +++ b/docs/versioned_docs/version-v2.0.3/the_aztec_network/guides/run_nodes/how_to_run_sequencer.md @@ -24,280 +24,253 @@ tags: ## Background +This guide covers the steps required to run a sequencer node on the Aztec network. + The Aztec sequencer node is critical infrastructure responsible for ordering transactions and producing blocks. -The sequencer node takes part in three key actions: +The sequencer node performs three key actions: -1. Assemble unprocessed transactions and propose the next block -2. Attest to correct execution of txs in the proposed block (if part of validator committee) -3. Submit the successfully attested block to L1 +1. Assembles unprocessed transactions and proposes the next block +2. Attests to correct execution of transactions in proposed blocks (when part of the sequencer committee) +3. Submits successfully attested blocks to L1 -When transactions are sent to the Aztec network, sequencer nodes bundles them into blocks, checking various constraints such as gas limits, block size, and transaction validity. Before a block can be published, it must be validated by a committee of other sequencer nodes (validators in this context) who re-execute public transactions and verify private function proofs so they can attest to correct execution. These validators attest to the block's validity by signing it, and once enough attestations are collected (two-thirds of the committee plus one), the sequencer can submit the block to L1. +Sequencer nodes bundle transactions into blocks while checking constraints like gas limits, block size, and validity. 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. The archiver component complements this process by maintaining historical chain data. It continuously monitors L1 for new blocks, processes them, and maintains a synchronized view of the chain state. This includes managing contract data, transaction logs, and L1-to-L2 messages, making it essential for network synchronization and data availability. -## Setup - -### Requirements - -A computer running Linux or MacOS with the following specifictions: - -- CPU: 8-cores -- RAM: 16 GiB -- Storage: 1 TB SSD +## Prerequisites -A Network connection of at least 25 Mbps up/down. +Minimum hardware requirements: -### Installation +- 2 core / 4 vCPU +- 16 GB RAM +- 1TB NVMe SSD +- 25 Mbps network connection -import { General, Fees } from '@site/src/components/Snippets/general_snippets'; +Please note that these requirements are subject to change as the network throughput increases. - +This guide assumes you are using a standard Linux distribution (Debian or Ubuntu). -Now install the latest testnet version of aztec: `aztec-up -v latest` +### Required Software -Join the [Discord](https://discord.gg/aztec) to connect with the community and get help with your setup. +- Docker and the Aztec toolchain installed via aztec-up (see the [getting started section](../../index.md)) +- Docker Compose ([installation guide](https://docs.docker.com/compose/install/)) +- Access to L1 node endpoints (execution and consensus clients). See [Eth Docker's guide](https://ethdocker.com/Usage/QuickStart) if you need to set these up. -## Sequencer Quickstart +## Configure the Sequencer -With the alpha-testnet version of the aztec tools, you now need to define required variables for your node. +Setting up a sequencer involves configuring keys, environment variables, and Docker Compose. -The following variable names are specific to the `aztec start` command, set them as variables in the terminal or inline before the command. +### Setup Steps -- `ETHEREUM_HOSTS=`: One or more comma-separated public rpc provider url(s). NB - don't share your access token -- `L1_CONSENSUS_HOST_URLS=`: One or more comma-separated public rpc provider url(s) that supports consensus client requests -- `VALIDATOR_PRIVATE_KEY="Ox"`: Private key of testnet L1 EOA that holds Sepolia ETH (0.01 Sepolia ETH can get you started) -- `COINBASE="0x"`: Recipient of block rewards (for node security on mainnet, this should be a different address to the validator eoa) -- `P2P_IP="x.x.x.x"`: IP address of computer running the node (you can get this by running, `curl api.ipify.org`, on your node) +1. Define private keys and accounts for sequencer duties +2. Configure node settings via environment variables +3. Enable auto-update and auto-restart functionality +4. Deploy with Docker Compose -Now in a terminal start your node as a sequencer and archiver: +First, create the directory structure for sequencer data storage: -If the above variables are set you can simply use: `aztec start --node --archiver --sequencer --network testnet` - -Otherwise you can specify values via the CLI flags (using values in place of the variable names): - -```bash -aztec start --node --archiver --sequencer \ - --network testnet \ - --l1-rpc-urls $ETHEREUM_HOSTS \ - --l1-consensus-host-urls $L1_CONSENSUS_HOST_URLS \ - --sequencer.validatorPrivateKeys $VALIDATOR_PRIVATE_KEY \ - --sequencer.coinbase $COINBASE \ - --p2p.p2pIp $P2P_IP +```sh +mkdir -p aztec-sequencer/keys aztec-sequencer/data +cd aztec-sequencer +touch .env ``` -**Additional Parameters**: The comprehensive list of parameters can be seen via: `aztec help start`. For example: +### Define Private Keys and Accounts -``` ---p2p.p2pPort (default: 40400) ($P2P_PORT) - The port for the P2P service. -``` +Sequencers require private keys to identify themselves as valid proposers or attesters. Configure these through a keystore file. -### Port forwarding +Create a `keystore.json` file in your `aztec-sequencer/keys` folder: -For some restricted environments, you may need to explicity forward the p2p port (default: 40400) to your local node ip address. - -This is often in a router's advanced network settings if required. - -### Next steps - -To add your sequencer you'll need the following few values, as well as `ETHEREUM_HOSTS` from before: - -- `STAKING_ASSET_HANDLER="0xF739D03e98e23A7B65940848aBA8921fF3bAc4b2"`: Constant L1 contract address -- `L1_CHAIN_ID="11155111"`: Sepolia chainid -- `PRIVATE_KEY="0x`: private key of account with sepolia eth to make transaction (eg can use funded validator key) - -Then run the aztec command to add your address as an L1 validator, with rpc url(s) for Etheruem L1 execution requests: - -```bash -aztec add-l1-validator --staking-asset-handler=0xF739D03e98e23A7B65940848aBA8921fF3bAc4b2 \ - --l1-rpc-urls $ETHEREUM_HOSTS \ - --l1-chain-id 11155111 \ - --private-key "0x" \ - --attester "0x" \ - --proposer-eoa "0x" +```json +{ + "schemaVersion": 1, + "validators": [ + { + "attester": ["ETH_PRIVATE_KEY_0"], + "publisher": ["ETH_PRIVATE_KEY_1"], + "coinbase": "ETH_ADDRESS_2", + "feeRecipient": "AZTEC_ADDRESS_0" + } + ] +} ``` -**Tip**: Use `aztec help add-l1-validator` for further parameter details. - -:::note Validator Quota Filled - -In the absence of real-world staking incentives, becoming a validator is throttled with time, so you may see `ValidatorQuotaFilledUntil(uint256 _timestamp)` at the beginning of the text returned. - -The timestamp is when the next round of sequencers can be added as validators, so try again right after that. - -::: - -## Deeper dive - -This guide will describe how to setup your sequencer using the `aztec start` command. For more advanced setups, refer to the Advanced Configuration section below. - -The `aztec start` tool is a one-stop-shop for running your sequencer on any Aztec Network. It assigns default values to several config variables based on a `--network` flag and launches a docker container running the sequencer software. - -To use the `aztec start` command, you need to obtain the following: - -#### RPCs - -- An L1 execution client (for reading transactions and state). It can be specified via the `--l1-rpc-urls` flag when using `aztec start` or via the env var `ETHEREUM_HOSTS`. Popular execution clients include [Geth](https://geth.ethereum.org/) or [Nethermind](https://nethermind.io/). You can run your own node or use a service like [Alchemy](https://www.alchemy.com/) or [Infura](https://www.infura.io/). - -- An L1 consensus client (for blobs). It can be specified via the `--l1-consensus-host-urls` flag when using `aztec start` or via the env var `L1_CONSENSUS_HOST_URLS`. Popular consensus clients include [Lighthouse](https://lighthouse.sigmaprime.io/) or [Prysm](https://prysmaticlabs.com/). Not all RPC providers support consensus endpoints, [Quicknode](https://www.quicknode.com/) and [dRPC](https://drpc.org/) have been known to work for consensus endpoints. - -- To reduce load on your consensus endpoint, the Aztec sequencer supports an optional remote server that serves blobs to the client. This is often called a "blob sink" or "blob storage service". You can pass your own or use one provided by a trusted party via the `--sequencer.blobSinkUrl` flag when using `aztec start`, or via the env var `BLOB_SINK_URL`. Some providers like [Alchemy](https://www.alchemy.com/) offer blob storage services as part of their infrastructure offerings. - -#### Ethereum Keys +The keystore defines keys and addresses for sequencer operation: -You will need an Ethereum private key and the corresponding public address. The private key is set via the `--sequencer.validatorPrivateKeys` flag while the public address should be specified via the `--sequencer.coinbase ` flag. +- `attester`: Private key for signing block proposals and attestations. The corresponding Ethereum address identifies the sequencer. +- `publisher`: Private key for sending block proposals to L1. Defaults to attester key if not set. +- `coinbase`: Ethereum address receiving L1 rewards and fees. Defaults to attester address if not set. +- `feeRecipient`: Aztec address receiving unburnt transaction fees from blocks. -The private key is needed as your validator will post blocks to Ethereum, and the public address will be the recipient of any block rewards. +Replace the placeholder values with your actual keys and addresses. -Disclaimer: you may want to generate and use a new Ethereum private key. +### Node Configuration -#### Networking +Required environment variables: -You MUST forward your ports. Your router must send UDP and TCP traffic on port `40400` (unless you changed the default) to your IP address on your local network. Failure to do so may result in your sequencer not participating on the p2p network. +- `DATA_DIRECTORY`: the folder where the data of the sequencer is stored +- `KEY_STORE_DIRECTORY`: can be a path to the file or directory where keystores are located. In our case it is the path to the folder containing the `keystore.json` file created above +- `LOG_LEVEL`: the desired level of logging for the sequencer. It defaults to `INFO`. +- `ETHEREUM_HOSTS`: The execution RPC endpoints +- `L1_CONSENSUS_HOST_URLS`: The consensus RPC endpoints +- `P2P_IP`: The IP address of this sequencer +- `P2P_PORT`: The port that P2P communication happens on +- `AZTEC_PORT`: The port that the sequencer node API is exposed on -As a tip, configure your router to give your MAC address the same IP address every time it does a DHCP refresh. +Add the following to your `.env` file (using default ports 8080 and 40400): -You also need to grab your external IP address and pass it along to the `--p2p.p2pIp` when using `aztec start`. - -#### Sepolia ETH - -You'll need Sepolia ETH to cover gas costs. Here are some options: - -- Use a PoW faucet like [Sepolia PoW Faucet](https://sepolia-faucet.pk910.de/) -- Ask in our Discord community (and remember to pay it forward when you can!) - -### Now Start Your Sequencer - -To boot up a sequencer using `aztec start`, run the following command: - -```bash -aztec start --node --archiver --sequencer \ - --network testnet \ - --l1-rpc-urls https://example.com \ - --l1-consensus-host-urls https://example.com \ - --sequencer.validatorPrivateKeys 0xYourPrivateKey \ - --sequencer.coinbase 0xYourAddress \ - --p2p.p2pIp 999.99.999.99 \ - --p2p.maxTxPoolSize 1000000000 +```sh +DATA_DIRECTORY=./data +KEY_STORE_DIRECTORY=./keys +LOG_LEVEL=info +ETHEREUM_HOSTS= +L1_CONSENSUS_HOST_URLS= +P2P_IP= +P2P_PORT=40400 +AZTEC_PORT=8080 ``` :::tip +You MUST forward ports for P2P connectivity. Configure your router to forward both UDP and TCP traffic on the port specified by `P2P_PORT` to your local IP address. -For a full overview of all available commands, check out the [CLI reference sheet](../../reference/cli_reference.md). +To find your public IP address, run: `curl ipv4.icanhazip.com` ::: -:::tip +### Enable Auto-Update and Auto-Restart -If you are unable to determine your public ip. Running the command `curl ipv4.icanhazip.com` can retrieve it for you. -::: +The sequencer's auto-update functionality is critical for network coordination. This background module enables: + +- Configuration updates across all nodes +- Automated image updates via controlled shutdowns +- Rapid hot-fix deployment +- Coordinated resets after governance upgrades -### Register as a Validator +**Important**: Do NOT set `AUTO_UPDATE_URL` or `AUTO_UPDATE` environment variables. These must use their default values for proper operation. -Once your node is fully synced, you can register as a validator using the `add-l1-validator` command: +Since Docker Compose doesn't respect pull policies on container restarts, install Watchtower for automatic updates: -```bash -aztec add-l1-validator \ - --l1-rpc-urls https://eth-sepolia.g.example.com/example/your-key \ - --private-key your-private-key \ - --attester your-validator-address \ - --proposer-eoa your-validator-address \ - --staking-asset-handler 0xF739D03e98e23A7B65940848aBA8921fF3bAc4b2 \ - --l1-chain-id 11155111 +```sh +docker run -d \ + --name watchtower \ + -v /var/run/docker.sock:/var/run/docker.sock \ + containrrr/watchtower ``` -:::warning +### Deploy with Docker Compose -You may see a warning when trying to register as a validator. To maintain network health there is a daily quota for validators to join the validator set. If you are not able to join, it could mean that today's quota of validators has already been added to the set. If you see this, you can try again later. Read [our blog post](https://aztec.network/blog/what-is-aztec-testnet) for more info. +Create a `docker-compose.yml` file in your `aztec-sequencer` directory: -::: +```yaml +services: + aztec-sequencer: + image: "aztecprotocol/aztec:latest" + 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} + P2P_IP: ${P2P_IP} + P2P_PORT: ${P2P_PORT} + AZTEC_PORT: ${AZTEC_PORT} + entrypoint: >- + node + --no-warnings + /usr/src/yarn-project/aztec/dest/bin/index.js + start + --node + --archiver + --sequencer + --network testnet + networks: + - aztec + restart: always + +networks: + aztec: + name: aztec +``` -## Advanced Configuration +**Note**: This configuration includes only essential settings. The `--network testnet` flag applies network-specific defaults. See the [CLI reference](../../reference/cli_reference.md) for all available options. -### Using Environment Variables +Start the sequencer: -Every flag in the `aztec start` command corresponds to an environment variable. You can see the variable names by running `aztec start --help`. A reference is provided [here](../../reference/cli_reference.md). +```sh +docker compose up -d +``` -For example: +## Verification -- `--l1-rpc-urls` maps to `ETHEREUM_HOSTS` -- `--l1-consensus-host-urls` maps to `L1_CONSENSUS_HOSTS_URLS` +To verify your sequencer is running correctly: -You can create a `.env` file with these variables: +1. Check the current sync status (this may take a few minutes): -```bash -ETHEREUM_HOSTS=https://example.com -L1_CONSENSUS_HOST_URLS=https://example.com -# Add other configuration variables as needed +```sh +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" ``` -Then source this file before running your command: +Compare the output with block explorers like [Aztec Scan](https://aztecscan.xyz/) or [Aztec Explorer](https://aztecexplorer.xyz/). -```bash -source .env -aztec start --network testnet --archiver --node --sequencer # other flags... -``` +2. View sequencer logs: -### Using a Docker Compose - -If you would like to run in a docker compose, you can use a configuration like the one below: +```sh +docker compose logs -f aztec-sequencer +``` -```yml -name: aztec-node -services: - node: - network_mode: host # Optional, run with host networking - image: aztecprotocol/aztec:latest - environment: - ETHEREUM_HOSTS: "" - L1_CONSENSUS_HOST_URLS: "" - DATA_DIRECTORY: /data - VALIDATOR_PRIVATE_KEY: $VALIDATOR_PRIVATE_KEY - P2P_IP: $P2P_IP - LOG_LEVEL: debug - entrypoint: > - sh -c 'node --no-warnings /usr/src/yarn-project/aztec/dest/bin/index.js start --network testnet start --node --archiver --sequencer' - ports: - - 40400:40400/tcp - - 40400:40400/udp - - 8080:8080 +3. Check node status: - volumes: - - /home/my-node/node:/data # Local directory +```sh +curl http://localhost:8080/status ``` ## Troubleshooting -### L1 Access +### Common Issues -If you're hosting your own Ethereum execution or consensus client locally (rather than using an external RPC like Alchemy), you need to ensure that the prover node inside Docker can reach it. +**Port forwarding not working:** -By default, Docker runs containers on a bridge network that isolates them from the host machine's network interfaces. This means localhost inside the container won't point to the host's localhost. +- Verify your external IP address matches the `P2P_IP` setting +- Check firewall rules on your router and local machine +- Test connectivity using: `nc -zv ` -To fix this: +**Sequencer not syncing:** -Option 1: Use the special hostname host.docker.internal -This tells Docker to route traffic from the container to the host machine. For example: +- Check L1 endpoint connectivity +- Verify both execution and consensus clients are fully synced +- Review logs for specific error messages -```bash ---l1-rpc-urls http://host.docker.internal:8545 -``` +**Keystore issues:** -Option 2: Add a host network entry to your Docker Compose file (advanced users) -This gives your container direct access to the host's network stack, but removes Docker's network isolation. Add to your `docker-compose.yml` +- Ensure keystore.json is properly formatted +- Verify private keys are valid Ethereum private keys +- Check file permissions on the keys directory -```yaml -network_mode: "host" -``` +**Docker issues:** -⚠️ Note: network_mode: "host" only works on Linux. On macOS and Windows, use `host.docker.internal`. +- Ensure Docker and Docker Compose are up to date +- Check disk space availability +- Verify container has sufficient resources -:::info +## Join the Sequencer Set -You can run your own Sepolia ETH Node. However, at the moment only [`geth`](https://github.com/ethereum/go-ethereum) and [`reth`](https://github.com/paradigmxyz/reth) nodes are confirmed to work reliably with the Aztec client. +After setting up your node, you must request to be added to the sequencer set. -::: +Complete the onboarding process at [testnet.aztec.network](https://testnet.aztec.network) using zkPassport. -Once you have your node running, head to the [Aztec Discord](https://discord.gg/aztec) to interact with other network operators. +## Next Steps -Happy sequencing! +- Monitor your sequencer's performance and attestation rate +- Join the [Aztec Discord](https://discord.gg/aztec) for operator support +- Review [Reacting to Upgrades](../../reference/reacting_to_upgrades.md) guide +- Consider implementing monitoring and alerting for production deployments diff --git a/docs/versioned_docs/version-v2.0.3/the_aztec_network/index.md b/docs/versioned_docs/version-v2.0.3/the_aztec_network/index.md index 517502d8175f..6d7ebd1f3ad0 100644 --- a/docs/versioned_docs/version-v2.0.3/the_aztec_network/index.md +++ b/docs/versioned_docs/version-v2.0.3/the_aztec_network/index.md @@ -5,6 +5,8 @@ title: Running a Full Node description: A guide about how to run a full node on the Aztec network. --- +## Background + This guide will go over the steps required to run a full node on Aztec with a basic setup. A full node allows users to connect and interact with the network. It provides users an interface to send and receive transactions and state updates without relying on a third party. @@ -18,24 +20,24 @@ Please note that there are two other types of nodes available that we are not co Minimum hardware requirements: - 2 core / 4 vCPU -- 8 GB RAM -- 10 GB SDD +- 16 GB RAM +- 1 TB NVMe SDD - 25 Mbps network connection Please note that these requirements are subject to change as the network throughput increases. -Along with the above minimum hardware requirements, it is assumed that the user has access to a performant ethereum RPC endpoint. Furthermore, this guide expects the user to be using a "standard" Linux distribution like Debian / Ubuntu when following along with the steps. +Along with the above minimum hardware requirements, it is assumed that the user has access to a performant Ethereum RPC endpoint. Furthermore, this guide expects the user to be using a "standard" Linux distribution like Debian / Ubuntu when following along with the steps. -Overview +## Overview 1. Install Docker -2. Install aztec +2. Install Aztec 3. Configure the node 4. Start the node! ## Install and set up Docker -Please ensure that docker is installed. If not, here is a convenient way to install it. +Ensure Docker is installed. If not, here is a convenient way to install it. This uses the script at [https://get.docker.com/](https://get.docker.com/) to install the latest stable release of Docker on Linux: @@ -45,7 +47,7 @@ curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh ``` -Afterwards, the currently logged in user must be added to the docker group, so sudo is not needed to invoke docker. +Afterwards, the currently logged in user must be added to the docker group, so `sudo` is not needed to invoke docker. ```console sudo groupadd docker @@ -57,21 +59,21 @@ docker run hello-world ## Install Aztec -Run these commands to grab the aztec stack and add them to path. +Run these commands to grab the Aztec stack and add them to path. ```console bash -i <(curl -s https://install.aztec.network) # Users should check that it is installed by using ls ~/.aztec/bin -# aztec, aztec-up aztec-nargo and aztec-wallet should show up here +# aztec, aztec-up, aztec-nargo and aztec-wallet should show up here echo 'export PATH="$HOME/.aztec/bin:$PATH"' >> ~/.bashrc source ~/.bashrc ``` -The next step is to install the correct version of aztec that is running on testnet. The correct version of the aztec network currently is `1.2.0`. If that is not the version that was installed in the previous step, please run this to ensure the correct version is installed. +The next step is to install the correct version of aztec that is running on testnet. The correct version of the aztec network currently is `2.0.3`. If that is not the version that was installed in the previous step, please run this to ensure the correct version is installed. ```console -aztec-up 1.2.0 +aztec-up 2.0.3 ``` The user can confirm that they are running on the correct version with: @@ -88,17 +90,21 @@ Now that the correct version of the node is installed, it needs to be configured mkdir aztec-node && cd ./aztec-node ``` -Next, set some required configuration options. This guide will use `custom_named` environment variables (e.g. `AZTEC_NODE_P2P_IP`) but this is not necessary; you can pass valued directly into the command without specifying them as environment variables. The external IP address of the node, and the L1 RPC endpoints must be defined when starting a node. Also, configuration defining the network version should be set, as this will let the node define the other required protocol variables, like rollup address, registry address etc. Please note that the specified RPC endpoints must support high throughput, otherwise the node will suffer degraded performance. +Next, set some required configuration options. This guide will use `custom_named` environment variables (e.g. `AZTEC_NODE_P2P_IP`) but this is not necessary; you can pass values directly into the command without specifying them as environment variables. The external IP address of the node, and the L1 RPC endpoints must be defined when starting a node. Also, configuration defining the network version should be set, as this will let the node define the other required protocol variables, like rollup address, registry address etc. Note that the specified RPC endpoints must support high throughput, otherwise the node will suffer degraded performance. ```console -# If the external IP of the machine the node is running on is unknown, it can be obtained by running `curl ifconfig.me`. -export AZTEC_NODE_P2P_IP=IP export AZTEC_NODE_NETWORK=testnet +export AZTEC_NODE_P2P_IP=IP export AZTEC_NODE_ETH_HOSTS= export AZTEC_NODE_CONSENSUS_HOSTS= ``` -Finally, the ports used by the node must be accessible to other Aztec nodes on the internet. This will require disabling the firewall for and / or forwarding these ports. The router must be able to send UDP and TCP traffic on port 40400 (unless the defaults were changed) to the node IP address on its local network. Failure to do so may result in the node not participating in p2p duties. +:::tip + +The ports used by the node must be accessible to other Aztec nodes on the internet. This will require disabling the firewall for and / or forwarding these ports. The router must be able to send UDP and TCP traffic on port 40400 (unless the defaults were changed) to the node IP address on its local network. Failure to do so may result in the node not participating in p2p duties. + +Running the command `curl ipv4.icanhazip.com` can retrieve your public IP address for you. +::: ## Run the node @@ -110,16 +116,16 @@ To verify the node is working, run these commands in another terminal window: ```console # Rule 1: For HTTP traffic on port 8080 -curl -X POST --data '{"method": "node_getL2Tips"}' +curl -X POST http://localhost:8080 --data '{"method": "node_getL2Tips"}' # should return JSON data in the format of "{"result":{"latest":{"number":"...}}}" # Rule 2: For TCP traffic on port 40400 (set by default) -nc -vz IP 40400 -# should return "Connection to IP 40400 port [tcp/*] succeeded!" if port open +nc -vz [YOUR_EXTERNAL_IP] 40400 +# should return "Connection to [YOUR_EXTERNAL_IP] 40400 port [tcp/*] succeeded!" if port open # Rule 3: For UDP traffic on port 40400 (set by default) -nc - vu IP 40400 -# should return "Connection to IP 40400 port [udp/*] succeeded!" if port open +nc -vu [YOUR_EXTERNAL_IP] 40400 +# should return "Connection to [YOUR_EXTERNAL_IP] 40400 port [udp/*] succeeded!" if port open ``` Congrats, the node should be up, running, and connected to the network! diff --git a/docs/versioned_docs/version-v2.0.3/the_aztec_network/reference/operator_faq.md b/docs/versioned_docs/version-v2.0.3/the_aztec_network/reference/operator_faq.md index d70a1f771bf6..7ae875e8cee0 100644 --- a/docs/versioned_docs/version-v2.0.3/the_aztec_network/reference/operator_faq.md +++ b/docs/versioned_docs/version-v2.0.3/the_aztec_network/reference/operator_faq.md @@ -16,9 +16,9 @@ Here is a list of common issues node operators may face. If you don't find your If it is regarding a beacon call, it has failed to the beacon rpc call. If it is regarding the execution endpoint, then it is likely just reporting. -## Update aztec alpha-testnet version +## Update aztec testnet version -To make sure you're using the latest version, run: `aztec-up alpha-testnet`, then restart your node. +To make sure you're using the latest version, run: `aztec-up latest`, then restart your node. ## "rpc rate", "quota limit" @@ -42,6 +42,6 @@ Ignore. `ERROR: world-state:database Call SYNC_BLOCK failed: Error: Can't synch block: block state does not match world state` - Stop aztec -- Delete current snapshot: `rm -rf ~/.aztec/1.2.0/data/archiver` +- Delete current snapshot: `rm -rf ~/.aztec/2.0.3/data/archiver` - Update to latest version: `aztec-up -v latest` - Start aztec diff --git a/docs/versioned_docs/version-v2.0.3/the_aztec_network/reference/reacting_to_upgrades.md b/docs/versioned_docs/version-v2.0.3/the_aztec_network/reference/reacting_to_upgrades.md index a1507ceb843a..32caaa45efbd 100644 --- a/docs/versioned_docs/version-v2.0.3/the_aztec_network/reference/reacting_to_upgrades.md +++ b/docs/versioned_docs/version-v2.0.3/the_aztec_network/reference/reacting_to_upgrades.md @@ -11,7 +11,7 @@ This is a guide for sequencer operators to understand how to react to protocol u To signal for governance upgrades, sequencers must set their `GOVERNANCE_PROPOSER_PAYLOAD` on their sequencer node to the address of a `payload`. This will register their signal with the GovernanceProposer contract. :::info -the `payload` is a contract on L1 that specifies the address of the new rollup contract to be upgraded to. The payloads to be voted on during alpha-testnet will be communicated to sequencers on the forum and on community channels like discord. +the `payload` is a contract on L1 that specifies the address of the new rollup contract to be upgraded to. The payloads to be voted on during testnet will be communicated to sequencers on the forum and on community channels like discord. ::: This signalling phase will pass once `N` sequencers in a round of `M` L2 blocks have signalled for the same payload. Once the quorum is met, anyone can call the `executeProposal(roundNumber)` function on the Governance Proposer contract to advance the upgrade into the next stage. diff --git a/docs/versioned_docs/version-v2.0.3/the_aztec_network/reference/useful_commands.md b/docs/versioned_docs/version-v2.0.3/the_aztec_network/reference/useful_commands.md index bac4ea535565..2a8066fd1c49 100644 --- a/docs/versioned_docs/version-v2.0.3/the_aztec_network/reference/useful_commands.md +++ b/docs/versioned_docs/version-v2.0.3/the_aztec_network/reference/useful_commands.md @@ -18,7 +18,7 @@ These commands are useful to sequencer operators. If you're trying to do somethi The Registry contract is your entrypoint into almost all other contracts for a particular deployment of the Aztec Network. Armed with this address, you can retrieve almost all other useful contracts. -Assume there are two "deployments" of Aztec i.e. an `alpha-testnet` and a `ignition-testnet`. Then each deployment will have a unique Registry contract that does not change with upgrades. If a governance upgrade on `alpha-testnet` deploys a new rollup contract, the Registry contract for the `alpha-testnet` deployment will not change. +Assume there are two "deployments" of Aztec i.e. an `testnet` and a `ignition-testnet`. Then each deployment will have a unique Registry contract that does not change with upgrades. If a governance upgrade on `testnet` deploys a new rollup contract, the Registry contract for the `testnet` deployment will not change.