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..293447af06 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,97 @@ # 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. + +``` +┌──────┐ ┌───────────────────────────────┐ ┌─────────────┐ +│ │ 1 │ AggregationModePaymentService │ 2 │ Payments │ +│ │--->│ (Contract) │--->│ Poller │ +│ │ └───────────────────────────────┘ └─────┬───────┘ +│ │ │ +│ │ 3 │ +│ │ v +│ │ ┌───────────────┐ 5 ┌──────────────┐ ┌───────────────────────────────┐ +│ User │ 4 │ Gateway │------------------>│ PostgreSQL │ │ AlignedProofAggregationService│ +│ │--->│ │ │ DB │ │ (Contract) │ +│ │ └───────────────┘ └──────────────┘ └───────────────────────────────┘ +│ │ ^ ^ +│ │ 6 │ │ +│ │ │ 7 │ +│ │ ┌─────────────┐ │ +│ │ │ Proof │-------------------┘ +│ │ │ Aggregator │ +└──────┘ └─────────────┘ +``` + +1. User deposits ETH into `AggregationModePaymentService` contract to get quota. +2. `Payments Poller` monitors the contract for deposit events. +3. `Payments Poller` updates user quotas in the database. +4. User submits proofs to the `Gateway`. +5. `Gateway` validates and stores proofs in the database. +6. `Proof Aggregator` fetches pending proofs from the database. +7. `Proof Aggregator` aggregates proofs in the zkVM and submits to `AlignedProofAggregationService` contract. + +## 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 +102,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/9_aligned_cli.md b/docs/3_guides/10_aligned_cli.md similarity index 100% rename from docs/3_guides/9_aligned_cli.md rename to docs/3_guides/10_aligned_cli.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 diff --git a/docs/3_guides/8_submitting_batch_without_batcher.md b/docs/3_guides/9_submitting_batch_without_batcher.md similarity index 100% rename from docs/3_guides/8_submitting_batch_without_batcher.md rename to docs/3_guides/9_submitting_batch_without_batcher.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index e533aacb31..bf34d9c7b2 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -35,9 +35,10 @@ * [Generating proofs for Aligned](3_guides/4_generating_proofs.md) * [Generating & submitting proofs of Rust code with ZKRust](3_guides/5_using_zkrust.md) * [Setup Aligned Infrastructure Locally](3_guides/6_setup_aligned.md) -* [Contract Addresses](3_guides/7_contract_addresses.md) -* [Submitting Batch Without Batcher](3_guides/8_submitting_batch_without_batcher.md) -* [Aligned CLI](3_guides/9_aligned_cli.md) +* [Setup Aligned Agg Mode Infrastructure Locally](3_guides/7_setup_aligned_agg_mode.md) +* [Contract Addresses](3_guides/8_contract_addresses.md) +* [Submitting Batch Without Batcher](3_guides/9_submitting_batch_without_batcher.md) +* [Aligned CLI](3_guides/10_aligned_cli.md) ## Operators