docs: fully ai generated mdbook

docs/codebase/.gitignore

@@ -0,0 +1,5 @@
+# mdBook build output
+book/
+
+# Backup files
+**/*.md.bak

docs/codebase/README_BUILD.md

@@ -0,0 +1,101 @@
+# FHEVM Codebase Documentation (mdBook)
+
+This directory contains comprehensive technical documentation for the FHEVM codebase, structured as an mdBook.
+
+## Quick Start
+
+### Install mdBook
+
+```bash
+cargo install mdbook
+```
+
+### Build and Serve Locally
+
+```bash
+# From this directory
+mdbook serve
+
+# Or from repo root
+mdbook serve docs/codebase
+```
+
+Then open http://localhost:3000 in your browser.
+
+### Build Static Site
+
+```bash
+mdbook build
+```
+
+Output will be in `book/` directory (gitignored).
+
+## Structure
+
+```
+docs/codebase/
+├── book.toml              # mdBook configuration
+├── src/
+│   ├── SUMMARY.md         # Table of contents (navigation)
+│   ├── README.md          # Landing page
+│   │
+│   ├── executive-summary.md
+│   ├── key-concepts.md
+│   ├── architecture.md
+│   ├── component-health.md
+│   │
+│   ├── components/        # Core component docs
+│   │   ├── README.md
+│   │   ├── gateway-contracts.md
+│   │   ├── host-contracts.md
+│   │   ├── library-solidity.md
+│   │   ├── coprocessor.md
+│   │   ├── kms-connector.md
+│   │   ├── protocol-contracts.md
+│   │   └── infrastructure.md
+│   │
+│   ├── workflows/         # Key workflow docs
+│   │   ├── README.md
+│   │   ├── symbolic-execution.md
+│   │   ├── decryption-pipeline.md
+│   │   └── input-verification.md
+│   │
+│   └── reference/         # Reference materials
+│       ├── tech-stack.md
+│       ├── roadmap.md
+│       ├── quick-reference.md
+│       └── glossary.md
+```
+
+## Current Status
+
+✅ **Level 0 Complete**: High-level overview with all major sections populated
+🚧 **Level 1 In Progress**: Detailed documentation of each component (see TODOs)
+
+Each component file includes `[TODO]` markers indicating areas for deeper documentation. See `src/reference/roadmap.md` for the complete documentation plan.
+
+## Contributing
+
+When adding or updating documentation:
+
+1. Edit markdown files in `src/`
+2. Update `SUMMARY.md` if adding new pages
+3. Run `mdbook serve` to preview changes
+4. Remove `[TODO]` markers when documentation is complete
+5. Update `roadmap.md` to reflect progress
+
+## Publishing
+
+To publish to GitHub Pages:
+
+```bash
+mdbook build
+# Copy book/ contents to gh-pages branch or docs/ directory
+```
+
+Or use the provided GitHub Action (if configured).
+
+## Links
+
+- mdBook Documentation: https://rust-lang.github.io/mdBook/
+- Original Overview: `/CODEBASE_OVERVIEW.md` (consolidated into this mdBook structure)

docs/codebase/book.toml

@@ -0,0 +1,24 @@
+[book]
+title = "FHEVM Codebase Documentation"
+authors = ["Zama"]
+description = "Comprehensive technical documentation of the FHEVM codebase"
+language = "en"
+src = "src"
+
+[build]
+build-dir = "book"
+
+[output.html]
+default-theme = "light"
+preferred-dark-theme = "navy"
+git-repository-url = "https://github.com/zama-ai/fhevm"
+edit-url-template = "https://github.com/zama-ai/fhevm/edit/main/docs/codebase/{path}"
+
+[output.html.search]
+enable = true
+limit-results = 30
+use-boolean-and = true
+
+[output.html.fold]
+enable = true
+level = 1

docs/codebase/src/README.md

@@ -0,0 +1,69 @@
+# FHEVM Codebase Documentation
+
+> **Version**: 1.0 | **Last Updated**: December 2025
+> **Purpose**: Comprehensive technical documentation for developers working with or rebuilding the FHEVM codebase
+
+---
+
+## Welcome
+
+This documentation provides a complete technical overview of the **FHEVM** (Fully Homomorphic Encryption Virtual Machine) codebase - the core framework of the Zama Confidential Blockchain Protocol.
+
+**FHEVM** enables **confidential smart contracts on EVM-compatible blockchains** by leveraging Fully Homomorphic Encryption (FHE), allowing encrypted data to be processed directly on-chain without ever being decrypted.
+
+## What You'll Find Here
+
+This documentation is organized into four main sections:
+
+### 📋 Overview
+- **[Executive Summary](executive-summary.md)** - High-level understanding of FHEVM's purpose and innovation
+- **[Key Concepts](key-concepts.md)** - Essential concepts like ciphertext handles, symbolic execution, and asynchronous computation
+- **[Architecture Overview](architecture.md)** - Three-layer architecture and data flow
+- **[Component Health](component-health.md)** - Development activity and focus areas
+
+### 🔧 Core Components
+Detailed documentation of each major system component:
+- Gateway Contracts, Host Contracts, Solidity Library
+- Coprocessor, KMS Connector, Protocol Contracts
+- Supporting Infrastructure
+
+### 🔄 Key Workflows
+Step-by-step flows for critical operations:
+- Symbolic Execution Pattern
+- Decryption Pipeline
+- Input Verification
+
+### 📚 Reference
+- Technology Stack
+- Documentation Roadmap
+- Quick Reference & Glossary
+
+## Quick Start Paths
+
+**→ I'm a smart contract developer:**
+Start with [Key Concepts](key-concepts.md) → [Solidity Library](components/library-solidity.md)
+
+**→ I'm deploying infrastructure:**
+Start with [Architecture Overview](architecture.md) → [Supporting Infrastructure](components/infrastructure.md)
+
+**→ I'm contributing to core protocol:**
+Start with [Component Health](component-health.md) → specific component documentation
+
+**→ I want to understand the system:**
+Follow the documentation in order: Overview → Components → Workflows → Reference
+
+---
+
+## Documentation Status
+
+This is an actively maintained documentation set. Each component section includes:
+- 🔥 **Active development** markers for rapidly evolving areas
+- ✅ **Stable** markers for mature components
+- 📦 **Infrastructure** markers for operational tooling
+- **[TODO]** markers for areas pending deeper documentation
+
+See the [Documentation Roadmap](reference/roadmap.md) for planned expansions.
+
+---
+
+*Ready to dive in? Start with the [Executive Summary](executive-summary.md) →*

docs/codebase/src/SUMMARY.md

@@ -0,0 +1,43 @@
+# Summary
+
+[Introduction](README.md)
+
+---
+
+# Overview
+
+- [Executive Summary](executive-summary.md)
+- [Key Concepts](key-concepts.md)
+- [Architecture Overview](architecture.md)
+- [Component Health & Activity](component-health.md)
+
+---
+
+# Core Components
+
+- [Components Overview](components/README.md)
+- [Gateway Contracts](components/gateway-contracts.md)
+- [Host Contracts](components/host-contracts.md)
+- [Solidity Library](components/library-solidity.md)
+- [Coprocessor](components/coprocessor.md)
+- [KMS Connector](components/kms-connector.md)
+- [Protocol Contracts](components/protocol-contracts.md)
+- [Supporting Infrastructure](components/infrastructure.md)
+
+---
+
+# Key Workflows
+
+- [Workflows Overview](workflows/README.md)
+- [Symbolic Execution Pattern](workflows/symbolic-execution.md)
+- [Decryption Pipeline](workflows/decryption-pipeline.md)
+- [Input Verification](workflows/input-verification.md)
+
+---
+
+# Reference
+
+- [Technology Stack](reference/tech-stack.md)
+- [Documentation Roadmap](reference/roadmap.md)
+- [Quick Reference](reference/quick-reference.md)
+- [Glossary](reference/glossary.md)

docs/codebase/src/architecture.md

@@ -0,0 +1,116 @@
+# Architecture Overview
+
+FHEVM follows a three-layer architecture separating on-chain coordination from off-chain computation:
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         SMART CONTRACT LAYER                            │
+│                           (On-Chain / EVM)                              │
+│  ┌────────────────┐  ┌────────────────┐  ┌────────────────────────┐    │
+│  │     Host       │  │    Gateway     │  │   Library (Developer)  │    │
+│  │   Contracts    │◄─┤   Contracts    │  │   FHE.sol + Types      │    │
+│  │                │  │                │  │                        │    │
+│  │ FHEVMExecutor  │  │ GatewayConfig  │  │ euint8, euint256,      │    │
+│  │ ACL, HCULimit  │  │ Decryption     │  │ ebool, eaddress...     │    │
+│  │ KMSVerifier    │  │ MultichainACL  │  │                        │    │
+│  └───────┬────────┘  └───────┬────────┘  └────────────────────────┘    │
+└──────────┼───────────────────┼─────────────────────────────────────────┘
+           │                   │
+           │  Events/Requests  │
+           ▼                   ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           COMPUTE LAYER                                 │
+│                         (Off-Chain / Rust)                              │
+│  ┌───────────────────────────────────────────────────────────────────┐ │
+│  │                    Coprocessor (fhevm-engine)                      │ │
+│  │                                                                    │ │
+│  │  ┌─────────────┐  ┌───────────┐  ┌──────────────┐  ┌───────────┐ │ │
+│  │  │ tfhe-worker │  │ scheduler │  │ zkproof-     │  │ listeners │ │ │
+│  │  │ (FHE ops)   │  │           │  │ worker       │  │ (host/gw) │ │ │
+│  │  └─────────────┘  └───────────┘  └──────────────┘  └───────────┘ │ │
+│  └───────────────────────────────────────────────────────────────────┘ │
+└──────────────────────────────────┬──────────────────────────────────────┘
+                                   │
+                                   │  Key Operations
+                                   ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                        KMS CONNECTIVITY LAYER                           │
+│                         (Off-Chain / Rust)                              │
+│  ┌───────────────────────────────────────────────────────────────────┐ │
+│  │                        KMS Connector                               │ │
+│  │                                                                    │ │
+│  │  ┌─────────────┐  ┌────────────┐  ┌────────────────────────────┐ │ │
+│  │  │ gw-listener │  │ kms-worker │  │ transaction-sender         │ │ │
+│  │  │             │  │ (MPC keys) │  │                            │ │ │
+│  │  └─────────────┘  └────────────┘  └────────────────────────────┘ │ │
+│  └───────────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## Layer Breakdown
+
+### Layer 1: Smart Contract Layer (On-Chain)
+
+**Components:**
+- **Host Contracts**: Symbolic FHE execution on each EVM chain
+- **Gateway Contracts**: Cross-chain coordination and off-chain communication
+- **Library**: Developer-facing API (FHE.sol with encrypted types)
+
+**Purpose:** Fast, deterministic on-chain operations that generate ciphertext handles and coordinate with off-chain services.
+
+### Layer 2: Compute Layer (Off-Chain)
+
+**Components:**
+- **Coprocessor (fhevm-engine)**: Rust-based FHE computation engine
+  - `tfhe-worker`: Actual FHE operations using TFHE-rs
+  - `scheduler`: Job orchestration
+  - `zkproof-worker`: Zero-knowledge proof generation
+  - `listeners`: Monitor blockchain events
+
+**Purpose:** Perform expensive FHE computations asynchronously and submit verified results back to chain.
+
+### Layer 3: KMS Connectivity Layer (Off-Chain)
+
+**Components:**
+- **KMS Connector**: Interface to Key Management System
+  - `gw-listener`: Monitor gateway events
+  - `kms-worker`: Coordinate with external KMS Core
+  - `transaction-sender`: Submit signed results
+
+**Purpose:** Manage encryption keys via multi-party computation (MPC), ensuring no single party holds complete keys.
+
+## Data Flow Summary
+
+1. **Developer** writes smart contract using `FHE.sol` library with encrypted types
+2. **User** submits transaction with encrypted inputs (proven via ZK proofs)
+3. **Host Contracts** execute operations symbolically, generating ciphertext handles
+4. **Gateway Contracts** coordinate between chain and off-chain components
+5. **Coprocessor** performs actual FHE computations asynchronously
+6. **KMS** manages encryption keys via multi-party computation (MPC)
+7. Results are verified and committed back to chain state
+
+## Key Architectural Principles
+
+### Separation of Concerns
+- **Consensus** (on-chain) is separate from **computation** (off-chain)
+- Smart contracts never touch raw ciphertexts, only handles
+- Heavy crypto happens asynchronously without blocking transactions
+
+### Eventual Consistency
+- Operations complete immediately on-chain (handle generation)
+- Results become available later (seconds to minutes)
+- System guarantees eventual consistency across all layers
+
+### Threshold Security
+- No single point of trust or failure
+- Multiple coprocessors can provide redundancy
+- KMS uses threshold signatures (MPC) for key operations
+
+### Multi-Chain Design
+- Single gateway can coordinate multiple host chains
+- Host chains operate independently
+- Gateway provides cross-chain ACL and coordination
+
+---
+
+**Next:** Check [Component Health & Activity](component-health.md) to see which areas are actively evolving →