create-mn-app 0.3.28 → 0.4.0

package/README.md

@@ -1,12 +1,20 @@
 # create-mn-app
 
-Scaffold Midnight Network applications on Preprod.
+Scaffold a Midnight Network DApp project. One command bootstraps a contract, a local devnet, and the SDK plumbing to deploy and call it. Public testnets are one flag away.
 
 [![npm version](https://img.shields.io/npm/v/create-mn-app.svg)](https://www.npmjs.com/package/create-mn-app)
 [![npm downloads](https://img.shields.io/npm/dw/create-mn-app.svg)](https://www.npmjs.com/package/create-mn-app)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Node.js](https://img.shields.io/node/v/create-mn-app.svg)](https://nodejs.org/)
 
+## Requirements
+
+| Requirement      | Version  | Notes                                                  |
+| ---------------- | -------- | ------------------------------------------------------ |
+| Node.js          | 22+      |                                                        |
+| Docker           | Compose v2 | Runs the local devnet and proof server               |
+| Compact compiler | 0.31.0   | Required for `counter` and `bboard`; the CLI offers to install it for you |
+
 ## Quick Start
 
 ```bash
@@ -15,132 +23,110 @@ cd my-app
 npm run setup
 ```
 
-The `setup` command:
-
-1. Starts proof server via Docker
-2. Compiles the Compact contract
-3. Deploys to Preprod (prompts for faucet funding)
+That's the whole getting-started flow. `setup` boots a local devnet in Docker, compiles the contract, and deploys it. No wallet extension, no faucet, no public-network credentials.
 
-> Fund your wallet at [faucet.preprod.midnight.network](https://faucet.preprod.midnight.network/)
+### What you get
 
-## Why create-mn-app?
+**Bundled local devnet.** The `hello-world` template ships a `docker-compose.yml` that runs node + indexer + proof-server. The dev preset pre-mints NIGHT to a genesis seed, so deploys work the second `setup` finishes — no faucet polling, no testnet flake.
 
-- **Zero Configuration** - Start building immediately
-- **Preprod Ready** - Deploys to Midnight Preprod network
-- **SDK 3.0** - Uses latest Midnight wallet and contract SDKs
-- **One Command Setup** - Single `npm run setup` handles everything
-- **Auto-updates** - Built-in notifier for new versions
-
-## Templates
-
-Templates are organized by category. The interactive flow guides you through category → template selection.
+## Deploy to preview and preprod
 
 ```bash
-npx create-mn-app@latest my-app         # interactive: pick category then template
-npx create-mn-app@latest my-app --list  # list all templates grouped by category
+npm run setup --network preview
 ```
 
-### Contract
-
-| Template | Description |
-| -------- | ----------- |
-| `hello-world` (default) | Basic message storage contract demonstrating state management |
-
 ```bash
-npx create-mn-app@latest my-app
-cd my-app
-npm run setup     # starts proof server, compiles, deploys
-npm run cli       # interact with deployed contract
+npm run setup --network preprod
 ```
 
-### Full DApp
+## Networks
+
+The bundled `hello-world` template runs against three networks. Local devnet is the default.
 
-| Template | Description |
-| -------- | ----------- |
-| `counter` | Increment/decrement app with zkProofs ([source](https://github.com/midnightntwrk/example-counter)) |
-| `bboard` | Multi-user bulletin board with privacy patterns ([source](https://github.com/midnightntwrk/example-bboard)) |
-| `dex` | Decentralized exchange using FungibleToken *(coming soon)* |
-| `midnight-kitties` | NFT-based full stack DApp *(coming soon)* |
+| Network      | Source                                                            | When to use                                              |
+| ------------ | ----------------------------------------------------------------- | -------------------------------------------------------- |
+| `undeployed` | Local devnet from `docker-compose.yml`                            | Default. Iterate fast, no funding, no extension needed.  |
+| `preview`    | Public preview testnet ([faucet](https://faucet.preview.midnight.network/)) | Test against shared infra before a release.              |
+| `preprod`    | Public preprod testnet ([faucet](https://faucet.preprod.midnight.network/)) | Validate against the network closest to mainnet.         |
+
+Switch network on a single command:
 
 ```bash
-npx create-mn-app@latest my-app --template counter
-npx create-mn-app@latest my-app --template bboard
+npm run setup -- --network preview
 ```
 
-Requires Compact compiler — the CLI will check and offer to install it.
+Or set the active network for the project, so subsequent commands don't need the flag:
 
-### Connector
+```bash
+npm run network preview     # active network is now preview
+npm run setup               # uses preview
+npm run cli                 # uses preview
+npm run network             # prints current state
+```
 
-Integration examples and patterns *(coming soon)*.
+On first use of `preview` or `preprod`, the deploy script generates a wallet seed, prints the faucet URL, and polls the wallet balance until funds land. Seeds are stored per-network in `.midnight-state.json` (gitignored) — switch back later and your funded wallet is still there.
 
-## Requirements
 
-| Requirement      | Version | Notes                                              |
-| ---------------- | ------- | -------------------------------------------------- |
-| Node.js          | 22+     | Required for all templates                         |
-| Docker           | Latest  | Runs proof server                                  |
-| Compact Compiler | 0.28.0+ | Counter and Bboard templates (auto-install offered)|
+## Additional Templates
 
-## CLI Options
+Pick a template interactively, or pass `--template`:
 
 ```bash
-npx create-mn-app@latest [project-name] [options]
+npx create-mn-app@latest my-app                    # interactive picker
+npx create-mn-app@latest my-app --template counter # skip the prompts
+npx create-mn-app@latest my-app --list             # show every template
 ```
 
-| Option                    | Description                                          |
-| ------------------------- | ---------------------------------------------------- |
-| `-t, --template <name>`   | Template: `hello-world`, `counter`, `bboard`        |
-| `--list`                  | List all available templates grouped by category     |
-| `-y, --yes`               | Accept all defaults (non-interactive mode)           |
-| `--dry-run`               | Preview what will be created without writing files   |
-| `--from <owner/repo>`     | Create from a custom GitHub repository               |
-| `--use-npm/yarn/pnpm/bun` | Force package manager                               |
-| `--skip-install`          | Skip dependency installation                         |
-| `--skip-git`              | Skip git initialization                              |
-| `--verbose`               | Show detailed output                                 |
-| `-h, --help`              | Show help                                            |
-| `-V, --version`           | Show version                                         |
+**NOTE:** Not all templates support the `--network` flag for switching networks like `hello-world`. Consult each template's README for more information.
 
-### Non-Interactive / CI Mode
+### Contract
 
-Use `-y` or set `CI=true` / `GITHUB_ACTIONS=true` to skip all prompts:
+| Template                | What it is                                                              |
+| ----------------------- | ----------------------------------------------------------------------- |
+| `hello-world` (default) | Bundled. Local devnet + message-storage contract. The fastest path to a working deploy. |
 
-```bash
-npx create-mn-app@latest my-app -y -t counter    # defaults, no prompts
-CI=true npx create-mn-app@latest my-app           # auto-detected in CI
+### Full DApp
 
-npx create-mn-app@latest my-app --dry-run         # preview without writing files
-npx create-mn-app@latest my-app --from user/repo  # clone any GitHub repo
-```
+| Template  | What it is                                                                                                |
+| --------- | --------------------------------------------------------------------------------------------------------- |
+| `counter` | Increment/decrement contract with ZK proofs. Cloned from [`example-counter`](https://github.com/midnightntwrk/example-counter). |
+| `bboard`  | Multi-user bulletin board demonstrating privacy patterns. Cloned from [`example-bboard`](https://github.com/midnightntwrk/example-bboard). |
 
-## Project Structure
+The DApp templates clone an upstream example and configure it for the pinned compiler. They follow the upstream project's setup flow — see the cloned repo's README after scaffolding.
 
+`dex` and `midnight-kitties` are listed as coming-soon in the picker.
+
+## CLI reference
+
+```bash
+npx create-mn-app@latest [project-directory] [options]
 ```
-my-app/
-├── contracts/
-│   └── hello-world.compact    # Compact smart contract
-├── src/
-│   ├── cli.ts                 # Interact with deployed contract
-│   ├── deploy.ts              # Deploy contract to Preprod
-│   └── check-balance.ts       # Check wallet balance
-├── docker-compose.yml         # Proof server config
-├── package.json
-└── deployment.json            # Generated after deploy (contains wallet seed)
-```
+
+| Option                                          | Description                                       |
+| ----------------------------------------------- | ------------------------------------------------- |
+| `-t, --template <name>`                         | `hello-world`, `counter`, `bboard`                |
+| `--list`                                        | List all templates and exit                       |
+| `--from <owner/repo>`                           | Scaffold from any GitHub repository               |
+| `-y, --yes`                                     | Accept defaults; non-interactive                  |
+| `--dry-run`                                     | Print actions without writing files               |
+| `--use-npm` / `--use-yarn` / `--use-pnpm` / `--use-bun` | Force a package manager                   |
+| `--skip-install`                                | Skip dependency install                           |
+| `--skip-git`                                    | Skip `git init`                                   |
+| `--verbose`                                     | Show detailed output                              |
+| `-V, --version`                                 | Print version                                     |
+| `-h, --help`                                    | Print help                                        |
+
+CI mode is auto-detected (`CI=true` or `GITHUB_ACTIONS=true`) and skips prompts. `-y` does the same explicitly.
 
 ## Contributing
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+Issues and pull requests welcome at [github.com/midnightntwrk/create-mn-app](https://github.com/midnightntwrk/create-mn-app).
 
 ## Links
 
 - [Midnight Docs](https://docs.midnight.network)
-- [Discord Community](https://discord.com/invite/midnightnetwork)
-- [GitHub](https://github.com/midnightntwrk/create-mn-app)
+- [Discord](https://discord.com/invite/midnightnetwork)
+- [Preview Faucet](https://faucet.preview.midnight.network/)
 - [Preprod Faucet](https://faucet.preprod.midnight.network/)
 
 ## License

package/dist/utils/templates.js

@@ -60,7 +60,7 @@ exports.templates = [
         repo: "midnightntwrk/example-counter",
         nodeVersion: 22,
         requiresCompactCompiler: true,
-        compactVersion: "0.28.0",
+        compactVersion: "0.31.0",
         projectStructure: [
             "contract/     smart contract (compact)",
             "counter-cli/  cli interface",
@@ -79,7 +79,7 @@ exports.templates = [
             {
                 title: "Proof Server",
                 commands: [
-                    "docker run -d -p 6300:6300 -e PORT=6300 midnightntwrk/proof-server:7.0.0",
+                    "docker run -d -p 6300:6300 -e PORT=6300 midnightntwrk/proof-server:8.0.3",
                 ],
                 note: "runs in background",
             },
@@ -104,7 +104,7 @@ exports.templates = [
         repo: "midnightntwrk/example-bboard",
         nodeVersion: 22,
         requiresCompactCompiler: true,
-        compactVersion: "0.28.0",
+        compactVersion: "0.31.0",
         projectStructure: [
             "contract/     smart contract (compact)",
             "api/          shared api methods",
@@ -128,7 +128,7 @@ exports.templates = [
             {
                 title: "Proof Server",
                 commands: [
-                    "docker run -d -p 6300:6300 -e PORT=6300 midnightntwrk/proof-server:7.0.0",
+                    "docker run -d -p 6300:6300 -e PORT=6300 midnightntwrk/proof-server:8.0.3",
                 ],
                 note: "runs in background",
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-mn-app",
-  "version": "0.3.28",
+  "version": "0.4.0",
   "description": "Create Midnight Network applications with zero configuration",
   "main": "dist/index.js",
   "bin": {

package/templates/hello-world/README.md.template

@@ -1,88 +1,173 @@
 # {{projectName}}
 
-A Midnight Network application created with `create-mn-app`.
+A Midnight Network smart contract scaffolded with create-mn-app.
 
-## Getting Started
+## Quick start
 
-### Prerequisites
+Requirements: Node 22, Docker (with Compose v2), and the Compact compiler at the version pinned in `.compact-version` at the create-mn-app repo root (the version this project was scaffolded against).
 
-- Node.js 22+ installed
-- Docker installed (for proof server)
+```bash
+npm install
+npm run setup
+npm run test:e2e
+```
+
+`npm run setup` runs end-to-end with no prompts:
+
+1. `docker compose up -d --wait` — starts a local Midnight devnet (node, indexer, proof-server) and blocks until all three pass their healthchecks.
+2. `npm run compile` — compiles `contracts/hello-world.compact` to `contracts/managed/hello-world/`.
+3. `npm run deploy` — derives the genesis-seed wallet (NIGHT pre-minted), registers UTXOs for DUST generation, deploys the contract, writes `.midnight-state.json`.
+
+`npm run test:e2e` reconnects to the deployed contract and reads its ledger state. Exits 0 if the contract is live and indexable.
 
-### Quick Start
+## Local devnet
 
-1. **Install dependencies**:
-   ```bash
-   npm install
-   ```
+The project ships its own devnet via `docker-compose.yml`:
 
-2. **Setup and deploy**:
+| Service        | Port | Purpose                                         |
+| -------------- | ---- | ----------------------------------------------- |
+| `node`         | 9944 | Midnight node, `dev` chain preset               |
+| `indexer`      | 8088 | GraphQL indexer for chain state                 |
+| `proof-server` | 6300 | Generates ZK proofs for contract transactions   |
 
-   ```bash
-   npm run setup
-   ```
+State lives in container-managed volumes. Tear everything down with:
 
-   This will:
+```bash
+docker compose down -v
+```
+
+That removes all containers, networks, and volumes. The next `npm run setup` starts from a clean slate.
 
-   - Compile your Compact contract
-   - Deploy contract to Preprod
+## ⚠️ LOCAL DEVNET ONLY
 
-3. **Interact with your contract**:
-   ```bash
-   npm run cli
-   ```
+The deploy script uses a well-known genesis seed (`0000…0001`) so the
+pre-minted NIGHT in the `dev` chain preset is immediately available. **Do
+not use this seed against Preprod, mainnet, or any environment that
+handles real value** — anyone running this devnet has full access to
+funds at this seed.
 
-### Available Scripts
+## Networks
 
-- `npm run setup` - Start proof server, compile contract, and deploy
-- `npm run compile` - Compile Compact contract
-- `npm run deploy` - Deploy contract to Preprod
-- `npm run cli` - Interactive CLI for contract
-- `npm run check-balance` - Check wallet balance
-- `npm run proof-server:start` - Start proof server (Docker)
-- `npm run proof-server:stop` - Stop proof server
-- `npm run clean` - Clean build artifacts
+This DApp supports three networks:
 
-### Project Structure
+| Network | When to use | Default? |
+|---|---|---|
+| `undeployed` | Local devnet bundled in `docker-compose.yml`. Genesis seed is hardcoded; no funding needed. | yes |
+| `preview` | Public preview testnet. Faucet at `https://faucet.preview.midnight.network`. |  |
+| `preprod` | Public preprod testnet. Faucet at `https://faucet.preprod.midnight.network`. |  |
 
+The active network is **sticky**: whichever network you last interacted
+with stays active until you switch. Any command run with `--network <name>`
+also sets that network active for subsequent commands. The default on a
+fresh project is `undeployed` (local devnet).
+
+```sh
+npm run setup -- --network preview   # runs on preview AND makes it active
+npm run cli                          # still uses preview
+npm run check-balance                # still uses preview
 ```
-{{projectName}}/
-├── contracts/
-│   ├── hello-world.compact    # Smart contract source
-│   └── managed/               # Compiled artifacts (after compile)
-├── src/
-│   ├── deploy.ts             # Deployment script
-│   ├── cli.ts                # Interactive CLI
-│   └── check-balance.ts      # Balance checker
-├── docker-compose.yml        # Proof server config
-├── deployment.json           # Deployment info (after deploy)
-└── package.json
+
+You can also switch without running anything else:
+
+```sh
+npm run network preview         # active network is now preview
+npm run network                 # prints current active network
+npm run network undeployed      # switch back to local devnet
 ```
 
-### Getting Preprod Tokens
+### How wallets work across networks
 
-1. Run `npm run deploy` to see your wallet address
-2. Visit [https://faucet.preprod.midnight.network/](https://faucet.preprod.midnight.network/)
-3. Enter your address to receive test tokens (tNight)
+- `undeployed` uses a hardcoded genesis seed. Local devnet pre-funds it.
+- `preview` and `preprod` generate a fresh seed on first use and store it
+  in `.midnight-state.json` (gitignored). The seed survives switching
+  networks — switch back later and your funded wallet returns.
+- **Back up your seed** if you fund a public-network wallet you care
+  about. Open `.midnight-state.json` and copy the relevant
+  `wallets.<network>.seed` value to a safe place.
 
-### Learn More
+### Funding a public-network wallet
 
-- [Midnight Documentation](https://docs.midnight.network)
-- [Compact Language Guide](https://docs.midnight.network/compact)
-- [Tutorial Series](https://docs.midnight.network/tutorials)
+On the first run with `--network preview` (or `preprod`):
 
-## Contract Overview
+1. `setup` will print your wallet address and the faucet URL.
+2. Open the faucet URL, paste the address, request tNIGHT.
+3. `setup` polls the wallet balance every 10 s and continues automatically
+   once funds arrive.
+4. The default poll budget is 10 minutes. Override with
+   `MIDNIGHT_FAUCET_TIMEOUT_MS=1800000` (30 min) for unattended runs.
 
-This project includes a simple "Hello World" contract that:
+If the faucet is slow or the script times out, your seed is preserved.
+Re-run `npm run setup -- --network preview` once the funds land.
 
-- Stores a message on the blockchain
-- Allows reading the current message
-- Demonstrates basic Midnight functionality
+### Environment overrides
 
-The contract uses:
+These env vars override the active network's config (no per-network
+suffix — they apply to whichever network is active for the run):
 
-- **Public ledger state** for the message
-- **Zero-knowledge proofs** for transactions
-- **Privacy-preserving** architecture
+| Variable | Effect |
+|---|---|
+| `MIDNIGHT_WALLET_SEED` | Use this seed instead of generating/persisting one. Useful for CI with a pre-funded wallet. |
+| `MIDNIGHT_INDEXER_URL` | Override the indexer GraphQL URL. |
+| `MIDNIGHT_INDEXER_WS_URL` | Override the indexer WS URL. |
+| `MIDNIGHT_NODE_URL` | Override the node RPC URL. |
+| `MIDNIGHT_FAUCET_URL` | Override the faucet URL printed during setup. |
+| `MIDNIGHT_PROOF_SERVER_URL` | Override the proof server URL — set to a public proof server (e.g. `https://lace-proof-pub.preview.midnight.network`) to skip running one locally. |
+| `MIDNIGHT_FAUCET_TIMEOUT_MS` | Faucet poll budget in milliseconds (default 600000 = 10 min). |
 
-Happy coding! 🌙
+By default all networks use the **local** proof server. Public proof
+servers exist (see the env override above) but the local default keeps
+your witness data on your machine and avoids depending on a remote
+service for the deploy hot path.
+
+### Switching back to local devnet
+
+```sh
+npm run network undeployed     # or: npm run setup -- --network undeployed
+```
+
+Your preview/preprod wallet seeds and deploy addresses stay in
+`.midnight-state.json`. Switch back later, and they're still there.
+
+## Available scripts
+
+| Script                  | Description                                                    |
+| ----------------------- | -------------------------------------------------------------- |
+| `npm run setup`         | One-shot: start devnet, compile, deploy.                       |
+| `npm run compile`       | Compile the Compact contract.                                  |
+| `npm run deploy`        | Deploy the compiled contract (requires devnet up + compiled).  |
+| `npm run cli`           | Interactive CLI to call circuits on the deployed contract.     |
+| `npm run check-balance` | Print the genesis-seed wallet's NIGHT and DUST balances.       |
+| `npm run test:e2e`      | Smoke + read-back check against the deployed contract.         |
+| `npm run clean`         | Remove `contracts/managed/` and `.midnight-state.json`.        |
+| `npm run proof-server:start` / `:stop` | Compose lifecycle for just the proof-server service. |
+
+## Project structure
+
+```
+{{projectName}}/
+├── contracts/
+│   └── hello-world.compact     # Compact source
+├── scripts/
+│   └── e2e-check.ts            # smoke + read-back
+├── src/
+│   ├── network.ts              # network selection + state file management
+│   ├── setup.ts                # orchestrator for `npm run setup`
+│   ├── deploy.ts               # deploy the contract
+│   ├── cli.ts                  # interact with deployed contract
+│   └── check-balance.ts        # NIGHT / DUST balance
+├── docker-compose.yml          # node + indexer + proof-server
+├── .midnight-state.json        # written by deploy (gitignored)
+├── package.json
+└── tsconfig.json
+```
+
+## Compact compiler version
+
+`.compact-version` at the create-mn-app repo root pinned the compiler
+version this project was scaffolded against. To upgrade your local
+compiler to that version:
+
+```bash
+compact update <version>
+compact use <version>
+```

package/templates/hello-world/_gitignore

@@ -22,7 +22,6 @@ contracts/managed/
 deployment.json
 
 # Wallet seed (sensitive)
-.midnight-seed
 
 # OS generated files
 .DS_Store
@@ -53,3 +52,6 @@ coverage/
 # Temporary files
 tmp/
 temp/
+
+# Midnight network state (per-network seeds, deploy addresses)
+.midnight-state.json

package/templates/hello-world/contracts/hello-world.compact.template

@@ -1,4 +1,4 @@
-pragma language_version >= 0.16;
+pragma language_version >= 0.23;
 
 import CompactStandardLibrary;
 

package/templates/hello-world/docker-compose.yml.template

@@ -1,9 +1,70 @@
+# Local Midnight devnet for {{projectName}}
+# LOCAL DEVELOPMENT ONLY — do not expose these ports to a public network.
+# Tear down with: docker compose down -v
+name: {{kebabName}}-devnet
+
 services:
-  proof-server:
-    image: midnightntwrk/proof-server:7.0.0
-    platform: linux/amd64
+  node:
+    image: midnightntwrk/midnight-node:0.22.5
+    container_name: {{kebabName}}-node
+    ports:
+      - "9944:9944"
+    environment:
+      CFG_PRESET: "dev"
+      SIDECHAIN_BLOCK_BENEFICIARY: "04bcf7ad3be7a5c790460be82a713af570f22e0f801f6659ab8e84a52be6969e"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:9944/health"]
+      interval: 2s
+      timeout: 5s
+      retries: 30
+      start_period: 20s
+
+  indexer:
+    # Pinned to 4.2.1, NOT 4.3.0+: indexer-standalone 4.3.0 introduced an SPO
+    # (Cardano Stake Pool Operator) indexer that hard-requires a Blockfrost API
+    # key (APP__INFRA__SPO_NODE__BLOCKFROST_ID) — the process exits 1 at boot
+    # if missing, and placeholder values are explicitly rejected. There is no
+    # opt-out flag. 4.2.1 is the latest tag without that dependency, so it is
+    # the latest viable image for a zero-config local devnet. Do not bump to
+    # 4.3.x without first wiring a Blockfrost credential into this compose file
+    # — that is unacceptable for a "first DApp on Midnight" experience.
+    image: midnightntwrk/indexer-standalone:4.2.1
+    container_name: {{kebabName}}-indexer
+    ports:
+      - "8088:8088"
     environment:
-      - PORT=6300
+      RUST_LOG: "indexer=info,chain_indexer=info,indexer_api=info,wallet_indexer=info,indexer_common=info,fastrace_opentelemetry=off,info"
+      APP__APPLICATION__NETWORK_ID: "undeployed"
+      APP__INFRA__NODE__URL: "ws://node:9944"
+      APP__INFRA__STORAGE__PASSWORD: "indexer"
+      APP__INFRA__PUB_SUB__PASSWORD: "indexer"
+      APP__INFRA__LEDGER_STATE_STORAGE__PASSWORD: "indexer"
+      APP__INFRA__SECRET: "303132333435363738393031323334353637383930313233343536373839303132"
+    healthcheck:
+      test: ["CMD-SHELL", "cat /var/run/indexer-standalone/running"]
+      interval: 10s
+      timeout: 5s
+      retries: 30
+      start_period: 10s
+    depends_on:
+      node:
+        condition: service_healthy
+
+  proof-server:
+    # No healthcheck: the proof-server image is distroless (nix-built) and has
+    # no shell or curl/wget binaries inside, so `docker compose --wait` cannot
+    # gate on it. The deploy script polls the proof-server from the host side
+    # before submitting transactions (see waitForProofServer in src/deploy.ts).
+    # Pinned to 8.0.3, NOT a 7.x: proof-server 7.x (all patches tested: 7.0.0
+    # through 7.0.3) hangs in proof generation on Apple Silicon Macs running
+    # Docker Desktop — the actix worker thread spins at 100% CPU forever after
+    # receiving /prove, with no log output, no memory growth, and no progress.
+    # The same image runs fine on x86_64 Linux. 8.0.3 fixed this; never bump
+    # downward into the 7.x line without re-validating on macOS arm64.
+    image: midnightntwrk/proof-server:8.0.3
+    container_name: {{kebabName}}-proof-server
+    command: ["midnight-proof-server -v"]
     ports:
       - "6300:6300"
-    restart: unless-stopped
+    environment:
+      RUST_BACKTRACE: "full"