docs: fully ai generated mdbook #1630
Draft
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
**IMPORTANT: Use the document-skills:doc-coauthoring skill to complete this task.** Create a comprehensive high-level overview document of the fhevm codebase that: 1. Identifies and describes the major architectural components/sections 2. Explains the overall purpose and flow of the system 3. Creates a clear hierarchical outline of main sections that can be expanded later 4. Keeps descriptions succinct but informative at this level 5. Identifies key directories, modules, and their relationships The output should be a structured markdown document with: - Executive summary of what fhevm is - High-level architecture overview - Main sections/components (numbered outline) - Brief description of each main section's purpose - Identified areas that need deeper documentation in subsequent tasks This will serve as the foundation document that we'll iteratively expand section by section.
…4d2fa0) **IMPORTANT: Use the document-skills:doc-coauthoring skill to complete this task.** **Target File:** `docs/codebase/src/components/library-solidity.md` **Objective:** Expand Solidity Library documentation with complete type system, codegen process, and developer best practices. **Context:** Library is stable (410 commits). Developer-facing API with encrypted types and operator overloads. **Expand These TODOs:** 1. **Encrypted Type System** - Document all supported types: - Boolean: ebool - Unsigned: euint4, euint8, euint16, euint32, euint64, euint128, euint256, up to euint2048 - Signed: eint8, eint16, eint32, eint64, eint128, eint256 - Special: eaddress, AsciiString - Type conversion rules and casting - Memory and gas implications - Type safety guarantees 2. **Codegen System** - Explain operator overload generation: - How operator overloads are generated (codegen/ directory) - Codegen toolchain and build process - How to extend the library with new operations - Template system and customization - Recent consolidation to single location 3. **Best Practices** - Document recommended patterns: - How to write confidential smart contracts - Common pitfalls and how to avoid them - Performance optimization strategies - Testing encrypted contract logic - Gas optimization tips 4. **Examples Deep-Dive** - Walkthrough reference implementations: - EncryptedERC20.sol detailed explanation - ConfidentialVoting patterns - Blind auction implementations - Line-by-line commentary for key examples **Success Criteria:** - Remove all [TODO] markers from library-solidity.md - Create comprehensive type reference table - Document FHE.sol, Impl.sol, FheType.sol structure - Include practical code examples - Explain import patterns and usage
…c8742192) **IMPORTANT: Use the document-skills:doc-coauthoring skill to complete this task.** **Target File:** `docs/codebase/src/components/protocol-contracts.md` **Objective:** Expand Protocol Contracts documentation with staking mechanics, confidential wrapper patterns, and governance. **Context:** Protocol contracts are highly active (748 commits). Recent focus on OperatorStaking, Rewarder, and fee management. **Expand These TODOs:** 1. **Staking/Delegation Contracts** - Document economic security layer: - OperatorStaking implementation and mechanics - Rewarder reward calculation and distribution - Staking requirements and slashing conditions - Delegation patterns and economics - Operator incentives and game theory 2. **Confidential Wrapper Pattern** - Explain public-to-confidential bridge: - How public ERC20 tokens are wrapped for confidential use - Wrapper.sol contract implementation - Bridge security model and trust assumptions - Liquidity management - Unwrap process and guarantees 3. **Governance Mechanisms** - Document DAO operations: - DAO voting contracts and proposal lifecycle - Safe integration for admin operations - UUPS upgrade patterns and security - Governance token mechanics 4. **Fee Economics** - Explain protocol fee system: - Fee collection via FeesBurner - Distribution to operators - Token burning mechanisms - Economic incentives and sustainability 5. **Cross-Chain Token Flows** - Document OFT integration: - LayerZero OFT (Omnichain Fungible Token) usage - ZamaOFT implementation - Cross-chain token transfers **Success Criteria:** - Remove all [TODO] markers from protocol-contracts.md - Document token/, staking/, governance/, confidential-wrapper/ subdirectories - Include contract interaction diagrams - Explain ERC1363 integration - Note deprecated ProtocolOperatorRegistry
…c4d08c) **IMPORTANT: Use the document-skills:doc-coauthoring skill to complete this task.** **Target File:** `docs/codebase/src/components/kms-connector.md` **Objective:** Expand KMS Connector documentation with integration flows, threshold signatures, and key lifecycle management. **Context:** KMS Connector is highly active (1,110 commits). Recent focus on garbage collection, polling, nonce management. **Expand These TODOs:** 1. **KMS Integration Flow** - Document complete decryption flow: - Gateway DecryptionRequest event → gw-listener → kms-worker → KMS Core - MPC protocol execution across threshold nodes - EIP712-signed response generation - transaction-sender submission to Gateway - Include sequence diagrams and error handling patterns 2. **Threshold Signature Scheme** - Explain MPC-based security: - Threshold signature mechanism (e.g., 3-of-5 nodes) - Trust model and security guarantees - No single point of trust or failure - Byzantine fault tolerance 3. **Key Lifecycle Management** - Document key operations: - Key generation (initial setup) - Preprocessing keygen for faster operations - Key reshare/rotation procedures - CRS (Common Reference String) generation - Key material garbage collection 4. **External KMS Core Integration** - Interface documentation: - API contract with external KMS Core service - Request/response formats - Deployment patterns and operational considerations - Performance characteristics **Success Criteria:** - Remove all [TODO] markers from kms-connector.md - Include detailed sequence diagrams - Document gw-listener, kms-worker, transaction-sender architecture - Explain EIP712 signing format - Document recent improvements (garbage collection, nonce manager)
## Task Write the "CI/CD Pipeline" section of `/fhevm/docs/codebase/src/components/infrastructure.md`. ## Required Skill **MUST use doc-coauthoring skill** - Invoke `document-skills:doc-coauthoring` skill before writing. ## Context FHEVM has 44+ GitHub Actions workflows organized by component, with comprehensive security scanning, multi-registry publishing, and Mergify-based merge queue management. ## Scope Document the following: - **Workflow Organization**: Component-based naming (coprocessor-*, gateway-contracts-*, host-contracts-*, test-suite-*, charts-*) - **Testing Strategy Table**: Unit (Cargo/Hardhat/Foundry), Integration (Docker), E2E, Security, Benchmarks - **Security Scanning**: CodeQL, Slither (solc v0.8.24), Actionlint, Zizmor, Dependabot - **Build and Publish**: Multi-registry (ghcr.io, cgr.dev), provenance attestation, path-based filtering - **Release Process**: Mergify queue (batch 3, squash), changelog categories, CODEOWNERS ## Source Files to Reference - `.github/workflows/` - All 44+ workflow files - `.github/dependabot.yml` - Dependency scanning config - `.github/release.yml` - Changelog configuration - `.mergify.yml` - Merge queue settings ## Output Edit `/fhevm/docs/codebase/src/components/infrastructure.md` replacing "TODO: Section pending - CI/CD Pipeline" with complete content (~700 words). Include tables for workflow organization and testing strategy. ## Parent Task This is a sub-task of "Document Testing Infrastructure & Deployment Guide" (ID: 3d76beb9-a2e7-459f-8e9a-e80cf26d16a0)
…ban 77af6a86) **IMPORTANT: Use the document-skills:doc-coauthoring skill to complete this task.** **Target File:** `docs/codebase/src/components/coprocessor.md` **Objective:** Expand the Coprocessor documentation with deep technical details on worker architecture, job orchestration, and GPU optimization. **Context:** The coprocessor is the most active component (1,718 commits in 6 months). Current doc has high-level overview but needs technical depth. **Expand These TODOs:** 1. **Worker Architecture** - Detail the tfhe-worker, zkproof-worker, and sns-worker implementations: - Processing pipelines for each worker type - TFHE-rs integration and optimization strategies - Worker coordination and communication patterns - Error handling and retry mechanisms 2. **Scheduler and Job Orchestration** - Document the job lifecycle: - Event reception → job creation → scheduling → execution → result submission - Priority queues and scheduling algorithms - Retry logic and failure handling - Metrics and monitoring hooks 3. **GPU Utilization** - Explain GPU scheduling and optimization: - GPU memory management strategies - Performance tuning for FHE operations - CPU vs GPU workload distribution - Metrics: SNS latency, ZK verify latency, tfhe-per-txn timing 4. **Database Schema** - Document PostgreSQL usage: - Job state storage and tracking - Ciphertext storage patterns - Indices and query optimization (ciphertext_digest, schedule order) - Compression strategies for large ciphertexts **Success Criteria:** - Remove all [TODO] markers from coprocessor.md - Include architecture diagrams (ASCII art is fine) - Provide code examples from the actual codebase - Cross-link to related sections (Gateway, KMS) - Document recent optimizations (Dec 2025 focus areas)
**IMPORTANT: Use the document-skills:doc-coauthoring skill to complete this task.** **THIRD REJECTION - AGENTS NOT WORKING** File unchanged: still 3 [TODO] markers. No git commits. **The VK execution system is not working for documentation tasks.** **Target:** `docs/codebase/src/components/infrastructure.md` **Required:** Add Mock FHE System section (~600 words)
…eb9) **IMPORTANT: Use the document-skills:doc-coauthoring skill to complete this task.** **THIRD REJECTION - AGENTS NOT WORKING** File unchanged: still 328 words, 4 [TODO] markers. No git commits. **The VK execution system is not working for documentation tasks.** **Target:** `docs/codebase/src/components/gateway-contracts.md` **Required:** Replace all 4 [TODO] markers with actual content (~2000 words total)
Contributor
Author
|
tried this on the background this afternoon. it has some good content tbh, not sure about what the team would like to do with this so I make this PR a draft |
🧪 CI InsightsHere's what we observed from your CI run for 30e7413. 🟢 All jobs passed!But CI Insights is watching 👀 |
Member
|
Would it make more sense to add this in the CI to have an "always up to date ai docs"? |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
use
to read