How a maintainer takes Boon from clone to a verified mainnet deployment, with pointers to the canonical commands and gates.
Operator runbook
Section titled “Operator runbook”This page is the docs-site map to Boon’s mainnet deployment process. The
canonical, line-by-line runbook is DEPLOYMENT.md in the repo — keep it open while
following these steps. Treat this page as orientation, not a substitute.
⚠️ Boon is pre-audit. Operator-side mistakes (wrong signer keys, missing KV namespaces, unfunded relayer, stale subgraph addresses) fail loudly by design. Do not skip gates.
Deployment gates (in order)
Section titled “Deployment gates (in order)”The repo serializes deployment into numbered steps. Each one has a verification command that must pass before moving on.
| Step | What | Reference |
|---|---|---|
| 0 | EIP-712 signer roundtrip — proves the Worker signer and the contract agree on the Link voucher domain before any real funds move. | Step 0 in DEPLOYMENT.md and ./scripts/run-eip712-roundtrip.sh |
| 1 | Contract on Base mainnet (forge create, BaseScan verify, setSigner to the production Worker key). | Step 1 |
| 2 | Subgraph — update subgraph/networks.json with the live address + start block, then npm --prefix subgraph run deploy:mainnet. | Step 2 + Data layer concept |
| 3 | Worker — create KV namespaces (OAUTH_STATE, DISCLOSURE_KV), set OAuth secrets, set BOON_SIGNER_KEY, set optional BOON_RELAYER_KEY, wrangler deploy. | Step 3 |
| 3b | x402 / Boon Points — production X402_RECIPIENT, X402_NETWORK, X402_FACILITATOR_URL, CDP_API_KEY_ID/SECRET. | x402 protocol → Worker configuration + Step 3b |
| 4 | App — set VITE_BOON_API_URL, VITE_BOON_CONTRACT_ADDR, VITE_BOON_CHAIN_ID=8453, build and deploy. | Step 4 |
| 5 | Mainnet cutover copy — sweep placeholders in HOW_TO_CLAIM.md, README.md, subgraph/networks.json, Worker/App env. | Step 5 |
| 6 | CLI integration — confirm boon doctor, OWS adapter, and signer paths point at the production Worker and contract. | Step 6 |
| 7 | End-to-end smoke — send a small real boon, escrow, link, claim, and verify on BaseScan. | Step 7 |
| 8 | Tag the release. | Step 8 |
Things this runbook never does
Section titled “Things this runbook never does”The runbook is explicit about what it does not automate:
- It does not bypass the EIP-712 signer roundtrip.
- It does not deploy a subgraph against placeholder addresses; the render step fails on zero addresses on purpose.
- It does not silently fall back from missing relayer/signer keys — the UI is required to fail closed.
- It does not skip the funded live-settlement smoke for paid x402 routes.
If a step appears redundant, treat that as the runbook’s safety margin rather than something to optimize away.
Per-PR placeholder grep
Section titled “Per-PR placeholder grep”Mainnet cutover sweeps for placeholders before release. The exact greps are listed in Step 5 of DEPLOYMENT.md; run them before any tag.
Local development
Section titled “Local development”A local hack loop is intentionally not in this runbook — it lives in
package READMEs (worker/README.md, app/, cli/README.md) and the
Quickstart. The runbook focuses on the
operations a maintainer performs against the production deployment.
Companion references
Section titled “Companion references”- Contract addresses — the canonical live address table.
- Status and disclaimers — current release posture and unaudited warnings.
- Documentation maintenance — which surfaces a deployment-affecting change must update.
- x402 protocol → Verification and deployment gates — the paid-route-specific smoke and U-gate serialization.