DOCS / OPERATOR TESTNET SETUP

From Solana authority to Base execution.

Operator setup for development signing infrastructure. Developers using hosted signers can start directly with the quickstarts.

Build a fresh development deployment

For a new isolated state directory, install pinned tools and build the service and programs:

python3 scripts/install-ci-tools.py
bash scripts/demo-testnet.sh addresses
bash scripts/demo-testnet.sh build
bash scripts/demo-testnet.sh verify
# Fund the printed dedicated owner before deploying programs.
bash scripts/demo-testnet.sh deploy
bash scripts/demo-testnet.sh serve

The service serves the website and API together at http://127.0.0.1:4180. A static preview server has no signing backend. Build-time gateway and controller IDs must match deployed programs; the script pins them in host and SBF builds.

For an existing deployment, perform a coordinated v2 upgrade and reconcile active jobs first. Preserve all roots, identities, enrolled keys, journals and incident latches. Do not start a migrated local backup while its hosted instance runs. The commands above are not instructions to reset existing operational state.

State sources and identity providers

Store a dedicated Solana devnet HTTPS RPC URL in the private runtime directory’s solana-rpc-url file, mode 0600. Never commit provider keys or put them in website code. The service validates the devnet genesis. Its development configuration can share one provider between signers; that is a shared trust dependency, not independent state validation.

OIDC is disabled unless oidc-issuers.json exists in the private runtime directory with mode 0600 and is readable by the service account. Each entry contains exact issuer, audience and operator-pinned HTTPS jwks_url. Both signers independently validate RS256 tokens and binding nonces. Malformed or duplicate configurations fail startup; redirects and token-selected key URLs are refused. The hosted Google demo uses Google Identity Services with the site origin authorized in its Web OAuth client. Its client ID is the configured audience; changing that audience changes OIDC namespace identity and derived keys. The client secret is not used for browser ID-token approval and must not be shipped in the site.

Which accounts need test tokens?

• The operator owner funds program deployment and signer-set setup.
• Account off-chain message approvals need no SOL or destination funds.
• Policy edits and program on-chain approvals need a funded fee payer, plus rent for new or enlarged accounts.
• Each worker identity needs a small balance as the simulation transaction payer. Simulation does not broadcast or spend that balance.
• Base Sepolia test ETH is needed only for the older transfer-execution demo, not message signing.

Use test tokens only. Deployment rent depends on binary size. The networks are Solana devnet, Base Sepolia 84532 for EVM message context and Bitcoin testnet for Bitcoin messages.

Exercise hosted v2

1. Check /api/v2/config, including gateway, signer identities, example program and hardware status.
2. Use the account quickstart with a wallet message signature and no registration transaction.
3. Set an example program policy. Test both immutable off-chain evaluation and on-chain allowance consumption as appropriate for the deployment.
4. Sign and verify all five message schemes. Recover a completed job using only its saved public metadata.
5. Exercise wrong-message, stale-policy and uncertain-result failures without resetting state.

Compatibility paths

The older hosted /api/v1 and shared operator-funded transfer/message APIs remain separate compatibility paths. Their registration, COMMIT and transfer-session semantics are unchanged. V2 namespace metadata is lazy, and v2 sessions are deferred. The public v2 demo uses the visitor’s connected wallet.

Development deployment boundaries

The hosted API uses bounded requests, rate limits and a signing/enrollment gate. Private worker authentication endpoints are not exposed publicly. The browser receives public keys, messages, signatures and receipts; it never receives signer roots or the operator’s wallet key.

Development workers report hardware_backed: false. The default release worker needs a production provisioner. File permissions and separate processes do not establish independent TEEs, protected entropy or rollback resistance.

Restart safely

Record active hosted and coordinator jobs before a coordinated restart. Interrupted jobs are uncertain; POST /api/v2/jobs/:id/recover can read both workers’ retained public receipts but cannot sign again. A missing receipt pair remains unresolved. Keep the original request IDs and public transcripts.

Never delete roots, journals, locks or incident latches to make a request pass. A committed program allowance may remain consumed after a signing failure. Backups must preserve all participants’ consistent state; restoring a snapshot is not automatically safe.

Validation and rollout

Run bash scripts/ci.sh in an isolated checkout before rollout. It includes native sidecar tests, host and SBF checks, hosted browser signing, downloaded program verification and legacy process tests. Follow docs/offchain-approval-api.md and the approval plan for coordinated deployment requirements. Passing a local gate does not prove a production TEE or live OAuth integration.