@unionlabs/payments 0.1.0 → 0.2.0

package/src/legacy/client.ts

@@ -0,0 +1,1652 @@
+import { Duration, Effect, pipe, Schedule } from "effect";
+import type { Address, Hex, PublicClient, WalletClient } from "viem";
+import {
+  createPublicClient,
+  encodeAbiParameters,
+  hexToBigInt,
+  http,
+  keccak256,
+  toRlp,
+} from "viem";
+import { AttestationClient } from "../attestation.js";
+import { Z_ASSET_REGISTRY } from "../constants/z-asset-registry.js";
+import * as evm from "../internal/evm.js";
+import { computeNullifier, computeUnspendableAddress } from "../poseidon2.js";
+import {
+  computeStorageSlot,
+  deterministicShuffleClients,
+  fetchLightClients,
+  fetchMptProof,
+  IBC_STORE_ABI,
+  parseProofJson,
+  proofJsonToRedeemParams,
+  RpcClient,
+} from "../rpc.js";
+import type {
+  BalanceInfo,
+  DepositResult,
+  FullRedeemResult,
+  GenerateProofResult,
+  RedemptionHistoryEntry,
+  TokenInfo,
+  UnionPrivatePaymentsConfig,
+  UpdateLightClientResult,
+  WitnessData,
+} from "../types.js";
+import { ProverClient } from "./prover.js";
+
+const ZERO_ADDRESS: Address = "0x0000000000000000000000000000000000000000";
+
+const commonRetry = {
+  schedule: Schedule.linear(Duration.seconds(2)),
+  times: 6,
+} as const satisfies Effect.Retry.Options<any>;
+
+/**
+ * @public
+ */
+export interface ClientOptions {
+  proverUrl?: URL | undefined; // optional, default prover.payments.union.build
+  rpcUrl: URL;
+  chainId: bigint; // fetch from rpc?
+  assetAddress: Address; // hardcode into the sdk
+  attestationUrl?: string | undefined;
+  attestorApiKey?: string | undefined;
+}
+
+/**
+ * @public
+ */
+export 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;
+}
+
+/**
+ * @public
+ */
+export 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;
+}
+
+/**
+ * @public
+ */
+export 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;
+}
+
+/**
+ * @public
+ */
+export 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;
+}
+
+/**
+ * Construct a {@link UnionPrivatePayments} client.
+ *
+ * @throws Error if asset is unrecognized.
+ * @public
+ */
+export const make = (options: ClientOptions): UnionPrivatePayments => {
+  const proverUrl =
+    options.proverUrl?.toString() ?? "https://prover.payments.union.build";
+
+  const attestorUrl =
+    options.attestationUrl?.toString() ??
+    "https://attestor.payments.union.build/functions/v1/attest";
+
+  const zAssetAddress =
+    // @ts-expect-error
+    Z_ASSET_REGISTRY[`${options.chainId}`][options.assetAddress];
+
+  if (!zAssetAddress) throw new Error("Invalid asset address");
+  if (!options.attestorApiKey) throw new Error("No attestor API key");
+
+  return new UnionPrivatePayments({
+    proverUrl,
+    sourceRpcUrl: options.rpcUrl.toString(),
+    destinationRpcUrl: options.rpcUrl.toString(),
+    srcZAssetAddress: zAssetAddress,
+    dstZAssetAddress: zAssetAddress,
+    sourceChainId: options.chainId,
+    destinationChainId: options.chainId,
+    attestorUrl: attestorUrl,
+    attestorApiKey: options.attestorApiKey,
+  });
+};
+
+/**
+ * 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 class UnionPrivatePayments {
+  private config: UnionPrivatePaymentsConfig;
+  private srcClient: RpcClient;
+  private dstClient: RpcClient;
+  private proverClient: ProverClient;
+
+  constructor(config: UnionPrivatePaymentsConfig) {
+    this.config = config;
+    this.srcClient = new RpcClient(config.sourceRpcUrl);
+    this.dstClient = new RpcClient(config.destinationRpcUrl);
+    this.proverClient = new ProverClient(config.proverUrl);
+  }
+
+  /**
+   * 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 {
+    const paddedBeneficiaries = this.padBeneficiaries(beneficiaries);
+    return computeUnspendableAddress(
+      secret,
+      this.config.destinationChainId,
+      paddedBeneficiaries,
+    );
+  }
+
+  /**
+   * 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 {
+    return computeNullifier(paymentKey, this.config.destinationChainId);
+  }
+
+  /**
+   * 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
+   */
+  async getBalance(options: GetBalanceOptions): Promise<BalanceInfo> {
+    const { depositAddress, nullifier, clientId } = options;
+    console.log(options);
+    console.log({ dstZAssetAddress: this.config.dstZAssetAddress });
+    const ibcHandlerAddress = await this.dstClient.getIbcHandlerAddress(
+      this.config.dstZAssetAddress,
+    );
+
+    const lightClientAddress = await this.dstClient.getLightClientAddress(
+      ibcHandlerAddress,
+      clientId,
+    );
+    const lightClientHeight = await this.dstClient.getLatestHeight(
+      lightClientAddress,
+      clientId,
+    );
+
+    const balance = await this.getBalanceAtHeight(
+      depositAddress,
+      nullifier,
+      lightClientHeight,
+    );
+
+    return {
+      ...balance,
+      lightClientHeight,
+    };
+  }
+
+  /**
+   * 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
+   */
+  async getBalanceAtHeight(
+    depositAddress: Address,
+    nullifier: bigint,
+    height: bigint,
+  ): Promise<Omit<BalanceInfo, "lightClientHeight">> {
+    const latestHeight = await this.srcClient.getLatestBlockNumber();
+
+    const [balanceAtTip, confirmed, redeemed] = await Promise.all([
+      this.srcClient.getBalance(this.config.srcZAssetAddress, depositAddress),
+      this.srcClient.getBalance(
+        this.config.srcZAssetAddress,
+        depositAddress,
+        height,
+      ),
+      this.dstClient.getNullifierBalance(
+        this.config.dstZAssetAddress,
+        nullifier,
+      ),
+    ]);
+
+    const available = confirmed > redeemed ? confirmed - redeemed : 0n;
+    const pending = balanceAtTip > confirmed ? balanceAtTip - confirmed : 0n;
+
+    return {
+      confirmed,
+      redeemed,
+      available,
+      pending,
+      latestHeight,
+    };
+  }
+
+  /**
+   * 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
+   */
+  async generateProof(
+    secret: Hex,
+    beneficiaries: Address[],
+    beneficiary: Address,
+    amount: bigint,
+    clientIds: number[],
+    selectedClientId: number,
+  ): Promise<GenerateProofResult> {
+    // Validate inputs
+    if (!clientIds.includes(selectedClientId)) {
+      return {
+        proof: {
+          success: false,
+          error: `selectedClientId ${selectedClientId} not in clientIds`,
+        },
+      };
+    }
+    if (beneficiary === ZERO_ADDRESS) {
+      return {
+        proof: {
+          success: false,
+          error: "Beneficiary address cannot be zero",
+        },
+      };
+    }
+
+    const paddedBeneficiaries = this.padBeneficiaries(beneficiaries);
+    const depositAddress = this.getDepositAddress(secret, beneficiaries);
+
+    const lightClients = await fetchLightClients(
+      this.dstClient,
+      this.config.dstZAssetAddress,
+      clientIds,
+    );
+
+    if (lightClients.length === 0) {
+      return {
+        proof: {
+          success: false,
+          error: "No valid light clients found",
+        },
+      };
+    }
+
+    // Deterministic shuffle: same secret always produces the same ordering for privacy
+    const shuffled = deterministicShuffleClients(lightClients, secret);
+    const selectedClientIndex = shuffled.findIndex(
+      (c) => c.clientId === selectedClientId,
+    );
+    if (selectedClientIndex === -1) {
+      return {
+        proof: {
+          success: false,
+          error: `Client ${selectedClientId} not found after fetching`,
+        },
+      };
+    }
+    const selectedClient = shuffled[selectedClientIndex]!;
+
+    const { tokenAddressKey, balanceSlot } =
+      await this.dstClient.getCounterparty(
+        this.config.dstZAssetAddress,
+        selectedClientId,
+      );
+
+    // Check if counterparty is configured for this light client
+    const ZERO_BYTES32 =
+      "0x0000000000000000000000000000000000000000000000000000000000000000";
+    if (balanceSlot === ZERO_BYTES32 || tokenAddressKey === ZERO_BYTES32) {
+      return {
+        proof: {
+          success: false,
+          error:
+            `Light client ${selectedClientId} is not configured as a counterparty on the destination ZAsset. ` +
+            `Please call setCounterparty() on the ZAsset contract first.`,
+        },
+      };
+    }
+
+    const mappingSlot = hexToBigInt(balanceSlot);
+
+    const nullifier = this.getNullifier(secret);
+
+    // Check balance at the selected light client's height
+    const balance = await this.getBalanceAtHeight(
+      depositAddress,
+      nullifier,
+      selectedClient.height,
+    );
+
+    if (amount > balance.available) {
+      return {
+        proof: {
+          success: false,
+          error:
+            `Insufficient available balance. Requested: ${amount}, Available: ${balance.available} ` +
+            `(Confirmed at height ${selectedClient.height}: ${balance.confirmed}, Already redeemed: ${balance.redeemed})`,
+        },
+      };
+    }
+
+    const storageSlot = computeStorageSlot(depositAddress, mappingSlot);
+
+    const mptProof = await fetchMptProof(
+      this.srcClient,
+      this.config.srcZAssetAddress,
+      storageSlot,
+      selectedClient.height,
+    );
+
+    const witness: WitnessData = {
+      secret,
+      dstChainId: this.config.destinationChainId,
+      beneficiaries: paddedBeneficiaries,
+      beneficiary,
+      redeemAmount: amount,
+      alreadyRedeemed: balance.redeemed,
+      lightClients: shuffled,
+      selectedClientIndex,
+      mptProof,
+      srcZAssetAddress: this.config.srcZAssetAddress,
+      mappingSlot: `0x${mappingSlot.toString(16)}` as Hex,
+    };
+
+    const proofResult = await this.proverClient.generateProof(witness);
+
+    if (proofResult.success) {
+      return {
+        proof: proofResult,
+        metadata: {
+          depositAddress,
+          beneficiary,
+          value: amount,
+          lightClients: shuffled,
+          nullifier,
+        },
+      };
+    }
+
+    return { proof: proofResult };
+  }
+
+  /**
+   * 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
+   */
+  async exportVerifier(): Promise<string> {
+    return this.proverClient.exportVerifier();
+  }
+
+  /**
+   * Get source ZAsset token information
+   *
+   * @returns Token symbol and decimals
+   */
+  async getSrcZAssetInfo(): Promise<TokenInfo> {
+    const [symbol, decimals] = await Promise.all([
+      this.srcClient.getSymbol(this.config.srcZAssetAddress),
+      this.srcClient.getDecimals(this.config.srcZAssetAddress),
+    ]);
+    return { symbol, decimals };
+  }
+
+  /**
+   * Get destination ZAsset token information
+   *
+   * @returns Token symbol and decimals
+   */
+  async getDstZAssetInfo(): Promise<TokenInfo> {
+    const [symbol, decimals] = await Promise.all([
+      this.dstClient.getSymbol(this.config.dstZAssetAddress),
+      this.dstClient.getDecimals(this.config.dstZAssetAddress),
+    ]);
+    return { symbol, decimals };
+  }
+
+  /**
+   * 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
+   */
+  async deposit(options: DepositOptions): Promise<DepositResult> {
+    const { paymentKey, beneficiaries, amount, walletClient } = options;
+
+    if (!walletClient.account) {
+      throw new Error("WalletClient must have an account");
+    }
+    if (!walletClient.chain) {
+      throw new Error("WalletClient must have a chain configured");
+    }
+
+    return Effect.gen(this, function* () {
+      const depositAddress = this.getDepositAddress(paymentKey, beneficiaries);
+
+      // Get underlying token address
+      const underlyingToken = yield* pipe(
+        evm.readContract({
+          address: this.config.srcZAssetAddress,
+          abi: [
+            {
+              inputs: [],
+              name: "underlying",
+              outputs: [{ name: "", type: "address" }],
+              stateMutability: "view",
+              type: "function",
+            },
+          ] as const,
+          functionName: "underlying",
+        }),
+        Effect.retry(commonRetry),
+        Effect.provideService(evm.PublicClient, {
+          client: this.srcClient.getClient(),
+        }),
+      );
+
+      if (underlyingToken === ZERO_ADDRESS) {
+        return yield* Effect.fail(
+          Error("ZAsset is not a wrapped token (underlying is zero address)"),
+        );
+      }
+
+      const ERC20_ABI = [
+        {
+          inputs: [
+            { name: "spender", type: "address" },
+            { name: "amount", type: "uint256" },
+          ],
+          name: "approve",
+          outputs: [{ name: "", type: "bool" }],
+          stateMutability: "nonpayable",
+          type: "function",
+        },
+      ] as const;
+
+      const ZASSET_ABI = [
+        {
+          inputs: [{ name: "amount", type: "uint256" }],
+          name: "deposit",
+          outputs: [],
+          stateMutability: "nonpayable",
+          type: "function",
+        },
+        {
+          inputs: [
+            { name: "to", type: "address" },
+            { name: "amount", type: "uint256" },
+          ],
+          name: "transfer",
+          outputs: [{ name: "", type: "bool" }],
+          stateMutability: "nonpayable",
+          type: "function",
+        },
+      ] as const;
+
+      // 1. Approve ZAsset to spend underlying tokens
+      const approveHash = yield* pipe(
+        evm.writeContract({
+          address: underlyingToken,
+          abi: ERC20_ABI,
+          functionName: "approve",
+          args: [this.config.srcZAssetAddress, amount],
+          chain: walletClient.chain,
+          account: walletClient.account!,
+        }),
+        Effect.retry(commonRetry),
+      );
+      const approveReceipt = yield* pipe(
+        evm.waitForTransactionReceipt(approveHash),
+        Effect.retry(commonRetry),
+      );
+      if (approveReceipt.status === "reverted") {
+        return yield* Effect.fail(
+          Error(`Approve transaction reverted: ${approveHash}`),
+        );
+      }
+
+      // 2. Deposit underlying to get ZAsset
+      const depositHash = yield* pipe(
+        evm.writeContract({
+          address: this.config.srcZAssetAddress,
+          abi: ZASSET_ABI,
+          functionName: "deposit",
+          args: [amount],
+          chain: walletClient.chain,
+          account: walletClient.account!,
+        }),
+        Effect.retry(commonRetry),
+      );
+      const depositReceipt = yield* evm
+        .waitForTransactionReceipt(depositHash)
+        .pipe(Effect.retry(commonRetry));
+      if (depositReceipt.status === "reverted") {
+        throw new Error(`Deposit transaction reverted: ${depositHash}`);
+      }
+
+      // 3. Transfer ZAsset to deposit address
+      const transferHash = yield* pipe(
+        evm.writeContract({
+          address: this.config.srcZAssetAddress,
+          abi: ZASSET_ABI,
+          functionName: "transfer",
+          args: [depositAddress, amount],
+          chain: walletClient.chain,
+          account: walletClient.account!,
+        }),
+        Effect.retry(commonRetry),
+      );
+      const transferReceipt =
+        yield* evm.waitForTransactionReceipt(transferHash);
+      if (transferReceipt.status === "reverted") {
+        throw new Error(`Transfer transaction reverted: ${transferHash}`);
+      }
+
+      return {
+        txHash: transferHash,
+        depositAddress,
+        underlyingToken,
+        chainId: this.config.sourceChainId,
+        height: transferReceipt.blockNumber,
+      };
+    }).pipe(
+      Effect.provide(
+        evm.PublicClient.Live({
+          chain: options.walletClient.chain,
+          transport: http(this.config.sourceRpcUrl),
+        }),
+      ),
+      Effect.provideService(evm.WalletClient, {
+        client: options.walletClient,
+        account: options.walletClient.account!,
+        chain: options.walletClient.chain!,
+      }),
+      Effect.runPromise,
+    );
+  }
+
+  /**
+   * 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
+   */
+  async unsafeDeposit(options: DepositOptions): Promise<DepositResult> {
+    const { paymentKey, beneficiaries, amount, walletClient } = options;
+    if (!walletClient.account) {
+      throw new Error("WalletClient must have an account");
+    }
+    if (!walletClient.chain) {
+      throw new Error("WalletClient must have a chain configured");
+    }
+
+    const depositAddress = this.getDepositAddress(paymentKey, beneficiaries);
+    const publicClient = createPublicClient({
+      chain: walletClient.chain,
+      transport: http(this.config.sourceRpcUrl),
+    });
+
+    // Get underlying token address
+    const underlyingToken = (await this.srcClient.getClient().readContract({
+      address: this.config.srcZAssetAddress,
+      abi: [
+        {
+          inputs: [],
+          name: "underlying",
+          outputs: [{ name: "", type: "address" }],
+          stateMutability: "view",
+          type: "function",
+        },
+      ] as const,
+      functionName: "underlying",
+    })) as Address;
+
+    if (underlyingToken === ZERO_ADDRESS) {
+      throw new Error(
+        "ZAsset is not a wrapped token (underlying is zero address)",
+      );
+    }
+
+    const ERC20_ABI = [
+      {
+        inputs: [
+          { name: "spender", type: "address" },
+          { name: "amount", type: "uint256" },
+        ],
+        name: "approve",
+        outputs: [{ name: "", type: "bool" }],
+        stateMutability: "nonpayable",
+        type: "function",
+      },
+    ] as const;
+
+    const ZASSET_ABI = [
+      {
+        inputs: [{ name: "amount", type: "uint256" }],
+        name: "deposit",
+        outputs: [],
+        stateMutability: "nonpayable",
+        type: "function",
+      },
+      {
+        inputs: [
+          { name: "to", type: "address" },
+          { name: "amount", type: "uint256" },
+        ],
+        name: "transfer",
+        outputs: [{ name: "", type: "bool" }],
+        stateMutability: "nonpayable",
+        type: "function",
+      },
+    ] as const;
+
+    // 1. Approve ZAsset to spend underlying tokens
+    const approveHash = await walletClient
+      .writeContractSync({
+        address: underlyingToken,
+        abi: ERC20_ABI,
+        functionName: "approve",
+        args: [this.config.srcZAssetAddress, amount],
+        chain: walletClient.chain,
+        account: walletClient.account,
+      })
+      .then((x) => x.transactionHash);
+    const approveReceipt = await publicClient.waitForTransactionReceipt({
+      hash: approveHash,
+    });
+    if (approveReceipt.status === "reverted") {
+      throw new Error(`Approve transaction reverted: ${approveHash}`);
+    }
+
+    // 2. Deposit underlying to get ZAsset
+    const depositHash = await walletClient
+      .writeContractSync({
+        address: this.config.srcZAssetAddress,
+        abi: ZASSET_ABI,
+        functionName: "deposit",
+        args: [amount],
+        chain: walletClient.chain,
+        account: walletClient.account,
+      })
+      .then((x) => x.transactionHash);
+    const depositReceipt = await publicClient.waitForTransactionReceipt({
+      hash: depositHash,
+    });
+    if (depositReceipt.status === "reverted") {
+      throw new Error(`Deposit transaction reverted: ${depositHash}`);
+    }
+
+    // 3. Transfer ZAsset to deposit address
+    const transferHash = await walletClient
+      .writeContractSync({
+        address: this.config.srcZAssetAddress,
+        abi: ZASSET_ABI,
+        functionName: "transfer",
+        args: [depositAddress, amount],
+        chain: walletClient.chain,
+        account: walletClient.account,
+      })
+      .then((x) => x.transactionHash);
+    const transferReceipt = await publicClient.waitForTransactionReceipt({
+      hash: transferHash,
+    });
+    if (transferReceipt.status === "reverted") {
+      throw new Error(`Transfer transaction reverted: ${transferHash}`);
+    }
+
+    return {
+      txHash: transferHash,
+      depositAddress,
+      underlyingToken,
+      chainId: this.config.sourceChainId,
+      height: transferReceipt.blockNumber,
+    };
+  }
+
+  /**
+   * 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
+   */
+  async updateLightClient(
+    options: UpdateLightClientOptions,
+  ): Promise<UpdateLightClientResult> {
+    const { clientId, height, walletClient } = options;
+
+    if (!walletClient.account) {
+      throw new Error("WalletClient must have an account");
+    }
+    if (!walletClient.chain) {
+      throw new Error("WalletClient must have a chain configured");
+    }
+
+    return Effect.gen(this, function* () {
+      const publicClient = createPublicClient({
+        chain: walletClient.chain,
+        transport: http(this.config.destinationRpcUrl),
+      });
+
+      // Get IBC handler address from ZAsset
+      const ibcHandlerAddress = yield* Effect.tryPromise({
+        try: () =>
+          this.dstClient.getIbcHandlerAddress(this.config.dstZAssetAddress),
+        catch: (cause) => Effect.fail(cause as Error),
+      });
+
+      // Get the block number
+      const blockNumber =
+        height === "latest"
+          ? yield* pipe(
+              Effect.tryPromise(() => publicClient.getBlockNumber()),
+              Effect.retry(commonRetry),
+            )
+          : height;
+
+      // Get the block for metadata
+      const block = yield* pipe(
+        Effect.tryPromise(() => publicClient.getBlock({ blockNumber })),
+        Effect.retry(commonRetry),
+      );
+
+      if (!block.number) {
+        throw new Error("Block number is null");
+      }
+
+      // Helper to convert bigint/number to minimal RLP hex encoding
+      const toRlpHex = (value: bigint | number | null | undefined): Hex => {
+        if (
+          value === undefined ||
+          value === null ||
+          value === 0n ||
+          value === 0
+        ) {
+          return "0x" as Hex;
+        }
+        let hex =
+          typeof value === "bigint" ? value.toString(16) : value.toString(16);
+        if (hex.length % 2 !== 0) {
+          hex = "0" + hex;
+        }
+        return `0x${hex}` as Hex;
+      };
+
+      // Build header fields in order (pre-merge + post-merge fields)
+      const headerFields: (Hex | Hex[])[] = [
+        block.parentHash,
+        block.sha3Uncles,
+        block.miner,
+        block.stateRoot,
+        block.transactionsRoot,
+        block.receiptsRoot,
+        block.logsBloom ?? (("0x" + "00".repeat(256)) as Hex),
+        toRlpHex(block.difficulty),
+        toRlpHex(block.number),
+        toRlpHex(block.gasLimit),
+        toRlpHex(block.gasUsed),
+        toRlpHex(block.timestamp),
+        block.extraData,
+        block.mixHash ??
+          ("0x0000000000000000000000000000000000000000000000000000000000000000" as Hex),
+        block.nonce ?? ("0x0000000000000000" as Hex),
+      ];
+
+      // Post-merge fields
+      if (block.baseFeePerGas !== undefined && block.baseFeePerGas !== null) {
+        headerFields.push(toRlpHex(block.baseFeePerGas));
+      }
+      if (block.withdrawalsRoot) {
+        headerFields.push(block.withdrawalsRoot);
+      }
+      if (block.blobGasUsed !== undefined && block.blobGasUsed !== null) {
+        headerFields.push(toRlpHex(block.blobGasUsed));
+      }
+      if (block.excessBlobGas !== undefined && block.excessBlobGas !== null) {
+        headerFields.push(toRlpHex(block.excessBlobGas));
+      }
+      if (block.parentBeaconBlockRoot) {
+        headerFields.push(block.parentBeaconBlockRoot);
+      }
+      const blockAny = block as Record<string, unknown>;
+      if (blockAny.requestsHash) {
+        headerFields.push(blockAny.requestsHash as Hex);
+      }
+
+      const rlpEncoded = toRlp(headerFields);
+
+      // Verify the encoding produces the correct block hash
+      const computedHash = keccak256(rlpEncoded);
+      if (computedHash !== block.hash) {
+        throw new Error(
+          `RLP encoding mismatch: computed hash ${computedHash} does not match block hash ${block.hash}`,
+        );
+      }
+
+      // Encode the Header struct: (uint64 height, bytes encodedHeader)
+      const clientMessage = encodeAbiParameters(
+        [
+          { type: "uint64", name: "height" },
+          { type: "bytes", name: "encodedHeader" },
+        ],
+        [block.number, rlpEncoded],
+      );
+
+      const LIGHTCLIENT_ABI = [
+        {
+          inputs: [
+            { name: "caller", type: "address" },
+            { name: "clientId", type: "uint32" },
+            { name: "clientMessage", type: "bytes" },
+            { name: "relayer", type: "address" },
+          ],
+          name: "updateClient",
+          outputs: [],
+          stateMutability: "nonpayable",
+          type: "function",
+        },
+      ] as const;
+
+      // Wait for the next block so the fetched block's hash is verifiable on-chain
+      let currentBlock = yield* pipe(
+        Effect.tryPromise(() => publicClient.getBlockNumber()),
+        Effect.retry(commonRetry),
+      );
+      while (currentBlock <= blockNumber) {
+        yield* Effect.sleep("1 second");
+        currentBlock = yield* Effect.tryPromise(() =>
+          publicClient.getBlockNumber(),
+        );
+      }
+
+      const loopbackClient = yield* pipe(
+        evm.readContract({
+          address: ibcHandlerAddress,
+          abi: IBC_STORE_ABI,
+          functionName: "getClient",
+          args: [clientId],
+        }),
+        Effect.retry(commonRetry),
+      );
+
+      // Submit the transaction
+      const txHash = yield* pipe(
+        evm.writeContract({
+          address: loopbackClient,
+          abi: LIGHTCLIENT_ABI,
+          functionName: "updateClient",
+          args: [
+            walletClient.account!.address,
+            clientId,
+            clientMessage,
+            walletClient.account!.address,
+          ],
+          chain: walletClient.chain,
+          account: walletClient.account!,
+        }),
+        Effect.retry(commonRetry),
+      );
+
+      const chainId = yield* Effect.sync(() => this.config.destinationChainId);
+
+      return {
+        txHash,
+        blockNumber: block.number,
+        stateRoot: block.stateRoot,
+        chainId,
+      };
+    }).pipe(
+      Effect.provide(
+        evm.PublicClient.Live({
+          chain: walletClient.chain,
+          transport: http(this.config.destinationRpcUrl),
+        }),
+      ),
+      Effect.provideService(evm.WalletClient, {
+        client: options.walletClient,
+        account: options.walletClient.account!,
+        chain: options.walletClient.chain!,
+      }),
+      Effect.runPromise,
+    );
+  }
+
+  /**
+   * 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
+   */
+  async unsafeUpdateLightClient(
+    options: UpdateLightClientOptions,
+  ): Promise<UpdateLightClientResult> {
+    const { clientId, height, walletClient } = options;
+
+    if (!walletClient.account) {
+      throw new Error("WalletClient must have an account");
+    }
+    if (!walletClient.chain) {
+      throw new Error("WalletClient must have a chain configured");
+    }
+
+    const publicClient = createPublicClient({
+      chain: walletClient.chain,
+      transport: http(this.config.destinationRpcUrl),
+    });
+
+    // Get IBC handler address from ZAsset
+    const ibcHandlerAddress = await this.dstClient.getIbcHandlerAddress(
+      this.config.dstZAssetAddress,
+    );
+
+    // Get the block number
+    const blockNumber =
+      height === "latest" ? await publicClient.getBlockNumber() : height;
+
+    // Get the block for metadata
+    const block = await publicClient.getBlock({ blockNumber });
+
+    if (!block.number) {
+      throw new Error("Block number is null");
+    }
+
+    // Helper to convert bigint/number to minimal RLP hex encoding
+    const toRlpHex = (value: bigint | number | null | undefined): Hex => {
+      if (
+        value === undefined ||
+        value === null ||
+        value === 0n ||
+        value === 0
+      ) {
+        return "0x" as Hex;
+      }
+      let hex =
+        typeof value === "bigint" ? value.toString(16) : value.toString(16);
+      if (hex.length % 2 !== 0) {
+        hex = "0" + hex;
+      }
+      return `0x${hex}` as Hex;
+    };
+
+    // Build header fields in order (pre-merge + post-merge fields)
+    const headerFields: (Hex | Hex[])[] = [
+      block.parentHash,
+      block.sha3Uncles,
+      block.miner,
+      block.stateRoot,
+      block.transactionsRoot,
+      block.receiptsRoot,
+      block.logsBloom ?? (("0x" + "00".repeat(256)) as Hex),
+      toRlpHex(block.difficulty),
+      toRlpHex(block.number),
+      toRlpHex(block.gasLimit),
+      toRlpHex(block.gasUsed),
+      toRlpHex(block.timestamp),
+      block.extraData,
+      block.mixHash ??
+        ("0x0000000000000000000000000000000000000000000000000000000000000000" as Hex),
+      block.nonce ?? ("0x0000000000000000" as Hex),
+    ];
+
+    // Post-merge fields
+    if (block.baseFeePerGas !== undefined && block.baseFeePerGas !== null) {
+      headerFields.push(toRlpHex(block.baseFeePerGas));
+    }
+    if (block.withdrawalsRoot) {
+      headerFields.push(block.withdrawalsRoot);
+    }
+    if (block.blobGasUsed !== undefined && block.blobGasUsed !== null) {
+      headerFields.push(toRlpHex(block.blobGasUsed));
+    }
+    if (block.excessBlobGas !== undefined && block.excessBlobGas !== null) {
+      headerFields.push(toRlpHex(block.excessBlobGas));
+    }
+    if (block.parentBeaconBlockRoot) {
+      headerFields.push(block.parentBeaconBlockRoot);
+    }
+    const blockAny = block as Record<string, unknown>;
+    if (blockAny.requestsHash) {
+      headerFields.push(blockAny.requestsHash as Hex);
+    }
+
+    const rlpEncoded = toRlp(headerFields);
+
+    // Verify the encoding produces the correct block hash
+    const computedHash = keccak256(rlpEncoded);
+    if (computedHash !== block.hash) {
+      throw new Error(
+        `RLP encoding mismatch: computed hash ${computedHash} does not match block hash ${block.hash}`,
+      );
+    }
+
+    // Encode the Header struct: (uint64 height, bytes encodedHeader)
+    const clientMessage = encodeAbiParameters(
+      [
+        { type: "uint64", name: "height" },
+        { type: "bytes", name: "encodedHeader" },
+      ],
+      [block.number, rlpEncoded],
+    );
+
+    const LIGHTCLIENT_ABI = [
+      {
+        inputs: [
+          { name: "caller", type: "address" },
+          { name: "clientId", type: "uint32" },
+          { name: "clientMessage", type: "bytes" },
+          { name: "relayer", type: "address" },
+        ],
+        name: "updateClient",
+        outputs: [],
+        stateMutability: "nonpayable",
+        type: "function",
+      },
+    ] as const;
+
+    // Wait for the next block so the fetched block's hash is verifiable on-chain
+    let currentBlock = await publicClient.getBlockNumber();
+    while (currentBlock <= blockNumber) {
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+      currentBlock = await publicClient.getBlockNumber();
+    }
+
+    const loopbackClient = await publicClient.readContract({
+      address: ibcHandlerAddress,
+      abi: IBC_STORE_ABI,
+      functionName: "getClient",
+      args: [clientId],
+    });
+
+    // Submit the transaction
+    const txHash = await walletClient
+      .writeContractSync({
+        address: loopbackClient,
+        abi: LIGHTCLIENT_ABI,
+        functionName: "updateClient",
+        args: [
+          walletClient.account.address,
+          clientId,
+          clientMessage,
+          walletClient.account.address,
+        ],
+        chain: walletClient.chain,
+        account: walletClient.account,
+      })
+      .then((x) => x.transactionHash);
+
+    return {
+      txHash,
+      blockNumber: block.number,
+      stateRoot: block.stateRoot,
+      chainId: this.config.destinationChainId,
+    };
+  }
+
+  /**
+   * 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[]> {
+    return Effect.gen(this, function* () {
+      const nullifier = this.getNullifier(secret);
+      return yield* pipe(
+        Effect.tryPromise(() =>
+          this.dstClient.getRedemptionHistory(
+            this.config.dstZAssetAddress,
+            nullifier,
+            fromBlock,
+            toBlock,
+          ),
+        ),
+        Effect.retry(commonRetry),
+      );
+    }).pipe(Effect.runPromise);
+  }
+
+  /**
+   * 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
+   */
+  async unsafeGetRedemptionHistory(
+    secret: Hex,
+    fromBlock?: bigint,
+    toBlock?: bigint,
+  ): Promise<RedemptionHistoryEntry[]> {
+    const nullifier = this.getNullifier(secret);
+    return this.dstClient.getRedemptionHistory(
+      this.config.dstZAssetAddress,
+      nullifier,
+      fromBlock,
+      toBlock,
+    );
+  }
+
+  /**
+   * 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> {
+    const {
+      paymentKey,
+      beneficiaries,
+      beneficiary,
+      amount,
+      clientIds,
+      selectedClientId,
+      walletClient,
+      unwrap = true,
+    } = options;
+
+    // Resolve attestation URL and API key from options or stored config
+    const attestationUrl = this.config.attestorUrl;
+    const attestorApiKey = this.config.attestorApiKey;
+
+    if (!attestationUrl) {
+      throw Error(
+        "Attestation URL must be provided either in redeem options or ClientOptions",
+      );
+    }
+    if (!attestorApiKey) {
+      throw Error(
+        "Attestation API key must be provided either in redeem options or ClientOptions",
+      );
+    }
+
+    if (!walletClient.account) {
+      throw Error("WalletClient must have an account");
+    }
+    if (!walletClient.chain) {
+      throw Error("WalletClient must have a chain configured");
+    }
+
+    return Effect.gen(this, function* () {
+      // 1. Generate proof
+      const proofResult = yield* Effect.tryPromise({
+        try: () =>
+          this.generateProof(
+            paymentKey,
+            beneficiaries,
+            beneficiary,
+            amount,
+            clientIds,
+            selectedClientId,
+          ),
+        catch: (cause) => Effect.fail(cause as Error),
+      }).pipe(Effect.retry(commonRetry));
+
+      if (
+        !proofResult.proof.success ||
+        !proofResult.proof.proofJson ||
+        !proofResult.metadata
+      ) {
+        return yield* Effect.fail(
+          Error(proofResult.proof.error ?? "Proof generation failed"),
+        );
+      }
+
+      const proofJson = parseProofJson(proofResult.proof.proofJson);
+      const metadata = proofResult.metadata;
+      const depositAddress = this.getDepositAddress(paymentKey, beneficiaries);
+
+      // 2. Get attestation
+      const attestationClient = new AttestationClient(
+        attestationUrl,
+        attestorApiKey,
+      );
+      const attestationResponse = yield* Effect.tryPromise({
+        try: () =>
+          attestationClient.getAttestation(depositAddress, beneficiary),
+        catch: (cause) => Effect.fail(cause as Error),
+      }).pipe(Effect.retry(commonRetry));
+
+      // 3. Build redeem params
+      const redeemParams = proofJsonToRedeemParams(proofJson, {
+        lightClients: metadata.lightClients,
+        nullifier: metadata.nullifier,
+        value: metadata.value,
+        beneficiary: metadata.beneficiary,
+        attestedMessage: attestationResponse.attestedMessage,
+        signature: attestationResponse.signature,
+      });
+
+      // 4. Submit transaction
+      const ZASSET_ABI = [
+        {
+          inputs: [
+            { name: "proof", type: "uint256[8]" },
+            { name: "commitments", type: "uint256[2]" },
+            { name: "commitmentPok", type: "uint256[2]" },
+            {
+              name: "lightClients",
+              type: "tuple[]",
+              components: [
+                { name: "clientId", type: "uint32" },
+                { name: "height", type: "uint64" },
+              ],
+            },
+            { name: "nullifier", type: "uint256" },
+            { name: "value", type: "uint256" },
+            { name: "beneficiary", type: "address" },
+            { name: "attestedMessage", type: "bytes32" },
+            { name: "signature", type: "bytes" },
+            { name: "unwrap", type: "bool" },
+          ],
+          name: "redeem",
+          outputs: [],
+          stateMutability: "nonpayable",
+          type: "function",
+        },
+      ] as const;
+
+      const txHash = yield* pipe(
+        evm.writeContract({
+          address: this.config.dstZAssetAddress,
+          abi: ZASSET_ABI,
+          functionName: "redeem",
+          args: [
+            redeemParams.proof,
+            redeemParams.commitments,
+            redeemParams.commitmentPok,
+            redeemParams.lightClients,
+            redeemParams.nullifier,
+            redeemParams.value,
+            redeemParams.beneficiary,
+            redeemParams.attestedMessage,
+            redeemParams.signature,
+            unwrap,
+          ],
+          chain: walletClient.chain!,
+          account: walletClient.account!,
+        }),
+        Effect.retry(commonRetry),
+      );
+
+      return {
+        txHash,
+        proof: proofJson,
+        metadata,
+      } as const;
+    }).pipe(
+      Effect.provide(
+        evm.PublicClient.Live({
+          chain: options.walletClient.chain,
+          transport: http(this.config.destinationRpcUrl),
+        }),
+      ),
+      Effect.provideService(evm.WalletClient, {
+        client: options.walletClient,
+        account: options.walletClient.account!,
+        chain: options.walletClient.chain!,
+      }),
+      Effect.runPromise,
+    );
+  }
+
+  /**
+   * 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
+   */
+  async unsafeRedeem(options: RedeemOptions): Promise<FullRedeemResult> {
+    const {
+      paymentKey,
+      beneficiaries,
+      beneficiary,
+      amount,
+      clientIds,
+      selectedClientId,
+      walletClient,
+      unwrap = true,
+    } = options;
+
+    // Resolve attestation URL and API key from options or stored config
+    const attestationUrl = this.config.attestorUrl;
+    const attestorApiKey = this.config.attestorApiKey;
+
+    if (!attestationUrl) {
+      throw new Error(
+        "Attestation URL must be provided either in redeem options or ClientOptions",
+      );
+    }
+    if (!attestorApiKey) {
+      throw new Error(
+        "Attestation API key must be provided either in redeem options or ClientOptions",
+      );
+    }
+
+    if (!walletClient.account) {
+      throw new Error("WalletClient must have an account");
+    }
+    if (!walletClient.chain) {
+      throw new Error("WalletClient must have a chain configured");
+    }
+
+    // 1. Generate proof
+    const proofResult = await this.generateProof(
+      paymentKey,
+      beneficiaries,
+      beneficiary,
+      amount,
+      clientIds,
+      selectedClientId,
+    );
+
+    if (
+      !proofResult.proof.success ||
+      !proofResult.proof.proofJson ||
+      !proofResult.metadata
+    ) {
+      throw new Error(proofResult.proof.error ?? "Proof generation failed");
+    }
+
+    const proofJson = parseProofJson(proofResult.proof.proofJson);
+    const metadata = proofResult.metadata;
+    const depositAddress = this.getDepositAddress(paymentKey, beneficiaries);
+
+    // 2. Get attestation
+    const attestationClient = new AttestationClient(
+      attestationUrl,
+      attestorApiKey,
+    );
+    const attestationResponse = await attestationClient.getAttestation(
+      depositAddress,
+      beneficiary,
+    );
+
+    // 3. Build redeem params
+    const redeemParams = proofJsonToRedeemParams(proofJson, {
+      lightClients: metadata.lightClients,
+      nullifier: metadata.nullifier,
+      value: metadata.value,
+      beneficiary: metadata.beneficiary,
+      attestedMessage: attestationResponse.attestedMessage,
+      signature: attestationResponse.signature,
+    });
+
+    // 4. Submit transaction
+    const publicClient = createPublicClient({
+      chain: walletClient.chain,
+      transport: http(this.config.destinationRpcUrl),
+    });
+
+    const ZASSET_ABI = [
+      {
+        inputs: [
+          { name: "proof", type: "uint256[8]" },
+          { name: "commitments", type: "uint256[2]" },
+          { name: "commitmentPok", type: "uint256[2]" },
+          {
+            name: "lightClients",
+            type: "tuple[]",
+            components: [
+              { name: "clientId", type: "uint32" },
+              { name: "height", type: "uint64" },
+            ],
+          },
+          { name: "nullifier", type: "uint256" },
+          { name: "value", type: "uint256" },
+          { name: "beneficiary", type: "address" },
+          { name: "attestedMessage", type: "bytes32" },
+          { name: "signature", type: "bytes" },
+          { name: "unwrap", type: "bool" },
+        ],
+        name: "redeem",
+        outputs: [],
+        stateMutability: "nonpayable",
+        type: "function",
+      },
+    ] as const;
+
+    const txHash = await walletClient
+      .writeContractSync({
+        address: this.config.dstZAssetAddress,
+        abi: ZASSET_ABI,
+        functionName: "redeem",
+        args: [
+          redeemParams.proof,
+          redeemParams.commitments,
+          redeemParams.commitmentPok,
+          redeemParams.lightClients,
+          redeemParams.nullifier,
+          redeemParams.value,
+          redeemParams.beneficiary,
+          redeemParams.attestedMessage,
+          redeemParams.signature,
+          unwrap,
+        ],
+        chain: walletClient.chain,
+        account: walletClient.account,
+      })
+      .then((x) => x.transactionHash);
+
+    const receipt = await publicClient.waitForTransactionReceipt({
+      hash: txHash,
+    });
+    if (receipt.status === "reverted") {
+      throw new Error(`Redeem transaction reverted: ${txHash}`);
+    }
+
+    return {
+      txHash,
+      proof: proofJson,
+      metadata,
+    };
+  }
+
+  /**
+   * Pad beneficiaries array to exactly 4 addresses
+   * Empty array = unbounded mode (all zeros, any beneficiary allowed)
+   */
+  private padBeneficiaries(
+    beneficiaries: Address[],
+  ): [Address, Address, Address, Address] {
+    if (beneficiaries.length > 4) {
+      throw new Error("Maximum 4 beneficiaries allowed");
+    }
+
+    const padded: [Address, Address, Address, Address] = [
+      beneficiaries[0] ?? ZERO_ADDRESS,
+      beneficiaries[1] ?? ZERO_ADDRESS,
+      beneficiaries[2] ?? ZERO_ADDRESS,
+      beneficiaries[3] ?? ZERO_ADDRESS,
+    ];
+
+    return padded;
+  }
+}
+
+/**
+ * Wait for predicate on block height
+ * @public
+ */
+export const waitForBlockCondition = <T extends PublicClient>(
+  publicClient: T,
+  predicate: (blockNumber: bigint) => boolean,
+  options?: { timeoutMs?: number | undefined },
+): Promise<bigint> => {
+  const timeoutMs = options?.timeoutMs ?? 60_000;
+  return new Promise((resolve, reject) => {
+    let done = false;
+
+    const unwatch = publicClient.watchBlockNumber({
+      onBlockNumber(blockNumber) {
+        if (done) return;
+
+        if (predicate(blockNumber)) {
+          done = true;
+          unwatch();
+          resolve(blockNumber);
+        }
+      },
+      onError(error) {
+        if (done) return;
+        done = true;
+        unwatch();
+        reject(error);
+      },
+    });
+
+    setTimeout(() => {
+      if (done) return;
+      done = true;
+      unwatch();
+      reject(new Error("Timed out waiting for block condition"));
+    }, timeoutMs);
+  });
+};