AztecProtocol · critesjosh · Mar 3, 2026 · Mar 3, 2026
diff --git a/bootstrap.sh b/bootstrap.sh
@@ -637,7 +637,7 @@ case "$cmd" in
   "ci-docs")
     export CI=1
     export USE_TEST_CACHE=1
-    ./bootstrap.sh
+    BOOTSTRAP_TO=yarn-project ./bootstrap.sh
     docs/bootstrap.sh ci
     ;;
   "ci-barretenberg-debug")

diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
@@ -110,6 +110,9 @@ Default content
 - `static/img/` - Static images and assets
 - `static/aztec-nr-api/` - Auto-generated Aztec.nr API documentation (HTML)
 - `static/typescript-api/` - Auto-generated TypeScript API documentation (markdown)
+- `examples/` - Code examples (Noir circuits, Noir contracts, Solidity, TypeScript)
+- `examples/ts/` - TypeScript aztec.js examples with `docker-compose.yml` for CI execution
+- `examples/ts/aztecjs_runner/` - Runner script that executes examples against a live network
 - `scripts/` - Build and utility scripts
 - `scripts/typescript_api_generation/` - TypeScript API doc generation scripts and config
 
@@ -142,6 +145,23 @@ Uses Docusaurus multi-instance versioning with separate version tracks:
 - Preprocessing macros (`#include_code`, `#release_version`, conditionals, etc.) only work in source folders, not in versioned copies
 - Create new versions with: `yarn docusaurus docs:version:<instance-id> <version>`
 
+### Code Examples Pipeline
+
+The `examples/` directory contains runnable code examples that are included in documentation via `#include_code` markers. The examples pipeline has two stages:
+
+**Validation (type-checking)**: `examples/bootstrap.sh` compiles Noir circuits, Noir contracts, Solidity, and type-checks TypeScript examples. This runs on every PR.
+
+**Execution (runtime testing)**: TypeScript examples in `examples/ts/` are executed against a live Aztec network via Docker Compose. The `examples/ts/docker-compose.yml` spins up Anvil (L1 fork), an Aztec local network, and a runner service that executes the examples.
+
+- **CI**: `docs/bootstrap.sh ci` calls `examples/bootstrap.sh execute`, which uses `run_compose_test` from `ci3/`
+- **Local**: Start a sandbox manually, then run `examples/ts/aztecjs_runner/run.sh`
+- **`AZTEC_NODE_URL`**: All example `index.ts` files and `run.sh` use this env var (defaults to `http://localhost:8080`). In Docker Compose, it points to `http://local-network:8080`.
+
+When adding new TypeScript examples:
+1. Create a directory under `examples/ts/` with `index.ts`, `config.yaml`, and empty `yarn.lock`
+2. Use `process.env.AZTEC_NODE_URL ?? "http://localhost:8080"` for the node URL
+3. Add the example to the list in `examples/ts/aztecjs_runner/run.sh` if it should be executed at runtime
+
 ## Documentation Review Standards
 
 ## Primary Review Objectives
@@ -329,5 +349,5 @@ Approved external documentation sources:
 - Suggest improvements even if they go beyond pure editing
 - When making changes to documentation processes or tooling, remember to check and update READMEs, project documentation (like this file), and code comments
 
-Last updated: 2026-02-04
-Version: 1.4
+Last updated: 2026-02-23
+Version: 1.5
diff --git a/...per_versioned_docs/version-v4.0.0-devnet.2-patch.1/docs/aztec-js/how_to_test.md b/...per_versioned_docs/version-v4.0.0-devnet.2-patch.1/docs/aztec-js/how_to_test.md
@@ -17,21 +17,22 @@ This guide covers how to test Aztec smart contracts by connecting to a local net
 
 Connect to your local Aztec network and create an embedded wallet:
 
-```typescript title="setup" showLineNumbers
-const logger = createLogger("e2e:token");
+```typescript title="connect_to_network" showLineNumbers
+import { createAztecNodeClient, waitForNode } from "@aztec/aztec.js/node";
+import { EmbeddedWallet } from "@aztec/wallets/embedded";
+import { getInitialTestAccountsData } from "@aztec/accounts/testing";
 
-// We create PXE client connected to the local network URL
-const node = createAztecNodeClient(AZTEC_NODE_URL);
-// Wait for local network to be ready
-await waitForNode(node, logger);
-const wallet = await TestWallet.create(node);
+const nodeUrl = process.env.AZTEC_NODE_URL ?? "http://localhost:8080";
+const node = createAztecNodeClient(nodeUrl);
 
-const nodeInfo = await node.getNodeInfo();
+// Wait for the network to be ready
+await waitForNode(node);
 
-logger.info(format("Aztec Local Network Info ", nodeInfo));
+// Create an EmbeddedWallet connected to the node
+const wallet = await EmbeddedWallet.create(node, { ephemeral: true });
 ```
 
-> <sup><sub><a href="https://github.com/AztecProtocol/aztec-packages/blob/v4.0.0-devnet.2-patch.1/yarn-project/end-to-end/src/composed/e2e_local_network_example.test.ts#L37-L50" target="_blank" rel="noopener noreferrer">Source code: yarn-project/end-to-end/src/composed/e2e_local_network_example.test.ts#L37-L50</a></sub></sup>
+> <sup><sub><a href="https://github.com/AztecProtocol/aztec-packages/blob/v4.0.0-devnet.2-patch.1/docs/examples/ts/aztecjs_connection/index.ts#L1-L14" target="_blank" rel="noopener noreferrer">Source code: docs/examples/ts/aztecjs_connection/index.ts#L1-L14</a></sub></sup>
 
 The `EmbeddedWallet` manages accounts, tracks deployed contracts, and handles transaction proving. It connects to the Aztec node which provides access to both the Private eXecution Environment (PXE) and the network.
 

diff --git a/docs/docs-developers/docs/aztec-js/how_to_read_data.md b/docs/docs-developers/docs/aztec-js/how_to_read_data.md
@@ -22,7 +22,7 @@ The `from` option specifies which address context to use for the simulation. Thi
 
 ### Basic simulation
 
-#include_code simulate_function yarn-project/end-to-end/src/composed/docs_examples.test.ts typescript
+#include_code simulate_function docs/examples/ts/aztecjs_connection/index.ts typescript
 
 ### Handling return values
 

diff --git a/docs/docs-developers/docs/aztec-js/how_to_test.md b/docs/docs-developers/docs/aztec-js/how_to_test.md
@@ -17,7 +17,7 @@ This guide covers how to test Aztec smart contracts by connecting to a local net
 
 Connect to your local Aztec network and create an embedded wallet:
 
-#include_code setup yarn-project/end-to-end/src/composed/e2e_local_network_example.test.ts typescript
+#include_code connect_to_network /docs/examples/ts/aztecjs_connection/index.ts typescript
 
 The `EmbeddedWallet` manages accounts, tracks deployed contracts, and handles transaction proving. It connects to the Aztec node which provides access to both the Private eXecution Environment (PXE) and the network.
 
@@ -53,7 +53,7 @@ const contract = await TokenContract.deploy(
 
 Use `.simulate()` to read contract state without creating a transaction:
 
-#include_code simulate_function yarn-project/end-to-end/src/composed/docs_examples.test.ts typescript
+#include_code simulate_function docs/examples/ts/aztecjs_connection/index.ts typescript
 
 Simulations are free (no gas cost) and return the function's result directly. Use them for:
 

diff --git a/docs/docs-developers/docs/foundational-topics/call_types.md b/docs/docs-developers/docs/foundational-topics/call_types.md
@@ -3,7 +3,7 @@ title: Call Types
 sidebar_position: 6
 tags: [calls, contracts, execution]
 description: Understand the different types of contract calls in Aztec, including private and public execution modes, and how they compare to Ethereum's call types.
-references: ["noir-projects/noir-contracts/contracts/app/auth_contract/src/main.nr", "noir-projects/noir-contracts/contracts/app/crowdfunding_contract/src/main.nr", "noir-projects/noir-contracts/contracts/app/lending_contract/src/main.nr", "noir-projects/noir-contracts/contracts/fees/fpc_contract/src/main.nr", "noir-projects/noir-contracts/contracts/protocol/router_contract/src/main.nr", "noir-projects/noir-contracts/contracts/protocol/router_contract/src/utils.nr", "yarn-project/end-to-end/src/composed/docs_examples.test.ts", "yarn-project/end-to-end/src/e2e_card_game.test.ts", "yarn-project/end-to-end/src/e2e_crowdfunding_and_claim.test.ts"]
+references: ["noir-projects/noir-contracts/contracts/app/auth_contract/src/main.nr", "noir-projects/noir-contracts/contracts/app/crowdfunding_contract/src/main.nr", "noir-projects/noir-contracts/contracts/app/lending_contract/src/main.nr", "noir-projects/noir-contracts/contracts/fees/fpc_contract/src/main.nr", "noir-projects/noir-contracts/contracts/protocol/router_contract/src/main.nr", "noir-projects/noir-contracts/contracts/protocol/router_contract/src/utils.nr", "docs/examples/ts/aztecjs_connection/index.ts", "yarn-project/end-to-end/src/e2e_card_game.test.ts", "yarn-project/end-to-end/src/e2e_crowdfunding_and_claim.test.ts"]
 ---
 
 ## What is a Call
@@ -197,7 +197,7 @@ There are two main ways to execute an Aztec contract function using the `aztec.j
 
 This is used to get a result out of an execution, either private or public. It creates no transaction and spends no gas. The mental model is fairly close to that of [`eth_call`](#eth_call), in that it can be used to call any type of function, simulate its execution and get a result out of it. `simulate` is also the only way to run [utility functions](#utility).
 
-#include_code simulate_function yarn-project/end-to-end/src/composed/docs_examples.test.ts typescript
+#include_code simulate_function docs/examples/ts/aztecjs_connection/index.ts typescript
 
 :::warning
 No correctness is guaranteed on the result of `simulate`! Correct execution is entirely optional and left up to the client that handles this request.

@@ -77,6 +77,12 @@ function validate-ts {
   (cd ts && ./bootstrap.sh "$@")
 }
 
+function execute-examples {
+  echo_header "Executing TypeScript documentation examples"
+  local COMPOSE_DIR="$REPO_ROOT/docs/examples/ts"
+  run_compose_test "docs_examples" "docs-examples" "$COMPOSE_DIR"
+}
+
 ##############################################################################
 # CI failure handling - send Slack notifications instead of blocking the build
 ##############################################################################
@@ -204,6 +210,7 @@ case "$cmd" in
     run_step "Compile (Noir contracts)" compile
     run_step "Compile (Solidity)" compile-solidity
     run_step "TypeScript validation" validate-ts
+    run_step "Execute examples" execute-examples
 
     if [[ ${#FAILED_STEPS[@]} -gt 0 ]]; then
       send_failure_slack_message
@@ -220,6 +227,9 @@ case "$cmd" in
   compile-solidity)
     compile-solidity
     ;;
+  execute)
+    execute-examples
+    ;;
   *)
     default_cmd_handler "$@"
     ;;

@@ -0,0 +1,129 @@
+# TypeScript Documentation Examples
+
+This directory contains TypeScript examples used in the Aztec documentation. Each example is a self-contained project that demonstrates specific Aztec.js functionality.
+
+## Directory Structure
+
+Each example directory contains:
+- `index.ts` - The example code with `docs:start:` and `docs:end:` markers for inclusion in documentation
+- `config.yaml` - Specifies dependencies and any custom contract artifacts needed
+- `yarn.lock` - Empty file to prevent yarn from using parent monorepo's yarn.lock
+
+## Validation: Type Checking
+
+The `bootstrap.sh` script validates all examples by:
+
+1. Reading `config.yaml` to determine dependencies and custom contracts
+2. Running codegen for any custom contracts specified (from `docs/target/`)
+3. Installing linked `@aztec/*` dependencies from `yarn-project/`
+4. Running `tsc --noEmit` to type-check the example
+
+Run validation for all examples:
+```bash
+./bootstrap.sh
+```
+
+Run validation for specific example(s):
+```bash
+./bootstrap.sh aztecjs_connection aztecjs_advanced
+```
+
+## Execution: Test Runner
+
+The `aztecjs_runner/run.sh` script executes examples against a live local Aztec network to verify they work correctly.
+
+### CI Execution (Docker Compose)
+
+In CI, examples run via `docker-compose.yml` which spins up an Anvil fork, a local Aztec network, and runs the examples automatically. This is triggered by `docs/examples/bootstrap.sh execute` (called from `docs/bootstrap.sh ci`).
+
+```bash
+# Run via bootstrap (recommended for CI)
+cd docs/examples && ./bootstrap.sh execute
+
+# Or invoke docker-compose directly
+cd docs/examples/ts && run_compose_test docs_examples docs-examples .
+```
+
+### Local Execution
+
+For local development, start the sandbox manually and run examples directly.
+
+#### Prerequisites
+
+- Local Aztec network running (default: `localhost:8080`)
+- Built yarn-project packages
+
+#### Usage
+
+Run all examples:
+```bash
+cd aztecjs_runner
+./run.sh
+```
+
+Run specific example(s):
+```bash
+./run.sh connection           # aztecjs_connection
+./run.sh getting_started      # aztecjs_getting_started
+./run.sh advanced authwit     # multiple examples
+```
+
+#### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AZTEC_NODE_URL` | URL of the Aztec node to connect to | `http://localhost:8080` |
+
+The `AZTEC_NODE_URL` env var is used by both the runner script and the example `index.ts` files. In Docker Compose, it is set to `http://local-network:8080` to point at the compose network's Aztec node.
+
+### Currently Tested Examples
+
+| Example | Description |
+|---------|-------------|
+| `aztecjs_connection` | Basic network connection, account setup, token deployment |
+| `aztecjs_getting_started` | Complete getting started tutorial flow |
+| `aztecjs_advanced` | NO_WAIT transactions, BatchCall, sponsored FPC, events |
+| `aztecjs_authwit` | Authentication witnesses for delegated actions |
+| `aztecjs_testing` | Test patterns: minting, transfers, revert testing |
+
+### Examples Not Executed (Type-Checked Only)
+
+These examples require additional infrastructure or custom contracts with verification keys:
+
+| Example | Reason |
+|---------|--------|
+| `bob_token_contract` | Custom contract requires verification keys |
+| `token_bridge` | Requires L1 contracts and bridge infrastructure |
+| `recursive_verification` | Requires prover and verification key generation |
+
+## Adding New Examples
+
+1. Create a new directory with your example name
+2. Add `index.ts` with your example code
+3. Add `config.yaml` specifying dependencies:
+
+```yaml
+# For examples using pre-built contracts from @aztec/noir-contracts.js
+contracts: []
+
+dependencies:
+  - "@aztec/aztec.js"
+  - "@aztec/accounts"
+  - "@aztec/test-wallet"
+  - "@aztec/noir-contracts.js"
+```
+
+4. Create empty `yarn.lock` file
+5. Run `./bootstrap.sh your_example_name` to validate
+6. If the example can run against a live network, add it to `aztecjs_runner/run.sh`
+
+## File Management
+
+The validation and runner scripts generate temporary files during execution. These are cleaned up automatically, but if you need to manually clean:
+
+```bash
+# In each example directory
+rm -rf node_modules .yarn artifacts package.json tsconfig.json .yarnrc.yml
+rm -f .editorconfig .gitattributes .gitignore README.md codegenCache.json
+> yarn.lock  # Keep empty
+```
@@ -16,9 +16,9 @@ import { getPublicEvents } from "@aztec/aztec.js/events";
 import { BlockNumber } from "@aztec/aztec.js/fields";
 
 // Setup: connect to network
-const node = createAztecNodeClient("http://localhost:8080");
+const node = createAztecNodeClient(process.env.AZTEC_NODE_URL ?? "http://localhost:8080");
 await waitForNode(node);
-const wallet = await EmbeddedWallet.create(node);
+const wallet = await EmbeddedWallet.create(node, { ephemeral: true });
 
 const testAccounts = await getInitialTestAccountsData();
 const [aliceAddress, bobAddress] = await Promise.all(
@@ -126,6 +126,10 @@ await token.methods
   .mint_to_public(aliceAddress, 10000n)
   .send({ from: aliceAddress });
 
+await token.methods
+  .mint_to_private(aliceAddress, 10000n)
+  .send({ from: aliceAddress });
+
 // docs:start:no_wait_deploy
 // Use NO_WAIT to get the transaction hash immediately and track deployment
 const txHash = await TokenContract.deploy(

@@ -6,9 +6,11 @@ import { Fr } from "@aztec/aztec.js/fields";
 import { SetPublicAuthwitContractInteraction } from "@aztec/aztec.js/authorization";
 
 // Setup: connect to network and deploy a token contract
-const node = createAztecNodeClient("http://localhost:8080");
+const node = createAztecNodeClient(
+  process.env.AZTEC_NODE_URL ?? "http://localhost:8080",
+);
 await waitForNode(node);
-const wallet = await EmbeddedWallet.create(node);
+const wallet = await EmbeddedWallet.create(node, { ephemeral: true });
 
 const testAccounts = await getInitialTestAccountsData();
 const [aliceAddress, bobAddress] = await Promise.all(
@@ -59,7 +61,13 @@ const privateWitness = await wallet.createAuthWit(aliceAddress, {
 });
 
 // Bob executes the transfer, providing the authwit
-await privateAction.send({ from: bobAddress, authWitnesses: [privateWitness] });
+// additionalScopes lets the PXE access Alice's private state
+// during authwit verification
+await privateAction.send({
+  from: bobAddress,
+  authWitnesses: [privateWitness],
+  additionalScopes: [aliceAddress],
+});
 // docs:end:private_authwit
 
 // docs:start:public_authwit

@@ -13,3 +13,4 @@ dependencies:
   - "@aztec/wallets"
   - "@aztec/noir-contracts.js"
   - "@aztec/stdlib"
+  - "@aztec/ethereum"