VeilGuard

Know what the chain learns before you sign.

VeilGuard is a pre-sign privacy simulator and policy engine for STRK20. It explains which transaction fields will be public, estimates timing and amount linkability from live Starknet mainnet pool activity, recommends safer alternatives, and only then hands the action to a compatible wallet.

Built for IDEA-25 in the STRK20 Private Sprint. The infrastructure path also advances IDEA-26: the engine and report are designed to become a drop-in signing guard for other Starknet apps.

Why this exists

“Private transaction” is not one guarantee. In STRK20 today:

Action	Public	Private
Shield	Sender, token, exact amount, time	Future note owner and spend path
Note-to-note transfer	Pool activity, encrypted note/nullifier, time	Sender, recipient, token amount, source note
Unshield	Destination, token, exact amount, time	Initiating pool user, source note, deposit link
Private DeFi	Execution amount and time	User identity behind the shared anonymizer

VeilGuard surfaces that boundary before an irreversible signature instead of after an explorer has indexed it.

Working prototype

• Live mainnet event scan against the deployed STRK20 pool
• STRK20-aware reports for shield, private transfer, and unshield intents
• Four explainable dimensions: identity, amount, timing, and recent crowd
• Field-level “Public / Encrypted” disclosure map
• Evidence and a safer next action for every material finding
• Read-only wallet capability probe
• Real execution through WalletAccountV6.strk20InvokeTransaction after review
• Pure TypeScript risk engine with unit tests
• Responsive, no-login reference interface

Pool: 0x040337…ffe812a

Quick start

npm install
cp .env.example .env.local # optional; public RPC defaults work out of the box
npm run dev

Open http://localhost:3000. Analysis does not require a wallet. Signing requires a Starknet wallet that implements the STRK20 Wallet API, currently best tested with Ready, on mainnet.

npm test
npx tsc --noEmit
npm run build

Architecture

Transaction intent
      │
      ├── action semantics ───────────────┐
      │                                   │
      └── recent STRK20 mainnet events ───┤
                                          ▼
                                  risk-engine.ts
                                          │
                         score + evidence + safer action
                                          │
                                          ▼
                                  user review gate
                                          │
                                          ▼
                            STRK20 Wallet API signing

Important files:

• src/lib/privacy/risk-engine.ts — deterministic, side-effect-free scoring and findings
• src/lib/privacy/starknet-source.ts — bounded mainnet event scanner and parser
• src/app/api/pool-context/route.ts — public mainnet telemetry boundary; no user intent crosses it
• src/app/components/client/PrivacySimulator.tsx — reference composition/review/sign flow
• docs/PRODUCT.md — product definition and threat model
• docs/IMPLEMENTATION_PLAN.md — sprint plan and submission checklist

Scoring model

The 0–100 result combines:

• identity protection: 35%
• amount confidentiality: 30%
• timing safety: 20%
• recent private-pool crowd: 15%

Recent amount cohorts use public same-token deposits and withdrawals within ±10%. Timing checks look for a same-token public deposit from the connected address inside the 5,000-block scan window. Crowd is a log-scaled count of unique transactions carrying encrypted-note, note-use, open-note, or external-invoke activity.

The score is an explainable heuristic, not a cryptographic proof and not a formal anonymity-set calculation. The UI says this directly. See the full methodology.

Privacy-preserving data flow

The browser fetches GET /api/pool-context, which returns only already-public pool events. The transaction intent—sender, recipient, token, and amount—is analyzed locally by the pure risk engine and is never posted to VeilGuard. The resulting report stays in the current browser session.

Apps can import the same engine directly and supply their own public context source. The result contains the overall score, grade, four dimensions, public/encrypted fields, cohort evidence, findings, recommendations, methodology, and source quality.

Known limitations

• The current composer covers deposits, private transfers, and withdrawals; swap/lending anonymizer analysis is next.
• It analyzes on-chain linkability, not IP, browser, RPC, prover, or wallet telemetry.
• A 5,000-block bounded scan is a recent-activity proxy, not the pool’s lifetime anonymity set.
• Amount similarity is intentionally simple and explainable; it does not yet model token price or address-cluster heuristics.
• A compatible wallet and user confirmation are required for real transactions. VeilGuard never handles viewing keys or private keys.

Sprint submission

Before the deadline, update strk20.json with at least three successful mainnet transactions that touched the STRK20 pool, plus the demo URL and three-minute video. The registration PR also needs the public repository URL and Telegram username(s).

Credits and license

The Wallet API connection path was bootstrapped from the MIT-licensed STRK20 starter kit. VeilGuard is MIT licensed. It is experimental software, not a security guarantee or financial advice.