# 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 }>;
}

const result = await sdk.auth.authenticateAsSafeMember(adapter, { safeAddress });

if (result.status === 'safeAccountCreationRequired') {
  await proposeToSafe(result.createAccountTransaction);
  // Retry authentication after AccountCreated is indexed.
}

const { mnemonic } = await sdk.auth.prepareSafeAccount(safeAddress);
await showAndConfirm(mnemonic);

const { createAccountTransaction, accountExists } =
  await sdk.auth.bootstrapSafeAccount(adapter, { safeAddress }, mnemonic);
if (!accountExists) {
  await proposeToSafe(createAccountTransaction);
}
// Any owner, on any device: authenticateAsSafeMember reports
// safeAccountCreationRequired with this same transaction until the Safe
// executes it, then signs in.

async logout(): Promise<void>

async clearSession(): Promise<void>

isConnected(): boolean

isAuthenticated(): boolean

getPrivacyAddress(): string | null

getMpk(): string | null

async revealRecoveryPhrase(options?: RevealMnemonicOptions): Promise<RevealMnemonicResult>

interface RevealMnemonicOptions {
  strings?: Partial<RecoveryPhraseStrings>;
}

interface RevealMnemonicResult {
  status: 'shown' | 'absent';
  revealed: boolean;
}

const { status, revealed } = await sdk.auth.revealRecoveryPhrase();
if (status === 'absent') {
  // Nothing to show, and nothing a retry can do about it.
}

await sdk.auth.revealRecoveryPhrase({
  strings: { title: '복구 문구', reveal: '탭하여 보기', done: '완료' },
});

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 sendBatch(params: SendBatchParams): Promise<TransactionResult>

interface SendBatchParams {
  /** Recipients in output order. At least one; duplicates allowed. */
  recipients: SendBatchRecipient[];
  tokenAddress: Hex;
  signal?: AbortSignal;
}

interface SendBatchRecipient {
  recipient: PrivacyAddress;
  amount: bigint;
}

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 listShieldsByStatus(statuses?: ShieldRequestStatus[]): Promise<UnsettledShield[]>

type ShieldRequestStatus =
  | 'pending' | 'processing' | 'preconfirmed' | 'completed' | 'failed';

interface UnsettledShield {
  /** The on-chain deposit request id, decimal. */
  requestId: string;
  status: ShieldRequestStatus;
  /** The `requestDeposit` transaction, once the server has observed it. */
  txHash?: string;
  /** Block the `DepositRequested` event was emitted in. */
  blockNumber?: number;
  createdAt?: string;
  updatedAt?: string;
  /** Why the shield failed, when the server recorded a reason. */
  error?: string;
}

const stuck = await sdk.vault.listShieldsByStatus(['failed']);
for (const shield of stuck) {
  const status = await sdk.vault.getDepositCancellation(shield.requestId);
  if (status.cancellable) await sdk.vault.cancelDeposit(shield.requestId);
  else console.log(shield.requestId, status.reason);
}

async depositRequestIdsFromTransaction(txHash: string): Promise<string[]>

async getDepositCancellation(depositRequestId: string): Promise<DepositCancellation>

type DepositCancelState =
  | 'Cancellable'
  | 'NotFound'
  | 'NotDepositor'
  | 'AlreadyProcessed'
  | 'TooEarly'
  | 'GatewayOrigin';

interface DepositCancellation {
  /** The queried id, normalized to decimal. */
  depositRequestId: string;
  state: DepositCancelState;
  /** True exactly when `state` is `'Cancellable'`. */
  cancellable: boolean;
  /** Address that must sign the cancellation. Absent when no escrow exists. */
  depositor?: string;
  /** The address the status was evaluated against. */
  caller: string;
  tokenId: number;
  /** Escrow that would be refunded, decimal. `"0"` when no escrow exists. */
  totalAmount: string;
  requestBlock: number;
  /** The pool's `cancelDelay()`, in blocks. */
  cancelDelay: number;
  /** First block cancellation is allowed (`requestBlock + cancelDelay`). */
  cancellableAtBlock: number;
  /** Chain head the status was evaluated at. */
  currentBlock: number;
  /** Blocks left before `'TooEarly'` clears; `0` once the delay has elapsed. */
  blocksRemaining: number;
  /** Human-readable explanation of `state`, safe to surface directly. */
  reason: string;
}

async cancelDeposit(depositRequestId: string): Promise<string>

const status = await sdk.vault.getDepositCancellation(result.requestId);
if (status.cancellable) {
  await sdk.vault.cancelDeposit(status.depositRequestId);
} else {
  console.log(status.reason);
}

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[]>

async getRegisteredTokens(): Promise<RegisteredToken[]>

interface RegisteredToken {
  id: number;
  tokenType: number;
  tokenAddress: Hex;
  tokenSubId: string;
  symbol?: string;
  name?: string;
  priceUSD?: number;
  decimals?: number;
  minShieldAmount?: string;
  capabilities?: TokenCapability[];
}

interface TokenCapability {
  adapter: string;
  direction?: string;
  vault?: string;
  shareTokenId?: number;
  underlyingTokenId?: number;
  outputTokenPolicy?: 'any-registered-token' | 'allowlist';
  outputTokenIds?: number[];
}

async earnDeposit(params: EarnParams): Promise<EarnResult>

interface EarnParams {
  /** ERC-4626 vault address (also the share token address). */
  vaultAddress: Hex;
  /** Net amount entering the vault call: assets to deposit, shares to redeem. */
  amount: bigint;
  /** Max slippage below the on-chain preview, in bps (default 100 = 1%). */
  maxSlippageBps?: number;
  onProgress?: OnProgress;
}

interface EarnResult {
  /** Server-side request ID; use with the unshield status endpoint. */
  requestId: string;
  /** Local placeholder hash used to track pending status. */
  txHash: Hex;
  /** "deposit" | "redeem". */
  action: string;
  vaultAddress: string;
  inputTokenId: number;
  outputTokenId: number;
  /** Net amount that enters the vault call. */
  amount: bigint;
  /** Gateway fee charged on the exit amount, in raw units. */
  fee: bigint;
  /** Client-side preview of the vault output. */
  expectedOutputAmount: bigint;
  /** Signed floor; a fill below this refunds the input via the fallback receipt. */
  minOutputAmount: bigint;
  expiryBlock: bigint;
}

async earnRedeem(params: EarnParams): Promise<EarnResult>

async listEarnVaults(): Promise<EarnVaultsResponse>

async getEarnVault(vaultAddress: string): Promise<EarnVaultDetail>

async getGatewayConfig(): Promise<GatewayConfig>

async getEarnVaultHistory(
  vaultAddress: string,
  metric: EarnHistoryMetric,
  period?: EarnHistoryPeriod,
): Promise<EarnVaultHistory>

type EarnHistoryMetric = 'tvlUsd' | 'netApy';
/** Server default is '1w'. */
type EarnHistoryPeriod = '1w' | '1m' | '3m' | 'all';

interface EarnVaultHistoryPoint {
  /** Unix seconds. */
  timestamp: number;
  /** null marks an upstream gap the chart should not interpolate across. */
  value: number | null;
}

interface EarnVaultHistoryMetadata {
  /** Open set — treat unknown values as data of unknown freshness, not errors. */
  state: 'fresh' | 'stale' | 'synthetic' | 'unsupported' | (string & {});
  /** RFC 3339 timestamp of the underlying upstream fetch. */
  updatedAt?: string;
}

interface EarnVaultHistory {
  chainId: number;
  vaultAddress: string;
  protocol: string;
  protocolVersion: string;
  metric: EarnHistoryMetric | (string & {});
  period: EarnHistoryPeriod | (string & {});
  /** Point spacing ('hour' | 'day'; open set). */
  interval: string;
  /** 'usd' for tvlUsd, 'ratio' for netApy (open set). */
  unit: string;
  lookbackHours?: number | null;
  periodAverage?: number | null;
  points: EarnVaultHistoryPoint[];
  metadata: EarnVaultHistoryMetadata;
}

async getEarnVaultCharts(
  vaultAddress: string,
  period?: EarnHistoryPeriod,
): Promise<EarnVaultCharts>

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

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 listPage(options?: PortalPageOptions): Promise<PortalInfoPage>

async depositsPage(
  address: string,
  options?: PortalPageOptions,
): Promise<PortalDepositPage>

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

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

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

async withdraw(params: WithdrawPortalParams): Promise<string>

async delegateAddress(): Promise<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`)
}

type GatewayAddress = `0x${string}`;
type GatewaySelector = `0x${string}`; // Runtime validation requires exactly 4 bytes.

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;
  gatewayAddress?: GatewayAddress;
  gatewaySelector?: GatewaySelector;
  gatewayFeeMode?: 'flat' | 'bps';
  gatewayFeeFlat?: string;
  gatewayFeeRate?: number;
  gatewayFeeRateDenominator?: number;
  gatewayFeeBase?: 'flat' | 'unshield_amount' | 'zero';
  gatewayRequiresFeeSchemaVersion?: number;
}

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

const rates = await sdk.vault.getFees(tokenAddress);
const gatewayRates = await sdk.vault.getGatewayFees(
  tokenAddress,
  gatewayAddress,
  gatewaySelector,
);

// 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');
calculateGatewayFee(gatewayRates, amount, gatewayAddress, gatewaySelector);
formatGatewayFeeRate(gatewayRates, gatewayAddress, gatewaySelector);

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;