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

# Documentation will be generated in docs/api/

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

const sdk = await PrivacyBoost.create({
  appId: 'your-app-id',
  serverUrl: 'https://optimism.sepolia.privacyboost.io',
  wethContractAddress: "0x4200000000000000000000000000000000000006"
});

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

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

async logout(): Promise<void>

async clearSession(): Promise<void>

isConnected(): boolean

isAuthenticated(): boolean

getPrivacyAddress(): string | null

getMpk(): string | null

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

interface ShieldParams {
  tokenAddress: Hex;
  amount: bigint;
  /** Defaults to the caller's own MPK. Set to shield directly to another user. */
  recipientMpk?: bigint;
  onProgress?: OnProgress;
}

interface ShieldResult {
  /** Hash of the shield transaction submitted to the chain. */
  txHash: Hex;
  /** Note commitment registered in the shielded pool. */
  commitment: Hex;
  /** Fee charged for this shield, in token wei. Not surfaced by the shield response, so usually undefined; query `vault.getFees()` for the schedule. */
  fee?: bigint;
  /** On-chain shield request ID, from the `ShieldRequested` event. */
  requestId: string;
  /** Set only when ETH was wrapped to WETH as part of the flow. */
  wrapTxHash?: Hex;
}

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

interface UnshieldParams {
  tokenAddress: Hex;
  amount: bigint;
  recipientAddress: Hex;
  onProgress?: OnProgress;
  /**
   * When true and the token is WETH, automatically wait for the unshield to
   * land on-chain and then unwrap the received WETH back to native ETH.
   * Requires `wethContractAddress` to be configured. Reports
   * `UnshieldStep.unwrapping` via `onProgress`.
   */
  unwrapWeth?: boolean;
}

interface UnshieldResult {
  /** Server-side request ID for this unshield. Use to track status. */
  requestId: string;
  /**
   * Local placeholder hash used to track pending status until the canonical
   * on-chain hash is available. Not the final on-chain transaction hash.
   */
  txHash: Hex;
  /** Amount unshielded, in token wei. */
  amount: bigint;
}

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

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

interface TransactionResult {
  /** Server-side request ID for this transfer. Use to track status. */
  requestId: string;
  /**
   * Local placeholder hash used to track pending status until the canonical
   * on-chain hash is available. Not the final on-chain transaction hash.
   */
  txHash: Hex;
}

async prepareShield(params: PrepareShieldParams): Promise<PreparedShield>

interface PrepareShieldParams {
  tokenAddress: Hex;
  amount: bigint;
  /** Recipient privacy address. Omit to shield to yourself. */
  recipient?: PrivacyAddress;
}

interface PreparedShield {
  /** ERC-20 approve(pool, amount). Omitted when allowance is managed out of band. */
  approve?: ShieldCall;
  /** WETH deposit() wrap. Present only when shielding native ETH. */
  wrap?: ShieldCall;
  /** The requestDeposit(...) call. */
  shield: ShieldCall;
  /** Note commitment to track; also appears on-chain inside the shield call. */
  commitment: string;
  finalize: { shieldContract: string; tokenId: number };
}

/** A single on-chain call to relay. `value` and `data` are 0x-hex. */
interface ShieldCall {
  to: string;
  value: string;
  data: string;
}

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

async getAllBalances(): Promise<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;
}

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

async refreshBalances(): Promise<void>

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

interface TokenMetadata {
  address: Hex;
  symbol: string;
  decimals: number;
  name: string;
  priceUSD?: number;
  /** Minimum shield amount enforced by the protocol, in token wei (string). */
  minShieldAmount?: string;
}

async getTokens(): Promise<TokenMetadata[]>

import { parseAmount } from '@sunnyside-io/privacy-boost';

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

import { formatAmount } from '@sunnyside-io/privacy-boost';

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

import { buildShieldPayload } from '@sunnyside-io/privacy-boost';

async function buildShieldPayload(params: BuildShieldPayloadParams): Promise<PreparedShield>

interface BuildShieldPayloadParams {
  tokenAddress: Hex;
  amount: bigint;
  /** Recipient privacy address (required). */
  recipient: PrivacyAddress;
  /** Resolved on-chain token id (from the token catalog). */
  tokenId: number;
  shieldContractAddress: Hex;
  /** Required only when shielding native ETH. */
  wethContractAddress?: Hex;
  teePublicKey: string;
  /** Per-token minimum in raw units (token catalog `minShieldAmount`); rejects below it. */
  minShieldAmount?: bigint;
  /** Emit the ERC-20 approve call. Defaults to `true`. */
  emitApprove?: boolean;
}

import { finalizeShield } from '@sunnyside-io/privacy-boost';

async function finalizeShield(params: FinalizeShieldParams): Promise<ShieldResult>

interface FinalizeShieldParams {
  /** Mined transaction receipt (viem/ethers shape). */
  receipt: unknown;
  /** Shield pool contract — the DepositRequested emitter (from `PreparedShield.finalize`). */
  shieldContract: Hex;
  /** Commitment from the `PreparedShield` being settled. */
  commitment: Hex;
}

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 {
  shield = 'shield',
  unshield = 'unshield',
  transfer = 'transfer',
}

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

enum TransactionStatus {
  pending = 'pending',
  /** Submitted on-chain, not yet finalized. */
  preconfirmed = 'preconfirmed',
  completed = 'completed',
  failed = 'failed',
  /** Blocked by compliance. See `complianceStatus`. */
  blocked = 'blocked',
}

async getStartaleProgress(): Promise<StartaleCampaignProgress>

interface StartaleCampaignProgress {
  /** Whether cumulative completed shield deposits reach $10. */
  hasDepositedAtLeast10Usd: boolean;
  /** Whether the user has completed at least one private transfer. */
  hasMadeTransfer: boolean;
  /** Registry token ID the deposit mission is scoped to, if the server scopes it. */
  campaignTokenId?: number;
}

async create(opts?: CreatePortalOptions): Promise<Portal>

async list(): Promise<PortalInfo[]>

async deposits(address: string): Promise<PortalDeposit[]>

async status(address: string): Promise<PortalStatus>

async sweep(address: string, tokenId: number): Promise<string>

async reclaim(depositId: string): Promise<string>

withdraw(params: WithdrawPortalParams): string

delegateAddress(): string | undefined

function isValidPrivacyAddress(address: string): boolean

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

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

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

function extractMpkFromPrivacyAddress(address: PrivacyAddress): Hex

function isEvmAddress(address: string): boolean

function isNativeEth(address: Hex): boolean

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

type Hex = `0x${string}`

type PrivacyAddress = string // 96-byte payload, 194 chars including `0x` prefix

interface WalletAdapter {
  connect(): Promise<{ address: string; chainId: number }>;
  disconnect(): Promise<void>;
  signMessage(message: string): Promise<string>;
  /** `typedDataJson` is a JSON-stringified EIP-712 typed-data payload. */
  signTypedData(typedDataJson: string): Promise<string>;
  sendTransaction(tx: unknown): Promise<string>;
  getAddress(): Promise<string>;
  getChainId(): Promise<number>;
}

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

enum ShieldStep {
  wrapping = 'wrapping',     // Wrapping ETH to WETH
  approving = 'approving',   // Approving token spend
  shielding = 'shielding',   // Submitting the shield transaction
  compliance = 'compliance', // Awaiting compliance check
}

enum UnshieldStep {
  preparing = 'preparing',     // Fetching notes and proofs
  proving = 'proving',         // Generating the ZK proof
  unshielding = 'unshielding', // Submitting the unshield transaction
  unwrapping = 'unwrapping',   // Unwrapping WETH back to ETH (only if `unwrapWeth: true`)
}

interface FeeRates {
  /** Flat transfer fee in token wei; active when transferFeeMode is "flat". */
  transferFeeFlat: string;
  /** Unshield BPS fee; active when unshieldFeeMode is "bps". */
  unshieldFeeBps: number;
  /** Whether the user pays the fee or the application sponsors it. */
  feeModel?: 'user_pays' | 'app_pays';
  feeSchemaVersion?: number;
  requiresFeeSchemaVersion?: number;
  transferRequiresFeeSchemaVersion?: number;
  unshieldRequiresFeeSchemaVersion?: number;
  transferFeeMode?: 'flat' | 'bps';
  transferFeeBps?: number;
  unshieldFeeMode?: 'flat' | 'bps';
  unshieldFeeFlat?: string;
}

import {
  calculateFee,
  formatFeeRate,
  validateFeeRates,
  validateFeeRatesFor,
  SUPPORTED_FEE_SCHEMA_VERSION,
} from '@sunnyside-io/privacy-boost';

const rates = await sdk.vault.getFees(tokenAddress);

// Fee for an amount, under whichever mode the rates select for the operation.
const fee = calculateFee(rates, amount, 'transfer', { externalVolume });
const maxSendable = balance - calculateFee(rates, balance, 'unshield');

// Human-readable rate: "0.50%" for BPS, "1000 wei" for flat.
formatFeeRate(rates, 'unshield');

type ComplianceStatus = 'PENDING' | 'LEGIT' | 'ILLICIT';

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