@unionlabs/payments 0.1.0

package/dist/payments.d.ts

@@ -0,0 +1,835 @@
+/**
+ * TypeScript SDK for privacy-preserving transfers using Union's ZK proof system.
+ *
+ * @remarks
+ * @see https://pdfs.cdn.union.build/union-private-bridging.pdf
+ *
+ * @packageDocumentation
+ */
+
+import { Address } from 'viem';
+import { GetProofReturnType } from 'viem';
+import { Hash } from 'viem';
+import { Hex } from 'viem';
+import { PublicClient } from 'viem';
+import { WalletClient } from 'viem';
+import { Withdrawal } from 'viem';
+
+/**
+ * Client for attestation service that signs poseidon(unspendable_address, beneficiary)
+ * @public
+ */
+export declare class AttestationClient {
+    private baseUrl;
+    private apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    getAttestation(unspendableAddress: Address, beneficiary: Address): Promise<AttestationResponse>;
+}
+
+/**
+ * @public
+ */
+export declare interface AttestationRequest {
+    unspendableAddress: Address;
+    beneficiary: Address;
+}
+
+/**
+ * @public
+ */
+export declare interface AttestationResponse {
+    /** Poseidon hash of (unspendableAddress, beneficiary) */
+    attestedMessage: Hex;
+    signature: Hex;
+}
+
+/**
+ * @public
+ */
+export declare interface BalanceInfo {
+    /** Pending deposits not yet visible to light client */
+    pending: bigint;
+    /** Deposits visible to the light client (provable balance) */
+    confirmed: bigint;
+    /** Already redeemed via nullifier */
+    redeemed: bigint;
+    /** Available for redemption (confirmed - redeemed) */
+    available: bigint;
+    /** Light client height used for confirmed balance */
+    lightClientHeight: bigint;
+    /** Latest height for the pending balance */
+    latestHeight: bigint;
+}
+
+export declare namespace Client {
+    export {
+        ClientOptions,
+        UpdateLightClientOptions,
+        DepositOptions,
+        GetBalanceOptions,
+        RedeemOptions,
+        make,
+        UnionPrivatePayments,
+        waitForBlockCondition
+    }
+}
+
+/**
+ * @public
+ */
+export declare interface ClientOptions {
+    proverUrl?: URL | undefined;
+    rpcUrl: URL;
+    chainId: bigint;
+    assetAddress: Address;
+    attestationUrl?: string | undefined;
+    attestorApiKey?: string | undefined;
+}
+
+/**
+ * Compute the nullifier: Poseidon2(0xDEAD || chainId || secret)
+ * @public
+ */
+export declare function computeNullifier(secret: Hex, dstChainId: bigint): bigint;
+
+/**
+ * Compute the storage slot for an ERC20 balance mapping: keccak256(abi.encode(address, slot))
+ * @public
+ */
+export declare function computeStorageSlot(address: Address, mappingSlot: bigint): Hex;
+
+/**
+ * Compute the unspendable address: bottom 160 bits of
+ * Poseidon2(0xDEAF || dstChainId || secret || beneficiary1..4)
+ * @public
+ */
+export declare function computeUnspendableAddress(secret: Hex, dstChainId: bigint, beneficiaries: [Address, Address, Address, Address]): Address;
+
+/**
+ * @public
+ */
+export declare interface ConsensusState {
+    stateRoot: Hash;
+}
+
+/**
+ * @public
+ */
+export declare interface CounterpartyInfo {
+    tokenAddressKey: Hash;
+    balanceSlot: Hash;
+}
+
+/**
+ * @public
+ */
+export declare interface DepositOptions {
+    /** The 32-byte secret payment key as a hex string */
+    paymentKey: Hex;
+    /** Array of 0-4 beneficiary addresses*/
+    beneficiaries: Address[];
+    /** Amount to deposit (in underlying token's smallest unit) */
+    amount: bigint;
+    /** viem WalletClient with account and chain configured */
+    walletClient: WalletClient;
+}
+
+/**
+ * Result from deposit() after wrapping and transferring tokens to the unspendable address.
+ * @public
+ */
+export declare interface DepositResult {
+    /** Transaction hash of the deposit */
+    txHash: Hash;
+    /** The unspendable deposit address derived from the secret */
+    depositAddress: Address;
+    /** Address of the underlying token that was wrapped */
+    underlyingToken: Address;
+    /** Chain ID where the deposit occurred */
+    chainId: bigint;
+    /** Block height of deposit transaction */
+    height: bigint;
+}
+
+/**
+ * Deposit underlying tokens to ZAsset and transfer to a deposit address.
+ * Executes 3 transactions: approve → deposit → transfer.
+ *
+ * @param rpcUrl - RPC URL for the chain
+ * @param zAssetAddress - Address of the ZAsset contract
+ * @param depositAddress - Address to receive the ZAsset tokens (derived from secret)
+ * @param amount - Amount to deposit (in underlying token's smallest unit)
+ * @param walletClient - viem WalletClient with account and chain configured
+ * @returns Transaction hash of the final transfer, underlying token address, and chain ID
+ * @public
+ */
+export declare function depositToZAsset(rpcUrl: string, zAssetAddress: Address, depositAddress: Address, amount: bigint, walletClient: WalletClient): Promise<DepositToZAssetResult>;
+
+/**
+ * @public
+ */
+export declare interface DepositToZAssetResult {
+    txHash: Hash;
+    underlyingToken: Address;
+    chainId: bigint;
+}
+
+/**
+ * Deterministically shuffle light clients using the secret as seed.
+ * Same secret always produces the same ordering for privacy.
+ * @public
+ */
+export declare function deterministicShuffleClients(clients: LightClientData[], secret: Hex): LightClientData[];
+
+/**
+ * @public
+ */
+export declare function fetchLightClients(dstClient: RpcClient, zassetAddress: Address, clientIds: number[]): Promise<LightClientData[]>;
+
+/**
+ * @public
+ */
+export declare function fetchMptProof(srcClient: RpcClient, tokenAddress: Address, storageSlot: Hex, blockNumber: bigint): Promise<MptProofData>;
+
+/**
+ * Result from redeem() containing the transaction hash and proof details.
+ * @public
+ */
+export declare interface FullRedeemResult {
+    /** Transaction hash of the redemption */
+    txHash: Hash;
+    /** The generated proof (for record-keeping) */
+    proof: ProofJSON;
+    /** Metadata about the redemption */
+    metadata: ProofMetadata;
+}
+
+/**
+ * Generate a random secret valid for BN254 scalar field
+ * @public
+ */
+export declare function generatePaymentKey(): Hex;
+
+/**
+ * Combined result from generateProof() containing the proof and associated metadata.
+ * @public
+ */
+export declare interface GenerateProofResult {
+    /** Proof generation result from the prover */
+    proof: ProofResult;
+    /** Metadata for constructing the redeem transaction (present on success) */
+    metadata?: ProofMetadata;
+}
+
+/**
+ * @public
+ */
+export declare interface GetBalanceOptions {
+    /** The deposit address (unspendable address) */
+    depositAddress: Address;
+    /** The nullifier for this paymentKey */
+    nullifier: bigint;
+    /** The light client ID to use for querying the source chain state */
+    clientId: number;
+}
+
+/**
+ * Light client state data used for proof generation and balance queries.
+ * Light clients provide verified blockchain state roots via IBC.
+ * @public
+ */
+export declare interface LightClientData {
+    /** Unique identifier for this light client */
+    clientId: number;
+    /** Block height at which this state was captured */
+    height: bigint;
+    /** Ethereum state root at this height */
+    stateRoot: Hash;
+}
+
+/**
+ * Construct a {@link UnionPrivatePayments} client.
+ *
+ * @throws Error if asset is unrecognized.
+ * @public
+ */
+declare const make: (options: ClientOptions) => UnionPrivatePayments;
+
+/**
+ * @public
+ */
+export declare interface MptProofData {
+    accountProof: Hex[];
+    storageProof: Hex[];
+    storageValue: Hex;
+    storageRoot: Hash;
+}
+
+/**
+ * @public
+ */
+export declare function parseProofJson(proofJsonBytes: Uint8Array): ProofJSON;
+
+/**
+ * @public
+ */
+export declare interface ProofJSON {
+    proof: [string, string, string, string, string, string, string, string];
+    commitments: [string, string];
+    commitmentPok: [string, string];
+    publicInputs: string[];
+}
+
+/**
+ * @public
+ */
+export declare function proofJsonToRedeemParams(proofJson: ProofJSON, metadata: RedeemMetadata): RedeemParams;
+
+/**
+ * Client-side metadata derived from witness inputs (NOT from the prover)
+ * @public
+ */
+export declare interface ProofMetadata {
+    depositAddress: Address;
+    beneficiary: Address;
+    value: bigint;
+    lightClients: LightClientData[];
+    nullifier: bigint;
+}
+
+/**
+ * Result from the prover server after proof generation.
+ * @public
+ */
+export declare interface ProofResult {
+    /** Whether proof generation succeeded */
+    success: boolean;
+    /** Serialized proof data (only present on success) */
+    proofJson?: Uint8Array;
+    /** Error message (only present on failure) */
+    error?: string;
+    /** Timestamp when the proof was created */
+    createdAt?: Date;
+}
+
+/**
+ * Prover client for communicating with the prover gRPC-web server
+ *
+ * Uses `@connectrpc/connect-web` to communicate with the gRPC-web server.
+ * @public
+ */
+export declare class ProverClient {
+    private client;
+    private pollIntervalMs;
+    private maxPollAttempts;
+    constructor(proverUrl: string, options?: {
+        pollIntervalMs?: number;
+        maxPollAttempts?: number;
+    });
+    /**
+     * Generate a proof by sending witness data to the prover server
+     *
+     * The server handles witness transformation internally, so we send
+     * the structured WitnessData instead of pre-serialized circuit witness bytes.
+     */
+    generateProof(witness: WitnessData): Promise<ProofResult>;
+    /**
+     * Export the verifier contract from the prover server
+     */
+    exportVerifier(): Promise<string>;
+    private witnessToProto;
+    private sleep;
+}
+
+/**
+ * Client-side metadata for redeem (NOT from prover)
+ * @public
+ */
+export declare interface RedeemMetadata {
+    lightClients: LightClientData[];
+    nullifier: bigint;
+    value: bigint;
+    beneficiary: Address;
+    attestedMessage: Hex;
+    signature: Hex;
+}
+
+/**
+ * @public
+ */
+export declare interface RedeemOptions {
+    /** The 32-byte secret payment key as a hex string */
+    paymentKey: Hex;
+    /** Array of 0-4 beneficiary addresses */
+    beneficiaries: Address[];
+    /** The beneficiary address to redeem to */
+    beneficiary: Address;
+    /** Amount to redeem */
+    amount: bigint;
+    /** Light client IDs to include in the proof (for anonymity set) */
+    clientIds: number[];
+    /** The specific light client ID to use for the proof */
+    selectedClientId: number;
+    /** viem WalletClient with account and chain configured */
+    walletClient: WalletClient;
+    /** Auto unwrap */
+    unwrap?: boolean | undefined;
+}
+
+/**
+ * @public
+ */
+export declare interface RedeemParams {
+    proof: [bigint, bigint, bigint, bigint, bigint, bigint, bigint, bigint];
+    commitments: [bigint, bigint];
+    commitmentPok: [bigint, bigint];
+    lightClients: {
+        clientId: number;
+        height: bigint;
+    }[];
+    nullifier: bigint;
+    value: bigint;
+    beneficiary: Address;
+    attestedMessage: Hex;
+    signature: Hex;
+}
+
+/**
+ * @public
+ */
+export declare interface RedeemResult {
+    txHash: Hash;
+    success: boolean;
+    error?: string;
+}
+
+/**
+ * @public
+ */
+export declare interface RedeemTransaction {
+    txHash: Hash;
+    blockNumber: bigint;
+    timestamp: bigint;
+    nullifier: bigint;
+    value: bigint;
+    beneficiary: Address;
+}
+
+/**
+ * A single redemption event from getRedemptionHistory().
+ * @public
+ */
+export declare interface RedemptionHistoryEntry {
+    /** Transaction hash of the redemption */
+    txHash: Hash;
+    /** Block number when the redemption was confirmed */
+    blockNumber: bigint;
+    /** Amount redeemed in this transaction */
+    redeemAmount: bigint;
+    /** Address that received the redeemed tokens */
+    beneficiary: Address;
+}
+
+/**
+ * @public
+ */
+export declare class RpcClient {
+    private client;
+    constructor(rpcUrl: string);
+    getClient(): PublicClient;
+    getChainId(): Promise<bigint>;
+    getLatestBlockNumber(): Promise<bigint>;
+    getBalance(tokenAddress: Address, accountAddress: Address, blockNumber?: bigint): Promise<bigint>;
+    getDecimals(tokenAddress: Address): Promise<number>;
+    getSymbol(tokenAddress: Address): Promise<string>;
+    getLightClientAddress(ibcStoreAddress: Address, clientId: number): Promise<Address>;
+    getLatestHeight(lightClientAddress: Address, clientId: number): Promise<bigint>;
+    /**
+     * Get consensus state, extracting the state root at the given byte index
+     */
+    getConsensusState(lightClientAddress: Address, clientId: number, height: bigint, stateRootIndex: bigint): Promise<ConsensusState>;
+    getNullifierBalance(zassetAddress: Address, nullifier: bigint): Promise<bigint>;
+    getCounterparty(zassetAddress: Address, clientId: number): Promise<CounterpartyInfo>;
+    getIbcHandlerAddress(zassetAddress: Address): Promise<Address>;
+    getStateRootIndex(zassetAddress: Address, clientId: number): Promise<bigint>;
+    getProof(address: Address, storageKeys: Hex[], blockNumber: bigint): Promise<GetProofReturnType>;
+    getBlock(blockNumber: bigint): Promise<{
+        number: bigint;
+        nonce: `0x${string}`;
+        hash: `0x${string}`;
+        logsBloom: `0x${string}`;
+        baseFeePerGas: bigint | null;
+        blobGasUsed: bigint;
+        difficulty: bigint;
+        excessBlobGas: bigint;
+        extraData: Hex;
+        gasLimit: bigint;
+        gasUsed: bigint;
+        miner: Address;
+        mixHash: Hash;
+        parentBeaconBlockRoot?: `0x${string}` | undefined;
+        parentHash: Hash;
+        receiptsRoot: Hex;
+        sealFields: Hex[];
+        sha3Uncles: Hash;
+        size: bigint;
+        stateRoot: Hash;
+        timestamp: bigint;
+        totalDifficulty: bigint | null;
+        transactionsRoot: Hash;
+        uncles: Hash[];
+        withdrawals?: Withdrawal[] | undefined | undefined;
+        withdrawalsRoot?: `0x${string}` | undefined;
+        transactions: `0x${string}`[];
+    }>;
+    /**
+     * Get redemption history for a nullifier by querying Redeemed events
+     */
+    getRedemptionHistory(zassetAddress: Address, nullifier: bigint, fromBlock?: bigint, toBlock?: bigint): Promise<RedemptionHistoryEntry[]>;
+}
+
+/**
+ * Sign an attested message with raw ECDSA (no EIP-191 prefix).
+ * Matches Go CLI's crypto.Sign behavior for SignatureCheckerLib verification.
+ * @public
+ */
+export declare function signAttestedMessage(message: Hex, privateKey: Hex): Promise<Hex>;
+
+/**
+ * @public
+ */
+export declare function submitRedeem(zassetAddress: Address, params: RedeemParams, walletClient: WalletClient): Promise<Hash>;
+
+/**
+ * Token metadata from getSrcZAssetInfo() or getDstZAssetInfo().
+ * @public
+ */
+export declare interface TokenInfo {
+    /** Token symbol (e.g., "USDC") */
+    symbol: string;
+    /** Number of decimal places */
+    decimals: number;
+}
+
+/**
+ * Union Private Payments client
+ *
+ * This class provides a high-level interface for performing private transfers
+ * using the Union protocol. It handles:
+ *
+ * - Generating unspendable addresses for deposits
+ *
+ * - Querying balances (confirmed, pending, redeemed, available)
+ *
+ * - Building witness data for proof generation
+ *
+ * - Communicating with the prover server
+ *
+ * @example
+ * ```typescript
+ * import { UnionPrivatePayments } from '@unionlabs/payments';
+ *
+ * const client = new UnionPrivatePayments({
+ *   proverUrl: 'http://localhost:8080',
+ *   sourceRpcUrl: 'https://eth-mainnet.alchemyapi.io/v2/...',
+ *   destinationRpcUrl: 'https://arbitrum-mainnet.alchemyapi.io/v2/...',
+ *   srcZAssetAddress: '0x...', // ZAsset on source chain
+ *   dstZAssetAddress: '0x...', // ZAsset on destination chain
+ *   sourceChainId: 1n,
+ *   destinationChainId: 42161n,
+ * });
+ *
+ * // Generate deposit address
+ * const address = client.getDepositAddress(secret, beneficiaries);
+ *
+ * // Check balance
+ * const balance = await client.getBalance({ depositAddress, nullifier, clientId });
+ *
+ * // Generate proof for redemption
+ * const proof = await client.generateProof(secret, beneficiaries, beneficiary, amount, clientIds);
+ * ```
+ * @public
+ */
+export declare class UnionPrivatePayments {
+    private config;
+    private srcClient;
+    private dstClient;
+    private proverClient;
+    constructor(config: UnionPrivatePaymentsConfig);
+    /**
+     * Get the deposit address for a given secret and beneficiaries
+     *
+     * The returned address is an "unspendable" address derived from the secret.
+     * Tokens sent to this address can only be redeemed via ZK proof.
+     *
+     * @param secret - The 32-byte secret as a hex string
+     * @param beneficiaries - Array of 1-4 beneficiary addresses (remaining slots zero-padded)
+     * @returns The unspendable deposit address
+     */
+    getDepositAddress(secret: Hex, beneficiaries: Address[]): Address;
+    /**
+     * Get the nullifier for a given paymentKey
+     *
+     * The nullifier is used to prevent double-spending. Each (paymentKey, chainId) pair
+     * produces a unique nullifier that is recorded on-chain when funds are redeemed.
+     *
+     * @param paymentKey - The 32-byte paymentKey as a hex string
+     * @returns The nullifier as a bigint
+     */
+    getNullifier(paymentKey: Hex): bigint;
+    /**
+     * Get balance information
+     *
+     * Returns:
+     * - confirmed: balance visible to light client (provable)
+     * - redeemed: amount already redeemed via nullifier
+     * - available: amount that can be redeemed now (confirmed - redeemed)
+     * - pending: deposits not yet visible to light client
+     *
+     * @param options - Options for getting balance
+     * @returns Balance information
+     */
+    getBalance(options: GetBalanceOptions): Promise<BalanceInfo>;
+    /**
+     * Get balance information at a specific block height
+     *
+     * @param depositAddress - The deposit address (unspendable address)
+     * @param nullifier - The nullifier for this secret
+     * @param height - The block height to query confirmed balance at
+     * @returns Balance information at the given height
+     */
+    getBalanceAtHeight(depositAddress: Address, nullifier: bigint, height: bigint): Promise<Omit<BalanceInfo, "lightClientHeight">>;
+    /**
+     * Generate a proof for redeeming funds
+     *
+     * This method:
+     * 1. Fetches light client data from the destination chain
+     * 2. Deterministically shuffles clients for privacy
+     * 3. Fetches MPT proof from the source chain
+     * 4. Builds the witness data
+     * 5. Sends the witness to the prover server
+     * 6. Polls until the proof is ready
+     *
+     * @param secret - The 32-byte secret as a hex string
+     * @param beneficiaries - Array of 0-4 beneficiary addresses (empty array = unbounded mode)
+     * @param beneficiary - The beneficiary address to redeem to
+     * @param amount - Amount to redeem
+     * @param clientIds - Light client IDs to include in the proof (for anonymity set)
+     * @param selectedClientId - The specific light client ID to use for the proof
+     * @returns GenerateProofResult containing proof result and client-side metadata
+     */
+    generateProof(secret: Hex, beneficiaries: Address[], beneficiary: Address, amount: bigint, clientIds: number[], selectedClientId: number): Promise<GenerateProofResult>;
+    /**
+     * Export the verifier contract from the prover server
+     *
+     * The verifier contract is used to verify proofs on-chain.
+     * It is circuit-specific and does not change between proofs.
+     *
+     * @returns The Solidity verifier contract source code
+     */
+    exportVerifier(): Promise<string>;
+    /**
+     * Get source ZAsset token information
+     *
+     * @returns Token symbol and decimals
+     */
+    getSrcZAssetInfo(): Promise<TokenInfo>;
+    /**
+     * Get destination ZAsset token information
+     *
+     * @returns Token symbol and decimals
+     */
+    getDstZAssetInfo(): Promise<TokenInfo>;
+    /**
+     * Deposit underlying tokens to ZAsset and transfer to deposit address
+     *
+     * Executes 3 transactions: approve → deposit → transfer.
+     * The wallet client must be connected to the source chain.
+     *
+     * @param secret - The 32-byte secret as a hex string
+     * @param beneficiaries - Array of 0-4 beneficiary addresses
+     * @param amount - Amount to deposit (in underlying token's smallest unit)
+     * @param walletClient - viem WalletClient with account and chain configured
+     * @returns Transaction hash, deposit address, underlying token, and chain ID
+     */
+    deposit(options: DepositOptions): Promise<DepositResult>;
+    /**
+     * Deposit underlying tokens to ZAsset and transfer to deposit address
+     *
+     * Executes 3 transactions: approve → deposit → transfer.
+     * The wallet client must be connected to the source chain.
+     *
+     * @param secret - The 32-byte secret as a hex string
+     * @param beneficiaries - Array of 0-4 beneficiary addresses
+     * @param amount - Amount to deposit (in underlying token's smallest unit)
+     * @param walletClient - viem WalletClient with account and chain configured
+     * @returns Transaction hash, deposit address, underlying token, and chain ID
+     */
+    unsafeDeposit(options: DepositOptions): Promise<DepositResult>;
+    /**
+     * Update loopback light client to a specific block height
+     *
+     * Fetches the IBC handler address internally from the destination ZAsset.
+     * The wallet client must be connected to the destination chain.
+     *
+     * @returns Transaction hash, block number, state root, and chain ID
+     */
+    updateLightClient(options: UpdateLightClientOptions): Promise<UpdateLightClientResult>;
+    /**
+     * Update loopback light client to a specific block height
+     *
+     * Fetches the IBC handler address internally from the destination ZAsset.
+     * The wallet client must be connected to the destination chain.
+     *
+     * @returns Transaction hash, block number, state root, and chain ID
+     */
+    unsafeUpdateLightClient(options: UpdateLightClientOptions): Promise<UpdateLightClientResult>;
+    /**
+     * Get redemption history for a secret
+     *
+     * Queries the Redeemed events filtered by the nullifier derived from the secret.
+     * This is a read-only operation that doesn't require a wallet.
+     *
+     * @param secret - The 32-byte secret as a hex string
+     * @param fromBlock - Start block number (default: earliest)
+     * @param toBlock - End block number (default: latest)
+     * @returns Array of redemption transactions
+     */
+    getRedemptionHistory(secret: Hex, fromBlock?: bigint, toBlock?: bigint): Promise<RedemptionHistoryEntry[]>;
+    /**
+     * Get redemption history for a secret
+     *
+     * Queries the Redeemed events filtered by the nullifier derived from the secret.
+     * This is a read-only operation that doesn't require a wallet.
+     *
+     * @param secret - The 32-byte secret as a hex string
+     * @param fromBlock - Start block number (default: earliest)
+     * @param toBlock - End block number (default: latest)
+     * @returns Array of redemption transactions
+     */
+    unsafeGetRedemptionHistory(secret: Hex, fromBlock?: bigint, toBlock?: bigint): Promise<RedemptionHistoryEntry[]>;
+    /**
+     * Full redeem flow: generate proof + get attestation + submit transaction
+     *
+     * This method orchestrates the entire redemption process:
+     * 1. Generates a ZK proof via the prover server
+     * 2. Gets attestation from the attestation service
+     * 3. Submits the redeem transaction
+     *
+     * The wallet client must be connected to the destination chain.
+     *
+     * @returns Transaction hash, proof, and metadata
+     */
+    redeem(options: RedeemOptions): Promise<FullRedeemResult>;
+    /**
+     * Full redeem flow: generate proof + get attestation + submit transaction
+     *
+     * This method orchestrates the entire redemption process:
+     * 1. Generates a ZK proof via the prover server
+     * 2. Gets attestation from the attestation service
+     * 3. Submits the redeem transaction
+     *
+     * The wallet client must be connected to the destination chain.
+     *
+     * @returns Transaction hash, proof, and metadata
+     */
+    unsafeRedeem(options: RedeemOptions): Promise<FullRedeemResult>;
+    /**
+     * Pad beneficiaries array to exactly 4 addresses
+     * Empty array = unbounded mode (all zeros, any beneficiary allowed)
+     */
+    private padBeneficiaries;
+}
+
+/**
+ * Configuration for the UnionPrivatePayments client.
+ * @public
+ */
+export declare interface UnionPrivatePaymentsConfig {
+    /** URL of the ZK prover server (gRPC-web endpoint) */
+    proverUrl: string;
+    /** RPC URL for the source chain where deposits are made */
+    sourceRpcUrl: string;
+    /** RPC URL for the destination chain where redemptions occur */
+    destinationRpcUrl: string;
+    /** ZAsset contract address on the source chain */
+    srcZAssetAddress: Address;
+    /** ZAsset contract address on the destination chain */
+    dstZAssetAddress: Address;
+    /** Chain ID of the source chain */
+    sourceChainId: bigint;
+    /** Chain ID of the destination chain */
+    destinationChainId: bigint;
+    /** Optional attestation service URL for redemptions */
+    attestorUrl?: string;
+    /** Optional attestation service API key */
+    attestorApiKey?: string;
+}
+
+/**
+ * @public
+ */
+export declare interface UpdateLightClientOptions {
+    /** The light client ID to update */
+    clientId: number;
+    /** Block height to update to (bigint or 'latest') */
+    height: bigint | "latest";
+    /** viem WalletClient with account and chain configured */
+    walletClient: WalletClient;
+}
+
+/**
+ * Result from updateLightClient() after updating a loopback light client.
+ * @public
+ */
+export declare interface UpdateLightClientResult {
+    /** Transaction hash of the update */
+    txHash: Hash;
+    /** Block number the light client was updated to */
+    blockNumber: bigint;
+    /** State root at the updated block height */
+    stateRoot: Hash;
+    /** Chain ID where the update occurred */
+    chainId: bigint;
+}
+
+/**
+ * Update a loopback light client to a specific block height.
+ * The loopback client operates on the same chain, so only one RPC URL is needed.
+ *
+ * @param rpcUrl - RPC URL for the chain (same chain for fetching block and submitting tx)
+ * @param ibcHandlerAddress - Address of the IBCHandler contract
+ * @param clientId - The light client ID to update
+ * @param height - Block height to update to (bigint or 'latest')
+ * @param walletClient - viem WalletClient with account and chain configured
+ * @returns Transaction hash, block number, state root, and chain ID
+ * @public
+ */
+export declare function updateLoopbackClient(rpcUrl: string, ibcHandlerAddress: Address, clientId: number, height: bigint | 'latest', walletClient: WalletClient): Promise<UpdateLightClientResult>;
+
+/**
+ * Wait for predicate on block height
+ * @public
+ */
+export declare const waitForBlockCondition: <T extends PublicClient>(publicClient: T, predicate: (blockNumber: bigint) => boolean, options?: {
+    timeoutMs?: number | undefined;
+}) => Promise<bigint>;
+
+/**
+ * @public
+ */
+export declare interface WitnessData {
+    secret: Hex;
+    dstChainId: bigint;
+    beneficiaries: [Address, Address, Address, Address];
+    beneficiary: Address;
+    redeemAmount: bigint;
+    alreadyRedeemed: bigint;
+    lightClients: LightClientData[];
+    selectedClientIndex: number;
+    mptProof: MptProofData;
+    srcZAssetAddress: Address;
+    mappingSlot: Hex;
+}
+
+export { }