API Reference

Complete API reference for the Privacy Boost React SDK.

Generated Documentation

Full API documentation can be generated using TypeDoc:

# From packages/privacy-boost-react directory
npm run docs

# Documentation will be generated in docs/api/

The generated docs include:

All hook signatures and return types
JSDoc comments with usage examples
Type definitions and interfaces

Provider

`PrivacyBoostProvider`

Main provider component that initializes the SDK.

<PrivacyBoostProvider
  config={PrivacyBoostConfig}
  loadingComponent?: ReactNode
  errorComponent?: (error: Error) => ReactNode
>
  {children}
</PrivacyBoostProvider>

// Or with pre-initialized SDK
<PrivacyBoostProvider sdk={PrivacyBoost}>
  {children}
</PrivacyBoostProvider>

Context Hooks

`usePrivacyBoost()`

Get direct access to the SDK instance.

function usePrivacyBoost(): PrivacyBoost | null

`usePrivacyBoostState()`

Get provider initialization state.

function usePrivacyBoostState(): {
  loading: boolean;
  error: Error | null;
  initialized: boolean;
}

useAuth

Authentication hook.

function useAuth(): UseAuthResult

interface UseAuthResult {
  // State
  isConnected: boolean;
  isAuthenticated: boolean;
  isWalletAvailable: boolean;
  address: string | null;
  privacyAddress: string | null;
  mpk: string | null;

  // Methods
  authenticate(adapter: WalletAdapter, options?: AuthenticateOptions): Promise<AuthResult>;
  authenticateWithWalletAdapter(options?: AuthenticateOptions): Promise<AuthResult>;
  logout(): Promise<void>;
  clearSession(): Promise<void>;
}

useVault

Vault operations hook.

function useVault(): UseVaultResult

interface UseVaultResult {
  shield(params: SimpleShieldParams): Promise<ShieldResult>;
  unshield(params: SimpleUnshieldParams): Promise<UnshieldResult>;
  send(params: SimpleSendParams): Promise<TransactionResult>;
  /** Pay several recipients in one transfer: one request, one fee. */
  sendBatch(params: SimpleSendBatchParams): Promise<TransactionResult>;
  getBalance(tokenAddress: string): Promise<TokenBalance>;
  getAllBalances(): Promise<TokenBalance[]>;
  getTokens(): Promise<TokenMetadata[]>;
  /** Force a server refresh of one token's balance. */
  refreshBalance(tokenAddress: Hex): Promise<void>;
  /** Force a server refresh of all tracked balances. */
  refreshBalances(): Promise<void>;
}

interface SimpleShieldParams {
  tokenAddress: Hex;
  /** Either a human-readable string (e.g. "1.5") or a wei `bigint`. Strings are parsed using the token's `decimals`. */
  amount: string | bigint;
  onProgress?: OnProgress;
}

interface SimpleUnshieldParams {
  tokenAddress: Hex;
  amount: string | bigint;
  /** Recipient Ethereum address. Defaults to the connected wallet address. */
  recipient?: Hex;
  /** @deprecated Use `recipient`. */
  recipientAddress?: Hex;
  onProgress?: OnProgress;
}

interface SimpleSendParams {
  tokenAddress: Hex;
  amount: string | bigint;
  /** Recipient privacy address. */
  recipient?: Hex;
  /** @deprecated Use `recipient`. */
  to?: Hex;
}

useFees

Reactive ordinary or Gateway-specific fee quotes.

function useFees(options?: UseFeesOptions): UseFeesReturn

interface UseFeesOptions {
  tokenAddress?: Hex;
  gatewayAddress?: GatewayAddress;
  gatewaySelector?: GatewaySelector;
}

interface UseFeesReturn {
  data: FeeRates | null;
  fees: FeeRates | null;
  isLoading: boolean;
  loading: boolean;
  error: PrivacyBoostError | null;
  refetch(): Promise<void>;
  calculateFee(
    amount: bigint,
    type: 'transfer' | 'unshield' | 'gateway',
    options?: CalculateFeeOptions,
  ): bigint | null;
  formatFeeRate(type: 'transfer' | 'unshield' | 'gateway'): string;
}

With only tokenAddress, the hook calls the ordinary getFees API. Supplying gatewayAddress switches to getGatewayFees; add gatewaySelector for an exact selector override. A selector without an address is rejected. For a Gateway quote, calculateFee(..., 'gateway') and formatFeeRate('gateway') use the Gateway rate that replaces the ordinary unshield fee.

const { fees, calculateFee, isLoading, error } = useFees({
  tokenAddress,
  gatewayAddress,
  gatewaySelector: '0xd0e30db0',
});

useBalances

Reactive balance data hook.

function useBalances(): UseBalancesResult

interface UseBalancesResult {
  balances: FormattedBalance[];
  loading: boolean;
  lastSynced: number | null;
  getBalance(tokenAddress: string): FormattedBalance | undefined;
  getShieldedBalance(tokenAddress: string): bigint;
  getWalletBalance(tokenAddress: string): bigint;
  totalShielded: bigint;
  tokenCount: number;
}

interface FormattedBalance extends TokenBalance {
  formattedShielded: string;
  formattedWallet: string;
}

useTransactions

Transaction history hook.

function useTransactions(): UseTransactionsResult

interface UseTransactionsResult {
  transactions: Transaction[];
  recentTransactions: Transaction[];
  pending: Transaction[];
  isLoading: boolean;
  hasPending: boolean;
  pendingCount: number;
  deposits: Transaction[];
  withdrawals: Transaction[];
  transfers: Transaction[];
  fetchHistory(params?: TransactionHistoryParams): Promise<Transaction[]>;
  refreshPending(): Promise<number>;
  getByHash(txHash: string): Transaction | undefined;
  getByType(type: TransactionType): Transaction[];
  getByStatus(status: TransactionStatus): Transaction[];
}

interface TransactionHistoryParams {
  type?: 'shield' | 'unshield' | 'transfer';
  tokenAddress?: string;
  limit?: number;
}

useChain

Get a chain-scoped client for multi-chain operations.

function useChain(config: ChainClientConfig): ChainClient | null

interface ChainClientConfig {
  /** Server URL for the chain. Required. */
  serverUrl: string;
  /** EVM chain ID. Auto-discovered from the server when omitted. */
  chainId?: number;
  /** Shield contract address on this chain. Auto-discovered when omitted. */
  shieldContractAddress?: string;
  /** WETH address on this chain. Required for native-ETH flows. */
  wethContractAddress?: string;
  rpcUrl?: string;
  tokenRegistryAddress?: string;
  pinnedTransportKeys?: TransportServerKeyInfo[];
  allowPlaintext?: boolean;
}

The returned ChainClient exposes the same vault, transactions, audit, and campaigns resources as the root SDK, scoped to the target chain. Authentication is a method rather than a resource — call chain.authenticate(walletBridge). Returns null until the provider has finished initializing. The hook memoizes by serverUrl, so changing other fields between renders is ignored — pass a stable config or a new serverUrl to switch chains.

useCampaignProgress

Read the authenticated user’s Startale mission progress.

function useCampaignProgress(): UseCampaignProgressReturn

interface UseCampaignProgressReturn {
  /** Mission progress, or null before the first fetch settles or after one failed. */
  data: StartaleCampaignProgress | null;
  /** Alias for `data`. */
  progress: StartaleCampaignProgress | null;
  isLoading: boolean;
  /** Alias for `isLoading`. */
  loading: boolean;
  error: PrivacyBoostError | null;
  refetch: () => Promise<void>;
}

interface StartaleCampaignProgress {
  hasDepositedAtLeast10Usd: boolean;
  hasMadeTransfer: boolean;
  /** Registry token ID the deposit mission is scoped to, if the server scopes it. */
  campaignTokenId?: number;
}

The hook requires the full auth tier, so it stays idle until the session is authenticated and fetches once it becomes so. It reads through the provider’s active client, so after a chain switch it reports the progress of the chain currently in view. On failure it reports null with an error rather than falling back to { false, false }. The server answers 503 when a shield token price is unavailable, and rendering that as “mission incomplete” would tell a user who qualified that they did not. See the sdk.campaigns section of the TypeScript API reference for what each mission counts, why hasDepositedAtLeast10Usd is not monotonic, and what campaignTokenId changes about which deposits count.

function MissionList() {
  const { progress, isLoading, error } = useCampaignProgress();

  if (isLoading) return <div>Loading progress...</div>;
  if (error) return <div>Progress unavailable. Try again shortly.</div>;
  // Idle: the session is not authenticated yet, so there is nothing to report.
  if (!progress) return null;

  // Scoped to one token when campaignTokenId is present, otherwise any token
  // the user shields counts toward the $10.
  const depositLabel =
    progress.campaignTokenId === undefined
      ? 'Deposit $10'
      : `Deposit $10 of token #${progress.campaignTokenId}`;

  return (
    <ul>
      <li>{progress.hasDepositedAtLeast10Usd ? '✓' : '○'} {depositLabel}</li>
      <li>{progress.hasMadeTransfer ? '✓' : '○'} Make a private transfer</li>
    </ul>
  );
}

usePortal

Hidden-recipient portal deposits: create portals, list them and their deposits, and drive the sweep / reclaim / withdraw actions.

function usePortal(): UsePortalReturn

interface UsePortalReturn {
  /** Every portal of the authenticated account, accumulated across pages by `refresh`. */
  portals: PortalInfo[];
  /** Alias for `portals`. */
  data: PortalInfo[];
  loading: boolean;
  /** Alias for `loading`. */
  isLoading: boolean;
  error: PrivacyBoostError | null;
  refresh: () => Promise<void>;
  /** Alias for `refresh`. */
  refetch: () => Promise<void>;
  /** Re-reads `portals` afterwards: the listing carries fields a new portal does not. */
  create: (opts?: CreatePortalOptions) => Promise<Portal>;
  listPage: (options?: PortalPageOptions) => Promise<PortalInfoPage>;
  depositsPage: (address: string, options?: PortalPageOptions) => Promise<PortalDepositPage>;
  status: (address: string) => Promise<PortalStatus>;
  sweep: (address: string, tokenId: number) => Promise<string>;
  reclaim: (depositId: string) => Promise<string>;
  withdraw: (params: WithdrawPortalParams) => Promise<string>;
  delegateAddress: () => Promise<string | undefined>;
}

refresh pages through listPage until the cursor runs out and runs automatically once the session is authenticated; it records failures in error rather than rejecting. Portals are bound to the chain the root SDK was configured for and ChainClient has no portal resource, so this hook reads the root client and does not follow the provider’s active client. See the Portal Deposits guide.

useGifts

Claimable transfers: fund a gift in any of the three modes, claim one by commitment or link, refund an unclaimed one, and read the pending gifts plus this session’s funding records.

function useGifts(): UseGiftsReturn

interface UseGiftsReturn {
  /** Gifts addressed to this wallet that are funded and not yet claimed. */
  pendingGifts: PendingGift[];
  /** Gifts funded during this session, newest first. In-memory, so empty after a reload. */
  giftRecords: GiftRecord[];
  loading: boolean;
  /** Alias for `loading`. */
  isLoading: boolean;
  error: PrivacyBoostError | null;
  refresh: () => Promise<void>;
  /** Alias for `refresh`. */
  refetch: () => Promise<void>;
  /** Seals the ciphertext to a recipient privacy address; still binds to `recipientWallet`. */
  fund: (params: GiftFundParams) => Promise<GiftResult>;
  fundToWallet: (params: GiftFundToWalletParams) => Promise<GiftResult>;
  /** Link-only gift: the returned `claimLink` is a bearer credential and no record comes back. */
  fundSecretBearer: (params: GiftFundSecretBearerParams) => Promise<GiftResult>;
  claimByCGift: (params: GiftClaimByCGiftParams) => Promise<GiftResult>;
  claimFromLink: (params: GiftClaimFromLinkParams) => Promise<GiftResult>;
  refund: (params: GiftRefundParams) => Promise<GiftResult>;
  /** Reclaim by position in `giftRecords`; only reaches gifts funded in this session. */
  refundByRecord: (index: number) => Promise<GiftResult>;
  decodeLink: (link: string) => Promise<GiftLinkPreview>;
}

Every funding, claim and refund re-reads both lists, so pendingGifts and giftRecords are the read surface and no imperative getter is needed. Block heights are decimal strings, not numbers, because they cross the vault boundary. giftRecords is the SDK’s in-memory ledger rather than a server query: an app that funds gifts must persist the records itself to stay able to refund after a reload. Gifts are bound to the root SDK’s chain, so this hook reads the root client. See the Claimable Transfers guide.

useEarn

ERC-4626 Gateway operations: the vault catalog, gateway configuration, deposit and redeem, history charts, and the on-chain output preview.

function useEarn(): UseEarnReturn

interface UseEarnReturn {
  /** The earn vault catalog, or null before the first fetch settles. */
  vaults: EarnVaultsResponse | null;
  /** Alias for `vaults`. */
  data: EarnVaultsResponse | null;
  loading: boolean;
  /** Alias for `loading`. */
  isLoading: boolean;
  error: PrivacyBoostError | null;
  refresh: () => Promise<void>;
  /** Alias for `refresh`. */
  refetch: () => Promise<void>;
  listVaults: () => Promise<EarnVaultsResponse>;
  /** One vault with the detail route's extra fields (owner, guardian, share price). */
  getVault: (vaultAddress: string) => Promise<EarnVaultDetail>;
  getGatewayConfig: () => Promise<GatewayConfig>;
  deposit: (params: EarnParams) => Promise<EarnResult>;
  redeem: (params: EarnParams) => Promise<EarnResult>;
  vaultHistory: (
    vaultAddress: string,
    metric: EarnHistoryMetric,
    period?: EarnHistoryPeriod,
  ) => Promise<EarnVaultHistory>;
  vaultCharts: (vaultAddress: string, period?: EarnHistoryPeriod) => Promise<EarnVaultCharts>;
  previewOutput: (
    action: 'deposit' | 'redeem',
    vaultAddress: string,
    amount: bigint,
  ) => Promise<bigint>;
}

The catalog is public, so refresh runs as soon as the SDK is available rather than waiting for authentication. Earn runs inside the shared key vault, which is bound to the root SDK’s chain and rejects the whole surface on a ChainClient, so this hook reads the root client rather than the provider’s active client.

useSwap

Server-quoted Gateway swaps, plus the gateway fee lookup a swap UI prices against.

function useSwap(): UseSwapReturn

interface UseSwapReturn {
  loading: boolean;
  /** Alias for `loading`. */
  isLoading: boolean;
  error: PrivacyBoostError | null;
  /** Preview a validated quote without submitting it. */
  createQuote: (params: CreateSwapQuoteParams) => Promise<SwapQuote>;
  /** Execute a quote from `createQuote`, unchanged. */
  swapFromQuote: (params: SwapFromQuoteParams) => Promise<SwapResult>;
  /** Fetch a fresh quote and submit it in one call. */
  swap: (params: SwapParams) => Promise<SwapResult>;
  getGatewayFees: (
    tokenAddress: Hex,
    gatewayAddress: GatewayAddress,
    gatewaySelector?: GatewaySelector,
  ) => Promise<FeeRates>;
}

isSwapQuoteExecutable and swapQuoteEconomics are pure and need no hook state, so import them from @sunnyside-io/privacy-boost-react directly rather than through this return. Hand a quote back to swapFromQuote unchanged: callData and minOutputAmount are what get signed, so reshaping any field means signing something other than what was quoted. Like earn, swaps run in the root-bound key vault, so this hook reads the root client.

useContacts

The private treasury address book, stored encrypted per wallet on the server.

function useContacts(): UseContactsReturn

interface UseContactsReturn {
  /** Every contact, as of the last `refresh`. */
  contacts: Contact[];
  /** Alias for `contacts`. */
  data: Contact[];
  loading: boolean;
  /** Alias for `loading`. */
  isLoading: boolean;
  error: PrivacyBoostError | null;
  refresh: () => Promise<void>;
  /** Alias for `refresh`. */
  refetch: () => Promise<void>;
  create: (input: CreateContactInput) => Promise<Contact>;
  bulkCreate: (contacts: CreateContactInput[]) => Promise<BulkContactsResult>;
  update: (id: string, input: UpdateContactInput) => Promise<Contact>;
  remove: (id: string) => Promise<void>;
}

refresh runs automatically once the session is authenticated and pages through the whole list. create, update and remove keep contacts in step from their own results, so a refresh is only needed to pick up a change made elsewhere; bulkCreate returns ids rather than rows, so it re-reads the list itself. A contact the server can no longer decrypt arrives with decryptionFailed: true and empty content fields: show it as unreadable rather than dropping it, because the row still exists.

useLabels

Private memos and contact links keyed by transaction hash. Same storage and session model as contacts.

function useLabels(): UseLabelsReturn

interface UseLabelsReturn {
  /** Every label, as of the last `refresh`. */
  labels: TransactionLabel[];
  /** Alias for `labels`. */
  data: TransactionLabel[];
  loading: boolean;
  /** Alias for `loading`. */
  isLoading: boolean;
  error: PrivacyBoostError | null;
  refresh: () => Promise<void>;
  /** Alias for `refresh`. */
  refetch: () => Promise<void>;
  upsert: (txHash: string, input: UpsertLabelInput) => Promise<TransactionLabel>;
  remove: (txHash: string) => Promise<void>;
}

upsert is a PUT that replaces the whole label, so a field you omit is cleared on an existing one. It and remove keep labels in step from their own results, so a refresh is only needed to pick up a change made elsewhere. Like contacts, a row the server cannot decrypt comes back with decryptionFailed: true.

Helper Functions

`createWalletAdapter()`

Create wallet adapter from window.ethereum.

function createWalletAdapter(): WalletAdapter

Types

PrivacyBoostConfig

interface PrivacyBoostConfig {
  appId: string;
  serverUrl: string;
  chainId?: number;                 // Auto-discovered from server if omitted
  shieldContractAddress?: string;   // Auto-discovered from server if omitted
  wethContractAddress?: string;
  rpcUrl?: string;
  tokenRegistryAddress?: string;
  persistence?: {
    storage: 'localStorage' | 'indexedDB' | 'osKeychain';
    unlock?: 'none' | 'pin' | 'password';
  };
}

Transaction

interface ReceiverTransfer {
  pubKey: Hex;
  amount: bigint;
}

interface Transaction {
  txHash: Hex;
  type: 'shield' | 'unshield' | 'transfer';
  direction: 'incoming' | 'outgoing';
  status: 'pending' | 'preconfirmed' | 'completed' | 'failed' | 'blocked';
  tokenAddress?: Hex;
  amount?: bigint;
  receivers: ReceiverTransfer[];
  createdAt: number;
  updatedAt: number;
  to?: Hex;
  from?: Hex;
  error?: string;
  tokenSymbol?: string;
  commitment?: Hex;
  complianceStatus?: ComplianceStatus;  // 'PENDING' | 'LEGIT' | 'ILLICIT'
}

TokenBalance

interface TokenBalance {
  tokenAddress: Hex;
  /** Private balance held in the shielded pool, in token wei. */
  shieldedBalance: bigint;
  /** Public balance in the connected wallet, in token wei. */
  walletBalance: bigint;
  symbol?: string;
  decimals?: number;
  /** Number of unspent notes contributing to `shieldedBalance`. */
  noteCount?: number;
}

useBalances() returns FormattedBalance values, which extend TokenBalance with formattedShielded / formattedWallet strings already formatted with the token’s decimals.

FeeRates

interface FeeRates {
  transferFeeFlat: string;
  unshieldFeeBps: number;
  feeModel?: 'user_pays' | 'app_pays';
  minTransferAmountUSD?: number;
  feeSchemaVersion?: number;
  requiresFeeSchemaVersion?: number;
  transferRequiresFeeSchemaVersion?: number;
  unshieldRequiresFeeSchemaVersion?: number;
  transferFeeMode?: 'flat' | 'bps';
  transferFeeBps?: number;
  unshieldFeeMode?: 'flat' | 'bps';
  unshieldFeeFlat?: string;
  gatewayAddress?: GatewayAddress;
  gatewaySelector?: GatewaySelector;
  gatewayFeeMode?: 'flat' | 'bps';
  gatewayFeeFlat?: string;
  gatewayFeeRate?: number;
  gatewayFeeRateDenominator?: number;
  gatewayFeeBase?: 'flat' | 'unshield_amount' | 'zero';
  gatewayRequiresFeeSchemaVersion?: number;
}

Gateway fields are present on quotes requested with gatewayAddress. The Gateway fee replaces the ordinary unshield fee for that operation.

OnProgress

type OnProgress = (progress: {
  step: ShieldStep | UnshieldStep;
  message: string;
  txHash?: Hex;
}) => void;

Gifts and Portals

Both features have dedicated hooks; usePrivacyBoost() reaches the same resources directly when you want to drive them yourself.

Claimable Transfers: useGifts(), or sdk.gifts
Portal Deposits: usePortal(), or sdk.portal

Quickstart

Setup

SDKs

Api reference

API Reference

Generated Documentation

Provider

`PrivacyBoostProvider`

Context Hooks

`usePrivacyBoost()`

`usePrivacyBoostState()`

useAuth

useVault

useFees

useBalances

useTransactions

useChain

useCampaignProgress

usePortal

useGifts

useEarn

useSwap

useContacts

useLabels

Helper Functions

`createWalletAdapter()`

Types

PrivacyBoostConfig

Transaction

TokenBalance

FeeRates

OnProgress

Gifts and Portals

​API Reference

​Generated Documentation

​Provider

​PrivacyBoostProvider

​Context Hooks

​usePrivacyBoost()

​usePrivacyBoostState()

​useAuth

​useVault

​useFees

​useBalances

​useTransactions

​useChain

​useCampaignProgress

​usePortal

​useGifts

​useEarn

​useSwap

​useContacts

​useLabels

​Helper Functions

​createWalletAdapter()

​Types

​PrivacyBoostConfig

​Transaction

​TokenBalance

​FeeRates

​OnProgress

​Gifts and Portals

API Reference

Generated Documentation

Provider

`PrivacyBoostProvider`

Context Hooks

`usePrivacyBoost()`

`usePrivacyBoostState()`

useAuth

useVault

useFees

useBalances

useTransactions

useChain

useCampaignProgress

usePortal

useGifts

useEarn

useSwap

useContacts

useLabels

Helper Functions

`createWalletAdapter()`

Types

PrivacyBoostConfig

Transaction

TokenBalance

FeeRates

OnProgress

Gifts and Portals