Api reference

API Reference

Complete API reference for the Privacy Boost TypeScript SDK.

Generated Documentation

Full API documentation can be generated using TypeDoc:

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

# Documentation will be generated in docs/api/

The generated docs include:

• All exported types and interfaces
• JSDoc comments and examples
• Type signatures and inheritance

---

PrivacyBoost

Main SDK class.

PrivacyBoost.create(config)

Creates and initializes a new SDK instance.

static async create(config: PrivacyBoostConfig): Promise<PrivacyBoost>

Parameters:

Name	Type	Description
config.appId	string	Application identifier
config.indexerUrl	string	Indexer service URL
config.chainId	number	(Optional) EVM chain ID (auto-discovered from indexer)
config.shieldContract	string	(Optional) Shield contract address (auto-discovered from indexer)
config.wethContract	string	(Optional) WETH contract address

Example:

const sdk = await PrivacyBoost.create({
  appId: 'your-app-id',
  indexerUrl: 'https://test-api.privacy-boost.sunnyside.io/indexer',
  wethContract: "0x4200000000000000000000000000000000000006"
});

---

sdk.auth

Authentication resource.

auth.authenticate(adapter, options?)

Connect a wallet, derive privacy keys, and authenticate with the server in a single call.

async authenticate(
  adapter: WalletAdapter,
  options?: AuthenticateOptions
): Promise<AuthResult>

interface AuthenticateOptions {
  keySource?: KeySource;
  tokenProvider?: (payload: LoginPayload) => Promise<{ token: string; expiresIn: number }>;
}

Parameters:

Name	Type	Description
adapter	WalletAdapter	Wallet adapter implementation
options	AuthenticateOptions	(Optional) Options object with keySource and tokenProvider
options.keySource	KeySource	(Optional) Key derivation source. Defaults to walletDerived when no persistence is configured.
options.tokenProvider	function	(Optional) Callback to obtain a JWT from the login payload

Returns: AuthResult - either { status: 'authenticated', privacyAddress, mpk } or { status: 'credentialRequired', action, unlockType, submit }. If credential is required, call result.submit(credential) to complete authentication.

auth.logout()

End session completely, clear all state.

async logout(): Promise<void>

auth.clearSession()

Clear JWT only, keep keys for quick re-auth.

async clearSession(): Promise<void>

auth.isConnected()

Check if wallet is connected.

isConnected(): boolean

auth.isAuthenticated()

Check if user is authenticated.

isAuthenticated(): boolean

auth.getPrivacyAddress()

Get user’s privacy address.

getPrivacyAddress(): string | null

auth.getMpk()

Get user’s master public key.

getMpk(): string | null

sdk.vault

Vault resource for privacy operations.

vault.shield(params)

Deposit tokens to private balance.

async shield(params: ShieldParams): Promise<ShieldResult>

interface ShieldParams {
  tokenAddress: Hex;
  amount: bigint;
  recipientMpk?: bigint;
  onProgress?: OnProgress;
}

interface ShieldResult {
  txHash: Hex;
  commitment: Hex;
  fee: bigint;
  wrapTxHash?: Hex;
}

vault.unshield(params)

Withdraw tokens to public address.

async unshield(params: UnshieldParams): Promise<UnshieldResult>

interface UnshieldParams {
  tokenAddress: Hex;
  amount: bigint;
  recipientAddress: Hex;
  onProgress?: OnProgress;
}

interface UnshieldResult {
  txHash: Hex;
  amount: bigint;
}

vault.send(params)

Send private transfer.

async send(params: SendParams): Promise<TransactionResult>

interface SendParams {
  to: PrivacyAddress;
  tokenAddress: Hex;
  amount: bigint;
}

interface TransactionResult {
  txHash: Hex;
}

vault.getBalance(tokenAddress)

Get shielded balance for a token.

async getBalance(tokenAddress: string): Promise<bigint>

vault.getAllBalances()

Get all token balances.

async getAllBalances(): Promise<TokenBalance[]>

interface TokenBalance {
  tokenAddress: Hex;
  shielded: bigint;
  wallet: bigint;
  symbol?: string;
  decimals?: number;
}

vault.syncBalance(tokenAddress)

Sync balance from indexer.

async syncBalance(tokenAddress: Hex): Promise<void>

vault.syncAllBalances()

Sync all balances from indexer.

async syncAllBalances(): Promise<void>

vault.getToken(address)

Get token metadata.

async getToken(address: string): Promise<TokenMetadata>

interface TokenMetadata {
  address: Hex;
  symbol: string;
  decimals: number;
  name: string;
}

vault.getSupportedTokens()

Get list of supported tokens.

async getSupportedTokens(): Promise<TokenMetadata[]>

vault.parseAmount(tokenAddress, amount)

Parse string amount to bigint.

async parseAmount(tokenAddress: string, amount: string): Promise<bigint>

vault.formatAmount(amount, decimals)

Format bigint to string.

formatAmount(amount: bigint, decimals: number): string

---

sdk.transactions

Transactions resource.

transactions.fetchHistory(params?)

Get transaction history.

async fetchHistory(params?: TransactionHistoryParams): Promise<Transaction[]>

interface TransactionHistoryParams {
  type?: TransactionType;
  tokenAddress?: string;
  limit?: number;
}

interface Transaction {
  txHash: Hex;
  type: TransactionType;
  direction: TransactionDirection;
  status: TransactionStatus;
  tokenAddress?: Hex;
  amount?: bigint;
  receivers: ReceiverTransfer[];
  createdAt: number;
  updatedAt: number;
  to?: Hex;
  from?: Hex;
  tokenSymbol?: string;
  commitment?: Hex;
  complianceStatus?: ComplianceStatus;
  error?: string;
}

enum TransactionType {
  deposit = 'deposit',
  withdraw = 'withdraw',
  transfer = 'transfer',
}

enum TransactionDirection {
  incoming = 'incoming',
  outgoing = 'outgoing',
}

enum TransactionStatus {
  pending = 'pending',
  completed = 'completed',
  failed = 'failed',
}

---

Utility Functions

isValidPrivacyAddress(address)

Check if address is valid privacy address.

function isValidPrivacyAddress(address: string): boolean

validatePrivacyAddress(address)

Validate a privacy address.

function validatePrivacyAddress(address: string): { valid: boolean; message: string }

encodePrivacyAddress(mpk, viewingPublicKey)

Encode MPK and viewing public key to privacy address.

function encodePrivacyAddress(mpk: bigint, viewingPublicKey: Point): PrivacyAddress

decodePrivacyAddress(address)

Decode privacy address to components.

function decodePrivacyAddress(address: PrivacyAddress): {
  mpk: bigint;
  viewingPublicKey: Point;
}

extractMpkFromPrivacyAddress(address)

Extract MPK from privacy address.

function extractMpkFromPrivacyAddress(address: PrivacyAddress): Hex

isEvmAddress(address)

Check if valid EVM address.

function isEvmAddress(address: string): boolean

isNativeEth(address)

Check if address represents native ETH.

function isNativeEth(address: Hex): boolean

---

Types

KeySource

Key derivation source, passed to authenticate().

type KeySource =
  | { type: 'walletDerived' }
  | { type: 'mnemonic'; phrase: string }
  | { type: 'rawSeed'; hexSeed: string };

Variant	Description
walletDerived	Derive keys from a wallet signature (default when no persistence is configured)
mnemonic	Derive keys from a BIP-39 mnemonic phrase
rawSeed	Derive keys from a raw 32-byte hex seed

Hex

type Hex = `0x${string}`

PrivacyAddress

type PrivacyAddress = string // 96-byte encoded address (194 chars)

WalletAdapter

interface WalletAdapter {
  connect(): Promise<{ address: string; chainId: number }>;
  disconnect(): Promise<void>;
  signMessage(message: string): Promise<string>;
  signTypedData(typedData: string): Promise<string>;
  sendTransaction(tx: unknown): Promise<string>;
  getAddress(): Promise<string>;
  getChainId(): Promise<number>;
}

OnProgress

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

---

Constants

const NATIVE_ETH_ADDRESS = '0x0000000000000000000000000000000000000000';
const PRIVACY_ADDRESS_LENGTH = 194;
const PRIVACY_ADDRESS_HEX_LENGTH = 192;