API Reference

Complete API reference for the Privacy Boost React Native SDK (version 0.2.14). Everything below is derived from the generated UniFFI bindings — signatures match what consumers actually see.

Module exports

import {
  PrivacyBoost,
  PrivacyBoostConfig,
  ChainContextHandle,
  ChainContextConfig,
  KeySource,
  SdkError,
  SdkError_Tags,
  AuthResult,
  TransactionHistoryQuery,
  StringPatch,
  MetadataPatch,
  sdkVersion,
  generateMnemonic,
  registerKeychainDelegate,
  hasKeychainDelegate,
  buildShieldPayload,
  finalizeShield,
} from '@sunnyside-io/privacy-boost-react-native';

Top-level functions:

sdkVersion(): string          // Current SDK version string
generateMnemonic(): string    // Random BIP-39 12-word mnemonic

// Process-wide; required before constructing an SDK whose config selects
// StorageBackend.OsKeychain, and a later call replaces the delegate for every
// instance. `service` namespaces the stored items; omit it to use the SDK's
// own name. See KeychainDelegate below.
registerKeychainDelegate(delegate: KeychainDelegate, service?: string): void
hasKeychainDelegate(): boolean

See Stateless shield helpers for buildShieldPayload and finalizeShield.

PrivacyBoost

Main SDK class. One instance per app; hold it in a module-level ref or a context provider.

Constructor

new PrivacyBoost(config: PrivacyBoostConfig)

Configs are created via the factory:

const config = PrivacyBoostConfig.create({
  serverUrl: 'https://indexer.example.com',
  chainId: undefined,                   // discovered from server if omitted
  shieldContractAddress: undefined,     // discovered from server if omitted
  wethContractAddress: '0x...' || undefined,
  teePublicKey: undefined,              // discovered from server if omitted
  appId: 'app_...',
  persistenceStorage: undefined, // StorageBackend.OsKeychain after registerKeychainDelegate(...)
  persistenceUnlock: undefined,  // None, Pin, Password, or Biometric with OsKeychain
  idleTtlSecs: undefined,        // auto-lock after this many idle seconds
  absoluteTtlSecs: undefined,    // auto-lock this many seconds after unlock
});

const sdk = new PrivacyBoost(config);

Throws: SdkError.ConfigError if initialization fails, including unsupported persistence storage, OsKeychain without a registered KeychainDelegate, or passkey unlock configuration.

State

sdk.isConnected(): boolean
sdk.isAuthenticated(): boolean
sdk.getPrivacyAddress(): string | undefined
sdk.getMpk(): string | undefined
sdk.getWalletAddress(): string | undefined
sdk.getMnemonic(): string | undefined                   // throws

Authentication

sdk.authenticate(
  wallet: WalletDelegate,
  keySource: KeySource | undefined,
  tokenProvider: TokenProvider | undefined,
): Promise<AuthResult>

Connect a wallet, derive privacy keys, authenticate with the backend. Returns an AuthResult tagged union — see AuthResult for all variants and handling.

sdk.submitCredential(
  credential: string,
  tokenProvider: TokenProvider | undefined,
): Promise<LoginResult>

Complete an authentication flow that returned CredentialRequired.

sdk.proceedAfterMnemonic(
  tokenProvider: TokenProvider | undefined,
): Promise<LoginResult>

Complete an authentication flow that returned MnemonicGenerated (first-time user). Call this after the user confirms they’ve saved the recovery phrase.

sdk.logout(): void                  // End session, clear all state
sdk.clearSession(): void            // Clear JWT only, keep keys for quick re-auth
sdk.lock(): void                    // Wipe resident keys and the JWT, keep the persisted vault
sdk.deleteVault(): Promise<void>    // Erase persisted vault on the device

lock() zeroizes all resident key material and drops the session JWT while keeping the persisted encrypted vault, so the user unlocks again without re-deriving keys. The next key access throws SdkError.NotAuthenticated; call authenticate again to reopen the vault. The idleTtlSecs and absoluteTtlSecs config fields invoke the same lock automatically (see PrivacyBoostConfig). Chain-context handles share the wiped keys but keep their own JWT, so call clearSession() on each of them.

Operations

sdk.shield(tokenAddress: string, amount: string): Promise<ShieldResult>
sdk.prepareShield(tokenAddress: string, amount: string, recipient: string | undefined): Promise<PreparedShield>
sdk.unshield(tokenAddress: string, amount: string, recipient: string): Promise<UnshieldResult>
sdk.send(tokenAddress: string, amount: string, recipientPrivacyAddress: string): Promise<TransferResult>
sdk.sendBatch(tokenAddress: string, recipients: TransferRecipient[]): Promise<TransferResult>
sdk.unwrapWeth(amount: string, recipientAddress: string): Promise<string>

sendBatch pays several recipients from one set of input notes, in one request: TransferRecipient is { recipient: string; amount: string }, and output order follows the array. The transfer’s output count is the recipient count plus a change note, and the server only proves specific (inputs, outputs) combinations, so past two recipients at most four input notes can be spent; requests no enabled circuit can serve fail with UNSUPPORTED_TRANSFER_SHAPE before submission. unwrapWeth unwraps WETH the user already holds in their wallet back to native ETH — it does not interact with the shielded pool. prepareShield builds a deposit payload without submitting it — for callers that relay the transaction themselves (a gasless relayer, an EIP-7702 session key, or a plain raw transaction). It returns the calldata to relay plus the note commitment; nothing is sent on-chain. Pass undefined for recipient to shield to yourself, or a privacy address to shield to someone else. After relaying, pass the mined receipt to the top-level finalizeShield to recover the on-chain request id.

Earn and gateway

sdk.earnDeposit(vaultAddress: string, amount: string, slippageBps: number | undefined): Promise<EarnResult>
sdk.earnRedeem(vaultAddress: string, amount: string, slippageBps: number | undefined): Promise<EarnResult>
sdk.listEarnVaults(): Promise<EarnVaultCatalog>
sdk.getEarnVault(vaultAddress: string): Promise<EarnVaultDetail>
sdk.getGatewayConfig(): Promise<GatewayConfig>
sdk.getEarnVaultHistory(
  vaultAddress: string,
  metric: EarnHistoryMetric,
  period?: EarnHistoryPeriod,
): Promise<EarnVaultHistory>
sdk.getEarnVaultCharts(vaultAddress: string, period?: EarnHistoryPeriod): Promise<EarnVaultCharts>

Gateway earn operations deposit into or redeem from a yield vault from inside the pool. The catalog and history reads are public and work before login; earnDeposit and earnRedeem need an authenticated session and a ChainReaderDelegate registered with setChainReader. For a deposit, amount is the net amount that enters the vault and the unshield fee is charged on top; for a redeem it is the share amount. metric is EarnHistoryMetric.TvlUsd or NetApy; period is EarnHistoryPeriod.OneWeek, OneMonth, ThreeMonths, or All. The *Json accessors take the wire names instead, keeping the signatures they shipped with. APY values are fractions (0.05 is 5%), an undefined point value is an upstream gap, and metadata.state reports freshness.

const catalog = await sdk.listEarnVaults();
for (const vault of catalog.vaults.filter((v) => v.listed)) {
  const apy = vault.apy.net === undefined ? 'n/a' : `${(vault.apy.net * 100).toFixed(2)}%`;
  const open = vault.availability.deposit.canSubmit;
  console.log(`${vault.name} ${apy} deposits ${open ? 'open' : 'closed'}`);
}

The listEarnVaultsJson, getGatewayConfigJson, getEarnVaultHistoryJson, and getEarnVaultChartsJson methods return the same data as canonical JSON strings for callers that parse the wire shape themselves.

Status polling

sdk.getShieldStatus(requestId: string): Promise<ShieldStatus>
sdk.getTransferStatus(id: string): Promise<TransactionStatus>
sdk.getUnshieldStatus(id: string): Promise<TransactionStatus>

Balances & tokens

sdk.getBalance(tokenAddress: string): Promise<TokenBalance>
sdk.getAllBalances(): Promise<TokenBalance[]>
sdk.getRegisteredTokens(): Promise<RegisteredToken[]>
sdk.getTokenByAddress(address: string): Promise<RegisteredToken>
sdk.getFees(tokenAddress: string): Promise<FeeRates>
sdk.getGatewayFees(
  tokenAddress: string,
  gatewayAddress: string,
  gatewaySelector: string | undefined,
): Promise<FeeRates>

History & notes

sdk.getTransactionHistory(
  txType: string | undefined,
  limit: number | undefined,
  cursor: string | undefined,
): Promise<TransactionsResult>

// Same query, but each gateway operation comes back as one row with a
// server-computed status instead of the two on-chain epochs it settles as.
// Its own method rather than a flag on the call above, so the trailing
// `asyncOpts_` argument every async binding takes keeps its position.
sdk.getCollapsedTransactionHistory(
  txType: string | undefined,
  limit: number | undefined,
  cursor: string | undefined,
): Promise<TransactionsResult>

// The full query: type, token id and direction filters, page size, cursor,
// and collapseGateway. Its own method for the same reason as above.
sdk.queryTransactionHistory(query: TransactionHistoryQuery): Promise<TransactionsResult>

sdk.getUnspentNotes(tokenAddress: string | undefined): Promise<UnspentNote[]>

// Incoming transactions for token id 1, 25 per page, gateway operations collapsed
const page = await sdk.queryTransactionHistory(
  TransactionHistoryQuery.create({
    tokenId: 1,
    direction: TransactionDirection.Incoming,
    limit: 25,
    collapseGateway: true,
  }),
);
// page.next is the cursor for the following page, as with getTransactionHistory

Merkle tree

sdk.getMerkleTreeStats(): Promise<MerkleTreeStats>

Audit APIs

For auditable operations — returns all-party visible data, not just the calling user’s. Intended for compliance dashboards and regulators, not for end-user UIs.

sdk.getAuditTransactions(
  pubkey?: string,
  txType?: string,
  limit?: number,
  offset?: number,
): Promise<AuditTransactionsResult>

sdk.getAuditNotes(
  owner?: string,
  tokenAddress?: string,
  spent?: boolean,
  limit?: number,
  offset?: number,
): Promise<AuditNotesResult>

sdk.getAuditBalances(
  pubkey?: string,
  tokenAddress?: string,
  limit?: number,
  offset?: number,
): Promise<AuditBalancesResult>

App metadata

sdk.getAppInfo(appIds: string[]): Promise<AppInfoEntry[]>

Private treasury

Per-wallet contacts and transaction labels, stored encrypted on the server and readable only with the session’s keys. Every method requires an authenticated session. A row whose decryptionFailed is true is one the server could no longer open: show it as unreadable, not as missing.

sdk.listContacts(limit?: number, cursor?: string): Promise<ContactPage>
sdk.createContact(input: CreateContactInput): Promise<Contact>
sdk.bulkCreateContacts(contacts: CreateContactInput[]): Promise<BulkContactsResult>
sdk.updateContact(id: string, input: UpdateContactInput): Promise<Contact>
sdk.deleteContact(id: string): Promise<void>

sdk.listLabels(limit?: number, cursor?: string): Promise<TransactionLabelPage>
sdk.upsertLabel(txHash: string, input: UpsertLabelInput): Promise<TransactionLabel>
sdk.deleteLabel(txHash: string): Promise<void>

listContacts and listLabels page with an opaque cursor: both arguments default, so listContacts() is the first page at the server’s page size, and the previous page’s nextCursor gets the next one. bulkCreateContacts reports a contact whose privacy address already exists under skipped, with the existing row’s id, rather than failing the batch; clientId on each input is echoed back so you can correlate rows. updateContact takes a patch for every field, so “leave alone” is always Keep and never an undefined that could be read as a clear; nickname and emoji are the two the API can only replace, and Clear on either rejects with SdkError.InvalidInput naming the field. upsertLabel replaces the whole label, so an absent field means “no value”.

import {
  CreateContactInput,
  MetadataPatch,
  StringPatch,
  UpdateContactInput,
  UpsertLabelInput,
} from '@sunnyside-io/privacy-boost-react-native';

// Save a contact, then label a transfer to them.
const alice = await sdk.createContact(
  CreateContactInput.create({
    privacyAddress: '0x04...alice',
    nickname: 'Alice',
    ethAddress: '0x1234...abcd',
    metadata: new Map([['team', 'design']]),
  }),
);

await sdk.upsertLabel(
  transfer.txHash,
  UpsertLabelInput.create({ contactId: alice.id, memo: 'Dinner split' }),
);

// Later: clear the ETH address and keep everything else.
await sdk.updateContact(
  alice.id,
  UpdateContactInput.create({
    ethAddress: new StringPatch.Clear(),
    nickname: new StringPatch.Keep(),
    emoji: new StringPatch.Keep(),
    metadata: new MetadataPatch.Keep(),
  }),
);

// Page through contacts.
let cursor: string | undefined;
do {
  const page = await sdk.listContacts(50, cursor);
  for (const contact of page.contacts) {
    if (!contact.decryptionFailed) console.log(contact.nickname, contact.privacyAddress);
  }
  cursor = page.nextCursor;
} while (cursor);

Campaigns

sdk.getStartaleCampaignProgress(): Promise<StartaleCampaignProgress>

Lifetime Startale mission progress for the authenticated user and app. The deposit mission is priced at query time, so it is not monotonic: record the first true your app sees and never downgrade it. campaignTokenId is undefined only when no campaign token is configured, in which case every shielded token counted toward the deposit total.

Session persistence

sdk.exportSession(): ExportedSession | undefined
sdk.importSession(session: ExportedSession): boolean

Identity lookup

sdk.resolveIdentity(identifier: string): IdentityResult   // throws

Pending transactions

Local bookkeeping for optimistic UI — not persisted across SDK instances.

sdk.addPendingTransaction(tx: PendingTransaction): void
sdk.getPendingTransactions(): PendingTransaction[]
sdk.getAllPendingTransactions(): PendingTransaction[]
sdk.refreshPendingTransactions(): Promise<number>       // returns updated count

Chain context

Create a handle scoped to a different chain while sharing the same SDK identity. The handle has its own session and JWT: authenticate it separately with ctx.authenticate(wallet), and clear it separately with ctx.clearSession(), since sdk.lock() wipes the shared keys but leaves the handle’s JWT in place. Every call returns a new handle, so create each one once and keep it. Throws if serverUrl is empty or not an HTTPS URL.

sdk.createChainContext(config: ChainContextConfig): ChainContextHandle

See ChainContextHandle below.

Utilities

sdk.isValidAddress(address: string): boolean
sdk.isValidPrivacyAddress(address: string): boolean
sdk.toChecksumAddress(address: string): string | undefined
sdk.parseAmount(amount: string, decimals: number): string    // throws
sdk.formatAmount(wei: string, decimals: number): string      // throws

ChainContextHandle

Returned by sdk.createChainContext(). Mirrors the main SDK’s chain-scoped operations against a different chain. It shares the parent’s identity keys, so ctx.authenticate(wallet) obtains that chain’s JWT without deriving keys a second time.

ctx.chainId(): bigint
ctx.isAuthenticated(): boolean
ctx.isRegistered(): boolean
ctx.authenticate(wallet: WalletDelegate): Promise<LoginResult>

ctx.shield(tokenAddress: string, amount: string): Promise<ShieldResult>
ctx.prepareShield(tokenAddress: string, amount: string, recipient: string | undefined): Promise<PreparedShield>
ctx.unshield(tokenAddress: string, amount: string, recipient: string): Promise<UnshieldResult>
ctx.send(tokenAddress: string, amount: string, recipientPrivacyAddress: string): Promise<TransferResult>
ctx.sendBatch(tokenAddress: string, recipients: TransferRecipient[]): Promise<TransferResult>
ctx.unwrapWeth(amount: string, recipient: string): Promise<string>

ctx.getBalance(tokenAddress: string): Promise<TokenBalance>
ctx.getAllBalances(): Promise<TokenBalance[]>
ctx.getRegisteredTokens(): Promise<RegisteredToken[]>
ctx.getTokenByAddress(address: string): Promise<RegisteredToken>
ctx.getFees(tokenAddress: string): Promise<FeeRates>
ctx.getGatewayFees(
  tokenAddress: string,
  gatewayAddress: string,
  gatewaySelector: string | undefined,
): Promise<FeeRates>

ctx.getShieldStatus(requestId: string): Promise<ShieldStatus>
ctx.getTransferStatus(id: string): Promise<TransactionStatus>
ctx.getUnshieldStatus(id: string): Promise<TransactionStatus>

ctx.getTransactionHistory(txType?: string, limit?: number, cursor?: string): Promise<TransactionsResult>
ctx.getCollapsedTransactionHistory(txType?: string, limit?: number, cursor?: string): Promise<TransactionsResult>
ctx.queryTransactionHistory(query: TransactionHistoryQuery): Promise<TransactionsResult>
ctx.getUnspentNotes(tokenAddress?: string): Promise<UnspentNote[]>

ctx.addPendingTransaction(tx: PendingTransaction): void
ctx.getPendingTransactions(): PendingTransaction[]
ctx.getAllPendingTransactions(): PendingTransaction[]
ctx.refreshPendingTransactions(): Promise<number>

ctx.clearSession(): void

The claimable-transfer methods (giftFund, giftFundToWallet, giftFundSecretBearer, giftClaim, giftClaimByCGift, giftClaimFromLink, giftRefund, giftRefundByRecord, getPendingGifts, getGiftRecords, decodeGiftLink) are also on the handle with the same signatures as on sdk (see Gift Methods), along with consolidateNotes, refreshPendingTransactionsDetailed, waitForPreconfirmation, waitForFinality, and importGiftRecords(records: GiftRecord[]), which rehydrates the handle’s sender ledger from persisted records. Portal deposits, earn and swap, audit, and the private treasury stay on the parent sdk, as do resolveIdentity, the amount utilities, setChainReader, and session export. The parent’s pending transactions and token registry reflect its own chain only, so read each chain’s through its handle.

Stateless shield helpers

Top-level named exports for building a deposit payload without a signed-in session — for a backend that holds only a recipient’s privacy address. No wallet, no private keys.

import { buildShieldPayload, finalizeShield } from '@sunnyside-io/privacy-boost-react-native';

buildShieldPayload(
  tokenAddress: string,
  amount: string,
  recipient: string,
  tokenId: number,
  shieldContractAddress: string,
  wethContractAddress: string | undefined,
  teePublicKey: string,
  minShieldAmount: string | undefined,
  emitApprove: boolean,
): PreparedShield

finalizeShield(
  receipt: TransactionReceipt,
  shieldContract: string,
  commitment: string,
): ShieldResult

buildShieldPayload builds a recipient-targeted deposit payload from public material only. Resolve tokenId, shieldContractAddress, and teePublicKey from the token catalog / config. An ephemeral sender keypair is generated and discarded internally, and the note is spendable only by recipient. wethContractAddress is required only when shielding native ETH; minShieldAmount (per-token minimum in wei) rejects below-minimum deposits; emitApprove emits the ERC-20 approve call (pass true by default). finalizeShield recovers the on-chain shield request id from the mined receipt of a relayed deposit. Stateless — the caller obtained the receipt from its own relay/RPC. Throws if the deposit reverted or the DepositRequested log is absent. The TransactionReceipt is the same shape returned by WalletDelegate.waitForTransactionReceipt (see WalletDelegate).

Delegate interfaces

WalletDelegate

interface WalletDelegate {
  getAddress(): Promise<string>;
  getChainId(): Promise<bigint>;
  signMessage(message: string): Promise<string>;
  signTypedData(typedDataJson: string): Promise<string>;
  sendTransaction(toAddress: string, value: string, data: string): Promise<string>;
  waitForTransactionReceipt(txHash: string): Promise<TransactionReceipt>;
}

interface TransactionReceipt {
  txHash: string;
  status: boolean;
  logs: Array<{ address: string; topics: string[]; data: string }>;
}

TokenProvider

interface TokenProvider {
  getToken(loginPayloadJson: string): Promise<TokenResponse>;
}

interface TokenResponse {
  token: string;
  expiresIn: bigint;
}

KeychainDelegate

Implemented by the app and registered process-wide with registerKeychainDelegate to serve StorageBackend.OsKeychain persistence. Values are opaque bytes; requireBiometry is true when the config selects UnlockMethod.Biometric, and the item must then be stored behind the OS biometric prompt. The optional service argument on registration namespaces the items, which an app running two SDK instances should set.

interface KeychainDelegate {
  store(key: string, value: ArrayBuffer, requireBiometry: boolean): Promise<void>;
  load(key: string): Promise<ArrayBuffer | undefined>;
  remove(key: string): Promise<void>;
  contains(key: string): Promise<boolean>;
  isAvailable(): boolean;
  supportsBiometry(): boolean;
}

See Session Storage for a react-native-keychain implementation.

Types

PrivacyBoostConfig

type PrivacyBoostConfig = {
  serverUrl: string;
  chainId: bigint | undefined;
  shieldContractAddress: string | undefined;
  wethContractAddress: string | undefined;
  teePublicKey: string | undefined;
  appId: string;
  persistenceStorage: StorageBackend | undefined;
  persistenceUnlock: UnlockMethod | undefined;
  approvalOnly: boolean;
  idleTtlSecs: bigint | undefined;
  absoluteTtlSecs: bigint | undefined;
};

PrivacyBoostConfig.create() defaults approvalOnly to false and both TTL fields to undefined. The SDK discovers the chain-specific AuthRegistry from the configured server; it is not a caller-supplied field. idleTtlSecs and absoluteTtlSecs drive auto-lock, in seconds: the first is how long the resident keys may go unused, the second how long after an unlock they may stay resident at all. undefined or 0n disables the respective timer. Both are checked lazily, on the next key access: once one has elapsed, that access zeroizes the keys and throws SdkError.NotAuthenticated, exactly as sdk.lock() would, and the persisted vault is kept so authenticate can reopen it. They bound key use rather than key residency; call sdk.lock() from your own timer when the keys must be gone at a fixed time. See Auto-lock. persistenceStorage: StorageBackend.OsKeychain stores the encrypted vault through a KeychainDelegate the app implements in JavaScript and registers with registerKeychainDelegate before constructing the SDK; construction throws SdkError.ConfigError otherwise. LocalStorage and IndexedDb are browser backends and are rejected on React Native. See Session Storage.

ChainContextConfig

type ChainContextConfig = {
  serverUrl: string;
  chainId: bigint;
  shieldContractAddress: string | undefined;
  wethContractAddress: string | undefined;
  rpcUrl: string | undefined;
  teePublicKey: string | undefined;
  timeoutMs: bigint;
};

Everything after chainId is defaulted, so ChainContextConfig.create({ serverUrl, chainId }) is a complete config: the addresses are discovered from that chain’s server and timeoutMs falls back to the SDK-wide 30s. A contract address you do pass has to parse — a malformed one is rejected rather than dropped, so a typo can never fall back to the server-advertised pool.

KeySource

Tagged union — each variant is constructable.

new KeySource.WalletDerived()
new KeySource.Mnemonic('twelve word phrase')
new KeySource.RawSeed('0xdeadbeef...')

StorageBackend

enum StorageBackend {
  LocalStorage = 'LocalStorage',
  IndexedDb = 'IndexedDb',
  OsKeychain = 'OsKeychain',
}

These enum values are shared with other SDK targets. React Native accepts OsKeychain once a KeychainDelegate is registered and rejects the two browser backends at construction.

UnlockMethod

enum UnlockMethod {
  None = 'None',
  Pin = 'Pin',
  Password = 'Password',
  Biometric = 'Biometric',
  Passkey = 'Passkey',
}

Passkey is rejected on React Native because iOS and Android do not expose the WebAuthn PRF extension needed for reproducible vault unlock keys. Biometric stores the keychain item with requireBiometry: true, so the delegate places it behind the OS biometric prompt; Pin and Password produce a CredentialRequired result that submitCredential completes.

AuthResult

Tagged union returned by authenticate(). You must handle all five variants.

type AuthResult =
  | { tag: 'Authenticated'; loginResult: LoginResult }
  | { tag: 'CredentialRequired'; challenge: CredentialChallenge }
  | { tag: 'MnemonicGenerated'; mnemonic: string }
  | { tag: 'RecoveryRequired'; challenge: RecoveryChallenge }
  | { tag: 'AccountCreationRequired'; challenge: AccountCreationChallenge };

AccountCreationRequired contains the account ID, canonical account salt, and a prepared EOA transaction (chainId, to, value, data). The SDK validates the target against the AuthRegistry advertised by this deployment’s /api/v1/info. See Getting Started → Connecting a Wallet for worked handling of each variant.

LoginResult

interface LoginResult {
  privacyAddress: string;
  mpk: string;
  isNewUser: boolean;
  chainRegistrations: Map<string, string>;  // chainId → registration tx hash
}

ShieldResult

interface ShieldResult {
  txHash: string;
  commitment: string;
  requestId: string;
  warning?: string;
  wrapTxHash?: string;   // present when shielding native ETH
}

finalizeShield also returns a ShieldResult.

Call / PreparedShield

Returned by prepareShield and buildShieldPayload. Each Call is a single on-chain call to relay; value and data are 0x-hex.

interface Call {
  to: string;
  value: string;
  data: string;
}

interface PreparedShield {
  approve?: Call;   // ERC-20 approve(pool, amount); omitted when managed out of band
  wrap?: Call;      // WETH deposit() wrap; present only when shielding native ETH
  shield: Call;     // the requestDeposit(...) call
  commitment: string;
  finalize: { shieldContract: string; tokenId: number };
}

UnshieldResult / TransferResult

interface UnshieldResult { requestId: string; txHash: string; fee: string; }
interface TransferResult { requestId: string; txHash: string; fee: string; giftRecord?: GiftRecord; claimLink?: string; }

ShieldStatus / TransactionStatus

interface ShieldStatus {
  id: string;
  status: string;         // "pending" | "confirmed" | "failed" | ...
  createdAt?: string;
  updatedAt?: string;
  txHash?: string;
  leafIndex?: bigint;
  error?: string;
}

interface TransactionStatus {
  id: string;
  txType: string;
  status: string;
  createdAt?: string;
  updatedAt?: string;
  txHash?: string;
  error?: string;
}

TokenBalance

interface TokenBalance {
  tokenAddress: string;
  shieldedBalance: string;   // in wei
  walletBalance: string;     // in wei
  symbol?: string;
  decimals: number;
}

RegisteredToken

interface RegisteredToken {
  id: number;
  tokenType: number;
  tokenAddress: string;
  tokenSubId: string;
  priceUsd?: number;
  decimals?: number;
  minShieldAmount?: string;
}

FeeRates

interface FeeRates {
  transferFeeFlat: string;             // active when transferFeeMode is "flat"
  unshieldFeeBps: number;              // active when unshieldFeeMode is "bps"
  feeSchemaVersion?: number;
  requiresFeeSchemaVersion?: number;
  transferRequiresFeeSchemaVersion?: number;
  unshieldRequiresFeeSchemaVersion?: number;
  transferFeeMode?: 'flat' | 'bps';
  transferFeeBps?: number;
  unshieldFeeMode?: 'flat' | 'bps';
  unshieldFeeFlat?: string;
  gatewayAddress?: string;
  gatewaySelector?: string;
  gatewayFeeMode?: 'flat' | 'bps';
  gatewayFeeFlat?: string;
  gatewayFeeRate?: number;
  gatewayFeeRateDenominator?: number;
  gatewayFeeBase?: 'flat' | 'unshield_amount' | 'zero';
  gatewayRequiresFeeSchemaVersion?: number;
}

Schema-v1 responses omit the optional fields and default to a flat transfer fee and BPS unshield fee. Schema v2 selects each mode independently. BPS fees use floor(base * bps / 10000): unshield uses the public exit amount, while a transfer uses only externally sent volume. Pure self-transfers therefore have zero transfer BPS fee. For Gateway operations, pass the executor address and the first four bytes of external calldata to getGatewayFees. The generated React Native binding requires the selector position; pass undefined to request the Gateway-wide default. An exact selector override wins, otherwise the default rate is returned and bound to the requested selector.

Transaction / TransactionNote / TransactionsResult

interface TransactionNote {
  amount: string;
  direction: string;          // "incoming" | "outgoing"
  isChange: boolean;
  leafIndex?: bigint;
  nullifier?: string;
  counterparty?: string;      // Address ("eoa") or accountId ("account")
  counterpartyType?: string;  // "eoa" | "account"
  counterpartyAddress?: string; // Wallet address, whatever the type
}

interface Transaction {
  txHash: string;
  txType: string;             // "shield" | "unshield" | "transfer"
  direction: string;
  value: string;
  tokenId: bigint;
  createdAt: bigint;
  counterparty?: string;
  counterpartyType?: string;
  notes: TransactionNote[];
}

interface TransactionsResult {
  data: Transaction[];
  limit: number;
  next?: string;              // cursor for next page
}

TransactionHistoryQuery

type TransactionHistoryQuery = {
  txType: string | undefined;                    // "shield" | "unshield" | "transfer"
  tokenId: number | undefined;                   // registered token id, from getRegisteredTokens()
  direction: TransactionDirection | undefined;   // relative to the wallet
  limit: number | undefined;                     // page size
  cursor: string | undefined;                    // previous page's next
  collapseGateway: boolean;                      // fold each Gateway operation's two rows into one
};

enum TransactionDirection {
  Incoming,
  Outgoing,
}

Every field is defaulted, so TransactionHistoryQuery.create({ tokenId: 1 }) is a valid query and a plain object literal is not needed. undefined fields are unfiltered.

UnspentNote

interface UnspentNote {
  commitment: string;
  value: string;
  tokenAddress: string;
  tokenId: string;
  random: string;
  owner: string;
  spent: boolean;
  isOpaque: boolean;
  createdAt: bigint;
  leafIndex?: bigint;
  treeNumber?: bigint;
}

MerkleTreeStats

interface MerkleTreeStats { size: string; root: string; }

Audit result types

interface AuditTransactionEntry { /* ...tx_hash, tx_type, value_in/out, ... */ }
interface AuditNoteEntry        { /* ...commitment, owner, value, spent, ... */ }
interface AuditBalanceEntry     { /* ...pub_key, token, balance, tx_count, ... */ }

interface AuditTransactionsResult { transactions: AuditTransactionEntry[]; total: bigint; limit: number; offset: number; }
interface AuditNotesResult        { notes: AuditNoteEntry[];        total: bigint; limit: number; offset: number; }
interface AuditBalancesResult     { balances: AuditBalanceEntry[];  total: bigint; limit: number; offset: number; }

See the generated bindings for full field lists; they’re stable but verbose.

PendingTransaction

enum PendingTransactionType      { Shield = 'Shield', Unshield = 'Unshield', Transfer = 'Transfer' }
enum PendingTransactionStatus    { Pending = 'Pending', Preconfirmed = 'Preconfirmed', Completed = 'Completed', Failed = 'Failed', Blocked = 'Blocked' }
enum PendingTransactionDirection { Incoming = 'Incoming', Outgoing = 'Outgoing' }

interface PendingTransaction {
  txHash: string;
  txType: PendingTransactionType;
  status: PendingTransactionStatus;
  direction: PendingTransactionDirection;
  error?: string;
  tokenAddress?: string;
  amount?: string;
  from?: string;
  to?: string;
  receivers: PendingReceiverTransfer[];
  createdAt: bigint;
  updatedAt: bigint;
  tokenSymbol?: string;
  commitment?: string;
  requestId?: string;
  isChange: boolean;
}

ExportedSession

interface ExportedSession {
  version: number;
  data: string;
}

data is an opaque serialized core session. Store and pass it back unchanged; do not parse or persist individual key fields.

IdentityResult

interface IdentityResult {
  mpk: string;
  viewingPublicKeyX: string;
  viewingPublicKeyY: string;
  privacyAddress: string;
}

AppInfoEntry

interface AppInfoEntry {
  appId: string;
  name: string;
  description?: string;
}

Private treasury types

interface Contact {
  id: string;
  privacyAddress?: string;
  ethAddress?: string;
  nickname: string;
  emoji: string;
  metadata?: Map<string, string>;
  updatedAt: string;
  decryptionFailed: boolean;   // the server could not open this row; show it as unreadable
}

interface CreateContactInput {
  privacyAddress: string;
  nickname: string;
  ethAddress?: string;
  emoji?: string;
  metadata?: Map<string, string>;
  clientId?: string;           // caller-chosen correlation id echoed back in bulk results
}

// PATCH fields: leave alone, clear, or replace. Tagged unions, constructed
// like KeySource.
new StringPatch.Keep()
new StringPatch.Clear()
new StringPatch.Set({ value: '0x...' })

new MetadataPatch.Keep()
new MetadataPatch.Clear()
new MetadataPatch.Set({ value: new Map([['team', 'design']]) })

// Every field is a patch. `Clear` on nickname or emoji rejects: the API can
// only replace those two.
interface UpdateContactInput {
  ethAddress: StringPatch;
  nickname: StringPatch;
  emoji: StringPatch;
  metadata: MetadataPatch;
}

interface BulkContactRef { clientId?: string; id: string; }

// A contact whose privacy address already exists lands in `skipped` with the existing row's id.
interface BulkContactsResult { created: BulkContactRef[]; skipped: BulkContactRef[]; }

interface ContactPage { contacts: Contact[]; nextCursor?: string; }

interface TransactionLabel {
  txHash?: string;
  contactId?: string;
  memo?: string;
  metadata?: Map<string, string>;
  updatedAt: string;
  decryptionFailed: boolean;
}

// A PUT replaces the whole label, so an absent field means "no value".
interface UpsertLabelInput {
  contactId?: string;
  memo?: string;
  metadata?: Map<string, string>;
}

interface TransactionLabelPage { labels: TransactionLabel[]; nextCursor?: string; }

The generated record types spell optional fields as T | undefined rather than ?:, so a plain object literal must list every field. Build them with the generated create({...}) factories instead, as in the Private treasury example: a factory fills in every field the UDL gives a default, which is all of them here except privacyAddress and nickname.

Earn and gateway types

interface EarnResult {
    requestId: string;
    action: string;              // "deposit" | "redeem"
    vaultAddress: string;
    inputTokenId: number;
    outputTokenId: number;
    amount: string;
    fee: string;
    expectedOutputAmount: string;
    minOutputAmount: string;
    expiryBlock: bigint;
}

interface EarnVaultCatalog {
    vaults: EarnVaultSummary[];
    gateway: GatewayAvailability;
}

interface EarnVaultSummary {
    chainId: bigint;
    vaultAddress: string;
    asset: EarnVaultAsset;       // address, symbol, decimals, logoUri
    name: string;
    symbol: string;
    description?: string;
    imageUrl?: string;
    apy: EarnApy;
    tvlUsd?: number;
    liquidity?: string;          // smallest unit, decimal string
    liquidityUsd?: number;
    fees: EarnFees;              // performanceFee, managementFee
    curators: EarnCurator[];     // name, image, aumUsd
    warnings: EarnWarning[];     // warningType, level
    listed: boolean;
    capabilities: EarnVaultCapabilities;   // deposit, redeem
    availability: EarnVaultAvailability;   // deposit, redeem: GatewayAvailability
    metadata: EarnVaultMetadata;           // state, updatedAt
    protocol: string;
    protocolVersion: string;
    updatedAt?: string;
}

interface EarnApy {
    net?: number;                // fractions: 0.05 is 5%
    netExcludingRewards?: number;
    net7d?: number;
    net30d?: number;
    net90d?: number;
    rewards: EarnReward[];       // assetAddress, assetSymbol, supplyApr
}

interface GatewayAvailability {
    state: string;
    canSubmit: boolean;
    reason: string;
    retryable: boolean;             // a closed window expected to reopen on its own
    checkedAt?: string;
}

interface EarnVaultDetail {
    summary: EarnVaultSummary;
    owner?: string;
    curator?: string;
    deployedAt?: string;
    timelockSeconds?: bigint;
    guardian?: string;
    feeRecipient?: string;
    sharePrice?: number;
    sharePriceUsd?: number;
    gateway: GatewayAvailability;
}

interface GatewayConfig {
    enabled: boolean;
    executorAddress?: string;
    adapters: GatewayAdapterInfo[];      // id, version, quoteMode, availability
    constraints: GatewayConstraints;     // calldata, slippage, and expiry limits
    rescue: GatewayRescueInfo;           // cancelDelayBlocks
    policy: GatewayPolicyInfo;
    availability: GatewayAvailability;
}

interface EarnVaultHistory {
    chainId: bigint;
    vaultAddress: string;
    protocol: string;
    protocolVersion: string;
    metric: string;              // "tvlUsd" | "netApy"
    period: string;
    interval: string;
    unit: string;
    lookbackHours?: bigint;
    periodAverage?: number;
    points: VaultHistoryPoint[]; // timestamp, value (undefined is an upstream gap)
    metadata: VaultHistoryMetadata;      // state, updatedAt
}

interface EarnVaultCharts {
    tvlUsd: EarnVaultHistory;
    netApy: EarnVaultHistory;
}

StartaleCampaignProgress

interface StartaleCampaignProgress {
  hasDepositedAtLeast10Usd: boolean;
  hasMadeTransfer: boolean;
  campaignTokenId?: number;   // undefined only when no campaign token is configured
}

SdkError

Tagged union. Every variant is a constructable class, checked via .instanceOf(err). See the Error Handling guide for patterns and the full variant table.

SdkError.NotConnected.instanceOf(err)
SdkError.NotAuthenticated.instanceOf(err)
SdkError.AuthenticationFailed.instanceOf(err)
SdkError.InvalidConfig.instanceOf(err)
SdkError.ConfigError.instanceOf(err)
SdkError.NetworkError.instanceOf(err)
SdkError.WalletError.instanceOf(err)
SdkError.SignatureRejected.instanceOf(err)
SdkError.InsufficientBalance.instanceOf(err)
SdkError.InvalidAddress.instanceOf(err)
SdkError.InvalidAmount.instanceOf(err)
SdkError.InvalidInput.instanceOf(err)
SdkError.SerializationError.instanceOf(err)
SdkError.AuthServerError.instanceOf(err)
SdkError.ShieldError.instanceOf(err)
SdkError.TransferError.instanceOf(err)
SdkError.NoteError.instanceOf(err)
SdkError.MerkleError.instanceOf(err)
SdkError.ApiError.instanceOf(err)
SdkError.RateLimited.instanceOf(err)
SdkError.Forbidden.instanceOf(err)
SdkError.ResourceNotFound.instanceOf(err)
SdkError.WaitTimeout.instanceOf(err)
SdkError.TransactionFailed.instanceOf(err)
SdkError.InternalError.instanceOf(err)
SdkError.TransactionReverted.instanceOf(err)
SdkError.CryptoError.instanceOf(err)
SdkError.StateError.instanceOf(err)
SdkError.OperationError.instanceOf(err)

The string tag is also available at runtime via SdkError_Tags:

if (err.tag === SdkError_Tags.NotConnected) { ... }

Gift Methods

Claimable transfers (gifts) — instance methods on sdk, taking positional arguments. See the Claimable Transfers guide and the concept page.

These methods may not be present in the checked-in generated bindings.

Each fund/claim/refund method returns a TransferResult whose giftRecord and claimLink fields are populated for gift operations.

sdk.giftFundToWallet(
  tokenAddress: string,
  amount: string,
  recipientWallet: string,
  refundAfterBlock: number,
  currentBlock: number,
): Promise<TransferResult>

Fund a gift bound to an Ethereum wallet address that may not be registered with Privacy Boost. amount is wei; refundAfterBlock/currentBlock are block numbers. Returns a TransferResult with claimLink and giftRecord populated.

sdk.giftFund(
  tokenAddress: string,
  amount: string,
  recipientPrivacyAddress: string,   // 194-char privacy address (ECDH target)
  recipientWallet: string,
  refundAfterBlock: number,
  currentBlock: number,
): Promise<TransferResult>

Fund a gift when the recipient is already a Privacy Boost user, sealing the ciphertext to their viewing key. The third argument is the 194-char privacy address.

sdk.giftClaim(index: number, acknowledgeUnknownSender: boolean): Promise<TransferResult>

Claim a pending gift by its position in getPendingGifts(). acknowledgeUnknownSender must be true — it acknowledges accepting funds from an unknown sender.

sdk.giftClaimByCGift(cGift: string, acknowledgeUnknownSender: boolean): Promise<TransferResult>

Claim a pending gift by its stable commitment cGift (preferred when the list may shift as gifts settle).

sdk.giftClaimFromLink(link: string, acknowledgeUnknownSender: boolean): Promise<TransferResult>

Claim a gift directly from a pbgift:v1:... claim link, without a server lookup first.

sdk.giftRefundByRecord(index: number): Promise<TransferResult>

Refund an unclaimed gift after its deadline, using a local gift record. index is the positional index into getGiftRecords().

sdk.giftRefund(
  recipientWallet: string,
  blind: string,
  refundAfterBlock: number,
  tokenId: number,
  amount: string,
  fundingTreeNumber: number,
  giftLeafIndex: number,
): Promise<TransferResult>

Refund an unclaimed gift by supplying every field manually — the fallback when the local gift record is unavailable.

sdk.getPendingGifts(): Promise<PendingGift[]>

List the pending gifts addressed to the authenticated wallet.

sdk.getGiftRecords(): GiftRecord[]

Return the local records the SDK persisted for gifts you funded. These make a gift refundable and travel inside an exported session. Synchronous.

sdk.decodeGiftLink(link: string): GiftLinkPreview     // throws

Decode a claim link into a preview offline, with no network call. Synchronous.

A third funding mode, giftFundSecretBearer, binds a gift to a secret instead of a wallet. It is a bearer instrument (whoever holds the link can claim), selected only by that explicit method. See the concept page before considering it.

GiftRecord

interface GiftRecord {
  recipientWallet: string;
  blind: string;
  refundAfterBlock: number;
  tokenId: number;
  amount: string;
  cGift: string;
  giftNpk: string;
  requestId: string;
  fundingTreeNumber?: number;
  giftLeafIndex?: number;
  status?: string;
}

PendingGift

interface PendingGift {
  index: number;
  treeNumber: number;
  leafIndex: number;
  cGift: string;
  tokenId: number;
  amount: string;
  refundAfterBlock: number;
  recipientWallet: string;
}

GiftLinkPreview

interface GiftLinkPreview {
  server: string;
  chainId: number;
  cGift: string;
  recipientWallet: string;
  tokenId: number;
  amount: string;
  refundAfterBlock: number;
}

The gift fields (giftRecord, claimLink) on TransferResult are populated only for gift operations; see UnshieldResult / TransferResult.

Portal

Portal deposit addresses. See the Portal Deposits guide and the concept page.

React Native exposes portal lifecycle methods on PrivacyBoost. Low-level portal functions are limited to custodial escape hatches.

The supported path is sdk.createPortal(...), which derives the portal EOA from the recovered nullifying key and keeps the key inside core.

sdk.createPortal(index?: number): Promise<Portal>

Derive portal E, gaslessly delegate and register it via the server relays, then publish the discovery entry. Omit index to use the next free derivation index.

sdk.listPortalsPage(
  cursor: string | undefined,
  limit: number,
): Promise<PortalInfoPage>

One page of the authenticated account’s portals with status and derivation index. limit must be between 1 and 100; pass the page’s nextCursor back as cursor to continue, and treat an absent nextCursor as the final page.

sdk.listPortalDepositsPage(
  portal: string,
  cursor: string | undefined,
  limit: number,
): Promise<PortalDepositPage>

One page of the deposits observed at portal. Same cursor and limit semantics.

sdk.getPortalStatus(portal: string): Promise<PortalStatus>

Return registry/on-chain status for one portal.

sdk.sweepPortal(portal: string, tokenId: number): Promise<string>

Send requestPortalDeposit from the connected wallet and return the transaction hash.

sdk.reclaimPortalDeposit(depositId: string): Promise<string>

Send cancelPortalDeposit from the connected wallet and return the transaction hash.

sdk.withdrawPortal(
  index: number,
  token: string,
  to: string,
  amount: string,
  nonce: string,
  gasLimit: string,
  maxFeePerGas: string,
  maxPriorityFeePerGas: string,
): string

Build a signed EIP-1559 transaction that withdraws raw funds resting at the seed-derived portal E. Broadcast the returned raw transaction yourself.

Low-level escape hatches

These module-level functions are imported from @sunnyside-io/privacy-boost-react-native and are for custodial integrations that manage their own portal EOA key. The seed-derived createPortal flow does not expose a private key.

generatePortalEoa(): PortalEoa

Generate a fresh portal EOA E and its secret private key.

encodePortalWithdraw(token: string, to: string, amount: string): string

Encode raw withdraw calldata for a custodial integration that already controls its own portal EOA.

sdk.publishPortalRegistry(portal: string, index: number): Promise<void>

Publish the discovery registry entry (E → blind) — the supported submit path so the indexer can credit deposits to the right account.

sdk.portalDelegateAddress(): string | undefined

Return the portal delegate address advertised by the server’s /info, or undefined if the server does not support portals.

PortalEoa

interface Portal {
  address: string;
  index: number;
  bindH: string;
}

interface PortalInfo {
  address: string;
  index: number;
  status: PortalStatus;
}

interface PortalInfoPage {
  items: PortalInfo[];
  nextCursor?: string;
}

interface PortalStatus {
  registered: boolean;
  delegated: boolean;
  published: boolean;
}

enum PortalDepositState {
  PendingSweep = 'PendingSweep',
  Credited = 'Credited',
  Cancellable = 'Cancellable',
  Cancelled = 'Cancelled',
  Unknown = 'Unknown',
}

interface PortalDeposit {
  portalDepositId: string;
  portal: string;
  tokenId: number;
  grossAmount: string;
  netAmount: string;
  sweepFeeBps: number; // rate snapshotted when this deposit was swept
  feeAmount: string;   // grossAmount - netAmount
  state: PortalDepositState;
  requestBlock: bigint;
  cancellableAtBlock: bigint;
}

interface PortalDepositPage {
  items: PortalDeposit[];
  nextCursor?: string;
}

interface PortalEoa {
  privateKey: string; // SECRET — custody it; never persisted by the SDK
  address: string;    // the portal deposit address E
}

Deposit Cancellation

sdk.shield(...) moves the depositor’s tokens into the pool and holds them there until the sequencer settles the request into the note tree. Almost always that happens within a couple of blocks. When it doesn’t, because of a commitment mismatch, a malformed ciphertext, or a stalled sequencer, the tokens stay in escrow and the depositor reclaims them by cancelling the request on-chain. The server will tell you a shield failed — getShieldStatus(requestId) returns failed for a commitment mismatch or a malformed ciphertext — but it says nothing about the escrow behind it: whether the pool still holds it, who may reclaim it, and when. A stalled sequencer doesn’t even produce that failed row. So use getShieldStatus to notice something went wrong, and these two methods to find out what you can do about it. They read the pool directly and tell you what it would do before you ask anyone to sign.

getDepositCancellation reads chain state, so it needs a ChainReaderDelegate registered with sdk.setChainReader(...). cancelDeposit works without one — it just skips its preflight. It’s the same optional delegate earn uses, and any RPC-connected wallet can back it.

interface ChainReaderDelegate {
  getBlockNumber(): Promise<bigint>;
  readContract(contractAddress: string, data: string): Promise<string>;
}

sdk.setChainReader(reader: ChainReaderDelegate): void

sdk.listShieldsByStatus(statuses: Array<string>): Promise<Array<UnsettledShield>>

Find a depositRequestId you never kept. Lists the authenticated wallet’s own shield requests in the given public statuses (pending, processing, preconfirmed, completed, failed), oldest first. An empty list means the server’s default of pending. Pass failed to list the shields whose escrow may still be sitting in the pool, then feed each requestId to getDepositCancellation. Served by the server and scoped to the session, so it needs no ChainReaderDelegate and cannot enumerate anyone else’s deposits. failed is a public status the server folds several internal ones into, so it also covers shields rejected as below-minimum or blocked; a stalled sequencer produces no failed row at all and stays pending. Each row is an UnsettledShield: requestId, status, and the optional txHash, blockNumber, createdAt and error.

sdk.depositRequestIdsFromTransaction(txHash: string): Promise<Array<string>>

The fallback when the app kept the shield’s transaction hash but not its request id. Reads the receipt and returns every DepositRequested id the pool emitted, in log order — more than one when an aggregating relayer settled several callers in the same transaction. Empty means the transaction emitted no DepositRequested from the configured pool, which is the answer for a hash that was never a shield rather than an error. Reads the chain, so it needs the same ChainReaderDelegate as getDepositCancellation.

sdk.getDepositCancellation(depositRequestId: string): Promise<DepositCancellation>

Read the pool and report whether cancelling would succeed for the connected wallet right now, without sending anything. Costs three eth_calls plus one eth_blockNumber, and rejects if no ChainReaderDelegate is set. depositRequestId is the DepositRequested event’s indexed topic1, a uint256. It’s the same value sdk.shield(...) and finalizeShield return as ShieldResult.requestId. Pass it as a decimal string or a 0x-hex string; the depositRequestId on the result is always normalized to decimal.

sdk.cancelDeposit(depositRequestId: string): Promise<string>

Cancel a stuck deposit and refund its full escrow to the depositor. Returns the transaction hash. The call preflights through getDepositCancellation and rejects locally, before anything is signed, when the pool would revert. The rejection message is the status reason, so a stuck deposit explains itself instead of burning gas on an opaque revert. Without a ChainReaderDelegate there’s no preflight: the transaction is submitted anyway and the chain arbitrates.

Who can cancel, and when

Only the address that submitted the deposit can cancel it, and the refund goes to that address. For a relayer-submitted shield that’s the relayer, not the note recipient, so a user whose deposit is genuinely theirs can still get NotDepositor back. The cancel delay is measured in blocks and read from the pool’s cancelDelay(). Read the deployed value instead of hardcoding a delay, using cancelDelay, cancellableAtBlock, and blocksRemaining from the returned status.

Cancellation states

state mirrors the reverts in the pool’s cancelDeposit, reported permanent-blocker first rather than in the pool’s own check order. The pool checks the depositor before anything else, and that check would mask the two conditions no caller can clear.

State	Meaning
`Cancellable`	Every precondition holds; the transaction should land.
`NotFound`	The pool holds no escrow under this id. It was never created, or it’s already been cancelled or rescued. Settling does not clear the record, so a settled deposit reports `AlreadyProcessed` instead.
`AlreadyProcessed`	The sequencer already settled this deposit into the note tree, so the funds are in a note rather than in escrow. This blocks the rescue path too, so it’s reported ahead of `GatewayOrigin`.
`GatewayOrigin`	A gateway-origin deposit. It carries a rescue commitment and has to be recovered with `rescueGatewayDeposit` by its rescue authority instead.
`NotDepositor`	Escrow exists but belongs to another address.
`TooEarly`	Escrow is reclaimable, but the cancel delay hasn’t elapsed yet. The one rejecting state that resolves on its own.

A gateway-origin deposit stores the gateway contract as its depositor, never the wallet whose funds routed through it, so it reports GatewayOrigin for every caller and at every point in the delay window. Waiting never makes it cancellable.

DepositCancellation

enum DepositCancelState {
  Cancellable,
  NotFound,
  NotDepositor,
  AlreadyProcessed,
  TooEarly,
  GatewayOrigin,
}

interface DepositCancellation {
  depositRequestId: string;   // the queried id, normalized to decimal
  state: DepositCancelState;
  cancellable: boolean;       // true exactly when state is Cancellable
  depositor?: string;         // undefined when no escrow exists
  caller: string;             // the address the status was evaluated against
  tokenId: number;
  totalAmount: string;        // escrow that would be refunded; "0" when absent
  requestBlock: bigint;
  cancelDelay: bigint;        // the pool's cancelDelay(), in blocks
  cancellableAtBlock: bigint; // requestBlock + cancelDelay
  currentBlock: bigint;       // chain head the status was evaluated at
  blocksRemaining: bigint;    // 0 once the delay has elapsed
  reason: string;             // human-readable explanation of state
}

​API Reference

​Module exports

​PrivacyBoost

​Constructor

​State

​Authentication

​Operations

​Earn and gateway

​Status polling

​Balances & tokens

​History & notes

​Merkle tree

​Audit APIs

​App metadata

​Private treasury

​Campaigns

​Session persistence

​Identity lookup

​Pending transactions

​Chain context

​Utilities

​ChainContextHandle

​Stateless shield helpers

​Delegate interfaces

​WalletDelegate

​TokenProvider

​KeychainDelegate

​Types

​PrivacyBoostConfig

​ChainContextConfig

​KeySource

​StorageBackend

​UnlockMethod

​AuthResult

​LoginResult

​ShieldResult

​Call / PreparedShield

​UnshieldResult / TransferResult

​ShieldStatus / TransactionStatus

​TokenBalance

​RegisteredToken

​FeeRates

​Transaction / TransactionNote / TransactionsResult

​TransactionHistoryQuery

​UnspentNote

​MerkleTreeStats

​Audit result types

​PendingTransaction

​ExportedSession

​IdentityResult

​AppInfoEntry

​Private treasury types

​Earn and gateway types

​StartaleCampaignProgress

​SdkError

​Gift Methods

​GiftRecord

​PendingGift

​GiftLinkPreview

​Portal

​Low-level escape hatches

​PortalEoa

​Deposit Cancellation

​Who can cancel, and when

​Cancellation states

​DepositCancellation

API Reference

Module exports

PrivacyBoost

Constructor

State

Authentication

Operations

Earn and gateway

Status polling

Balances & tokens

History & notes

Merkle tree

Audit APIs

App metadata

Private treasury

Campaigns

Session persistence

Identity lookup

Pending transactions

Chain context

Utilities

ChainContextHandle

Stateless shield helpers

Delegate interfaces

WalletDelegate

TokenProvider

KeychainDelegate

Types

PrivacyBoostConfig

ChainContextConfig

KeySource

StorageBackend

UnlockMethod

AuthResult

LoginResult

ShieldResult

Call / PreparedShield

UnshieldResult / TransferResult

ShieldStatus / TransactionStatus

TokenBalance

RegisteredToken

FeeRates

Transaction / TransactionNote / TransactionsResult

TransactionHistoryQuery

UnspentNote

MerkleTreeStats

Audit result types

PendingTransaction

ExportedSession

IdentityResult

AppInfoEntry

Private treasury types

Earn and gateway types

StartaleCampaignProgress

SdkError

Gift Methods

GiftRecord

PendingGift

GiftLinkPreview

Portal

Low-level escape hatches

PortalEoa

Deposit Cancellation

Who can cancel, and when

Cancellation states

DepositCancellation