Release Network Docs

Workflow

Step 1: Query Network Info and Detect Release Type

Fetch node info from the provided RPC URL:

curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"method":"node_getNodeInfo"}' <RPC_URL> | jq .result

Parse the response to extract:

• nodeVersion (the version string, e.g. 4.1.2 or 4.1.0-rc.2)
• L1 contract addresses from l1ContractAddresses: registry, rollup, inbox, outbox, fee juice, staking asset, fee juice portal, fee asset handler, coin issuer, reward distributor, governance proposer, governance, slash factory
• L2 protocol contract addresses from protocolContractAddresses: instance registry, class registry, multi-call entrypoint, fee juice
• rollupVersion
• l1ChainId

Detect release type from the version string:

• Contains mainnet or matches a plain semver like 4.1.2 → release type is mainnet
• Contains testnet or rc → release type is testnet
• Contains devnet → abort: network docs do not support devnet. Direct the user to use /release-docs instead.
• If unclear, ask the user to confirm the release type (must be mainnet or testnet)

Store all values for use in subsequent steps.

Step 2: Verify Git Tag and Checkout

The version from Step 1 tells us which git tag the docs should be built from. The operator docs source in docs/docs-operate/ must reflect the code at the release tag, not whatever happens to be on next.

git fetch origin
git tag -l "v<nodeVersion>"

• If the tag exists and is already checked out, continue.
• If the tag exists but is not checked out: git checkout v<nodeVersion>
• Abort if the tag doesn't exist — the release hasn't been tagged yet.

Pre-release workflow

If the user provides a target version that differs from the nodeVersion returned by the RPC (e.g. the network is still running 4.1.3 but the user wants to prepare docs for 4.2.0), this is a pre-release docs preparation. Ask the user to confirm the target version, then use that version instead of nodeVersion throughout the remaining steps. The git tag for the target version must still exist. Contract addresses from the RPC reflect the current network state (the old version); they are still valid if the upgrade reuses the same contracts, but ask the user to confirm whether any addresses will change at upgrade time.

Step 3: Identify and Resolve Missing Contract Addresses

The networks.md L1 table includes contracts that are not returned by node_getNodeInfo. Resolve these addresses in three tiers:

Tier 1: Query on-chain from known contracts

The Rollup and Registry addresses are already known from the RPC response. Use them to query additional addresses on L1. Determine the L1 RPC from the chain ID: 1 → Ethereum mainnet, 11155111 → Sepolia.

First check whether the RPC response already includes gseAddress in l1ContractAddresses — newer node versions return it directly. If present, use it and skip the on-chain query for GSE.

# GSE (Governance Staking Escrow) — from Rollup (skip if already in RPC response)
cast call <ROLLUP_ADDRESS> "getGSE()(address)" --rpc-url <L1_RPC>

# Slasher — from Rollup
cast call <ROLLUP_ADDRESS> "getSlasher()(address)" --rpc-url <L1_RPC>

# Governance — from Registry
cast call <REGISTRY_ADDRESS> "getGovernance()(address)" --rpc-url <L1_RPC>

Tier 2: From deployment output (if available)

These addresses are stored internally in contracts with no public getter. They can be obtained from the Forge deployment script output (l1-contracts/script/deploy/DeployAztecL1Contracts.s.sol prints JSON with all addresses). Ask the user if they have deployment output.

• Reward Booster (stored in Rollup's RewardLib storage, no getter)
• Tally Slashing Proposer (deployed alongside Slasher, no getter)
• Staking Registry

Tier 3: Manual / confirm unchanged

These periphery contracts have no on-chain getter. Ask the user to provide new addresses or confirm that the existing values in networks.md are still correct.

• Honk Verifier
• Register New Rollup Version Payload
• Slash Payload Cloneable

Present a summary table showing: which addresses came from RPC, which were queried on-chain, which came from deployment output, and which are unchanged. Get user confirmation before proceeding.

Step 4: Update Network Info and Contract Addresses

File: docs/docs/networks.md

Update the column matching the release type (Alpha (Mainnet) or Testnet) in each table:

• Network Technical Information table: update the version, rollup version. Update the RPC endpoint only if the user provides a new one (the argument RPC URL may be temporary or internal). Keep bootnodes and block explorer links unless the user requests changes.

• L1 Contract Addresses table: update all addresses from the RPC response, on-chain queries, and any additional addresses provided by the user.

  • Mainnet: use https://etherscan.io/address/0xADDR link format
  • Testnet: use https://sepolia.etherscan.io/address/0xADDR link format
  • For contracts that are not deployed on this network, use N/A

• L2 Contract Addresses table: update if any canonical protocol contract addresses changed (check the protocolContractAddresses from the RPC response). SponsoredFPC is always "Not deployed" on mainnet and testnet.

Also grep for any old addresses that may appear elsewhere in the docs:

grep -r "<old_address>" docs/

Step 5: Review Operator Docs Content (Optional)

Ask the user if any content changes are needed in docs/docs-operate/:

• New or changed configuration options, environment variables, or CLI flags
• Updated setup instructions or prerequisites
• New or modified troubleshooting entries
• Operator changelog updates (if not handled by /updating-changelog)

If the user has content changes, apply them to the source files in docs/docs-operate/. If no content changes are needed, skip to Step 5b.

Step 5b: Regenerate Node API Reference Docs

Regenerate the Node JSON-RPC API reference documentation. This script parses the TypeScript interface definitions and Zod schemas in yarn-project/stdlib/src/interfaces/ to produce a complete markdown reference for the node_ and nodeAdmin_ RPC methods.

Prerequisite: yarn-project must be built (cd yarn-project && yarn && yarn build). This is the only heavy build dependency for this skill and is only needed for this step. If the node API has not changed since the last release, you can skip this step.

cd docs
yarn generate:node-api-reference

This updates docs/docs-operate/operators/reference/node-api-reference.md.

The file is auto-generated — do not hand-edit it. When cutting network versioned docs (Step 7), the generated content is included in the snapshot automatically.

Step 6: Build and Validate

Set the environment variables matching the release type so the build preprocessor resolves version placeholders correctly in the operator docs:

• Mainnet: MAINNET_TAG=<new_version> RELEASE_TYPE=mainnet
• Testnet: TESTNET_TAG=<new_version> RELEASE_TYPE=testnet

IMPORTANT: COMMIT_TAG must include the v prefix (e.g., v4.1.2). The preprocessor uses this for git tag references and GitHub URLs.

cd docs && <TAG_VAR>=<new_version> RELEASE_TYPE=<release_type> COMMIT_TAG=v<nodeVersion> yarn build

Where <TAG_VAR> is MAINNET_TAG for mainnet or TESTNET_TAG for testnet.

Fix any issues reported by the build:

• Broken redirect targets (from validate_redirect_targets.sh)
• Broken API reference links (from validate_api_ref_links.sh)
• Spellcheck errors

Iterate until the build passes.

Step 7: Read Old Version and Cut Network Versioned Docs

Before cutting, read docs/network_version_config.json and record the current version for this release type. This is the old version that will be cleaned up in Step 8. Save this value — the config will be overwritten next.

cat docs/network_version_config.json

For example, if the config shows "mainnet": "v4.1.2" and you are releasing v4.2.0 for mainnet, the old version is v4.1.2.

Now create a versioned snapshot of the network/operator docs. The version string must always be prefixed with v (e.g. v4.1.2, not 4.1.2).

cd docs
<TAG_VAR>=<new_version> RELEASE_TYPE=<release_type> yarn docusaurus docs:version:network v<new_version>

Then update the version config and reconcile:

scripts/update_docs_versions.sh network <release_type> v<new_version>

Verify the results:

• docs/network_version_config.json has the new version under the correct release type (the old version is no longer mapped to this release type)
• docs/network_versioned_docs/version-v<new_version>/ exists with resolved macros (check that #release_version was replaced with the actual version string and #release_network was replaced with mainnet or testnet)
• docs/network_versioned_sidebars/version-v<new_version>-sidebars.json exists

Note: At this point network_versions.json may still list the old version as an unmapped extra (its directory still exists). This is cleaned up in Step 8.

Step 8: Clean Up Old Network Version

Use the old version recorded at the start of Step 7.

If this is the first release for this release type (no previous version existed in the config), skip this step.

Ask the user for confirmation before deleting. If approved, remove:

• docs/network_versioned_docs/version-<old_version>/
• docs/network_versioned_sidebars/version-<old_version>-sidebars.json

Then re-run the reconciliation script so that network_versions.json drops the old version (its directory no longer exists):

scripts/update_docs_versions.sh network

Verify that both network_version_config.json and network_versions.json no longer reference the old version.

Step 9: Move Changes to next Branch

git stash
git checkout next && git pull origin next
git stash pop

Check for stash conflicts. Then report to the user:

• git status and git diff --stat to show what changed
• List all modified/added/deleted files
• Flag any conflicts or unexpected changes
• Let the user know the changes are ready to be committed and a PR can be opened

Key Points

• Mainnet and testnet only: This skill does not support devnet or nightly releases. Network operator docs only have mainnet and testnet versions. If devnet is detected, abort and direct the user to /release-docs.
• Tag must be checked out: The operator docs source in docs/docs-operate/ must reflect the release tag, not next. Always checkout the tag before building and cutting versioned docs.
• Always query the network first: The RPC response is the source of truth for version and L1/L2 contract addresses.
• Some addresses are not in the RPC: Contracts like Staking Registry, Reward Booster, Tally Slashing Proposer, and others must be queried on-chain, obtained from deployment output, or confirmed unchanged by the user.
• Mostly lightweight: This skill does not require aztec CLI or nargo. The only heavy dependency is yarn-project build, needed only for regenerating the node API reference (Step 5b) — skip that step if the node API hasn't changed. Otherwise only yarn (for the docs build), curl/jq (for the RPC query), and cast (for on-chain address queries) are needed.
• Build must pass: Do not cut versioned docs until yarn build succeeds.
• COMMIT_TAG needs v prefix: The preprocessor uses COMMIT_TAG for GitHub URLs and git tag references. Omitting the v will break links in versioned docs.
• User confirmation required: Ask before deleting old versioned docs and before making content changes to operator docs.
• Changes land on next: All changes are stashed and moved to the next branch at the end, ready for a PR.
• Network version config only: This skill modifies network_version_config.json and network_versions.json. It does not touch developer_version_config.json or developer_versions.json.