DarkCircle Suite Docs
Docs / DarkCircle

🛡️ 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

LayerStatus
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 verifierReal code read/prepare only; never signs or broadcasts
x402 protocol, spending policy, gateway, ephemeral payees, audit engine, CLI, UIReal code running against the simulated ledger
Blockchain, token contracts, shielded pools, relayerSimulation in-memory; nothing deployed on Quai
Voice agent pageReal Quai your wallet signs every step; public operations only
Groth16 circuit and pool contractReference unaudited, dev ceremony, deployed nowhere
Before real funds

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.

WQUAIWQI
Obtainwraps native QUAI (deposit() / withdraw())issued by its own contract; no wrap
EIP-2612 permitnoyes
Sweeping a payee addressneeds the relayer to fund QUAI gasgasless: payee signs a permit, relayer submits
Decimals1818

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.

Static hosting

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.

SayIt 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.