docs: add 20-page documentation site with 8 diagrams, llms.txt, and CI freshness check#357
Open
Giri-Aayush wants to merge 68 commits intomainfrom
Open
docs: add 20-page documentation site with 8 diagrams, llms.txt, and CI freshness check#357Giri-Aayush wants to merge 68 commits intomainfrom
Giri-Aayush wants to merge 68 commits intomainfrom
Conversation
Initialize a Vocs-powered docs site for aztec-fpc, structured with landing, overview, how-to, SDK, contracts, services, and operations sections. Lives at /website to coexist with the existing /docs folder of engineering reference material. Run with: cd website && bun install && bunx vocs dev
- New /reference section: testnet deployment, wallet discovery spec, asset-model ADR, e2e test matrix, operational metrics - New /how-to/cold-start-flow for bridge builder persona - Reorganize how-to sidebar into Wallet & App Integration + Operator - Add Reference topNav entry, bump version label to v3.0.0 - Content refinements across overview, sdk, services, operations pages
Based on verified audience analysis (Azguard, Obsidion, Shieldswap, Nemi, Substance Labs, TRAIN, Wormhole) and Alpha Mainnet context: - architecture: add persona routing callout (wallet/dApp/bridge roles) - what-is-fpc: fix bridge-builder link → /how-to/cold-start-flow - integrate-wallet: name Azguard + Obsidion as live wallet examples; note AB1 winners - sdk/getting-started: add persona tip block for privacy DEX, wallet, bridge builders - run-operator: callout naming real wallet operators + Alpha Mainnet early-mover context - testnet-deployment: add Alpha Mainnet security advisory warning - info/index.md: full source-file → info-doc traceability graph (all subsystems)
- faucet.mdx, fpc-multi-asset.mdx: contract reference improvements - add-supported-asset.mdx: how-to refinements - index.mdx: landing page updates - docker.mdx: operations updates - topup.mdx: service doc updates - styles.css: style adjustments
- Rewrites index.mdx with Neo-Renaissance design: Newsreader serif italic headlines, Space Grotesk mono labels, full-bleed lime ticker marquee, ghost FPC watermark, film grain overlay, tonal-depth bento grid, persona routing cards — no borders, 0px radius throughout - Updates styles.css with full Renaissance design system (tokens, ticker animation, hero, stats strip, bento, personas, responsive breakpoints) - Aligns Vocs theme with landing page: bg #161312, surface #1e1b1a, accent #C8E600 (readable lime), body font Manrope - Removes top banner; adds Contribute link to topnav - Adds glossary page (Aztec primitives + FPC terms, verified Aztec doc URLs) and wires it into the Reference sidebar
- Replace split topNav/per-path sidebar with a single unified sidebar; all sections (Learn, How-To, SDK, Contracts, Services, Operations, Reference) are now collapsible groups with subsections in one pane. TopNav retains only Contribute link and v3.0.0 version picker. - Fix testnet-deployment.mdx: token name humanUSDC → FpcAcceptedAsset, verified live against /.well-known/fpc.json and /accepted-assets.
- Stats (infinity/1TX/0/2) now render inside the hero above the fold - Stats strip goes transparent, borderless, sits below CTAs with a hairline separator - Removed full-bleed width from .ren-stats (no longer needed outside hero) - Replaced em dash in hero tagline with a period
- Stat numbers: 2rem -> 2.25rem, labels: 0.6875 -> 0.75rem, improved contrast - Stats separator: opacity 0.08 -> 0.12, height 2.25rem -> 2.5rem - Stat gap 0.25rem -> 0.375rem for breathing room - Ghost button border: 0.2 -> 0.35 opacity - Hero bottom padding: 5rem -> 3.5rem (less whitespace after stats) - Stats margin-top: 2.5rem -> 2rem - Section labels: add 3.5rem top margin for clean section spacing
…-is-fpc The diagram showed `fee_entrypoint(quote, authwit, ...)` which implied authwit is a function parameter. It is not — the actual parameters are accepted_asset, authwit_nonce, fj_fee_amount, aa_payment_amount, valid_until, and quote_sig. The authwit (transfer authorization witness) is carried as an execution payload component separate from the function call. Also clarify "the user includes the quote signature" → "the operator's quote signature" to make clear who signed it.
Strip the Vocs docs site and convert all .mdx pages to plain .md files readable directly on GitHub. No build step required. - Convert 28 .mdx files to .md in website/docs/ - Replace Vocs admonitions (:::info, :::tip, etc.) with GitHub alert syntax - Convert JSX landing page to clean markdown - Fix all internal links to relative paths with .md extension - Strip :::code-group and ::::steps wrappers - Move image assets from public/ to assets/ - Remove vocs.config.ts, node_modules, package.json, dist, styles.css
Cross-reference every page against the source-of-truth docs in docs/ (protocol-spec, deployer guide, ops runbooks, ADR, test spec, wallet discovery spec) and rewrite to meet the editorial guide standard. Technical accuracy: - fee_entrypoint 8-step execution matches protocol-spec section 3.4 - Quote preimage fields match spec section 3.2 exactly - Cold-start domain separator 0x46504373 documented - fj_amount == max_gas_cost_no_teardown constraint added - Admin endpoints (operator-balances, sweeps) with request/response formats - Bridge mechanics 4-step flow from spec 5.3 - Auto-claim env vars, configure-token variants, Docker batch registration - Known Limitations (Alpha) section from spec section 9 - Local-network troubleshooting from spec 5.4 Editorial compliance: - Zero em dashes across all 28 files - Zero AI-tell words - All bracket subtitle headings stripped - Imperative voice for action steps - No preamble, first sentence states the point
EmbeddedWallet has three breaking changes in Aztec 4.2.0 that cause FPC transactions to fail at runtime. The working example uses FpcWallet, a compatibility shim from scripts/common/fpc-wallet.ts. - Replace EmbeddedWallet with FpcWallet in both code examples - Add FpcWallet section explaining the three 4.2.0 regressions - Add fj_fee_amount == get_max_gas_cost constraint warning - Fix authwit caller description (FPC contract, not operator) - Add missing return fields and txWaitTimeoutMs parameter - Link to FpcWallet source and full example
Consolidate for GitHub browsability without a sidebar nav. Merged files: - contracts/ (4 files) -> contracts.md - sdk/ (2 files) -> sdk.md - services/ (2 files) -> services.md - overview/what-is-fpc.md -> index.md (with TLDR section) Moved to root: - overview/quick-start.md -> quick-start.md - overview/architecture.md -> architecture.md - overview/security.md -> security.md - overview/quote-system.md -> quote-system.md Removed: - reference/asset-model-adr.md (links now point to docs/spec/ source) Kept as folders (enough files to justify): - how-to/ (4 files) - operations/ (4 files) - reference/ (5 files) All internal links updated and verified.
The manifest schema was fabricated by the rewrite agent and diverged
from the actual deployManifestSchema in contract-deployment/src/manifest.ts.
Fixes:
- network_metadata -> network (correct key name)
- deployer: {address, private_key} -> deployer_address (flat, no keys)
- Remove l1_contract_addresses (come from nodeInfo, not manifest)
- Add status, generated_at, aztec_required_addresses fields
- Add field reference table with types
- Link to manifest.ts source
Every doc page verified against the actual codebase, not reference notes.
Source links added so readers can trace claims to code.
Key fixes found during verification:
- Constructor annotation: #[public] -> #[external("public")]
- get_max_gas_cost_no_teardown -> get_max_gas_cost (function doesn't exist)
- msg_sender.is_none() -> context.maybe_msg_sender().is_none()
- fee_entrypoint execution order corrected to match main.nr
- cold_start_entrypoint missing steps added (set_sender_for_tags, fee assert)
- TokenBridge portal type: AztecAddress -> EthAddress
- TokenBridge amount types: Field -> u128
- Auto secret provider: only tries env+config, not all 4 modes
- Admin endpoints return 503 when disabled, not 404
- ColdStartResult has 5 fields, not 3
- Config: removed phantom env vars that don't exist in source
- Docker: added missing image and service, fixed CI pipeline steps
- Testing: replaced generic descriptions with actual test function names
Source links added to all 20 doc files pointing to relevant .ts and .nr files.
Add three sections to e2e-test-matrix.md that were in the source spec (docs/spec/e2e-test-spec.md) but missing from published docs: - Asset Model and Wiring (accepted_asset vs Fee Juice distinction) - Full Lifecycle Phases (7-step execution sequence) - Local-Network Troubleshooting runbook
…trix - glossary.md: cold-start calls bridge.claim_private(), not claim_public() (verified: contracts/fpc/src/main.nr line 226) - e2e-test-matrix.md: deploy scripts are .sh not .ts (verified: scripts/contract/deploy-fpc-local-mode.sh, deploy-smoke-local.sh)
GitHub renders README.md automatically when browsing a folder. index.md has no special meaning on GitHub, so visitors had no way to know it was the entry point. README.md solves this.
… FPC availability - README.md: replace "Poseidon2 hash" with "compute_inner_authwit_hash" for consistency with contracts.md and quote-system.md - README.md: Sponsored FPC is available on testnet too, not just devnet and local (verified against docs.aztec.network) - e2e-test-matrix.md: add FPC_TEST_TOKEN_MANIFEST env var (user fix)
- Replace generic wallet placeholder with FpcWallet.create() to match the working example (fpc-full-flow.ts line 91) - Add CAUTION block linking to sdk.md FpcWallet section - Remove .send().wait() chain (neither fpc-full-flow.ts nor the deployer guide uses .wait(); the verified pattern is just await .send())
Add website/public/llms.txt and llms-full.txt for AI agent context. Add missing tests-cold-start-validation to README test service table and improve tests-fee-entrypoint-validation description accuracy.
Two remaining Poseidon2 references (lines 36 and 89) replaced for consistency with contracts.md and quote-system.md.
Line 76 and line 293 still said Poseidon2. Replaced with computeInnerAuthWitHash for consistency across all docs.
#cold-start -> #cold-start-quote-cold_start_entrypoint (the heading includes the function name in backticks)
FPC_WALLET_DEPLOY_RETRIES, FPC_WALLET_DEPLOY_RETRY_BACKOFF_MS, and FPC_WALLET_DATA_DIR do not exist in any source code file. They were carried over from the source-of-truth doc (devnet-deployment-how-to.md) but are not consumed by the deploy script or TypeScript CLI.
Quote preimage and Poseidon2 definitions updated for consistency with all other doc pages that use the precise function name.
- Add function-to-file index with exact line numbers for 50+ functions - Add error codes and failure modes section (on-chain reverts, HTTP errors, SDK retries) - Add config key to env var mapping for attestation, topup, and auto-claim - Fix 3 wrong #L anchor links (topup main, secret-provider, glossary) - Rename index.md references to README.md - Add AGENT_PROMPT.md with ready-to-paste prompt for AI assistants - Update README callout to reference AGENT_PROMPT.md - Regenerate llms-full.txt with all updates
- Deduplicate exchange rate formula: canonical in quote-system.md, others link to it - Replace hardcoded testnet addresses with named constants + testnet-deployment.md refs - Add version discrepancy note (node 4.1.0-rc.2 vs SDK 4.2.0-aztecnr-rc.2) - Add support.md with contact info (aayush@nethermind.io, GitHub Discussions) - Add scripts/generate-llms-full.sh for auto-regenerating llms-full.txt with TOC - Add "See also" navigation to add-supported-asset.md and run-operator.md - Add transfer_private_to_private to Token row in contracts.md At a Glance table - Replace truncated addresses in integrate-wallet.md with placeholder variables - Collapse cold-start-flow.md explanation into details block - Add prerequisites tip to sdk.md linking to quick-start.md - Add deployment.md cross-link to docker.md - Break dense README paragraph into numbered list
…ll.txt - Fix Documentation table display text to show docs/specs/ paths (previously showed old docs/ops/ and docs/spec/ names) - Regenerate llms-full.txt via scripts/generate-llms-full.sh to include Mermaid diagrams, rollup_version fix, and all recent changes
Replace the old table pointing to specs/ files with a section-organized table pointing to the new documentation pages. Links to specs are kept in a dedicated Specs row for protocol-level reference.
Remove duplicated content that now lives in docs/: - Token flow ASCII diagrams (now Mermaid in docs/architecture.md) - Full testnet deploy walkthrough (now docs/operations/deployment.md) - SDK integration example (now docs/sdk.md) - Docker build/compose reference (now docs/operations/docker.md) - Environment variable table (now docs/operations/configuration.md) Keep: project intro, agent/developer entry points, quick start (5 commands), documentation table, repo layout, development commands, security notes.
8 legacy files now show a CAUTION banner at the top warning readers that the document may contain outdated function names, wrong defaults, or references to non-existent scripts. Each banner links to docs/README.md as the canonical entry point. The ADR gets a softer NOTE banner since it is a design decision record, not operational documentation.
…t, and docs/README.md
- Document the rate_quote alternative preimage format in quote-system.md (signs rate_num/rate_den instead of concrete amounts, same domain separator, requires a contract fork that verifies rate-based preimages) - Add .github/workflows/docs-freshness.yml CI step that regenerates llms-full.txt and fails if it drifts from the committed version - Regenerate llms-full.txt with updated TOC line numbers
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Addresses CodeQL finding: set explicit `contents: read` permission to limit the GITHUB_TOKEN scope.
…ture in protocol spec
- Lead with value prop, not project name - Add SDK code snippet as the "money shot" (2 methods, full surface) - Add persona routing table (dApp dev, wallet, operator, auditor) - Move AI agent callout to quiet blockquote under Documentation - Add license badge, support section, Nethermind attribution - Remove verbose ASCII diagrams (docs handle that now) - Keep quick start, repo layout, dev commands, security notes
- contracts.md (562 lines): add TOC linking to 6 major sections - services.md (536 lines): add TOC linking to 13 key sections - sdk.md (499 lines): add TOC linking to 9 sections - cold-start-flow.md: move mermaid diagram after the intro paragraph so readers see text first, not raw markup if rendering fails
Versions (Aztec, Bun) are kept inline for usability but each mention now notes that package.json and docker-compose.yaml are authoritative. If the docs drift from the repo files, readers know which to trust.
- docker.md: WARNING on passing secrets via CLI args - testing.md: NOTE on compile-first requirement for contract tests - metrics.md: TIP on critical alerts (topup_readiness_status) - e2e-test-matrix.md: NOTE on test prerequisites - Regenerate llms-full.txt
Giri-Aayush
changed the title
- De-duplicate cold-start flow (sdk.md now references cold-start-flow.md) - De-duplicate quote preimage (contracts.md now references quote-system.md) - De-duplicate quote lifecycle (architecture.md now references quote-system.md) - De-duplicate error handling (integrate-wallet.md now references sdk.md) - Remove "At a Glance" table from contracts.md (duplicate of Contract Map) - Remove "Test Tiering" section from e2e-test-matrix.md - Remove Docker images Source column from docker.md - Extract SDK boilerplate into shared Common Setup section - Trim Aztec.js bridge boilerplate from cold-start-flow.md - Delete docs/support.md (merged into docs/README.md) - Delete docs/info/docs-workflow.md (merged into docs/README.md) - Delete docs/reference/glossary.md (removed by maintainer) - Fix terminology: "gas token" -> "fee token", "gasless" -> "fee-abstracted", "pays gas" -> "pays fees", "gas abstraction" -> "fee abstraction", "protocol's gas layer" -> "pays fees in Fee Juice", "mined" -> "included", "production multi-asset implementation" -> "multi-asset implementation deployed on testnet", "four-layer" -> "four-component" - Remove fluff: filler intros, "This page covers..." sentences, AI-tell words - Regenerate llms-full.txt, update llms.txt and AGENT_PROMPT.md
Giri-Aayush
changed the title
- Remove named teams (Azguard, Obsidion, Shieldswap, etc.) from persona callouts in architecture, cold-start, run-operator, and integrate-wallet pages. Keeps persona descriptions, drops names that will go stale. - Consolidate setup-phase irreversibility warning: canonical explanation stays in security.md, other pages link to it instead of repeating it with different wording. - Regenerate llms-full.txt to reflect all changes.
Nikola flagged that the intro conflated "FPC" (the Aztec primitive) with "Nethermind's aztec-fpc" (one specific implementation). Fixed by: - Rewriting README TLDR to separate the two - Replacing "What is FPC?" with two sections: the Aztec primitive and its design variants (sponsored, private, third-party), then what aztec-fpc specifically is - Adding the cold-start privacy caveat (mint_to_private enqueues a public update_total_supply call) that Aztec's own docs mention - Clarifying aztec-fpc is private, multi-asset, quote-based (previously just "multi-asset", missing the "private" property) - Renaming "What FPC does not do" to "What aztec-fpc does not do" since the spread mechanic is our implementation, not inherent to FPCs - Fixing security.md line 8 to scope "trusted operator model" to aztec-fpc (Sponsored FPCs have different trust assumptions) Regenerated llms-full.txt.
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
Summary
Adds structured documentation for the FPC system: 20 pages, 8 Mermaid diagrams, machine-readable context for AI agents, and a CI freshness check.
Replaces the scattered specs and runbooks in docs/ with a single doc set that routes readers by role (dApp dev, wallet team, operator, auditor) and covers every contract function, service endpoint, SDK method, config key, and error code.
What reviewers need to read
Total diff: 10,375 lines added, 395 deleted across 37 files.
Most of that is auto-generated or legacy. Here is the breakdown:
Start at docs/README.md, it routes to everything else.
Pages
Core (read these first)
SDK, Contracts, Services
How-to, Operations, Reference
8 Mermaid diagrams
All render natively on GitHub, audited against contract source for step ordering:
AI agent context
Root README rewrite
README.md (root) rewritten with side-by-side docs table, persona routing, quick start commands, AI agent TIP callout, and security summary.
Editorial standards
Single-source principle: Each concept is defined once. Other pages reference it instead of duplicating it. Cold-start lives in cold-start-flow.md, quote preimage lives in quote-system.md, error taxonomy lives in sdk.md. Shared SDK setup is extracted into a Common Setup section.
Aztec-native terminology: All 20 pages use correct Aztec terms. Fee Juice (not "gas token"), "pays fees" (not "pays gas"), "fee-abstracted" (not "gasless"), "included in a block" (not "mined"), "fee abstraction" (not "gas abstraction"), "L1 transaction fees" (not "bridge gas"). No Ethereum-borrowed terms that don't apply to Aztec.
No filler: No "This page covers...", no "comprehensive", "robust", "seamlessly", "work together", or similar padding. Every sentence is actionable or informative.
3 files deleted (content merged into docs/README.md):
What is NOT in this PR