Merge pull request #251 from AztecProtocol/josh/add-testnet-docs-to-testnet

Add testnet documentation and branch model

Author: critesjosh

CLAUDE.md

@@ -47,25 +47,34 @@ NODE_NO_WARNINGS=1 node --experimental-vm-modules $(yarn bin jest) --no-cache --
 
 ## Deployment & Scripts
 
-All scripts support `::devnet` suffix for devnet targeting (sets `AZTEC_ENV=devnet`):
+All scripts support `::devnet` and `::testnet` suffixes for remote network targeting:
 
 ```bash
 yarn deploy               # Deploy contract to local network
 yarn deploy::devnet       # Deploy contract to devnet
+yarn deploy::testnet      # Deploy contract to testnet
 yarn deploy-account       # Deploy a Schnorr account
 yarn multiple-wallet      # Deploy from one wallet, interact from another
 yarn profile              # Profile a transaction deployment
 yarn read-logs            # Demo utility function for client-side debug logging
 yarn read-logs::devnet    # Same on devnet
+yarn read-logs::testnet   # Same on testnet
 ```
 
 ## Environment Configuration
 
-- `AZTEC_ENV` variable selects config: `local-network` (default) or `devnet`
-- Config files: `config/local-network.json`, `config/devnet.json`
+- `AZTEC_ENV` variable selects config: `local-network` (default), `devnet`, or `testnet`
+- Config files: `config/local-network.json`, `config/devnet.json`, `config/testnet.json`
 - `config/config.ts` — singleton `ConfigManager` loads the appropriate JSON based on `AZTEC_ENV`
 - `.env` stores secrets (SECRET, SIGNING_KEY, SALT, contract keys) — never commit
 
+## Branch Model
+
+- **`next` branch** — default branch; used for local network and devnet development
+- **`testnet` branch** — used for testnet development; may run a different Aztec version
+
+Devnet PRs target `next`. Testnet PRs target `testnet`. Each branch pins its own Aztec version independently.
+
 ## Project Structure
 
 **Contract (Noir):**
@@ -143,9 +152,11 @@ When updating the Aztec version, update all of these locations:
 
 1. `Nargo.toml` — `aztec` dependency tag
 2. `package.json` — all `@aztec/*` dependency versions
-3. `config/local-network.json` and `config/devnet.json` — `settings.version`
+3. `config/local-network.json`, `config/devnet.json`, and/or `config/testnet.json` — `settings.version` (update the configs relevant to the branch you're on)
 4. `README.md` — install command version
 
+> **Note:** The `next` and `testnet` branches may pin different Aztec versions. Only update the config files relevant to the branch.
+
 ## ONBOARDING.md Maintenance
 
 `ONBOARDING.md` is **generated** — do not edit it directly. Edit `docs/ONBOARDING.src.md` instead, then rebuild:

README.md

@@ -16,9 +16,16 @@ You can find the **Pod Racing Game contract** in `./src/main.nr`. A simple integ
 
 The Pod Racing contract is a two-player competitive game where players allocate points across 5 tracks over multiple rounds. The game demonstrates Aztec's private state capabilities - round choices remain private until players reveal their final scores.
 
-## Devnet
+## Devnet & Testnet
 
-This repo connects to a locally running Aztec local network by default, but can be configured to connect to the devnet by specifying `AZTEC_ENV=devnet` in a `.env` file or by prefixing a command e.g. `AZTEC_ENV=devnet yarn deploy`.
+This repo connects to a locally running Aztec local network by default, but can be configured to connect to remote networks:
+
+- **Devnet**: `AZTEC_ENV=devnet` — development network on the `next` branch
+- **Testnet**: `AZTEC_ENV=testnet` — test network on the `testnet` branch
+
+Set the variable in a `.env` file or prefix a command, e.g. `AZTEC_ENV=devnet yarn deploy`.
+
+> **Branch model:** Devnet code lives on the `next` branch. Testnet code lives on the `testnet` branch. Each branch may run a different Aztec version.
 
 <div align="center">
 
@@ -55,6 +62,7 @@ This project uses JSON configuration files to manage environment-specific settin
 
 - `config/local-network.json` - Configuration for local network development
 - `config/devnet.json` - Configuration for devnet deployment
+- `config/testnet.json` - Configuration for testnet deployment
 
 The system automatically loads the appropriate configuration file based on the `AZTEC_ENV` environment variable. If `AZTEC_ENV` is not set, it defaults to `local-network`.
 
@@ -89,6 +97,21 @@ yarn interaction-existing-contract::devnet  # Interact with devnet contracts
 
 The `::devnet` suffix automatically sets `AZTEC_ENV=devnet`, loading configuration from `config/devnet.json`.
 
+### Running on Testnet
+
+Similarly, all scripts support a `::testnet` suffix:
+
+```bash
+yarn deploy::testnet              # Deploy to testnet
+yarn test::testnet                # Run tests on testnet
+yarn deploy-account::testnet      # Deploy account to testnet
+yarn interaction-existing-contract::testnet  # Interact with testnet contracts
+```
+
+The `::testnet` suffix sets `AZTEC_ENV=testnet`, loading configuration from `config/testnet.json`.
+
+> **Note:** Testnet code should be developed and merged into the `testnet` branch, not `next`. The `testnet` branch may use a different Aztec version than the `next` (devnet) branch.
+
 ---
 
 ## 📦 **Install Packages**