Api reference

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>;
  getBalance(tokenAddress: string): Promise<bigint>;
  getAllBalances(): Promise<TokenBalance[]>;
  getRegisteredTokens(): Promise<RegisteredToken[]>;
  syncBalance(tokenAddress: Hex): Promise<void>;
  syncAllBalances(): Promise<void>;
}

interface SimpleDepositParams {
  tokenAddress: Hex;
  amount: string | bigint;
  onProgress?: OnProgress;
}

interface SimpleUnshieldParams {
  tokenAddress: Hex;
  amount: string | bigint;
  recipientAddress?: Hex;
  onProgress?: OnProgress;
}

interface SimpleSendParams {
  to: Hex | string;
  tokenAddress: Hex;
  amount: string | bigint;
}

---

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?: 'deposit' | 'withdraw' | 'transfer';
  tokenAddress?: string;
  limit?: number;
}

---

Helper Functions

createWalletAdapter()

Create wallet adapter from window.ethereum.

function createWalletAdapter(): WalletAdapter

---

Types

PrivacyBoostConfig

interface PrivacyBoostConfig {
  appId: string;
  indexerUrl: string;
  chainId?: number;               // Auto-discovered from indexer if omitted
  shieldContract?: string;         // Auto-discovered from indexer if omitted
  wethContract?: 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: 'deposit' | 'withdraw' | 'transfer';
  direction: 'incoming' | 'outgoing';
  status: 'pending' | 'completed' | 'failed';
  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;
  shielded: bigint;
  wallet: bigint;
  symbol?: string;
  decimals?: number;
}

OnProgress

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