Operations

Running the three repositories locally, the one-shot commands that walk a payment through to a mint, what CI enforces, how deployment works, and what to do when an alert fires.

Local bring-up

Backend

npm ci
cp .env.example .env                 # DB, indexer key, contract addresses, RPC maps
npm run docker:up                    # Postgres + Redis + Adminer
npm run migration:run                # 13 migrations
NODE_ENV=development npm run seed    # test user + the demo signer addresses
npm run dev

• API: http://localhost:3000/api
• Swagger UI: http://localhost:3000/docs (JSON at /docs/json)
• Health: http://localhost:3000/health — outside the /api prefix, where load balancers and container health checks look

Each background role is its own process with its own env file:

npm run dev                                     # API + poller + pricing + accrual
ISSUER_ENV_FILE=.env.issuer-a npm run issuer    # attestation loop
RELAYER_ENV_FILE=.env.relayer npm run relayer
SETTLEMENT_ENV_FILE=.env.settlement npm run settlement
MONITOR_ENV_FILE=.env.monitor npm run monitor

.env.issuer.example, .env.relayer.example, .env.settlement.example and .env.monitor.example document what each process needs.

Contracts

git clone --recurse-submodules <repo>   # or: git submodule update --init --recursive
npm ci
cp .env.example .env                    # DEPLOYER_PRIVATE_KEY, ETHERSCAN_API_KEY
forge build && forge test

Mobile

npm install          # postinstall generates .wdk/ and .wdk-bundle/
cp .env.example .env # GOOGLE_*_CLIENT_ID, API_BASE_URL
bundle install && (cd ios && bundle exec pod install)   # iOS only, first clone
npm start            # WDK bundle watcher + Metro
npm run ios          # or: npm run android

API_BASE_URL must point at the backend's /api prefix. On a device or Android emulator, localhost is the phone — use the host's LAN address (or 10.0.2.2 on the Android emulator).

Walkthrough: payment → mint

One-shot equivalents of the loops. Each runs a single pass and exits, which is what makes a demo followable:

npm run poll:once     # ingest → price → accrue
npm run issue:once    # verify + sign the pending claims
npm run relay:once    # preflight + claim() + wait for the receipt

Order of operations for an end-to-end run. Step through it, or click any stage for the exact command and what to check before moving on.

Utilities

CI

Backend deployment is Dokploy (self-hosted) watching main. CI does not deploy — it gates: branch protection on main requires check and build, so a red pipeline cannot reach the branch Dokploy pulls from.

Deployment

Backend — one image, five services

The production image is dist/main.js on npm ci --omit=dev: no ts-node, no src/ on disk. Every role is the same image with a different PROCESS_ROLE (api, issuer, relayer, settlement, monitor); an unrecognised value fails fast rather than silently booting the API. .env.prod is one file for all five — paste it into each service and change PROCESS_ROLE.

Pre-deployment checklist: tests pass, no secrets in code or .env, migrations generate cleanly, build succeeds, /health responds, .env.example matches all required vars.

Contracts — Sepolia

# 1. fill in script/config/ethereum-sepolia.json (every address; 0x0 is refused
#    except governor, where 0x0 means "use the deployer")
# 2. fund the deployer: ~0.015 ETH at 2 gwei (~7.3M gas)
# 3. dry run — free, and runs every check against live Sepolia state
forge script script/Deploy.s.sol:Deploy --rpc-url "$SEPOLIA_RPC_URL"
# 4. broadcast + verify
forge script script/Deploy.s.sol:Deploy \
  --rpc-url "$SEPOLIA_RPC_URL" --broadcast --verify -vvv

The script asserts the whole wiring after deploying and writes deployments/<chainId>.json only on a real broadcast — a dry run predicts addresses from the deployer nonce, and writing those looks identical to a successful deployment.

Observability

• Health. GET /health — liveness plus database connectivity.
• Logs. Structured (Pino) to stdout; alerts appear as security_event=… lines. Never log PII, tokens or seed material.
• Alerts. AlertService requires a subject on every alert — an alert that names the claim or the paymentRef sends someone to the row instead of on a hunt. Optionally POSTed to ALERT_WEBHOOK_URL; with ALERT_TELEGRAM_CHAT_ID set and a Telegram sendMessage URL, the payload is rewritten into {chat_id, text}. A pager that is down never takes the process with it.
• Cross-process counters. service_counters carries indexer request / error / 429 counts, which the monitor reads from another process.
• Reconciliation. The monitor compares minted supply against the payments that justify it, and the settlement watcher raises a CRITICAL alert on a Claimed event with an unknown paymentRef.

Runbook

Type what you are seeing — an error string, a status, a component — to find the row.