@grimswap/circuits

ZK-SNARK SDK for privacy-preserving swaps on Uniswap v4.

Deposit ETH, then swap privately through stealth addresses — no link between depositor and recipient.

Install

npm install @grimswap/circuits

Quick Start (10 lines)

import {
  createDepositNote,
  formatCommitmentForContract,
  executePrivateSwap,
  UNICHAIN_SEPOLIA_ADDRESSES,
} from "@grimswap/circuits";

// 1. Create deposit note + deposit on-chain
const note = await createDepositNote(parseEther("1"));
const commitment = formatCommitmentForContract(note.commitment);
// → call GrimPool.deposit(commitment, { value: parseEther("1") })
// → save note.leafIndex from the Deposit event

// 2. Load circuit files (host on your CDN or copy from node_modules)
const wasm = await fetch("/circuits/privateSwap.wasm").then(r => r.arrayBuffer());
const zkey = await fetch("/circuits/privateSwap.zkey").then(r => r.arrayBuffer());

// 3. Execute private swap — builds tree, generates proof, submits to relayer
const result = await executePrivateSwap({
  note,
  recipient: stealthAddress,
  poolKey: {
    currency0: "0x0000000000000000000000000000000000000000",
    currency1: tokenAddress,
    fee: 3000,
    tickSpacing: 60,
    hooks: UNICHAIN_SEPOLIA_ADDRESSES.grimSwapZK,
  },
  zeroForOne: true,
  amountSpecified: -note.amount,
  wasmBuffer: wasm,
  zkeyBuffer: zkey,
});

console.log(result.txHash); // done!

Setup Circuit Files

Copy the WASM and zkey files to your app's public directory:

npx grimswap-copy-circuits public/circuits

Or manually copy from node_modules/@grimswap/circuits/build/.

Step-by-Step Integration

1. Deposit

import {
  createDepositNote,
  formatCommitmentForContract,
  serializeNote,
  GRIM_POOL_ABI,
  UNICHAIN_SEPOLIA_ADDRESSES,
} from "@grimswap/circuits";

const note = await createDepositNote(parseEther("1"));
const commitment = formatCommitmentForContract(note.commitment);

// Deposit on-chain (use viem, ethers, or wagmi)
const tx = await walletClient.writeContract({
  address: UNICHAIN_SEPOLIA_ADDRESSES.grimPool,
  abi: GRIM_POOL_ABI,
  functionName: "deposit",
  args: [commitment],
  value: parseEther("1"),
});

// Save the note — user needs it to withdraw!
// Set leafIndex from the Deposit event
note.leafIndex = depositEvent.args.leafIndex;
const saved = serializeNote(note);
localStorage.setItem("grimswap_note", saved);

2. Add Merkle Root (Testnet Only)

const { fetchDeposits, buildMerkleTree } = await import("@grimswap/circuits");

const commitments = await fetchDeposits();
const tree = await buildMerkleTree(commitments);
const merkleProof = tree.getProof(note.leafIndex);

// Testnet: depositor adds their own root
const rootHex = "0x" + merkleProof.root.toString(16).padStart(64, "0");
await walletClient.writeContract({
  address: UNICHAIN_SEPOLIA_ADDRESSES.grimPool,
  abi: GRIM_POOL_ABI,
  functionName: "addKnownRoot",
  args: [rootHex],
});

3. Private Swap

Use executePrivateSwap() (recommended) or build manually:

import {
  generateProofFromBuffers,
  formatProofForContract,
  submitToRelayer,
  getRelayerInfo,
} from "@grimswap/circuits";

// Get relayer info
const relayer = await getRelayerInfo();

// Generate proof
const { proof, publicSignals } = await generateProofFromBuffers(
  note, merkleProof,
  {
    recipient: stealthAddress,
    relayer: relayer.address,
    relayerFee: relayer.fee,
    expectedAmountOut: note.amount,
  },
  wasmBuffer, zkeyBuffer
);

// Format and submit
const formatted = formatProofForContract(proof, publicSignals);
const result = await submitToRelayer(
  undefined, // uses default relayer URL
  { a: formatted.pA, b: formatted.pB, c: formatted.pC },
  formatted.pubSignals,
  {
    poolKey,
    zeroForOne: true,
    amountSpecified: (-note.amount).toString(),
    sqrtPriceLimitX96: "4295128740",
  }
);

API Reference

High-Level

Function	Description
executePrivateSwap(params)	Complete private swap in one call
fetchDeposits(rpcUrl?)	Fetch all deposit commitments from GrimPool
fetchDepositEvents(rpcUrl?)	Fetch deposits with full metadata
getDepositCount(rpcUrl?)	Get current deposit count

Proof Generation

Function	Environment	Description
generateProofFromBuffers()	Browser + Node	Generate proof from in-memory buffers
generateProof()	Node.js only	Generate proof from file paths
formatProofForContract()	Both	Format proof for Solidity

Commitment & Merkle Tree

Function	Description
createDepositNote(amount)	Create deposit note with random secret + nullifier
formatCommitmentForContract(commitment)	Format as bytes32 for deposit tx
serializeNote(note) / deserializeNote(str)	Save/restore note
buildMerkleTree(commitments)	Build Poseidon Merkle tree

Relayer Client

Function	Description
submitToRelayer(url, proof, signals, swapParams)	Submit proof for execution
getRelayerInfo(url?)	Get relayer address and fee
checkRelayerHealth(url?)	Check if relayer is online

Stealth Addresses (ERC-5564)

Function	Description
generateStealthKeys()	Generate spending + viewing key pair
generateStealthAddress(metaAddress)	Derive one-time stealth address
scanAnnouncements(params)	Scan chain for payments to you

Claiming from Stealth Addresses

Function	Description
claimStealthTokens(params)	Sweep ERC20 tokens from stealth address to your wallet
getStealthBalance(...)	Check token balance at stealth address
getStealthEthBalance(...)	Check ETH balance (gas availability)

Constants & ABIs

import {
  UNICHAIN_SEPOLIA_ADDRESSES,  // All contract addresses
  GRIM_POOL_ABI,               // deposit, isSpent, getLastRoot, addKnownRoot
  GRIM_SWAP_ROUTER_ABI,        // executePrivateSwap
  GRIM_SWAP_ZK_ABI,            // Hook events
  GROTH16_VERIFIER_ABI,        // verifyProof
  RELAYER_DEFAULT_URL,          // https://services.grimswap.com
} from "@grimswap/circuits";

Types

import type {
  DepositNote,
  MerkleProof,
  SwapParams,
  PoolKey,
  PrivateSwapParams,
  RelayerRequest,
  RelayerResponse,
  DepositEvent,
  Groth16Proof,
  ContractProof,
  StealthKeys,
  ClaimParams,
  ClaimResult,
  GrimAddresses,
  ChainConfig,
} from "@grimswap/circuits";

Contract Addresses (Unichain Sepolia)

Contract	Address
GrimPool	0xEAB5E7B4e715A22E8c114B7476eeC15770B582bb
GrimSwapZK (Hook)	0x3bee7D1A5914d1ccD34D2a2d00C359D0746400C4
GrimSwapRouter	0xC13a6a504da21aD23c748f08d3E991621D42DA4F
Groth16Verifier	0xF7D14b744935cE34a210D7513471a8E6d6e696a0
PoolManager	0x00B036B58a818B1BC34d502D3fE730Db729e62AC

Pool Configuration

Fee/TickSpacing

Fee	TickSpacing	Use Case
500	10	Stable pairs
3000	60	Most pairs
10000	200	Exotic pairs

sqrtPriceX96 for ETH/USDC

For ETH = currency0, USDC = currency1 (6 decimals):

• $2000/ETH: 3543191142285914205922034
• $3000/ETH: 4339505028714986015908034

Formula: sqrt(price_usdc * 10^6 / 10^18) * 2^96

Integration Flow

User                    Frontend                  GrimPool          Relayer          Router
 |                         |                         |                 |                |
 |  deposit 1 ETH          |                         |                 |                |
 |------------------------>|  deposit(commitment)     |                 |                |
 |                         |------------------------>|                 |                |
 |                         |                         |                 |                |
 |  swap privately         |                         |                 |                |
 |------------------------>|  executePrivateSwap()    |                 |                |
 |                         |  1. fetchDeposits()      |                 |                |
 |                         |  2. buildMerkleTree()    |                 |                |
 |                         |  3. generateProof()      |                 |                |
 |                         |  4. submitToRelayer() ---|---------------->|                |
 |                         |                         |                 |                |
 |                         |                         |  executePrivateSwap              |
 |                         |                         |<----------------|--------------->|
 |                         |                         |                 |                |
 |                         |  { txHash, success }     |                 |                |
 |                         |<-----------------------------------------|                |
 |                         |                         |                 |                |
 |  tokens at stealth addr |                         |                 |                |
 |<------------------------|                         |                 |                |

4. Claim Tokens from Stealth Address

After a private swap, tokens land at a stealth address. The relayer automatically funds it with ETH for gas. Use claimStealthTokens() to sweep tokens to your wallet:

import {
  claimStealthTokens,
  getStealthBalance,
} from "@grimswap/circuits";

// Check balance first
const { stealthAddress, balance } = await getStealthBalance(
  keys.spendingPrivateKey,
  keys.viewingPrivateKey,
  stealth.ephemeralPubKey,
  outputTokenAddress,
);

console.log(`${balance} tokens at ${stealthAddress}`);

// Sweep tokens to your wallet
const result = await claimStealthTokens({
  spendingPrivateKey: keys.spendingPrivateKey,
  viewingPrivateKey: keys.viewingPrivateKey,
  ephemeralPubKey: stealth.ephemeralPubKey,
  tokenAddress: outputTokenAddress,
  toAddress: "0xYourWallet...",
});

console.log(result.txHash); // claimed!

No ethers/viem dependency required — works via raw JSON-RPC.

Circuit Architecture

Public Inputs:                          Private Inputs:
  merkleRoot                              secret (256-bit random)
  nullifierHash                           nullifier (256-bit random)
  recipient (stealth address)             amount (deposit amount)
  relayerFee                              pathElements[20] (siblings)
                                          pathIndices[20] (directions)

Constraints:
  1. commitment = Poseidon(nullifier, secret, amount)
  2. MerkleProof(commitment, path) == merkleRoot
  3. nullifierHash == Poseidon(nullifier)

Building Circuits from Source

npm install
npm run compile           # Compile Circom circuits
npm run setup             # Trusted setup (Powers of Tau)
npm run generate-verifier # Solidity verifier

Requires Circom 2.1.x and Node.js >= 18.

License

MIT