@unionlabs/payments 0.1.0 → 0.2.0

package/dist/esm/legacy/client.js

@@ -0,0 +1,1212 @@
+import { Duration, Effect, pipe, Schedule } from "effect";
+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 { ProverClient } from "./prover.js";
+const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+const commonRetry = {
+  schedule: /*#__PURE__*/Schedule.linear(/*#__PURE__*/Duration.seconds(2)),
+  times: 6
+};
+/**
+ * Construct a {@link UnionPrivatePayments} client.
+ *
+ * @throws Error if asset is unrecognized.
+ * @public
+ */
+export const make = options => {
+  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 {
+  config;
+  srcClient;
+  dstClient;
+  proverClient;
+  constructor(config) {
+    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, beneficiaries) {
+    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) {
+    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) {
+    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, nullifier, height) {
+    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, beneficiaries, beneficiary, amount, clientIds, selectedClientId) {
+    // 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 = {
+      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)}`
+    };
+    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() {
+    return this.proverClient.exportVerifier();
+  }
+  /**
+   * Get source ZAsset token information
+   *
+   * @returns Token symbol and decimals
+   */
+  async getSrcZAssetInfo() {
+    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() {
+    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) {
+    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"
+        }],
+        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"
+      }];
+      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"
+      }];
+      // 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) {
+    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"
+      }],
+      functionName: "underlying"
+    });
+    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"
+    }];
+    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"
+    }];
+    // 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) {
+    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)
+      });
+      // 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 => {
+        if (value === undefined || value === null || value === 0n || value === 0) {
+          return "0x";
+        }
+        let hex = typeof value === "bigint" ? value.toString(16) : value.toString(16);
+        if (hex.length % 2 !== 0) {
+          hex = "0" + hex;
+        }
+        return `0x${hex}`;
+      };
+      // Build header fields in order (pre-merge + post-merge fields)
+      const headerFields = [block.parentHash, block.sha3Uncles, block.miner, block.stateRoot, block.transactionsRoot, block.receiptsRoot, block.logsBloom ?? "0x" + "00".repeat(256), toRlpHex(block.difficulty), toRlpHex(block.number), toRlpHex(block.gasLimit), toRlpHex(block.gasUsed), toRlpHex(block.timestamp), block.extraData, block.mixHash ?? "0x0000000000000000000000000000000000000000000000000000000000000000", block.nonce ?? "0x0000000000000000"];
+      // 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;
+      if (blockAny.requestsHash) {
+        headerFields.push(blockAny.requestsHash);
+      }
+      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"
+      }];
+      // 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) {
+    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 => {
+      if (value === undefined || value === null || value === 0n || value === 0) {
+        return "0x";
+      }
+      let hex = typeof value === "bigint" ? value.toString(16) : value.toString(16);
+      if (hex.length % 2 !== 0) {
+        hex = "0" + hex;
+      }
+      return `0x${hex}`;
+    };
+    // Build header fields in order (pre-merge + post-merge fields)
+    const headerFields = [block.parentHash, block.sha3Uncles, block.miner, block.stateRoot, block.transactionsRoot, block.receiptsRoot, block.logsBloom ?? "0x" + "00".repeat(256), toRlpHex(block.difficulty), toRlpHex(block.number), toRlpHex(block.gasLimit), toRlpHex(block.gasUsed), toRlpHex(block.timestamp), block.extraData, block.mixHash ?? "0x0000000000000000000000000000000000000000000000000000000000000000", block.nonce ?? "0x0000000000000000"];
+    // 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;
+    if (blockAny.requestsHash) {
+      headerFields.push(blockAny.requestsHash);
+    }
+    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"
+    }];
+    // 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, fromBlock, toBlock) {
+    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, fromBlock, toBlock) {
+    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) {
+    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)
+      }).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)
+      }).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"
+      }];
+      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
+      };
+    }).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) {
+    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"
+    }];
+    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)
+   */
+  padBeneficiaries(beneficiaries) {
+    if (beneficiaries.length > 4) {
+      throw new Error("Maximum 4 beneficiaries allowed");
+    }
+    const padded = [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 = (publicClient, predicate, options) => {
+  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);
+  });
+};
+//# sourceMappingURL=client.js.map