Development deployment

This page covers local and testnet evaluation. A production launch still needs live interoperability testing, an approved proving setup, independent assurance and operations review. The pilot’s local acceptance workflow is described in the local acceptance guide .

Configuration

Variable	Purpose
`PII_MASTER_KEY`	Required at API startup: 64 valid hex characters or at least 32 UTF-8 bytes; generate a random secret
`HKDF_SALT`	Required stable random deployment salt; passed to HKDF as UTF-8 bytes, including hex-looking values. Keep it with retained legacy ciphertext
`ALLOW_INSECURE_HKDF_SALT`	Exactly `1` explicitly permits the historical default for local tests/demos only; never configure it in production
`AUTH_MODE`	Select the supported API-key, JWT or SIWE authentication mode
`API_KEY`	Required for protected requests in API-key mode
`DATABASE_URL`	PostgreSQL connection. Required by the pilot routes; without it only the legacy in-memory demo path works
`CIRCUIT_ARTIFACTS_DIR`	Compatible local circuit artifacts
`PILOT_PROVING_FACTORY`	Operator-owned `module:callable` returning tenant-bound proving targets for the API and separate job worker
`CLEARPROOF_RAPIDSNARK_BIN`	Optional operator-owned Linux native executable, selected by the target factory helper
`CLEARPROOF_RAPIDSNARK_SHA256`	Independently approved native binary digest; unpinned discovery preserves JavaScript
`VASP_DID`	Configured VASP identity
`VASP_DOMAIN`	Domain used by the discovery publisher
`VASP_HPKE_PRIVATE_KEY`	Recipient X25519 private key for the HPKE path; keep secret
`CORS_ALLOWED_ORIGINS`	Explicit allowed browser origins
`CHAIN_RPC_URL`	RPC endpoint for chain readers
`COMPLIANCE_REGISTRY_ADDRESS`	Registry deployment used for the intended verification context

The pilot routes also need independently configured storage keys and tenant/trust configuration; see the tenant storage guide . Startup checks key encoding/length and configures storage. It does not certify key randomness, artifact assurance, complete tenant isolation or end-to-end readiness. Current CORS handling removes wildcard origins when credentials are enabled.

An authenticated usage:read principal can call GET /pilot/readiness/{capability}/{target_id} for an operator-configured inspection or proving target in its own tenant. The report checks a bounded read-only database/schema query, an in-memory storage-key round trip and the loaded target’s profile, trust and freshness. Proving additionally checks artifact sizes and runtime-file availability. HTTP 200 means this configuration preflight passed; HTTP 503 identifies failed checks without disclosing configuration or secrets. /health remains public process liveness. The preflight does not pair or generate proofs, check retained current heads/credentials, rehash large artifact files, confirm a worker heartbeat, contact providers or consume authorization. Use the readiness runbook and the authorized read-only inspection path for those separate checks.

Durable proving jobs additionally need a separately supervised Linux worker: uv run python -m src.prover.proof_job_worker. Use the same database, storage keyring and independently pinned target configuration in both services. Configure host/container memory bounds, disable sensitive-memory swapping and core dumps, and measure capacity before increasing queue concurrency. The Node heap limit alone is not an RSS bound. See the proving jobs runbook .

The factory can select an optional pinned native backend with select_pilot_backend(javascript_prover). It uses anonymous RAM for WTNS and proof intermediates and independently pairs native output in JavaScript. Without a discovered binary/pin, JavaScript remains selected; explicit invalid configuration fails closed. Native process RSS excludes the Node and parent phases. See the native runbook and measured scope .

Validation


make test
npm run test:ts
npm run build

Contract checks run in packages/contracts with Hardhat. Real proofs additionally require Circom 2.2.2 and 2^17 powers-of-tau parameters; see circuits. Test counts and latency depend on the checkout and environment.

Sanctions operations

For the pilot, a new sanctions root is published as a signed root snapshot that the authorization service must accept as the current head. For the legacy contracts, every intended chain must receive the corresponding oracle relay update. Confirm the actual configured targets and freshness; do not infer successful relay from a local tree rebuild.

See recorded Sepolia contracts, sanctions and security. These instructions do not authorize or establish production use.