| name | dust-protocol |
| description | Activate when the user works with Dust Protocol, stealth transfers, stealth addresses, privacy swaps, DustPool, DustSwap, DustPaymaster, .tok names, ERC-5564, ERC-6538, ZK privacy pools, Poseidon Merkle trees, gasless claims, ERC-4337 stealth accounts, or private payments on Tokamak.
|
| license | MIT |
| metadata | {"author":"tokamak-network","version":"1.0.0"} |
Dust Protocol
Private finance protocol on EVM chains. Two primitives: stealth transfers (send tokens without on-chain link) and privacy swaps (trade ETH/USDC without traceability via Uniswap V4 hooks + ZK proofs).
Source: https://github.com/tokamak-network/dust-protocol
Architecture
Dust Protocol
│
├── Stealth Transfers
│ ├── .tok name registry (on-chain)
│ ├── ECDH key derivation (secp256k1, ERC-5564/6538)
│ ├── Gasless claims via ERC-4337 (DustPaymaster)
│ └── Sub-addresses (sub.alice.tok)
│
├── DustPool (Privacy Pool for Transfers)
│ ├── Poseidon Merkle tree (depth 20, ~1M leaves)
│ ├── Groth16 proof (BN254), ~5,900 constraints
│ └── Consolidate multiple stealth wallets → single address
│
└── DustSwap (Privacy Swaps)
├── DustSwapPoolETH + DustSwapPoolUSDC
├── Uniswap V4 hook (beforeSwap/afterSwap)
├── ZK proof verification atomic with swap
└── Output to stealth address (no link to deposit)
Key Concepts
Stealth Key Derivation
wallet_signature = sign("Dust Protocol stealth key", walletAddress)
entropy = PBKDF2(signature + PIN, salt, 100000 iter, SHA-512)
spendKey = entropy[0:32] // secp256k1 scalar
viewKey = entropy[32:64] // secp256k1 scalar
metaAddress = (spendKey*G, viewKey*G) // registered on ERC-6538
Both wallet signature and PIN are required. Keys stored in React ref only — never serialized or sent to server.
ZK Proof Flow (DustPool / DustSwap)
Deposit: commitment = Poseidon(Poseidon(nullifier, secret), amount) → inserted into on-chain Poseidon Merkle tree.
Withdraw/Swap: Browser generates Groth16 proof that commitment ∈ tree without revealing which leaf. nullifierHash = Poseidon(nullifier, nullifier) prevents double-spend.
Gasless Claims (ERC-4337)
1. Scanner detects stealth payment via ERC-5564 announcement
2. Browser derives stealth private key (ECDH + spendKey)
3. POST /api/bundle → DustPaymaster signs for gas
4. Browser signs userOpHash locally (key never leaves browser)
5. EntryPoint deploys StealthAccount (CREATE2) + drains funds — one tx
Common Mistakes
| Mistake | Fix |
|---|
| Keys in localStorage/state | Keys must stay in React ref only — never serialize |
| Missing PIN on key derivation | Both wallet signature AND PIN are required for stealth keys |
| Amount correlation in DustSwap | Use fixed denominations only — variable amounts enable deanonymization |
| Forgetting nullifier check | Always verify nullifierHash is not spent before attempting withdrawal |
| Calling DustSwap on Thanos | DustSwap is Ethereum Sepolia only — not deployed on Thanos Sepolia |
Contract Addresses (Sepolia)
Ethereum Sepolia (11155111)
| Contract | Address |
|---|
| ERC5564Announcer | 0x64044FfBefA7f1252DdfA931c939c19F21413aB0 |
| ERC6538Registry | 0xb848398167054cCb66264Ec25C35F8CfB1EF1Ca7 |
| StealthNameRegistry | 0x4364cd60dF5F4dC82E81346c4E64515C08f19BBc |
| StealthAccountFactory | 0xc73fce071129c7dD7f2F930095AfdE7C1b8eA82A |
| DustPaymaster | 0x20C28cbF9bc462Fb361C8DAB0C0375011b81BEb2 |
| DustPool | 0xc95a359E66822d032A6ADA81ec410935F3a88bcD |
| DustSwapPoolETH | 0x52FAc2AC445b6a5b7351cb809DCB0194CEa223D0 |
| DustSwapPoolUSDC | 0xc788576786381d41B8F5180D0B92A15497CF72B3 |
| DustSwapHook | 0x09b6a164917F8ab6e8b552E47bD3957cAe6d80C4 |
Thanos Sepolia (111551119090)
| Contract | Address |
|---|
| ERC5564Announcer | 0x2C2a59E9e71F2D1A8A2D447E73813B9F89CBb125 |
| ERC6538Registry | 0x9C527Cc8CB3F7C73346EFd48179e564358847296 |
| StealthNameRegistry | 0x0129DE641192920AB78eBca2eF4591E2Ac48BA59 |
| DustPool | 0x16b8c82e3480b1c5B8dbDf38aD61a828a281e2c3 |
DustSwap not yet deployed on Thanos Sepolia.
Full addresses: See references/contract-addresses.md
Project Structure
dust-protocol/
├── src/
│ ├── app/
│ │ ├── dashboard/ # Balance + pool UI
│ │ ├── onboarding/ # PIN setup + name registration
│ │ ├── swap/ # Privacy swaps
│ │ ├── pools/ # Pool stats
│ │ ├── pay/[name]/ # Public pay page (.tok names)
│ │ └── api/
│ │ ├── bundle/ # ERC-4337 UserOp build + submit
│ │ ├── resolve/[name] # Stealth address generation
│ │ ├── pool-deposit/ # DustPool deposit
│ │ └── pool-withdraw/ # ZK-verified withdrawal
│ ├── lib/
│ │ ├── stealth/ # ECDH cryptography
│ │ ├── dustpool/ # Poseidon, Merkle tree, snarkjs
│ │ └── swap/zk/ # Privacy swap proof gen
│ └── hooks/
│ ├── stealth/ # useStealthScanner, useUnifiedBalance
│ └── swap/ # useDustSwap, usePoolQuote
├── contracts/
│ ├── wallet/ # StealthWallet + StealthAccount
│ ├── dustpool/ # DustPool + MerkleTree + Verifier
│ │ └── circuits/ # DustPoolWithdraw.circom
│ └── dustswap/ # DustSwapHook + Pools
│ └── circuits/ # PrivateSwap.circom
├── relayer/ # Standalone relayer service
├── subgraph/ # The Graph indexing
└── public/
├── zk/ # DustPool ZK assets (WASM + zkey)
└── circuits/ # DustSwap ZK assets
Tech Stack
| Technology | Purpose |
|---|
| Next.js 14, React 18 | Frontend |
| wagmi + viem + ethers v5 | Blockchain |
| circom + snarkjs | ZK proofs (Groth16, BN254) |
| Foundry (Solidity 0.8.x) | Smart contracts |
| Uniswap V4 | Privacy swap hooks |
| ERC-4337 | Gasless stealth claims |
| The Graph | Name + announcement indexing |
Security Model
| Layer | Mechanism |
|---|
| Stealth addresses | ECDH on secp256k1 — only recipient can derive private key |
| Key derivation | PBKDF2 (SHA-512, 100k iter) over wallet signature + PIN |
| Key isolation | React ref only, never serialized |
| Gasless claim | Client signs locally, server relays — key never leaves browser |
| ZK pool privacy | Groth16 — withdrawal is cryptographically unlinkable to deposit |
| Double-spend | nullifierHash = Poseidon(nullifier, nullifier) stored on-chain |
| Amount correlation | Fixed denominations in DustSwap pools |
Quick Start
npm install
cp .env.example .env.local
npm run dev
Standards
- ERC-5564: Stealth Address Announcements
- ERC-6538: Stealth Meta-Address Registry
- ERC-4337: Account Abstraction (gasless claims)
Related Skills
- tokamak-contracts: Tokamak contract addresses and proxy patterns
- thanos-l2: Thanos L2 where Dust Protocol is also deployed
