feat(docs): run prover first draft (#17094)

Author: AztecBot

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,66 +23,182 @@ 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.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
 
-#### Prover Node
+The minimum hardware specifications for each of the components is listed below.
 
-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.
+#### Prover Node
 
 Minimum specifications:
 
 - 2 core / 4 vCPU
 - 16 GB RAM
-- 1 TB NVMe SDD
+- 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:
 
 - 2 core / 4 vCPU
 - 16 GB RAM
-- 10 GB SDD
+- 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 SDD
+- 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
+
+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=<your external IP address>
+P2P_PORT=40400
+ETHEREUM_HOSTS=<your L1 execution endpoint, or a comma separated list if you have multiple>
+L1_CONSENSUS_HOST_URLS=<your L1 consensus endpoint, or a comma separated list if you have multiple>
+LOG_LEVEL=info
+PROVER_BROKER_HOST=http://prover-broker:8080
+PROVER_PUBLISHER_PRIVATE_KEY=<the private key of the L1 EOA your prover will publish proofs from>
+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`
+
+Add to your `.env` file:
+
+```sh
+PROVER_AGENT_COUNT=10
+PROVER_AGENT_POLL_INTERVAL_MS=10000
+PROVER_BROKER_HOST=http://prover-broker:8080
+PROVER_ID=<the address corresponding to the PROVER_PUBLISHER_PRIVATE_KEY you set on the node>
+```
+
+### 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.
+    image: aztecprotocol/aztec:latest
     command:
       - node
       - --no-warnings
@@ -93,58 +209,89 @@ services:
       - --network
       - alpha-testnet
     depends_on:
-      broker:
+      prover-broker:
         condition: service_started
         required: true
     environment:
-      # PROVER_COORDINATION_NODE_URL: "http://:8080" # this can point to your own sequencer - using this replaces the need for the prover node to be on the P2P network and uses your sequencer 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_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
+      - ${DATA_DIRECTORY}:/var/lib/data
 
-  agent:
-    image: aztecprotocol/aztec:latest # Always refer to the docs to check that you're using the correct image.
+  prover-broker:
+    image: aztecprotocol/aztec:latest
     command:
       - node
       - --no-warnings
       - /usr/src/yarn-project/aztec/dest/bin/index.js
       - start
-      - --prover-agent
+      - --prover-broker
       - --network
       - alpha-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.
-    pull_policy: always
-    restart: unless-stopped
+      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
 
-  broker:
-    image: aztecprotocol/aztec:latest # Always refer to the docs to check that you're using the correct image.
+  prover-agent:
+    image: aztecprotocol/aztec:latest
     command:
       - node
       - --no-warnings
       - /usr/src/yarn-project/aztec/dest/bin/index.js
       - start
-      - --prover-broker
+      - --prover-agent
       - --network
       - alpha-testnet
     environment:
-      DATA_DIRECTORY: /data
-      ETHEREUM_HOSTS: # Your EL RPC endpoint
-      LOG_LEVEL: info
-    volumes:
-      - /home/my-node/node:/data # Local directory
+      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
+```
+
+**Note**: This configuration includes only essential settings. The `--network alpha-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
 ```