Merge pull request #49 from BrianSeong99/main

RE-MERGE Aggkit documentation

Author: arnavshah01

.gitignore

@@ -11,4 +11,6 @@ node_modules/
 *.iml
 temp_dir/
 package-lock.json
-package.json
+package.json
+.cursorindexingignore
+.specstory/

docs/agglayer/core-concepts/aggkit/architecture.md

@@ -0,0 +1,206 @@
+---
+title: Architecture
+---
+
+<!-- Page Header Component -->
+<h1 style="text-align: left; font-size: 38px; font-weight: 700; font-family: 'Inter Tight', sans-serif;">
+  Architecture
+</h1>
+
+<div style="text-align: left; margin: 0.5rem 0;">
+  <p style="font-size: 18px; color: #666; max-width: 600px; margin: 0;">
+    Discover how AggKit's ingenious architecture makes complex cross-chain synchronization feel effortless
+  </p>
+</div>
+
+## The Architecture Story: Building a Synchronization Symphony
+
+Imagine conducting an orchestra where the musicians are scattered across different buildings, in different time zones, playing different instruments, but they all need to stay perfectly synchronized to create beautiful music together. That's essentially the challenge AggKit solves for blockchain networks.
+
+Traditional blockchain architecture assumes you're dealing with a single network. But in the Agglayer ecosystem, you're dealing with **multiple sovereign chains** that each have their own rhythm, their own pace, their own way of doing things – yet they all need to work together seamlessly.
+
+AggKit's architecture is the **conductor's baton** that keeps everyone in perfect harmony.
+
+## The Three-Tier Architecture: How the Magic Happens
+
+Let's break down AggKit's architecture into three distinct tiers, each with its own purpose and personality:
+
+### Tier 1: Your Chain's Domain
+
+At the foundation, you have **your L2 chain** doing what it does best – processing transactions, executing smart contracts, maintaining state. This is your domain, where you have full sovereignty and control.
+
+When users perform bridge operations on your chain, several things happen simultaneously: bridge contracts emit events, state gets updated, and your chain needs to communicate these changes to the broader ecosystem. This is where AggKit steps in.
+
+### Tier 2: The AggKit Synchronization Orchestra
+
+In the middle tier, you have **AggKit components** working together like a well-orchestrated symphony. Each component has its specialized role, but they all coordinate to ensure seamless synchronization:
+
+![Aggkit](../../../img/agglayer/Aggkit.png)
+
+*Figure 1: The three-tier architecture – your chain, AggKit synchronization, and the broader ecosystem*
+
+### Tier 3: The Unified Ecosystem
+
+At the top tier, you have **the broader Agglayer ecosystem** – Agglayer itself, Ethereum L1, and all the other chains connected to the network. This is where the global state lives, where final settlement happens, and where the unified liquidity that makes everything possible is maintained.
+
+## Data Flow Architecture
+
+### The Two Essential Conversations
+
+Understanding AggKit's architecture means understanding the **two critical conversations** that keep everything synchronized:
+
+#### **Upward Flow: L2 → Agglayer**
+```mermaid
+sequenceDiagram
+    participant L2 as L2 Chain
+    participant BS as BridgeSync
+    participant L1S as L1InfoTreeSync
+    participant AS as AggSender
+    participant AL as Agglayer
+    
+    Note over L2,AL: Certificate Submission Flow
+    L2->>BS: Bridge Events
+    BS->>AS: Bridge Data
+    L1S->>AS: L1 Verification Data
+    AS->>AS: Build Certificate
+    AS->>AL: Submit Certificate
+    AL->>AL: Generate Pessimistic Proof
+    AL-->>AS: Certificate Status
+```
+
+**Purpose**: Submits L2 state transitions to Agglayer for validation and proof generation.
+
+**Components Involved**:
+
+- **BridgeSync**: Captures bridge events from L2 contracts
+- **L1InfoTreeSync**: Provides L1 verification data and Merkle proofs
+- **AggSender**: Packages data into signed certificates and submits to Agglayer
+
+#### **Downward Flow: Agglayer → L2**
+```mermaid
+sequenceDiagram
+    participant L1 as Ethereum L1
+    participant L1S as L1InfoTreeSync
+    participant AO as AggOracle
+    participant L2S as L2GERSync
+    participant L2 as L2 Chain
+    
+    Note over L1,L2: GER Propagation Flow
+    L1->>L1S: GER Update Event
+    L1S->>AO: New GER Available
+    AO->>L2: Inject GER
+    L2->>L2S: GER Injected Event
+    L2S->>L2S: Index GER Locally
+```
+
+**Purpose**: Propagates global state updates from Agglayer/L1 to L2 chains for claim verification.
+
+**Components Involved**:
+
+- **L1InfoTreeSync**: Monitors L1 for Global Exit Root updates
+- **AggOracle**: Propagates GER updates to L2 contracts (with v0.3.5 committee security)
+- **L2GERSync**: Indexes and manages GER state locally on L2
+
+## Component Interaction Patterns
+
+### **Certificate Generation Pattern**
+
+```mermaid
+graph LR
+    subgraph "Data Collection"
+        A[Bridge Events] --> D[Certificate Builder]
+        B[L1 Verification Data] --> D
+        C[Chain State] --> D
+    end
+    
+    subgraph "Certificate Processing"
+        D --> E[Sign Certificate]
+        E --> F[Submit to Agglayer]
+        F --> G[Monitor Status]
+    end
+    
+    subgraph "Error Handling"
+        G --> H{Certificate Status}
+        H -->|Success| I[Complete]
+        H -->|Error| J[Retry Logic]
+        J --> D
+    end
+    
+    style D fill:#e8f5e8
+    style F fill:#e3f2fd
+    style I fill:#f3e5f5
+```
+
+*Figure 2: Certificate generation and submission pattern*
+
+### **Oracle Propagation Pattern**
+
+```mermaid
+graph LR
+    subgraph "GER Detection"
+        A[Monitor L1] --> B[Detect New GER]
+        B --> C[Validate GER]
+    end
+    
+    subgraph "Committee Consensus (v0.3.5)"
+        C --> D{Committee Mode?}
+        D -->|Yes| E[Propose GER]
+        E --> F[Collect Votes]
+        F --> G{Quorum Met?}
+        G -->|Yes| H[Inject GER]
+        G -->|No| I[Wait for Votes]
+        I --> F
+        D -->|No| H
+    end
+    
+    subgraph "L2 Update"
+        H --> J[Update L2 Contract]
+        J --> K[Index Locally]
+    end
+    
+    style E fill:#fff3e0
+    style F fill:#fff3e0
+    style G fill:#fff3e0
+    style H fill:#e8f5e8
+```
+
+*Figure 3: GER propagation with v0.3.5 committee security*
+
+### **v0.3.5 Security Enhancements**
+
+The major architectural improvement in v0.3.5 is the **elimination of single-address vulnerabilities**:
+
+#### **Before v0.3.5: Single Point of Failure**
+```mermaid
+graph LR
+    L1[L1 GER Updates] --> Single[Single AggOracle]
+    Single --> L2[L2 GER Contract]
+    
+    style Single fill:#ffebee
+```
+
+**Risk**: Single compromised address could steal funds or mint unauthorized assets.
+
+#### **After v0.3.5: Distributed Security**
+```mermaid
+graph LR
+    L1[L1 GER Updates] --> Committee[AggOracle Committee]
+    
+    subgraph Committee
+        M1[Member 1]
+        M2[Member 2]
+        M3[Member 3]
+        Quorum[Threshold Quorum]
+    end
+    
+    M1 --> Quorum
+    M2 --> Quorum
+    M3 --> Quorum
+    Quorum --> L2[L2 GER Contract]
+    
+    style Committee fill:#e8f5e8
+    style Quorum fill:#e3f2fd
+```
+
+**Security**: Multiple parties must agree before any GER injection, eliminating single points of failure.
+

docs/agglayer/core-concepts/aggkit/components/aggchain-proof-gen.md

@@ -0,0 +1,86 @@
+---
+title: AggchainProofGen
+---
+
+<!-- Page Header Component -->
+<h1 style="text-align: left; font-size: 38px; font-weight: 700; font-family: 'Inter Tight', sans-serif;">
+  AggchainProofGen
+</h1>
+
+<div style="text-align: left; margin: 0.5rem 0;">
+  <p style="font-size: 18px; color: #666; max-width: 600px; margin: 0;">
+    Advanced proof generation service for aggregated chain operations and state transition verification
+  </p>
+</div>
+
+## Meet AggchainProofGen: The Security Expert
+
+AggchainProofGen is the **advanced security component** for chains that need mathematical proof of their operations' validity. While basic chains can use simple signature-based verification, some chains require comprehensive **[state transition proofs](../../state-transition-proof/index.md)** that verify both internal chain operations and cross-chain bridge activities.
+
+**Core Function**: AggchainProofGen generates sophisticated cryptographic proofs that demonstrate a chain's operations are mathematically valid and comply with all bridge security constraints. These proofs enable Agglayer's advanced dual proof system introduced in v0.3.
+
+## When You Need the Security Expert
+
+AggchainProofGen is **essential for chains requiring maximum security**:
+
+### **High-Value Environments**
+If your chain handles significant value, operates in regulatory environments, or requires mathematical certainty about operations, AggchainProofGen provides the advanced cryptographic proofs that basic signature verification cannot offer.
+
+### **Custom Consensus Chains**
+Chains with unique consensus mechanisms that need to prove their internal operations are valid use AggchainProofGen to generate comprehensive verification proofs that Agglayer can validate.
+
+### **Enterprise Deployments**
+Organizations requiring audit trails, compliance documentation, and mathematical proof of system correctness use AggchainProofGen to meet strict security and regulatory requirements.
+
+## How AggchainProofGen Works
+
+AggchainProofGen implements a **dual verification system** that validates both internal chain operations and cross-chain bridge activities:
+
+```mermaid
+sequenceDiagram
+    participant AggSender as AggSender
+    participant APG as AggchainProofGen
+    participant zkVM as zkVM Prover
+    participant Agglayer as Agglayer
+    
+    Note over AggSender,Agglayer: Enhanced Certificate with State Transition Proof
+    AggSender->>APG: Request proof for state transition
+    APG->>APG: Verify consensus (ECDSA or validity proof)
+    APG->>APG: Verify bridge constraints
+    APG->>zkVM: Generate cryptographic proof
+    zkVM-->>APG: Return verified proof
+    APG-->>AggSender: Proof + public values
+    AggSender->>Agglayer: Submit enhanced certificate
+    Agglayer->>Agglayer: Validate proof and generate pessimistic proof
+```
+
+**The dual verification**: AggchainProofGen first verifies your chain's consensus mechanism, then verifies that all bridge operations comply with security constraints, finally generating a cryptographic proof of both validations.
+
+## The Two Types of Proof Generation
+
+### **ECDSA Mode**: Fast and Simple
+For chains with trusted sequencer models, AggchainProofGen can verify operations using **ECDSA signature validation**. This provides fast verification while maintaining compatibility with existing chain architectures.
+
+### **Validity Proof Mode**: Mathematical Certainty
+For chains requiring maximum security, AggchainProofGen generates **comprehensive mathematical proofs** using zero-knowledge virtual machines. This provides cryptographic certainty about the correctness of both internal operations and bridge activities.
+
+## Integration with AggSender
+
+When chains use AggchainProofGen, AggSender operates in **AggchainProver mode**:
+
+```mermaid
+sequenceDiagram
+    participant AS as AggSender
+    participant APG as AggchainProofGen
+    participant AL as Agglayer
+    
+    AS->>APG: Request state transition proof
+    APG->>APG: Generate aggchain proof
+    APG-->>AS: Proof + public values
+    AS->>AL: Submit certificate with proof
+    AL->>AL: Validate and process dual proofs
+```
+
+This integration enables the **advanced security model** where both internal chain operations and cross-chain bridge activities are mathematically verified before acceptance by Agglayer.
+
+AggchainProofGen represents the **cutting-edge security option** for chains that require mathematical certainty about their operations. It enables the most advanced security model available in the Agglayer ecosystem, making it suitable for high-value deployments and enterprise environments that demand comprehensive verification.