SDK Reference

The ShieldFlow TypeScript SDK provides a complete interface for interacting with the protocol. It handles deposits, withdrawals, ZK proof generation, and account management.

Installation

terminal

npm install @shieldflow/sdk

Initialization

Create a ShieldFlow instance with your chain configuration. The SDK automatically discovers registered pools and configures verifier contracts.

setup.ts

import { ShieldFlow } from '@shieldflow/sdk';

const shieldflow = new ShieldFlow({
  chainId: 1,
  rpcUrl: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY',
  entrypointAddress: '0xCFFf9d27e6A23C94447cEA72DDf6B0C3807F5fE5',
});

API Reference

`deposit()`

Creates a new deposit into the Privacy Pool. Generates a cryptographic commitment, submits the on-chain transaction, and derives a 12-word recovery mnemonic from the deposit secrets.

Parameters

assetstringAsset identifier (e.g. "ETH", "USDC")

amountstringHuman-readable deposit amount (e.g. "1.0")

Returns: { commitment, mnemonic, txHash }

deposit.ts

const result = await shieldflow.deposit({
  asset: 'ETH',
  amount: '1.0',
});

console.log(result.commitment); // bytes32 commitment hash
console.log(result.mnemonic);   // 12-word recovery phrase
console.log(result.txHash);     // transaction hash

`withdraw()`

Generates a ZK proof and submits a withdrawal through the relayer. The proof demonstrates the caller owns a valid commitment without revealing which deposit is being spent.

Parameters

mnemonicstring12-word recovery phrase from deposit

recipientstringDestination address for withdrawn funds

amountstringAmount to withdraw (e.g. "0.5")

Returns: { txHash, nullifier }

withdraw.ts

const result = await shieldflow.withdraw({
  mnemonic: 'word1 word2 ... word12',
  recipient: '0xRecipientAddress',
  amount: '0.5',
});

console.log(result.txHash);    // withdrawal transaction hash
console.log(result.nullifier); // nullifier to prevent double-spend

`ragequit()`

Emergency exit that bypasses the relayer and ASP. The original depositor can reclaim their full deposit directly on-chain by proving ownership of the commitment.

Parameters

mnemonicstring12-word recovery phrase from deposit

Returns: { txHash }

ragequit.ts

const result = await shieldflow.ragequit({
  mnemonic: 'word1 word2 ... word12',
});

console.log(result.txHash); // ragequit transaction hash

`loadAccount()`

Reconstructs account state from a recovery mnemonic. Scans on-chain events to find all deposits associated with the derived secrets and computes current balances.

Parameters

mnemonicstring12-word recovery phrase

Returns: { deposits, balances }

load-account.ts

const account = await shieldflow.loadAccount({
  mnemonic: 'word1 word2 ... word12',
});

console.log(account.deposits);  // array of deposit records
console.log(account.balances);  // per-asset balance summary

`getDeposits()`

Retrieves all deposits made by a specific account address. Queries on-chain Deposited events and returns structured deposit records.

Parameters

accountstringEthereum address to query deposits for

Returns: Deposit[]

get-deposits.ts

const deposits = await shieldflow.getDeposits({
  account: '0xYourAddress',
});

// Returns: Deposit[]
deposits.forEach((d) => {
  console.log(d.commitment, d.amount, d.asset, d.timestamp);
});

Supported Platforms

Node.js (ESM)

Full SDK support with native crypto. Import as an ES module.

Browser (with Web Workers)

ZK proof generation runs in a dedicated Web Worker to avoid blocking the main thread.

React / Next.js

Compatible with React 18+ and Next.js App Router. Use dynamic imports to avoid SSR issues with WASM dependencies.

Web Worker ZK Proofs

ZK proof generation runs in a Web Worker to avoid blocking the main thread. The SDK handles this automatically in browser environments.

Configuration Options

The following options can be passed to the ShieldFlow constructor:

OptionTypeRequiredDescription

chainIdnumberYesTarget chain ID (e.g. 1 for mainnet, 11155111 for Sepolia)

rpcUrlstringYesJSON-RPC endpoint for the target chain

entrypointAddressstringYesAddress of the deployed Entrypoint contract

relayerUrlstringNoURL of the ShieldFlow relayer service for private withdrawals

aspUrlstringNoURL of the ASP (Association Set Provider) for compliance verification