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

Contract Addresses (Sepolia)

Ethereum Sepolia (11155111)

Thanos Sepolia (111551119090)

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

Security Model

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