Operator guide

Activation checklist

The ordered sequence to take a fresh deployment to a live network. Every step is an explicit operator action, and several are gated or pending — this is the order, not a claim that any of it is already done. Contract deployment, the Base Sepolia → mainnet checklist, and the canary runbook live in docs/CONTRACTS.md — followed here, not duplicated.

1. 01Configure a live inference upstream (BASIS_INFERENCE_UPSTREAM_URL/_KEY/_MODEL).
2. 02Configure a durable DB (BASIS_STORE_DRIVER=postgres + BASIS_DATABASE_URL + migrations).
3. 03Launch $BASIS on Bankr (operator action — DONE: $BASIS is live on Base).
4. 04Seed liquidity for $BASIS so quotes are meaningful.
5. 05Set BASIS_TOKEN_ADDRESS to the deployed token address.
6. 06Set ZEROX_API_KEY (server-only) for the quote provider.
7. 07Enable the router (BASIS_PAYMENT_ROUTER_ENABLED=true).
8. 08Deploy the credit vault on Base Sepolia; set BASIS_CREDIT_VAULT_ADDRESS.
9. 09Verify a direct BASIS deposit credits a balance.
10. 10Verify a USDC→BASIS quote returns a real, bounded quote.
11. 11Verify payment confirmation final-credits only after on-chain proof.
12. 12Deploy the reward distributor; set BASIS_REWARD_DISTRIBUTOR_ADDRESS.
13. 13Run the worker canary (pnpm canary).
14. 14Run the settlement dry-run (pnpm settle:rewards).
15. 15Run a small live settlement on Sepolia and confirm idempotency.
16. 16Promote to Base mainnet (explicit operator decision — see docs/CONTRACTS.md).

Backend activation (Phase 1 → 3)

The website, docs, dashboard, auth, and most REST routes already run as a backend on Vercel serverless — that part is live. Real inference, durable data, and reward settlement each need an additional piece that is not yet provisioned. The phases below are the honest floor each configuration can stand on — not a claim that any service is running. The live GET /api/launch-status backend block reports which phase the current env supports, derived from env. Full detail lives in docs/backend-architecture.md and the per-piece deploy guides (docs/deploy-inference-upstream.md, docs/deploy-postgres.md, docs/deploy-orchestrator.md, docs/deploy-keeper.md).

Privy activation

Stand up sign-in and API keys. Login is via Privy (wallet or email); keys are sk-basis-... bearer tokens minted in the dashboard. The server verifies a Privy access token against the public JWKS — so no app secret is in the verify path — but the app secret and the API-key pepper are still server-only secrets that must be rotated and kept out of the client bundle. Work this list in order; step 1 is non-negotiable.

1. 01Rotate the pasted Privy App Secret (it was shown in plaintext at creation — treat the old one as compromised).
2. 02Store the new PRIVY_APP_SECRET in the Vercel environment only — never NEXT_PUBLIC, never committed to the repo.
3. 03Set NEXT_PUBLIC_PRIVY_APP_ID (public — the browser SDK uses it to start login).
4. 04Set PRIVY_APP_ID (server-side audience for access-token verification).
5. 05Set PRIVY_JWKS_URL (the public JWKS the server verifies tokens against — no secret in this path).
6. 06Set BASIS_API_KEY_PEPPER (server-only strong random string — required to create/verify sk-basis-... keys).
7. 07Enable login methods (wallet and email) in the Privy dashboard.
8. 08Configure basis.watch as the production domain in the Privy dashboard.
9. 09Upgrade the Privy app from development to production before launch (development mode is capped at <=150 users).
10. 10(Optional) Enable HTTP-only cookies for production (PRIVY_AUTH_MODE=cookie + PRIVY_COOKIE_DOMAIN=basis.watch).
11. 11If cookies are enabled, use separate dev/prod Privy apps so cookie domains and origins do not collide.
12. 12Run production auth smoke tests: sign in, mint a key, call a protected route, hit an unauthenticated route (expect 401 auth_required when BASIS_AUTH_REQUIRED=true).
13. 13Verify no secrets appear in the client bundle: neither PRIVY_APP_SECRET nor BASIS_API_KEY_PEPPER is shipped to the browser, and the app secret is never given a NEXT_PUBLIC_ prefix.

# Privy authentication. App id + JWKS URL are PUBLIC; the app SECRET and the
# API-key pepper are SERVER-ONLY. NEVER set a secret as NEXT_PUBLIC, never commit
# a real value, and ROTATE the development app secret before production use.
NEXT_PUBLIC_PRIVY_APP_ID=     # PUBLIC — browser SDK uses it to start login
PRIVY_APP_ID=                 # server-side audience for token verification
PRIVY_APP_SECRET=             # SERVER-ONLY — ROTATE before prod; never NEXT_PUBLIC
PRIVY_JWKS_URL=               # public JWKS — token verify needs NO secret (jose)
PRIVY_AUTH_MODE=local_storage # local_storage (default) | cookie (prod preference)
PRIVY_COOKIE_DOMAIN=          # e.g. basis.watch, when PRIVY_AUTH_MODE=cookie

# API keys + auth enforcement.
BASIS_API_KEY_PEPPER=         # SERVER-ONLY — required to mint/verify sk-basis-... keys
BASIS_AUTH_REQUIRED=false     # true → protected routes require a token or API key
BASIS_DASHBOARD_ENABLED=true  # master switch for the /dashboard app

Environment variables

The full operator configuration surface. Values are set per-environment (never committed); an unset variable renders the corresponding feature as pending. The right column notes what each variable gates.

Vercel deployment

The web app deploys on Vercel with the project Root Directory set to apps/web. A push to main auto-deploys to production; pushes to a branch get a preview URL. Environment variables are configured per-environment in the Vercel dashboard.

# Vercel project settings (apps/web is the web app)
Root Directory: apps/web

# Deploy model:
#   push to main      → production (basis.watch)
#   push to a branch  → preview URL
# Environment variables are set per-environment in the Vercel dashboard,
# never committed to the repo.

# Scheduled jobs live in apps/web/vercel.json (Vercel reads it from the Root
# Directory; a repo-root vercel.json is IGNORED). The committed cron prepares a
# settlement batch daily via /api/internal/settlement/run — it never signs or
# submits. See the Settlement keeper section + docs/deploy-keeper.md.

Orchestrator hosting

The orchestrator (runtime/orchestrator) is a separate, long-lived Socket.io process that holds persistent websocket connections to workers. It does not run on Vercel — host it where a long-lived process can accept connections. Workers reach it via BASIS_ORCHESTRATOR_URL. A hosted orchestrator is running in production (a private backend); you can also run your own.

# The orchestrator is a separate, long-lived process — NOT on Vercel.
# Run it where it can hold persistent websocket connections to workers.
PORT=8787 pnpm --filter runtime/orchestrator start

# Workers connect to it via BASIS_ORCHESTRATOR_URL (default ws://localhost:8787).
# A hosted orchestrator is running in production (a private backend). Public worker
# routing for /api/v1 stays OFF until BASIS_WORKER_ROUTING_ENABLED=true.

Persistence

The store backend is selected by BASIS_STORE_DRIVER. The default is memory — process-local and non-durable: worker registrations, the credit and reward ledgers, receipts, quotes, and the /data state live in process memory and reset on a cold start. That is fine for local testing and a single long-lived process, but it must not be treated as a system of record — payments recorded under memory are not durably persisted.

The honest posture is reported by persistenceStatus() as exactly one of three states, surfaced on GET /api/launch-status (persistence.status):

• memory_non_durable — the default (and production today); the process-local memory store (durable: false).
• postgres_unavailable — postgres driver selected but no BASIS_DATABASE_URL, so no database can be reached; records fall back to the non-durable memory store (durable: false).
• postgres_configured — driver + connection string set and the durable adapter is wired (the STORE_WIRED constant, which is true). The only state with durable: true.

The async adapter (apps/web/lib/store/postgres.ts) and schema (migrations/0001_init.sql) are complete and wired: InferenceStore is asynchronous, STORE_WIRED is true, and store() returns the durable PostgresStore (over a lazy postgres driver — pooled, prepare:false, imported on first query, never at build) whenever the postgres driver and a connection string are set. So moving off memory is an operator migration, not a code change: provision pooled managed Postgres, set BASIS_STORE_DRIVER=postgres + BASIS_DATABASE_URL, run migrations/0001_init.sql (idempotent; there is no 0002), deploy, and confirm persistence.status: "postgres_configured" / durable: true. STORE_WIRED is a hard-coded constant (never an env flag) so durability is reported from the same code path that returns PostgresStore — and storeHealth() additionally probes the DB (SELECT 1) and downgrades to postgres_unavailable if it is unreachable, so a surface never claims durability against a database it cannot reach. The full runbook is in docs/PERSISTENCE.md (deployment side: docs/deploy-postgres.md); see also architecture.

⚠ Do not enable live deposits, worker payouts, or settlement while BASIS_STORE_DRIVER=memory — the in-memory store resets on cold start and is not shared across instances, so money-path records would be lost. Durable persistence (durable: true) is gate g4 of the five live-settlement gates; verify it before turning on payment finalization or the live keeper.

# Store backend. memory is the repo DEFAULT (local/preview) and is process-local +
# NON-DURABLE: receipts, credits, rewards, quotes, and /data reset on a cold start.
# PRODUCTION runs durable Postgres (Neon): persistence.status postgres_configured,
# durable true. A no-DB-env deploy stays memory_non_durable.
BASIS_STORE_DRIVER=postgres          # memory (default) | postgres (durable, wired; prod)

# Durable Postgres (wired — operator migration, no code change; DONE in prod):
#   1. BASIS_STORE_DRIVER=postgres
#   2. BASIS_DATABASE_URL=postgres://...   # SERVER-ONLY, POOLED endpoint; never client-side
#   3. run migrations/0001_init.sql        # idempotent (0002/0003 also applied in prod)
#   -> persistence.status: postgres_configured, durable: true
BASIS_DATABASE_URL=                  # required when BASIS_STORE_DRIVER=postgres

Upstream inference config

Set BASIS_INFERENCE_UPSTREAM_URL to an OpenAI-compatible backend to put the gateway in proxy mode: requests forward upstream, tokens stream back, and a receipt is recorded (server-counted output tokens). With no upstream configured, the API returns a structured runtime_pending response — the OpenAI-compatible contract stays live either way.

# Proxy mode: forward to an OpenAI-compatible backend and record receipts.
BASIS_INFERENCE_UPSTREAM_URL=https://your-openai-compatible-backend/v1
BASIS_INFERENCE_UPSTREAM_KEY=sk-...        # SERVER-ONLY, if the backend needs auth
BASIS_INFERENCE_UPSTREAM_MODEL=basis-default  # optional model override
BASIS_INFERENCE_UPSTREAM_TIMEOUT_MS=60000  # optional per-request timeout (default 60s)

# Unset BASIS_INFERENCE_UPSTREAM_URL → the API returns a structured
# runtime_pending (503). The OpenAI-compatible contract stays live either way.
#
# PRECEDENCE: this hosted upstream proxy is the ONLY backend the serverless route
# (/api/v1/chat/completions) dials. BASIS_ORCHESTRATOR_URL is the WORKER mesh's
# socket target, NOT a backend this route calls — if both are set, the upstream
# proxy still wins (the route never silently routes to the orchestrator).

Cost guardrails

In proxy mode the gateway forwards to a managed, per-token-billed upstream model, so every completion costs real money per input and output token. The gateway bounds spend before any upstream call with three independent controls — a per-request size/output ceiling, a per-caller throttle, and an instant kill switch — plus an in-app usage signal. These are configured by the BASIS_INFERENCE_* and BASIS_RATE_* env vars in the table above; each reads from env with a safe default and never throws.

Kill switch — instant zero-spend off

BASIS_INFERENCE_DISABLED=true is the emergency cost cap. When set, the chat route returns a structured inference_disabled (503) before any upstream call — the managed upstream is never dialed, so upstream spend drops to zero — while the OpenAI-compatible API contract stays live (callers get a clean error envelope, not a hang). To engage: set it in the deployment environment, redeploy so new invocations pick it up, and verify a POST /api/v1/chat/completions returns 503 inference_disabled. To restore, unset it (or set it to anything other than the literal true) and redeploy. It is faster and more total than tuning the caps — pull it on a cost spike, a provider incident, or abuse you cannot throttle in time.

Per-request spend ceiling

A single request can never become an unbounded spend faucet. BASIS_INFERENCE_MAX_PROMPT_CHARS (default 200000) bounds the input size, and BASIS_INFERENCE_MAX_OUTPUT_TOKENS (default 2048) is the hard cap on completion tokens forwarded upstream — the forwarded budget is always clamped to it, even if the caller asks for more or omits max_tokens, so the worst-case billable output of any one call is fixed. MAX_BODY_BYTES / MAX_MESSAGES reject oversized or malformed shapes early. Lower the output cap to tighten per-call cost.

Per-caller throttle

The rate limiter gives anonymous callers low caps (10/min, 200/day by default) and an authenticated identity or API key higher caps (60/min, 5000/day). BASIS_RATE_LIMIT_ENABLED is on unless set to the literal false.

# Emergency kill switch — instant, zero-spend off. When exactly "true", the chat
# route returns inference_disabled (503) BEFORE any upstream call; the managed
# upstream is never dialed. The OpenAI-compatible contract stays live.
BASIS_INFERENCE_DISABLED=false        # set true to halt all upstream spend now

# Per-request spend ceiling — caps request SIZE + OUTPUT length before any
# (billable) upstream call. Absent/malformed → the default; never throws.
BASIS_INFERENCE_MAX_BODY_BYTES=262144     # raw body bytes (256 KiB) → 413 over
BASIS_INFERENCE_MAX_MESSAGES=64           # messages per request → 400 over
BASIS_INFERENCE_MAX_PROMPT_CHARS=200000   # total prompt chars (INPUT guard)
BASIS_INFERENCE_MAX_OUTPUT_TOKENS=2048    # HARD output cap (OUTPUT spend ceiling)
BASIS_INFERENCE_DEFAULT_OUTPUT_TOKENS=1024 # budget when caller omits max_tokens

# Per-caller throttle — low caps for anonymous, higher for an identity / API key.
# BEST-EFFORT and PER-INSTANCE (no shared store): each serverless instance keeps
# its own counters, so the effective ceiling is per-instance, not global.
BASIS_RATE_LIMIT_ENABLED=true         # only the literal "false" disables it
BASIS_RATE_ANON_PER_MIN=10
BASIS_RATE_ANON_PER_DAY=200
BASIS_RATE_AUTH_PER_MIN=60
BASIS_RATE_AUTH_PER_DAY=5000

In-app usage signal

Daily receipt volume is the primary in-app cost signal — every served job records a receipt, so receipt count ≈ billable request count. GET /api/inference/receipts lists the receipts (each gateway-served job is workerRewardRaw: "0" — metered, not paid; contributor-worker rewards require the separate worker mesh) and GET /api/inference/stats reports the accounting totals and runtime mode. On the non-durable memory store these counts are process-local and reset on a cold start; durable cross-instance totals need the Postgres store. Pair this with the upstream provider's own cost dashboard and per-minute token quota as the authoritative, out-of-band spend controls.

Auth posture

BASIS_AUTH_REQUIRED decides whether the protected routes (/api/v1/*, /api/user/*, payment prepare/confirm, worker register) accept anonymous callers. When off, anonymous requests still work under the low anonymous rate caps; when on, they fail closed (401/403) and usage is attributable to an identity or API key. This deployment currently has BASIS_AUTH_REQUIRED=false — protected routes are open (the public demo posture).

Base RPC config

Configure the Base RPC endpoint and chain identity. The chain id is validated before any chain action — Base mainnet is 8453 — so a misconfigured network is caught rather than acted on. The explorer URL drives address and transaction links.

# Base RPC + chain identity. Chain id is validated before any chain action.
BASE_RPC_URL=https://mainnet.base.org      # or your provider endpoint
BASE_CHAIN_ID=8453                         # Base mainnet
BASE_BLOCK_EXPLORER_URL=https://basescan.org

Token / contract env config

The token and contract addresses are each empty until deployed and configured. Empty values render honestly as pending — addresses are never invented in source. Two of these gate features: BASIS_CREDIT_VAULT_ADDRESS gates deposits, and BASIS_REWARD_DISTRIBUTOR_ADDRESS gates worker reward settlement.

# Token + contract addresses. Each is empty until deployed/configured;
# empty values render honestly as "pending" — never invent an address.
BASIS_TOKEN_ADDRESS=                 # $BASIS contract → token "deployed" when set
BASIS_CREDIT_VAULT_ADDRESS=          # gates deposits  (depositsEnabled)
BASIS_REWARD_DISTRIBUTOR_ADDRESS=    # gates rewards   (rewardSettlementEnabled)
BASIS_TREASURY_ADDRESS=              # treasury reference

Pricing-epoch operations

BASIS-per-credit is a dynamic, versioned value, not a forever constant. It is configured entirely by the BASIS_PRICING_* env vars in the table above, and every value is honest-pending unless set: an unconfigured deployment stays in the placeholder epoch and never fabricates a live price.

• BASIS_PRICING_MODE selects the source: placeholder (default), manual (operator-asserted BASIS/USD via BASIS_PRICING_MANUAL_BASIS_USD_RAW + BASIS_CREDIT_TARGET_USD_RAW), or quote / twap (live derivation, pending until a token + liquidity + a price source exist).
• BASIS_PRICING_MAX_EPOCH_CHANGE_BPS caps each epoch-to-epoch move (default 2500 = 25%); BASIS_PRICE_TTL_SECONDS bounds staleness; the MIN/MAX_BASIS_PER_CREDIT_RAW bounds are hard sanity rails.
• A new pricing epoch applies prospectively — to new quotes and reservations only. Existing receipts are never rewritten and accepted jobs are never silently repriced; a worker's reward is drawn from the snapshot already locked on its receipt.

Read the resolved rate at any time with GET /api/pricing and the epoch table with GET /api/pricing/epochs. To re-read the price source and re-derive BASIS-per-credit now, call the secret-protected POST /api/internal/pricing/refresh (it accepts INTERNAL_API_SECRET / ADMIN_SECRET or the dedicated BASIS_PRICING_REFRESH_SECRET, and never signs or writes on-chain).

Payment router env config

The payment router lets a payer route ETH, WETH, or USDC into $BASIS at payment time to fund credits. It is a deliberate opt-in via BASIS_PAYMENT_ROUTER_ENABLED and is reported as configured only when the token, a quote provider, and the enable flag are all set. Quote providers are wired by env; provider API keys are read server-side only and are never returned to the client.

# Payment router: route ETH/WETH/USDC into $BASIS at payment time.
# Enable ONLY after the $BASIS token AND on-chain liquidity exist — quoting a
# token with no market is meaningless. Until then the router stays pending.
BASIS_PAYMENT_ROUTER_ENABLED=false   # master opt-in (true to enable)
BASIS_DEFAULT_SLIPPAGE_BPS=100       # default slippage when caller omits one (1%)
BASIS_MAX_SLIPPAGE_BPS=300           # hard ceiling on caller slippage (3%)
BASIS_QUOTE_TTL_SECONDS=90           # quote lifetime, clamped 30–300s
BASIS_PAYMENT_ROUTER_ADDRESS=        # router contract, if used

# Quote providers. 0x is the configured path; Uniswap/Aerodrome are in research.
# Provider keys are SERVER-ONLY — never expose them client-side.
ZEROX_API_KEY=                       # SERVER-ONLY — never sent to the browser
ZEROX_SWAP_API_URL=https://base.api.0x.org
UNISWAP_UNIVERSAL_ROUTER_ADDRESS=    # research
UNISWAP_PERMIT2_ADDRESS=             # research
AERODROME_ROUTER_ADDRESS=            # research

# Payment receiver + on-chain verification. A payment final-credits ONLY after
# the tx is proven on Base (success, chain 8453, correct token, correct
# receiver, enough BASIS out, enough confirmations, quote unexpired + unreplayed).
BASIS_PAYMENT_RECEIVER_ADDRESS=      # defaults to credit vault → router when unset
BASIS_PAYMENT_CONFIRMATIONS=1        # confirmations required before crediting
BASIS_PAYMENT_VERIFICATION_MODE=     # strict | provisional | disabled
                                     #   strict      → default when router enabled
                                     #   provisional → dev/test only (credits early)
                                     #   disabled    → when the router is off

Treasury & tokenomics

How value accrues to the network now that $BASIS is live — fee streams, a draft treasury allocation, and Bankr creator fees. None of those flows is live yet: every fee, treasury balance, and accrual reads pending until addresses are configured and reads are verified on Base. The public surface is /treasury (also in the treasury block of /api/data); the design source of truth is docs/tokenomics.md + docs/treasury-policy.md + docs/bankr-fees.md.

• WETH-side and $BASIS-side are separate ledgers — never blended. The Bankr/Doppler creator trading fee accrues in both WETH and $BASIS together in the Uniswap-V4 pool; each side is accounted on its own. WETH is a liquid external reserve that funds real opex; $BASIS is native inventory. No automatic buyback is promised; any WETH→$BASIS market buy is an explicit operator-approved action.
• Tokenomics splits. The per-job split is 90% worker / 10% burn (BASIS_WORKER_REWARD_BPS / BASIS_NETWORK_MARGIN_BPS), configurable. The 10% per-job share routes to BURN via the on-chain BasisInferenceFeeRouter (deployed + configured; CreditVault spendSink wired to it). The 10% burn / 90% worker split has been CANARY-PROVEN by a controlled mainnet tx (totalBurned 1000 / totalAllocated 9000 $BASIS) — proven, not yet a continuous live feed. This is a SEPARATE flow from the Bankr $BASIS-side split. The Bankr creator-fee $BASIS-side splits 50% burn / 50% staker rewards (BASIS_SIDE_BURN_BPS / BASIS_SIDE_STAKER_REWARD_BPS), realized per claim (each $BASIS-side claim is burned 50% on-chain + funded 50% to the staking vault); the CONTINUOUS automatic feed is not yet wired. There is no fixed allocation matrix; the treasury is accounted as assets vs obligations.
• Reads are unauthenticated; claiming is operator-signed. Once BASIS_TOKEN_ADDRESS and BASIS_BANKR_FEE_RECIPIENT_ADDRESS are set, the read-only surface MAY poll Bankr's public fee endpoints (Base, chainId 8453; 0.7% swap fee; the Bankr protocol split — creator 95% / Doppler 5% — is a source-tagged assumption, and Basis's exact beneficiary share is read from the launch output / fee API). Claiming creator fees is an operator/keeper signed action and is never performed server-side.

# Treasury + Bankr creator-fee accounting. Everything stays PENDING until the
# addresses are set and a verified production read succeeds. WETH-side
# and $BASIS-side are accounted SEPARATELY and NEVER blended. Reads are
# UNAUTHENTICATED; CLAIMING Bankr fees is an operator/keeper signed action and is
# NEVER performed server-side.
BASIS_TREASURY_ADDRESS=          # treasury holdings address (empty → pending)
BASIS_BANKR_FEE_RECIPIENT_ADDRESS=      # Bankr creator-fee beneficiary (only it can claim)
BASIS_BANKR_FEES_API_URL=        # default https://api.bankr.bot (read-only)
BASIS_BURN_ENABLED=false         # DRAFT gate only — never makes the burn live

# Read accrued creator fees (no key) once token + wallet are configured:
#   GET https://api.bankr.bot/token-launches/<tokenAddress>/fees?days=30
#   GET https://api.bankr.bot/public/doppler/creator-fees/<walletAddress>

Burn policy status

The Proposed Burn Policy is a DRAFT and is NOT IMPLEMENTED. The proposal is to burn 10% of the $BASIS inference protocol fee (deflationary as usage grows). It is not active, and BASIS_BURN_ENABLED does not make it live — even when set, the policy stays a draft until an on-chain burn path exists and is verified.

Activation requires all of: an on-chain burn path, accounting support, operator approval, and legal review — each verified. Burned amounts are tracked separately from treasury balances and are never blended (burned-to-date is "0" until live). No burn claim may appear on a public surface until it is verifiable on-chain. See docs/treasury-policy.md (§4) and docs/tokenomics.md for the full-burn vs partial-burn vs route-to-treasury analysis.

Staking activation

The BasisStakingVault (contracts/src/BasisStakingVault.sol) is DEPLOYED + BaseScan-verified + configured in production (address read from env, never hardcoded). The public surface is /stake ("Stake $BASIS"), enabled in production. On a no-env deploy every staking action stays disabled until both addresses are configured and an on-chain read succeeds.

The staker-reward tranche is funded and streaming. fundRewards has been called: a funded $BASIS reward tranche streams over 7 days into the redeemable value of staked $BASIS (gated behind BASIS_STAKING_LIVE=true; unset → honestly not-active). Staking receives the staker-reward side — 50% of $BASIS-side fee generation — through a staking contract on Base; reward amounts are read live on-chain. This is NOT yield, passive income, or a guaranteed return. WETH-side fees are separate and never enter the vault, and the per-job 90% worker / 10% burn split is a separate flow again. Rewards accrue as vault share-value (ERC4626), not a per-user APY, and are not guaranteed.

1. 01Launch the $BASIS token (operator action — DONE: $BASIS is live on Base) and set BASIS_TOKEN_ADDRESS.
2. 02Deploy and verify the BasisStakingVault on Base (DONE — contracts/src/BasisStakingVault.sol; runbook docs/DEPLOY_CONTRACTS.md). No address lives in source.
3. 03Set the vault address in BOTH BASIS_STAKING_VAULT_ADDRESS (server) and NEXT_PUBLIC_BASIS_STAKING_VAULT_ADDRESS (client) — the same deployed address.
4. 04(Optional) set NEXT_PUBLIC_BASE_RPC_URL so browser reads use your endpoint instead of the public default.
5. 05Confirm GET /api/staking/status reports vault.readVerified true (a real on-chain read succeeded) before exposing any action.
6. 06Fund the staker-reward tranche on-chain (fundRewards) — DONE: rewards stream linearly into staked value over the reward duration; vault.live stays false from an env address alone.
7. 07Set BASIS_STAKING_LIVE=true (the staking-policy `implemented` gate) so vault.live opens — it needs a successful on-chain read AND this affirmative policy env.
8. 08Confirm the /api/launch-status staking block reports vaultConfigured + vaultLive true; the /stake surface then enables actions and shows the Live chip.
9. 09Smoke-test on /stake with a wallet: a deposit, a start-cooldown, and a redeem in the withdraw window after the cooldown matures — the wallet signs every transaction; Basis never signs server-side.

# Staking vault (BasisStakingVault — ERC4626 + cooldown). DEPLOYED + BaseScan-verified
# + configured in prod (0x8E06...a2f6); no address lives in source. The staker-reward
# tranche is funded + streaming: fundRewards has been called and a funded $BASIS
# tranche streams into the redeemable value of staked $BASIS (gated behind
# BASIS_STAKING_LIVE=true; unset ->
# honestly not-active). Every /stake action stays disabled on a no-env deploy until
# both addresses are set to the SAME deployed address and an on-chain read succeeds.
# Staking receives the staker-reward side (50% of $BASIS-side fee generation). These
# rewards are not yield, not passive income, not a guaranteed return; they accrue as
# ERC4626 share-value, not a per-user APY, and are not guaranteed.
BASIS_TOKEN_ADDRESS=                       # the staked asset; empty -> staking pending
BASIS_STAKING_LIVE=true                    # operator assertion the reward tranche is funded
BASIS_STAKING_VAULT_ADDRESS=               # server-side vault address (empty -> pending)
NEXT_PUBLIC_BASIS_STAKING_VAULT_ADDRESS=   # PUBLIC — SAME address; the browser reads vault state
NEXT_PUBLIC_BASE_RPC_URL=                  # optional public Base RPC for browser reads

# Verify the read-only surface once configured (no secret needed):
#   GET /api/staking/status        # vault.readVerified true after a real on-chain read
#   GET /api/launch-status         # staking block: vaultConfigured / vaultLive
# Unstaking is two steps: start a cooldown, then redeem in the withdraw window after
# it matures (miss it -> restart). Defaults 7-day cooldown / 7-day window, owner-set.
# The wallet signs every transaction; Basis never holds keys or signs server-side.

Internal secrets

The internal routes are authorized by a shared secret. Each /api/internal/* route requires a valid INTERNAL_API_SECRET or ADMIN_SECRET; without one the route returns 401/403. Set distinct, high-entropy values in the deployment environment.

# Internal route auth. /api/internal/* require ONE of these; without a valid
# secret the route returns 401/403. Set distinct, high-entropy values.
INTERNAL_API_SECRET=...
ADMIN_SECRET=...

# Protected internal routes:
#   POST /api/internal/settlement/run
#   POST /api/internal/workers/probe
#   POST /api/internal/inference/reconcile

Settlement keeper

Worker-reward settlement runs on a schedule, off the inference hot path, and is dry-run by default. Two pieces, deliberately separated by trust: a scheduled trigger that only prepares a batch (safe on Vercel — it holds no signer), and an operator-run keeper (pnpm settle:rewards) that submits with the signer in a controlled environment. There are no on-chain writes in the inference hot path. Settlement is idempotent — a batchHash settles once.

# Settle accrued worker rewards to Base. Idempotent: a batchHash settles once.
pnpm settle:rewards

# Seed example rewards first (local testing only):
pnpm settle:rewards --demo

# Dry-run until BASIS_REWARD_DISTRIBUTOR_ADDRESS is configured
# (rewardSettlementEnabled() is false until then). The keeper never signs in
# the app or the inference hot path; the operator key is read in memory only at
# execution time and is never logged or committed.

Scheduled trigger (Vercel Cron). The cron is already wired in apps/web/vercel.json and deploys with the app. It issues a GET to the secret-protected /api/internal/settlement/run, which builds a deterministic, idempotent batch and — only when the live gate passes — prepares the unsigned distributor call. It never submits. Set CRON_SECRET in the Vercel project to authenticate the scheduled call.

# apps/web/vercel.json — Vercel reads vercel.json from the project Root
# Directory, which for this project is apps/web (a repo-root vercel.json is
# IGNORED). The scheduled trigger only PREPARES a batch; it never signs/submits.
{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "crons": [
    { "path": "/api/internal/settlement/run", "schedule": "0 0 * * *" }
  ]
}

# Authenticate the cron: set CRON_SECRET in the Vercel project. Vercel then sends
# Authorization: Bearer ${CRON_SECRET} on each scheduled (GET) call and the route
# verifies it (else it falls back to INTERNAL_API_SECRET / ADMIN_SECRET; 503 if
# none is set). CRON_SECRET is server-only and is never echoed or logged.

# Operator intent (advisory; does NOT authorize any send):
BASIS_SETTLEMENT_MODE=dry_run          # dry_run (default) | live  (live = gate #5)
BASIS_SETTLEMENT_CRON_ENABLED=false    # surfaced as cronEnabled; never authorizes a send
BASIS_SETTLEMENT_MIN_BATCH_RAW=        # optional BigInt min total (no floats)
BASIS_SETTLEMENT_MAX_BATCH_SIZE=       # optional max receipts per batch

The five live-settlement gates (ALL required). evaluateSettlementGate() (lib/settlement/gate.ts) returns mode: "live" only when every one of these holds; otherwise it is dry_run with the unmet gates and an honest reason:

1. 1. BASIS_REWARD_DISTRIBUTOR_ADDRESS configured.
2. 2. BASIS_OPERATOR_PRIVATE_KEY present (presence only — the value is never read into any log or response).
3. 3. Base mainnet (BASE_CHAIN_ID === 8453).
4. 4. Persistence is durable (persistenceStatus().durable === true) — a hard blocker until durable Postgres is wired (see Persistence above; it is false today).
5. 5. BASIS_SETTLEMENT_MODE=live explicitly set (opt-in, never the default).

Production smoke tests

After deploying, verify the public surface responds correctly. These reads are safe and need no secrets.

# Models — advertised model list (available reflects backend config).
curl -s https://basis.watch/api/v1/models

# Launch status — what is configured vs pending, as JSON.
curl -s https://basis.watch/api/launch-status

# Inference stats — runtime mode and accounting totals.
curl -s https://basis.watch/api/inference/stats

# Payments — supported tokens + router status (no secrets exposed).
curl -s https://basis.watch/api/payments/supported-tokens

# Payments — request a quote (returns a structured pending response until the
# token + a provider are configured; never a fabricated quote).
curl -s https://basis.watch/api/payments/quote \
  -H "Content-Type: application/json" \
  -d '{"sell_token":"USDC","payer_wallet":"0x0000000000000000000000000000000000000000","credit_amount":"100","slippage_bps":100}'

• GET /api/v1/modelsThe advertised model list. available reflects whether an inference backend is configured.
• GET /api/launch-statusWhat is configured vs pending, as JSON — the same source the status panels read.
• GET /api/inference/statsRuntime mode and accounting totals — confirm the gateway is in the expected mode.

Live vs pending

The panel below is derived from real configuration. A fresh deployment with no addresses set reads honestly as pending across the board.