diff --git a/docs/2_architecture/agg_mode_components/1_deep_dive.md b/docs/2_architecture/agg_mode_components/1_deep_dive.md index 7ffca70105..f415d0a2f6 100644 --- a/docs/2_architecture/agg_mode_components/1_deep_dive.md +++ b/docs/2_architecture/agg_mode_components/1_deep_dive.md @@ -1,64 +1,192 @@ # Proof Aggregation Service Deep Dive -The Proof Aggregation Service runs **once every 24 hours** and performs the following steps: - -1. **Fetch Proofs from the Verification Layer** - Queries `NewBatchV3` events from the `AlignedLayerServiceManager` and downloads the batches from `S3`, starting from the last processed block of the previous run. - -2. **Filter Proofs** - Filters proofs by supported verifiers and proof types. - -3. **Aggregate Proofs in the zkVM** - Selected proofs are aggregated using a zkVM. - -4. **Construct the Blob** - A blob is built containing the [commitments](#proof-commitment) of the aggregated proofs. - -5. **Send Aggregated Proof** - The final aggregated proof and its blob are sent to the `AlignedProofAggregationService` contract for verification. - -> [Note] -> Currently if you want your proof to be verified in the `AggregationMode` you need to submit it via the `VerificationLayer`. In the future, users will have the option to choose whether they want to continue using this method or switch to using only the Aggregation service. - -## Aggregators and Supported Proof Types - -Two separate aggregators are run every 24 hours: - -- **Risc0**: Aggregates proofs of types `Composite` and `Succinct`. -- **SP1**: Aggregates proofs of type `Compressed`. +## Architecture Overview + +The Proof Aggregation Service consists of three main components that work together to aggregate user proofs and submit them on-chain. + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ PROOF AGGREGATION SERVICE │ +└─────────────────────────────────────────────────────────────────────────────┘ + + ┌──────────┐ ┌───────────────────────────────┐ + │ User │ │ AggregationModePaymentService │ + │ │ │ (Contract) │ + └────┬─────┘ └───────────────┬───────────────┘ + │ │ + │ 1. Deposit ETH │ + │──────────────────────────────>│ + │ │ + │ │ Payment Event + │ │ + ┌────┴─────┐ ┌───────────────┴───────────────┐ + │ User │ │ Payments Poller │ + │ │ │ │ + └────┬─────┘ └───────────────┬───────────────┘ + │ │ + │ │ 2. Monitor payments + │ │ Update quotas + │ │ + │ ┌───────────────┴───────────────┐ + │ │ PostgreSQL DB │ + │ │ │ + │ └───────────────┬───────────────┘ + │ │ + ┌────┴─────┐ ┌───────────────┴───────────────┐ + │ User │ │ Gateway │ + │ │ │ │ + └────┬─────┘ └───────────────┬───────────────┘ + │ │ + │ 3. Submit proof │ + │──────────────────────────────>│ + │ │ + │ │ 4. Verify & Store + │ │ proof in DB + │ │ + │ ┌───────────────┴───────────────┐ + │ │ Proof Aggregator │ + │ │ │ + │ └───────────────┬───────────────┘ + │ │ + │ │ 5. Fetch pending proofs + │ │ 6. Aggregate in zkVM + │ │ + │ ┌───────────────┴───────────────┐ + │ │ AlignedProofAggregationService│ + │ │ (Contract) │ + │ └───────────────────────────────┘ + │ │ + │ │ 7. Submit aggregated + │ │ proof on-chain + │ │ + └──────────┘ +``` + +## Workflow + +### Step 1: User Payment + +Users deposit ETH into the **AggregationModePaymentService** contract to obtain quota for submitting proofs. + +``` +┌──────────┐ ┌─────────────────────────────────┐ +│ User │───── deposit() ───>│ AggregationModePaymentService │ +└──────────┘ └─────────────────────────────────┘ +``` + +### Step 2: Payments Poller Updates Quotas + +The **Payments Poller** monitors the `AggregationModePaymentService` contract for deposit events and updates user quotas in the database. + +``` +┌─────────────────────────────────┐ ┌──────────────┐ ┌──────────┐ +│ AggregationModePaymentService │──event─>│ Payments │──update─>│ DB │ +│ │ │ Poller │ quota │ │ +└─────────────────────────────────┘ └──────────────┘ └──────────┘ +``` + +### Step 3: User Submits Proof to Gateway + +Users submit their proofs to the **Gateway** via HTTP API. The gateway: + +1. Verifies the user has sufficient quota +2. Validates the proof format and signature +3. Verifies the proof is valid (SP1 compressed proof) + +``` +┌──────────┐ ┌──────────────┐ +│ User │───── submit() ────>│ Gateway │ +│ │<──── receipt ──────│ │ +└──────────┘ └──────────────┘ +``` + +### Step 4: Gateway Stores Proof in Database + +After validation, the gateway stores the proof in PostgreSQL for later aggregation. + +``` +┌──────────────┐ ┌──────────────┐ +│ Gateway │───── store ───>│ PostgreSQL │ +│ │ proof │ DB │ +└──────────────┘ └──────────────┘ +``` + +### Step 5: Proof Aggregator Processes Proofs + +The **Proof Aggregator** runs periodically (every 24 hours) and: + +1. Fetches pending proofs from the database +2. Filters proofs by supported verifiers +3. Aggregates proofs using the zkVM +4. Constructs a blob with proof commitments +5. Submits the aggregated proof on-chain + +``` +┌──────────────┐ ┌──────────────┐ ┌─────────────────────────────────┐ +│ PostgreSQL │──fetch─>│ Proof │──submit─>│ AlignedProofAggregationService │ +│ DB │ │ Aggregator │ │ │ +└──────────────┘ └──────────────┘ └─────────────────────────────────┘ +``` + +## Supported Proof Types + +The aggregation service currently supports: + +- **SP1**: Aggregates proofs of type `Compressed` ## Proof Commitment The **proof commitment** is a hash that uniquely identifies a proof. It is defined as the keccak of the proof public inputs + program ID: -- **For SP1**: +- **For SP1**: The commitment is computed as: `keccak(proof_public_inputs_bytes || vk_hash_bytes)` -- **For Risc0**: - The commitment is computed as: `keccack(receipt_public_inputs_bytes || image_id_bytes)` ## Multilayer Aggregation -To scale aggregation without exhausting zkVM memory, aggregation is split in two programs: - -1. **User Proof Aggregator** - Processes chunks of `n` user proofs. Each run creates an aggregated proof that commits to a Merkle root of the user proofs inputs. This step is repeated for as many chunks as needed. Usually each chunks contains `256` proofs but it can be lowered based on the machine specs. - -2. **Chunk Aggregator** +To scale aggregation without exhausting zkVM memory, aggregation is split into two programs: + +``` + User Proofs (n per chunk) + │ + ┌───────────────────────┼───────────────────────┐ + │ │ │ + ▼ ▼ ▼ + ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ + │ Chunk 1 │ │ Chunk 2 │ │ Chunk N │ + │ Aggregator │ │ Aggregator │ │ Aggregator │ + └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ + │ │ │ + │ Aggregated Proofs + Merkle Roots │ + │ │ │ + └───────────────────────┼───────────────────────┘ + │ + ▼ + ┌─────────────────┐ + │ Chunk │ + │ Aggregator │ + └────────┬────────┘ + │ + ▼ + ┌─────────────────┐ + │ Final Proof + │ + │ Merkle Root │ + └─────────────────┘ +``` + +1. **User Proof Aggregator** + Processes chunks of `n` user proofs. Each run creates an aggregated proof that commits to a Merkle root of the user proofs inputs. This step is repeated for as many chunks as needed. Usually each chunk contains `256` proofs but it can be lowered based on the machine specs. + +2. **Chunk Aggregator** Aggregates all chunk-level proofs into a single final proof. It receives: - The chunked proofs - - The original [proofs commitments](#proof-commitment) included each chunk received + - The original [proofs commitments](#proof-commitment) included in each chunk received - During verification, it checks that each chunk’s committed Merkle root matches the reconstructed root to ensure input correctness. The final Merkle root, representing all user [proofs commitments](#proof-commitment), is then committed as a public input. + During verification, it checks that each chunk's committed Merkle root matches the reconstructed root to ensure input correctness. The final Merkle root, representing all user [proofs commitments](#proof-commitment), is then committed as a public input. ## Verification -Once aggregated, the proof is sent to Ethereum and verified via the `AlignedProofAggregationService` contract. Depending on the proving system, the contract invokes: - -- `verifySP1` for SP1 proofs -- `verifyRisc0` for Risc0 proofs - -Each function receives: +Once aggregated, the proof is sent to Ethereum and verified via the `AlignedProofAggregationService` contract. The contract invokes `verifySP1` which receives: - The public inputs - The proof binary @@ -69,17 +197,17 @@ If verification succeeds, the new proof is added to the `aggregatedProofs` map i ### Proof Inclusion Verification -To verify a user’s proof on-chain, the following must be provided: +To verify a user's proof on-chain, the following must be provided: - The proof bytes - The proof public inputs -- The program ID +- The program ID (vk hash) - A Merkle proof -The Merkle root is computed and checked for existence in the contract using the `verifyProofInclusion` function of the `ProofAggregationServiceContract`, which: +The Merkle root is computed and checked for existence in the contract using the `verifyProofInclusion` function of the `AlignedProofAggregationService` contract, which: 1. Computes the merkle root -2. Returns `true` or `false` depending if there exists an `aggregatedProof` with the computed root. +2. Returns `true` or `false` depending on whether there exists an `aggregatedProof` with the computed root. ## Data Availability diff --git a/docs/3_guides/8_submitting_batch_without_batcher.md b/docs/3_guides/10_submitting_batch_without_batcher.md similarity index 100% rename from docs/3_guides/8_submitting_batch_without_batcher.md rename to docs/3_guides/10_submitting_batch_without_batcher.md diff --git a/docs/3_guides/7_setup_aligned_agg_mode.md b/docs/3_guides/7_setup_aligned_agg_mode.md new file mode 100644 index 0000000000..132b115fb3 --- /dev/null +++ b/docs/3_guides/7_setup_aligned_agg_mode.md @@ -0,0 +1,83 @@ +# Aligned Infrastructure Deployment Guide + +## Dependencies + +Ensure you have the following installed: + +- [Rust](https://www.rust-lang.org/tools/install) +- [Docker](https://docs.docker.com/get-docker/) +- [Kurtosis](https://docs.kurtosis.com/install/) + +## Supported Verifiers + +The aggregation mode currently supports the following proving systems: + +- **SP1** - Succinct's zkVM (compressed proofs) + +## Step-by-Step Setup + +Follow these steps to start the aggregation mode locally using the Ethereum package environment. + +### 1. Start the Ethereum Package + +Start the local Ethereum network using Kurtosis: + +```bash +make ethereum_package_start +``` + +This command spins up a local Ethereum network with all necessary components. To stop it run: + +```bash +make ethereum_package_rm +``` + +### 2. Start the Gateway + +Start the aggregation mode gateway service: + +```bash +make agg_mode_gateway_start_ethereum_package +``` + +The gateway handles proof submissions and manages the proof queue. This command also starts the required Docker containers (PostgreSQL) and runs database migrations automatically. + +### 3. Start the Payments Poller + +In a separate terminal, start the payments poller: + +```bash +make agg_mode_payments_poller_start_ethereum_package +``` + +The payments poller monitors the blockchain for payment events and updates user quotas accordingly. + +### 4. Send a Payment (Deposit) + +Deposit funds to get quota for submitting proofs: + +```bash +make agg_mode_gateway_send_payment +``` + +This deposits funds using a default test account. For custom deposits, you can use the CLI directly. + +### 5. Submit a Proof + +Submit an SP1 proof to the gateway: + +```bash +make agg_mode_gateway_send_sp1_proof +``` + +This sends a test SP1 Fibonacci proof to the gateway. + +### 6. Start the Proof Aggregator + +In a separate terminal, start the proof aggregator: + +```bash +AGGREGATOR=sp1 make proof_aggregator_start_ethereum_package +``` + +The proof aggregator fetches pending proofs from the database, aggregates them, and submits the aggregated proof on-chain. diff --git a/docs/3_guides/7_contract_addresses.md b/docs/3_guides/8_contract_addresses.md similarity index 100% rename from docs/3_guides/7_contract_addresses.md rename to docs/3_guides/8_contract_addresses.md