@veil-cash/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,2099 @@
+import MerkleTree from 'fixed-merkle-tree-legacy';
+
+/**
+ * UTXO (Unspent Transaction Output) class for Veil SDK
+ * Represents a private balance entry that can be spent
+ */
+
+interface UtxoParams {
+    amount?: bigint | number | string;
+    keypair?: Keypair;
+    blinding?: bigint;
+    index?: number;
+}
+/**
+ * UTXO class - represents a private balance entry
+ *
+ * A UTXO contains:
+ * - amount: The value in wei
+ * - blinding: Random value for privacy
+ * - keypair: The owner's keypair
+ * - index: Position in the merkle tree (needed for nullifier calculation)
+ *
+ * @example
+ * ```typescript
+ * // Decrypt an encrypted output
+ * const utxo = Utxo.decrypt(encryptedOutput, keypair);
+ * utxo.index = 5; // Set the merkle tree index
+ *
+ * // Check if spent
+ * const nullifier = utxo.getNullifier();
+ * const isSpent = await pool.isSpent(nullifier);
+ * ```
+ */
+declare class Utxo {
+    amount: bigint;
+    blinding: bigint;
+    keypair: Keypair;
+    index?: number;
+    private _commitment?;
+    private _nullifier?;
+    /**
+     * Create a new UTXO
+     * @param params - UTXO parameters
+     */
+    constructor(params?: UtxoParams);
+    /**
+     * Get the commitment for this UTXO
+     * commitment = poseidonHash([amount, pubkey, blinding])
+     * @returns Commitment as bigint
+     */
+    getCommitment(): bigint;
+    /**
+     * Get the nullifier for this UTXO
+     * Requires index and private key to be set
+     * nullifier = poseidonHash([commitment, index, signature])
+     * @returns Nullifier as bigint
+     */
+    getNullifier(): bigint;
+    /**
+     * Encrypt UTXO data using the keypair
+     * @returns Encrypted data as 0x-prefixed hex string
+     */
+    encrypt(): string;
+    /**
+     * Decrypt an encrypted output to create a UTXO
+     * Only succeeds if the keypair owns this UTXO
+     *
+     * @param data - Encrypted output as hex string
+     * @param keypair - Keypair to decrypt with
+     * @returns Decrypted UTXO
+     * @throws If decryption fails (wrong keypair)
+     */
+    static decrypt(data: string, keypair: Keypair): Utxo;
+}
+
+/**
+ * Type definitions for Veil SDK
+ */
+/**
+ * Supported tokens
+ */
+type Token = 'ETH' | 'USDC';
+/**
+ * Encrypted message format (x25519-xsalsa20-poly1305)
+ */
+interface EncryptedMessage {
+    version: string;
+    nonce: string;
+    ephemPublicKey: string;
+    ciphertext: string;
+}
+/**
+ * Contract addresses for a network
+ */
+interface NetworkAddresses {
+    entry: `0x${string}`;
+    ethPool: `0x${string}`;
+    ethQueue: `0x${string}`;
+    usdcPool: `0x${string}`;
+    usdcQueue: `0x${string}`;
+    usdcToken: `0x${string}`;
+    chainId: number;
+    relayUrl: string;
+}
+/**
+ * Options for building a register transaction
+ */
+interface RegisterTxOptions {
+    depositKey: string;
+}
+/**
+ * Options for building a deposit transaction
+ */
+interface DepositTxOptions {
+    depositKey: string;
+    fallbackReceiver: `0x${string}`;
+    amount: string;
+    token?: Token;
+}
+/**
+ * Transaction data returned by build functions
+ */
+interface TransactionData {
+    to: `0x${string}`;
+    data: `0x${string}`;
+    value?: bigint;
+}
+/**
+ * Pool configuration
+ */
+interface PoolConfig {
+    decimals: number;
+    displayDecimals: number;
+    symbol: string;
+    name: string;
+}
+/**
+ * Pending deposit from queue contract
+ */
+interface PendingDeposit {
+    nonce: string;
+    status: 'pending' | 'accepted' | 'rejected' | 'refunded';
+    amount: string;
+    amountWei: string;
+    timestamp: string;
+}
+/**
+ * Result from getQueueBalance
+ */
+interface QueueBalanceResult {
+    address: string;
+    queueBalance: string;
+    queueBalanceWei: string;
+    pendingDeposits: PendingDeposit[];
+    pendingCount: number;
+}
+/**
+ * UTXO info for private balance
+ */
+interface UtxoInfo {
+    index: number;
+    amount: string;
+    amountWei: string;
+    isSpent: boolean;
+}
+/**
+ * Result from getPrivateBalance
+ */
+interface PrivateBalanceResult {
+    privateBalance: string;
+    privateBalanceWei: string;
+    utxoCount: number;
+    spentCount: number;
+    unspentCount: number;
+    utxos: UtxoInfo[];
+}
+/**
+ * Pool type for relay operations
+ */
+type RelayPool = 'eth' | 'usdc';
+/**
+ * Type of relay transaction
+ */
+type RelayType = 'withdraw' | 'transfer';
+/**
+ * Proof arguments for relay transaction
+ */
+interface RelayProofArgs {
+    proof: string;
+    root: string;
+    inputNullifiers: string[];
+    outputCommitments: [string, string];
+    publicAmount: string;
+    extDataHash: string;
+}
+/**
+ * External data for relay transaction
+ */
+interface RelayExtData {
+    recipient: string;
+    extAmount: string;
+    relayer: string;
+    fee: string;
+    encryptedOutput1: string;
+    encryptedOutput2: string;
+}
+/**
+ * Metadata for relay transaction (optional)
+ */
+interface RelayMetadata {
+    amount?: string;
+    recipient?: string;
+    inputUtxoCount?: number;
+    outputUtxoCount?: number;
+}
+/**
+ * Request body for relay service
+ */
+interface RelayRequest {
+    type: RelayType;
+    proofArgs: RelayProofArgs;
+    extData: RelayExtData;
+    metadata?: RelayMetadata;
+}
+/**
+ * Response from relay service
+ */
+interface RelayResponse {
+    success: boolean;
+    transactionHash: string;
+    blockNumber: string;
+    gasUsed: string;
+    status: string;
+    network: string;
+}
+/**
+ * Error response from relay service
+ */
+interface RelayErrorResponse {
+    error: string;
+    message?: string;
+    retryAfter?: number;
+    network?: string;
+}
+/**
+ * Options for submitRelay function
+ */
+interface SubmitRelayOptions {
+    /** Type of transaction: 'withdraw' or 'transfer' */
+    type: RelayType;
+    /** Pool to use: 'eth' or 'usdc' */
+    pool?: RelayPool;
+    /** Proof arguments generated by ZK prover */
+    proofArgs: RelayProofArgs;
+    /** External data for the transaction */
+    extData: RelayExtData;
+    /** Optional metadata */
+    metadata?: RelayMetadata;
+    /** Custom relay URL (overrides default) */
+    relayUrl?: string;
+}
+/**
+ * Options for building a withdrawal proof
+ */
+interface BuildWithdrawProofOptions {
+    /** Amount to withdraw (human readable, e.g., "0.1") */
+    amount: string;
+    /** Recipient address for withdrawal */
+    recipient: `0x${string}`;
+    /** User's keypair for signing */
+    keypair: Keypair;
+    /** Optional RPC URL */
+    rpcUrl?: string;
+    /** Progress callback */
+    onProgress?: (stage: string, detail?: string) => void;
+}
+/**
+ * Options for building a transfer proof
+ */
+interface BuildTransferProofOptions {
+    /** Amount to transfer (human readable, e.g., "0.1") */
+    amount: string;
+    /** Recipient's address (must be registered) */
+    recipientAddress: `0x${string}`;
+    /** Sender's keypair */
+    senderKeypair: Keypair;
+    /** Optional RPC URL */
+    rpcUrl?: string;
+    /** Progress callback */
+    onProgress?: (stage: string, detail?: string) => void;
+}
+/**
+ * Result from building a withdrawal or transfer proof
+ */
+interface ProofBuildResult {
+    /** Proof arguments for on-chain verification */
+    proofArgs: RelayProofArgs;
+    /** External data for transaction */
+    extData: RelayExtData;
+    /** Number of input UTXOs used */
+    inputCount: number;
+    /** Number of output UTXOs created */
+    outputCount: number;
+    /** Amount being withdrawn/transferred */
+    amount: string;
+}
+/**
+ * Result from executing a withdrawal
+ */
+interface WithdrawResult {
+    /** Whether the withdrawal was successful */
+    success: boolean;
+    /** Transaction hash */
+    transactionHash: string;
+    /** Block number of the transaction */
+    blockNumber: string;
+    /** Amount withdrawn */
+    amount: string;
+    /** Recipient address */
+    recipient: string;
+}
+/**
+ * Result from executing a transfer
+ */
+interface TransferResult {
+    /** Whether the transfer was successful */
+    success: boolean;
+    /** Transaction hash */
+    transactionHash: string;
+    /** Block number of the transaction */
+    blockNumber: string;
+    /** Amount transferred */
+    amount: string;
+    /** Recipient address */
+    recipient: string;
+}
+/**
+ * UTXO selection result
+ */
+interface UtxoSelectionResult {
+    /** Selected UTXOs */
+    selectedUtxos: Utxo[];
+    /** Total amount of selected UTXOs (wei) */
+    totalSelected: bigint;
+    /** Change amount to return to sender (wei) */
+    changeAmount: bigint;
+}
+
+/**
+ * Veil Keypair class
+ * Generates and manages keypairs for Veil deposits
+ */
+
+/**
+ * Pack encrypted message into hex string
+ */
+declare function packEncryptedMessage(encryptedMessage: EncryptedMessage): string;
+/**
+ * Unpack hex string into encrypted message
+ */
+declare function unpackEncryptedMessage(encryptedMessage: string): EncryptedMessage;
+/**
+ * Veil Keypair for deposits
+ *
+ * A keypair consists of:
+ * - Private key: Random 32-byte Ethereum-style key
+ * - Public key: Poseidon hash of the private key
+ * - Encryption key: x25519 public key for encrypted outputs
+ *
+ * The deposit key (used for registration) is: pubkey + encryptionKey
+ *
+ * @example
+ * ```typescript
+ * // Generate new keypair
+ * const keypair = new Keypair();
+ * console.log(keypair.depositKey()); // Register this on-chain
+ * console.log(keypair.privkey);      // Store securely!
+ *
+ * // Restore from existing private key
+ * const restored = new Keypair(savedPrivkey);
+ * ```
+ */
+declare class Keypair {
+    /** Private key (null if created from public deposit key only) */
+    privkey: string | null;
+    /** Public key (Poseidon hash of private key) */
+    pubkey: bigint;
+    /** x25519 encryption public key */
+    encryptionKey: string;
+    /**
+     * Create a new Keypair
+     * @param privkey - Optional private key. If not provided, generates a random one.
+     */
+    constructor(privkey?: string);
+    /**
+     * Get the deposit key for this keypair
+     * This is what you register on-chain
+     * @returns Deposit key as hex string (130 chars with 0x prefix)
+     */
+    toString(): string;
+    /**
+     * Alias for toString() - returns the deposit key
+     * @returns Deposit key as hex string
+     */
+    depositKey(): string;
+    /**
+     * Create a Keypair from a public deposit key (without private key)
+     * Useful for sending transfers to other users
+     * @param str - Deposit key (128 or 130 hex chars)
+     * @returns Keypair instance (privkey will be null)
+     */
+    static fromString(str: string): Keypair;
+    /**
+     * Sign a message using the private key
+     * @param commitment - Commitment hash
+     * @param merklePath - Merkle path
+     * @returns Signature as bigint
+     */
+    sign(commitment: string | number | bigint, merklePath: string | number | bigint): bigint;
+    /**
+     * Encrypt data using the encryption key
+     * @param bytes - Data to encrypt
+     * @returns Encrypted data as hex string
+     */
+    encrypt(bytes: Buffer): string;
+    /**
+     * Decrypt data using the private key
+     * @param data - Encrypted data as hex string
+     * @returns Decrypted data as Buffer
+     */
+    decrypt(data: string): Buffer;
+}
+
+/**
+ * Deposit functions for Veil SDK
+ * Build transactions for registration and deposits
+ */
+
+/**
+ * Build a transaction to register a deposit key
+ * This is a one-time operation that links your address to your keypair
+ *
+ * @param depositKey - Deposit key from Keypair.depositKey()
+ * @param ownerAddress - Address that will own this deposit key
+ * @returns Transaction data to send
+ *
+ * @example
+ * ```typescript
+ * const keypair = new Keypair();
+ * const tx = buildRegisterTx(keypair.depositKey(), '0x...');
+ * // Send tx using your wallet (viem, ethers, etc.)
+ * ```
+ */
+declare function buildRegisterTx(depositKey: string, ownerAddress: `0x${string}`): TransactionData;
+/**
+ * Build a transaction to deposit ETH
+ *
+ * @param options - Deposit options
+ * @param options.depositKey - Deposit key from Keypair.depositKey()
+ * @param options.amount - Amount to deposit (human readable, e.g., '0.1')
+ * @returns Transaction data including value to send
+ *
+ * @example
+ * ```typescript
+ * const tx = buildDepositETHTx({
+ *   depositKey: keypair.depositKey(),
+ *   amount: '0.1',
+ * });
+ * // Send tx with tx.value as the ETH amount
+ * ```
+ */
+declare function buildDepositETHTx(options: {
+    depositKey: string;
+    amount: string;
+}): TransactionData;
+/**
+ * Build a transaction to approve USDC for deposit
+ * Must be called before depositUSDC if allowance is insufficient
+ *
+ * @param options - Approval options
+ * @param options.amount - Amount to approve (human readable, e.g., '100')
+ * @returns Transaction data
+ */
+declare function buildApproveUSDCTx(options: {
+    amount: string;
+}): TransactionData;
+/**
+ * Build a transaction to deposit USDC
+ * Note: You must approve USDC first using buildApproveUSDCTx
+ *
+ * @param options - Deposit options
+ * @param options.depositKey - Deposit key from Keypair.depositKey()
+ * @param options.amount - Amount to deposit (human readable, e.g., '100')
+ * @returns Transaction data
+ */
+declare function buildDepositUSDCTx(options: {
+    depositKey: string;
+    amount: string;
+}): TransactionData;
+/**
+ * Build a deposit transaction (ETH or USDC)
+ * Convenience function that routes to the correct builder
+ *
+ * @param options - Deposit options
+ * @returns Transaction data
+ *
+ * @example
+ * ```typescript
+ * // ETH deposit
+ * const ethTx = buildDepositTx({
+ *   depositKey: keypair.depositKey(),
+ *   amount: '0.1',
+ *   token: 'ETH',
+ * });
+ *
+ * // USDC deposit (remember to approve first!)
+ * const usdcTx = buildDepositTx({
+ *   depositKey: keypair.depositKey(),
+ *   amount: '100',
+ *   token: 'USDC',
+ * });
+ * ```
+ */
+declare function buildDepositTx(options: {
+    depositKey: string;
+    amount: string;
+    token?: Token;
+}): TransactionData;
+
+/**
+ * Balance functions for Veil SDK
+ * Query queue and private balances directly from blockchain
+ */
+
+/**
+ * Progress callback type
+ */
+type ProgressCallback = (stage: string, detail?: string) => void;
+/**
+ * Get queue balance and pending deposits for an address
+ * Queries the Queue contract directly (no API dependency)
+ *
+ * @param options - Query options
+ * @param options.address - Address to check
+ * @param options.rpcUrl - Optional RPC URL (uses default if not provided)
+ * @param options.onProgress - Optional progress callback
+ * @returns Queue balance and pending deposits
+ *
+ * @example
+ * ```typescript
+ * const result = await getQueueBalance({
+ *   address: '0x...',
+ *   onProgress: (stage, detail) => console.log(stage, detail),
+ * });
+ *
+ * console.log(`Queue balance: ${result.queueBalance} ETH`);
+ * console.log(`Pending deposits: ${result.pendingCount}`);
+ * ```
+ */
+declare function getQueueBalance(options: {
+    address: `0x${string}`;
+    rpcUrl?: string;
+    onProgress?: ProgressCallback;
+}): Promise<QueueBalanceResult>;
+/**
+ * Get private balance from the Pool contract
+ * Decrypts all encrypted outputs, calculates nullifiers, and checks spent status
+ *
+ * @param options - Query options
+ * @param options.keypair - Keypair to decrypt UTXOs with
+ * @param options.rpcUrl - Optional RPC URL (uses default if not provided)
+ * @param options.onProgress - Optional progress callback
+ * @returns Private balance and UTXO details
+ *
+ * @example
+ * ```typescript
+ * const keypair = new Keypair(process.env.VEIL_KEY);
+ * const result = await getPrivateBalance({
+ *   keypair,
+ *   onProgress: (stage, detail) => console.log(stage, detail),
+ * });
+ *
+ * console.log(`Private balance: ${result.privateBalance} ETH`);
+ * console.log(`Unspent UTXOs: ${result.unspentCount}`);
+ * ```
+ */
+declare function getPrivateBalance(options: {
+    keypair: Keypair;
+    rpcUrl?: string;
+    onProgress?: ProgressCallback;
+}): Promise<PrivateBalanceResult>;
+
+/**
+ * Withdrawal functions for Veil SDK
+ * Build ZK proofs to withdraw funds from the pool to a public address
+ */
+
+/**
+ * Select UTXOs for withdrawal using largest-first algorithm
+ *
+ * @param utxos - Available unspent UTXOs
+ * @param amount - Amount to withdraw (human readable)
+ * @param decimals - Token decimals (default: 18 for ETH)
+ * @returns Selected UTXOs and change amount
+ */
+declare function selectUtxosForWithdraw(utxos: Utxo[], amount: string, decimals?: number): UtxoSelectionResult;
+/**
+ * Build a withdrawal proof
+ *
+ * This function:
+ * 1. Fetches the user's unspent UTXOs
+ * 2. Selects UTXOs to cover the withdrawal amount
+ * 3. Fetches all commitments from the pool
+ * 4. Builds the ZK proof
+ *
+ * @param options - Withdrawal options
+ * @returns Proof data ready for relay submission
+ *
+ * @example
+ * ```typescript
+ * const keypair = new Keypair(process.env.VEIL_KEY);
+ * const proof = await buildWithdrawProof({
+ *   amount: '0.1',
+ *   recipient: '0x1234...',
+ *   keypair,
+ *   onProgress: (stage, detail) => console.log(stage, detail),
+ * });
+ * ```
+ */
+declare function buildWithdrawProof(options: BuildWithdrawProofOptions): Promise<ProofBuildResult>;
+/**
+ * Execute a withdrawal by building proof and submitting to relay
+ *
+ * @param options - Withdrawal options
+ * @returns Withdrawal result with transaction hash
+ *
+ * @example
+ * ```typescript
+ * const keypair = new Keypair(process.env.VEIL_KEY);
+ * const result = await withdraw({
+ *   amount: '0.1',
+ *   recipient: '0x1234...',
+ *   keypair,
+ * });
+ *
+ * console.log(`Withdrawal tx: ${result.transactionHash}`);
+ * ```
+ */
+declare function withdraw(options: BuildWithdrawProofOptions): Promise<WithdrawResult>;
+
+/**
+ * Transfer functions for Veil SDK
+ * Build ZK proofs to transfer funds privately within the pool
+ */
+
+/**
+ * Check if a recipient is registered and get their deposit key
+ *
+ * @param address - Address to check
+ * @param rpcUrl - Optional RPC URL
+ * @returns Whether registered and their deposit key if so
+ *
+ * @example
+ * ```typescript
+ * const { isRegistered, depositKey } = await checkRecipientRegistration('0x1234...');
+ * if (!isRegistered) {
+ *   console.log('Recipient needs to register first');
+ * }
+ * ```
+ */
+declare function checkRecipientRegistration(address: `0x${string}`, rpcUrl?: string): Promise<{
+    isRegistered: boolean;
+    depositKey?: string;
+}>;
+/**
+ * Build a transfer proof
+ *
+ * This function:
+ * 1. Verifies the recipient is registered
+ * 2. Fetches the sender's unspent UTXOs
+ * 3. Selects UTXOs to cover the transfer amount
+ * 4. Creates output UTXOs for recipient and change
+ * 5. Builds the ZK proof
+ *
+ * @param options - Transfer options
+ * @returns Proof data ready for relay submission
+ *
+ * @example
+ * ```typescript
+ * const senderKeypair = new Keypair(process.env.VEIL_KEY);
+ * const proof = await buildTransferProof({
+ *   amount: '0.1',
+ *   recipientAddress: '0x1234...',
+ *   senderKeypair,
+ * });
+ * ```
+ */
+declare function buildTransferProof(options: BuildTransferProofOptions): Promise<ProofBuildResult>;
+/**
+ * Execute a transfer by building proof and submitting to relay
+ *
+ * @param options - Transfer options
+ * @returns Transfer result with transaction hash
+ *
+ * @example
+ * ```typescript
+ * const senderKeypair = new Keypair(process.env.VEIL_KEY);
+ * const result = await transfer({
+ *   amount: '0.1',
+ *   recipientAddress: '0x1234...',
+ *   senderKeypair,
+ * });
+ *
+ * console.log(`Transfer tx: ${result.transactionHash}`);
+ * ```
+ */
+declare function transfer(options: BuildTransferProofOptions): Promise<TransferResult>;
+/**
+ * Merge UTXOs by doing a self-transfer
+ * This consolidates multiple small UTXOs into fewer larger ones
+ *
+ * Unlike regular transfers, merge doesn't need a recipient address -
+ * it uses the sender's keypair directly to create the output UTXO.
+ *
+ * @param options - Merge options
+ * @returns Transfer result
+ *
+ * @example
+ * ```typescript
+ * const keypair = new Keypair(process.env.VEIL_KEY);
+ * const result = await mergeUtxos({
+ *   amount: '0.5', // Total amount to consolidate
+ *   keypair,
+ * });
+ * ```
+ */
+declare function mergeUtxos(options: {
+    amount: string;
+    keypair: Keypair;
+    rpcUrl?: string;
+    onProgress?: (stage: string, detail?: string) => void;
+}): Promise<TransferResult>;
+
+/**
+ * Transaction preparation for Veil SDK
+ * Core function to build ZK proofs for withdrawals and transfers
+ */
+
+/**
+ * External data for a transaction (sent alongside proof)
+ */
+interface ExtData {
+    recipient: string;
+    extAmount: string;
+    relayer: string;
+    fee: string;
+    encryptedOutput1: string;
+    encryptedOutput2: string;
+}
+/**
+ * Proof arguments for on-chain verification
+ */
+interface ProofArgs {
+    proof: string;
+    root: string;
+    inputNullifiers: string[];
+    outputCommitments: string[];
+    publicAmount: string;
+    extDataHash: string;
+}
+/**
+ * Result of preparing a transaction
+ */
+interface TransactionResult {
+    args: ProofArgs;
+    extData: ExtData;
+}
+/**
+ * Parameters for preparing a transaction
+ */
+interface PrepareTransactionParams {
+    /** All commitments from the merkle tree (from pool contract) */
+    commitments: (string | bigint)[];
+    /** Input UTXOs to spend */
+    inputs?: Utxo[];
+    /** Output UTXOs to create */
+    outputs?: Utxo[];
+    /** Transaction fee (usually 0 for relay) */
+    fee?: bigint | number;
+    /** Recipient address for withdrawals (0x0 for transfers) */
+    recipient?: string | bigint | number;
+    /** Relayer address (0x0 for now) */
+    relayer?: string | bigint | number;
+    /** Optional progress callback */
+    onProgress?: (stage: string, detail?: string) => void;
+}
+/**
+ * Prepare a transaction (withdrawal or transfer)
+ * Builds the ZK proof and external data needed for on-chain execution
+ *
+ * @param params - Transaction parameters
+ * @returns Proof arguments and external data
+ *
+ * @example
+ * ```typescript
+ * // Withdrawal: send funds to external address
+ * const result = await prepareTransaction({
+ *   commitments: poolCommitments,
+ *   inputs: [utxo1, utxo2],
+ *   outputs: [changeUtxo], // Just change
+ *   recipient: '0x1234...', // Withdrawal address
+ *   fee: 0,
+ *   relayer: '0x0000...',
+ * });
+ *
+ * // Transfer: move funds to another Veil user
+ * const result = await prepareTransaction({
+ *   commitments: poolCommitments,
+ *   inputs: [utxo1],
+ *   outputs: [recipientUtxo, changeUtxo],
+ *   recipient: 0, // No external recipient
+ *   fee: 0,
+ *   relayer: '0x0000...',
+ * });
+ * ```
+ */
+declare function prepareTransaction({ commitments, inputs, outputs, fee, recipient, relayer, onProgress, }: PrepareTransactionParams): Promise<TransactionResult>;
+
+/**
+ * Merkle tree utilities for Veil SDK
+ * Build merkle trees from UTXO commitments for ZK proofs
+ */
+
+/**
+ * Height of the merkle tree (matches on-chain contract)
+ */
+declare const MERKLE_TREE_HEIGHT = 23;
+/**
+ * Build a merkle tree from UTXO commitments
+ * Uses Poseidon hash function compatible with on-chain verification
+ *
+ * @param commitments - Array of commitment hashes (hex strings or bigints)
+ * @returns MerkleTree instance
+ *
+ * @example
+ * ```typescript
+ * const commitments = await poolContract.getCommitments(0, 1000);
+ * const tree = await buildMerkleTree(commitments);
+ * const root = tree.root();
+ * ```
+ */
+declare function buildMerkleTree(commitments: (string | bigint)[]): Promise<MerkleTree>;
+/**
+ * Get merkle path for a commitment
+ *
+ * @param tree - Merkle tree instance
+ * @param commitment - Commitment to get path for
+ * @returns Path elements and indices
+ */
+declare function getMerklePath(tree: MerkleTree, commitment: bigint | string): {
+    pathElements: bigint[];
+    pathIndices: number;
+};
+
+/**
+ * ZK Proof generation for Veil SDK
+ * Uses snarkjs groth16 to generate proofs for transactions
+ */
+/**
+ * Input data for ZK proof generation
+ */
+interface ProofInput {
+    root: bigint;
+    inputNullifier: bigint[];
+    outputCommitment: bigint[];
+    publicAmount: string;
+    extDataHash: bigint;
+    inAmount: bigint[];
+    inPrivateKey: (string | null)[];
+    inBlinding: bigint[];
+    inPathIndices: number[];
+    inPathElements: (bigint | number)[][];
+    outAmount: bigint[];
+    outBlinding: bigint[];
+    outPubkey: bigint[];
+}
+/**
+ * Generate a ZK proof for a transaction
+ *
+ * @param input - Proof input data
+ * @param circuitName - Circuit name (e.g., 'transaction2' or 'transaction16')
+ * @returns Serialized proof as hex string
+ *
+ * @example
+ * ```typescript
+ * const proof = await prove(proofInput, 'transaction2');
+ * // Returns: 0x1234...abcd (256 bytes hex)
+ * ```
+ */
+declare function prove(input: ProofInput, circuitName: string): Promise<string>;
+/**
+ * Get the supported circuit names and their max input counts
+ */
+declare const CIRCUIT_CONFIG: {
+    readonly transaction2: {
+        readonly maxInputs: 2;
+        readonly maxOutputs: 2;
+    };
+    readonly transaction16: {
+        readonly maxInputs: 16;
+        readonly maxOutputs: 2;
+    };
+};
+/**
+ * Select the appropriate circuit based on input count
+ *
+ * @param inputCount - Number of input UTXOs
+ * @returns Circuit name to use
+ */
+declare function selectCircuit(inputCount: number): string;
+
+/**
+ * Contract addresses for Veil on Base
+ */
+
+/**
+ * Contract addresses for Base mainnet
+ */
+declare const ADDRESSES: NetworkAddresses;
+/**
+ * Pool configuration (decimals, symbols, etc.)
+ */
+declare const POOL_CONFIG: {
+    readonly eth: {
+        readonly decimals: 18;
+        readonly displayDecimals: 4;
+        readonly symbol: "ETH";
+        readonly name: "Ethereum";
+    };
+    readonly usdc: {
+        readonly decimals: 6;
+        readonly displayDecimals: 2;
+        readonly symbol: "USDC";
+        readonly name: "USD Coin";
+    };
+};
+/**
+ * Get contract addresses
+ * @returns Contract addresses for Base mainnet
+ */
+declare function getAddresses(): NetworkAddresses;
+/**
+ * Get Relay URL
+ * @returns Relay URL for Base mainnet
+ */
+declare function getRelayUrl(): string;
+
+/**
+ * Relay functions for submitting withdrawals and transfers
+ *
+ * The relay service handles transaction submission for privacy-preserving
+ * withdrawals and transfers from Veil pools.
+ *
+ * Note: Public API is rate limited to 5 requests per minute per IP.
+ *
+ * @example
+ * ```typescript
+ * import { submitRelay } from '@veil-cash/sdk';
+ *
+ * const result = await submitRelay({
+ *   type: 'withdraw',
+ *   pool: 'eth',
+ *   proofArgs: { ... },
+ *   extData: { ... },
+ *   metadata: { amount: '0.1' }
+ * });
+ *
+ * console.log(result.transactionHash);
+ * ```
+ */
+
+/**
+ * Error thrown when relay request fails
+ */
+declare class RelayError extends Error {
+    /** HTTP status code */
+    statusCode: number;
+    /** Seconds until rate limit resets (only for 429 errors) */
+    retryAfter?: number;
+    /** Network the error occurred on */
+    network?: string;
+    constructor(message: string, statusCode: number, retryAfter?: number, network?: string);
+}
+/**
+ * Submit a withdrawal or transfer to the relay service
+ *
+ * The relay service submits the transaction on behalf of the user,
+ * allowing for privacy-preserving withdrawals and transfers.
+ *
+ * Rate limit: 5 requests per minute per IP (public API)
+ *
+ * @param options - Relay options including type, pool, proofArgs, extData
+ * @returns Promise resolving to relay response with transaction hash
+ * @throws RelayError if the request fails
+ *
+ * @example
+ * ```typescript
+ * // Withdraw ETH
+ * const result = await submitRelay({
+ *   type: 'withdraw',
+ *   pool: 'eth',
+ *   proofArgs: proofData.args,
+ *   extData: proofData.extData,
+ *   metadata: { amount: '0.1', recipient: '0x...' }
+ * });
+ *
+ * // Transfer USDC
+ * const result = await submitRelay({
+ *   type: 'transfer',
+ *   pool: 'usdc',
+ *   proofArgs: proofData.args,
+ *   extData: proofData.extData,
+ *   metadata: { amount: '100' }
+ * });
+ * ```
+ */
+declare function submitRelay(options: SubmitRelayOptions): Promise<RelayResponse>;
+/**
+ * Check if relay service is healthy
+ *
+ * @param relayUrl - Optional custom relay URL
+ * @returns Promise resolving to health status
+ *
+ * @example
+ * ```typescript
+ * const health = await checkRelayHealth();
+ * console.log(health.status); // 'ok'
+ * console.log(health.network); // 'base'
+ * ```
+ */
+declare function checkRelayHealth(relayUrl?: string): Promise<{
+    status: string;
+    service: string;
+    network: string;
+    timestamp: string;
+}>;
+/**
+ * Get relay service info
+ *
+ * @param relayUrl - Optional custom relay URL
+ * @returns Promise resolving to service info including rate limit config
+ *
+ * @example
+ * ```typescript
+ * const info = await getRelayInfo();
+ * console.log(info.rateLimit.limit); // 5
+ * console.log(info.rateLimit.windowMs); // 60000
+ * ```
+ */
+declare function getRelayInfo(relayUrl?: string): Promise<{
+    service: string;
+    version: string;
+    network: string;
+    endpoints: Record<string, string>;
+    rateLimit: {
+        limit: number;
+        windowMs: number;
+        note: string;
+    };
+}>;
+
+/**
+ * Veil Entry Contract ABI
+ */
+declare const ENTRY_ABI: readonly [{
+    readonly inputs: readonly [];
+    readonly name: "DepositsDisabled";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "FeeTransferFailed";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "InvalidDepositKey";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "InvalidDepositKeyForUser";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "InvalidInitialization";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "MinimumDepositNotMet";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "NotAllowedToDeposit";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "NotInitializing";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "OnlyOperatorAllowed";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "OnlyOwnerCanRegister";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "OnlyQueueContractAllowed";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }];
+    readonly name: "OwnableInvalidOwner";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly name: "OwnableUnauthorizedAccount";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "ReentrancyGuardReentrantCall";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "USDCTransferFailed";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "UserAlreadyRegistered";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "UserNotRegistered";
+    readonly type: "error";
+}, {
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly name: "key";
+        readonly type: "bytes";
+    }];
+    readonly name: "DepositKey";
+    readonly type: "event";
+}, {
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "depositor";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly name: "DepositedETH";
+    readonly type: "event";
+}, {
+    readonly inputs: readonly [{
+        readonly components: readonly [{
+            readonly name: "owner";
+            readonly type: "address";
+        }, {
+            readonly name: "depositKey";
+            readonly type: "bytes";
+        }];
+        readonly name: "_account";
+        readonly type: "tuple";
+    }];
+    readonly name: "register";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "_depositKey";
+        readonly type: "bytes";
+    }];
+    readonly name: "queueETH";
+    readonly outputs: readonly [];
+    readonly stateMutability: "payable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "_amount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "_depositKey";
+        readonly type: "bytes";
+    }];
+    readonly name: "queueUSDC";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly name: "depositKeys";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bytes";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "depositETHEnabled";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "depositFee";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "minimumDeposit";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "_totalAmount";
+        readonly type: "uint256";
+    }];
+    readonly name: "getFeeAndNetDeposit";
+    readonly outputs: readonly [{
+        readonly name: "netDeposit";
+        readonly type: "uint256";
+    }, {
+        readonly name: "fee";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "_netDepositAmount";
+        readonly type: "uint256";
+    }];
+    readonly name: "getDepositAmountWithFee";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "_depositor";
+        readonly type: "address";
+    }];
+    readonly name: "isAllowedDepositor";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}];
+/**
+ * Queue Contract ABI (for balance queries)
+ */
+declare const QUEUE_ABI: readonly [{
+    readonly inputs: readonly [];
+    readonly name: "getPendingDeposits";
+    readonly outputs: readonly [{
+        readonly name: "nonces";
+        readonly type: "uint256[]";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "_nonce";
+        readonly type: "uint256";
+    }];
+    readonly name: "getDeposit";
+    readonly outputs: readonly [{
+        readonly components: readonly [{
+            readonly name: "fallbackReceiver";
+            readonly type: "address";
+        }, {
+            readonly name: "amountIn";
+            readonly type: "uint256";
+        }, {
+            readonly name: "fee";
+            readonly type: "uint256";
+        }, {
+            readonly name: "shieldAmount";
+            readonly type: "uint256";
+        }, {
+            readonly name: "timestamp";
+            readonly type: "uint256";
+        }, {
+            readonly name: "status";
+            readonly type: "uint8";
+        }, {
+            readonly name: "depositKey";
+            readonly type: "bytes";
+        }];
+        readonly name: "deposit";
+        readonly type: "tuple";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "depositQueueNonce";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "getPendingCount";
+    readonly outputs: readonly [{
+        readonly name: "count";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}];
+/**
+ * ETH Pool Contract ABI
+ */
+declare const POOL_ABI: readonly [{
+    readonly inputs: readonly [];
+    readonly name: "CannotWithdrawToZeroAddress";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "ETHTransferFailed";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "IncorrectExternalDataHash";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "InputAlreadySpent";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "InvalidExtAmount";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "InvalidFee";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "InvalidMerkleRoot";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "InvalidPublicAmount";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "InvalidRange";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "InvalidTransactionProof";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "OnlyForDeposits";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "OnlyForTransfers";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "OnlyForWithdrawals";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "OnlyValidatorContractAllowed";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "OnlyWETHContractAllowed";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }];
+    readonly name: "OwnableInvalidOwner";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly name: "OwnableUnauthorizedAccount";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "ProofAmountMismatch";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "ReentrancyGuardReentrantCall";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "UnsupportedInputCount";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "WETHDepositFailed";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "WETHUnwrapFailed";
+    readonly type: "error";
+}, {
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly indexed: false;
+        readonly name: "commitment";
+        readonly type: "bytes32";
+    }, {
+        readonly indexed: false;
+        readonly name: "index";
+        readonly type: "uint256";
+    }, {
+        readonly indexed: false;
+        readonly name: "encryptedOutput";
+        readonly type: "bytes";
+    }];
+    readonly name: "NewCommitment";
+    readonly type: "event";
+}, {
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly indexed: false;
+        readonly name: "nullifier";
+        readonly type: "bytes32";
+    }];
+    readonly name: "NewNullifier";
+    readonly type: "event";
+}, {
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "previousOwner";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "newOwner";
+        readonly type: "address";
+    }];
+    readonly name: "OwnershipTransferred";
+    readonly type: "event";
+}, {
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "newValidatorContract";
+        readonly type: "address";
+    }];
+    readonly name: "ValidatorContractUpdated";
+    readonly type: "event";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "FIELD_SIZE";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "ROOT_HISTORY_SIZE";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint32";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "ZERO_VALUE";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly name: "commitments";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bytes32";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "currentRootIndex";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint32";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly name: "encryptedOutputs";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bytes";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly name: "filledSubtrees";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bytes32";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "startIndex";
+        readonly type: "uint256";
+    }, {
+        readonly name: "endIndex";
+        readonly type: "uint256";
+    }];
+    readonly name: "getCommitments";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bytes32[]";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "startIndex";
+        readonly type: "uint256";
+    }, {
+        readonly name: "endIndex";
+        readonly type: "uint256";
+    }];
+    readonly name: "getEncryptedOutputs";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bytes[]";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "getLastRoot";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bytes32";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "_left";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "_right";
+        readonly type: "bytes32";
+    }];
+    readonly name: "hashLeftRight";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bytes32";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "hasher";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "_root";
+        readonly type: "bytes32";
+    }];
+    readonly name: "isKnownRoot";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "_nullifierHash";
+        readonly type: "bytes32";
+    }];
+    readonly name: "isSpent";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "levels";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint32";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "nextIndex";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint32";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "";
+        readonly type: "bytes32";
+    }];
+    readonly name: "nullifierHashes";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "owner";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly name: "roots";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bytes32";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "validatorContract";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "verifier16";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "verifier2";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "weth";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "i";
+        readonly type: "uint256";
+    }];
+    readonly name: "zeros";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bytes32";
+    }];
+    readonly stateMutability: "pure";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "_extAmount";
+        readonly type: "int256";
+    }, {
+        readonly name: "_fee";
+        readonly type: "uint256";
+    }];
+    readonly name: "calculatePublicAmount";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "pure";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly components: readonly [{
+            readonly name: "proof";
+            readonly type: "bytes";
+        }, {
+            readonly name: "root";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "inputNullifiers";
+            readonly type: "bytes32[]";
+        }, {
+            readonly name: "outputCommitments";
+            readonly type: "bytes32[2]";
+        }, {
+            readonly name: "publicAmount";
+            readonly type: "uint256";
+        }, {
+            readonly name: "extDataHash";
+            readonly type: "bytes32";
+        }];
+        readonly name: "_args";
+        readonly type: "tuple";
+    }, {
+        readonly components: readonly [{
+            readonly name: "recipient";
+            readonly type: "address";
+        }, {
+            readonly name: "extAmount";
+            readonly type: "int256";
+        }, {
+            readonly name: "relayer";
+            readonly type: "address";
+        }, {
+            readonly name: "fee";
+            readonly type: "uint256";
+        }, {
+            readonly name: "encryptedOutput1";
+            readonly type: "bytes";
+        }, {
+            readonly name: "encryptedOutput2";
+            readonly type: "bytes";
+        }];
+        readonly name: "_extData";
+        readonly type: "tuple";
+    }];
+    readonly name: "depositETH";
+    readonly outputs: readonly [];
+    readonly stateMutability: "payable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly components: readonly [{
+            readonly name: "proof";
+            readonly type: "bytes";
+        }, {
+            readonly name: "root";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "inputNullifiers";
+            readonly type: "bytes32[]";
+        }, {
+            readonly name: "outputCommitments";
+            readonly type: "bytes32[2]";
+        }, {
+            readonly name: "publicAmount";
+            readonly type: "uint256";
+        }, {
+            readonly name: "extDataHash";
+            readonly type: "bytes32";
+        }];
+        readonly name: "_args";
+        readonly type: "tuple";
+    }, {
+        readonly components: readonly [{
+            readonly name: "recipient";
+            readonly type: "address";
+        }, {
+            readonly name: "extAmount";
+            readonly type: "int256";
+        }, {
+            readonly name: "relayer";
+            readonly type: "address";
+        }, {
+            readonly name: "fee";
+            readonly type: "uint256";
+        }, {
+            readonly name: "encryptedOutput1";
+            readonly type: "bytes";
+        }, {
+            readonly name: "encryptedOutput2";
+            readonly type: "bytes";
+        }];
+        readonly name: "_extData";
+        readonly type: "tuple";
+    }];
+    readonly name: "transactETH";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly components: readonly [{
+            readonly name: "proof";
+            readonly type: "bytes";
+        }, {
+            readonly name: "root";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "inputNullifiers";
+            readonly type: "bytes32[]";
+        }, {
+            readonly name: "outputCommitments";
+            readonly type: "bytes32[2]";
+        }, {
+            readonly name: "publicAmount";
+            readonly type: "uint256";
+        }, {
+            readonly name: "extDataHash";
+            readonly type: "bytes32";
+        }];
+        readonly name: "_args";
+        readonly type: "tuple";
+    }, {
+        readonly components: readonly [{
+            readonly name: "recipient";
+            readonly type: "address";
+        }, {
+            readonly name: "extAmount";
+            readonly type: "int256";
+        }, {
+            readonly name: "relayer";
+            readonly type: "address";
+        }, {
+            readonly name: "fee";
+            readonly type: "uint256";
+        }, {
+            readonly name: "encryptedOutput1";
+            readonly type: "bytes";
+        }, {
+            readonly name: "encryptedOutput2";
+            readonly type: "bytes";
+        }];
+        readonly name: "_extData";
+        readonly type: "tuple";
+    }];
+    readonly name: "withdrawETH";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly components: readonly [{
+            readonly name: "proof";
+            readonly type: "bytes";
+        }, {
+            readonly name: "root";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "inputNullifiers";
+            readonly type: "bytes32[]";
+        }, {
+            readonly name: "outputCommitments";
+            readonly type: "bytes32[2]";
+        }, {
+            readonly name: "publicAmount";
+            readonly type: "uint256";
+        }, {
+            readonly name: "extDataHash";
+            readonly type: "bytes32";
+        }];
+        readonly name: "_args";
+        readonly type: "tuple";
+    }];
+    readonly name: "verifyProof";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "renounceOwnership";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "newOwner";
+        readonly type: "address";
+    }];
+    readonly name: "transferOwnership";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "_newValidator";
+        readonly type: "address";
+    }];
+    readonly name: "updateValidatorContract";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly stateMutability: "payable";
+    readonly type: "receive";
+}];
+/**
+ * ERC20 ABI (for USDC approval)
+ */
+declare const ERC20_ABI: readonly [{
+    readonly inputs: readonly [{
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly name: "approve";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly name: "balanceOf";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }];
+    readonly name: "allowance";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}];
+
+/**
+ * Crypto utilities for Veil SDK
+ * Poseidon hash, hex conversion, and random number generation
+ */
+/**
+ * SNARK scalar field size
+ */
+declare const FIELD_SIZE: bigint;
+/**
+ * Compute Poseidon hash of items
+ * @param items - Array of values to hash (bigint, string, or number)
+ * @returns Poseidon hash as bigint
+ */
+declare const poseidonHash: (items: (bigint | string | number)[]) => bigint;
+/**
+ * Compute Poseidon hash of two items
+ * @param a - First value
+ * @param b - Second value
+ * @returns Poseidon hash as bigint
+ */
+declare const poseidonHash2: (a: bigint | string | number, b: bigint | string | number) => bigint;
+/**
+ * Generate random bigint of specified byte length
+ * @param nbytes - Number of bytes (default: 31)
+ * @returns Random bigint
+ */
+declare const randomBN: (nbytes?: number) => bigint;
+/**
+ * Convert bigint/string/number/Buffer to fixed-length hex string
+ * @param number - Value to convert
+ * @param length - Output byte length (default: 32)
+ * @returns Hex string with 0x prefix
+ */
+declare function toFixedHex(number: bigint | string | number | Buffer, length?: number): string;
+/**
+ * Convert value to Buffer of specified byte length
+ * @param value - Value to convert
+ * @param length - Output byte length
+ * @returns Buffer
+ */
+declare const toBuffer: (value: bigint | string | number, length: number) => Buffer;
+/**
+ * External data input for hash calculation
+ */
+interface ExtDataInput {
+    recipient: string | bigint;
+    extAmount: bigint;
+    relayer: string | bigint;
+    fee: bigint;
+    encryptedOutput1: string;
+    encryptedOutput2: string;
+}
+/**
+ * Calculate hash of external data for ZK proof
+ * Uses Solidity-compatible ABI encoding and keccak256 hash
+ *
+ * @param extData - External data to hash
+ * @returns Hash as bigint (mod FIELD_SIZE)
+ */
+declare function getExtDataHash(extData: ExtDataInput): bigint;
+/**
+ * Shuffle an array using Fisher-Yates algorithm
+ * Used to randomize input/output order for privacy
+ *
+ * @param array - Array to shuffle
+ * @returns Shuffled array (mutates and returns same array)
+ */
+declare function shuffle<T>(array: T[]): T[];
+
+export { ADDRESSES, type BuildTransferProofOptions, type BuildWithdrawProofOptions, CIRCUIT_CONFIG, type DepositTxOptions, ENTRY_ABI, ERC20_ABI, type EncryptedMessage, type ExtData, type ExtDataInput, FIELD_SIZE, Keypair, MERKLE_TREE_HEIGHT, type NetworkAddresses, POOL_ABI, POOL_CONFIG, type PendingDeposit, type PoolConfig, type PrepareTransactionParams, type PrivateBalanceResult, type ProgressCallback, type ProofArgs, type ProofBuildResult, type ProofInput, QUEUE_ABI, type QueueBalanceResult, type RegisterTxOptions, RelayError, type RelayErrorResponse, type RelayExtData, type RelayMetadata, type RelayPool, type RelayProofArgs, type RelayRequest, type RelayResponse, type RelayType, type SubmitRelayOptions, type Token, type TransactionData, type TransactionResult, type TransferResult, Utxo, type UtxoInfo, type UtxoParams, type UtxoSelectionResult, type WithdrawResult, buildApproveUSDCTx, buildDepositETHTx, buildDepositTx, buildDepositUSDCTx, buildMerkleTree, buildRegisterTx, buildTransferProof, buildWithdrawProof, checkRecipientRegistration, checkRelayHealth, getAddresses, getExtDataHash, getMerklePath, getPrivateBalance, getQueueBalance, getRelayInfo, getRelayUrl, mergeUtxos, packEncryptedMessage, poseidonHash, poseidonHash2, prepareTransaction, prove, randomBN, selectCircuit, selectUtxosForWithdraw, shuffle, submitRelay, toBuffer, toFixedHex, transfer, unpackEncryptedMessage, withdraw };