Update Version

---
description: Update the Aztec version across the entire repo, update contract and TS code, and run tests. Usage: /update-version <new-version-tag>
---

# Update Aztec Version

Update all Aztec version references, sync the MCP server, update contract and TypeScript code for API changes, and run tests.

**Version argument:** $ARGUMENTS

## Workflow

### Step 1: Determine the new version

- If a version argument is provided, use it directly (strip leading `v` if present for npm versions, keep `v` prefix for git tags)
- If no version argument, ask the user to provide one

The version has two forms:
- **npm version** (no `v` prefix): e.g. `4.1.0-devnet.1` — used in `package.json`, config JSONs, README install command, and `CLAUDE.md`
- **git tag** (with `v` prefix): e.g. `v4.1.0-devnet.1` — used in `Nargo.toml` aztec dependency tag and for MCP sync

### Step 2: Sync MCP server to new version

Call `aztec_sync_repos` with the new version tag (with `v` prefix) and `force: true`:

aztec_sync_repos({ version: "v", force: true })

Then call `aztec_status()` to verify the sync succeeded. This gives the MCP server access to the new version's source code and docs — essential for the later steps.

### Step 3: Read current files

Read these files to understand current state:
- `Nargo.toml`
- `package.json`
- `config/local-network.json`
- `config/devnet.json`
- `README.md`
- `CLAUDE.md`

### Step 4: Update all version references

Use the Edit tool to update each file. Be precise — only change version strings, nothing else.

**1. `Nargo.toml`** — Update the aztec dependency tag:
```toml
aztec = { git = "https://github.com/AztecProtocol/aztec-nr/", tag = "v<VERSION>", directory = "aztec" }

2. package.json — Update ALL @aztec/* dependency versions to the new npm version (no v prefix). Do NOT change non-aztec dependencies.

3. config/local-network.json — Update settings.version to the new npm version.

4. config/devnet.json — Update settings.version to the new npm version.

5. README.md — Update the install command version in the Getting Started section:

export VERSION=<NEW_VERSION>
curl -fsSL "https://install.aztec.network/${VERSION}" | VERSION="${VERSION}" bash -s

6. CLAUDE.md — Update the **Aztec version: ...** line to reflect the new version.

Step 5: Verify version references

After all edits, grep the repo for the OLD version string to check for any missed references:

grep -r "<OLD_VERSION>" --include="*.toml" --include="*.json" --include="*.md" .

Report any remaining occurrences (excluding node_modules, target, .git).

Step 6: Upgrade the Aztec CLI

Run aztec-up install <VERSION> (npm version, no v prefix) to upgrade the local aztec toolchain (CLI, nargo, bb, etc.) to match the new version:

aztec-up install <VERSION>

Verify with aztec --version.

Step 6b: Install dependencies

Run yarn install to pull new @aztec/* package versions and update yarn.lock.

Step 7: Research API changes in the new version

Use the MCP tools (now synced to the new version) to research what changed. This is critical — the Aztec API frequently changes between versions.

7a. Search for breaking changes in Noir contract APIs:

Use aztec_search_code to look up current signatures and patterns for:

• Contract macros: #[aztec], #[storage], #[note], #[external], #[initializer], #[only_self]
• Storage types: Map, Owned, PrivateSet, PublicMutable
• Note system: NoteGetterOptions, note delivery via MessageDelivery
• Test environment: TestEnvironment, derive_storage_slot_in_map
• Oracle functions: debug_log_format
• Core traits: Serialize, Deserialize, Packable, ToField

7b. Search for breaking changes in TypeScript APIs:

Use aztec_search_code and aztec_search_docs to look up current patterns for:

• Wallet setup: EmbeddedWallet, createAztecNodeClient
• Account management: AccountManager, GrumpkinScalar, Schnorr accounts
• Fee payment: SponsoredFeePaymentMethod, SponsoredFPCContract
• Contract interaction: .simulate(), .send(), ContractDeployer
• Protocol contracts: getCanonicalFeeJuice, SPONSORED_FPC_SALT
• Types: Fr, AztecAddress, TxStatus, GasSettings

Step 8: Update Noir contract files

Based on the API research from Step 7, update the contract source files as needed. Read each file first, then apply changes.

Files to check and update:

• src/main.nr — Main contract (imports, macros, storage declarations, function signatures, note handling, message delivery)
• src/race.nr — Race struct (trait implementations, serialization)
• src/game_round_note.nr — GameRoundNote (note macro, trait implementations)
• src/test/utils.nr — Test setup helper (TestEnvironment API)
• src/test/helpers.nr — Test helpers (TestEnvironment API)
• src/test/pod_racing.nr — TXE unit tests (test API, storage slot derivation)

Common breaking changes to watch for:

• Import path changes (e.g. aztec::protocol::address vs aztec::address)
• Macro attribute changes or new required attributes
• Storage type API changes (constructor, read/write methods)
• Note trait requirements or macro changes
• TestEnvironment method signature changes
• Trait rename/restructure (Packable, Serialize, etc.)

Step 9: Compile the contract

Run yarn compile to compile the Noir contract with the new Aztec version.

If compilation fails, read the error messages carefully and fix the contract code. Use aztec_search_code and aztec_search_docs to look up correct patterns for the new version. Iterate until compilation succeeds.

Then run yarn codegen to regenerate the TypeScript artifacts from the compiled contract.

Step 10: Update TypeScript files

Based on the API research from Step 7 and any changes revealed by yarn codegen, update TypeScript files as needed.

Utility files (update first — other files depend on these):

• `