@0xbow/privacy-pools-core-sdk

Privacy Pool Core SDK

A TypeScript SDK for interacting with the Privacy Pool protocol. This SDK provides cryptographic utilities, proof generation, account management, and contract interactions for Privacy Pool integration.

Installation

npm install @0xbow/privacy-pools-core-sdk
# or
yarn add @0xbow/privacy-pools-core-sdk
# or
pnpm add @0xbow/privacy-pools-core-sdk

Setup

1. Install dependencies by running pnpm install
2. Build the SDK by running pnpm build

Available Scripts

Usage

Initialization

import { PrivacyPoolSDK, Circuits } from '@0xbow/privacy-pools-core-sdk';

// In Node.js — set browser: false to load artifacts from the filesystem
const circuits = new Circuits({ browser: false });

// In the browser — the default (browser: true) uses fetch
// const circuits = new Circuits();

const sdk = new PrivacyPoolSDK(circuits);

Commitment Proofs

const commitmentProof = await sdk.proveCommitment(value, label, nullifier, secret);
const isValid = await sdk.verifyCommitment(commitmentProof);

Withdrawal Proofs

const withdrawalProof = await sdk.proveWithdrawal(commitment, withdrawalInput);
const isValid = await sdk.verifyWithdrawal(withdrawalProof);

Key Derivation

The SDK derives deterministic master keys from a BIP-39 mnemonic phrase using generateMasterKeys. These keys are used to generate per-deposit and per-withdrawal nullifiers and secrets.

import { generateMasterKeys, generateDepositSecrets, generateWithdrawalSecrets } from '@0xbow/privacy-pools-core-sdk';

const { masterNullifier, masterSecret } = generateMasterKeys(mnemonic);

const depositSecrets = generateDepositSecrets(
  { masterNullifier, masterSecret },
  scope,
  index,
);

const withdrawalSecrets = generateWithdrawalSecrets(
  { masterNullifier, masterSecret },
  label,
  index,
);

Account Recovery

The AccountService reconstructs on-chain account state from a mnemonic by scanning deposit, withdrawal, and ragequit events.

import { AccountService, DataService } from '@0xbow/privacy-pools-core-sdk';

const { account, legacyAccount, errors } = await AccountService.initializeWithEvents(
  dataService,
  { mnemonic },
  pools,
);

Incomplete Scopes

A non-empty errors array means one or more pools failed to load. Reconstructed state for those scopes is absent, not empty — the account may hold notes that are not visible, so treating the scope as having no accounts will understate the next deposit index and produce a deposit that later reconstructions cannot find.

Check status before acting on a scope:

account.getScopeStatus(scope); // 'complete' | 'incomplete' | 'not-loaded'
account.isScopeComplete(scope); // true only for 'complete'
account.getIncompleteScopes(); // scopes whose last load failed

Block deposits and withdrawals for any scope that is not complete. createDepositSecrets(scope) without an explicit index throws for such a scope rather than guessing; pass an explicit index only in recovery flows. Status is stored on the account, so it survives persisting and restoring it.

To retry the failed pools, pass both services returned by the original call:

const retry = await AccountService.initializeWithEvents(
  dataService,
  { service: account, legacyService: legacyAccount },
  pools,
);

Omitting legacyService reconstructs the retried scopes without migration discovery, which silently omits migration-derived accounts.

Empty Nodes

account.getSpendableCommitments() returns the latest decrypted commitment of each account. By default (includeEmptyNodes: true) the result includes empty (zero-value), migrated, and ragequit nodes alongside spendable ones, so callers can see the full decrypted state.

To restore the spendable-only behavior — returning only commitments with a non-zero value whose account has not been ragequit or migrated — set includeEmptyNodes: false:

const { account } = await AccountService.initializeWithEvents(
  dataService,
  { mnemonic },
  pools,
  { includeEmptyNodes: false },
);

The same option can be passed when constructing an AccountService directly:

const account = new AccountService(dataService, { mnemonic, includeEmptyNodes: false });

Note: when includeEmptyNodes is true, getSpendableCommitments() may return commitments that are not actually spendable (zero-value, migrated, or ragequit). Filter on value / account flags before attempting to spend.

Contract Interactions

const contracts = sdk.createContractInstance(rpcUrl, chain, entrypointAddress, privateKey);

Mnemonic Security

The SDK does not provide a generateMnemonic utility. Use a trusted BIP-39 library (e.g. @scure/bip39 or viem/accounts) to generate mnemonic phrases externally.

• Never hardcode mnemonics in source code or configuration files.
• Never log or transmit mnemonics in plaintext.
• Store mnemonics using OS-level secure storage (e.g. OS keychain, encrypted vault) — never in browser localStorage or unencrypted files.
• Do not reuse a single mnemonic across unrelated applications. A compromised mnemonic exposes all derived keys and the funds they control.
• The mnemonic is the sole root of all derived keys. Loss of the mnemonic means permanent loss of access to all associated commitments and funds.

Circuit Artifact Integrity

The SDK verifies every downloaded circuit artifact (wasm, vkey, zkey) against expected SHA-256 digests. Artifacts without a registered hash are rejected at load time.

You can independently verify these against the committed artifacts:

shasum -a 256 packages/circuits/trusted-setup/final-keys/*.{vkey,zkey}
shasum -a 256 packages/circuits/build/*/*_js/*.wasm

Features

• Zero-knowledge proof generation and verification (commitments and withdrawals)
• Deterministic key derivation from BIP-39 mnemonics
• Account state recovery from on-chain events
• Commitment and Merkle proof utilities
• Contract interaction helpers
• Type-safe API

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

Apache-2.0 License - see the LICENSE file for details.