@tbookdev/vault-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,894 @@
+import { Connection, PublicKey, Transaction, Commitment } from '@solana/web3.js';
+import { Program } from '@coral-xyz/anchor';
+
+/**
+ * Transaction history for vault user accounts.
+ *
+ * Fetches and classifies on-chain vault interactions (deposits, redeems,
+ * claims, cancel-deposits) by reading Solana transaction signatures and
+ * matching Anchor instruction discriminators.
+ *
+ * @module history
+ */
+
+interface VaultTransaction {
+    /** Transaction signature (base58). */
+    signature: string;
+    /** Classified instruction type. */
+    type: "deposit" | "redeem" | "claim" | "cancel_deposit" | "unknown";
+    /** Unix timestamp (seconds). 0 if unavailable. */
+    timestamp: number;
+    /** Slot number of the transaction. */
+    slot: number;
+    /** Whether the transaction succeeded. */
+    success: boolean;
+    /** Human-readable description. */
+    description: string;
+}
+interface TransactionHistoryOptions {
+    /** Maximum number of transactions to return (default: 20). */
+    limit?: number;
+    /** Pagination cursor: signature to start searching before. */
+    before?: string;
+}
+/**
+ * Fetch vault transaction history for a user.
+ *
+ * Uses `getSignaturesForAddress` on the user's UserAccount PDA to find
+ * relevant transactions, then batch-fetches parsed transaction data
+ * to classify each one by its Anchor instruction discriminator.
+ *
+ * @param connection - Solana RPC connection
+ * @param userPda - The user's UserAccount PDA address
+ * @param programId - The vault program ID (used to identify vault instructions)
+ * @param options - Pagination options
+ * @returns Array of classified vault transactions, newest first
+ */
+declare function fetchTransactionHistory(connection: Connection, userPda: PublicKey, programId: PublicKey, options?: TransactionHistoryOptions): Promise<VaultTransaction[]>;
+
+/**
+ * Core type definitions for the TBook Vault Gateway SDK.
+ *
+ * @module types
+ */
+
+/** Supported Solana networks. */
+type SolanaNetwork = "devnet" | "mainnet-beta";
+/** Options for initializing a {@link TBookVault} client instance. */
+interface TBookVaultOptions {
+    /** Solana network to connect to. */
+    network: SolanaNetwork;
+    /**
+     * Custom Solana RPC endpoint URL.
+     * Falls back to a sensible public default for the chosen network.
+     */
+    rpcUrl?: string;
+    /**
+     * TBook API key for accessing the hosted API layer.
+     * When provided, queries are routed through the cached TBook API
+     * (higher rate limits, lower latency). Without a key the SDK reads
+     * directly from the Solana RPC.
+     */
+    apiKey?: string;
+    /**
+     * Default timeout for RPC calls in milliseconds.
+     * Applies to all on-chain reads and transaction building.
+     * Default: 30_000 (30 seconds).
+     */
+    timeoutMs?: number;
+}
+/** Metadata for a single vault available in the TBook ecosystem. */
+interface VaultDescriptor {
+    /** Unique identifier for this vault, e.g. `"rcUSDP"`. */
+    id: string;
+    /** Human-readable name. */
+    name: string;
+    /** Short description of the vault strategy. */
+    description: string;
+    /** Solana program ID that manages this vault. */
+    programId: string;
+    /** Network this vault is deployed on. */
+    network: SolanaNetwork;
+    /** USDC mint address accepted by the vault. */
+    usdcMint: string;
+    /** Share token details. */
+    shareToken: {
+        symbol: string;
+        decimals: number;
+    };
+    /** Current vault status. */
+    status: "active" | "paused" | "deprecated";
+}
+/** Epoch lifecycle status. */
+type EpochStatus = "Open" | "Frozen" | "Bridging" | "Settled" | "RolledBack";
+/** Numeric → EpochStatus mapping for manual deserialization. */
+declare const STATUS_MAP: Record<number, EpochStatus>;
+/** Global vault state from VaultMirror PDA. All amounts are human-readable. */
+interface VaultInfo {
+    /** Authority (governance) public key. */
+    admin: string;
+    /** Curator multisig public key. */
+    curator: string;
+    /** Operator multisig public key. */
+    operator: string;
+    /** Total shares outstanding across all users. */
+    totalShares: number;
+    /** Current deposit epoch number. */
+    currentDepositEpoch: number;
+    /** Current redeem epoch number. */
+    currentRedeemEpoch: number;
+    /** Maximum USDC allowed per deposit epoch. */
+    maxEpochDeposit: number;
+    /** Minimum single deposit amount in USDC. */
+    minDeposit: number;
+    /** Whether the vault is paused (claim always works even when paused). */
+    paused: boolean;
+    /** USDC mint public key. */
+    usdcMint: PublicKey;
+    /** Current USDC balance held in the vault token account. */
+    vaultUsdcBalance: number;
+    /** Estimated TVL in USDC. */
+    tvlEstimate: number;
+    /** Cancellation fee in basis points (default 10 = 0.1%). */
+    cancelFeeBps: number;
+}
+/** Current deposit epoch on-chain state. */
+interface DepositEpochInfo {
+    epoch: number;
+    status: EpochStatus;
+    /** Total USDC deposited in this epoch. */
+    totalDepositUsdc: number;
+    /** Number of unique users who deposited in this epoch. */
+    depositUserCount: number;
+    /** Shares minted for this epoch after settlement. */
+    settledSharesMinted: number;
+}
+/** Current redeem epoch on-chain state. */
+interface RedeemEpochInfo {
+    epoch: number;
+    status: EpochStatus;
+    /** Total shares queued for redemption. */
+    totalRedeemShares: number;
+    /** Number of unique users who requested redemption. */
+    redeemUserCount: number;
+    /** USDC distributed for this epoch after settlement. */
+    settledUsdcForRedeems: number;
+}
+/**
+ * Per-user on-chain account state.
+ * All amounts are human-readable (divided by 10^decimals).
+ */
+interface UserAccount {
+    /** Settled share balance. */
+    shares: number;
+    /** USDC pending in an open deposit epoch. */
+    pendingDepositUsdc: number;
+    /** Which deposit epoch the pending deposit belongs to. */
+    pendingDepositEpoch: number;
+    /** Shares pending in an open redeem epoch. */
+    pendingRedeemShares: number;
+    /** Which redeem epoch the pending redeem belongs to. */
+    pendingRedeemEpoch: number;
+    /** USDC available to claim. */
+    claimableUsdc: number;
+    /**
+     * Effective share balance including not-yet-lazy-settled deposits.
+     * This is what the user "really" owns.
+     */
+    effectiveShares: number;
+    /**
+     * Effective claimable USDC including not-yet-lazy-settled redeems.
+     */
+    effectiveClaimableUsdc: number;
+    /**
+     * Estimated portfolio value in USDC (effectiveShares * sharePrice).
+     * Only present when share price is available.
+     */
+    portfolioValueUsdc?: number;
+}
+/** Share price data from the NAV oracle. */
+interface SharePriceData {
+    /** Human-readable price string, e.g. "1.000214". */
+    price: string;
+    /** Price as a number for calculations. */
+    priceNum: number;
+    /** Annualized yield percentage, e.g. "8.30". */
+    apy: string;
+    /** Date of the NAV snapshot (ISO date string). */
+    date: string;
+    /** ISO timestamp when the data was last fetched. */
+    fetchedAt: string;
+    /** Where this price data came from. */
+    source?: "api" | "cache" | "on-chain";
+    /** Whether the data is stale (older than the freshness window). */
+    stale?: boolean;
+}
+/**
+ * Result of a transaction-building operation.
+ * Contains both the raw Transaction object and a pre-serialized base58
+ * string for direct use with Wallet-as-a-Service APIs.
+ */
+interface TransactionResult {
+    /** Unsigned Solana Transaction object. */
+    transaction: Transaction;
+    /**
+     * Base58-encoded serialized transaction.
+     * Can be sent directly to WaaS providers (Crossmint, Privy, etc.)
+     * or deserialized back into a Transaction for wallet adapters.
+     */
+    serialized: string;
+    /** Human-readable description of the transaction. */
+    message: string;
+    /** Blockhash used in the transaction (needed for confirmation). */
+    blockhash: string;
+    /** Last valid block height for the blockhash (needed for expiry detection). */
+    lastValidBlockHeight: number;
+}
+/** Parameters for building a deposit transaction. */
+interface DepositParams {
+    /** User's Solana public key. */
+    user: PublicKey;
+    /** Amount of USDC to deposit (human-readable, e.g. 100 for $100). */
+    amountUsdc: number;
+}
+/** Parameters for building a redeem transaction. */
+interface RedeemParams {
+    /** User's Solana public key. */
+    user: PublicKey;
+    /** Number of vault shares to redeem (human-readable). */
+    shares: number;
+}
+/** Parameters for building a claim or cancel transaction. */
+interface UserTxParams {
+    /** User's Solana public key. */
+    user: PublicKey;
+}
+/** Full vault information including current epochs. */
+interface VaultInfoResult {
+    vault: VaultInfo | null;
+    depositEpoch: DepositEpochInfo | null;
+    redeemEpoch: RedeemEpochInfo | null;
+}
+
+/**
+ * Main SDK client for TBook Vault Gateway.
+ *
+ * ```typescript
+ * import { TBookVault } from "@tbookdev/vault-sdk";
+ *
+ * const vault = new TBookVault({ network: "mainnet-beta" });
+ *
+ * // Read vault state (no wallet needed)
+ * const info = await vault.getVaultInfo();
+ * const price = await vault.getSharePrice();
+ *
+ * // Build unsigned transactions
+ * const { transaction, serialized } = await vault.buildDeposit({
+ *   user: userPublicKey,
+ *   amountUsdc: 100,
+ * });
+ * // Send `serialized` to WaaS or `transaction` to wallet adapter
+ * ```
+ *
+ * @module client
+ */
+
+/**
+ * TBook Vault SDK client.
+ *
+ * Provides a unified interface for reading on-chain state and building
+ * unsigned transactions. Framework-agnostic — works in browsers and Node.js.
+ *
+ * The client is lightweight and stateless. Each method makes independent
+ * RPC calls, so instances can be shared across components safely.
+ */
+declare class TBookVault {
+    /** Solana RPC connection. */
+    readonly connection: Connection;
+    /** Active network. */
+    readonly network: TBookVaultOptions["network"];
+    /** Default timeout for RPC calls in milliseconds. */
+    readonly timeoutMs: number;
+    private readonly apiKey?;
+    /** Cache of Anchor programs, keyed by vault ID. */
+    private readonly programs;
+    /** Timestamps of when each cached program was created. */
+    private readonly programCreatedAt;
+    /** Maximum age for cached programs (5 minutes). */
+    private static readonly PROGRAM_CACHE_TTL_MS;
+    constructor(options: TBookVaultOptions);
+    /**
+     * List all available vaults on the current network.
+     *
+     * Currently returns built-in vaults only. In the future, this will
+     * also query the TBook API for dynamically registered vaults.
+     */
+    listVaults(): Promise<VaultDescriptor[]>;
+    /**
+     * Fetch global vault state and current epoch info.
+     *
+     * @param vaultId - Vault identifier (default: "rcUSDP")
+     */
+    getVaultInfo(vaultId?: string): Promise<VaultInfoResult>;
+    /**
+     * Fetch a user's vault account with effective balances.
+     *
+     * Returns `null` if the user has never interacted with the vault.
+     *
+     * @param user - User's Solana public key (string or PublicKey)
+     * @param vaultId - Vault identifier (default: "rcUSDP")
+     */
+    getUserAccount(user: string | PublicKey, vaultId?: string): Promise<UserAccount | null>;
+    /**
+     * Fetch current share price from the NAV oracle.
+     *
+     * Uses a 3-layer fallback: fresh cache -> API fetch -> stale cache.
+     * The API endpoint (NAV oracle) is the authoritative price source.
+     *
+     * @param vaultId - Vault identifier. Currently all registered vaults share
+     *   one NAV source; per-vault price URLs land with the multi-asset registry
+     *   (VaultConfig.sharePriceUrl) in 0.2.0.
+     */
+    getSharePrice(vaultId?: string): Promise<SharePriceData>;
+    /**
+     * Build an unsigned deposit transaction.
+     *
+     * @param params - Deposit parameters (user + amount)
+     * @param vaultId - Vault identifier (default: "rcUSDP")
+     * @returns Unsigned transaction + base58 serialization + description
+     */
+    buildDeposit(params: DepositParams, vaultId?: string): Promise<TransactionResult>;
+    /**
+     * Build an unsigned redeem transaction.
+     *
+     * @param params - Redeem parameters (user + shares)
+     * @param vaultId - Vault identifier (default: "rcUSDP")
+     */
+    buildRedeem(params: RedeemParams, vaultId?: string): Promise<TransactionResult>;
+    /**
+     * Build an unsigned claim transaction.
+     * Claim always works even when the vault is paused.
+     *
+     * @param params - User parameters
+     * @param vaultId - Vault identifier (default: "rcUSDP")
+     */
+    buildClaim(params: UserTxParams, vaultId?: string): Promise<TransactionResult>;
+    /**
+     * Build an unsigned cancel-deposit transaction.
+     * Returns pending USDC minus 0.1% fee.
+     *
+     * @param params - User parameters
+     * @param vaultId - Vault identifier (default: "rcUSDP")
+     */
+    buildCancelDeposit(params: UserTxParams, vaultId?: string): Promise<TransactionResult>;
+    /**
+     * Fetch vault transaction history for a user.
+     *
+     * Returns classified transactions (deposit, redeem, claim, cancel_deposit)
+     * by querying the user's PDA account for signatures and parsing instruction data.
+     *
+     * @param userAddress - User's Solana wallet address (string or PublicKey)
+     * @param options - Pagination options (limit, before cursor)
+     * @param vaultId - Vault identifier (default: "rcUSDP")
+     * @returns Array of classified vault transactions, newest first
+     */
+    getTransactionHistory(userAddress: string | PublicKey, options?: TransactionHistoryOptions, vaultId?: string): Promise<VaultTransaction[]>;
+    /**
+     * Estimate the number of shares that a USDC deposit would yield
+     * at the current share price.
+     *
+     * @param amountUsdc - USDC amount (human-readable)
+     * @returns Estimated shares as a string, or null if price unavailable
+     */
+    estimateShares(amountUsdc: number): Promise<string | null>;
+    /**
+     * Estimate the USDC value of a given number of shares
+     * at the current share price.
+     *
+     * @param shares - Number of shares (human-readable)
+     * @returns Estimated USDC value as a string, or null if price unavailable
+     */
+    estimateUsdc(shares: number): Promise<string | null>;
+    /**
+     * Resolve a vault config by ID, falling back to the default vault.
+     * @throws {UnknownVaultError} If the vault ID is not registered
+     */
+    private resolveVault;
+    /**
+     * Get or create a cached Anchor Program instance for a vault.
+     *
+     * Uses a read-only provider (no signer) since the SDK only builds
+     * transactions — it never signs or submits them.
+     */
+    private getProgram;
+    /**
+     * Resolve the Anchor IDL for a given vault configuration.
+     * Currently only the built-in rcUSDP devnet IDL is supported.
+     */
+    private resolveIdl;
+}
+
+/**
+ * Network-specific configuration and vault registry.
+ *
+ * The SDK ships with built-in configuration for the rcUSDP vault on both
+ * devnet and mainnet. Future vaults will be dynamically loaded via the
+ * TBook API.
+ *
+ * @module config
+ */
+
+/** USDC uses 6 decimal places on Solana. */
+declare const USDC_DECIMALS = 6;
+/** Vault shares use 6 decimal places (matching Sui vault share token). */
+declare const SHARE_DECIMALS = 6;
+/** 1 USDC in raw units (10^6). */
+declare const ONE_USDC = 1000000;
+/** 1 share in raw units (10^6). */
+declare const ONE_SHARE = 1000000;
+/** Default cancellation fee in basis points (0.1%). */
+declare const DEFAULT_CANCEL_FEE_BPS = 10;
+/**
+ * Return a default public RPC URL for the given network.
+ * In production, consumers should supply their own dedicated RPC
+ * (e.g. Helius, Triton) for reliability and rate-limit headroom.
+ */
+declare function getDefaultRpcUrl(network: SolanaNetwork): string;
+/** Build a Solana Explorer URL for an address or transaction. */
+declare function explorerUrl(type: "address" | "tx", value: string, network: SolanaNetwork): string;
+/**
+ * Per-vault on-chain configuration.
+ * Contains the program ID and known account addresses needed to
+ * interact with a specific vault deployment.
+ */
+interface VaultConfig {
+    /** Vault identifier. */
+    id: string;
+    /** Anchor program ID. */
+    programId: PublicKey;
+    /** USDC mint used by this vault. */
+    usdcMint: PublicKey;
+    /** Network this config applies to. */
+    network: SolanaNetwork;
+}
+/**
+ * Resolve a vault config by id and network.
+ * Returns `undefined` if the vault is not registered.
+ */
+declare function getVaultConfig(vaultId: string, network: SolanaNetwork): VaultConfig | undefined;
+/**
+ * List all built-in vault descriptors for a given network.
+ */
+declare function listBuiltInVaults(network: SolanaNetwork): VaultDescriptor[];
+/** Default vault ID used when no vaultId is specified. */
+declare const DEFAULT_VAULT_ID = "rcUSDP";
+
+/**
+ * PDA (Program Derived Address) derivation for Vault Gateway accounts.
+ *
+ * Each vault has a set of deterministic PDAs derived from the program ID:
+ * - VaultMirror: global singleton
+ * - UserAccount: per-user state
+ * - DepositEpoch / RedeemEpoch: per-epoch batch tracking
+ * - UsdcVault: SPL token account for vault USDC
+ *
+ * All functions are pure and synchronous — no RPC calls needed.
+ *
+ * @module pda
+ */
+
+/**
+ * Derive the VaultMirror PDA (global vault state).
+ * Seeds: `["vault_mirror"]`
+ */
+declare function getVaultMirrorPda(programId: PublicKey): [PublicKey, number];
+/**
+ * Derive the USDC vault token account PDA.
+ * Seeds: `["usdc_vault", vaultMirror]`
+ */
+declare function getUsdcVaultPda(vaultMirror: PublicKey, programId: PublicKey): [PublicKey, number];
+/**
+ * Derive a user's account PDA.
+ * Seeds: `["user", vaultMirror, userPubkey]`
+ */
+declare function getUserPda(vaultMirror: PublicKey, user: PublicKey, programId: PublicKey): [PublicKey, number];
+/**
+ * Derive a deposit epoch PDA.
+ * Seeds: `["deposit_epoch", vaultMirror, epochNumber (u64 LE)]`
+ */
+declare function getDepositEpochPda(vaultMirror: PublicKey, epoch: number, programId: PublicKey): [PublicKey, number];
+/**
+ * Derive a redeem epoch PDA.
+ * Seeds: `["redeem_epoch", vaultMirror, epochNumber (u64 LE)]`
+ */
+declare function getRedeemEpochPda(vaultMirror: PublicKey, epoch: number, programId: PublicKey): [PublicKey, number];
+
+/**
+ * On-chain state query functions.
+ *
+ * Reads VaultMirror, UserAccount, and Epoch PDAs from Solana.
+ * Supports both Anchor-based and raw byte deserialization for
+ * maximum compatibility (the latter works without a wallet).
+ *
+ * @module queries
+ */
+
+/**
+ * Fetch global vault state and current epoch info.
+ *
+ * Tries Anchor deserialization first (requires a Program instance),
+ * then falls back to manual byte parsing (works with just a Connection).
+ *
+ * @param connection - Solana RPC connection
+ * @param programId - Vault Gateway program ID
+ * @param program - Optional Anchor program (enables richer deserialization)
+ */
+declare function fetchVaultInfo(connection: Connection, programId: PublicKey, program?: Program): Promise<VaultInfoResult>;
+/**
+ * Fetch a user's vault account with effective balances.
+ *
+ * Effective balances account for settled epochs that haven't been
+ * lazy-settled yet — the user's "real" balance even before their
+ * next on-chain interaction.
+ *
+ * @param connection - Solana RPC connection
+ * @param programId - Vault Gateway program ID
+ * @param user - User's public key
+ * @param program - Optional Anchor program
+ * @returns User account state, or null if user has never interacted
+ */
+declare function fetchUserAccount(connection: Connection, programId: PublicKey, user: PublicKey, program?: Program): Promise<UserAccount | null>;
+
+/**
+ * Share price fetching with 3-layer fallback:
+ *
+ * 1. Fresh cache  — return immediately if within freshness window
+ * 2. API fetch    — NAV oracle endpoint, with timeout + circuit breaker
+ * 3. Stale cache  — return expired cache with `stale: true` flag
+ * 4. All fail     — throw SharePriceUnavailableError
+ *
+ * NOTE: On-chain calculation (vaultUsdcBalance / totalShares) was removed
+ * because it only reflects Solana-side USDC, not bridged assets on Sui.
+ * This would produce dangerously low prices (e.g., $0.02 when real price
+ * is ~$1.00). The API endpoint is the only reliable price source.
+ *
+ * @module share-price
+ */
+
+/**
+ * Options for {@link fetchSharePrice}.
+ */
+interface FetchSharePriceOptions {
+    /** Override the default API endpoint. */
+    apiUrl?: string;
+}
+/**
+ * Fetch the current share price using a 3-layer fallback strategy.
+ *
+ * @param options - Optional overrides for API URL
+ * @returns Share price data with `source` indicating where it came from
+ * @throws {SharePriceUnavailableError} If all layers fail
+ */
+declare function fetchSharePrice(options?: FetchSharePriceOptions | string): Promise<SharePriceData>;
+
+/**
+ * Transaction builders for vault operations.
+ *
+ * All builders return an **unsigned** {@link TransactionResult} containing:
+ * - `transaction`: a Solana `Transaction` object for wallet adapters
+ * - `serialized`: a base58 string for WaaS provider APIs
+ * - `message`: human-readable description
+ *
+ * The SDK never signs or submits transactions. Signing is the
+ * responsibility of the integrating app (via wallet adapter, WaaS, etc.).
+ *
+ * @module transactions
+ */
+
+/**
+ * Build an unsigned deposit transaction.
+ *
+ * Validates vault state (not paused, epoch open, min/max amounts)
+ * before building. Lazy settlement remaining_accounts are computed
+ * automatically.
+ *
+ * @param program - Initialized Anchor program (readonly, no signer needed)
+ * @param params - Deposit parameters (user pubkey + USDC amount)
+ * @returns Unsigned transaction ready for signing
+ *
+ * @throws {VaultPausedError} If the vault is paused
+ * @throws {MinDepositError} If amount is below minimum
+ * @throws {MaxEpochDepositError} If amount exceeds epoch limit
+ * @throws {EpochNotOpenError} If deposit epoch is not open
+ * @throws {RpcError} If an RPC call fails
+ */
+declare function buildDepositTx(program: Program, params: DepositParams, options?: {
+    timeoutMs?: number;
+}): Promise<TransactionResult>;
+/**
+ * Build an unsigned request-redeem transaction.
+ *
+ * Locks the specified shares for redemption in the current epoch.
+ * The actual USDC payout happens after the curator settles the epoch.
+ *
+ * @param program - Initialized Anchor program
+ * @param params - Redeem parameters (user pubkey + share amount)
+ * @returns Unsigned transaction ready for signing
+ *
+ * @throws {VaultPausedError} If the vault is paused
+ * @throws {RpcError} If an RPC call fails
+ */
+declare function buildRedeemTx(program: Program, params: RedeemParams, options?: {
+    timeoutMs?: number;
+}): Promise<TransactionResult>;
+/**
+ * Build an unsigned claim transaction.
+ *
+ * Withdraws any claimable USDC to the user's wallet.
+ * Claim always works even when the vault is paused.
+ *
+ * @param program - Initialized Anchor program
+ * @param params - User parameters (user pubkey)
+ * @returns Unsigned transaction ready for signing
+ */
+declare function buildClaimTx(program: Program, params: UserTxParams, options?: {
+    timeoutMs?: number;
+}): Promise<TransactionResult>;
+/**
+ * Build an unsigned cancel-deposit transaction.
+ *
+ * Cancels a pending deposit and returns USDC minus a 0.1% fee.
+ *
+ * @param program - Initialized Anchor program
+ * @param params - User parameters (user pubkey)
+ * @returns Unsigned transaction ready for signing
+ */
+declare function buildCancelDepositTx(program: Program, params: UserTxParams, options?: {
+    timeoutMs?: number;
+}): Promise<TransactionResult>;
+
+/**
+ * RPC utilities: timeout wrapper and transaction confirmation with retry.
+ *
+ * These utilities work in both browser and Node.js environments
+ * (no external dependencies, uses standard AbortController).
+ *
+ * @module rpc-utils
+ */
+
+/**
+ * Wait for the given number of milliseconds.
+ */
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Race a promise against a timeout. If the promise doesn't resolve
+ * within `ms` milliseconds, throws {@link RpcTimeoutError}.
+ *
+ * Uses `AbortController` which is available in browsers and Node 16+.
+ *
+ * @param promise - The async operation to wrap
+ * @param ms - Timeout in milliseconds
+ * @param label - Human-readable label for error messages (e.g., "getLatestBlockhash")
+ * @returns The resolved value of the promise
+ * @throws {RpcTimeoutError} If the timeout fires before the promise resolves
+ */
+declare function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T>;
+/** Options for {@link confirmTransactionWithRetry}. */
+interface ConfirmTxOptions {
+    /** Solana RPC connection. */
+    connection: Connection;
+    /** Transaction signature (base58). */
+    signature: string;
+    /** Blockhash used when the transaction was built. */
+    blockhash: string;
+    /** Last valid block height for the blockhash. */
+    lastValidBlockHeight: number;
+    /** Desired commitment level. Default: "confirmed". */
+    commitment?: Commitment;
+    /** Maximum total wait time in milliseconds. Default: 60_000. */
+    timeoutMs?: number;
+    /** Initial polling interval in milliseconds. Default: 2_000 (scales up with 1.5x backoff, max 5s). */
+    initialIntervalMs?: number;
+}
+/**
+ * Confirm a transaction with exponential-backoff polling.
+ *
+ * Unlike `connection.confirmTransaction()` which can silently hang,
+ * this implementation:
+ * - Polls `getSignatureStatuses` with configurable backoff
+ * - Checks `getBlockHeight` to detect expired blockhashes
+ * - Throws typed errors for timeout, expiry, and on-chain failures
+ *
+ * @throws {TransactionExpiredError} If the blockhash expires before confirmation
+ * @throws {TransactionFailedError} If the transaction fails on-chain
+ * @throws {RpcTimeoutError} If the overall timeout is exceeded
+ */
+declare function confirmTransactionWithRetry(opts: ConfirmTxOptions): Promise<void>;
+
+/**
+ * In-memory share price cache with circuit breaker.
+ *
+ * Avoids redundant API calls and provides graceful degradation
+ * when the NAV oracle is temporarily unreachable.
+ *
+ * @module share-price-cache
+ */
+
+/**
+ * In-memory cache for share price data with a simple circuit breaker
+ * to avoid hammering a failing API endpoint.
+ */
+declare class SharePriceCache {
+    /** Maximum age (in ms) before cached data is considered stale. */
+    readonly maxStaleMs: number;
+    private data;
+    private storedAt;
+    private failureCount;
+    private readonly failureThreshold;
+    private circuitOpenedAt;
+    private readonly circuitResetMs;
+    constructor(opts?: {
+        maxStaleMs?: number;
+        failureThreshold?: number;
+        circuitResetMs?: number;
+    });
+    /**
+     * Return cached data if it is fresher than `maxAge` milliseconds.
+     * Returns `null` if the cache is empty or the data is too old.
+     *
+     * @param maxAge - Override the default freshness window (pass `Infinity` for stale-ok)
+     */
+    get(maxAge?: number): SharePriceData | null;
+    /** Store fresh share price data. */
+    set(data: SharePriceData): void;
+    /** Whether the circuit breaker is currently open (API calls should be skipped). */
+    isCircuitOpen(): boolean;
+    /** Record a failed API call. Opens the circuit after the threshold is reached. */
+    recordFailure(): void;
+    /** Record a successful API call. Resets the circuit breaker. */
+    recordSuccess(): void;
+}
+/** Shared singleton cache instance used by {@link fetchSharePrice}. */
+declare const sharePriceCache: SharePriceCache;
+
+/**
+ * Typed error classes for the TBook Vault SDK.
+ *
+ * All SDK errors extend {@link VaultSdkError} so consumers can catch
+ * SDK-specific errors in a single catch block:
+ *
+ * ```typescript
+ * try {
+ *   await vault.buildDeposit({ ... });
+ * } catch (err) {
+ *   if (err instanceof VaultSdkError) {
+ *     console.error(`SDK error [${err.code}]: ${err.message}`);
+ *   }
+ * }
+ * ```
+ *
+ * @module errors
+ */
+/** Base error class for all vault SDK errors. */
+declare class VaultSdkError extends Error {
+    /** Machine-readable error code. */
+    readonly code: string;
+    /** Non-technical message suitable for displaying to end users. */
+    readonly userFriendlyMessage: string;
+    constructor(code: string, message: string, userFriendlyMessage?: string);
+}
+/**
+ * Thrown when the vault is paused and an operation that requires
+ * an active vault is attempted (deposit, redeem).
+ * Note: `claim` always works even when paused.
+ */
+declare class VaultPausedError extends VaultSdkError {
+    constructor();
+}
+/** Thrown when the deposit amount is below the vault's minimum. */
+declare class MinDepositError extends VaultSdkError {
+    /** The minimum required deposit in USDC. */
+    readonly minDeposit: number;
+    constructor(minDeposit: number);
+}
+/** Thrown when the deposit amount would exceed the epoch's maximum. */
+declare class MaxEpochDepositError extends VaultSdkError {
+    readonly maxEpochDeposit: number;
+    constructor(maxEpochDeposit: number);
+}
+/** Thrown when the deposit epoch is not in an "Open" state. */
+declare class EpochNotOpenError extends VaultSdkError {
+    constructor(epochType: "deposit" | "redeem", status: string);
+}
+/** Thrown when the VaultMirror PDA cannot be found on-chain. */
+declare class VaultNotFoundError extends VaultSdkError {
+    constructor();
+}
+/** Thrown when a user account PDA is expected but does not exist. */
+declare class UserAccountNotFoundError extends VaultSdkError {
+    constructor(pubkey: string);
+}
+/** Thrown when an unsupported or unknown vault ID is requested. */
+declare class UnknownVaultError extends VaultSdkError {
+    constructor(vaultId: string);
+}
+/** Thrown when the share price API is unreachable or returns invalid data. */
+declare class SharePriceUnavailableError extends VaultSdkError {
+    constructor(reason?: string);
+}
+/** Thrown when a cancel-deposit is attempted but the user has no pending deposit. */
+declare class NoPendingDepositError extends VaultSdkError {
+    constructor();
+}
+/** Thrown when an RPC call fails. */
+declare class RpcError extends VaultSdkError {
+    /** The underlying error from the RPC library. */
+    readonly cause: unknown;
+    constructor(operation: string, cause: unknown);
+}
+/** Thrown when an RPC call exceeds the configured timeout. */
+declare class RpcTimeoutError extends VaultSdkError {
+    /** The timeout duration in milliseconds. */
+    readonly timeoutMs: number;
+    constructor(operation: string, timeoutMs: number);
+}
+/** Thrown when a transaction's blockhash expires before confirmation. */
+declare class TransactionExpiredError extends VaultSdkError {
+    /** The transaction signature. */
+    readonly signature: string;
+    constructor(signature: string);
+}
+/** Thrown when a transaction fails on-chain (e.g., program error). */
+declare class TransactionFailedError extends VaultSdkError {
+    /** The transaction signature. */
+    readonly signature: string;
+    /** The on-chain error object. */
+    readonly txError: unknown;
+    constructor(signature: string, txError: unknown);
+}
+
+/**
+ * Formatting, validation, and conversion utilities.
+ *
+ * @module utils
+ */
+/** Truncate a number to N decimal places without rounding. */
+declare function truncateNumber(value: number, decimals: number): number;
+/** Truncate and format a number to a fixed-decimal string. */
+declare function formatTruncated(value: number, decimals: number): string;
+/** Format a number with locale-aware thousand separators (truncated, not rounded). */
+declare function formatNumber(value: number, decimals?: number): string;
+/** Format a number as USD currency (truncated). */
+declare function formatCurrency(value: number, currency?: string): string;
+/** Format a percentage value. */
+declare function formatPercentage(value: number, decimals?: number): string;
+/** Shorten a Solana address for display: "AbCd...xYz". */
+declare function shortenAddress(address: string, chars?: number): string;
+/** Format a raw USDC amount (6 decimals) to a human-readable string. */
+declare function formatUsdc(raw: number | bigint): string;
+/** Format a raw share amount (6 decimals) to a human-readable string. */
+declare function formatShares(raw: number | bigint): string;
+/** Convert raw u64 to human-readable UI amount. */
+declare function rawToUi(raw: number | bigint, decimals: number): number;
+/** Convert human-readable UI amount to raw u64. Uses truncation (not rounding). */
+declare function uiToRaw(ui: number, decimals: number): number;
+/** Result of an input validation check. */
+interface ValidationResult {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Validate an amount for deposit or redeem operations.
+ *
+ * @param amount - The amount as a string (from user input)
+ * @param balance - User's available balance
+ * @param action - Action name for error messages (e.g. "deposit")
+ * @param token - Token name for error messages (e.g. "USDC")
+ * @param min - Minimum allowed amount
+ * @param max - Maximum allowed amount
+ */
+declare function validateAmount(amount: string, balance: number, action: string, token: string, min?: number, max?: number): ValidationResult;
+/** Check if a string is a valid numeric input (numbers and single decimal point). */
+declare function isValidAmountInput(value: string): boolean;
+
+export { type ConfirmTxOptions, DEFAULT_CANCEL_FEE_BPS, DEFAULT_VAULT_ID, type DepositEpochInfo, type DepositParams, EpochNotOpenError, type EpochStatus, MaxEpochDepositError, MinDepositError, NoPendingDepositError, ONE_SHARE, ONE_USDC, type RedeemEpochInfo, type RedeemParams, RpcError, RpcTimeoutError, SHARE_DECIMALS, STATUS_MAP, SharePriceCache, type SharePriceData, SharePriceUnavailableError, type SolanaNetwork, TBookVault, type TBookVaultOptions, TransactionExpiredError, TransactionFailedError, type TransactionHistoryOptions, type TransactionResult, USDC_DECIMALS, UnknownVaultError, type UserAccount, UserAccountNotFoundError, type UserTxParams, type ValidationResult, type VaultConfig, type VaultDescriptor, type VaultInfo, type VaultInfoResult, VaultNotFoundError, VaultPausedError, VaultSdkError, type VaultTransaction, buildCancelDepositTx, buildClaimTx, buildDepositTx, buildRedeemTx, confirmTransactionWithRetry, explorerUrl, fetchSharePrice, fetchTransactionHistory, fetchUserAccount, fetchVaultInfo, formatCurrency, formatNumber, formatPercentage, formatShares, formatTruncated, formatUsdc, getDefaultRpcUrl, getDepositEpochPda, getRedeemEpochPda, getUsdcVaultPda, getUserPda, getVaultConfig, getVaultMirrorPda, isValidAmountInput, listBuiltInVaults, rawToUi, sharePriceCache, shortenAddress, sleep, truncateNumber, uiToRaw, validateAmount, withTimeout };