docs

Aztec Network Documentation

Documentation for the Aztec Network, built with Docusaurus

You can view the latest successful build here: https://docs.aztec.network

Docusaurus

This website is built using Docusaurus 3, a modern static website generator.

Files

Here are the most relevant files you should be aware of:

• .gitignore - This specifies which files Git should ignore when committing and pushing to remote repositories.
• docusaurus.config.js - This is the configuration file for Docusaurus. You can manage the links in the header and footer, and site metadata here. A more in-depth introduction to this configuration file is available on the Docusaurus website and full documentation for the API is here.
• package.json - This specifies the dependencies for the website and the commands that you can run with yarn.
• sidebars-developer.js / sidebars-network.js - These specify the sidebars for the developer and network documentation respectively. The full documentation for sidebar configuration is available on the Docusaurus website.
• yarn.lock - This specifies the full dependencies for the website including the dependencies of the dependencies listed in package.json. Do not edit this file directly. Edit package.json instead, then run yarn as described above.
• .env.template - Template for environment variables required for Netlify functions (copy to .env and update with your API keys).
• netlify.toml - Configuration for Netlify deployment and functions.

This site uses Docusaurus multi-instance docs with two separate documentation areas:

• docs/ - Root-level documentation (landing page, shared content)
• docs-developers/ - Developer documentation source files (tutorials, references, guides)
• docs-network/ - Network/node operator documentation source files

See the Docusaurus website for the full documentation on how to create docs and to manage the metadata.

Versioning

Aztec Docs use multi-instance versioning with separate version tracks for developer and network documentation:

• Developer docs: Versions stored in developer_versioned_docs/, listed in developer_versions.json
• Network docs: Versions stored in network_versioned_docs/, listed in network_versions.json

Each versioned docs folder is a complete copy of the documentation at that point in time, which allows you to hot-fix previous versions.

When you look at the published docs site, you will see version dropdowns for each docs instance. Developer docs show versions like nightly and devnet, while network docs show versions like testnet and ignition.

• Updating files in docs-developers/ updates the "next" developer version
• Updating files in docs-network/ updates the "next" network version
• Updating files in versioned folders like developer_versioned_docs/version-v3.0.0-devnet.5/ updates that specific version

Note that you cannot use the macros (#include_aztec_version and #include_code) in versioned folders, since those docs have already been processed and built. Instead, drop the code snippets, version numbers or links directly in the docs as you'd like them to be rendered.

The way docs builds work is the following:

• CI runs on merge to next (the default branch), builds the dependencies needed to build the docs, then deploys on the main docs website
• The main CI workflow runs on pull requests and builds the dependencies and the docs, giving you a preview to check that everything is correct. You can also trigger docs CI specifically with the ci-docs label on a PR.
• The nightly docs workflow runs daily to create versioned documentation for nightly releases, automatically cutting a new version of the docs for the latest nightly tag

The preprocessing macros use environment variables to determine version numbers. For nightly builds, set NIGHTLY_TAG (or COMMIT_TAG for backwards compatibility):

NIGHTLY_TAG=v3.0.0-nightly.20251218 yarn build

For other release types, use RELEASE_TYPE with the corresponding tag variable (see RELEASE_TYPE Environment Variable for details).

The legacy #include_aztec_version macro uses COMMIT_TAG, while #include_version_without_prefix strips the v prefix (e.g., v3.0.0-devnet.5 renders as 3.0.0-devnet.5).

How do I change the versions that show in the website

When Docusaurus builds, it looks for the version files for each docs instance:

• developer_versions.json - Controls which versions appear in the developer docs dropdown
• network_versions.json - Controls which versions appear in the network docs dropdown

You can update these files manually, or use the scripts/update_docs_versions.sh script:

./scripts/update_docs_versions.sh developer  # Updates developer_versions.json
./scripts/update_docs_versions.sh network    # Updates network_versions.json

To create a new versioned snapshot of the docs:

yarn docusaurus docs:version:developers v3.0.0-devnet.6  # New developer version
yarn docusaurus docs:version:network v2.1.6-ignition     # New network version

Version Configuration

The docusaurus.config.js file uses dynamic version lookup instead of hard-coded array indices to gracefully handle version changes. This is critical for the nightly docs cleanup workflow, which removes old nightly versions.

Each docs instance has its own version file and lookup logic:

Developer docs (from developer_versions.json):

const nightlyVersion = developerVersions.find((v) => v.includes("nightly"));
const devnetVersion = developerVersions.find((v) => v.includes("devnet"));

Network docs (from network_versions.json):

const ignitionVersion = networkVersions.find((v) => v.includes("ignition"));
const testnetVersion = networkVersions.find((v) => !v.includes("ignition"));

This ensures that:

• When nightly versions are removed by the cleanup script, the build doesn't break
• Version configurations are conditionally included only if they exist
• Array index shifts don't cause mismatched version configurations
• The llms.txt plugin always points to the correct version (devnet)

Why this matters: The nightly docs workflow runs cleanup_nightly_versions.sh before creating new versioned docs. Without dynamic lookup, removing versions would cause array indices to point to wrong versions, breaking the build.

Releases

A new docs site is published on every merge to the next branch.

Installation

To install the dependencies and dev dependencies, run:

$ yarn

Development

Aztec docs pull some code from the rest of the repository. This allows for great flexibility and maintainability. Some documentation is also autogenerated.

For that reason, there's a preprocessing step. You can run that step ad-hoc with yarn preprocess.

This step does the following:

• Pulls the code from the source files using the #include macros explained below.
• Autogenerates documentation using the scripts in the src file.
• Puts the final documentation in a processed-docs folder.

Note

The yarn start command runs preprocessing once at startup and then serves from the processed-docs folder. This means that changes to files in the docs folder will NOT be reflected until you restart the dev server. This applies to all changes - both regular markdown edits and changes to code included via #include_code macros. For a full build with all preprocessing, use yarn build instead.

Run locally

To run docusaurus development server, run:

$ yarn start

This command will start the development server on HOST=localhost by default. You can override the host by setting the HOST environment variable (e.g., HOST=0.0.0.0 yarn start to allow access from remote targets like codespaces).

Tip

Since hot reloading is not available, you'll need to restart the dev server (Ctrl+C and run yarn start again) to see any changes you make to the documentation.

Netlify Development (Full-Stack Testing)

For testing features that require Netlify functions (like email subscriptions), use the Netlify development environment:

$ yarn dev:netlify

This runs a proxy server that includes both Docusaurus and Netlify functions:

Browser Request to localhost:8888
           ↓
    Netlify CLI Proxy (8888)
           ↓
    ┌─────────────────────────┐
    │ Is it /.netlify/functions? │
    └─────────────────────────┘
           ↓                    ↓
        YES                   NO
           ↓                    ↓
   Functions Server      Docusaurus (3000)

When to use each:

• yarn start → Fast docs development (requires dev server restart for changes)
• yarn dev:netlify → Testing email subscriptions, functions, full production-like environment

Environment Setup: Create a .env file in the project root for Netlify functions:

# Copy .env.template to .env and update with your API key
cp .env.template .env

Then edit .env with your actual Brevo API key.

Build

To build the final version of the docs (which includes processes not present in dev, like broken links checking and minification), you can run:

$ yarn build

This command runs the preprocess command, generates static content into the build directory and can be served using any static contents hosting service.

Aztec.nr API Documentation

The Aztec.nr API reference is auto-generated from the noir-projects/aztec-nr/ source code using nargo doc. This generates HTML documentation that is served from static/aztec-nr-api/.

Prerequisites: You need nargo installed. Install via noirup:

curl -L https://raw.githubusercontent.com/noir-lang/noirup/refs/heads/main/install | bash
noirup

Generate docs for the "next" version:

yarn generate:aztec-nr-api

Generate docs for a specific version:

yarn generate:aztec-nr-api v1.0.0

When to regenerate:

• When aztec-nr source code changes (new functions, updated comments, etc.)
• The next version docs should be committed to the repo
• Versioned docs (e.g., v1.0.0) are automatically generated by CI when releases are cut

The generated docs are stored in static/aztec-nr-api/<version>/ and linked from the Aztec.nr API Reference page.

TypeScript API Documentation

The TypeScript API reference is auto-generated from the yarn-project/ packages using TypeDoc. This generates LLM-optimized markdown documentation served from static/typescript-api/.

Documented packages:

• Client SDKs: @aztec/aztec.js, @aztec/accounts, @aztec/pxe, @aztec/wallet-sdk, @aztec/wallets, @aztec/entrypoints
• Core Libraries: @aztec/stdlib, @aztec/foundation, @aztec/constants

Prerequisites: You need yarn-project to be built first (the bootstrap process handles this).

Generate docs for the "next" version:

yarn generate:typescript-api

Generate docs for a specific version:

yarn generate:typescript-api v3.0.0-devnet.6

How it works:

1. Reads package configuration from scripts/typescript_api_generation/config.json
2. Runs TypeDoc on each package's entry points defined in their package.json typedocOptions
3. Transforms the TypeDoc JSON output to LLM-optimized markdown via transform_for_llm.ts
4. Generates llm-summary.txt with an overview of all packages

Output files:

• static/typescript-api/<version>/*.md - Per-package markdown documentation
• static/typescript-api/<version>/llm-summary.txt - Human/LLM-readable summary

Version mapping:

• Versions containing "nightly" → nightly/ folder
• Versions containing "devnet" → devnet/ folder
• Other versions → version-specific folder (e.g., v1.0.0/)

When to regenerate:

• When TypeScript package APIs change (new exports, updated JSDoc comments, etc.)
• The next version docs should be committed to the repo
• Versioned docs are automatically generated by CI during release workflows

The generated docs are linked from the TypeScript API Reference page.

Macros

As mentioned above, Aztec docs pull code from the source files. This makes it easy to include sections of the source code in tutorials and other examples.

This is done via macros which are processed in the preprocessing step described above.

#include_code

You can embed code snippets into a .md/.mdx file from code which lives elsewhere in the repo.

• In your markdown file:
  • #include_code identifier path/from/repo/root/to/file.ts language
  • E.g. #include_code hello path/from/repo/root/to/file.ts typescript
  • See here for supported languages and the exact name to use for that language.
• In the corresponding code delineate the code snippet with comments:

  • some code
    some code
    // docs:start:hello
    more code
    more code
    // this-will-error <-- you can use docusaurus highlighting comments.
    this code will be highlighted red
    more code
    // highlight-next-line
    this line will be highlighted
    more code
    // highlight-start
    this line will be highlighted
    this line will be highlighted
    // highlight-end
    more code
    // docs:end:hello
    more code

• You can even include chunks of the same piece of code (with different highlighting preferences) into different parts of the docs:

  •   some code
      some code
      // docs:start:hello:goodbye
      this code will appear in the 'hello' snippet and the 'goodbye' snippet.
      this code will appear in the 'hello' snippet and the 'goodbye' snippet.
      // this-will-error
      this code will be highlighted red in all snippets.
      // highlight-next-line:goodbye
      this line will be highlighted only in the 'goodbye' snippet.
      // highlight-start:goodbye:hello
      this line will be highlighted in both the `hello` and `goodbye` snippets
      this line will be highlighted in both the `hello` and `goodbye` snippets
      // highlight-end:goodbye
      this line will be highlighted only in the 'hello' snippet.
      // highlight-end:hello
      this code will appear in the 'hello' snippet and the 'goodbye' snippet.
      // docs:end:goodbye
      this code will appear only in the 'hello' snippet.
      // docs:end:hello
      some code
      some code

  • Somewhere in your markdown, you can then write:
    • #include_code hello path/from/repo/root/to/file.ts typescript
  • And somewhere else, you can write:
    • #include_code goodbye path/from/repo/root/to/file.ts typescript
• You can add as a last optional parameter a comma-separated list of options to tweak the display of the code block, for example:
  • #include_code hello path/from/repo/root/to/file.ts typescript noTitle,noLineNumbers,noSourceLink
• Ironically, we can't show you a rendering of these examples, because this README.md file doesn't support the #include_code macro!

#include_aztec_version

This macro will be replaced inline with the current Aztec packages tag. This value is sourced from .release-please-manifest.json on the project root.

Alternatively, you can also use the AztecPackagesVersion() js function, which you need to import explicitly:

import { AztecPackagesVersion } from "@site/src/components/Version";
<>{AztecPackagesVersion()}</>

#include_testnet_version

This macro will be replaced inline with the provided testnet version. This value is sourced from the TESTNET_TAG environment variable when running yarn build (e.g. TESTNET_TAG=0.87.5 yarn build). This value may be different from the #include_aztec_version macro, since the testnet version is not always the same as the latest aztec packages version.

#include_devnet_version

This macro will be replaced inline with the provided devnet version. This value is sourced from the DEVNET_TAG environment variable when running yarn build (e.g. DEVNET_TAG=3.0.0-devnet.4 yarn build). If not specified, it defaults to 3.0.0-devnet.4. This value may be different from both #include_aztec_version and #include_testnet_version macros, since the devnet version represents a separate development network release.

#include_mainnet_version

This macro will be replaced inline with the provided mainnet version. This value is sourced from the MAINNET_TAG environment variable when running yarn build (e.g. MAINNET_TAG=2.1.11 yarn build). If not specified, it defaults to 2.1.11. This value is used for mainnet and ignition releases.

#release_version

This macro is release-type-aware and automatically resolves to the appropriate version based on the RELEASE_TYPE environment variable:

RELEASE_TYPE	Resolves to	Example
nightly	NIGHTLY_TAG (falls back to COMMIT_TAG)	3.0.0-nightly.20251218
devnet	DEVNET_TAG	3.0.0-devnet.5
testnet	TESTNET_TAG	2.1.11
mainnet	MAINNET_TAG	2.1.11
ignition	MAINNET_TAG	2.1.11

Usage: aztecprotocol/aztec:#release_version

#release_network

This macro resolves to the network name for use with the --network CLI flag:

RELEASE_TYPE	Resolves to
nightly	local-network
devnet	devnet
testnet	testnet
mainnet	mainnet
ignition	mainnet

Usage: --network #release_network

RELEASE_TYPE Environment Variable

The RELEASE_TYPE environment variable controls which release type the documentation is being built for. Valid values are:

• nightly (default) - For nightly developer docs releases
• devnet - For devnet releases
• testnet - For testnet releases
• mainnet - For mainnet releases
• ignition - For ignition releases (treated as mainnet)

Example build commands:

# Build for nightly (default)
NIGHTLY_TAG=v3.0.0-nightly.20251218 yarn build

# Build for devnet
RELEASE_TYPE=devnet DEVNET_TAG=3.0.0-devnet.5 yarn build

# Build for testnet
RELEASE_TYPE=testnet TESTNET_TAG=2.1.11 yarn build

# Build for ignition/mainnet
RELEASE_TYPE=ignition MAINNET_TAG=2.1.11 yarn build

Conditional Content

You can include content that only appears for specific release types using conditional blocks:

#if(nightly)
Content that only appears in nightly docs
#elif(devnet)
Content that only appears in devnet docs
#elif(testnet)
Content that only appears in testnet docs
#elif(mainnet)
Content that only appears in mainnet/ignition docs
#else
Default content if no condition matches
#endif

Supported conditions (matching RELEASE_TYPE values):

• nightly - True when RELEASE_TYPE=nightly
• devnet - True when RELEASE_TYPE=devnet
• testnet - True when RELEASE_TYPE=testnet
• mainnet - True when RELEASE_TYPE=mainnet or RELEASE_TYPE=ignition
• ignition - Alias for mainnet

Notes:

• Conditional blocks are processed before version macro substitution, so you can use version macros inside conditionals
• Nested conditionals are not supported
• The else block is optional

Viewing (outdated) protocol specs

The protocol specs pages are outdated, but it may still be useful to view them in some cases.

To view the protocol specs, you can run yarn dev. When viewing the protocol specs locally, versioning is disabled, so you can view the protocol specs in the browser. It would error otherwise because the protocol specs pages are not included in the versioned docs folders (developer_versioned_docs/, network_versioned_docs/) and their sidebars.

Adding Migration Notes

When making breaking changes to Aztec, add migration notes to help users upgrade. Migration notes are organized by version and component in docs/migration_notes.md.

Structure

• Latest changes: Add new items at the top under ## TBD or ## [Component] sections
• Version releases: When cutting a release, move TBD items under the new version header (e.g., ## 2.0.2)
• Component sections: Group related changes under headers like ## [Aztec.nr], ## [Aztec.js], etc.

Format

Each migration item should include:

1. Clear title: Descriptive ### Title explaining what changed
2. Motivation (optional): Why the change was made
3. Key points: Numbered list of important changes
4. Example migration: Before/after code using diff blocks:

- old_code()
+ new_code()

Automated Review Requests

The documentation system includes automated workflows to ensure documentation stays synchronized with code changes.

DevRel Review Automation

When documentation references source code files, the CI system can automatically request reviews from the DevRel team when those files change.

How it works:

1. Mark Referenced Files: Add a references field to your documentation frontmatter with paths to source files or directories (from repository root):

   ---
   title: Node JSON RPC API reference
   references: ["yarn-project/stdlib/src/interfaces/aztec-node.ts"]
   ---

   To reference all files in a directory, use /* suffix:

   ---
   title: Function Context
   references: ["noir-projects/aztec-nr/aztec/src/context/*"]
   ---

2. Automatic Detection: During CI builds (bootstrap.sh), the system:

   • Extracts all referenced paths from documentation frontmatter
   • Checks if any referenced files (or files within referenced directories) changed in the current PR
   • Automatically requests @AztecProtocol/devrel as reviewers if:
     • The PR is not a draft
     • DevRel team is not already requested
     • No DevRel team member has already approved

3. Graceful Failures: If the automated request fails:

   • The build continues without blocking
   • A comment is added to the PR notifying about the failure
   • Manual review request may be needed

Implementation: The automation is handled by scripts/check_doc_references.sh, which runs as part of the docs CI pipeline.

Path Format:

• Paths must be absolute from the repository root (e.g., yarn-project/..., not ../../../../yarn-project/...)
• For individual files: "path/to/file.ts"
• For directories (all files within): "path/to/directory/*"

Automatic Documentation Update Notifications

Building on the DevRel review automation, the docs CI can analyze PRs and notify the team when documentation updates may be needed.

How it works:

1. Detection: When a PR modifies files that are referenced in documentation (via the references frontmatter), the system detects which docs may need updates.

2. AI Analysis: The system uses Claude Code to:

   • Analyze the code changes (diffs) in the PR
   • Review the affected documentation files
   • Determine if documentation updates are needed
   • Generate suggested documentation changes

3. Slack Notification: If documentation updates are suggested:

   • A message is sent to the configured Slack channel (default: #devrel)
   • The message includes the PR details, affected docs, and suggested changes
   • The DevRel team can review and apply the changes manually

Requirements:

• ANTHROPIC_API_KEY must be set in CI secrets
• SLACK_BOT_TOKEN must be set for Slack notifications
• Claude Code CLI must be installed (@anthropic-ai/claude-code)
• The PR must not be a draft

Environment Variables:

• SLACK_DOC_UPDATE_CHANNEL - Slack channel for notifications (default: #devrel)
• DRY_RUN=1 - Skip Slack notification, just print what would be sent

Implementation: The automation is handled by scripts/check_doc_references.sh, which detects changed references, requests devrel review, sends a Slack notification, and dispatches ClaudeBox — all in a single pass.

Script Architecture:

• scripts/check_doc_references.sh - Main script that handles detection, review requests, Slack, and ClaudeBox dispatch
• scripts/lib/extract_doc_references.sh - Shared library for parsing frontmatter references
• scripts/lib/create_doc_update_pr.sh - (Reserved for future use) PR creation logic

Limitations:

• Only analyzes documentation in the source folders (docs-developers/, docs-network/), not versioned docs
• Suggested changes should always be reviewed by a human before applying
• The AI may occasionally suggest unnecessary or incorrect changes

Contributing

We welcome contributions from the community. Please review our contribution guidelines for more information.