samaharam 0.2.0

# Samaharam (സമാഹാരം)

> **സമാഹാരം** (samahāram) — Malayalam for "aggregation" or "collection"

**Samaharam** is a high-performance Rust library for aggregating heterogeneous zero-knowledge proofs into a single proof for efficient on-chain verification on EVM chains.

## Features

- **True KZG Aggregation**: Aggregates multiple proofs into a single constant-size proof (132 bytes)
- **Groth16 Support**: Native compatibility with **snarkjs/circom** proofs
- **SRS Support**: Parse `.ptau` ceremony files directly
- **Gas Optimized**: Reduces verification cost by **~93%** (e.g., 3 proofs cost ~45k gas total vs ~642k individually)
- **BN254 Curve**: Native support for EVM precompiles (ECADD, ECMUL, ECPAIRING)
- **Solidity Verifier Generation**: Automatically generate deployable verifier contracts
- **Parallel Processing**: Optional rayon-based parallelism for high throughput

## Quick Start

```rust
use samaharam::{Bn254, client::{AggregationClient, ProofRequest}, config::Srs};
use std::sync::Arc;

// Initialize with SRS (parse from .ptau file)
let srs = Arc::new(Srs::<Bn254>::from_ptau("pot12_final.ptau")?);
let mut client = AggregationClient::new(srs)?;

// Register the circuit verification key
let vk = ...; // Load your verification key
let circuit_id = client.register_circuit("payment_circuit", vk);

// Submit proofs (e.g. from snarkjs)
// proof_data is the JSON output from snarkjs
client.submit(ProofRequest {
    circuit_type: "payment_circuit".to_string(),
    proof_data: proof_bytes, 
    public_inputs: vec![input1, input2], 
})?;

// Aggregate
let result = client.aggregate_external()?;
println!("Aggregated {} proofs", result.proof_count);

// Generate Solidity Verifier
let sol_code = result.generate_solidity_verifier()?;
std::fs::write("SamaharamVerifier.sol", sol_code)?;
```

## Supported Proof Systems

Currently, Samaharam supports **Groth16** proofs generated by **snarkjs/circom**.

```rust
use samaharam::adapters::{SnarkjsProof, ExternalProof};

// Load proof from snarkjs JSON output
let proof = SnarkjsProof::from_json(json_data)?;

// Convert to internal accumulator instances
let instances = proof.to_accumulator_instances()?;
```

## Key Modules

| Module | Description |
|--------|-------------|
| `crypto::kzg` | KZG polynomial commitments with Pippenger MSM |
| `crypto::accumulator` | Proof folding with multi-pairing optimization |
| `adapters` | Import Groth16 proofs from snarkjs |
| `solidity::generator` | Generate Solidity verifier contracts |
| `client` | Ergonomic high-level API |

## Solidity Verifier

Samaharam generates a highly optimized Solidity verifier that uses the BN254 precompiles.

```solidity
// Optimized KZG pairing check (~45k gas)
function verifyKzg(
    uint256[2] calldata adjustedCommitment,
    uint256[2] calldata combinedQuotient
) external view returns (bool);
```

**Verification Logic**:
The verifier checks the pairing equation:
$$e(A, G_2) \cdot e(-Q, \tau G_2) = 1$$

Where:
- $A$ is the adjusted aggregated commitment
- $Q$ is the combined quotient
- $\tau$ is the trapdoor from the SRS
- $G_2$ is the generator of the G2 group

## Performance

### Gas Efficiency

Samaharam reduces on-chain verification costs by using Batched KZG. The aggregated proof size is constant regardless of the number of inputs.

| Verification Method | Pairings | Approx. Gas | Savings (vs 3 proofs) |
|---------------------|----------|-------------|----------|
| **Samaharam KZG** | **2** | **~45,000** | **~93%** |
| Standard Groth16 | 4 per proof | ~200,000+ | 0% |

*Note: Gas costs are estimates based on standard BN254 precompile costs.*

### Off-Chain Optimization

| Operation | Optimization |
|-----------|--------------|
| Multi-scalar multiplication | Pippenger's bucket method with adaptive window |
| Proof verification | Multi-pairing with shared final exponentiation |


## Security

See [docs/SECURITY.md](docs/SECURITY.md) for:
- VK registration trust model
- Threat vectors and mitigations
- On-chain protection recommendations

## Disclaimer

This software is provided "as is", without warranty of any kind, express or implied. The author(s) of this crate ([github.com/ronnakamoto](https://github.com/ronnakamoto)) shall not be held responsible for any damages, losses, or liabilities arising from the use of this software. Use at your own risk.

## License

Licensed under either of

 * Apache License, Version 2.0
   ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
 * MIT license
   ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

## Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.