🛡️ DarkCircle Simulation
x402 payment privacy for Quai Network: shielded-pool settlement in WQUAI and WQI,
with Private Proof of Innocence (PPOI) compliance, ephemeral payees and a voice agent.
Source: x402tumbler/ · Route: /x402tumbler/
What is real and what is simulated
| Layer | Status |
|---|---|
| Quai network rules (zones, chain ids, address validation, checksums, access lists) | Real checked against rpc.quai.network/cyprus1 |
| WQUAI / WQI registry (addresses, decimals, WQI's EIP-2612 domain) | Real pnpm verify:quai re-checks them live |
| Quai JSON-RPC client, access-list preparation, on-chain payment verifier | Real code read/prepare only; never signs or broadcasts |
| x402 protocol, spending policy, gateway, ephemeral payees, audit engine, CLI, UI | Real code running against the simulated ledger |
| Blockchain, token contracts, shielded pools, relayer | Simulation in-memory; nothing deployed on Quai |
| Voice agent page | Real Quai your wallet signs every step; public operations only |
| Groth16 circuit and pool contract | Reference unaudited, dev ceremony, deployed nowhere |
Everything up to the chain boundary is Quai-correct and testable; the pools themselves are a
model. Do not point this at real funds until the open items in x402tumbler/AUDIT.md
(O-1, O-2 and O-14 to O-17) are closed.
Two pools, both live
WQUAI and WQI each have their own shielded pool, relayer, merchant gateway, treasury notes and accounting journal on one shared ledger. A WQUAI note can never be spent from the WQI pool; custody and anonymity sets are per asset.
| WQUAI | WQI | |
|---|---|---|
| Obtain | wraps native QUAI (deposit() / withdraw()) | issued by its own contract; no wrap |
| EIP-2612 permit | no | yes |
| Sweeping a payee address | needs the relayer to fund QUAI gas | gasless: payee signs a permit, relayer submits |
| Decimals | 18 | 18 |
Quick start
pnpm test # full suite (915 tests)
pnpm lint # tsc --noEmit
pnpm verify:quai # live, read-only check of Cyprus-1, WQUAI, WQI
pnpm ui # operator console on http://127.0.0.1:5180 (simulation)
pnpm voice:setup # shows which speech model the voice agent needs
pnpm voice:setup -- --yes # downloads it once (~145 MB); speech never leaves this machine
# durable, encrypted state (passphrase from the environment, never a flag)
DARKCIRCLE_STORE_PASSPHRASE='twelve or more characters' pnpm ui --data-dir ./.darkcircle-data
CLI
node bin/darkcircle.ts shield --amount 10 # deposit into the pool
node bin/darkcircle.ts invoice --amount 2.5 # x402 invoice, single-use payee
node bin/darkcircle.ts pay --recipient 0x0037...8d --amount 1.25
node bin/darkcircle.ts sweep --invoice <id>
node bin/darkcircle.ts audit --format json
node bin/darkcircle.ts checklist unshield --address 0x0037...8d --amount 5
DARKCIRCLE_ASSET=WQI node bin/darkcircle.ts pay --recipient 0x0037...8d --amount 1.25
Amounts are token amounts: 5 means five tokens; base units need a
u suffix (5000000000000000000u). The CLI runs one asset per process
(DARKCIRCLE_ASSET, default WQUAI); the UI runs both.
Operator console
pnpm ui serves a local console, dark by default with a light theme behind the
sun/moon button. A sidebar switches between Overview, Notes &
events, Invoices and Journal, and the overview has a
pools overview plus modals for Shield, Send,
Receive, Sweep, Audit export and a stand-alone
Checklist. Each modal is three steps — details with a live pre-flight
checklist, review, result — and the server re-runs the same checklist on every action, so
the page cannot skip a gate.
The server binds to loopback only, checks Host and Origin, requires a
per-process session token, caps bodies at 64 KiB, serves a CSP that forbids inline script and
third-party origins, and never returns keys.
On the hosted site there is no local API, so the page shows a "Static preview" banner,
switches its actions off and makes no API calls. Run pnpm ui locally for the real
console.
Voice agent (real Quai)
The Voice agent page (sidebar, marked LIVE) turns spoken or typed commands into real Cyprus-1 (or Orchard) transactions that your wallet (Pelagus or Blip) signs after you confirm each one. A red banner says so whenever the page is open.
| Say | It does |
|---|---|
| "what's my balance" | Reads QUAI, WQUAI and WQI balances of your connected wallet |
| "wrap 5 QUAI", "unwrap 2.5 WQUAI" | Calls WQUAI's deposit() / withdraw() |
| "send 10 WQUAI to Acme" | Transfers to a saved contact, never a spoken address |
| "buy the analytics report" | Reads a saved service's x402 challenge, pays the invoice, collects the resource |
| "confirm 4 1 7", "cancel" | Confirms or drops the pending plan |
| "help", "contacts", "services" | Lists what it knows |
The grammar is deterministic and runs offline — there is no language model guessing what you meant. Every spend goes: plan (access list + gas estimate, refused early if it would fail) → read-back with a 3-digit code (3-minute TTL) → your wallet signs → the agent verifies the receipt against the plan. Spending limits are per asset, per action (default 25) and per day (default 100).
Speech stays on this machine by default: recordings are transcribed by a local faster-whisper
worker (local_files_only=True) and deleted. Shielded payments are refused by voice
on purpose, because the pools are not deployed.
Durable state
With --data-dir and DARKCIRCLE_STORE_PASSPHRASE the server keeps
AES-256-GCM encrypted snapshots (key via scrypt, N = 2^17; atomic writes; newest five kept).
Recovery takes the newest snapshot that authenticates and passes coherence checks
(Merkle root rebuilt, pool solvency, journal reconciliation, supply equals balances). A key,
network or asset mismatch refuses to start rather than starting empty over someone else's store.
If the passphrase is lost the snapshots cannot be read.
Trust modes
The pool and the payment gateway each run in verified (default; checks proofs and
receipts) or trusted-harness (pre-audit behaviour for the adversarial suites only).
trusted-harness is never a safe configuration and is reported as a failing blocker
by the checklist and a red chip in the UI.