Merge branch 'testnet' into staging

Author: JuArce

docs/2_architecture/2_aggregation_mode.md

@@ -2,7 +2,7 @@
 
 Aligned's Proof Aggregation Service introduces a scalable solution: compressing multiple proofs into one using recursion, drastically reducing verification costs while maintaining Ethereum-level security. This is our second major product, following the Proof Verification Layer, and is designed to give developers flexible, cost-efficient infrastructure for proving systems.
 
-Aggregation Service allows developers to submit individual ZK proofs to Aligned’s Verification Layer; the ones that can be aggregated are then batched and passed to the Aggregation Service. The service generates a single recursive proof that attests to the validity of these proofs. This final proof is then submitted and verified on Ethereum. By aggregating many proofs into one, the cost of on-chain verification is amortized across the batch—developers effectively pay a fraction of the full price, plus a small aggregation fee.
+The Proof Aggregation Service is a standalone service, independent from the Proof Verification Layer. Developers submit their ZK proofs directly to the Aggregation Service, where they are aggregated in a single recursive proof that attests to the validity of all the proofs. This final proof is then submitted and verified on Ethereum. By aggregating many proofs into one, the cost of on-chain verification is amortized across the batch—developers effectively pay a fraction of the full price, plus a small aggregation fee.
 
 ![Figure 1: Proof Aggregation Service](../images/aligned_proof_aggregation_service.png)
 

docs/3_guides/1.3_SDK_api_reference_aggregation.md

@@ -1,36 +1,230 @@
-# Aligned SDK
+# Aggregation Mode SDK
 
-## API Reference for aggregation mode
+## API Reference
 
-### `is_proof_verified_in_aggregation_mode`
+### `AggregationModeGatewayProvider`
 
-Checks if the proof has been verified with Aligned Aggregation Mode.
+The gateway provider handles communication with the Aggregation Mode Gateway for submitting proofs and querying proof status.
+
+---
+
+### `AggregationModeGatewayProvider::new`
+
+Creates a new gateway provider without a signer. Useful for read-only operations like checking nonces or receipts.
+
+```rust
+pub fn new(network: Network) -> Result<Self, GatewayError>
+```
+
+#### Arguments
+
+- `network` - The network to connect to (`Devnet | Hoodi | Mainnet`)
+
+#### Returns
+
+- `Result<AggregationModeGatewayProvider, GatewayError>` - A gateway provider instance or an error.
+
+---
+
+### `AggregationModeGatewayProvider::new_with_signer`
+
+Creates a new gateway provider with a signer. Required for submitting proofs.
+
+```rust
+pub fn new_with_signer(network: Network, signer: S) -> Result<Self, GatewayError>
+```
+
+#### Arguments
+
+- `network` - The network to connect to (`Devnet | Hoodi | Mainnet`)
+- `signer` - A signer implementing the `Signer` trait (e.g., `PrivateKeySigner`)
+
+#### Returns
+
+- `Result<AggregationModeGatewayProvider, GatewayError>` - A gateway provider instance or an error.
+
+---
+
+### `get_nonce_for`
+
+Retrieves the current nonce for a given address.
+
+```rust
+pub async fn get_nonce_for(
+    &self,
+    address: String,
+) -> Result<GatewayResponse<NonceResponse>, GatewayError>
+```
+
+#### Arguments
+
+- `address` - The Ethereum address to query the nonce for.
+
+#### Returns
+
+- `Result<GatewayResponse<NonceResponse>, GatewayError>` - The nonce response or an error.
+
+---
+
+### `get_receipts_for`
+
+Retrieves proof submission receipts for a given address.
+
+```rust
+pub async fn get_receipts_for(
+    &self,
+    address: String,
+    nonce: Option<u64>,
+) -> Result<GatewayResponse<ReceiptsResponse>, GatewayError>
+```
+
+#### Arguments
+
+- `address` - The Ethereum address to query receipts for.
+- `nonce` - Optional nonce to filter receipts by a specific submission.
+
+#### Returns
+
+- `Result<GatewayResponse<ReceiptsResponse>, GatewayError>` - The receipts response or an error.
+
+---
+
+### `submit_sp1_proof`
+
+Submits an SP1 proof to the Aggregation Mode Gateway.
 
 ```rust
-pub async fn is_proof_verified_in_aggregation_mode(
+pub async fn submit_sp1_proof(
+    &self,
+    proof: &SP1ProofWithPublicValues,
+    vk: &SP1VerifyingKey,
+) -> Result<GatewayResponse<SubmitProofResponse>, GatewayError>
+```
+
+#### Arguments
+
+- `proof` - The SP1 proof with public values.
+- `vk` - The SP1 verifying key.
+
+#### Returns
+
+- `Result<GatewayResponse<SubmitProofResponse>, GatewayError>` - The submission response containing a task ID, or an error.
+
+#### Errors
+
+- `SignerNotConfigured` - If the provider was created without a signer.
+- `ProofSerialization` - If there is an error serializing the proof or verifying key.
+- `MessageSignature` - If there is an error signing the submission message.
+- `Request` - If there is a network error communicating with the gateway.
+- `Api` - If the gateway returns an error response.
+
+---
+
+### `ProofAggregationServiceProvider`
+
+The blockchain provider handles verification of proofs on-chain by querying the AlignedProofAggregationService contract.
+
+---
+
+### `ProofAggregationServiceProvider::new`
+
+Creates a new blockchain provider for verifying proofs on-chain.
+
+```rust
+pub fn new(network: Network, rpc_url: String, beacon_client_url: String) -> Self
+```
+
+#### Arguments
+
+- `network` - The network to connect to (`Devnet | Hoodi | Mainnet`)
+- `rpc_url` - The Ethereum RPC provider URL.
+- `beacon_client_url` - The Beacon chain client URL.
+
+#### Returns
+
+- `ProofAggregationServiceProvider` - A blockchain provider instance.
+
+---
+
+### `check_proof_verification`
+
+Checks if a proof has been verified on-chain.
+
+```rust
+pub async fn check_proof_verification(
+    &self,
+    from_block: Option<u64>,
     verification_data: AggregationModeVerificationData,
-    network: Network,
-    eth_rpc_url: &str,
-    beacon_client_url: &str,
-    from_block: Option<u64>
-) -> Result<[u8; 32], ProofVerificationAggModeError>
+) -> Result<ProofStatus, ProofVerificationAggModeError>
 ```
 
 #### Arguments
 
--   `verification_data` - The verification data needed based on the provided proving system.
--   `network` - The network on which the verification will be done (`devnet | holesky | mainnet | hoodi`)
--   `eth_rpc_url` - The URL of the Ethereum RPC node.
+- `from_block` - Optional block number to start searching from. Defaults to current block minus 7500 blocks (~25 hours).
+- `verification_data` - The verification data containing the proving system type, verifying key hash, and public inputs.
 
 #### Returns
 
--   `Result<[u8; 32], ProofVerificationAggModeError>` - The merkle root of the aggregated proof.
+- `Result<ProofStatus, ProofVerificationAggModeError>` - The proof status or an error.
+
+#### Proof Status
+
+- `Verified { merkle_path, merkle_root }` - The proof was found and verified in an aggregated batch.
+- `Invalid` - The proof was found but Merkle root verification failed.
+- `NotFound` - The proof was not found in any aggregated batch.
 
 #### Errors
 
--   `ProvingSystemNotSupportedInAggMode` if the proving system is not supported (Currently, only SP1 compressed proofs are supported).
--   `EthereumProviderError` if there is an error in the Ethereum call.
--   `BeaconClient` if there is an error in the Beacon client call.
--   `UnmatchedBlobAndEventMerkleRoot` if the proof was in included in the blob but the merkle root did not match with the one in the contract
--   `ProofNotFoundInLogs` if the proof was not found in any of the aggregated proofs from the specified block_number
--   `EventDecoding`: if it failed to decode an event from the ProofAggregationService
+- `EthereumProviderError` - If there is an error communicating with the Ethereum RPC.
+- `BeaconClient` - If there is an error communicating with the Beacon chain.
+- `EventDecoding` - If there is an error decoding the on-chain event data.
+
+---
+
+## Types
+
+### `Network`
+
+```rust
+pub enum Network {
+    Devnet,   // Chain ID: 31337
+    Hoodi,    // Chain ID: 560048
+    Mainnet,  // Chain ID: 1
+}
+```
+
+### `AggregationModeVerificationData`
+
+```rust
+pub enum AggregationModeVerificationData {
+    SP1 {
+        vk: [u8; 32],
+        public_inputs: Vec<u8>,
+    },
+}
+```
+
+### `GatewayError`
+
+```rust
+pub enum GatewayError {
+    Request(String),
+    Api { status: u16, message: String },
+    SignerNotConfigured,
+    ProofSerialization(String),
+    MessageSignature(String),
+}
+```
+
+### `ProofStatus`
+
+```rust
+pub enum ProofStatus {
+    Verified {
+        merkle_path: Vec<[u8; 32]>,
+        merkle_root: [u8; 32],
+    },
+    Invalid,
+    NotFound,
+}
+```