PrivacyClient

The main class for interacting with the privacy pool.

Constructor

new PrivacyClient(config: PrivacyClientConfig)

PrivacyClientConfig

Property	Type	Required	Description
rpcUrl	string	Yes	Ethereum JSON-RPC endpoint
poolAddress	Address	Yes	UTXOPool contract address
chainId	number	No	Chain ID (auto-detected if not provided)
relayerUrl	string	No	Relayer URL for gasless transactions
quickSyncUrl	string	No	QuickSync service for fast initial sync
prover	Prover	No	Prover instance (uses global if not provided)
devMode	boolean	No	Use Anvil test account for gas
enableCache	boolean	No	Enable IndexedDB caching (default: true)
makerUrl	string	No	Market maker URL for swaps

Example

import { PrivacyClient, DEPLOYMENTS } from '@zkprivacy/sdk';

const client = new PrivacyClient({
  rpcUrl: DEPLOYMENTS.remote.rpcUrl,
  poolAddress: DEPLOYMENTS.remote.pool,
  relayerUrl: DEPLOYMENTS.remote.relayerUrl,
  quickSyncUrl: DEPLOYMENTS.remote.quickSyncUrl,
});

Methods

connect

Connect to the privacy pool with keys.

await client.connect(options: ConnectOptions): Promise<void>

ConnectOptions

Property	Type	Description
mode	'linked' | 'standalone'	Connection mode
walletClient	WalletClient	For linked mode
spendingKey	bigint	For standalone mode
mnemonic	string	For standalone mode
accountIndex	number	Account index (default: 0)

Examples

// Linked mode
await client.connect({
  mode: 'linked',
  walletClient,
});

// Standalone with key
await client.connect({
  mode: 'standalone',
  spendingKey: BigInt('0x...'),
});

// Standalone with mnemonic
await client.connect({
  mode: 'standalone',
  mnemonic: 'word1 word2 ...',
  accountIndex: 0,
});

---

disconnect

Clear keys from memory and disconnect.

client.disconnect(): void

---

isConnected

Check if client is connected.

client.isConnected(): boolean

---

sync

Synchronize with the blockchain.

await client.sync(onProgress?: (progress: SyncProgress) => void): Promise<void>

SyncProgress

Property	Type	Description
phase	'commitments' | 'notes' | 'nullifiers'	Current phase
current	number	Items processed
total	number	Total items
message	string	Human-readable status

Example

await client.sync((progress) => {
  console.log(`${progress.phase}: ${progress.current}/${progress.total}`);
});

---

getAddress

Get your ZK address for receiving.

client.getAddress(): string  // zks1...

---

getBalance

Get ETH balance in wei.

client.getBalance(): bigint

---

getBalanceByTokenId

Get balance for a specific token.

client.getBalanceByTokenId(tokenId: bigint): bigint

---

getAllBalances

Get all balances as a map.

client.getAllBalances(): Map<bigint, bigint>

Example

const balances = client.getAllBalances();
for (const [tokenId, balance] of balances) {
  console.log(`Token ${tokenId}: ${balance}`);
}

---

getUnspentNotes

Get spendable notes.

client.getUnspentNotes(tokenId?: bigint): TrackedNote[]

---

transfer

Execute a private transfer.

await client.transfer(request: TransferRequest): Promise<Hash>

TransferRequest

Property	Type	Required	Description
recipient	string	Yes	ZK address (zks1...)
amount	string | bigint	Yes	Amount to send
tokenId	bigint	No	Token ID (0n for ETH)
inputNotes	TrackedNote[]	No	Specific notes to spend

---

unshield

Withdraw to an EOA.

await client.unshield(request: UnshieldRequest): Promise<Hash>

UnshieldRequest

Property	Type	Required	Description
recipient	Address	Yes	EOA address (0x...)
amount	string | bigint	Yes	Amount to withdraw
tokenId	bigint	No	Token ID (0n for ETH)

---

consolidate

Merge multiple notes into one.

await client.consolidate(request: ConsolidateRequest): Promise<Hash>

ConsolidateRequest

Property	Type	Description
notes	TrackedNote[]	Notes to consolidate (max 2)
tokenId	bigint	Token ID

---

clearCache

Clear IndexedDB cache.

await client.clearCache(): Promise<void>

Types

TrackedNote

interface TrackedNote {
  note: Note;
  commitment: bigint;
  leafIndex: number;
  nullifier: bigint;
  spent: boolean;
  txHash?: Hash;
  blockNumber?: bigint;
  tokenId: bigint;
  senderAddress?: string;
}

Note

interface Note {
  npk: bigint;      // Nullifier public key
  amount: bigint;   // Note amount
  random: bigint;   // Random blinding factor
}