@cloakedxyz/clkd-privacy-pools

Key derivation, proof generation, and recovery tools for 0xbow Privacy Pools integration in Cloaked.

What this does

• Derives Privacy Pools secrets deterministically from a wallet signature (nothing to store)
• Scans the chain for deposits and matches them to a wallet's key material
• Generates ZK proofs for withdrawal and ragequit (commitment proofs)
• Queries the ASP API for deposit review status and Merkle data
• Calculates deposit fees from on-chain config

Install

pnpm add @cloakedxyz/clkd-privacy-pools

Usage

import {
  deriveMnemonic,
  deriveMasterKeys,
  deriveDepositSecrets,
  computePrecommitment,
  scanPoolEvents,
  getChainConfig,
} from '@cloakedxyz/clkd-privacy-pools';

// Derive PP secrets from a wallet signature
const mnemonic = await deriveMnemonic(signature);
const masterKeys = deriveMasterKeys(mnemonic);
const secrets = deriveDepositSecrets(masterKeys, poolScope, 0n);
const precommitment = computePrecommitment(secrets.nullifier, secrets.secret);

// Scan the chain for deposits
const config = getChainConfig(11155111); // Sepolia
const { depositsByPrecommitment } = await scanPoolEvents(
  publicClient,
  config.pools['ETH'].address,
  config.startBlock,
  latestBlock
);

Amount Precision

Privacy Pools emits deposit and withdrawal values in public on-chain events. Privacy Pools v1 uses a coarser deposit amount grid for the assets Cloaked supports: USDC, USDT, and ETH use 5 decimals for actual deposited event amounts. Relayed integrations should keep new deposit values on that same grid so a user does not stand out as the only account with extra decimal precision. Activity displays may render fewer decimals; that is presentation, not the amount rule.

These helpers encode that public amount convention. They are not a protocol or circuit constraint, and unsupported token symbols fail closed.

import {
  floorPrivacyPoolAmount,
  isPrivacyPoolAmountAligned,
} from '@cloakedxyz/clkd-privacy-pools';

const alignedDepositValue = floorPrivacyPoolAmount(netDepositValue, 6, 'USDC');
const isAligned = isPrivacyPoolAmountAligned(userDepositValue, 6, 'USDC');

For user-entered exact amounts, validate alignment and ask the user to adjust instead of silently changing the amount. For new max/all deposits, floor down to the grid before creating the deposit so every new Deposited value is aligned. Withdrawals can continue to use raw commitment amounts; once deposits are aligned, newly-created balances naturally stay on the same grid.

Supported chains

| Chain | ID | ASP API | | -------- | -------- | ------------ | | Ethereum | 1 | api.0xbow.io | | Sepolia | 11155111 | dw.0xbow.io |

Security

• Domain-separated key derivation (keccak256(encodePacked("privacy-pools-v1", signature))) ensures PP keys are cryptographically independent from stealth address keys derived from the same wallet signature
• All proof generation runs client-side — no server ever sees user secrets
• No private keys or secrets are stored — everything re-derives from the wallet

License

MIT