dust-protocol

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
# Set RELAYER_PRIVATE_KEY (required)
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