diff --git a/CODEBASE_OVERVIEW.md b/CODEBASE_OVERVIEW.md new file mode 100644 index 0000000000..b7b1d9a098 --- /dev/null +++ b/CODEBASE_OVERVIEW.md @@ -0,0 +1,633 @@ +# FHEVM Codebase Overview + +> **Version**: 1.0 | **Last Updated**: December 2024 +> **Purpose**: High-level architectural overview for developers working with or rebuilding the fhevm codebase + +--- + +## Executive Summary + +**FHEVM** is the core framework of the Zama Confidential Blockchain Protocol. It 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. + +### Key Guarantees + +- **End-to-end encryption**: Transaction data and state remain encrypted at all times +- **Composability**: Encrypted state coexists with public state, enabling complex DeFi and application logic +- **No impact on existing dApps**: Confidential features are additive; existing applications continue to function + +### Core Innovation + +FHEVM uses **symbolic execution with asynchronous computation**: +1. FHE operations execute **symbolically on-chain** (fast, deterministic, cheap) +2. Actual FHE computation happens **asynchronously off-chain** via the coprocessor +3. Results are verified and committed back to the chain + +This architecture separates the slow cryptographic work from blockchain consensus, enabling practical FHE on Ethereum-compatible chains. + +--- + +## Key Concepts + +Before diving into the architecture, these concepts are essential to understanding FHEVM: + +### Ciphertext Handles + +A **ciphertext handle** is a 32-byte identifier (`bytes32`) that references encrypted data. Think of it like a pointer or database key: +- The **handle** is stored on-chain (small, cheap) +- The actual **ciphertext** (encrypted data) is stored off-chain in the coprocessor +- Smart contracts operate on handles; the coprocessor operates on ciphertexts + +### Symbolic Execution + +**Symbolic execution** means the on-chain contracts don't perform actual FHE computation. Instead, they: + +1. **Generate deterministic handles**: Given inputs `handle_a` and `handle_b` for an `add` operation, compute `handle_result = hash(handle_a, handle_b, "add", counter)` +2. **Emit events**: Log the operation details for the off-chain coprocessor +3. **Return immediately**: The transaction completes without waiting for FHE computation + +**Example**: When a contract calls `FHE.add(a, b)`: +``` +On-chain (FHEVMExecutor): Off-chain (Coprocessor): +1. Validate inputs +2. Generate handle_c = hash(...) +3. Emit event(ADD, a, b, c) --> 4. Listen for event +4. Return handle_c 5. Load ciphertexts a, b + 6. Compute c = TFHE.add(a, b) + 7. Store ciphertext c + 8. Commit to CiphertextCommits +``` + +The on-chain transaction completes in step 4. Steps 5-8 happen asynchronously seconds/minutes later. + +### Asynchronous Computation Model + +Because FHE operations are slow (seconds to minutes), FHEVM uses an **eventual consistency** model: + +- **Writes are immediate**: `balances[user] = FHE.add(balances[user], amount)` completes immediately (new handle stored) +- **Results arrive later**: The actual encrypted value is computed and stored asynchronously +- **Reads use latest state**: Subsequent operations on the same handle will use the computed ciphertext once available + +**For decryption**: Contracts must request decryption explicitly and receive results via callback: +```solidity +// Request decryption (async) +Gateway.requestDecryption(handle, callbackSelector); + +// Receive result later via callback +function onDecrypt(uint256 plaintext) external onlyGateway { + // Use decrypted value +} +``` + +### Host Chain vs Gateway Chain + +FHEVM supports **multiple host chains** (any EVM-compatible chain) coordinated by a single **gateway chain**: + +- **Host Chain**: Where your dApp runs. Each host chain has its own FHEVMExecutor, ACL, etc. +- **Gateway Chain**: Central coordination point. Stores ciphertext commitments, manages cross-chain ACLs, coordinates with coprocessors and KMS. + +In simple deployments, these may be the same chain. In multichain deployments, the gateway is a separate chain that coordinates FHE operations across all hosts. + +### Use Cases + +- Confidential token transfers (private balances without mixers) +- Blind auctions (hidden bids until reveal) +- On-chain games (hidden cards, moves, selections) +- Encrypted DIDs and attestations +- Confidential voting (anti-bribery, anti-coercion) + +--- + +## 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) │ │ │ │ │ +│ │ └─────────────┘ └────────────┘ └────────────────────────────┘ │ │ +│ └───────────────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +### 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 + +--- + +## Component Health & Freshness + +> **Last analyzed**: December 2024 | Based on 6-month git history + +| Component | Status | 6-mo Commits | Focus Areas | +|-----------|--------|--------------|-------------| +| `coprocessor/` | 🔥 Active | 1,718 | GPU optimization, metrics, health checks | +| `kms-connector/` | 🔥 Active | 1,110 | Garbage collection, polling, nonce management | +| `gateway-contracts/` | 🔥 Active | 1,071 | Payment protocol, multi-sig, cross-chain | +| `protocol-contracts/` | 🔥 Active | 748 | Staking, delegation, fee management | +| `host-contracts/` | ✅ Stable | 455 | ACL enhancements, operator pricing | +| `library-solidity/` | ✅ Stable | 410 | Codegen consolidation, type improvements | +| `test-suite/` | 🔥 Active | 975 | E2E tests, version tracking | +| `charts/` | 📦 Infra | 138 | K8s deployment emerging | +| `sdk/` | 📦 Infra | 91 | Maintenance mode | + +**Legend**: 🔥 Active development | ✅ Stable/maintained | 📦 Infrastructure (minimal changes) + +**Recent removals** (avoid documenting these deprecated items): +- `ProtocolOperatorRegistry` - removed from protocol-contracts, replaced by `OperatorStaking` +- Distributed codegen - consolidated to `/library-solidity/codegen/` +- Safe-specific tasks - removed from gateway-contracts + +--- + +## 3. Core Components + +### 3.1 Gateway Contracts 🔥 + +**Location**: `/gateway-contracts/` +**Purpose**: Bridge between on-chain smart contracts and off-chain compute infrastructure + +The Gateway contracts serve as the coordination layer that manages communication between the blockchain and off-chain services. They handle ciphertext commitments, decryption requests, input verification, and access control across multiple chains. + +**Key Contracts**: + +| Contract | Purpose | +|----------|---------| +| `GatewayConfig.sol` | Central registry for KMS nodes, coprocessors, and protocol metadata | +| `Decryption.sol` | Manages public and user decryption requests with EIP712 signature validation | +| `MultichainACL.sol` | Access control for cross-chain operations and user delegations | +| `CiphertextCommits.sol` | Stores ciphertext material commitments from coprocessors | +| `InputVerification.sol` | Verifies encrypted user inputs via ZK proofs | +| `KMSGeneration.sol` | Orchestrates key generation and reshare operations | +| `ProtocolPayment.sol` | Handles protocol fee collection and distribution | + +**Key Files**: +- `contracts/GatewayConfig.sol` - Gateway registry and configuration +- `contracts/Decryption.sol` - Decryption request handling +- `contracts/shared/Structs.sol` - Core data structures (KmsNode, Coprocessor, etc.) + +**Relationships**: Gateway contracts receive events from Host contracts and coordinate with the Coprocessor and KMS Connector to process FHE operations. They maintain consensus through threshold signatures from multiple coprocessors. + +**Recent Development Focus** (as of Dec 2024): +- Payment protocol implementation (`ProtocolPayment` contract) +- Multi-sig contracts based on Safe Smart Account +- LayerZero cross-chain integration for testnet/mainnet +- Monitoring events and request ID validation + +[TODO: Gateway consensus mechanism - Document the threshold-based consensus process for ciphertext commits and how multiple coprocessors agree on computation results] + +[TODO: Multichain ACL flow - Detail how access control delegations work across different host chains] + +--- + +### 3.2 Host Contracts ✅ + +**Location**: `/host-contracts/` +**Purpose**: On-chain symbolic execution of FHE workflows on the host EVM chain + +Host contracts are deployed on each supported EVM chain and provide the core FHE execution interface. They execute operations symbolically (generating deterministic handles) while the actual encrypted computation happens off-chain. + +**Key Contracts**: + +| Contract | Purpose | +|----------|---------| +| `FHEVMExecutor.sol` | Symbolic execution engine with 20+ FHE operators | +| `ACL.sol` | Access control for encrypted data handles | +| `HCULimit.sol` | Enforces Homomorphic Complexity Unit limits per transaction | +| `KMSVerifier.sol` | Verifies KMS-signed decryption results | +| `InputVerifier.sol` | Verifies encrypted user input proofs (host-side) | + +> **Note**: Both Gateway (`InputVerification.sol`) and Host (`InputVerifier.sol`) have input verification. Gateway handles cross-chain verification; Host handles local chain verification. In single-chain deployments, Host's InputVerifier is the primary entry point. + +**Key Files**: +- `contracts/FHEVMExecutor.sol` - Core symbolic execution (fheAdd, fheMul, fheEq, etc.) +- `contracts/ACL.sol` - Permission management for ciphertext handles +- `contracts/shared/FheType.sol` - Encrypted type definitions + +**Relationships**: Host contracts receive calls from user smart contracts via the FHE library. They emit events that the Coprocessor's host-listener picks up. Results from the Coprocessor are verified via KMSVerifier before being accepted. + +[TODO: FHEVMExecutor operators - Document all 20+ FHE operators (fheAdd, fheSub, fheMul, fheDiv, fheEq, fheLt, fheGt, fheBitAnd, fheBitOr, fheBitXor, fheShl, fheShr, fheRotl, fheRotr, etc.) and their symbolic execution semantics] + +[TODO: ACL permission model - Detail the allowList, denyList, and delegation mechanisms for controlling access to encrypted values] + +[TODO: HCU limit enforcement - Explain the 20M HCU/tx and 5M depth limits and how they prevent DoS attacks] + +--- + +### 3.3 Solidity Library ✅ + +**Location**: `/library-solidity/` +**Purpose**: Developer-facing FHE primitives for writing confidential smart contracts + +The Solidity library provides the API that smart contract developers use to work with encrypted types. It abstracts away the complexity of FHE operations behind familiar Solidity syntax. + +**Key Components**: + +| File | Purpose | +|------|---------| +| `lib/FHE.sol` | Main developer API - import this to use FHE | +| `lib/Impl.sol` | Implementation details, delegates to precompiles | +| `lib/FheType.sol` | Encrypted type enum definitions | + +**Encrypted Types**: +- **Boolean**: `ebool` +- **Unsigned integers**: `euint4`, `euint8`, `euint16`, `euint32`, `euint64`, `euint128`, `euint256`, up to `euint2048` +- **Signed integers**: `eint8`, `eint16`, `eint32`, `eint64`, `eint128`, `eint256` +- **Special**: `eaddress`, `AsciiString` + +**Example Usage**: +```solidity +import {FHE, euint64} from "fhevm/lib/FHE.sol"; + +contract ConfidentialToken { + mapping(address => euint64) private balances; + + function transfer(address to, euint64 amount) external { + balances[msg.sender] = FHE.sub(balances[msg.sender], amount); + balances[to] = FHE.add(balances[to], amount); + } +} +``` + +**Key Files**: +- `lib/FHE.sol` - Primary import for developers +- `examples/EncryptedERC20.sol` - Reference implementation +- `codegen/` - Code generation for operator overloads + +[TODO: Encrypted type system - Document all supported types, their bit sizes, and conversion rules between types] + +[TODO: Codegen system - Explain how operator overloads are generated and how to extend the library] + +--- + +### 3.4 Coprocessor 🔥 + +**Location**: `/coprocessor/` +**Purpose**: Rust-based asynchronous FHE computation engine + +The Coprocessor is the off-chain component that performs actual FHE computations. It listens to events from Host and Gateway contracts, executes the expensive cryptographic operations, and submits results back to the chain. + +**Key Crates** (in `/coprocessor/fhevm-engine/`): + +| Crate | Purpose | +|-------|---------| +| `tfhe-worker` | Core FHE computation engine using TFHE-rs | +| `scheduler` | Job orchestration and work distribution | +| `zkproof-worker` | Zero-knowledge proof generation | +| `sns-worker` | Switch and Squash optimization for ciphertexts | +| `host-listener` | Monitors host chain events | +| `gw-listener` | Monitors gateway chain events | +| `transaction-sender` | Broadcasts results back to chain | + +**Architecture**: +- **Event-driven**: Listeners pick up on-chain events and create jobs +- **Database-backed**: PostgreSQL stores job state and ciphertext data +- **Async processing**: Workers process jobs concurrently via scheduler +- **Threshold consensus**: Multiple coprocessors can run for redundancy + +**Key Files**: +- `fhevm-engine/tfhe-worker/` - TFHE computation implementation +- `fhevm-engine/scheduler/` - Job queue and distribution +- `Cargo.toml` - Workspace manifest + +**Relationships**: The Coprocessor receives work from Gateway contract events, processes FHE operations, and submits results via transaction-sender. It coordinates with the KMS Connector for key material. + +**Recent Development Focus** (as of Dec 2024): +- GPU scheduler improvements and GPU memory management +- Metrics collection (SNS latency, ZK verify latency, tfhe-per-txn timing) +- Health checking in tfhe-worker and sns-worker +- Database optimization (indices on ciphertext_digest, schedule order) +- Compression for large ciphertexts +- Off-chain execution optimization + +[TODO: Worker architecture - Detail the tfhe-worker, zkproof-worker, and sns-worker implementations and their processing pipelines] + +[TODO: Scheduler and job orchestration - Document the job lifecycle from event reception to result submission] + +--- + +### 3.5 KMS Connector 🔥 + +**Location**: `/kms-connector/` +**Purpose**: Interface between the Gateway and Key Management System (KMS Core) + +The KMS Connector bridges the Gateway contracts with the external KMS Core service that manages encryption keys using multi-party computation (MPC). This ensures no single party ever holds the complete decryption key. + +**Key Crates**: + +| Crate | Purpose | +|-------|---------| +| `gw-listener` | Monitors Gateway for key-related events | +| `kms-worker` | Forwards requests to KMS Core service | +| `transaction-sender` | Submits signed responses back to Gateway | +| `utils` | Shared utilities and types | + +**Supported Key Operations**: +- Key generation (initial setup) +- Preprocessing keygen +- Key reshare (rotation) +- CRS (Common Reference String) generation +- Decryption signing (threshold signatures) + +**Key Files**: +- `gw-listener/src/main.rs` - Event listener entry point +- `kms-worker/src/main.rs` - KMS request handler +- `Cargo.toml` - Workspace dependencies + +**Relationships**: KMS Connector listens to KMSGeneration and Decryption events from Gateway contracts. It forwards requests to the external KMS Core (not in this repo) and submits EIP712-signed responses back to the chain. + +**Recent Development Focus** (as of Dec 2024): +- Garbage collection implementation +- Database transaction management and retry logic +- Polling mechanisms and listener improvements +- Nonce manager with recoverable patterns +- Configuration updates (WebSocket to HTTP migration) + +[TODO: KMS integration flow - Document the complete flow from decryption request to signed response] + +[TODO: Threshold signature scheme - Explain the MPC-based threshold signature mechanism for key security] + +--- + +### 3.6 Protocol Contracts 🔥 + +**Location**: `/protocol-contracts/` +**Purpose**: Protocol-level infrastructure including token, staking, and governance + +Protocol contracts implement the economic and governance layer of the FHEVM ecosystem. They are organized into domain-specific subdirectories. + +**Submodules**: + +| Directory | Purpose | +|-----------|---------| +| `token/` | ZAMA ERC20 token and OFT (Omnichain Fungible Token) for cross-chain | +| `staking/` | Node operator staking mechanisms | +| `governance/` | DAO voting and protocol governance | +| `confidential-wrapper/` | Wraps public tokens for confidential transfers | +| `feesBurner/` | Fee collection and token burning | +| `safe/` | Safe module for protocol administration | + +**Key Files**: +- `token/ZamaERC20.sol` - Protocol token +- `confidential-wrapper/Wrapper.sol` - Public-to-confidential token bridge +- `staking/OperatorStaking.sol` - Operator staking + +**Recent Development Focus** (as of Dec 2024): +- Staking/delegating contracts (`OperatorStaking`, `Rewarder`) +- Fee management and burner implementation +- Governance improvements (Safe ownership, admin modules) +- ERC1363 integration +- UUPS upgradeability patterns + +> ⚠️ **Note**: `ProtocolOperatorRegistry` has been removed. Use `OperatorStaking` for staking functionality. + +[TODO: Confidential wrapper pattern - Document how public ERC20 tokens are wrapped for confidential use and unwrapped back] + +--- + +### 3.7 Supporting Infrastructure 📦 + +**Location**: Various +**Purpose**: Deployment, testing, and operational tooling + +**Directories**: + +| Directory | Purpose | +|-----------|---------| +| `/charts/` | Helm charts for Kubernetes deployment | +| `/test-suite/` | E2E integration tests with docker-compose | +| `/golden-container-images/` | Base Docker images for Node.js and Rust | +| `/docs/` | Gitbook documentation source | +| `/sdk/` | Rust SDK for building applications | +| `/ci/` | CI/CD pipeline configurations | + +**Testing Infrastructure**: +- **Hardhat tests**: Unit/integration tests in `host-contracts/test/`, `library-solidity/test/` +- **Foundry tests**: Solidity-native tests via `forge test` +- **E2E tests**: Full-stack tests in `test-suite/` using docker-compose +- **Mock FHE**: SQLite-backed mocking for fast testing without real FHE + +**Key Files**: +- `test-suite/docker-compose.yml` - Full stack orchestration +- `host-contracts/hardhat.config.ts` - Hardhat configuration +- `.github/workflows/` - CI pipeline definitions + +#### CI/CD Pipeline & GitHub Actions + +FHEVM's CI/CD infrastructure consists of **40+ GitHub Actions workflows** organized by component domain, ensuring quality through multi-layered testing, comprehensive security scanning, and automated deployment. The pipeline architecture mirrors the codebase structure, with workflows grouped by component (coprocessor, contracts, infrastructure) to enable efficient parallel execution and path-based filtering. + +**Workflow Organization by Component Domain** + +| Component Domain | Workflow Count | Test Types | Build Outputs | Key Workflows | +|-----------------|----------------|------------|---------------|---------------| +| Coprocessor (Rust) | 14 | Unit (Cargo), GPU, Benchmarks, Listeners | 7 Docker images | `coprocessor-cargo-tests`, `coprocessor-benchmark-cpu`, `coprocessor-docker-build` | +| Gateway Contracts | 5 | Hardhat, Deployment, Upgrade, Integrity | Docker image | `gateway-contracts-hardhat-tests`, `gateway-contracts-deployment-tests` | +| Host Contracts | 5 | Hardhat, Foundry, Slither, Deployment | Docker image, npm package | `host-contracts-hardhat-forge-tests`, `host-contracts-slither-analysis` | +| Test Suite | 5 | E2E (13 scenarios), Operators, Orchestration | Docker images | `test-suite-e2e-tests`, `test-suite-e2e-tests-mq` (merge queue) | +| KMS Connector | 3 | Cargo, Dependency analysis | Docker images | `kms-connector-tests`, `kms-connector-docker-build` | +| Library Solidity | 2 | Hardhat | npm package | `library-solidity-tests`, `library-solidity-publish` | +| Protocol Contracts | 2 | Hardhat (Wrapper, Staking) | - | `protocol-contracts-confidential-wrapper-tests` | +| Charts (Helm) | 2 | Linting | Helm charts (OCI) | `charts-helm-checks`, `charts-helm-release` | +| Golden Images | 2 | - | Base Docker images (Node.js, Rust) | `golden-container-images-docker-build-nodejs` | +| SDK (Rust) | 1 | Cargo | - | `sdk-rust-sdk-tests` | +| Cross-cutting | 2 | CodeQL (4 languages), PR linting | - | `codeql`, `common-pull-request-lint` | + +Workflows follow a **component-based naming convention** (`{component}-{subcomponent}-{operation}.yml`) that enables clear categorization and filtering. Path-based filtering using `dorny/paths-filter` ensures workflows run only when relevant files change, optimizing CI resource usage and execution time. + +**Multi-Layered Testing Strategy** + +| Test Layer | Scope | Tooling | Trigger | Duration | Example Workflows | +|-----------|-------|---------|---------|----------|-------------------| +| **Unit Tests** | Component-level logic | Cargo (Rust), Hardhat (Solidity), Foundry (Solidity) | PR, push to main | 3-8 min | `coprocessor-cargo-tests`, `gateway-contracts-hardhat-tests`, `host-contracts-hardhat-forge-tests` | +| **Integration Tests** | Docker-based component interaction | docker-compose, LocalStack, PostgreSQL | PR (path-filtered) | 5-12 min | `coprocessor-cargo-listener-tests`, `gateway-contracts-deployment-tests` | +| **E2E Tests** | Full-stack validation with fhevm-cli | 13 test scenarios: pause/unpause, input proofs, decryption, ERC20, random operators, host listener polling | PR to main/release, workflow_dispatch | 15-25 min | `test-suite-e2e-tests`, `test-suite-e2e-tests-mq`, `test-suite-e2e-operators-tests` | +| **Security Scans** | Vulnerability detection | CodeQL (Actions/JS/Python/Rust), Slither (Solidity), Dependabot | Scheduled (weekdays 5:30 AM UTC), PR | 10-20 min | `codeql`, `host-contracts-slither-analysis`, `*-dependency-analysis` | +| **Benchmarks** | Performance validation | Custom Rust benchmarks, CPU/GPU profiling, Slab platform integration | Manual (workflow_dispatch) | 20-45 min | `coprocessor-benchmark-cpu`, `coprocessor-benchmark-gpu` | + +**Security Scanning**: CodeQL runs on a scheduled basis (weekdays at 05:30 UTC) analyzing Actions, JavaScript/TypeScript, Python, and Rust code for security vulnerabilities. Slither performs static analysis on Solidity contracts (configured for solc v0.8.24) during PR builds. Dependabot monitors Cargo and GitHub Actions dependencies for security updates. Workflow syntax is validated via Actionlint configuration (`.github/actionlint.yaml`). + +**Build and Publish**: Docker images are published to multiple registries (**ghcr.io** and **cgr.dev**) with SLSA provenance attestation for supply chain security. Build workflows use **Zama's shared CI template** (`zama-ai/ci-templates`) for consistency. The `re-tag-docker-image` workflow optimizes builds by reusing previous image tags when source files haven't changed, reducing unnecessary rebuilds for dependent components. Smart contract packages are published to npm with OIDC authentication and provenance enabled. + +**Release Management**: The Mergify merge queue (`.mergify.yml`) enforces strict quality gates with **batch size 3**, **squash merge** strategy, and **12-hour checks timeout**. All PRs must pass the E2E test suite (`run-e2e-tests / fhevm-e2e-test`) before merging. The queue uses **rebase update** method to ensure linear history. CODEOWNERS (`.github/CODEOWNERS`) enforces component-based review requirements, with specialized teams for coprocessor (`@zama-ai/fhevm-coprocessor`), gateway/contracts (`@zama-ai/fhevm-gateway`), and DevOps oversight for release workflows (`@zama-ai/fhevm-devops`). Automated changelog generation categorizes changes into Breaking Changes, New features, Improvements, and Fixes (`.github/release.yml`). + +**Key Patterns**: All workflows implement **concurrency control** to cancel redundant PR runs while preserving main branch execution. **Permissions minimization** follows the principle of least privilege, granting only necessary permissions per job (actions:read, contents:read, packages:write, security-events:write). Actions are **pinned to specific commit SHAs** for supply chain security. Runner sizing is optimized per workload: `ubuntu-latest` for lightweight tasks, `large_ubuntu_16` for resource-intensive tests, `large_ubuntu_32` for E2E tests, and `gpu_ubuntu-22.04` for GPU benchmarks. + +[TODO: Testing infrastructure deep-dive - Document the mock FHE system, test fixtures, and E2E testing patterns] + +[TODO: Deployment guide - Document the Helm charts and Kubernetes deployment process] + +--- + +## 4. Key Workflows + +### Symbolic Execution Pattern + +When a smart contract calls an FHE operation like `FHE.add(a, b)`: + +1. **On-chain (fast)**: `FHEVMExecutor` generates a deterministic ciphertext handle +2. **Event emission**: Operation details emitted as an event +3. **Off-chain (async)**: Coprocessor picks up event, performs actual FHE computation +4. **Result commitment**: Coprocessor submits result ciphertext to `CiphertextCommits` +5. **Consensus**: Multiple coprocessors agree on result via threshold signatures + +This pattern allows smart contracts to execute quickly on-chain while heavy crypto happens off-chain. + +### Decryption Pipeline + +When a contract requests decryption: + +1. **Request**: Contract calls decryption via Gateway's `Decryption` contract +2. **ACL check**: `MultichainACL` verifies requester has permission +3. **KMS notification**: `KMSGeneration` event triggers KMS Connector +4. **MPC decryption**: KMS nodes perform threshold decryption +5. **Signature**: Result signed by threshold of KMS nodes +6. **Verification**: `KMSVerifier` validates signatures on host chain +7. **Callback**: Decrypted value delivered to requesting contract + +### Input Verification + +When a user submits encrypted input: + +1. **Client-side**: User encrypts data and generates ZK proof +2. **Submission**: Transaction includes ciphertext + proof +3. **Verification**: `InputVerifier` validates ZK proof +4. **Registration**: Valid ciphertext registered in `CiphertextCommits` +5. **Handle creation**: Ciphertext handle returned to smart contract + +--- + +## 5. Technology Stack + +| Layer | Technologies | Key Files | +|-------|-------------|-----------| +| **Smart Contracts** | Solidity 0.8+, OpenZeppelin v5.2, UUPS Proxies | `*.sol` | +| **Dev Tooling** | Hardhat, Foundry, TypeChain, Prettier | `hardhat.config.ts`, `foundry.toml` | +| **Coprocessor** | Rust, TFHE-rs, Tokio, SQLx, PostgreSQL | `Cargo.toml`, `*.rs` | +| **Communication** | gRPC, Protobuf, EIP712 signatures | `*.proto` | +| **Deployment** | Docker, Kubernetes, Helm | `charts/`, `docker-compose.yml` | +| **CI/CD** | GitHub Actions | `.github/workflows/` | + +--- + +## 6. Documentation Roadmap + +The following areas require deeper documentation, **prioritized by component activity level**. Each item is tagged for agent-based expansion: + +### High Priority (🔥 Active Components) + +1. **[TODO: Worker architecture]** - Detail tfhe-worker, zkproof-worker, sns-worker implementations (Coprocessor 🔥) +2. **[TODO: Scheduler and job orchestration]** - Job lifecycle from event reception to result submission (Coprocessor 🔥) +3. **[TODO: Gateway consensus mechanism]** - Threshold-based consensus for ciphertext commits (Gateway 🔥) +4. **[TODO: Multichain ACL flow]** - Access control delegations across host chains (Gateway 🔥) +5. **[TODO: KMS integration flow]** - Complete flow from decryption request to signed response (KMS 🔥) +6. **[TODO: Threshold signature scheme]** - MPC-based threshold signature mechanism (KMS 🔥) +7. **[TODO: Staking/delegation contracts]** - OperatorStaking, Rewarder implementation (Protocol 🔥) + +### Medium Priority (✅ Stable Components) + +8. **[TODO: FHEVMExecutor operators]** - Document all 20+ FHE operators and symbolic execution (Host ✅) +9. **[TODO: ACL permission model]** - allowList, denyList, and delegation mechanisms (Host ✅) +10. **[TODO: HCU limit enforcement]** - Resource limits and DoS prevention (Host ✅) +11. **[TODO: Encrypted type system]** - All supported types and conversion rules (Library ✅) +12. **[TODO: Codegen system]** - Operator overload generation process (Library ✅) + +### Lower Priority (📦 Infrastructure) + +13. **[TODO: Confidential wrapper pattern]** - Public-to-confidential token bridge +14. **[TODO: Testing infrastructure deep-dive]** - Mock FHE system and E2E patterns +15. **[TODO: Deployment guide]** - Helm charts and Kubernetes deployment + +--- + +## Quick Reference + +### Directory Map + +``` +fhevm/ +├── gateway-contracts/ # Bridge to off-chain (Solidity) +├── host-contracts/ # On-chain FHE execution (Solidity) +├── library-solidity/ # Developer FHE library (Solidity) +├── protocol-contracts/ # Token, staking, governance (Solidity) +├── coprocessor/ # FHE compute engine (Rust) +├── kms-connector/ # KMS bridge (Rust) +├── charts/ # Kubernetes Helm charts +├── test-suite/ # E2E integration tests +├── docs/ # Documentation source +└── sdk/ # Rust SDK +``` + +### Entry Points for Developers + +- **Writing contracts**: Start with `/library-solidity/lib/FHE.sol` +- **Understanding execution**: Read `/host-contracts/contracts/FHEVMExecutor.sol` +- **Understanding coordination**: Read `/gateway-contracts/contracts/GatewayConfig.sol` +- **Running tests**: See `/host-contracts/package.json` scripts +- **Deploying**: See `/charts/` Helm configurations + +--- + +## Glossary + +| Term | Definition | +|------|------------| +| **Ciphertext** | Encrypted data that can be operated on using FHE | +| **Ciphertext Handle** | A 32-byte on-chain identifier referencing off-chain encrypted data | +| **Coprocessor** | Off-chain Rust service that performs actual FHE computation | +| **EIP712** | Ethereum standard for typed structured data signing | +| **FHE** | Fully Homomorphic Encryption - allows computation on encrypted data | +| **Gateway Chain** | Central chain coordinating FHE operations across multiple hosts | +| **HCU** | Homomorphic Complexity Unit - measure of FHE computation cost | +| **Host Chain** | EVM chain where user dApps run | +| **KMS** | Key Management System - manages encryption keys via MPC | +| **MPC** | Multi-Party Computation - distributes trust across multiple parties | +| **Symbolic Execution** | On-chain execution that generates handles without computing ciphertexts | +| **TFHE-rs** | Rust library implementing the TFHE FHE scheme (used by coprocessor) | +| **UUPS** | Universal Upgradeable Proxy Standard - pattern for upgradeable contracts | + +--- + +*This document is the foundation for iterative expansion. Each [TODO] marker indicates an area that can be expanded into its own detailed section.* diff --git a/docs/codebase/.gitignore b/docs/codebase/.gitignore new file mode 100644 index 0000000000..a3c5834cba --- /dev/null +++ b/docs/codebase/.gitignore @@ -0,0 +1,5 @@ +# mdBook build output +book/ + +# Backup files +**/*.md.bak diff --git a/docs/codebase/README_BUILD.md b/docs/codebase/README_BUILD.md new file mode 100644 index 0000000000..0642f71ddf --- /dev/null +++ b/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) diff --git a/docs/codebase/book.toml b/docs/codebase/book.toml new file mode 100644 index 0000000000..fd89a22921 --- /dev/null +++ b/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 diff --git a/docs/codebase/src/README.md b/docs/codebase/src/README.md new file mode 100644 index 0000000000..c92dec057f --- /dev/null +++ b/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) →* diff --git a/docs/codebase/src/SUMMARY.md b/docs/codebase/src/SUMMARY.md new file mode 100644 index 0000000000..ef1a7ad3bd --- /dev/null +++ b/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) diff --git a/docs/codebase/src/architecture.md b/docs/codebase/src/architecture.md new file mode 100644 index 0000000000..0fde1ab85d --- /dev/null +++ b/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 → diff --git a/docs/codebase/src/component-health.md b/docs/codebase/src/component-health.md new file mode 100644 index 0000000000..6e0d602590 --- /dev/null +++ b/docs/codebase/src/component-health.md @@ -0,0 +1,102 @@ +# Component Health & Development Activity + +> **Last analyzed**: December 2025 | Based on 6-month git history + +This page tracks the development activity and health of each major component to help you understand where the codebase is actively evolving versus stable. + +## Activity Overview + +| Component | Status | 6-mo Commits | Focus Areas | +|-----------|--------|--------------|-------------| +| `coprocessor/` | 🔥 Active | 1,718 | GPU optimization, metrics, health checks | +| `kms-connector/` | 🔥 Active | 1,110 | Garbage collection, polling, nonce management | +| `gateway-contracts/` | 🔥 Active | 1,071 | Payment protocol, multi-sig, cross-chain | +| `protocol-contracts/` | 🔥 Active | 748 | Staking, delegation, fee management | +| `host-contracts/` | ✅ Stable | 455 | ACL enhancements, operator pricing | +| `library-solidity/` | ✅ Stable | 410 | Codegen consolidation, type improvements | +| `test-suite/` | 🔥 Active | 975 | E2E tests, version tracking | +| `charts/` | 📦 Infra | 138 | K8s deployment emerging | +| `sdk/` | 📦 Infra | 91 | Maintenance mode | + +**Legend:** +- 🔥 **Active development** - Rapid evolution, expect frequent changes +- ✅ **Stable/maintained** - Mature codebase, incremental improvements +- 📦 **Infrastructure** - Operational tooling, minimal changes + +## Component Status Details + +### 🔥 Coprocessor (Highly Active) +**Recent Focus:** +- GPU scheduler improvements and memory management +- Metrics collection (SNS latency, ZK verify latency, tfhe-per-txn timing) +- Health checking in tfhe-worker and sns-worker +- Database optimization (indices on ciphertext_digest, schedule order) +- Compression for large ciphertexts +- Off-chain execution optimization + +**Implication:** Expect performance improvements and new optimization features. API relatively stable but internal architecture evolving. + +### 🔥 KMS Connector (Highly Active) +**Recent Focus:** +- Garbage collection implementation +- Database transaction management and retry logic +- Polling mechanisms and listener improvements +- Nonce manager with recoverable patterns +- Configuration updates (WebSocket to HTTP migration) + +**Implication:** Infrastructure hardening and reliability improvements. External KMS integration patterns maturing. + +### 🔥 Gateway Contracts (Highly Active) +**Recent Focus:** +- Payment protocol implementation (`ProtocolPayment` contract) +- Multi-sig contracts based on Safe Smart Account +- LayerZero cross-chain integration for testnet/mainnet +- Monitoring events and request ID validation + +**Implication:** Economic and cross-chain capabilities expanding. Expect new features for multi-chain deployments. + +### 🔥 Protocol Contracts (Highly Active) +**Recent Focus:** +- Staking/delegating contracts (`OperatorStaking`, `Rewarder`) +- Fee management and burner implementation +- Governance improvements (Safe ownership, admin modules) +- ERC1363 integration +- UUPS upgradeability patterns + +**Implication:** Economic layer maturing with staking and governance. Token mechanics actively evolving. + +### ✅ Host Contracts (Stable) +**Recent Focus:** +- ACL enhancements and permission model refinements +- Operator pricing mechanisms +- Minor optimizations and bug fixes + +**Implication:** Core execution layer is mature and stable. Changes are incremental improvements. + +### ✅ Library Solidity (Stable) +**Recent Focus:** +- Codegen consolidation to single location +- Type system improvements +- Developer experience enhancements + +**Implication:** Developer API is stable. Safe to build applications against this interface. + +## Recent Removals & Deprecations + +**Avoid documenting these deprecated items:** + +- `ProtocolOperatorRegistry` - Removed from protocol-contracts, replaced by `OperatorStaking` +- Distributed codegen - Consolidated to `/library-solidity/codegen/` +- Safe-specific tasks - Removed from gateway-contracts + +## What This Means for Documentation + +When expanding documentation: + +1. **High-priority areas** (🔥 Active): Expect APIs and internals to evolve. Document current state but note potential for change. +2. **Stable areas** (✅ Stable): Safe to create comprehensive, detailed documentation. Changes will be incremental. +3. **Infrastructure** (📦 Infra): Document operational patterns and deployment, less focus on internal details. + +--- + +**Next:** Dive into [Core Components](components/README.md) → diff --git a/docs/codebase/src/components/README.md b/docs/codebase/src/components/README.md new file mode 100644 index 0000000000..89d31aeaa7 --- /dev/null +++ b/docs/codebase/src/components/README.md @@ -0,0 +1,80 @@ +# Core Components + +FHEVM consists of seven major components, organized into three deployment layers: + +## On-Chain Components (Solidity) + +### 1. [Gateway Contracts](gateway-contracts.md) 🔥 +Bridge between on-chain smart contracts and off-chain compute infrastructure. Manages ciphertext commitments, decryption requests, cross-chain ACL, and KMS coordination. + +**Key contracts:** `GatewayConfig`, `Decryption`, `MultichainACL`, `CiphertextCommits` + +### 2. [Host Contracts](host-contracts.md) ✅ +On-chain symbolic execution of FHE workflows. Provides the core FHE execution interface for each supported EVM chain. + +**Key contracts:** `FHEVMExecutor`, `ACL`, `HCULimit`, `KMSVerifier` + +### 3. [Solidity Library](library-solidity.md) ✅ +Developer-facing FHE primitives for writing confidential smart contracts. Provides encrypted types and FHE operation API. + +**Key exports:** `FHE.sol`, encrypted types (`euint8`, `euint256`, `ebool`, `eaddress`) + +## Off-Chain Components (Rust) + +### 4. [Coprocessor](coprocessor.md) 🔥 +Rust-based asynchronous FHE computation engine. Performs actual TFHE operations off-chain and submits verified results. + +**Key crates:** `tfhe-worker`, `scheduler`, `zkproof-worker`, `host-listener`, `gw-listener` + +### 5. [KMS Connector](kms-connector.md) 🔥 +Interface between Gateway and Key Management System (KMS Core). Manages key generation, rotation, and decryption via MPC. + +**Key crates:** `gw-listener`, `kms-worker`, `transaction-sender` + +## Protocol Layer (Solidity) + +### 6. [Protocol Contracts](protocol-contracts.md) 🔥 +Protocol-level infrastructure including token, staking, and governance. + +**Key modules:** `token/`, `staking/`, `governance/`, `confidential-wrapper/` + +## Supporting Infrastructure + +### 7. [Supporting Infrastructure](infrastructure.md) 📦 +Deployment, testing, and operational tooling. + +**Key directories:** `charts/`, `test-suite/`, `docs/`, `sdk/` + +--- + +## Component Relationships + +``` +Developer Smart Contract + ↓ + Solidity Library (FHE.sol) + ↓ + Host Contracts (FHEVMExecutor) + ↓ + Gateway Contracts + ↓ + ┌────┴────┐ + ↓ ↓ +Coprocessor KMS Connector +``` + +**Flow:** +1. Developer uses Library to write contract with encrypted types +2. Contract calls Host Contracts for symbolic FHE operations +3. Host Contracts emit events picked up by Gateway +4. Gateway coordinates with Coprocessor (FHE compute) and KMS (key management) +5. Results flow back through Gateway → Host → Contract + +--- + +**Status Legend:** +- 🔥 Active development +- ✅ Stable/maintained +- 📦 Infrastructure + +Choose a component to explore its detailed documentation. diff --git a/docs/codebase/src/components/coprocessor.md b/docs/codebase/src/components/coprocessor.md new file mode 100644 index 0000000000..0f0f7009eb --- /dev/null +++ b/docs/codebase/src/components/coprocessor.md @@ -0,0 +1,438 @@ +# Coprocessor + +**Location**: `/coprocessor/` +**Status**: Active Development (1,718 commits in 6 months) +**Purpose**: Rust-based asynchronous FHE computation engine + +## Overview + +The Coprocessor is the off-chain component that performs actual FHE computations. It listens to events from Host and Gateway contracts, executes the expensive cryptographic operations, and submits results back to the chain. + +## Key Crates + +Located in `/coprocessor/fhevm-engine/`: + +| Crate | Purpose | +|-------|---------| +| `tfhe-worker` | Core FHE computation engine using TFHE-rs | +| `scheduler` | Dataflow graph and work distribution | +| `zkproof-worker` | Zero-knowledge proof verification | +| `sns-worker` | Switch-N-Squash noise reduction and S3 upload | +| `host-listener` | Monitors host chain events | +| `gw-listener` | Monitors gateway chain events | +| `transaction-sender` | Broadcasts results back to chain | +| `fhevm-engine-common` | Shared utilities, GPU memory, telemetry | + +## Architecture + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ COPROCESSOR │ +├─────────────────────────────────────────────────────────────────┤ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ +│ │ gw-listener │ │host-listener│ │ transaction-sender │ │ +│ └──────┬──────┘ └──────┬──────┘ └────────────▲────────────┘ │ +│ │ │ │ │ +│ ▼ ▼ │ │ +│ ┌──────────────────────────────────────────────┴──────────────┐│ +│ │ PostgreSQL Database ││ +│ │ (computations, ciphertexts, verify_proofs, tenants) ││ +│ └──────────────────────────────────────────────────────────────┘│ +│ │ │ ▲ │ +│ ▼ ▼ │ │ +│ ┌─────────────┐ ┌─────────────┐ ┌───────────┴───────────┐ │ +│ │ tfhe-worker │ │ sns-worker │ │ zkproof-worker │ │ +│ │ (GPU) │ │ (S3) │ │ │ │ +│ └─────────────┘ └─────────────┘ └───────────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +**Event-driven design:** +- Listeners pick up on-chain events and create jobs +- Jobs stored in PostgreSQL database with NOTIFY/LISTEN channels +- Scheduler distributes work to specialized workers +- Workers process jobs concurrently with GPU acceleration +- Results submitted back via transaction-sender + +--- + +## Worker Architecture + +### TFHE Worker (Core FHE Computation) + +**Location**: `fhevm-engine/tfhe-worker/src/tfhe_worker.rs` + +The TFHE Worker is the primary computation engine that executes FHE operations using TFHE-rs. It implements a hybrid polling strategy combining PostgreSQL notifications with interval-based fallback. + +**Processing Pipeline:** + +``` +┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ +│ LISTEN │───▶│ Query Work │───▶│ Build Graph │───▶│ Execute │ +│work_available│ │ (SKIP LOCK) │ │ (per tenant)│ │ (parallel) │ +└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ + │ +┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ NOTIFY │◀───│ Commit │◀───│Store Results │◀───────────┘ +│ computed │ │ Transaction │ │ (ciphertexts)│ +└──────────────┘ └──────────────┘ └──────────────┘ +``` + +**Key Implementation Details:** + +1. **Event Loop** (`tfhe_worker.rs:58-172`): + - Uses `PgListener` on `work_available` channel + - Falls back to polling every `worker_polling_interval_ms` if no notifications + - Immediately re-polls if work was found (no wait between batches) + +2. **Tenant Key Caching**: + - LRU cache with configurable size (default varies by deployment) + - Keys loaded lazily on first computation for tenant + - Separate Server Key (SKS) and Public Key (PKS) per tenant + +3. **Parallel Execution**: + - Uses `tokio::task::JoinSet` for blocking FHE operations + - Configurable thread counts: 32 FHE threads + 4 Tokio async threads + - GPU support via `#[cfg(feature = "gpu")]` with CUDA server keys + +4. **Metrics** (Prometheus): + - `coprocessor_worker_errors` - Error counter + - `coprocessor_work_items_polls` - Database poll counter + - `coprocessor_work_items_notifications` - Notification counter + - `coprocessor_work_items_processed` - Successful computation counter + +### SNS Worker (Switch-N-Squash) + +**Location**: `fhevm-engine/sns-worker/src/executor.rs` + +The SNS Worker performs Programmable Bootstrap (PBS) operations to reduce ciphertext noise, then uploads results to S3. + +**Dual Pipeline Architecture:** + +``` +┌────────────────────────────────────────────────────────────────┐ +│ SNS Worker │ +│ ┌─────────────────────┐ ┌─────────────────────────────┐ │ +│ │ Computation Pipeline│ │ Upload Pipeline │ │ +│ │ ─────────────────── │ │ ─────────────────────── │ │ +│ │ • Fetch ciphertexts │──────▶ • Queue UploadJob │ │ +│ │ • squash_noise() │ │ • Upload to S3 (ct64/ct128)│ │ +│ │ • Create 64/128 bit │ │ • Update ciphertext_digest │ │ +│ └─────────────────────┘ └─────────────────────────────┘ │ +└────────────────────────────────────────────────────────────────┘ +``` + +**Key Features:** +- **Schedule Policy**: Sequential or `RayonParallel` for PBS operations +- **Ciphertext Formats**: Creates both 64-bit compressed and 128-bit uncompressed +- **S3 Integration**: Configurable concurrent uploads, retry policy, bucket names +- **Health Checks**: S3 bucket readiness verification with 5s timeout + +**Metrics:** +- `coprocessor_sns_op_latency_seconds` - PBS operation timing +- `sns_worker_task_execute_success_counter` / `failure_counter` + +### ZKProof Worker (Proof Verification) + +**Location**: `fhevm-engine/zkproof-worker/src/verifier.rs` + +The ZKProof Worker verifies zero-knowledge proofs for encrypted operations using multi-threaded execution. + +**Configuration:** +- `worker_thread_count`: Default 8 verification threads +- `MAX_CACHED_TENANT_KEYS`: 100 entries in LRU cache +- `pg_polling_interval`: Default 60 seconds fallback poll + +**Processing:** +1. Listens on `event_ciphertext_computed` channel +2. Fetches proof verification requests from `verify_proofs` table +3. Loads tenant server keys (cached) +4. Verifies proof against ciphertext and auxiliary data +5. Updates `verify_proofs` with result (completed/error) + +**Error Types** (`scheduler/src/dfg/types.rs:59-90`): +```rust +pub enum SchedulerError { + CyclicDependence, // Dependency loop detected + DataflowGraphError, // Graph construction failed + MissingInputs, // Inputs not yet available + ReRandomisationError, // TFHE re-randomization failed + SchedulerError, // Generic scheduler error +} +``` + +--- + +## Scheduler and Job Orchestration + +### Job Lifecycle + +``` +┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ +│ Event │───▶│ Job │───▶│Schedule │───▶│ Execute │───▶│ Result │ +│Reception│ │Creation │ │(priority│ │ (graph) │ │Submission│ +│(listener)│ │(DB insert)│ │ queue) │ │ │ │(txn-sender)│ +└─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ +``` + +### Dataflow Graph + +**Location**: `fhevm-engine/scheduler/src/dfg/` + +The scheduler builds a Directed Acyclic Graph (DAG) of FHE operations using the `daggy` crate: + +```rust +pub struct DFComponentGraph { + graph: Dag, // Dependency graph + needed_map: HashMap, // Required ciphertexts + results: Vec, // Computed results +} + +pub enum DFGTaskInput { + Value(SupportedFheCiphertexts), // Scalar or ciphertext literal + Compressed((i16, Vec)), // Compressed from DB + Dependence(Handle), // Output from prior operation +} +``` + +### Scheduling Strategies + +**Location**: `scheduler/src/dfg/scheduler.rs:30-112` + +Two strategies controlled by `FHEVM_DF_SCHEDULE` environment variable: + +| Strategy | Description | Use Case | +|----------|-------------|----------| +| `MAX_PARALLELISM` | Maximize concurrent task execution | Default, best for GPU | +| `MAX_LOCALITY` | Optimize for cache locality on same device | Memory-bound workloads | + +**GPU Device Selection** (RoundRobin): +```rust +// scheduler.rs:139-150 +DeviceSelection::RoundRobin => { + static LAST: AtomicUsize = AtomicUsize::new(0); + let i = LAST.load(Ordering::Acquire); + LAST.store((i + 1) % self.csks.len(), Ordering::Release); + Ok((self.csks[i].clone(), self.cpk.clone())) +} +``` + +### Retry Logic and Error Handling + +**Exponential Backoff:** +- Failed computations marked with `uncomputable_counter` +- Schedule delay: `uncomputable_counter * 1 second` (doubles each retry) +- Maximum delay: 32,000 seconds (~9 hours) +- Re-attempted in subsequent worker cycles + +**Work Query with Non-Blocking Locks:** +```sql +SELECT transaction_id FROM computations +WHERE is_completed = FALSE AND is_error = FALSE AND is_allowed = TRUE +ORDER BY schedule_order +FOR UPDATE SKIP LOCKED +LIMIT $batch_size +``` + +--- + +## GPU Utilization + +### Memory Management + +**Location**: `fhevm-engine-common/src/gpu_memory.rs` + +GPU memory is managed with atomic per-GPU reservation pools: + +```rust +// Two-stage reservation protocol +pub fn reserve_memory_on_gpu(amount: u64, idx: usize) { + loop { + // Stage 1: Atomically add to reservation pool + let old_pool_size = gpu_mem_reservation[idx] + .fetch_add(amount, Ordering::SeqCst); + + // Stage 2: Validate against GPU capacity + if check_valid_cuda_malloc(old_pool_size + amount, GpuIndex::new(idx)) { + break; // Allocation successful + } else { + // Remove reservation, retry after 2ms backoff + gpu_mem_reservation[idx].fetch_sub(amount, Ordering::SeqCst); + std::thread::sleep(Duration::from_millis(2)); + } + } +} +``` + +**Type-Aware Sizing:** +- `get_size_on_gpu()` implemented for all FHE types +- Supports: FheBool, FheUint4-256, FheBytes64-256 +- Operation-specific sizing (e.g., `get_add_size_on_gpu()`) + +### Device Selection and Load Balancing + +- **RoundRobin**: Atomic counter distributes tasks across GPUs +- **Fallback**: Invalid device indices gracefully default to GPU 0 +- **Per-Tenant Isolation**: Server keys loaded per tenant + +### Performance Tuning + +**Thread Allocation** (configurable via CLI): +| Parameter | Default | Purpose | +|-----------|---------|---------| +| `coprocessor_fhe_threads` | 32 | Blocking FHE operations | +| `tokio_threads` | 4 | Async I/O coordination | +| `work_items_batch_size` | 100 | Items per worker cycle | +| `dependence_chains_per_batch` | 20 | Chains fetched per query | + +### Metrics + +| Metric | Description | +|--------|-------------| +| `coprocessor_fhe_batch_latency_seconds` | End-to-end FHE batch timing | +| `coprocessor_rerand_batch_latency_seconds` | Re-randomization batch timing | +| `coprocessor_sns_op_latency_seconds` | SNS PBS operation latency | + +--- + +## Database Schema + +### Core Tables + +**Location**: `fhevm-engine/db-migration/migrations/20240722111257_coprocessor.sql` + +``` +┌─────────────────────┐ ┌─────────────────────┐ +│ computations │ │ ciphertexts │ +├─────────────────────┤ ├─────────────────────┤ +│ tenant_id (PK) │ │ tenant_id (PK) │ +│ output_handle (PK) │──────▶│ handle (PK) │ +│ transaction_id (PK) │ │ ciphertext_version │ +│ dependencies[] │ │ ciphertext (BYTEA) │ +│ fhe_operation │ │ ciphertext_type │ +│ is_completed │ │ input_blob_hash │ +│ is_error │ └─────────────────────┘ +│ schedule_order │ +│ uncomputable_counter│ ┌─────────────────────┐ +└─────────────────────┘ │ tenants │ + ├─────────────────────┤ +┌─────────────────────┐ │ tenant_id (PK) │ +│ ciphertext_digest │ │ tenant_api_key │ +├─────────────────────┤ │ chain_id │ +│ tenant_id (PK) │ │ pks_key (BYTEA) │ +│ handle (PK) │ │ sks_key (BYTEA) │ +│ ciphertext (ct64) │ │ public_params │ +│ ciphertext128 │ └─────────────────────┘ +│ ciphertext128_format│ +│ txn_is_sent │ +│ created_at │ +└─────────────────────┘ +``` + +### Indices and Query Optimization + +**December 2025 Optimizations:** + +1. **Pending Tasks Index** (`20251205070512`): + ```sql + CREATE INDEX idx_pending_tasks + ON pbs_computations USING btree (created_at) + WHERE is_completed = false; + ``` + - Selective index (only incomplete tasks) + - Enables efficient backlog queries + +2. **Ciphertext Digest Indices** (`20251203140023`): + ```sql + CREATE INDEX idx_ciphertext_digest_handle + ON ciphertext_digest (handle); + + CREATE INDEX idx_ciphertext_digest_unsent + ON ciphertext_digest (txn_is_sent, created_at); + ``` + - Fast handle lookups for transaction-sender + - FIFO ordering for fair transaction processing + +**Index Types:** +- `BTREE`: Range scans, ordering (schedule_order, created_at) +- `GIN`: Array containment (dependencies) +- `HASH`: Equality lookups (transaction_id) + +### Ciphertext Storage Patterns + +**Compression Format Tracking:** +```sql +-- ciphertext128_format values: +-- 0 = Unknown +-- 10 = UncompressedOnCpu +-- 11 = CompressedOnCpu +-- 20 = UncompressedOnGpu +-- 21 = CompressedOnGpu +``` + +**S3 Digest Storage:** +- `ciphertext` column: 64-bit compressed digest +- `ciphertext128` column: 128-bit digest +- Nullable fields allow gradual migration to 128-bit format + +--- + +## Cross-Component Integration + +### Gateway Integration + +**Event Reception** (`gw-listener/src/gw_listener.rs`): +- WebSocket subscription via `eth_subscribe` to InputVerification contract +- Handles `VerifyProofRequest` events +- Polling-based for `ActivateCrs` and `ActivateKey` from KMSGeneration + +**Result Submission** (`transaction-sender/src/ops/`): +- `verify_proof.rs`: Submits verified proofs to InputVerification +- `add_ciphertext.rs`: Submits ciphertexts to CiphertextCommitment +- `allow_handle.rs`: Submits handle allowances to MultiChainACL + +### KMS Integration + +**Key Management:** +- KMS keys received via Gateway `ActivateKey` events +- S3 download for large key files +- Stored in PostgreSQL `tenants` table (sks_key, pks_key, public_params) + +### PostgreSQL Event Channels + +| Channel | Producer | Consumer | Trigger | +|---------|----------|----------|---------| +| `work_available` | host-listener | tfhe-worker | New computation job | +| `event_ciphertext_computed` | tfhe-worker | sns-worker, zkproof-worker | FHE computation done | +| `event_zkpok_computed` | zkproof-worker | transaction-sender | Proof verified | +| `event_allowed_handle` | (internal) | transaction-sender | Handle allowance ready | + +--- + +## Recent Development Focus (Dec 2025) + +- **GPU optimization**: Two-stage memory reservation, RoundRobin device selection +- **Database indices**: Selective indices on pending tasks, FIFO ordering for transactions +- **Metrics collection**: SNS latency, ZK verify latency, FHE batch timing histograms +- **Health checking**: S3 readiness checks, liveness thresholds per worker +- **Compression**: Format tracking for 64-bit/128-bit ciphertexts + +--- + +## Key Files Reference + +| File | Purpose | +|------|---------| +| `tfhe-worker/src/tfhe_worker.rs` | Main FHE worker loop | +| `scheduler/src/dfg/scheduler.rs` | Scheduling strategies | +| `fhevm-engine-common/src/gpu_memory.rs` | GPU memory management | +| `sns-worker/src/executor.rs` | SNS service and S3 upload | +| `zkproof-worker/src/verifier.rs` | ZK proof verification | +| `db-migration/migrations/*.sql` | Database schema | + +--- + +**Related:** +- [Gateway Contracts](gateway-contracts.md) - Provides events that trigger coprocessor jobs +- [KMS Connector](kms-connector.md) - Provides key material for operations +- [Architecture](../architecture.md) - Coprocessor's role in overall system diff --git a/docs/codebase/src/components/gateway-contracts.md b/docs/codebase/src/components/gateway-contracts.md new file mode 100644 index 0000000000..4663dec75d --- /dev/null +++ b/docs/codebase/src/components/gateway-contracts.md @@ -0,0 +1,250 @@ +# Gateway Contracts 🔥 + +**Location**: `/gateway-contracts/` +**Status**: Active Development +**Purpose**: Bridge between on-chain smart contracts and off-chain compute infrastructure + +## Overview + +The Gateway contracts serve as the coordination layer that manages communication between the blockchain and off-chain services. They handle ciphertext commitments, decryption requests, input verification, and access control across multiple chains. + +## Key Contracts + +| Contract | Purpose | +|----------|---------| +| `GatewayConfig.sol` | Central registry for KMS nodes, coprocessors, and protocol metadata | +| `Decryption.sol` | Manages public and user decryption requests with EIP712 signature validation | +| `MultichainACL.sol` | Access control for cross-chain operations and user delegations | +| `CiphertextCommits.sol` | Stores ciphertext material commitments from coprocessors | +| `InputVerification.sol` | Verifies encrypted user inputs via ZK proofs | +| `KMSGeneration.sol` | Orchestrates key generation and reshare operations | +| `ProtocolPayment.sol` | Handles protocol fee collection and distribution | + +## Key Files + +- `contracts/GatewayConfig.sol` - Gateway registry and configuration +- `contracts/Decryption.sol` - Decryption request handling +- `contracts/shared/Structs.sol` - Core data structures (KmsNode, Coprocessor, etc.) + +## Relationships + +Gateway contracts receive events from Host contracts and coordinate with the Coprocessor and KMS Connector to process FHE operations. They maintain consensus through threshold signatures from multiple coprocessors. + +## Recent Development Focus (Dec 2025) + +- Payment protocol implementation (`ProtocolPayment` contract) +- Multi-sig contracts based on Safe Smart Account +- LayerZero cross-chain integration for testnet/mainnet +- Monitoring events and request ID validation + +## Areas for Deeper Documentation + +### Gateway Consensus Mechanism + +The Gateway implements a **threshold-based consensus system** for ciphertext commits, ensuring Byzantine-fault-tolerant agreement among multiple independent coprocessors on FHE computation results. + +**Architecture** (`contracts/CiphertextCommits.sol`): + +The consensus mechanism revolves around the `addCiphertextMaterial()` function (lines 121-189), which aggregates votes from coprocessors. Each coprocessor submits ciphertext metadata including: +- `ctHandle` - unique ciphertext identifier +- `keyId` - encryption key reference +- `ciphertextDigest` - hash of the encrypted data +- `snsCiphertextDigest` - hash of the Switch-and-Squash transformed version + +**Vote Aggregation Process**: + +1. **Hash-Based Voting**: All parameters are hashed together to create a unique `addCiphertextHash`. Coprocessors can only reach consensus if they provide identical data for all parameters. + +2. **Deduplication**: The mapping `alreadyAddedCoprocessorTxSenders[ctHandle][msg.sender]` prevents any coprocessor from voting twice on the same ciphertext handle. + +3. **Counter Increment**: Each vote increments `addCiphertextHashCounters[addCiphertextHash]`, tracking how many coprocessors agree on this exact data combination. + +4. **Threshold Check**: Consensus is reached when `counter >= GATEWAY_CONFIG.getCoprocessorMajorityThreshold()`. This threshold is configured in `contracts/GatewayConfig.sol` (lines 790-805) and must be ≥1 and ≤ total coprocessors. + +**Consensus Finalization**: + +When the threshold is reached, the contract: +- Permanently stores the ciphertext digests and keyId +- Marks the handle as committed via `isCiphertextMaterialAdded[ctHandle] = true` +- Records the consensus hash for audit trails +- Emits `AddCiphertextMaterialConsensus` event with the list of participating coprocessors + +**Byzantine Fault Tolerance**: + +The system handles malicious or faulty coprocessors through data isolation. If Coprocessor A submits different data than Coprocessors B and C, A's vote creates a different hash and counts separately. Consensus is reached on the data agreed upon by the threshold majority, effectively excluding dishonest participants from the final commitment. + +**Late Arrivals**: Coprocessors that respond after consensus has been reached have their votes recorded but don't re-trigger consensus events. This ensures all valid responses are acknowledged without duplicate processing. + +**Data Retrieval**: The `getCiphertextMaterials()` function (lines 202-234) returns committed ciphertext metadata along with the complete list of coprocessors that participated in consensus, enabling full auditability of the agreement process. + +### Multichain ACL Flow + +The `MultichainACL` contract (`contracts/MultichainACL.sol`) provides a sophisticated cross-chain access control system for user decryption delegations, allowing users on one chain to delegate decryption rights to others across multiple host chains. + +**Delegation Model**: + +Delegations are stored in a four-dimensional mapping indexed by `(chainId, delegator, delegate, contractAddress)`, with each delegation containing: +- `expirationDate` (uint64) - UNIX timestamp when delegation expires +- `delegationCounter` (uint64) - monotonically increasing counter for ordering + +**Delegation Lifecycle** (lines 233-310): + +1. **Initiation**: Coprocessors call `delegateUserDecryption()` with delegation parameters including the target chain ID, delegator, delegate, contract address, counter, and expiration date. + +2. **Hash-Based Agreement**: All parameters (including the expiration date) are hashed together using `DELEGATE_USER_DECRYPTION_DOMAIN_SEPARATOR_HASH`. This ensures coprocessors can only reach consensus if they agree on the complete delegation specification. + +3. **Consensus Accumulation**: Each coprocessor's vote is recorded via `alreadyDelegatedUserDecryptionCoprocessors[hash][msg.sender]`, preventing double-voting. The system tracks participating coprocessors in `delegateUserDecryptionTxSenders[hash]`. + +4. **Finalization**: When the threshold is reached (via `GATEWAY_CONFIG.getCoprocessorMajorityThreshold()`), the delegation is finalized only if its counter is strictly greater than the previous counter for that (delegator, delegate, contract) triple. This prevents replay attacks and enforces chronological ordering. + +5. **Event Emission**: The `DelegateUserDecryptionConsensus` event is emitted with both old and new expiration dates, enabling off-chain systems to track delegation state changes. + +**Cross-Chain Synchronization**: + +The system doesn't rely on cross-chain messaging. Instead, each host chain's ACL state is mirrored in the Gateway's storage, with coprocessors acting as oracles that monitor host chain events and report them to the Gateway. The consensus mechanism ensures that multiple independent coprocessors agree on the chain state before it's accepted. + +**Revocation Flow** (lines 313-389): + +Revocations follow a similar pattern but set `expirationDate = 0`. Critically, a coprocessor cannot vote for both delegation and revocation of the same hash - the contract enforces mutual exclusivity via `_checkAlreadyDelegatedOrRevokedUserDecryptionDelegation()` (lines 580-621). + +**Counter-Based Ordering**: + +The monotonic counter requirement solves several problems: +- **Out-of-order prevention**: Even if network delays cause operations to arrive out of sequence, only higher counters are accepted +- **Revocation protection**: An old delegation can't override a newer revocation +- **Replay prevention**: Previously used counters can't be reused + +**State Queries**: + +- `isUserDecryptionDelegated()` checks if a delegation is currently active (counter exists and expiration > block.timestamp) +- `getDelegateUserDecryptionConsensusTxSenders()` returns the list of coprocessors that participated in a specific delegation consensus + +**Integration with Decryption**: + +When processing user decryption requests, the `Decryption` contract uses `MultichainACLChecks._checkIsUserDecryptionDelegated()` to verify that the delegate has valid permission from the delegator for the specific contract context, respecting per-chain delegation boundaries. + +### Payment Protocol Design + +The `ProtocolPayment` contract (`contracts/ProtocolPayment.sol`) implements a modular fee collection system for Gateway operations, denominated in the $ZAMA token (ERC20 with 18 decimals). + +**Fee Structure**: + +Three distinct fee types are managed independently: +- **Input Verification Fee** - Charged when users submit encrypted inputs via `InputVerification.sol` +- **Public Decryption Fee** - Charged when contracts request public decryption via `Decryption.sol` +- **User Decryption Fee** - Charged when users request private reencryption via `Decryption.sol` + +Each fee is stored in the `ProtocolPaymentStorage` structure (ERC-7201 pattern) and can be updated independently by the Gateway Owner via `setInputVerificationPrice()`, `setPublicDecryptionPrice()`, and `setUserDecryptionPrice()`. + +**Collection Mechanism**: + +The protocol follows a caller-pays model. When a user or contract initiates an operation: + +1. The `InputVerification` or `Decryption` contract calls the appropriate fee collection method (`collectInputVerificationFee()`, `collectPublicDecryptionFee()`, or `collectUserDecryptionFee()`) + +2. Authorization is enforced via `onlyInputVerificationContract` or `onlyDecryptionContract` modifiers, ensuring only legitimate protocol contracts can trigger fee collection + +3. The contract uses ERC20 `transferFrom()` to move $ZAMA tokens from the transaction sender to the `FeesSenderToBurner` address + +4. If the transfer fails (insufficient balance or allowance), the entire operation reverts + +**Integration Pattern**: + +Gateway contracts inherit from `ProtocolPaymentUtils` (`contracts/shared/ProtocolPaymentUtils.sol`), which provides convenience wrappers like `_collectInputVerificationFee(address txSender)`. This abstraction allows easy integration without tight coupling to the payment implementation. + +**Operator Compensation**: + +The current design transfers fees to `FeesSenderToBurner`, which acts as an aggregation point. The actual distribution to operators (coprocessors, KMS nodes, relay services) happens through an external system not directly managed by these contracts. This separation allows for flexible compensation models without requiring protocol upgrades. + +**Upgradeability**: + +The contract uses the UUPS (Universal Upgradeable Proxy Standard) pattern, allowing the Gateway Owner to upgrade pricing logic, add new fee types, or modify the distribution mechanism without disrupting existing operations. Version tracking (currently v0.1.0) ensures compatibility during upgrades. + +### KMS Coordination + +The Gateway orchestrates cryptographic key lifecycle management through the `KMSGeneration` contract (`contracts/KMSGeneration.sol`), implementing a consensus-based protocol for key generation and activation. + +**KMS Node Structure** (from `contracts/shared/Structs.sol`): + +Each registered KMS node has: +- `txSenderAddress` - Transaction submission address +- `signerAddress` - EIP712 signature address +- `ipAddress` - Network location +- `storageUrl` - Key material storage endpoint + +**Two-Phase Key Generation Protocol**: + +The protocol separates key preprocessing from actual key generation, enabling efficient multi-party computation: + +**Phase 1: Preprocessing Keygen** +1. Gateway Owner calls `keygen(paramsType)` specifying FHE parameters (Default or Test) +2. Contract generates a unique `prepKeygenId` and paired `keyId` using counters with distinct prefixes (0x03... and 0x04...) +3. `PrepKeygenRequest` event is emitted +4. KMS nodes sign the `prepKeygenId` with EIP712 (`PrepKeygenVerification` typed data) +5. Each node calls `prepKeygenResponse(prepKeygenId, signature)` with their signature +6. Signatures are validated using ECDSA recovery, checking both that the signer is authorized (`isKmsSigner()`) and matches the transaction sender +7. When consensus threshold is reached (via `GATEWAY_CONFIG.getKmsGenThreshold()`), `KeygenRequest` event is emitted + +**Phase 2: Actual Keygen** +1. KMS nodes perform off-chain MPC to generate key material +2. Each node signs the `keyId` and key digests with EIP712 (`KeygenVerification` typed data) +3. Key digests include both server keys (type 0) and public keys (type 1) +4. Nodes call `keygenResponse(keyId, keyDigests, signature)` +5. After consensus, the contract stores key digests and emits `ActivateKey` with storage URLs from all participating KMS nodes +6. The key becomes the active key via `setActiveKeyId(keyId)` + +**CRS Generation**: + +Common Reference String (CRS) generation follows a similar consensus pattern: +1. Gateway Owner calls `crsgenRequest(maxBitLength, paramsType)` +2. KMS nodes respond with `crsgenResponse(crsId, crsDigest, signature)` +3. Upon consensus, `ActivateCrs` is emitted with storage URLs and digest +4. CRS is activated via `setActiveCrsId(crsId)` + +**Request ID Uniqueness**: + +The system uses counter bases defined in `contracts/shared/KMSRequestCounters.sol`: +- `0x0300...` for prep keygen +- `0x0400...` for keygen +- `0x0500...` for CRS generation +- `0x0600...` for key reshare + +This ensures globally unique request IDs across all operation types. + +**Consensus Storage**: + +The `KMSGenerationStorage` structure tracks: +- `kmsHasSignedForResponse[requestId][kmsSigner]` - Prevents double-signing +- `isRequestDone[requestId]` - Marks completed requests +- `consensusTxSenderAddresses[requestId][digest]` - Lists participants for each digest +- `consensusDigest[requestId]` - Final agreed-upon digest +- `keygenIdPairs[id]` - Bidirectional mapping between prepKeygenId ↔ keyId +- `activeKeyId` and `activeCrsId` - Currently active cryptographic material + +**Integration with Decryption**: + +When the `Decryption` contract emits `PublicDecryptionRequest` or `UserDecryptionRequest` events, these reference the `activeKeyId`. KMS nodes: +1. Query `getActiveKeyId()` to identify which key to use +2. Call `getKeyMaterials(keyId)` to retrieve storage URLs and digests +3. Fetch key material from their storage endpoints +4. Perform decryption operations off-chain +5. Submit results back to the Decryption contract with signatures + +**Storage URL Coordination**: + +When consensus is reached, the contract queries `GATEWAY_CONFIG.getKmsNode(address)` for each participating KMS transaction sender and aggregates their storage URLs. This ensures clients can retrieve key material from multiple redundant sources, improving availability and fault tolerance. + +**EIP712 Security**: + +All KMS responses use typed structured data signatures (EIP712), providing: +- Human-readable signature content for hardware wallet users +- Type safety preventing signature malleability +- Domain separation preventing cross-contract replay attacks +- Clear accountability for each KMS node's responses + +--- + +**Related:** +- [Host Contracts](host-contracts.md) - Emit events that Gateway processes +- [Coprocessor](coprocessor.md) - Processes Gateway-coordinated FHE operations +- [KMS Connector](kms-connector.md) - Handles Gateway key management requests diff --git a/docs/codebase/src/components/host-contracts.md b/docs/codebase/src/components/host-contracts.md new file mode 100644 index 0000000000..cdc881d0fe --- /dev/null +++ b/docs/codebase/src/components/host-contracts.md @@ -0,0 +1,63 @@ +# Host Contracts ✅ + +**Location**: `/host-contracts/` +**Status**: Stable +**Purpose**: On-chain symbolic execution of FHE workflows on the host EVM chain + +## Overview + +Host contracts are deployed on each supported EVM chain and provide the core FHE execution interface. They execute operations symbolically (generating deterministic handles) while the actual encrypted computation happens off-chain. + +## Key Contracts + +| Contract | Purpose | +|----------|---------| +| `FHEVMExecutor.sol` | Symbolic execution engine with 20+ FHE operators | +| `ACL.sol` | Access control for encrypted data handles | +| `HCULimit.sol` | Enforces Homomorphic Complexity Unit limits per transaction | +| `KMSVerifier.sol` | Verifies KMS-signed decryption results | +| `InputVerifier.sol` | Verifies encrypted user input proofs (host-side) | + +> **Note**: Both Gateway (`InputVerification.sol`) and Host (`InputVerifier.sol`) have input verification. Gateway handles cross-chain verification; Host handles local chain verification. In single-chain deployments, Host's InputVerifier is the primary entry point. + +## Key Files + +- `contracts/FHEVMExecutor.sol` - Core symbolic execution (fheAdd, fheMul, fheEq, etc.) +- `contracts/ACL.sol` - Permission management for ciphertext handles +- `contracts/shared/FheType.sol` - Encrypted type definitions + +## Relationships + +Host contracts receive calls from user smart contracts via the FHE library. They emit events that the Coprocessor's host-listener picks up. Results from the Coprocessor are verified via KMSVerifier before being accepted. + +## FHEVMExecutor Operations + +The FHEVMExecutor provides 20+ symbolic FHE operations: + +**Arithmetic:** `fheAdd`, `fheSub`, `fheMul`, `fheDiv`, `fheRem`, `fheMin`, `fheMax` +**Comparison:** `fheEq`, `fheNe`, `fheLt`, `fheLe`, `fheGt`, `fheGe` +**Bitwise:** `fheBitAnd`, `fheBitOr`, `fheBitXor`, `fheNot`, `fheShl`, `fheShr` +**Special:** `fheRotl`, `fheRotr`, `fheSelect` (ternary) + +Each operation: +1. Validates input handles and types +2. Generates deterministic output handle +3. Emits event for coprocessor +4. Returns handle immediately (symbolic) + +## Areas for Deeper Documentation + +**[TODO: FHEVMExecutor operators]** - Document all 20+ FHE operators (fheAdd, fheSub, fheMul, fheDiv, fheEq, fheLt, fheGt, fheBitAnd, fheBitOr, fheBitXor, fheShl, fheShr, fheRotl, fheRotr, etc.) and their symbolic execution semantics + +**[TODO: ACL permission model]** - Detail the allowList, denyList, and delegation mechanisms for controlling access to encrypted values + +**[TODO: HCU limit enforcement]** - Explain the 20M HCU/tx and 5M depth limits and how they prevent DoS attacks + +**[TODO: Input verification flow]** - Document ZK proof verification for user-submitted encrypted inputs + +--- + +**Related:** +- [Solidity Library](library-solidity.md) - Developer-facing API that calls Host Contracts +- [Gateway Contracts](gateway-contracts.md) - Receives Host Contract events +- [Coprocessor](coprocessor.md) - Listens to Host Contract events via host-listener diff --git a/docs/codebase/src/components/infrastructure.md b/docs/codebase/src/components/infrastructure.md new file mode 100644 index 0000000000..88d3817cec --- /dev/null +++ b/docs/codebase/src/components/infrastructure.md @@ -0,0 +1,284 @@ +# Supporting Infrastructure 📦 + +**Location**: Various directories +**Status**: Infrastructure / Maintenance +**Purpose**: Deployment, testing, and operational tooling + +## Overview + +Supporting infrastructure enables development, testing, and deployment of the FHEVM stack. While not part of the core protocol, these components are essential for operating and maintaining FHEVM systems. + +## Directories + +| Directory | Purpose | +|-----------|---------| +| `/charts/` | Helm charts for Kubernetes deployment | +| `/test-suite/` | E2E integration tests with docker-compose | +| `/golden-container-images/` | Base Docker images for Node.js and Rust | +| `/docs/` | Gitbook documentation source | +| `/sdk/` | Rust SDK for building applications | +| `/ci/` | CI/CD pipeline configurations | + +## Testing Infrastructure + +### Test Types + +**Unit/Integration Tests:** +- **Hardhat tests**: Located in `host-contracts/test/`, `library-solidity/test/` +- **Foundry tests**: Solidity-native tests via `forge test` +- Written in TypeScript (Hardhat) or Solidity (Foundry) + +**E2E Tests:** +- **Full-stack tests**: Located in `test-suite/` +- **Orchestration**: Docker Compose brings up entire stack +- **Mock FHE**: SQLite-backed mocking for fast testing without real FHE + +### Mock FHE System + +For development and testing, FHEVM includes a mock FHE system: +- Replaces expensive FHE operations with simple encryption +- Backed by SQLite for ciphertext storage +- Enables fast iteration without coprocessor +- Maintains API compatibility with real FHE + +### Key Test Files + +- `test-suite/docker-compose.yml` - Full stack orchestration +- `host-contracts/hardhat.config.ts` - Hardhat configuration +- `library-solidity/foundry.toml` - Foundry configuration + +## Deployment Infrastructure + +### Kubernetes / Helm + +Located in `/charts/`: +- Helm charts for deploying FHEVM components +- Kubernetes manifests and configurations +- Emerging as primary deployment method + +### Docker Images + +Located in `/golden-container-images/`: +- Base images for Node.js services +- Base images for Rust services +- Standardized build environments + +## Development SDK + +Located in `/sdk/`: +- Rust SDK for building FHEVM applications +- Currently in maintenance mode (low activity) +- Provides client libraries for interacting with FHEVM + +## CI/CD + +Located in `/.github/workflows/`: +- GitHub Actions workflow definitions +- Automated testing on PR +- Build and publish pipelines +- Security scanning + +## Key Files + +- `test-suite/docker-compose.yml` - Full stack orchestration +- `host-contracts/hardhat.config.ts` - Hardhat configuration +- `.github/workflows/` - CI pipeline definitions + +## Areas for Deeper Documentation + +### Mock FHE System Architecture + +The mock FHE system enables rapid development and testing by simulating FHE operations without cryptographic overhead. This two-layer architecture—Solidity mock contracts and TypeScript simulation libraries—maintains full API compatibility with real FHEVM while reducing test execution time from minutes to seconds. Developers can compute test coverage (only possible in mocked mode), use Hardhat debugging tools (`evm_snapshot`, `evm_revert`), and iterate quickly before final validation on real FHEVM infrastructure. + +#### Solidity Mock Contracts + +Located in `/gateway-contracts/contracts/mocks/`, seven mock contracts simulate the gateway protocol layer: + +**DecryptionMock.sol** - Simulates public and user-initiated decryption workflows, emitting `PublicDecryptionRequest/Response` and `UserDecryptionRequest/Response` events. Uses counter with bits 248+ reserved: `1 << 248` for public, `2 << 248` for user decryptions. + +**KMSGenerationMock.sol** - Mocks Key Management System operations including keygen, CRS generation, and key resharing. Counter reserves: `3 << 248` (PrepKeygen), `4 << 248` (Key), `5 << 248` (CRS), `6 << 248` (KeyReshare). + +**InputVerificationMock.sol** - Simulates ZK proof verification for encrypted user inputs, emitting `VerifyProofRequest/Response` events with simple incremental counter. + +**GatewayConfigMock.sol**, **CiphertextCommitsMock.sol**, **MultichainACLMock.sol**, **ProtocolPaymentMock.sol** - Mock configuration, ciphertext storage, cross-chain ACL, and payment protocol respectively. + +These contracts emit events identical to real gateway contracts but perform no actual cryptographic operations. The bit-shifting counter pattern prevents ID collisions between different operation types while maintaining protocol compatibility. + +#### TypeScript Mocking Layer + +The `fhevmjsMocked.ts` library (mirrored in `/host-contracts/test/` and `/library-solidity/test/`) provides client-side encryption simulation: + +**createEncryptedInputMocked(contractAddress, userAddress)** - Builder pattern for encrypted inputs supporting all types (`addBool`, `add8`, `add16`, `add32`, `add64`, `add128`, `addAddress`, `add256`). Implementation at `/host-contracts/test/fhevmjsMocked.ts:61-100` packs values in big-endian format, appends 32 random bytes to simulate encryption noise, prepends type byte (ebool=0, euint8=2, euint16=3, etc.), then generates handles via Keccak256 hash combined with index and chain ID. + +**createUintToUint8ArrayFunction(numBits)** - Core encryption simulator converts plaintext numbers into encrypted-looking buffers with type information and random padding, maintaining the appearance of real FHE ciphertexts without computational cost. + +**userDecryptRequestMocked()** - Immediately returns decrypted values after validating EIP-712 signatures and ACL permissions, bypassing asynchronous coprocessor workflows. + +**computeInputSignaturesCopro() / coprocSign()** - Simulates coprocessor signatures using EIP-712 typed data, enabling tests to verify signature validation logic. + +#### Development Workflow + +**Fast Iteration**: Run `pnpm test` for full test suite completion in seconds instead of minutes. Tests written for mocked mode run unchanged on real FHEVM—same JavaScript, same Solidity. + +**Coverage Computation**: Execute `pnpm coverage` to generate coverage reports via `solidity-coverage` (only functional in mocked mode). Open `coverage/index.html` to identify untested branches. Tag tests using `evm_snapshot` with `[skip-on-coverage]` suffix to avoid `solidity-coverage` limitations. + +**Final Validation**: Before deployment, validate with real FHEVM using `pnpm test:hardhat` to ensure cryptographic operations behave correctly. Mock tests catch logic errors; real FHEVM tests catch cryptographic integration issues. + +**Debugging**: Mocked mode supports full Hardhat toolchain including `evm_mine`, `evm_snapshot`, `evm_revert`, and standard Ethereum JSON-RPC methods unavailable on FHEVM nodes. + +#### Mock vs Real FHE Comparison + +| Aspect | Mock Mode | Real FHEVM | +|--------|-----------|------------| +| **Test Duration** | Seconds (full suite) | Minutes per test | +| **Encryption** | Random bytes + type byte | TFHE-rs cryptographic encryption | +| **Decryption** | Immediate return | Async coprocessor processing | +| **Infrastructure** | Local Hardhat node | FHEVM node + coprocessor + KMS | +| **Coverage** | Computable via `solidity-coverage` | Not computable | +| **Debugging** | Full Hardhat toolchain | Limited RPC methods | +| **Use Case** | Development, unit tests, coverage | Pre-deployment validation, E2E | + +**Key Implementation Files:** +- `/gateway-contracts/contracts/mocks/*.sol` - Seven Solidity mock contracts (DecryptionMock, KMSGenerationMock, InputVerificationMock, GatewayConfigMock, CiphertextCommitsMock, MultichainACLMock, ProtocolPaymentMock) +- `/host-contracts/test/fhevmjsMocked.ts` - TypeScript mocking library (432 lines) +- `/library-solidity/test/fhevmjsMocked.ts` - Mirrored TypeScript implementation (484 lines) +- `/gateway-contracts/test/mocks/mocks.ts` - Mock contract test suite (451 lines) +- `/docs/solidity-guides/mocked.md` - Developer user guide for mocked mode + +**[TODO: Deployment guide]** - Document the Helm charts, Kubernetes deployment process, configuration options, and operational best practices. + +### E2E Testing Patterns + +FHEVM's E2E tests validate complete encrypted workflows from input encryption through FHE computation to decryption. Unlike unit tests with mocked FHE operations, E2E tests run against two local Anvil chains orchestrated by Docker Compose, verifying actual cryptographic operations. Tests use the Mocha framework with Hardhat, following a fixture pattern that separates deployment logic from test assertions. + +#### Two-Chain Architecture + +E2E tests require two independent EVM chains: + +- **Host Chain** (ID: 12345, port 8545): Runs FHEVM contracts, ACL, and application logic +- **Gateway Chain** (ID: 54321, port 8546): Manages KMS nodes, decryption requests, and input verification + +This separation mirrors production architecture where FHE infrastructure is isolated from application contracts. Both chains communicate via contract address registration stored in a shared Docker volume (`addresses-volume`), enabling tests to bridge operations across chains. + +``` +┌─────────────────────┐ ┌──────────────────────┐ +│ Host Chain │ │ Gateway Chain │ +│ (12345:8545) │◄───────►│ (54321:8546) │ +│ - FHEVM Contracts │ │ - KMS │ +│ - ACL │ │ - Input Verifier │ +└─────────────────────┘ └──────────────────────┘ + │ │ + └───────────────────────────────┘ + Shared addresses-volume +``` + +#### Docker Compose Infrastructure + +**Gateway Stack** (`gateway-contracts/docker-compose.yml`): Deploys 9 services including `anvil-node` (port 8546), contract deployments (`deploy-gateway-contracts`), host chain registration (`add-host-chains`), and cryptographic setup (`trigger-keygen`, `trigger-crsgen`). + +**Host Stack** (`host-contracts/docker-compose.yml`): Deploys 3 services including `anvil-node` (port 8545), FHEVM contracts (`fhevm-sc-deploy`), and pauser configuration. + +Services use `depends_on` with `service_completed_successfully` to enforce deployment order: + +```yaml +deploy-gateway-contracts: + depends_on: + anvil-node: + condition: service_started + deploy-mocked-zama-oft: + condition: service_completed_successfully + volumes: + - addresses-volume:/app/addresses # Shared contract discovery +``` + +#### Test Anatomy + +Tests follow a consistent pattern with fixtures handling deployment and test files containing assertions: + +```typescript +// From test-suite/e2e/test/encryptedERC20/EncryptedERC20.ts:10-20 +describe('EncryptedERC20', function () { + before(async function () { + await initSigners(2); // Initialize named test accounts + this.signers = await getSigners(); + }); + + beforeEach(async function () { + const contract = await deployEncryptedERC20Fixture(); + this.contractAddress = await contract.getAddress(); + this.erc20 = contract; + this.instances = await createInstances(this.signers); + }); +}); +``` + +**Named Signers**: Tests use pre-defined accounts (alice, bob, carol, dave, eve, fred) with automatic fauceting via `initSigners()`. See `host-contracts/test/signers.ts:10-16` for the interface definition. + +**Fixture Pattern**: Deployment logic lives in separate files: + +```typescript +// From test-suite/e2e/test/encryptedERC20/EncryptedERC20.fixture.ts:6-14 +export async function deployEncryptedERC20Fixture() { + const signers = await getSigners(); + const contractFactory = await ethers.getContractFactory('EncryptedERC20'); + const contract = await contractFactory.connect(signers.alice) + .deploy('Naraggara', 'NARA'); + await contract.waitForDeployment(); + return contract; +} +``` + +**Typical Test Flow**: Mint → Encrypt Input → Execute → Decrypt → Verify. See `test-suite/e2e/test/encryptedERC20/EncryptedERC20.ts:58-103` for a complete transfer example using encrypted amounts. + +#### Running Tests + +```bash +# Run all E2E tests +cd test-suite/e2e +./run-tests.sh + +# Run specific test pattern +./run-tests.sh -g "transfer tokens" + +# Verbose output for debugging +./run-tests.sh -v -g "pattern" + +# Target specific network (default: staging = chain 12345) +./run-tests.sh -n staging -g "pattern" +``` + +**Configuration**: Tests use the `staging` network (chain ID 12345) with Mocha timeout set to 300000ms (5 minutes) to accommodate slow FHE operations. See `test-suite/e2e/hardhat.config.ts:75-88`. + +#### Common Issues & Debugging + +| Issue | Symptom | Solution | +|-------|---------|----------| +| **Address Not Found** | `Cannot read address` error | Verify `addresses-volume` mounted; ensure `docker compose up` completed successfully | +| **Chain ID Mismatch** | Tests fail with wrong chain ID | Check `.env` has `CHAIN_ID_GATEWAY=54321`; verify `RPC_URL` points to correct port | +| **Faucet Failure** | `account sequence mismatch` | Retry logic handles automatically; restart Docker if persistent | +| **Test Timeout** | Exceeded 300000ms | Normal for complex FHE operations; increase timeout in `hardhat.config.ts` if needed | +| **Relayer Connection** | Failed to connect to relayer | Verify `RELAYER_URL` in `.env`; check gateway services running via `docker compose ps` | + +**Debugging Commands**: +```bash +# View service logs +docker compose logs deploy-gateway-contracts + +# Inspect shared volume +docker volume inspect fhevm_addresses-volume + +# Verify chain ID +curl http://localhost:8545 -X POST \ + -H "Content-Type: application/json" \ + --data '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' +``` + +**Pro Tips**: Use `-g "pattern"` to isolate failing tests. Check `test-suite/e2e/test/instance.ts` for required environment variables. Test times of 30+ seconds are normal for FHE operations. + +**[TODO: CI/CD pipeline]** - Explain the GitHub Actions workflows, testing strategy, and release process. + +--- + +**Related:** +- [Component Health](../component-health.md) - Infrastructure components have minimal activity +- [Technology Stack](../reference/tech-stack.md) - Tools and frameworks used diff --git a/docs/codebase/src/components/kms-connector.md b/docs/codebase/src/components/kms-connector.md new file mode 100644 index 0000000000..1f5959fb4b --- /dev/null +++ b/docs/codebase/src/components/kms-connector.md @@ -0,0 +1,418 @@ +# KMS Connector 🔥 + +**Location**: `/kms-connector/` +**Status**: Active Development +**Purpose**: Interface between the Gateway and Key Management System (KMS Core) + +## Overview + +The KMS Connector bridges the Gateway contracts with the external KMS Core service that manages encryption keys using multi-party computation (MPC). This ensures no single party ever holds the complete decryption key. + +## Key Crates + +| Crate | Purpose | +|-------|---------| +| `gw-listener` | Monitors Gateway for key-related events | +| `kms-worker` | Forwards requests to KMS Core service | +| `transaction-sender` | Submits signed responses back to Gateway | +| `utils` | Shared utilities and types | + +## Supported Key Operations + +- **Key generation** - Initial setup of encryption keys +- **Preprocessing keygen** - Pre-generated key material for faster operations +- **Key reshare (rotation)** - Distribute key shares to new node set +- **CRS generation** - Common Reference String for cryptographic protocols +- **Decryption signing** - Threshold signatures for decryption results + +## Architecture + +``` +Gateway Events → gw-listener → kms-worker → KMS Core (external) + ↓ +Gateway Contracts ← transaction-sender ← Signed Response +``` + +**Flow:** +1. Gateway emits key operation event (e.g., DecryptionRequest) +2. `gw-listener` detects event and creates job +3. `kms-worker` forwards request to external KMS Core +4. KMS Core performs MPC protocol across threshold nodes +5. KMS Core returns EIP712-signed response +6. `transaction-sender` submits signed result to Gateway contract + +## Key Files + +- `gw-listener/src/main.rs` - Event listener entry point +- `kms-worker/src/main.rs` - KMS request handler +- `Cargo.toml` - Workspace dependencies + +## Relationships + +KMS Connector listens to `KMSGeneration` and `Decryption` events from Gateway contracts. It forwards requests to the external KMS Core (not in this repo) and submits EIP712-signed responses back to the chain. + +## Recent Development Focus (Dec 2025) + +### Garbage Collection +Implementation of automatic cleanup for stale database entries: +- `spawn_garbage_collection_routine()` runs periodically in transaction-sender +- Deletes `completed` and `failed` requests/responses after configurable expiry +- Unlocks items stuck in `under_process` state beyond timeout +- Uses PostgreSQL `updated_at` timestamps for staleness detection + +### Database Status Management +Migration from boolean `under_process` to proper status enum: +```sql +CREATE TYPE operation_status AS ENUM ('pending', 'under_process', 'completed', 'failed'); +``` +- Enables precise tracking of request lifecycle +- Triggers auto-update `updated_at` on status changes +- Auto-completes requests when responses are inserted + +### Nonce Manager +`NonceManagedProvider` for reliable transaction submission: +- Wraps Alloy provider with internal nonce tracking +- Recovers nonce state on transaction failure +- Ensures sequential nonce assignment for ordered delivery +- Prevents nonce gaps that would stall the queue + +### Polling Improvements +Hybrid notification + polling architecture: +- Primary: PostgreSQL LISTEN/NOTIFY for real-time events +- Fallback: Configurable polling interval when no notifications received +- Ensures catch-up after downtime without manual intervention +- Independent tickers per event/response type + +### Configuration Updates +- WebSocket to HTTP migration for Gateway RPC connections +- Environment variable support with TOML override precedence +- Flexible wallet configuration (private key or AWS KMS) + +## KMS Integration Flow + +The KMS Connector orchestrates the complete flow from decryption request to signed response delivery. The system is designed to handle thousands of decryptions per second while ensuring no events are ever missed. + +### Decryption Request Lifecycle + +```mermaid +sequenceDiagram + participant Contract + participant Gateway + participant GwListener + participant PostgreSQL + participant KmsWorker + participant S3 + participant KmsCore + participant TxSender + + Contract->>Gateway: requestDecryption(handle, callback) + Gateway-->>GwListener: emit DecryptionRequested event + GwListener->>PostgreSQL: INSERT request (status=pending) + PostgreSQL-->>KmsWorker: NOTIFY decryption_available + KmsWorker->>PostgreSQL: UPDATE status=under_process + KmsWorker->>S3: Retrieve ciphertext material + S3-->>KmsWorker: Ciphertext data + KmsWorker->>KmsCore: gRPC PublicDecryptionRequest + KmsCore-->>KmsWorker: PublicDecryptionResponse (EIP712-signed) + KmsWorker->>PostgreSQL: INSERT response (status=pending) + PostgreSQL-->>TxSender: NOTIFY response_available + TxSender->>Gateway: publicDecryptionResponse(id, result, sig) + Gateway->>Contract: callback(plaintext) +``` + +### Component Responsibilities + +**gw-listener** (`/kms-connector/crates/gw-listener/`) +- Monitors multiple Gateway RPC nodes for redundancy +- Listens for 7 event types: `PublicDecryptionRequest`, `UserDecryptionRequest`, `PrepKeygenRequest`, `KeygenRequest`, `CrsgenRequest`, `PrssInit`, `KeyReshareSameSet` +- Stores events in PostgreSQL with `ON CONFLICT DO NOTHING` for duplicate handling +- Tracks `last_block_polled` per event type for catch-up after downtime +- Supports backup RPC node URLs per listener + +**kms-worker** (`/kms-connector/crates/kms-worker/`) +- Receives PostgreSQL NOTIFY when new events arrive +- Picks events atomically: `UPDATE...SET status='under_process' FOR UPDATE SKIP LOCKED` +- Retrieves ciphertext material from S3 buckets +- Sends gRPC requests to KMS Core (supports multiple shards) +- Stores signed responses in database, triggering auto-deletion of requests + +**transaction-sender** (`/kms-connector/crates/tx-sender/`) +- Single instance to ensure transaction ordering +- Picks responses via PostgreSQL notification +- Calls Gateway contract methods: `publicDecryptionResponse()`, `userDecryptionResponse()`, `prepKeygenResponse()`, `keygenResponse()`, `crsgenResponse()` +- Manages nonces with recovery on failure +- Retries with configurable attempts and intervals + +### Database Notification Flow + +The system uses PostgreSQL LISTEN/NOTIFY as the primary event mechanism with polling fallback: + +```sql +-- Trigger on request insertion +CREATE TRIGGER trigger_from_public_decryption_requests_insertions +AFTER INSERT ON public_decryption_requests +FOR EACH STATEMENT EXECUTE FUNCTION notify_public_decryption_request(); + +-- Notification function +CREATE FUNCTION notify_public_decryption_request() RETURNS trigger AS $$ +BEGIN + NOTIFY public_decryption_request_available; + RETURN NULL; +END; +$$ LANGUAGE plpgsql; +``` + +### Error Handling Patterns + +| Error Type | Action | Retry Behavior | +|------------|--------|----------------| +| **Recoverable** | Reset status to `pending` | Automatic retry on next notification/poll | +| **Irrecoverable** | Mark as `failed` | No retry; requires manual intervention | +| **Max attempts exceeded** | Mark as `failed` | Configurable limit (default: 3 for decryption) | +| **Connection lost** | Mark as `pending`, cancel token | Graceful shutdown, resume on restart | + +Key management operations (`PrepKeygen`, `Keygen`, `Crsgen`) have no retry limit - they must be manually cleaned up if stuck. + +--- + +## Threshold Signature Scheme + +The KMS implements MPC-based threshold cryptography where the secret FHE key is split across multiple independent parties. This ensures no single party can decrypt data alone. + +### MPC Security Model + +**Threshold Configuration**: t-of-n (e.g., 9-of-13 nodes) +- At least `t` parties must participate to perform any operation +- Adversary must compromise more than `t` nodes to break security +- System remains operational if up to `n-t` nodes are offline + +**Security Properties**: + +| Property | Description | +|----------|-------------| +| **Statistically Robust** | Security doesn't depend on computational assumptions; cannot be broken regardless of adversary's compute power | +| **Maliciously Robust** | Protocol completes correctly even with up to `t` parties running rogue software or not participating | +| **Proactive Security** | Key shares can be refreshed to "undo" leakage; stolen material becomes useless after refresh | + +### Trust Model + +- **Honest majority assumption**: Protocol tolerates up to 1/3 malicious nodes +- **Guaranteed output delivery**: Decryption completes even with some misbehaving nodes +- **No single point of trust**: No individual party ever sees the complete key +- **Byzantine fault tolerance**: Resilient against arbitrary node failures + +### Secure Execution Environment + +Each KMS node runs inside an **AWS Nitro Enclave**: +- Isolated execution environment with attestation +- Prevents node operators from accessing their own key shares +- Mitigates insider risks (unauthorized reconstruction, share selling) +- Key material loaded into RAM on boot, never exposed externally + +### Decryption Protocol + +1. Gateway broadcasts decryption request to all KMS nodes +2. Each node performs partial decryption using its key share +3. At least `t` partial results are combined to recover plaintext +4. Each node signs the result; threshold signature is generated +5. Signed result posted back to Gateway for on-chain verification + +--- + +## Key Lifecycle Management + +The KMS supports the complete key lifecycle following NIST SP 800-57 guidelines, from generation through destruction. + +### Key Operation Types + +| Operation | Purpose | Response Expected | +|-----------|---------|-------------------| +| `PrepKeygen` | Preprocessing for faster key generation | Signature only | +| `Keygen` | Full key generation (links to PrepKeygen) | Key digests + signature | +| `Crsgen` | Common Reference String generation | CRS digest + signature | +| `PrssInit` | PRSS (Pseudo-Random Secret Sharing) initialization | None | +| `KeyReshareSameSet` | Redistribute shares without changing key | None | + +### Key Generation Flow + +```mermaid +sequenceDiagram + participant Admin + participant Gateway + participant KmsConnector + participant KmsCore + + Note over Admin,KmsCore: Phase 1: Preprocessing + Admin->>Gateway: prepkeygen(paramsType, epochId) + Gateway-->>KmsConnector: PrepKeygenRequest event + KmsConnector->>KmsCore: KeyGenPreprocRequest + KmsCore-->>KmsConnector: PrepKeygenResponse (signature) + KmsConnector->>Gateway: prepKeygenResponse(prepKeygenId, sig) + + Note over Admin,KmsCore: Phase 2: Key Generation + Admin->>Gateway: keygen(prepKeygenId) + Gateway-->>KmsConnector: KeygenRequest event + KmsConnector->>KmsCore: KeyGenRequest + KmsCore-->>KmsConnector: KeygenResponse (digests, signature) + KmsConnector->>Gateway: keygenResponse(keyId, digests, sig) +``` + +### NIST SP 800-57 Lifecycle States + +| State | Description | Operations Allowed | +|-------|-------------|-------------------| +| **Pre-activation** | Key created but not yet in use | None | +| **Active** | Key in full operational use | Encryption + Decryption | +| **Suspended** | Temporarily replaced during rotation | Decryption only | +| **Deactivated** | Archived, no longer active | Decryption only | +| **Compromised** | Flagged for potential misuse | Decryption only | +| **Destroyed** | Key material permanently deleted | None | + +### Preprocessing Benefits + +Separating preprocessing from key generation provides: +- **Faster operations**: Expensive setup done in advance during low-load periods +- **Emergency rotation**: Rapid key generation when preprocessing already complete +- **Resource efficiency**: Preprocessing can be batched and scheduled + +### Key Reshare/Rotation + +`KeyReshareSameSet` enables validator set rotation without changing the underlying key: +- Redistributes key shares to new set of operators +- Links to new `PrepKeygenId` for fresh preprocessing +- Fire-and-forget operation (no response expected) +- Used during planned validator rotations + +### Garbage Collection + +Recent implementation cleans up stale data: + +```rust +// Configurable routine spawned at startup +spawn_garbage_collection_routine( + period: Duration, // How often to run + decryption_expiry: Interval, // When to delete completed/failed + under_process_limit: Interval, // When to unlock stuck items + db_pool: Pool, + cancel_token: CancellationToken, +) +``` + +**Operations performed**: +- Delete completed/failed requests older than `decryption_expiry` +- Delete completed/failed responses older than `decryption_expiry` +- Unlock items stuck in `under_process` longer than `under_process_limit` + +--- + +## EIP712 Signing Format + +All KMS responses are signed using EIP712 structured data, enabling on-chain verification. + +### Domain Structure + +```rust +struct Eip712Domain { + name: String, // Contract domain name (from config) + version: String, // Default: "1" + chain_id: U256, // BE-encoded chain ID + verifying_contract: Address, // Gateway contract address + salt: Option<[u8; 32]>, // Optional salt value +} +``` + +**Validation**: Domain names are checked for control characters and non-ASCII characters during config parsing to ensure EIP712 encoding compatibility. + +### Signed Response Types + +| Response Type | Signed Fields | +|---------------|---------------| +| `PublicDecryptionResponse` | `decryption_id`, `decrypted_result`, `extra_data` | +| `UserDecryptionResponse` | `decryption_id`, `user_decrypted_shares`, `user_address`, `public_key` | +| `PrepKeygenResponse` | `prep_keygen_id` | +| `KeygenResponse` | `key_id`, `key_digests[]` (type + digest pairs) | +| `CrsgenResponse` | `crs_id`, `crs_digest` | + +### On-Chain Verification + +The `KMSVerifier` contract on the host chain: +1. Receives signed response from transaction-sender +2. Recovers signer addresses from EIP712 signature +3. Validates signers are registered KMS nodes +4. Confirms threshold number of valid signatures +5. Approves callback delivery to requesting contract + +--- + +## External KMS Core Integration + +The KMS Connector communicates with the external KMS Core service via gRPC. The KMS Core is not part of this repository. + +### gRPC API Contract + +**Request Types**: +```protobuf +// Decryption operations +rpc PublicDecryption(PublicDecryptionRequest) returns (PublicDecryptionResponse) +rpc UserDecryption(UserDecryptionRequest) returns (UserDecryptionResponse) + +// Key management operations +rpc PrepKeygen(KeyGenPreprocRequest) returns (PrepKeygenResponse) +rpc Keygen(KeyGenRequest) returns (KeygenResponse) +rpc Crsgen(CrsGenRequest) returns (CrsgenResponse) + +// Fire-and-forget operations (no response) +rpc PrssInit(InitRequest) returns (Empty) +rpc KeyReshareSameSet(InitiateResharingRequest) returns (Empty) +``` + +### Connection Handling + +```rust +pub struct KmsClient { + inners: Vec>, // Multiple shards + grpc_request_retries: u8, +} +``` + +**Features**: +- Multiple shard support with independent connections +- Configurable retry delays and attempts +- Backup endpoint support per shard +- Automatic reconnection on connection loss + +### Deployment Patterns + +| Pattern | Description | Use Case | +|---------|-------------|----------| +| **Centralized** | Single KMS Core with full key material | Development, testing | +| **Threshold** | N distributed parties with secret-shared keys | Production | + +**Threshold deployment**: +- 13 MPC nodes operated by different organizations (typical) +- Each node in AWS Nitro Enclave +- Communication secured via mTLS with gRPC +- Key shares split using threshold secret sharing + +### Performance Characteristics + +- **Target throughput**: Thousands of decryptions per second +- **Batch processing**: 64 events for decryption, 1 for key management +- **Notification-first**: Real-time via PostgreSQL NOTIFY +- **Polling fallback**: Catches missed events after downtime +- **Concurrent processing**: Configurable task limits per worker + +### Operational Considerations + +**Ciphertext retrieval**: Ciphertexts stored in S3-compatible storage; URLs provided in Gateway events with fallback to configured defaults. + +**Wallet configuration**: Transaction-sender requires wallet for signing: +- Private key (development only) +- AWS KMS wallet (production) + +--- + +**Related:** +- [Gateway Contracts](gateway-contracts.md) - Emits events that trigger KMS operations +- [Key Concepts](../key-concepts.md) - Understanding the role of KMS in FHEVM +- [Workflows: Decryption Pipeline](../workflows/decryption-pipeline.md) - How KMS fits in decryption flow diff --git a/docs/codebase/src/components/library-solidity.md b/docs/codebase/src/components/library-solidity.md new file mode 100644 index 0000000000..2e2a0d09b9 --- /dev/null +++ b/docs/codebase/src/components/library-solidity.md @@ -0,0 +1,534 @@ +# Solidity Library ✅ + +**Location**: `/library-solidity/` +**Status**: Stable +**Purpose**: Developer-facing FHE primitives for writing confidential smart contracts + +## Overview + +The Solidity library provides the API that smart contract developers use to work with encrypted types. It abstracts away the complexity of FHE operations behind familiar Solidity syntax. + +## Key Components + +| File | Purpose | +|------|---------| +| `lib/FHE.sol` | Main developer API - import this to use FHE | +| `lib/Impl.sol` | Implementation details, delegates to precompiles | +| `lib/FheType.sol` | Encrypted type enum definitions | + +## Encrypted Types + +**Boolean:** +- `ebool` - Encrypted boolean + +**Unsigned Integers:** +- `euint4`, `euint8`, `euint16`, `euint32`, `euint64`, `euint128`, `euint256` - Up to `euint2048` + +**Signed Integers:** +- `eint8`, `eint16`, `eint32`, `eint64`, `eint128`, `eint256` + +**Special Types:** +- `eaddress` - Encrypted Ethereum address +- `AsciiString` - Encrypted ASCII string + +## Example Usage + +```solidity +import {FHE, euint64} from "fhevm/lib/FHE.sol"; + +contract ConfidentialToken { + mapping(address => euint64) private balances; + + function transfer(address to, euint64 amount) external { + balances[msg.sender] = FHE.sub(balances[msg.sender], amount); + balances[to] = FHE.add(balances[to], amount); + } +} +``` + +## Core Operations + +All standard operations are supported on encrypted types: + +**Arithmetic:** `add`, `sub`, `mul`, `div`, `rem`, `min`, `max` +**Comparison:** `eq`, `ne`, `lt`, `le`, `gt`, `ge` +**Bitwise:** `and`, `or`, `xor`, `not`, `shl`, `shr` +**Control Flow:** `select` (ternary: `condition ? a : b`) + +## Type System Design + +Each encrypted type: +- Is a distinct Solidity type (strong typing) +- Internally stores a `bytes32` handle +- Operations return new encrypted values +- Cannot be implicitly converted to plaintext + +## Key Files + +- `lib/FHE.sol` - Primary import for developers +- `examples/EncryptedERC20.sol` - Reference implementation +- `codegen/` - Code generation for operator overloads + +## Encrypted Type System + +The library supports 88 encrypted types organized into categories. Each encrypted type internally stores a `bytes32` handle that references the actual ciphertext managed by the coprocessor. + +### Type Categories + +#### Boolean +| Type | Bit Size | FheType Enum | Clear Equivalent | +|------|----------|--------------|------------------| +| `ebool` | 2-bit | `Bool` (0) | `bool` | + +#### Standard Unsigned Integers +| Type | Bit Size | FheType Enum | Clear Equivalent | +|------|----------|--------------|------------------| +| `euint8` | 8-bit | `Uint8` (2) | `uint8` | +| `euint16` | 16-bit | `Uint16` (3) | `uint16` | +| `euint32` | 32-bit | `Uint32` (4) | `uint32` | +| `euint64` | 64-bit | `Uint64` (5) | `uint64` | +| `euint128` | 128-bit | `Uint128` (6) | `uint128` | +| `euint256` | 256-bit | `Uint256` (8) | `uint256` | + +#### Extended Unsigned Integers +| Type | Bit Size | FheType Enum | Clear Equivalent | +|------|----------|--------------|------------------| +| `euint2` | 2-bit | `Uint2` (12) | `uint8` | +| `euint4` | 4-bit | `Uint4` (1) | `uint8` | +| `euint6` | 6-bit | `Uint6` (13) | `uint8` | +| `euint10` | 10-bit | `Uint10` (14) | `uint16` | +| `euint12` | 12-bit | `Uint12` (15) | `uint16` | +| `euint14` | 14-bit | `Uint14` (16) | `uint16` | +| `euint24` | 24-bit | `Uint24` (34) | `uint32` | +| `euint40`-`euint248` | 40-248 bit | Various | Various | +| `euint512` | 512-bit | `Uint512` (9) | `bytes memory` | +| `euint1024` | 1024-bit | `Uint1024` (10) | `bytes memory` | +| `euint2048` | 2048-bit | `Uint2048` (11) | `bytes memory` | + +#### Standard Signed Integers +| Type | Bit Size | FheType Enum | Clear Equivalent | +|------|----------|--------------|------------------| +| `eint8` | 8-bit | `Int8` (20) | `int8` | +| `eint16` | 16-bit | `Int16` (24) | `int16` | +| `eint32` | 32-bit | `Int32` (25) | `int32` | +| `eint64` | 64-bit | `Int64` (26) | `int64` | +| `eint128` | 128-bit | `Int128` (27) | `int128` | +| `eint256` | 256-bit | `Int256` (29) | `int256` | + +Extended signed integers (`eint2`-`eint2048`) follow the same pattern. + +#### Special Types +| Type | Bit Size | FheType Enum | Clear Equivalent | +|------|----------|--------------|------------------| +| `eaddress` | 160-bit | `Uint160` (7) | `address` | +| `AsciiString` | variable | `AsciiString` (30) | `string` | + +#### External Input Types +For accepting encrypted inputs from users with proof verification: +- `externalEbool`, `externalEuint8`, `externalEuint16`, `externalEuint32` +- `externalEuint64`, `externalEuint128`, `externalEaddress`, `externalEuint256` + +### Type Conversion Rules + +**Converting plaintext to encrypted:** +```solidity +ebool b = FHE.asEbool(true); +euint64 amount = FHE.asEuint64(1000); +eaddress addr = FHE.asEaddress(msg.sender); +``` + +**Casting between encrypted types (widening):** +```solidity +euint8 small = FHE.asEuint8(42); +euint64 large = FHE.asEuint64(small); // Safe: widening conversion +``` + +**Casting between encrypted types (narrowing):** +```solidity +euint64 large = FHE.asEuint64(1000); +euint8 small = FHE.asEuint8(large); // Truncates to lower 8 bits +``` + +**Converting external inputs:** +```solidity +function deposit(externalEuint64 encAmount, bytes calldata proof) external { + euint64 amount = FHE.fromExternal(encAmount, proof); + // Now 'amount' is verified and usable +} +``` + +### Memory and Gas Implications + +- **Internal representation**: All encrypted types store a `bytes32` handle +- **Gas costs**: Operations on larger types consume more gas +- **Storage**: Only the handle is stored on-chain; ciphertexts live in the coprocessor +- **Type efficiency**: Use the smallest type that fits your data (e.g., `euint8` for percentages) + +### Type Safety Guarantees + +1. **Strong typing**: Cannot implicitly convert between encrypted types +2. **Opaque handles**: Cannot directly access or manipulate the underlying ciphertext +3. **ACL enforcement**: Operations fail if caller lacks permission on the encrypted value +4. **Initialization checks**: Use `FHE.isInitialized(value)` to check if a value has been set + +--- + +## Codegen System + +The library uses a TypeScript-based code generation system to produce Solidity operator overloads for all type combinations. + +### Directory Structure + +``` +codegen/ +├── codegen.mjs # CLI entry point (commander.js) +├── package.json # npm configuration +├── src/ +│ ├── main.ts # Command handlers +│ ├── operators.ts # 21 operator definitions +│ ├── fheTypeInfos.ts # 84+ FHE type definitions +│ ├── templateFHEDotSol.ts # FHE.sol code generator +│ ├── templateImpDotSol.ts # Impl.sol code generator +│ ├── templateFheTypeDotSol.ts # FheType.sol generator +│ ├── operatorsPrices.ts # Gas cost definitions +│ └── templates/ # Solidity template files +│ ├── FHE.sol-template +│ ├── Impl.sol-template +│ └── FheType.sol-template +└── overloads/ # Generated test data (JSON) + ├── library-solidity.json + ├── host-contracts.json + └── e2e.json +``` + +### How Operator Overloads Are Generated + +**1. Template System**: Templates use `$${PLACEHOLDER}$$` markers that get replaced with generated code. + +**2. Operator Definitions** (`operators.ts`): Each of the 21 operators specifies: +```typescript +{ + name: 'add', + hasScalar: true, // Supports plaintext operands + hasEncrypted: true, // Supports encrypted operands + arguments: OperatorArguments.Binary, + returnType: ReturnType.Euint, + fheLibName: 'fheAdd' // Coprocessor function name +} +``` + +**3. Type Definitions** (`fheTypeInfos.ts`): Each type specifies supported operators and bit lengths. + +**4. Code Generation**: The generator produces all valid combinations: +- `FHE.add(euint8, euint8)` → `euint8` +- `FHE.add(euint8, uint8)` → `euint8` (scalar) +- `FHE.add(uint8, euint8)` → `euint8` (scalar, left) + +### Supported Operators + +| Category | Operators | Notes | +|----------|-----------|-------| +| Arithmetic | `add`, `sub`, `mul`, `div`, `rem` | `div`/`rem` only support scalar divisor | +| Bitwise | `and`, `or`, `xor`, `not` | Work on all integer types | +| Shift/Rotate | `shl`, `shr`, `rotl`, `rotr` | Shift amount can be scalar or encrypted | +| Comparison | `eq`, `ne`, `ge`, `gt`, `le`, `lt` | Return `ebool` | +| Min/Max | `min`, `max` | Return same type as inputs | +| Unary | `neg`, `not` | Single operand | + +### Build Process + +```bash +# Generate all library files (FHE.sol, Impl.sol, FheType.sol) +npm run codegen + +# Regenerate test data with new random values +npm run codegen:overloads +``` + +### Extending the Library + +**Adding a new operator:** +1. Add operator definition to `codegen/src/operators.ts` +2. Add template handler in `templateFHEDotSol.ts` +3. Run `npm run codegen` to regenerate + +**Adding a new type:** +1. Add type definition to `codegen/src/fheTypeInfos.ts` with: + - `type`: Name (e.g., `'Uint40'`) + - `bitLength`: Size in bits + - `supportedOperators`: List of allowed operators + - `clearMatchingType`: Corresponding Solidity type +2. Run `npm run codegen` to regenerate + +--- + +## Best Practices + +### Contract Setup Pattern + +Always initialize the coprocessor in your constructor: + +```solidity +import {FHE} from "fhevm/lib/FHE.sol"; +import {CoprocessorSetup} from "fhevm/examples/CoprocessorSetup.sol"; + +contract MyContract { + constructor() { + FHE.setCoprocessor(CoprocessorSetup.defaultConfig()); + } +} +``` + +### Access Control Pattern + +After any operation that creates or modifies an encrypted value, grant appropriate permissions: + +```solidity +function updateBalance(address user, euint64 newBalance) internal { + balances[user] = newBalance; + + // Allow this contract to use the value in future operations + FHE.allowThis(newBalance); + + // Allow the user to access their own balance + FHE.allow(newBalance, user); +} +``` + +For cross-contract calls, use transient permissions: + +```solidity +function transferToOtherContract(address target, euint64 amount) external { + FHE.allowTransient(amount, target); + IOtherContract(target).receive(amount); +} +``` + +### Common Pitfalls + +**1. Forgetting coprocessor setup:** +```solidity +// BAD: Operations will fail +contract Broken { + function doSomething() external { + euint64 a = FHE.asEuint64(100); // Fails! + } +} + +// GOOD: Initialize in constructor +contract Working { + constructor() { + FHE.setCoprocessor(CoprocessorSetup.defaultConfig()); + } +} +``` + +**2. Missing ACL permissions:** +```solidity +// BAD: Recipient can't use their balance +function transfer(address to, euint64 amount) external { + balances[to] = FHE.add(balances[to], amount); + // Missing: FHE.allow(balances[to], to); +} + +// GOOD: Grant permissions after modification +function transfer(address to, euint64 amount) external { + balances[to] = FHE.add(balances[to], amount); + FHE.allowThis(balances[to]); + FHE.allow(balances[to], to); +} +``` + +**3. Branching on encrypted conditions:** +```solidity +// BAD: Reveals whether condition is true! +if (FHE.decrypt(condition)) { + doA(); +} else { + doB(); +} + +// GOOD: Use select to maintain confidentiality +euint64 result = FHE.select(condition, valueIfTrue, valueIfFalse); +``` + +**4. Using uninitialized values:** +```solidity +// BAD: Comparing uninitialized values gives undefined behavior +ebool winner = FHE.gt(bids[alice], bids[bob]); + +// GOOD: Check initialization first +require(FHE.isInitialized(bids[alice]), "Alice hasn't bid"); +require(FHE.isInitialized(bids[bob]), "Bob hasn't bid"); +ebool winner = FHE.gt(bids[alice], bids[bob]); +``` + +### Performance Optimization + +1. **Choose appropriate types**: Use `euint8` for small values, not `euint256` +2. **Batch operations**: Combine multiple operations where possible +3. **Minimize encrypted ops**: Do plaintext computation when privacy isn't needed +4. **Avoid redundant permissions**: Don't call `FHE.allow()` if permission already exists + +### Testing Encrypted Contracts + +1. **Use mock mode** for faster development iteration +2. **Test boundary conditions** (zero, max values, overflow scenarios) +3. **Verify ACL permissions** are correctly set in all code paths +4. **Test with multiple accounts** to ensure cross-account permissions work + +--- + +## Examples Deep-Dive + +### EncryptedERC20.sol Walkthrough + +The `EncryptedERC20` contract demonstrates a complete confidential token implementation. + +**State Variables:** +```solidity +mapping(address => euint64) internal balances; // Encrypted balances +mapping(address => mapping(address => euint64)) internal allowances; // Encrypted allowances +``` + +**Constructor - Coprocessor Setup:** +```solidity +constructor(string memory name_, string memory symbol_) Ownable(msg.sender) { + FHE.setCoprocessor(CoprocessorSetup.defaultConfig()); + _name = name_; + _symbol = symbol_; +} +``` + +**Minting - Adding Plaintext to Encrypted:** +```solidity +function mint(uint64 mintedAmount) public virtual onlyOwner { + // Add plaintext amount to encrypted balance (auto-encrypts the scalar) + balances[owner()] = FHE.add(balances[owner()], mintedAmount); + + // Grant permissions for the new balance + FHE.allowThis(balances[owner()]); + FHE.allow(balances[owner()], owner()); + + _totalSupply = _totalSupply + mintedAmount; +} +``` + +**Transfer with External Input:** +```solidity +function transfer( + address to, + externalEuint64 encryptedAmount, // User-provided encrypted amount + bytes calldata inputProof // Proof of valid encryption +) public virtual returns (bool) { + // Verify and convert external input to internal encrypted value + transfer(to, FHE.fromExternal(encryptedAmount, inputProof)); + return true; +} +``` + +**Internal Transfer - Conditional Logic:** +```solidity +function _transfer(address from, address to, euint64 amount, ebool isTransferable) internal { + // Select: if transferable, use amount; else use 0 + euint64 transferValue = FHE.select(isTransferable, amount, FHE.asEuint64(0)); + + // Update recipient balance + euint64 newBalanceTo = FHE.add(balances[to], transferValue); + balances[to] = newBalanceTo; + FHE.allowThis(newBalanceTo); + FHE.allow(newBalanceTo, to); + + // Update sender balance + euint64 newBalanceFrom = FHE.sub(balances[from], transferValue); + balances[from] = newBalanceFrom; + FHE.allowThis(newBalanceFrom); + FHE.allow(newBalanceFrom, from); +} +``` + +**Allowance Update - Combining Conditions:** +```solidity +function _updateAllowance(address owner, address spender, euint64 amount) internal returns (ebool) { + euint64 currentAllowance = _allowance(owner, spender); + + // Check 1: Is amount <= allowance? + ebool allowedTransfer = FHE.le(amount, currentAllowance); + + // Check 2: Does owner have enough balance? + ebool canTransfer = FHE.le(amount, balances[owner]); + + // Combine conditions with AND + ebool isTransferable = FHE.and(canTransfer, allowedTransfer); + + // Conditionally update allowance: subtract if transferable, keep same if not + _approve(owner, spender, + FHE.select(isTransferable, FHE.sub(currentAllowance, amount), currentAllowance)); + + return isTransferable; +} +``` + +### HeadsOrTails.sol - Random Number Generation + +Demonstrates encrypted randomness and public decryption: + +```solidity +function headsOrTails(address headsPlayer, address tailsPlayer) external { + // Generate encrypted random boolean (true = heads, false = tails) + ebool headsOrTailsResult = FHE.randEbool(); + + // Store in game state + games[gameId] = Game({ + headsPlayer: headsPlayer, + tailsPlayer: tailsPlayer, + encryptedHasHeadWon: headsOrTailsResult, + winner: address(0) + }); + + // Make result publicly decryptable (instead of oracle workflow) + FHE.makePubliclyDecryptable(headsOrTailsResult); +} +``` + +Verifying decryption with proof: + +```solidity +function checkWinner(uint256 gameId, bytes memory clearGameResult, bytes memory decryptionProof) public { + // Decode the decrypted result + bool decodedClearGameResult = abi.decode(clearGameResult, (bool)); + address winner = decodedClearGameResult ? games[gameId].headsPlayer : games[gameId].tailsPlayer; + + // Verify the proof + bytes32[] memory cts = new bytes32[](1); + cts[0] = FHE.toBytes32(games[gameId].encryptedHasHeadWon); + FHE.checkSignatures(cts, clearGameResult, decryptionProof); + + games[gameId].winner = winner; +} +``` + +### Key Patterns Summary + +| Pattern | Example | Use Case | +|---------|---------|----------| +| Encrypted state | `mapping(address => euint64) balances` | Store confidential per-user data | +| External input | `FHE.fromExternal(encAmount, proof)` | Accept user-provided encrypted values | +| Conditional select | `FHE.select(cond, a, b)` | Branch without revealing condition | +| Combined conditions | `FHE.and(cond1, cond2)` | Multiple checks without branching | +| Permission grant | `FHE.allow(value, addr)` | Enable address to use encrypted value | +| Random generation | `FHE.randEuint64()` | On-chain encrypted randomness | +| Public decrypt | `FHE.makePubliclyDecryptable(v)` | Reveal result without oracle | + +### Additional Example References + +- **Rand.sol**: Bounded random number generation with `FHE.randEuint8(upperBound)` +- **MakePubliclyDecryptable.sol**: Public decryption workflow patterns +- **BlindAuction** (in docs/examples): Complete sealed-bid auction with encrypted bid comparison + +--- + +**Related:** +- [Host Contracts](host-contracts.md) - Underlying symbolic execution engine +- [Key Concepts](../key-concepts.md) - Understanding handles and symbolic execution +- [Workflows: Input Verification](../workflows/input-verification.md) - How users submit encrypted inputs diff --git a/docs/codebase/src/components/protocol-contracts.md b/docs/codebase/src/components/protocol-contracts.md new file mode 100644 index 0000000000..5ce147177b --- /dev/null +++ b/docs/codebase/src/components/protocol-contracts.md @@ -0,0 +1,623 @@ +# Protocol Contracts 🔥 + +**Location**: `/protocol-contracts/` +**Status**: Active Development +**Purpose**: Protocol-level infrastructure including token, staking, and governance + +## Overview + +Protocol contracts implement the economic and governance layer of the FHEVM ecosystem. They are organized into domain-specific subdirectories. + +## Submodules + +| Directory | Purpose | +|-----------|---------| +| `token/` | ZAMA ERC20 token and OFT (Omnichain Fungible Token) for cross-chain | +| `staking/` | Node operator staking mechanisms | +| `governance/` | DAO voting and protocol governance | +| `confidential-wrapper/` | Wraps public tokens for confidential transfers | +| `feesBurner/` | Fee collection and token burning | +| `safe/` | Safe module for protocol administration | + +## Key Contracts + +**Token Layer:** +- `token/ZamaERC20.sol` - Protocol token implementation +- `token/ZamaOFT.sol` - Omnichain token (LayerZero integration) + +**Economic Layer:** +- `staking/OperatorStaking.sol` - Operator staking and slashing +- `staking/OperatorRewarder.sol` - Reward distribution mechanisms +- `confidential-wrapper/Wrapper.sol` - Public-to-confidential token bridge +- `feesBurner/ProtocolFeesBurner.sol` - Fee collection and burning + +**Governance Layer:** +- `governance/GovernanceOAppSender.sol` - Cross-chain proposal transmission +- `governance/GovernanceOAppReceiver.sol` - Proposal execution on Gateway +- `safe/AdminModule.sol` - Safe module for admin operations + +## Recent Development Focus (Dec 2025) + +- **Staking/delegation**: `OperatorStaking` and `OperatorRewarder` implementation +- **Fee management**: Burner implementation and distribution logic +- **Governance**: Safe ownership and admin modules +- **ERC1363 integration**: Callback-based token transfers +- **UUPS upgradeability**: Proxy patterns for contract upgrades + +## Deprecation Notice + +> ⚠️ **Note**: `ProtocolOperatorRegistry` has been removed. Use `OperatorStaking` for staking functionality. + +--- + +## Staking/Delegation Contracts + +The staking system implements a three-tier architecture that enables users to delegate stake to operators while earning rewards. This design separates protocol-level staking from operator-specific delegation and reward distribution. + +### Architecture + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ User Deposit Flow │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ OperatorStaking │ +│ - Receives user deposits │ +│ - Mints shares to delegators │ +│ - Manages redemption requests │ +│ - Tracks operator authorization │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ ProtocolStaking │ +│ - Core staking with cooldown │ +│ - sqrt-weighted rewards │ +│ - Eligibility management │ +│ - Slashing execution │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ OperatorRewarder │ +│ - Claims rewards from ProtocolStaking │ +│ - Distributes to delegators │ +│ - Applies operator fee │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### Key Contracts + +| Contract | File | Purpose | +|----------|------|---------| +| `ProtocolStaking` | `staking/contracts/ProtocolStaking.sol` | Core staking with sqrt-weighted rewards and cooldown | +| `OperatorStaking` | `staking/contracts/OperatorStaking.sol` | Liquid staking derivative for operator delegation | +| `OperatorRewarder` | `staking/contracts/OperatorRewarder.sol` | Reward distribution with operator fee | + +### Deposit Flow + +1. **User deposits ZAMA tokens** to `OperatorStaking.deposit()` +2. **OperatorStaking stakes** into `ProtocolStaking` on behalf of delegators +3. **Shares are minted** to the user (1:1 initially, then based on exchange rate) +4. **Rewarder hook** is triggered to track reward allocations + +```solidity +// User deposits 100 ZAMA to operator +operatorStaking.deposit(100e18, userAddress); + +// Or with ERC1363 callback +zamaToken.transferAndCall(operatorStaking, 100e18, userData); +``` + +### Redemption Flow + +Redemption uses a two-phase process with cooldown: + +1. **Request redemption**: `requestRedeem()` burns shares and initiates unstaking +2. **Wait for cooldown**: Subject to `ProtocolStaking` unstaking period +3. **Claim assets**: `redeem()` transfers underlying tokens after cooldown + +```solidity +// Phase 1: Request (burns shares, starts cooldown) +operatorStaking.requestRedeem(100e18, controller, owner); + +// Phase 2: Redeem (after cooldown expires) +operatorStaking.redeem(100e18, receiver, controller); +``` + +### Reward Mechanics + +**ProtocolStaking** uses square-root weighting for rewards: + +``` +weight = sqrt(stakedAmount) +allocation = historicalReward × (weight / totalWeight) +``` + +This design: +- Provides diminishing returns on large stakes +- Encourages network decentralization +- Reduces incentive for stake consolidation + +**OperatorRewarder** distributes rewards to delegators minus an operator fee: + +```solidity +// Operator can claim fee percentage of rewards +uint256 fee = rewards * feeBasisPoints / 10000; +uint256 delegatorRewards = rewards - fee; +``` + +### Delegation Patterns + +**Operator Authorization:** +```solidity +// User authorizes operator to manage redemptions +operatorStaking.setOperator(operatorAddress, true); +``` + +**Reward Claimer Delegation:** +```solidity +// User authorizes another address to claim rewards +operatorRewarder.setClaimer(claimerAddress); +``` + +### Slashing + +Slashing occurs at the `ProtocolStaking` level and symmetrically affects all delegators: + +1. Protocol executes slash on `ProtocolStaking` +2. `totalAssets()` in `OperatorStaking` decreases +3. Share-to-asset exchange rate drops for all holders +4. Losses are proportionally distributed + +### ERC1363 Integration + +Both `OperatorStaking` and `ZamaERC20` support ERC1363 callbacks, enabling atomic deposit operations: + +```solidity +// Single transaction: approve + deposit +zamaToken.transferAndCall(operatorStaking, amount, ""); +``` + +--- + +## Confidential Wrapper Pattern + +The confidential wrapper bridges public ERC20 tokens to confidential tokens using FHE encryption. This enables privacy-preserving token transfers while maintaining 1-to-1 collateral backing. + +### Architecture + +``` +┌──────────────────┐ wrap() ┌──────────────────┐ +│ Public ERC20 │ ───────────────▶│ Wrapper │ +│ (e.g., USDC) │ │ Contract │ +└──────────────────┘ └────────┬─────────┘ + │ + │ mint() + ▼ + ┌──────────────────┐ + │ Confidential │ + │ ERC7984 Token │ + │ (encrypted) │ + └──────────────────┘ +``` + +### Key Contracts + +| Contract | File | Purpose | +|----------|------|---------| +| `Wrapper` | `confidential-wrapper/contracts/wrapper/Wrapper.sol` | Core wrap/unwrap logic | +| `WrapperUpgradeable` | `confidential-wrapper/contracts/wrapper/WrapperUpgradeable.sol` | UUPS upgradeable version | +| `RegulatedERC7984Upgradeable` | `confidential-wrapper/contracts/token/RegulatedERC7984Upgradeable.sol` | Confidential token with sanctions | +| `WrapperFactory` | `confidential-wrapper/contracts/factory/WrapperFactory.sol` | Deploys wrapper pairs | +| `FeeManager` | `confidential-wrapper/contracts/admin/FeeManager.sol` | Centralized fee configuration | + +### Wrap Flow (Public → Confidential) + +``` +User sends 100 USDC + │ + ▼ +┌───────────────────────────────────────┐ +│ 1. Calculate fees │ +│ baseFee = amount × feeBasisPoints │ +│ wrapDust = amount % rate │ +│ totalFee = baseFee + wrapDust │ +└───────────────────────────────────────┘ + │ + ▼ +┌───────────────────────────────────────┐ +│ 2. Transfer tokens │ +│ - Fee to feeRecipient │ +│ - Remainder held by Wrapper │ +└───────────────────────────────────────┘ + │ + ▼ +┌───────────────────────────────────────┐ +│ 3. Mint confidential tokens │ +│ mintAmount = transferAmount / rate │ +│ cToken.mint(user, mintAmount) │ +└───────────────────────────────────────┘ +``` + +**Rate Conversion:** +- Confidential tokens use `euint64` (64-bit encrypted integers) +- `rate = 10^(decimals - 6)` for tokens with >6 decimals +- Example: 18-decimal token has `rate = 10^12` + +### Unwrap Flow (Confidential → Public) + +Unwrapping is a **two-stage asynchronous process**: + +**Stage 1: Initiation** +```solidity +// User transfers cTokens to wrapper +cToken.confidentialTransferAndCall( + wrapper, + encryptedAmount, + inputProof, + abi.encode(receiver, refund, callbackData) +); +``` + +The wrapper: +1. Burns the encrypted tokens +2. Marks amounts as publicly decryptable via `FHE.makePubliclyDecryptable()` +3. Stores receiver info with committed fee rate +4. Emits `UnwrappedStarted` event + +**Stage 2: Finalization** +```solidity +// Called with decrypted values and proof +wrapper.finalizeUnwrap( + requestId, + abiEncodedClearBurnAmounts, + decryptionProof +); +``` + +The wrapper: +1. Verifies decryption proof via `FHE.checkSignatures()` +2. Calculates fee and transfer amounts +3. Transfers underlying tokens to receiver +4. On failure: mints cTokens back to refund address + +### Security Model + +**Collateral Parity Invariant:** +- Wrapper always holds exactly enough underlying tokens to back all minted cTokens +- Even if transfers fail, tokens are re-minted to maintain parity + +**Decryption Trust:** +- Off-chain decryption proof is cryptographically verified +- No on-chain decryption occurs + +**Protection Mechanisms:** +- Reentrancy guard on all state-changing functions +- Replay protection via unique requestIds +- Fee-on-transfer token handling via balance tracking + +### Operator System + +Users can authorize operators to finalize unwraps on their behalf: + +```solidity +// Authorize operator for 1 hour +wrapper.setFinalizeUnwrapOperator(operatorAddress, block.timestamp + 3600); +``` + +This enables relayers and intent solvers to complete unwraps. + +### Regulatory Features + +- **SanctionsList**: Blocks transfers to/from sanctioned addresses +- **Regulator role**: Can decrypt specific handles for compliance +- Enforced at ERC7984 transfer level + +--- + +## Governance Mechanisms + +Governance operates cross-chain: the DAO on Ethereum votes on proposals that execute on the Gateway chain via LayerZero messaging and Safe multi-sig. + +### Architecture + +``` +┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ Aragon DAO │ │ LayerZero │ │ Gateway Safe │ +│ (Ethereum) │────▶│ Protocol │────▶│ (Gateway) │ +└─────────────────┘ └─────────────────┘ └─────────────────┘ + │ │ + ▼ ▼ +┌─────────────────┐ ┌─────────────────┐ +│ GovernanceOApp │ │ GovernanceOApp │ +│ Sender │ │ Receiver │ +└─────────────────┘ └────────┬────────┘ + │ + ▼ + ┌─────────────────┐ + │ AdminModule │ + │ (Safe Module) │ + └────────┬────────┘ + │ + ▼ + ┌─────────────────┐ + │ Protocol │ + │ Contracts │ + └─────────────────┘ +``` + +### Key Contracts + +| Contract | File | Purpose | +|----------|------|---------| +| `GovernanceOAppSender` | `governance/contracts/GovernanceOAppSender.sol` | Sends proposals via LayerZero | +| `GovernanceOAppReceiver` | `governance/contracts/GovernanceOAppReceiver.sol` | Receives and routes to Safe | +| `AdminModule` | `safe/contracts/AdminModule.sol` | Executes transactions through Safe | + +### Proposal Lifecycle + +1. **DAO Vote (Ethereum)**: Aragon DAO votes on proposal +2. **Send Cross-Chain**: DAO calls `sendRemoteProposal()` on GovernanceOAppSender +3. **LayerZero Relay**: Message transmitted to Gateway chain +4. **Receive & Route**: GovernanceOAppReceiver calls AdminModule +5. **Safe Execution**: AdminModule executes via Safe's `execTransactionFromModuleReturnData()` + +```solidity +// On Ethereum: Send proposal to Gateway +governanceOAppSender.sendRemoteProposal( + targets, // Contract addresses to call + values, // ETH values (usually 0) + signatures, // Function signatures + calldatas, // Encoded function arguments + operations // CALL or DELEGATECALL +); +``` + +### Safe Integration + +The Safe wallet on Gateway owns protocol infrastructure: + +``` +Safe Wallet + │ + ├── AdminModule (enabled module) + │ │ + │ └── Only GovernanceOAppReceiver can call + │ + └── Owns: GatewayConfig, ProtocolStaking, etc. +``` + +**AdminModule** validates: +- Caller is the authorized admin (GovernanceOAppReceiver) +- All input arrays have matching lengths +- Supports both CALL and DELEGATECALL operations + +### UUPS Upgrade Pattern + +Protocol contracts use UUPS (EIP-1822) for upgradeability: + +```solidity +contract ProtocolStaking is + UUPSUpgradeable, + AccessControlDefaultAdminRulesUpgradeable, + ERC20VotesUpgradeable +{ + function _authorizeUpgrade(address) internal override onlyRole(UPGRADER_ROLE) {} +} +``` + +**Storage Pattern (ERC-7201):** +```solidity +bytes32 private constant STORAGE_LOCATION = + keccak256(abi.encode(uint256(keccak256("fhevm_protocol.storage.ProtocolStaking")) - 1)) + & ~bytes32(uint256(0xff)); +``` + +### Permission Hierarchy + +``` +Aragon DAO (Ethereum) + │ + └── GovernanceOAppSender + │ + └── [LayerZero] + │ + └── GovernanceOAppReceiver + │ + └── AdminModule + │ + └── Safe Wallet + │ + └── Protocol Contracts +``` + +--- + +## Fee Economics + +The protocol collects fees from wrapper operations and burns ZAMA tokens to create deflationary pressure. + +### Fee Flow + +``` +┌─────────────────┐ +│ Wrapper Fees │ (wrap/unwrap basis points) +│ (Gateway) │ +└────────┬────────┘ + │ + ▼ +┌─────────────────┐ +│ FeesSenderTo │ Accumulates ZAMA fees +│ Burner │ +│ (Gateway) │ +└────────┬────────┘ + │ + │ sendFeesToBurner() + │ [LayerZero] + │ + ▼ +┌─────────────────┐ +│ Protocol │ Receives ZAMA tokens +│ FeesBurner │ +│ (Ethereum) │ +└────────┬────────┘ + │ + │ burnFees() + ▼ +┌─────────────────┐ +│ Permanently │ +│ Burned │ +└─────────────────┘ +``` + +### Key Contracts + +| Contract | File | Purpose | +|----------|------|---------| +| `FeeManager` | `confidential-wrapper/contracts/admin/FeeManager.sol` | Configures fee basis points | +| `FeesSenderToBurner` | `feesBurner/contracts/FeesSenderToBurner.sol` | Sends fees cross-chain | +| `ProtocolFeesBurner` | `feesBurner/contracts/ProtocolFeesBurner.sol` | Burns ZAMA on Ethereum | + +### Fee Types + +**Wrapper Fees:** +- `wrapFeeBasisPoints`: Fee on wrap operations (ceiling division) +- `unwrapFeeBasisPoints`: Fee on unwrap operations +- `swapperFee`: Reduced fee for whitelisted swap contracts + +**Collection:** +```solidity +// Wrap fee calculation (ceiling division prevents leakage) +uint256 fee = (amount * basisPoints + 9999) / 10000; +``` + +### Burning Mechanism + +Anyone can trigger burning of accumulated fees: + +```solidity +// On Ethereum: Burn all held ZAMA tokens +protocolFeesBurner.burnFees(); +// Emits: FeesBurned(amount) +``` + +Uses `ERC20Burnable.burn()` to permanently remove tokens from circulation. + +### Economic Incentives + +1. **Deflationary Pressure**: Fee burning reduces total ZAMA supply +2. **Swapper Incentives**: Reduced fees for swap contracts encourage composability +3. **Operator Alignment**: OperatorRewarder fees align operator incentives with staking growth + +--- + +## Cross-Chain Token Flows + +ZAMA tokens use LayerZero's OFT (Omnichain Fungible Token) standard for cross-chain transfers. + +### Architecture + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Ethereum │ +├─────────────────────────────────────────────────────────────────┤ +│ ┌─────────────┐ ┌─────────────────┐ │ +│ │ ZamaERC20 │◀──────▶│ ZamaOFTAdapter │ │ +│ │ (ERC20) │ lock/ │ (OFT wrapper) │ │ +│ │ │ unlock │ │ │ +│ └─────────────┘ └────────┬────────┘ │ +└──────────────────────────────────┼──────────────────────────────┘ + │ + [LayerZero Protocol] + │ +┌──────────────────────────────────┼──────────────────────────────┐ +│ Gateway Chain │ +├──────────────────────────────────┼──────────────────────────────┤ +│ ┌───────┴───────┐ │ +│ │ ZamaOFT │ │ +│ │ (native OFT) │ │ +│ │ mint/burn │ │ +│ └───────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### Key Contracts + +| Contract | File | Purpose | +|----------|------|---------| +| `ZamaERC20` | `token/contracts/ZamaERC20.sol` | Main token on Ethereum | +| `ZamaOFTAdapter` | `token/contracts/ZamaOFTAdapter.sol` | Adapts ERC20 for OFT | +| `ZamaOFT` | `token/contracts/ZamaOFT.sol` | Native OFT on Gateway | + +### Cross-Chain Transfer: Ethereum → Gateway + +```solidity +// 1. Approve adapter +zamaERC20.approve(zamaOFTAdapter, amount); + +// 2. Send cross-chain +zamaOFTAdapter.send( + SendParam({ + dstEid: GATEWAY_EID, // Destination chain ID + to: bytes32(receiver), // Receiver address + amountLD: amount, // Amount in local decimals + minAmountLD: minAmount, // Minimum received + extraOptions: options, // Gas options + composeMsg: "", // Optional compose message + oftCmd: "" // OFT command + }), + fee, + refundAddress +); +``` + +**Flow:** +1. ZamaOFTAdapter locks ERC20 tokens +2. LayerZero relays message to Gateway +3. ZamaOFT mints equivalent tokens on Gateway + +### Cross-Chain Transfer: Gateway → Ethereum + +```solidity +// On Gateway +zamaOFT.send(sendParam, fee, refundAddress); +``` + +**Flow:** +1. ZamaOFT burns tokens on Gateway +2. LayerZero relays message to Ethereum +3. ZamaOFTAdapter unlocks ERC20 tokens + +### Decimal Handling + +OFT uses "shared decimals" for cross-chain consistency: +- Local decimals: Token's native decimal places +- Shared decimals: Normalized for cross-chain (usually 6) +- Conversion: `amountSD = amountLD / conversionRate` + +### ZamaERC20 Features + +Beyond standard ERC20: +- **ERC20Burnable**: Token holders can burn their tokens +- **ERC20Permit**: Gasless approvals via signatures (EIP-2612) +- **ERC1363**: Callback-based transfers (`transferAndCall`) +- **AccessControl**: Role-based minting (MINTER_ROLE) +- **Pausable**: Minting can be paused (MINTING_PAUSER_ROLE) + +```solidity +// ERC1363: Atomic transfer + callback +zamaToken.transferAndCall(receiver, amount, data); + +// ERC20Permit: Gasless approval +zamaToken.permit(owner, spender, value, deadline, v, r, s); +``` + +--- + +**Related:** +- [Gateway Contracts](gateway-contracts.md) - ProtocolPayment integrates with Gateway +- [Reference: Technology Stack](../reference/tech-stack.md) - ERC1363, UUPS patterns +- [Workflows: Decryption Pipeline](../workflows/decryption-pipeline.md) - FHE decryption process diff --git a/docs/codebase/src/executive-summary.md b/docs/codebase/src/executive-summary.md new file mode 100644 index 0000000000..6fc8e294b1 --- /dev/null +++ b/docs/codebase/src/executive-summary.md @@ -0,0 +1,41 @@ +# Executive Summary + +**FHEVM** is the core framework of the Zama Confidential Blockchain Protocol. It 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. + +## Key Guarantees + +- **End-to-end encryption**: Transaction data and state remain encrypted at all times +- **Composability**: Encrypted state coexists with public state, enabling complex DeFi and application logic +- **No impact on existing dApps**: Confidential features are additive; existing applications continue to function + +## Core Innovation + +FHEVM uses **symbolic execution with asynchronous computation**: + +1. FHE operations execute **symbolically on-chain** (fast, deterministic, cheap) +2. Actual FHE computation happens **asynchronously off-chain** via the coprocessor +3. Results are verified and committed back to the chain + +This architecture separates the slow cryptographic work from blockchain consensus, enabling practical FHE on Ethereum-compatible chains. + +## Use Cases + +- **Confidential token transfers** - Private balances without mixers +- **Blind auctions** - Hidden bids until reveal +- **On-chain games** - Hidden cards, moves, selections +- **Encrypted DIDs and attestations** - Private identity credentials +- **Confidential voting** - Anti-bribery, anti-coercion mechanisms + +## What Makes This Possible + +The breakthrough is the **separation of concerns**: + +- **On-chain**: Fast symbolic execution generates deterministic handles +- **Off-chain**: Heavy FHE computation happens asynchronously +- **Verification**: Results are cryptographically verified before commitment + +This enables confidential smart contracts to run at practical speeds on standard EVM chains without requiring specialized consensus mechanisms. + +--- + +**Next:** Learn the [Key Concepts](key-concepts.md) essential to understanding FHEVM → diff --git a/docs/codebase/src/key-concepts.md b/docs/codebase/src/key-concepts.md new file mode 100644 index 0000000000..82a4ee420c --- /dev/null +++ b/docs/codebase/src/key-concepts.md @@ -0,0 +1,83 @@ +# Key Concepts + +Before diving into the architecture, these concepts are essential to understanding FHEVM: + +## Ciphertext Handles + +A **ciphertext handle** is a 32-byte identifier (`bytes32`) that references encrypted data. Think of it like a pointer or database key: + +- The **handle** is stored on-chain (small, cheap) +- The actual **ciphertext** (encrypted data) is stored off-chain in the coprocessor +- Smart contracts operate on handles; the coprocessor operates on ciphertexts + +## Symbolic Execution + +**Symbolic execution** means the on-chain contracts don't perform actual FHE computation. Instead, they: + +1. **Generate deterministic handles**: Given inputs `handle_a` and `handle_b` for an `add` operation, compute `handle_result = hash(handle_a, handle_b, "add", counter)` +2. **Emit events**: Log the operation details for the off-chain coprocessor +3. **Return immediately**: The transaction completes without waiting for FHE computation + +### Example: FHE.add(a, b) + +When a contract calls `FHE.add(a, b)`: + +``` +On-chain (FHEVMExecutor): Off-chain (Coprocessor): +1. Validate inputs +2. Generate handle_c = hash(...) +3. Emit event(ADD, a, b, c) --> 4. Listen for event +4. Return handle_c 5. Load ciphertexts a, b + 6. Compute c = TFHE.add(a, b) + 7. Store ciphertext c + 8. Commit to CiphertextCommits +``` + +The on-chain transaction completes in step 4. Steps 5-8 happen asynchronously seconds/minutes later. + +## Asynchronous Computation Model + +Because FHE operations are slow (seconds to minutes), FHEVM uses an **eventual consistency** model: + +- **Writes are immediate**: `balances[user] = FHE.add(balances[user], amount)` completes immediately (new handle stored) +- **Results arrive later**: The actual encrypted value is computed and stored asynchronously +- **Reads use latest state**: Subsequent operations on the same handle will use the computed ciphertext once available + +### Decryption Requires Callbacks + +Contracts must request decryption explicitly and receive results via callback: + +```solidity +// Request decryption (async) +Gateway.requestDecryption(handle, callbackSelector); + +// Receive result later via callback +function onDecrypt(uint256 plaintext) external onlyGateway { + // Use decrypted value +} +``` + +## Host Chain vs Gateway Chain + +FHEVM supports **multiple host chains** (any EVM-compatible chain) coordinated by a single **gateway chain**: + +- **Host Chain**: Where your dApp runs. Each host chain has its own FHEVMExecutor, ACL, etc. +- **Gateway Chain**: Central coordination point. Stores ciphertext commitments, manages cross-chain ACLs, coordinates with coprocessors and KMS. + +In simple deployments, these may be the same chain. In multichain deployments, the gateway is a separate chain that coordinates FHE operations across all hosts. + +## Key Terminology Quick Reference + +| Term | Meaning | +|------|---------| +| **Handle** | On-chain identifier (bytes32) referencing encrypted data | +| **Ciphertext** | The actual encrypted data (stored off-chain) | +| **Symbolic Execution** | On-chain execution that generates handles without computing | +| **Coprocessor** | Off-chain service performing actual FHE computation | +| **Gateway** | Coordination layer between chains and off-chain services | +| **KMS** | Key Management System using threshold cryptography | +| **HCU** | Homomorphic Complexity Unit - measures FHE operation cost | + +--- + +**Next:** Explore the [Architecture Overview](architecture.md) → diff --git a/docs/codebase/src/reference/glossary.md b/docs/codebase/src/reference/glossary.md new file mode 100644 index 0000000000..3442860f95 --- /dev/null +++ b/docs/codebase/src/reference/glossary.md @@ -0,0 +1,191 @@ +# Glossary + +Comprehensive terminology reference for the FHEVM codebase. + +## Core Concepts + +**Ciphertext** +Encrypted data that can be operated on using Fully Homomorphic Encryption (FHE). The actual encrypted bytes stored off-chain in the coprocessor's database. + +**Ciphertext Handle** +A 32-byte (`bytes32`) identifier that references off-chain encrypted data. On-chain contracts store and manipulate handles, not ciphertexts themselves. Think of it like a pointer or database key. + +**Coprocessor** +Off-chain Rust service that performs actual FHE computation. Listens to blockchain events, executes TFHE operations asynchronously, and submits verified results back to the chain. + +**Symbolic Execution** +On-chain execution model where contracts generate deterministic handles for operations without performing actual FHE computation. The "symbolic" part means it manipulates symbols (handles) representing values rather than the values themselves. + +## System Architecture + +**FHE (Fully Homomorphic Encryption)** +Cryptographic scheme that allows arbitrary computation on encrypted data without decrypting it. FHEVM uses the TFHE scheme implemented in TFHE-rs. + +**TFHE (Torus Fully Homomorphic Encryption)** +Specific FHE scheme used by FHEVM. Optimized for boolean and small integer operations. Implemented in the TFHE-rs Rust library. + +**Gateway Chain** +Central EVM chain that coordinates FHE operations across multiple host chains. Stores ciphertext commitments, manages cross-chain ACLs, and coordinates with coprocessors and KMS. + +**Host Chain** +Any EVM-compatible blockchain where confidential dApps run. Each host chain has its own FHEVMExecutor, ACL, and other host contracts. + +**KMS (Key Management System)** +System that manages encryption keys using multi-party computation (MPC). Ensures no single party holds complete decryption keys. FHEVM uses external KMS Core for key operations. + +**KMS Core** +External service (not in this repository) that implements the threshold key management protocol. KMS Connector interfaces with KMS Core. + +## Blockchain Components + +**ACL (Access Control List)** +Smart contract that manages permissions for encrypted data handles. Controls which contracts and users can access specific ciphertexts. + +**CiphertextCommits** +Gateway contract that stores commitments to ciphertexts computed by the coprocessor. Acts as proof that ciphertext exists and matches the handle. + +**FHEVMExecutor** +Host contract that provides symbolic execution of FHE operations. Implements 20+ operators like `fheAdd`, `fheMul`, `fheEq`, etc. + +**GatewayConfig** +Central registry on the gateway chain for KMS nodes, coprocessor instances, and protocol metadata. + +**HCU (Homomorphic Complexity Unit)** +Measure of computational cost for FHE operations. Used to limit transaction complexity and prevent DoS. Each operation has an HCU cost (e.g., `fheAdd` costs 10 HCU). + +**InputVerifier** +Contract that verifies zero-knowledge proofs for user-submitted encrypted inputs. Ensures ciphertexts are well-formed before accepting them. + +## Off-Chain Components + +**gw-listener** +Component that monitors gateway chain for relevant events (decryption requests, key operations, etc.). Part of both Coprocessor and KMS Connector. + +**host-listener** +Component that monitors host chain for FHE operation events. Part of the Coprocessor. + +**Scheduler** +Coprocessor component that orchestrates job distribution to worker threads. Manages priority queues and retry logic. + +**tfhe-worker** +Coprocessor component that performs actual TFHE operations using the TFHE-rs library. CPU and GPU-accelerated. + +**zkproof-worker** +Coprocessor component that generates zero-knowledge proofs for certain operations. + +**sns-worker** +Coprocessor component that performs "Switch and Squash" optimizations on ciphertexts to reduce size and improve performance. + +**transaction-sender** +Component that submits results from off-chain computation back to blockchain. Handles nonce management, gas estimation, and retries. + +## Cryptographic Operations + +**EIP712** +Ethereum standard for typed structured data hashing and signing. Used for KMS signatures on decryption results and other off-chain-generated data. + +**MPC (Multi-Party Computation)** +Cryptographic protocol where multiple parties jointly compute a function while keeping inputs private. Used by KMS for threshold key operations. + +**Threshold Signature** +Signature scheme where t-of-n parties must cooperate to create a valid signature. Used by KMS to sign decryption results (e.g., 3-of-5 KMS nodes must agree). + +**Zero-Knowledge Proof (ZK Proof)** +Cryptographic proof that a statement is true without revealing why it's true. Used to prove encrypted inputs are well-formed without revealing plaintext. + +## Protocol & Economics + +**OFT (Omnichain Fungible Token)** +LayerZero standard for tokens that can transfer across chains. Used by ZAMA token for cross-chain transfers. + +**OperatorStaking** +Protocol contract for node operators to stake ZAMA tokens. Provides economic security and Sybil resistance. + +**ProtocolPayment** +Gateway contract that handles fee collection and distribution to operators. Implements the economic incentive layer. + +**Rewarder** +Protocol contract that distributes rewards to stakers and delegators based on operator performance. + +**UUPS (Universal Upgradeable Proxy Standard)** +Pattern for upgradeable smart contracts. Implementation stored separately from proxy, allowing logic updates. + +## Development & Testing + +**Hardhat** +Ethereum development environment for compiling, testing, and deploying smart contracts. Uses TypeScript for tests. + +**Foundry** +Rust-based Ethereum development toolkit. Uses Solidity for tests (`forge test`). + +**Mock FHE** +SQLite-backed fake FHE system for testing. Provides same API as real FHE but returns deterministic results instantly. + +**TypeChain** +Tool that generates TypeScript bindings from smart contract ABIs. Enables type-safe contract interaction in tests. + +## Encrypted Types + +**ebool** +Encrypted boolean type. Represents encrypted true/false values. + +**euint8, euint16, euint32, euint64, euint128, euint256** +Encrypted unsigned integer types of various bit sizes. Main types for confidential numeric operations. + +**eint8, eint16, eint32, eint64, eint128, eint256** +Encrypted signed integer types. Support negative values. + +**eaddress** +Encrypted Ethereum address type. Enables confidential address storage and comparison. + +**AsciiString** +Encrypted ASCII string type. Enables confidential string operations. + +## Operations + +**Arithmetic Operations** +`add`, `sub`, `mul`, `div`, `rem`, `min`, `max` - Standard math operations on encrypted values. + +**Comparison Operations** +`eq`, `ne`, `lt`, `le`, `gt`, `ge` - Comparison operations returning encrypted booleans. + +**Bitwise Operations** +`and`, `or`, `xor`, `not`, `shl`, `shr`, `rotl`, `rotr` - Bit manipulation operations. + +**Control Flow** +`select` - Encrypted ternary operator: `condition ? a : b`. Enables conditional logic without revealing which branch executes. + +## Deployment + +**Helm** +Kubernetes package manager. FHEVM components deployed via Helm charts in `/charts/`. + +**Kubernetes (K8s)** +Container orchestration platform. Used for production deployment of coprocessor, KMS connector, and other services. + +**docker-compose** +Tool for defining multi-container applications. Used in test-suite for local development and E2E testing. + +## Miscellaneous + +**Handle Generation** +Process of creating deterministic ciphertext handles. Uses cryptographic hash of inputs, operation type, and counter. + +**Eventual Consistency** +Design pattern where on-chain state (handles) is immediately consistent, but off-chain ciphertexts become available later. + +**Async Computation Model** +FHEVM's model where expensive operations happen asynchronously off-chain while on-chain transactions complete quickly. + +**Multichain Deployment** +Configuration where single gateway chain coordinates FHE operations across multiple host chains. + +**Single-chain Deployment** +Simple configuration where gateway and host are the same chain. Suitable for testing and simple deployments. + +--- + +**Related:** +- [Key Concepts](../key-concepts.md) - Detailed explanation of core concepts +- [Quick Reference](quick-reference.md) - Fast lookup guide +- [Technology Stack](tech-stack.md) - Technologies used diff --git a/docs/codebase/src/reference/quick-reference.md b/docs/codebase/src/reference/quick-reference.md new file mode 100644 index 0000000000..8722f8564f --- /dev/null +++ b/docs/codebase/src/reference/quick-reference.md @@ -0,0 +1,236 @@ +# Quick Reference + +Fast lookup guide for developers working with the FHEVM codebase. + +## Directory Map + +``` +fhevm/ +├── gateway-contracts/ # Bridge to off-chain (Solidity) +├── host-contracts/ # On-chain FHE execution (Solidity) +├── library-solidity/ # Developer FHE library (Solidity) +├── protocol-contracts/ # Token, staking, governance (Solidity) +├── coprocessor/ # FHE compute engine (Rust) +├── kms-connector/ # KMS bridge (Rust) +├── charts/ # Kubernetes Helm charts +├── test-suite/ # E2E integration tests +├── docs/ # Documentation source +└── sdk/ # Rust SDK +``` + +## Entry Points for Developers + +**Writing contracts:** +- Start: `/library-solidity/lib/FHE.sol` +- Examples: `/library-solidity/examples/` +- Types: `/library-solidity/lib/FheType.sol` + +**Understanding execution:** +- Symbolic execution: `/host-contracts/contracts/FHEVMExecutor.sol` +- ACL: `/host-contracts/contracts/ACL.sol` +- Events: Look for `event` declarations in contracts + +**Understanding coordination:** +- Gateway config: `/gateway-contracts/contracts/GatewayConfig.sol` +- Decryption: `/gateway-contracts/contracts/Decryption.sol` +- Ciphertext commits: `/gateway-contracts/contracts/CiphertextCommits.sol` + +**Running tests:** +- Hardhat: `npm run test` in contract directories +- Foundry: `forge test` in contract directories +- E2E: `docker-compose up` in `/test-suite/` + +**Deploying:** +- Helm: `/charts/` configurations +- Docker: `docker-compose.yml` files + +## Common Commands + +### Smart Contracts (Hardhat) + +```bash +# In contract directories (host-contracts/, gateway-contracts/, etc.) +npm install # Install dependencies +npm run compile # Compile contracts +npm run test # Run tests +npm run coverage # Test coverage +npm run lint # Lint Solidity +npm run format # Format code +``` + +### Smart Contracts (Foundry) + +```bash +forge build # Compile +forge test # Run tests +forge test -vvv # Verbose test output +forge coverage # Coverage report +forge fmt # Format code +``` + +### Rust Services + +```bash +# In coprocessor/ or kms-connector/ +cargo build --release # Build optimized binary +cargo test # Run tests +cargo clippy # Linting +cargo fmt # Format code +cargo check # Fast compile check +``` + +### Docker Compose (Full Stack) + +```bash +# In test-suite/ +docker-compose up # Start all services +docker-compose down # Stop services +docker-compose logs -f # Follow logs +docker-compose ps # Show status +``` + +## Key Contract Addresses (Example Deployment) + +> **Note:** These are example addresses. Actual addresses vary by deployment. + +**Host Chain Contracts:** +``` +FHEVMExecutor: 0x1234... +ACL: 0x5678... +HCULimit: 0x9abc... +KMSVerifier: 0xdef0... +InputVerifier: 0x1357... +``` + +**Gateway Chain Contracts:** +``` +GatewayConfig: 0x2468... +Decryption: 0x369c... +MultichainACL: 0x48ae... +CiphertextCommits: 0x59bf... +``` + +## FHE Operation Gas Costs + +Symbolic execution (on-chain): + +| Operation | Gas Cost (approx) | +|-----------|------------------| +| `fheAdd` | ~50k gas | +| `fheMul` | ~50k gas | +| `fheEq` | ~50k gas | +| `fheSelect` | ~60k gas | +| Input verification | ~150k-300k gas | + +> **Note:** Actual FHE computation happens off-chain asynchronously (no gas cost). + +## Encrypted Type Reference + +```solidity +import {FHE, euint32, ebool, eaddress} from "fhevm/lib/FHE.sol"; + +// Type declarations +euint8 smallNumber; +euint32 balance; +euint256 largeNumber; +ebool flag; +eaddress addr; + +// Operations +euint32 sum = FHE.add(a, b); +euint32 product = FHE.mul(a, b); +ebool isEqual = FHE.eq(a, b); +ebool isLess = FHE.lt(a, b); +euint32 result = FHE.select(condition, ifTrue, ifFalse); +``` + +## Common Patterns + +### Confidential Balance Transfer + +```solidity +function transfer(address to, euint32 amount) external { + balances[msg.sender] = FHE.sub(balances[msg.sender], amount); + balances[to] = FHE.add(balances[to], amount); +} +``` + +### Request Decryption + +```solidity +function revealBalance() external { + Gateway.requestDecryption( + balances[msg.sender], + this.onBalanceRevealed.selector + ); +} + +function onBalanceRevealed(uint256 balance) external onlyGateway { + emit BalanceRevealed(msg.sender, balance); +} +``` + +### Accept Encrypted Input + +```solidity +function deposit(bytes calldata ciphertext, bytes calldata proof) external { + euint32 amount = FHE.asEuint32(ciphertext, proof); + balances[msg.sender] = FHE.add(balances[msg.sender], amount); +} +``` + +## Environment Variables + +### Coprocessor + +```bash +DATABASE_URL=postgresql://user:pass@localhost/fhevm +RPC_URL=https://eth-node.example.com +PRIVATE_KEY=0x... +GATEWAY_CONTRACT_ADDRESS=0x... +``` + +### KMS Connector + +```bash +DATABASE_URL=postgresql://user:pass@localhost/kms +RPC_URL=https://eth-node.example.com +PRIVATE_KEY=0x... +KMS_CORE_URL=https://kms.example.com +``` + +## Debugging Tips + +**Smart contracts:** +- Use `console.log()` from Hardhat (import `hardhat/console.sol`) +- Check events with `forge test -vvv` for detailed output +- Use Hardhat Network's `console.log` for TypeScript tests + +**Rust services:** +- Set `RUST_LOG=debug` for verbose logging +- Use `tracing` macros: `tracing::debug!("message")` +- Check PostgreSQL logs for database issues + +**E2E tests:** +- Check `docker-compose logs -f servicename` +- Inspect database: `docker-compose exec postgres psql -U user -d fhevm` +- Verify blockchain state: Use Hardhat console or cast commands + +## Useful Links + +**Official Documentation:** +- FHEVM Docs: (internal docs links) +- TFHE-rs: https://github.com/zama-ai/tfhe-rs +- OpenZeppelin: https://docs.openzeppelin.com/contracts/ + +**Development Tools:** +- Hardhat: https://hardhat.org/ +- Foundry: https://book.getfoundry.sh/ +- Tokio: https://tokio.rs/ + +--- + +**Related:** +- [Technology Stack](tech-stack.md) - Complete technology breakdown +- [Glossary](glossary.md) - Term definitions +- [Components](../components/README.md) - Detailed component documentation diff --git a/docs/codebase/src/reference/roadmap.md b/docs/codebase/src/reference/roadmap.md new file mode 100644 index 0000000000..f0948a5fca --- /dev/null +++ b/docs/codebase/src/reference/roadmap.md @@ -0,0 +1,207 @@ +# Documentation Roadmap + +This page tracks areas that need deeper documentation, prioritized by component activity level and development needs. + +## Priority System + +Documentation priorities are based on: +- 🔥 **High Priority**: Active development components, frequently changing +- ✅ **Medium Priority**: Stable components, foundational understanding needed +- 📦 **Lower Priority**: Infrastructure, less critical for understanding core protocol + +## High Priority (🔥 Active Components) + +### 1. Coprocessor Deep Dives + +**Worker Architecture** +- Detail tfhe-worker, zkproof-worker, sns-worker implementations +- Document processing pipelines and optimization strategies +- Explain TFHE-rs integration and GPU utilization + +**Scheduler and Job Orchestration** +- Job lifecycle from event reception to result submission +- Priority queues, retry logic, and failure handling +- Database schema and query optimization + +**GPU Optimization** +- GPU scheduling and memory management +- Performance tuning for FHE operations +- Metrics and monitoring + +**Consensus Mechanism** +- How multiple coprocessors coordinate +- Threshold agreement on computation results +- Byzantine fault tolerance properties + +### 2. Gateway Contracts + +**Gateway Consensus Mechanism** +- Threshold-based consensus for ciphertext commits +- How multiple coprocessors agree on computation results +- Verification and slashing mechanisms + +**Multichain ACL Flow** +- Access control delegations across different host chains +- Cross-chain permission synchronization +- LayerZero integration details + +**Payment Protocol Design** +- Fee collection, distribution, and operator compensation +- Economic incentives and game theory +- ProtocolPayment contract deep dive + +### 3. KMS Connector + +**KMS Integration Flow** +- Complete flow from decryption request to signed response +- Sequence diagrams and error handling patterns +- Performance characteristics and optimization + +**Threshold Signature Scheme** +- MPC-based threshold signature mechanism +- Trust model and security guarantees +- Key generation, rotation, and reshare protocols + +**External KMS Core Integration** +- Interface contract with external KMS Core service +- API expectations and deployment patterns +- Operational considerations + +### 4. Protocol Contracts + +**Staking/Delegation Contracts** +- OperatorStaking and Rewarder implementations +- Staking mechanics, slashing conditions, reward calculation +- Delegation patterns and operator economics + +**Confidential Wrapper Pattern** +- How public ERC20 tokens are wrapped for confidential use +- Bridge security model and liquidity management +- Unwrap process and guarantees + +**Governance Mechanisms** +- DAO voting contracts and proposal lifecycle +- Safe integration for admin operations +- Upgrade patterns and security + +## Medium Priority (✅ Stable Components) + +### 5. Host Contracts + +**FHEVMExecutor Operators** +- All 20+ FHE operators and symbolic execution semantics +- Type compatibility and conversion rules +- Gas costs and performance characteristics + +**ACL Permission Model** +- allowList, denyList, and delegation mechanisms +- Permission grant/revoke flows +- Cross-contract access patterns + +**HCU Limit Enforcement** +- 20M HCU/tx and 5M depth limits +- How limits prevent DoS attacks +- Optimization strategies for complex operations + +### 6. Solidity Library + +**Encrypted Type System** +- All supported types, bit sizes, and conversion rules +- Memory and gas implications +- Type safety guarantees + +**Codegen System** +- Operator overload generation process +- How to extend the library with new operations +- Codegen toolchain and customization + +**Best Practices** +- Recommended patterns for confidential smart contracts +- Common pitfalls and how to avoid them +- Optimization strategies + +**Examples Deep-Dive** +- Walkthrough of reference implementations +- EncryptedERC20, ConfidentialVoting, etc. +- Detailed explanations with commentary + +## Lower Priority (📦 Infrastructure) + +### 7. Testing Infrastructure + +**Mock FHE System** +- SQLite-backed mocking implementation +- How to write tests using mock FHE +- Performance characteristics vs real FHE + +**E2E Testing Patterns** +- docker-compose setup and component interaction +- Writing effective E2E tests +- Debugging techniques for integration tests + +**Test Fixtures** +- Reusable test data and scenarios +- Contract deployment helpers +- Common test utilities + +### 8. Deployment + +**Helm Charts Deep Dive** +- Kubernetes deployment process +- Configuration options and tuning +- Multi-environment strategies (dev/staging/prod) + +**Operational Best Practices** +- Monitoring and alerting +- Backup and disaster recovery +- Performance tuning + +**Docker Compose Stack** +- test-suite setup and component configuration +- How components interact in local development +- Debugging issues in the stack + +### 9. CI/CD Pipeline + +**GitHub Actions Workflows** +- Testing strategy and coverage requirements +- Build and publish pipelines +- Security scanning and auditing + +**Release Process** +- Versioning strategy +- Changelog generation +- Deployment automation + +## Contribution Guidelines + +When expanding documentation: + +1. **High-priority areas** (🔥): Document current state, note potential for change +2. **Stable areas** (✅): Create comprehensive, detailed documentation +3. **Infrastructure** (📦): Focus on operational patterns and deployment + +### Documentation Standards + +Each expanded section should include: +- **Overview**: High-level summary +- **Detailed explanation**: Step-by-step with examples +- **Diagrams**: Architecture diagrams, sequence diagrams +- **Code examples**: Working code snippets +- **Edge cases**: Error handling and unusual scenarios +- **Performance**: Gas costs, timing, optimization tips +- **Related sections**: Cross-links to related docs + +## Tracking Progress + +Each TODO in component documentation maps to a section above. As documentation is created: +1. Remove [TODO] marker from source document +2. Add link to new detailed documentation +3. Update this roadmap to reflect completion + +--- + +**Related:** +- [Component Health](../component-health.md) - Which areas are actively evolving +- [Components](../components/README.md) - Component overview with TODO markers +- [Workflows](../workflows/README.md) - Workflow documentation with TODOs diff --git a/docs/codebase/src/reference/tech-stack.md b/docs/codebase/src/reference/tech-stack.md new file mode 100644 index 0000000000..4a3411a64c --- /dev/null +++ b/docs/codebase/src/reference/tech-stack.md @@ -0,0 +1,195 @@ +# Technology Stack + +This page documents the complete technology stack used across the FHEVM codebase. + +## Smart Contracts + +| Technology | Version | Purpose | Key Files | +|------------|---------|---------|-----------| +| **Solidity** | 0.8.24+ | Smart contract language | `*.sol` | +| **OpenZeppelin** | v5.2 | Security-audited contract libraries | `package.json` | +| **Hardhat** | Latest | Development environment, testing, deployment | `hardhat.config.ts` | +| **Foundry** | Latest | Solidity-native testing framework | `foundry.toml` | +| **TypeChain** | Latest | TypeScript bindings for contracts | Generated in `typechain/` | +| **Prettier** | Latest | Code formatting | `.prettierrc` | +| **Solhint** | Latest | Solidity linting | `.solhint.json` | + +### Upgrade Patterns + +**UUPS (Universal Upgradeable Proxy Standard):** +- Used for upgradeable contracts +- Implementation in OpenZeppelin v5.2 +- Allows contract logic updates without changing addresses + +### Standards + +**ERC Standards:** +- ERC20 - Fungible tokens +- ERC1363 - Payable token with callbacks +- EIP712 - Typed structured data hashing and signing + +## Off-Chain Services (Rust) + +| Technology | Version | Purpose | Key Files | +|------------|---------|---------|-----------| +| **Rust** | 1.75+ | Systems programming language | `Cargo.toml` | +| **TFHE-rs** | Latest | FHE operations library | Used in `tfhe-worker` | +| **Tokio** | 1.x | Async runtime | Throughout Rust crates | +| **SQLx** | Latest | Async SQL driver (PostgreSQL) | Database queries | +| **PostgreSQL** | 14+ | Database for job state and ciphertexts | `schema.sql` | +| **Tonic** | Latest | gRPC framework | Service definitions | +| **Protobuf** | 3.x | Serialization format | `*.proto` | +| **Serde** | Latest | Serialization/deserialization | Throughout | +| **Ethers-rs** | Latest | Ethereum library for Rust | Blockchain interaction | + +### Key Rust Crates + +**Coprocessor:** +- `tfhe-worker` - FHE computation using TFHE-rs +- `scheduler` - Job orchestration with Tokio +- `zkproof-worker` - Zero-knowledge proof generation +- `sns-worker` - Switch and Squash optimizations +- `host-listener` - Blockchain event monitoring +- `gw-listener` - Gateway event monitoring +- `transaction-sender` - Submit results to chain + +**KMS Connector:** +- `gw-listener` - Monitor Gateway events +- `kms-worker` - Interface with external KMS Core +- `transaction-sender` - Submit signed responses +- `utils` - Shared utilities + +## Cryptography + +| Technology | Purpose | Implementation | +|------------|---------|----------------| +| **TFHE** | Fully Homomorphic Encryption scheme | TFHE-rs library | +| **EIP712** | Structured data signing | Ethereum standard | +| **ZK Proofs** | Input verification without revealing data | zkproof-worker | +| **Threshold Signatures** | MPC-based signing (t-of-n) | External KMS Core | +| **ECDSA** | Ethereum transaction signing | ethers-rs | + +## Deployment & Infrastructure + +| Technology | Purpose | Key Files | +|------------|---------|-----------| +| **Docker** | Containerization | `Dockerfile`, `docker-compose.yml` | +| **Kubernetes** | Container orchestration | `charts/` | +| **Helm** | Kubernetes package manager | `charts/*/Chart.yaml` | +| **GitHub Actions** | CI/CD pipelines | `.github/workflows/` | + +### Helm Charts + +Located in `/charts/`: +- Deployment manifests for all components +- ConfigMaps for configuration +- Services and Ingress definitions +- Emerging as primary deployment method + +## Testing + +| Technology | Purpose | Location | +|------------|---------|----------| +| **Hardhat** | Smart contract testing (TypeScript) | `host-contracts/test/` | +| **Foundry** | Smart contract testing (Solidity) | `forge test` commands | +| **Jest** | JavaScript/TypeScript unit tests | Various `test/` dirs | +| **Docker Compose** | E2E integration testing | `test-suite/docker-compose.yml` | +| **SQLite** | Mock FHE backend for fast testing | Test configurations | + +### Mock FHE System + +**Purpose:** Enable fast testing without expensive FHE operations + +**Implementation:** +- SQLite database stores "fake" ciphertexts +- Operations return deterministic results +- API-compatible with real FHE +- Dramatically faster (ms vs seconds) + +## Development Tools + +| Tool | Purpose | +|------|---------| +| **pnpm** | Node.js package manager (workspaces) | +| **Cargo** | Rust package manager and build tool | +| **Git** | Version control | +| **pre-commit hooks** | Automated formatting and linting | +| **GitHub** | Source control and CI/CD | + +## Communication Protocols + +| Protocol | Purpose | Used Between | +|----------|---------|--------------| +| **JSON-RPC** | Ethereum node communication | All → Blockchain | +| **gRPC** | Service-to-service communication | Coprocessor components | +| **WebSocket** | Event streaming | Listeners → Blockchain | +| **HTTP REST** | KMS Core API | KMS Connector → KMS Core | + +## Cross-Chain + +| Technology | Purpose | Component | +|------------|---------|-----------| +| **LayerZero** | Omnichain messaging | Gateway contracts | +| **OFT (Omnichain Fungible Token)** | Cross-chain token transfers | Protocol contracts | + +## Build & Development + +### Smart Contracts + +```bash +# Hardhat +npm run compile # Compile contracts +npm run test # Run tests +npm run deploy # Deploy contracts + +# Foundry +forge build # Compile +forge test # Test +forge coverage # Coverage report +``` + +### Rust Services + +```bash +cargo build --release # Build optimized +cargo test # Run tests +cargo clippy # Linting +cargo fmt # Format code +``` + +### Full Stack + +```bash +# Docker Compose (test-suite) +docker-compose up # Start all services +docker-compose down # Stop all services +``` + +## Language Breakdown + +| Language | Primary Use | Lines of Code (approx) | +|----------|-------------|----------------------| +| **Solidity** | Smart contracts | ~30,000 | +| **Rust** | Off-chain services | ~50,000 | +| **TypeScript** | Tests, tooling, SDK | ~20,000 | +| **JavaScript** | Build scripts, configs | ~5,000 | +| **YAML** | Configuration, CI/CD | ~3,000 | + +## Version Requirements + +**Minimum versions:** +- Node.js: 18.x or later +- Rust: 1.75 or later +- Solidity: 0.8.24 +- PostgreSQL: 14.x + +**Recommended versions:** +- Latest stable Node.js LTS +- Latest stable Rust +- PostgreSQL 15.x for best performance + +--- + +**Related:** +- [Supporting Infrastructure](../components/infrastructure.md) - Deployment and testing details +- [Component Health](../component-health.md) - Which components are actively evolving diff --git a/docs/codebase/src/workflows/README.md b/docs/codebase/src/workflows/README.md new file mode 100644 index 0000000000..c99189f4f6 --- /dev/null +++ b/docs/codebase/src/workflows/README.md @@ -0,0 +1,61 @@ +# Key Workflows + +This section documents the critical operational flows in FHEVM, showing how components interact to process encrypted data from end to end. + +## Three Core Workflows + +### 1. [Symbolic Execution Pattern](symbolic-execution.md) +How FHE operations execute on-chain symbolically while computation happens asynchronously off-chain. + +**When it happens:** Every time a smart contract performs an FHE operation like `FHE.add(a, b)` + +**Key insight:** On-chain transactions complete immediately with handle generation; actual FHE computation happens seconds/minutes later. + +### 2. [Decryption Pipeline](decryption-pipeline.md) +How encrypted data is decrypted through threshold cryptography and delivered back to smart contracts via callbacks. + +**When it happens:** When a contract requests decryption via `Gateway.requestDecryption()` + +**Key insight:** Decryption requires MPC across multiple KMS nodes; no single party can decrypt alone. + +### 3. [Input Verification](input-verification.md) +How users submit encrypted inputs with zero-knowledge proofs to ensure data validity without revealing content. + +**When it happens:** When users submit encrypted data to smart contracts (e.g., encrypted token amounts) + +**Key insight:** ZK proofs verify that ciphertext is well-formed and meets constraints without revealing plaintext. + +## Workflow Interactions + +These three workflows compose to enable confidential smart contracts: + +``` +User prepares encrypted input + ↓ + Input Verification (ZK proof validation) + ↓ +Contract receives validated ciphertext handle + ↓ + Symbolic Execution (FHE operations) + ↓ + [Async FHE computation off-chain] + ↓ +Contract requests decryption (optional) + ↓ + Decryption Pipeline (threshold MPC) + ↓ +Contract receives plaintext via callback +``` + +## Understanding the Workflows + +Each workflow document includes: +- **Step-by-step flow** with component interactions +- **Example scenarios** showing real-world usage +- **Sequence diagrams** visualizing the flow +- **Error handling** and edge cases +- **Performance characteristics** (timing, gas costs) + +--- + +Choose a workflow to explore its detailed documentation. diff --git a/docs/codebase/src/workflows/decryption-pipeline.md b/docs/codebase/src/workflows/decryption-pipeline.md new file mode 100644 index 0000000000..1675be2521 --- /dev/null +++ b/docs/codebase/src/workflows/decryption-pipeline.md @@ -0,0 +1,172 @@ +# Decryption Pipeline + +## Overview + +The decryption pipeline enables smart contracts to request decryption of encrypted values and receive plaintext results via callbacks. Decryption uses threshold cryptography (MPC) across multiple KMS nodes, ensuring no single party can decrypt alone. + +## The Pipeline + +When a contract requests decryption: + +### Step 1: Request Decryption (On-Chain) + +```solidity +// Contract requests decryption +Gateway.requestDecryption( + ciphertextHandle, + this.onDecrypt.selector +); +``` + +**What happens:** +- Contract calls `Decryption.sol` on Gateway +- Request logged with callback selector +- Transaction completes immediately + +### Step 2: ACL Verification (Gateway) + +**MultichainACL checks:** +- Does the requesting contract have permission to decrypt this handle? +- Is the request properly authorized? + +**If denied:** Request is rejected, callback never called + +**If approved:** Proceed to KMS + +### Step 3: KMS Notification (Off-Chain) + +**Gateway emits event:** +``` +DecryptionRequested(requestId, handle, callbackSelector, contractAddress) +``` + +**KMS Connector (gw-listener) detects event:** +- Parses decryption request +- Creates job for kms-worker +- Forwards to external KMS Core + +### Step 4: Threshold Decryption (KMS Core - External) + +**KMS Core orchestrates MPC protocol:** +1. Broadcast decryption request to all KMS nodes (threshold: t-of-n) +2. Each node performs partial decryption using its key share +3. Combine t partial decryptions to recover plaintext +4. Generate EIP712 signature over result (threshold signature) + +**Security properties:** +- No single KMS node sees the plaintext key +- Requires threshold (e.g., 3-of-5) nodes to cooperate +- Malicious minority cannot decrypt or corrupt result + +### Step 5: Submit Signed Result (Off-Chain → On-Chain) + +**KMS Connector (transaction-sender):** +- Receives signed plaintext from KMS Core +- Submits transaction to `KMSVerifier` contract +- Includes: plaintext value, EIP712 signature, requestId + +### Step 6: Verify Signature (Host Chain) + +**KMSVerifier contract:** +- Verifies EIP712 threshold signature +- Checks signature matches registered KMS nodes +- Validates requestId matches pending request + +**If valid:** Approve callback +**If invalid:** Reject and log error + +### Step 7: Callback Delivery (On-Chain) + +**KMSVerifier calls back to original contract:** + +```solidity +// Contract receives decrypted value +function onDecrypt(uint256 plaintext) external onlyGateway { + // Use decrypted value + require(plaintext > minimumBid, "Bid too low"); + winningBid = plaintext; + winningBidder = msg.sender; +} +``` + +## Example: Blind Auction Reveal + +```solidity +contract BlindAuction { + mapping(address => euint32) private bids; + uint256 public winningBid; + address public winningBidder; + + // User submits encrypted bid + function submitBid(euint32 encryptedBid) external { + bids[msg.sender] = encryptedBid; + } + + // Auction ends, reveal winning bid + function revealWinner(address bidder) external { + Gateway.requestDecryption( + bids[bidder], + this.onBidRevealed.selector + ); + } + + // Callback receives plaintext + function onBidRevealed(uint256 bidAmount) external onlyGateway { + if (bidAmount > winningBid) { + winningBid = bidAmount; + winningBidder = msg.sender; + } + } +} +``` + +**Flow:** +1. T=0s: Contract calls `revealWinner(alice)` +2. T=0s: Request logged, transaction completes +3. T=2s: KMS Connector detects request +4. T=5s: KMS nodes perform threshold decryption +5. T=8s: Signed result submitted to KMSVerifier +6. T=9s: `onBidRevealed(1500)` called on contract +7. T=9s: Contract updates state with plaintext bid + +## Security Considerations + +### Threshold Security + +**Trust model:** +- Requires threshold (t) of total (n) KMS nodes to cooperate +- Adversary controlling < t nodes cannot decrypt +- Example: 3-of-5 means adversary must compromise 3+ nodes + +### ACL Enforcement + +**Permission checks:** +- Only contracts with ACL permission can request decryption +- ACL permissions set by data owner +- Prevents unauthorized decryption of sensitive data + +### Callback Safety + +**Reentrancy protection:** +- Callbacks should use `nonReentrant` modifier +- Validate caller is KMSVerifier +- Handle partial failures gracefully + +## Areas for Deeper Documentation + +**[TODO: EIP712 signature format]** - Complete specification of the signed data structure for decryption results and verification process. + +**[TODO: Threshold MPC protocol]** - Detailed explanation of the multi-party computation protocol used for threshold decryption. + +**[TODO: ACL permission model]** - How permissions are granted, revoked, and checked across multiple chains. + +**[TODO: Error handling patterns]** - Best practices for handling decryption failures, timeouts, and partial results in smart contracts. + +**[TODO: Gas optimization]** - Strategies for minimizing gas costs in callback functions and batch decryption requests. + +--- + +**Related:** +- [Gateway Contracts](../components/gateway-contracts.md) - Decryption.sol and MultichainACL +- [KMS Connector](../components/kms-connector.md) - Off-chain KMS coordination +- [Host Contracts](../components/host-contracts.md) - KMSVerifier implementation diff --git a/docs/codebase/src/workflows/input-verification.md b/docs/codebase/src/workflows/input-verification.md new file mode 100644 index 0000000000..0c6d63c155 --- /dev/null +++ b/docs/codebase/src/workflows/input-verification.md @@ -0,0 +1,192 @@ +# Input Verification + +## Overview + +Input verification enables users to submit encrypted data to smart contracts with zero-knowledge proofs that validate the data's properties without revealing its content. This ensures ciphertexts are well-formed and meet constraints before processing. + +## The Workflow + +When a user submits encrypted input to a smart contract: + +### Step 1: Client-Side Preparation + +**User's client application:** + +1. **Encrypt plaintext data** + ```javascript + const plaintext = 1000; // e.g., token amount + const { ciphertext, publicKey } = await fhevmClient.encrypt(plaintext); + ``` + +2. **Generate zero-knowledge proof** + ```javascript + const proof = await fhevmClient.generateProof(ciphertext, plaintext); + ``` + + **Proof certifies:** + - Ciphertext encrypts a valid value (not malformed) + - Value meets constraints (e.g., within range, non-negative) + - User knows the plaintext (prevents replay of intercepted ciphertexts) + +3. **Submit to blockchain** + ```javascript + await contract.transfer(recipient, ciphertext, proof); + ``` + +### Step 2: On-Chain Proof Verification + +**Contract calls InputVerifier:** + +```solidity +function transfer(address to, bytes calldata ciphertext, bytes calldata proof) external { + // Verify proof and get handle + euint32 amount = FHE.asEuint32(ciphertext, proof); + + // Now safe to use in operations + balances[msg.sender] = FHE.sub(balances[msg.sender], amount); + balances[to] = FHE.add(balances[to], amount); +} +``` + +**InputVerifier.sol checks:** +- ZK proof is valid (cryptographic verification) +- Ciphertext matches proof +- Public inputs are correct +- Proof hasn't been used before (replay protection) + +**If invalid:** Transaction reverts +**If valid:** Ciphertext registered, handle returned + +### Step 3: Ciphertext Registration + +**On successful verification:** + +1. **Generate handle**: `handle = hash(ciphertext, nonce)` +2. **Register in CiphertextCommits**: Store commitment to ciphertext +3. **Return handle to contract**: Contract receives `euint32` handle +4. **Contract proceeds**: Can now use handle in FHE operations + +## Example: Confidential Token Transfer + +```solidity +contract ConfidentialToken { + mapping(address => euint32) private balances; + + function transfer( + address to, + bytes calldata encryptedAmount, + bytes calldata proof + ) external { + // Verify input and get handle + euint32 amount = FHE.asEuint32(encryptedAmount, proof); + + // Perform transfer using verified input + euint32 senderBalance = balances[msg.sender]; + euint32 recipientBalance = balances[to]; + + balances[msg.sender] = FHE.sub(senderBalance, amount); + balances[to] = FHE.add(recipientBalance, amount); + + // Note: No need to check senderBalance >= amount on-chain + // The FHE operations handle this confidentially + } +} +``` + +**Security guarantee:** +- User cannot submit arbitrary/malformed ciphertexts +- Value is proven to be valid without revealing it +- Prevents attacks like "ciphertext of negative value" + +## Input Types & Constraints + +Different encrypted types support different constraints: + +### Range Proofs + +**euint32 with range constraint:** +```javascript +// Prove value is in range [0, 10000] +const proof = await fhevmClient.generateProof( + ciphertext, + plaintext, + { min: 0, max: 10000 } +); +``` + +### Boolean Proofs + +**ebool (true/false):** +```javascript +// Prove ciphertext encrypts exactly 0 or 1 +const proof = await fhevmClient.generateBoolProof(ciphertext, plaintext); +``` + +### Multiple Inputs + +**Batch verification:** +```javascript +// Submit multiple encrypted values with single proof +const proof = await fhevmClient.generateBatchProof([ct1, ct2, ct3], [pt1, pt2, pt3]); +``` + +## Verification Locations + +FHEVM has two input verification points: + +### Host Chain (InputVerifier.sol) + +- **Single-chain deployments**: Primary verification point +- **Local verification**: Fast, low-latency +- **Per-chain state**: Each chain maintains its own verified inputs + +### Gateway Chain (InputVerification.sol) + +- **Multi-chain deployments**: Central verification point +- **Cross-chain verification**: Verified inputs usable on multiple hosts +- **Coordinated state**: Gateway tracks verified inputs across all hosts + +> **Note**: Most deployments use Host's InputVerifier for simplicity. Gateway's InputVerification is for advanced multi-chain scenarios. + +## Security Properties + +### Soundness +- Invalid ciphertexts cannot pass verification +- User cannot cheat constraints (e.g., claim negative value is positive) + +### Zero-Knowledge +- Proof reveals nothing about plaintext +- Observer learns only that constraints are satisfied + +### Replay Protection +- Each proof can only be used once +- Prevents replaying valid proofs from other users + +## Performance Characteristics + +**Client-side (user's device):** +- Proof generation: ~500ms - 2s (depends on constraint complexity) +- Uses WASM/WebAssembly in browser + +**On-chain verification:** +- Gas cost: ~100k - 300k gas per proof +- Verification time: <1s (within block time) + +## Areas for Deeper Documentation + +**[TODO: ZK proof system details]** - Explain the specific zero-knowledge proof scheme used (Groth16, PLONK, etc.), trusted setup requirements, and security parameters. + +**[TODO: Constraint types and composition]** - Document all available constraint types, how to compose multiple constraints, and performance trade-offs. + +**[TODO: Client SDK usage]** - Complete guide to fhevm-client SDK for generating proofs, encryption parameters, and error handling. + +**[TODO: Proof batching optimization]** - Strategies for batching multiple input proofs to reduce gas costs. + +**[TODO: Replay protection mechanism]** - Detailed implementation of nonce tracking and proof uniqueness enforcement. + +--- + +**Related:** +- [Host Contracts](../components/host-contracts.md) - InputVerifier.sol implementation +- [Gateway Contracts](../components/gateway-contracts.md) - InputVerification.sol for multi-chain +- [Solidity Library](../components/library-solidity.md) - FHE.asEuint32() and type conversion diff --git a/docs/codebase/src/workflows/symbolic-execution.md b/docs/codebase/src/workflows/symbolic-execution.md new file mode 100644 index 0000000000..7578eaea23 --- /dev/null +++ b/docs/codebase/src/workflows/symbolic-execution.md @@ -0,0 +1,122 @@ +# Symbolic Execution Pattern + +## Overview + +The symbolic execution pattern is the foundational workflow that enables FHEVM to provide fast on-chain FHE operations. Instead of performing expensive FHE computation on-chain, contracts generate deterministic "handles" that reference off-chain ciphertexts. + +## The Pattern + +When a smart contract calls an FHE operation like `FHE.add(a, b)`: + +### On-Chain (Fast - milliseconds) + +1. **Validate inputs**: `FHEVMExecutor` checks that handles `a` and `b` are valid +2. **Generate deterministic handle**: `handle_c = hash(handle_a, handle_b, "add", counter)` +3. **Emit event**: Log operation details for off-chain coprocessor +4. **Return immediately**: Transaction completes, returning `handle_c` + +### Off-Chain (Async - seconds to minutes) + +5. **Listen for event**: Coprocessor's host-listener detects the ADD event +6. **Load ciphertexts**: Retrieve actual encrypted data for `a` and `b` +7. **Compute**: Execute `c = TFHE.add(a, b)` using TFHE-rs library +8. **Store ciphertext**: Save resulting ciphertext `c` +9. **Commit**: Submit ciphertext commitment to `CiphertextCommits` contract + +## Example Flow + +```solidity +// Smart contract code +euint32 balance = balances[user]; +euint32 amount = FHE.asEuint32(encryptedAmount); +euint32 newBalance = FHE.add(balance, amount); // <-- Symbolic execution +balances[user] = newBalance; +``` + +**What actually happens:** + +``` +T=0ms: Contract calls FHE.add(handle_balance, handle_amount) +T=1ms: FHEVMExecutor generates handle_newBalance deterministically +T=2ms: Event emitted: AddOp(handle_balance, handle_amount, handle_newBalance) +T=3ms: Transaction completes ✓ (gas: ~50k) + Contract state updated: balances[user] = handle_newBalance + +[Time passes...] + +T=30s: Coprocessor picks up AddOp event +T=31s: Loads ciphertext_balance and ciphertext_amount from database +T=45s: Computes ciphertext_newBalance = TFHE.add(ciphertext_balance, ciphertext_amount) +T=46s: Stores ciphertext_newBalance in database +T=50s: Submits commitment to CiphertextCommits contract ✓ +``` + +## Key Characteristics + +### Deterministic Handle Generation + +Handles are generated using a cryptographic hash of: +- Input handles +- Operation type +- Global counter (ensures uniqueness) + +This ensures: +- Same inputs + operation → same output handle +- Handles are collision-resistant +- No randomness required (fully deterministic) + +### Eventual Consistency + +- **Immediate consistency**: On-chain state (handles) is immediately consistent +- **Eventual consistency**: Off-chain ciphertexts become available later +- **Subsequent operations**: Can proceed with handles before ciphertexts are ready +- **Chain of operations**: Multiple operations can queue up before first completes + +### Gas Efficiency + +Symbolic execution is extremely gas-efficient: +- Handle generation: ~50k gas +- No expensive crypto on-chain +- Comparable to normal EVM operations + +Contrast with actual FHE: +- TFHE.add() on 32-bit integers: ~500ms CPU time +- Cannot be done in EVM's 15-second block time + +## Supported Operations + +All FHE operations follow this pattern: + +**Arithmetic:** add, sub, mul, div, rem, min, max +**Comparison:** eq, ne, lt, le, gt, ge +**Bitwise:** and, or, xor, not, shl, shr, rotl, rotr +**Special:** select (ternary operator) + +## Error Handling + +**On-chain validation:** +- Invalid handles → revert +- Type mismatches → revert +- HCU limit exceeded → revert + +**Off-chain failures:** +- Coprocessor crash → retry mechanism +- Computation error → alert + retry +- Never affects on-chain state (already committed) + +## Areas for Deeper Documentation + +**[TODO: Handle generation algorithm]** - Detailed cryptographic specification of how handles are generated, including hash function choice and collision resistance proof. + +**[TODO: Event format specification]** - Complete schema for FHE operation events, including all fields and encoding details. + +**[TODO: Ciphertext commitment scheme]** - How coprocessors commit results to chain and verification mechanism. + +**[TODO: Chain of operations optimization]** - How multiple dependent operations are optimized when queued together. + +--- + +**Related:** +- [Host Contracts](../components/host-contracts.md) - FHEVMExecutor implementation +- [Coprocessor](../components/coprocessor.md) - Off-chain FHE computation +- [Key Concepts](../key-concepts.md) - Understanding handles and symbolic execution