veilquota

# VeilQuota

VeilQuota is a pre-release Zcash gateway for privacy-preserving prepaid access to metered APIs and
MCP tools. Its intended flow is a shielded ZEC purchase followed by blind, single-use credits, so
later requests do not carry a reusable account, API key, payment proof, or session credential that
directly links them together.

This repository contains the reproducible engineering baseline and that flow. It runs end to end
on public testnet and as a capped, unaudited mainnet beta: one real shielded mainnet payment was
issued as a 100-credit booklet and spent on a paid OCR call (2026-10-07).

## Product boundary

Accountless API and MCP payments already exist through systems such as x402, MCPay, and Latinum.
Zcash payment infrastructure also exists through projects such as CipherPay and zpay. VeilQuota
therefore does not claim category uniqueness.

The narrower VeilQuota wedge is the combination of shielded ZEC settlement, blind single-use
credits for later API/MCP use, and exact retry behavior when a response is lost. This differs from
attaching a payment proof to every request and from using one reusable prepaid-session credential
across multiple calls. Kagi Privacy Pass and Nym ticketbooks provide adjacent evidence that users
and services can value separating payment identity from later usage.

`booklet_v1` is a VeilQuota credit-pack profile built from RFC 9578 publicly verifiable
Blind-RSA tokens. Issuance travels in the generic batch wire format of the IETF Privacy Pass
batched-tokens draft (`GenericBatchTokenRequest`/`GenericBatchTokenResponse`, token type
`0x0002`), checked byte for byte against independent known-answer vectors
(`vectors/batched-tokens-blind-rsa.json`). The draft is not yet an RFC, the pack is all-or-nothing
(partial issuance is rejected), and the profile has not received an
independent security audit, and must not be presented as one.

The current buyer, competition, business-model, unit-economics, and validation hypotheses are
documented in [docs/business.md](docs/business.md).

## Implemented so far

- pinned Rust and Node.js toolchains;
- Rust and TypeScript workspaces with committed lockfiles;
- a shared capability-status contract and one focused serialization test;
- distinct public, purchase-plane, and redemption-plane UUIDv4 identifier types in Rust and TypeScript;
- explicit Zatoshi and merchant-credit units with checked arithmetic in Rust and TypeScript;
- a bounded, schema-checked `VQCE` binary record codec with strict version, field, ordering, UTF-8/NFC, and size rules in Rust and TypeScript;
- typed SHA-256 domain-separated digests over validated `VQCE` records, using matching Rust and WebCrypto vectors;
- validated product, route/price, issuer, privacy, and deployment manifest models in Rust and TypeScript, including fixed public terms, strict origins, bounded validity, environment/network binding, and immutable VQCE field layouts;
- strict Ed25519 envelopes over schema-validated `VQCE` payloads, binding the manifest kind, signer-key version, and monotonic manifest version in Rust and Web Crypto;
- a strict, versioned signed-manifest binary transport with matching Rust and TypeScript parsers and trailing-byte rejection;
- typed signed-manifest verification that reconstructs validated domain objects only after authentication and requires byte-exact canonical re-encoding;
- fail-closed manifest-set activation that verifies product, route/price, issuer, privacy, deployment, environment, network, origin, profile, limit, signer-version, digest, and validity consistency;
- trust-root key selection with revoked-key rejection plus per-kind manifest rollback/equivocation detection; callers must durably persist its accepted high-water marks;
- explicit engine/epoch/profile bindings and profile-tagged opaque artifacts, preventing cross-engine decoding;
- issuance, wallet-spend, and redemption state machines that reject skipped, backwards, and unsafe timeout/recovery edges;
- stable public-safe error classifications and a machine-readable public/purchase/redemption field policy; and
- an SQLx PostgreSQL store crate with separately named purchase and redemption database pools plus embedded, plane-specific migrations;
- durable purchase-plane blind-issuance persistence: an authorization lock, exact blinded-request match, encrypted response/key-version storage, transition records, and one transactional outbox event;
- atomic finalized-payment authorization that binds one stable shielded-output evidence digest to one exact blinded-request batch, supports exact retries, and rejects payment reuse;
- durable redemption-plane operation journaling: atomic keyed-nullifier reservation, encrypted request/key-version storage, transition records, and exact-retry versus changed-replay decisions;
- fenced purchase- and redemption-plane outbox claims with bounded leases, monotonic fencing, compare-and-set acknowledgement, and a static cross-plane schema privacy lint;
- an ignored, disposable-PostgreSQL integration test that proves payment-to-batch binding, issuance/replay, all-or-nothing nullifier reservation, and stale-worker fencing against real PostgreSQL;
- a pinned RFC 9578 public Blind-RSA `booklet_v1` client with a local issue/finalize/redeem/replay-rejection lifecycle test; the selected library is not independently audited by this project;
- a view-only Ironwood payment detector (`crates/veilquota-ironwood`) on the NU7 pre-release librustzcash crates: each quote pays a fresh Orchard-only Unified Address derived from its quote ID, with a text memo (`VQ1:` + base64url) that mobile wallets can send; a buyer-named txid is accepted only if every configured lightwalletd endpoint returns the same bytes, height, and block, the block contains it, and it decrypts to exactly one incoming output with the quoted receiver, amount, and memo inside the quote window with enough confirmations. `veilquota-checkout merchant-key|ironwood-quote|ironwood-observe` drive it; the merchant recovery phrase is shown once and only the viewing key is stored. Tested against a real mainnet Ironwood transaction, and a real 0.0005 ZEC payment from the Zodl wallet (txid `0e7a8cc1ccd511a2b215c4db620583cf61096593766214b6c137b50f6b099bb1`, height 3509373) was accepted with all three endpoints agreeing. Mainnet defaults to three lightwalletd hosts run by different operators (zec.rocks, Cake Wallet, 0xRPC), and all three agreed on that payment;
- a capped mainnet beta, live since 2026-10-07 with its own issuer origin (`veilquota-issuer-mainnet`) and a 500-credit cap; one 100-credit booklet has been issued and finalized, and a separate `veilquota-gateway-mainnet` (own runtime identity and refund key) took buyer A from 100 to 87 credits for one real OCR result with a `Payment-Receipt`; both mainnet services are reproduced by `deploy/cloud-run/deploy-mainnet.sh`. Mainnet needs `VEILQUOTA_ENABLE_MAINNET=1`, packs are capped at 0.0013 ZEC, a `mainnet_beta` issuer epoch is a distinct manifest environment, and mainnet issuance runs under a per-epoch issuance control (`veilquota-issue control EPOCH_DIR enable CAP | disable | status`) whose row is locked during authorization, so concurrent purchases cannot exceed the cap and `disable` stops new purchases at once;
- config-driven priced routes (`VEILQUOTA_ROUTES`, rendered from `deploy/cloud-run/gateway/routes.template.json`) sharing one credit epoch: OCR (13 credits), private web search through Brave's LLM Context API (`/v1/tools/search`, 2 credits; bounded JSON queries, refused before any charge if malformed), and attested encrypted inference through Tinfoil (`/v1/inference/chat/completions`, 4 credits). For inference the wallet agent verifies the enclave's attestation (pinned `tinfoilsh/confidential-model-router` release) and seals the request once with EHBP to its attested HPKE key; the gateway prices and relays ciphertext plus the bound `Ehbp-Encapsulated-Key` and `X-Tinfoil-Model` headers, adds the API key, and replays the committed ciphertext and `Ehbp-Response-Nonce` on exact retry, so a lost answer is recovered and decrypted locally. Provider keys are mounted from Secret Manager. The MCP server exposes `private_search` and `private_chat` beside the OCR tools, and paid tools are annotated as irreversible (`destructiveHint`). Third-party routes commit their first timeout or oversized reply as a refunded failure, so a billed provider call is never re-run, and a paid answer that won't decrypt settles the spend instead of locking the wallet. `veilquota-checkout call WALLET GATEWAY MAX_CREDITS` runs one agent request read from stdin. Brave sees search queries but not who asked. Live on the mainnet gateway 2026-10-07: one paid search (2 credits) and one attested, encrypted `gpt-oss-120b` chat (4 credits), buyer A 87 → 85 → 81 (`docs/evidence/priced-routes-mainnet-2026-10-07.md`);
- unlinkable refunds: a spend carries one blind refund request per credit under the gateway's published refund key (a `PrivacyPass-Reverse` header holding a generic batch, following the Privacy Pass reverse-flow pattern without claiming conformance to that individual draft). When the upstream fails, or its last allowed attempt still has no answer, the gateway commits a uniform `502`, sends no receipt, and blind-signs exactly those requests. The wallet swaps the locked credits for the same number of fresh ones and never stays blocked. Refunds are bound into the operation digest, so the same credits cannot buy a second refund. Exact retries replay identical signatures. Presentations never mix purchased and refunded keys, and the wallet pins the refund key on first use. This is proven on real PostgreSQL in `scripts/verify.sh --database`. The refund key lives only in the redemption plane (Secret Manager) and the deployed gateway publishes it in every challenge;
- an OpenAI-compatible endpoint in the wallet agent: `veilquota-checkout agent WALLET SOCKET GATEWAY MAX_CREDITS 8787` also serves `GET /v1/models` and