@unionlabs/payments 0.1.0 → 0.2.0

package/src/rpc.ts

@@ -0,0 +1,994 @@
+import {
+  type Address,
+  type Block,
+  bytesToHex,
+  createPublicClient,
+  encodeAbiParameters,
+  encodePacked,
+  type GetProofReturnType,
+  type Hash,
+  type Hex,
+  hexToBigInt,
+  hexToBytes,
+  http,
+  keccak256,
+  type PublicClient,
+  padHex,
+  sha256,
+  toHex,
+  toRlp,
+  type WalletClient,
+} from "viem";
+import { sign } from "viem/accounts";
+import type {
+  ConsensusState,
+  CounterpartyInfo,
+  DepositToZAssetResult,
+  LightClientData,
+  MptProofData,
+  ProofJSON,
+  RedeemParams,
+  RedemptionHistoryEntry,
+  UpdateLightClientResult,
+} from "./types.js";
+
+const ERC20_ABI = [
+  {
+    inputs: [{ name: "account", type: "address" }],
+    name: "balanceOf",
+    outputs: [{ name: "", type: "uint256" }],
+    stateMutability: "view",
+    type: "function",
+  },
+  {
+    inputs: [],
+    name: "decimals",
+    outputs: [{ name: "", type: "uint8" }],
+    stateMutability: "view",
+    type: "function",
+  },
+  {
+    inputs: [],
+    name: "symbol",
+    outputs: [{ name: "", type: "string" }],
+    stateMutability: "view",
+    type: "function",
+  },
+  {
+    inputs: [
+      { name: "spender", type: "address" },
+      { name: "amount", type: "uint256" },
+    ],
+    name: "approve",
+    outputs: [{ name: "", type: "bool" }],
+    stateMutability: "nonpayable",
+    type: "function",
+  },
+  {
+    inputs: [
+      { name: "to", type: "address" },
+      { name: "amount", type: "uint256" },
+    ],
+    name: "transfer",
+    outputs: [{ name: "", type: "bool" }],
+    stateMutability: "nonpayable",
+    type: "function",
+  },
+  {
+    inputs: [
+      { name: "from", type: "address" },
+      { name: "to", type: "address" },
+      { name: "amount", type: "uint256" },
+    ],
+    name: "transferFrom",
+    outputs: [{ name: "", type: "bool" }],
+    stateMutability: "nonpayable",
+    type: "function",
+  },
+] as const;
+
+export const IBC_STORE_ABI = [
+  {
+    inputs: [{ name: "clientId", type: "uint32" }],
+    name: "getClient",
+    outputs: [{ name: "", type: "address" }],
+    stateMutability: "view",
+    type: "function",
+  },
+] as const;
+
+const LIGHT_CLIENT_ABI = [
+  {
+    inputs: [{ name: "clientId", type: "uint32" }],
+    name: "getLatestHeight",
+    outputs: [{ name: "", type: "uint64" }],
+    stateMutability: "view",
+    type: "function",
+  },
+  {
+    inputs: [
+      { name: "clientId", type: "uint32" },
+      { name: "height", type: "uint64" },
+    ],
+    name: "getConsensusState",
+    outputs: [{ name: "", type: "bytes" }],
+    stateMutability: "view",
+    type: "function",
+  },
+] as const;
+
+const ZASSET_ABI = [
+  {
+    inputs: [{ name: "nullifier", type: "uint256" }],
+    name: "nullifierBalance",
+    outputs: [{ name: "", type: "uint256" }],
+    stateMutability: "view",
+    type: "function",
+  },
+  {
+    inputs: [{ name: "clientId", type: "uint32" }],
+    name: "counterparty",
+    outputs: [
+      {
+        components: [
+          { name: "tokenAddressKey", type: "bytes32" },
+          { name: "balanceSlot", type: "bytes32" },
+        ],
+        type: "tuple",
+      },
+    ],
+    stateMutability: "view",
+    type: "function",
+  },
+  {
+    inputs: [],
+    name: "ibcHandler",
+    outputs: [{ name: "", type: "address" }],
+    stateMutability: "view",
+    type: "function",
+  },
+  {
+    inputs: [{ name: "clientId", type: "uint32" }],
+    name: "stateRootIndex",
+    outputs: [{ name: "", type: "uint256" }],
+    stateMutability: "view",
+    type: "function",
+  },
+  {
+    inputs: [],
+    name: "underlying",
+    outputs: [{ name: "", type: "address" }],
+    stateMutability: "view",
+    type: "function",
+  },
+  {
+    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",
+  },
+  {
+    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: "redeem",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function",
+  },
+  {
+    anonymous: false,
+    inputs: [
+      { indexed: true, name: "from", type: "address" },
+      { indexed: true, name: "to", type: "address" },
+      { indexed: false, name: "value", type: "uint256" },
+    ],
+    name: "Transfer",
+    type: "event",
+  },
+  {
+    anonymous: false,
+    inputs: [
+      { indexed: true, name: "nullifier", type: "uint256" },
+      { indexed: true, name: "redeemAmount", type: "uint256" },
+      { indexed: true, name: "beneficiary", type: "address" },
+    ],
+    name: "Redeemed",
+    type: "event",
+  },
+] as const;
+
+const IBC_HANDLER_ABI = [
+  {
+    inputs: [
+      {
+        components: [
+          { name: "clientId", type: "uint32" },
+          { name: "clientMessage", type: "bytes" },
+          { name: "relayer", type: "address" },
+        ],
+        name: "msg_",
+        type: "tuple",
+      },
+    ],
+    name: "updateClient",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function",
+  },
+] as const;
+
+// @ts-expect-error
+const MULTICALL3_ADDRESS =
+  "0xcA11bde05977b3631167028862bE2a173976CA11" as Address;
+
+// @ts-expect-error
+const MULTICALL3_ABI = [
+  {
+    inputs: [
+      {
+        name: "calls",
+        type: "tuple[]",
+        components: [
+          { name: "target", type: "address" },
+          { name: "allowFailure", type: "bool" },
+          { name: "callData", type: "bytes" },
+        ],
+      },
+    ],
+    name: "aggregate3",
+    outputs: [
+      {
+        name: "returnData",
+        type: "tuple[]",
+        components: [
+          { name: "success", type: "bool" },
+          { name: "returnData", type: "bytes" },
+        ],
+      },
+    ],
+    stateMutability: "payable",
+    type: "function",
+  },
+] as const;
+
+/**
+ * @public
+ */
+export class RpcClient {
+  private client: PublicClient;
+
+  constructor(rpcUrl: string) {
+    this.client = createPublicClient({
+      transport: http(rpcUrl),
+    });
+  }
+
+  getClient(): PublicClient {
+    return this.client;
+  }
+
+  async getChainId(): Promise<bigint> {
+    return BigInt(await this.client.getChainId());
+  }
+
+  async getLatestBlockNumber(): Promise<bigint> {
+    return this.client.getBlockNumber();
+  }
+
+  async getBalance(
+    tokenAddress: Address,
+    accountAddress: Address,
+    blockNumber?: bigint,
+  ): Promise<bigint> {
+    return this.client.readContract({
+      address: tokenAddress,
+      abi: ERC20_ABI,
+      functionName: "balanceOf",
+      args: [accountAddress],
+      blockNumber,
+    });
+  }
+
+  async getDecimals(tokenAddress: Address): Promise<number> {
+    return this.client.readContract({
+      address: tokenAddress,
+      abi: ERC20_ABI,
+      functionName: "decimals",
+    });
+  }
+
+  async getSymbol(tokenAddress: Address): Promise<string> {
+    return this.client.readContract({
+      address: tokenAddress,
+      abi: ERC20_ABI,
+      functionName: "symbol",
+    });
+  }
+
+  async getLightClientAddress(
+    ibcStoreAddress: Address,
+    clientId: number,
+  ): Promise<Address> {
+    return this.client.readContract({
+      address: ibcStoreAddress,
+      abi: IBC_STORE_ABI,
+      functionName: "getClient",
+      args: [clientId],
+    });
+  }
+
+  async getLatestHeight(
+    lightClientAddress: Address,
+    clientId: number,
+  ): Promise<bigint> {
+    return this.client.readContract({
+      address: lightClientAddress,
+      abi: LIGHT_CLIENT_ABI,
+      functionName: "getLatestHeight",
+      args: [clientId],
+    });
+  }
+
+  /**
+   * Get consensus state, extracting the state root at the given byte index
+   */
+  async getConsensusState(
+    lightClientAddress: Address,
+    clientId: number,
+    height: bigint,
+    stateRootIndex: bigint,
+  ): Promise<ConsensusState> {
+    const consensusBytes = await this.client.readContract({
+      address: lightClientAddress,
+      abi: LIGHT_CLIENT_ABI,
+      functionName: "getConsensusState",
+      args: [clientId, height],
+    });
+
+    const bytes: Uint8Array = hexToBytes(consensusBytes);
+    const idx = Number(stateRootIndex);
+    const stateRoot = bytesToHex(bytes.slice(idx, idx + 32)) as Hash;
+
+    return { stateRoot };
+  }
+
+  async getNullifierBalance(
+    zassetAddress: Address,
+    nullifier: bigint,
+  ): Promise<bigint> {
+    return this.client.readContract({
+      address: zassetAddress,
+      abi: ZASSET_ABI,
+      functionName: "nullifierBalance",
+      args: [nullifier],
+    });
+  }
+
+  async getCounterparty(
+    zassetAddress: Address,
+    clientId: number,
+  ): Promise<CounterpartyInfo> {
+    const result = await this.client.readContract({
+      address: zassetAddress,
+      abi: ZASSET_ABI,
+      functionName: "counterparty",
+      args: [clientId],
+    });
+
+    return {
+      tokenAddressKey: result.tokenAddressKey as Hash,
+      balanceSlot: result.balanceSlot as Hash,
+    };
+  }
+
+  async getIbcHandlerAddress(zassetAddress: Address): Promise<Address> {
+    return this.client.readContract({
+      address: zassetAddress,
+      abi: ZASSET_ABI,
+      functionName: "ibcHandler",
+    });
+  }
+
+  async getStateRootIndex(
+    zassetAddress: Address,
+    clientId: number,
+  ): Promise<bigint> {
+    return this.client.readContract({
+      address: zassetAddress,
+      abi: ZASSET_ABI,
+      functionName: "stateRootIndex",
+      args: [clientId],
+    });
+  }
+
+  async getProof(
+    address: Address,
+    storageKeys: Hex[],
+    blockNumber: bigint,
+  ): Promise<GetProofReturnType> {
+    return this.client.getProof({
+      address,
+      storageKeys,
+      blockNumber,
+    });
+  }
+
+  async getBlock(blockNumber: bigint) {
+    return this.client.getBlock({ blockNumber });
+  }
+
+  /**
+   * Get redemption history for a nullifier by querying Redeemed events
+   */
+  async getRedemptionHistory(
+    zassetAddress: Address,
+    nullifier: bigint,
+    fromBlock?: bigint,
+    toBlock?: bigint,
+  ): Promise<RedemptionHistoryEntry[]> {
+    const logs = await this.client.getLogs({
+      address: zassetAddress,
+      event: {
+        type: "event",
+        name: "Redeemed",
+        inputs: [
+          { indexed: true, name: "nullifier", type: "uint256" },
+          { indexed: true, name: "redeemAmount", type: "uint256" },
+          { indexed: true, name: "beneficiary", type: "address" },
+        ],
+      },
+      args: {
+        nullifier,
+      },
+      fromBlock: fromBlock ?? "earliest",
+      toBlock: toBlock ?? "latest",
+    });
+
+    return logs.map((log) => ({
+      txHash: log.transactionHash as Hash,
+      blockNumber: log.blockNumber,
+      redeemAmount: log.args.redeemAmount as bigint,
+      beneficiary: log.args.beneficiary as Address,
+    }));
+  }
+}
+
+/**
+ * Compute the storage slot for an ERC20 balance mapping: keccak256(abi.encode(address, slot))
+ * @public
+ */
+export function computeStorageSlot(address: Address, mappingSlot: bigint): Hex {
+  const paddedAddress = padHex(address, { size: 32 });
+  const paddedSlot = padHex(toHex(mappingSlot), { size: 32 });
+  return keccak256(
+    encodePacked(["bytes32", "bytes32"], [paddedAddress, paddedSlot]),
+  );
+}
+
+/**
+ * @public
+ */
+export async function fetchLightClients(
+  dstClient: RpcClient,
+  zassetAddress: Address,
+  clientIds: number[],
+): Promise<LightClientData[]> {
+  const ibcHandlerAddress = await dstClient.getIbcHandlerAddress(zassetAddress);
+  const results: LightClientData[] = [];
+
+  for (const clientId of clientIds) {
+    try {
+      const lightClientAddress = await dstClient.getLightClientAddress(
+        ibcHandlerAddress,
+        clientId,
+      );
+      const height = await dstClient.getLatestHeight(
+        lightClientAddress,
+        clientId,
+      );
+      const stateRootIndex = await dstClient.getStateRootIndex(
+        zassetAddress,
+        clientId,
+      );
+      const { stateRoot } = await dstClient.getConsensusState(
+        lightClientAddress,
+        clientId,
+        height,
+        stateRootIndex,
+      );
+
+      results.push({ clientId, height, stateRoot });
+    } catch {}
+  }
+
+  return results;
+}
+
+/**
+ * @public
+ */
+export async function fetchMptProof(
+  srcClient: RpcClient,
+  tokenAddress: Address,
+  storageSlot: Hex,
+  blockNumber: bigint,
+): Promise<MptProofData> {
+  const proof = await srcClient.getProof(
+    tokenAddress,
+    [storageSlot],
+    blockNumber,
+  );
+
+  let storageProof: Hex[] = [];
+  let storageValue: Hex = "0x0";
+
+  if (proof.storageProof.length > 0 && proof.storageProof[0]) {
+    storageProof = proof.storageProof[0].proof as Hex[];
+    storageValue = toHex(proof.storageProof[0].value);
+  }
+
+  return {
+    accountProof: proof.accountProof as Hex[],
+    storageProof,
+    storageValue,
+    storageRoot: proof.storageHash,
+  };
+}
+
+/**
+ * Deterministically shuffle light clients using the secret as seed.
+ * Same secret always produces the same ordering for privacy.
+ * @public
+ */
+export function deterministicShuffleClients(
+  clients: LightClientData[],
+  secret: Hex,
+): LightClientData[] {
+  if (clients.length <= 1) {
+    return [...clients];
+  }
+
+  // Seed = SHA256(secret || clientHeights as big-endian uint64s)
+  const secretBytes = hexToBytes(secret);
+  const heightsBytes = new Uint8Array(clients.length * 8);
+  for (let i = 0; i < clients.length; i++) {
+    const view = new DataView(heightsBytes.buffer, i * 8, 8);
+    view.setBigUint64(0, clients[i]!.height, false);
+  }
+
+  const combined = new Uint8Array(secretBytes.length + heightsBytes.length);
+  combined.set(secretBytes, 0);
+  combined.set(heightsBytes, secretBytes.length);
+  const seedHex = sha256(combined);
+  const seed = hexToBytes(seedHex);
+
+  // Fisher-Yates shuffle with deterministic PRNG
+  const shuffled = [...clients];
+  let seedIndex = 0;
+  for (let i = shuffled.length - 1; i > 0; i--) {
+    const randomByte = seed[seedIndex % seed.length]!;
+    seedIndex++;
+    const j = randomByte % (i + 1);
+    [shuffled[i], shuffled[j]] = [shuffled[j]!, shuffled[i]!];
+  }
+
+  return shuffled;
+}
+
+/**
+ * Sign an attested message with raw ECDSA (no EIP-191 prefix).
+ * Matches Go CLI's crypto.Sign behavior for SignatureCheckerLib verification.
+ * @public
+ */
+export async function signAttestedMessage(
+  message: Hex,
+  privateKey: Hex,
+): Promise<Hex> {
+  const messageBytes = hexToBytes(message);
+  if (messageBytes.length !== 32) {
+    throw new Error(
+      `Invalid message length: expected 32 bytes, got ${messageBytes.length}`,
+    );
+  }
+
+  const signature = await sign({
+    hash: message,
+    privateKey,
+    to: "hex",
+  });
+
+  return signature;
+}
+
+/**
+ * @public
+ */
+export function parseProofJson(proofJsonBytes: Uint8Array): ProofJSON {
+  const jsonStr = new TextDecoder().decode(proofJsonBytes);
+  const raw = JSON.parse(jsonStr);
+  const commitments = raw.commitments ?? ["0x0", "0x0"];
+
+  return {
+    proof: raw.proof as ProofJSON["proof"],
+    commitments: commitments as ProofJSON["commitments"],
+    commitmentPok: raw.commitmentPok as ProofJSON["commitmentPok"],
+    publicInputs: raw.publicInputs ?? [],
+  };
+}
+
+/**
+ * Client-side metadata for redeem (NOT from prover)
+ * @public
+ */
+export interface RedeemMetadata {
+  lightClients: LightClientData[];
+  nullifier: bigint;
+  value: bigint;
+  beneficiary: Address;
+  attestedMessage: Hex;
+  signature: Hex;
+}
+
+/**
+ * @public
+ */
+export function proofJsonToRedeemParams(
+  proofJson: ProofJSON,
+  metadata: RedeemMetadata,
+): RedeemParams {
+  const parseBigInt = (s: string): bigint => {
+    if (s.startsWith("0x")) {
+      return hexToBigInt(s as Hex);
+    }
+    return BigInt(s);
+  };
+
+  return {
+    proof: proofJson.proof.map(parseBigInt) as RedeemParams["proof"],
+    commitments: proofJson.commitments.map(
+      parseBigInt,
+    ) as RedeemParams["commitments"],
+    commitmentPok: proofJson.commitmentPok.map(
+      parseBigInt,
+    ) as RedeemParams["commitmentPok"],
+    lightClients: metadata.lightClients.map((lc) => ({
+      clientId: lc.clientId,
+      height: lc.height,
+    })),
+    nullifier: metadata.nullifier,
+    value: metadata.value,
+    beneficiary: metadata.beneficiary,
+    attestedMessage: metadata.attestedMessage,
+    signature: metadata.signature,
+  };
+}
+
+/**
+ * @public
+ */
+export async function submitRedeem(
+  zassetAddress: Address,
+  params: RedeemParams,
+  walletClient: WalletClient,
+): Promise<Hash> {
+  if (!walletClient.account) {
+    throw new Error("WalletClient must have an account");
+  }
+  if (!walletClient.chain) {
+    throw new Error("WalletClient must have a chain configured");
+  }
+
+  const hash = await walletClient
+    .writeContractSync({
+      address: zassetAddress,
+      abi: ZASSET_ABI,
+      functionName: "redeem",
+      args: [
+        params.proof,
+        params.commitments,
+        params.commitmentPok,
+        params.lightClients,
+        params.nullifier,
+        params.value,
+        params.beneficiary,
+        params.attestedMessage,
+        params.signature,
+      ],
+      chain: walletClient.chain,
+      account: walletClient.account,
+    })
+    .then((x) => x.transactionHash);
+
+  return hash;
+}
+
+/**
+ * RLP encode an EVM block header for the loopback light client.
+ * The header fields must be in the exact order expected by the EVM.
+ * Verifies the encoding by checking that keccak256(rlp) == block.hash
+ */
+function rlpEncodeBlockHeader(block: Block): Hex {
+  // Helper to convert bigint/number to minimal RLP hex encoding
+  // RLP requires no leading zeros, and 0 is encoded as empty string (0x80)
+  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);
+    // Ensure even length for proper byte encoding
+    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 (EIP-1559, EIP-4895, EIP-4844, EIP-4788, EIP-7685)
+  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);
+  }
+  // EIP-7685 requestsHash (Pectra upgrade) - not yet in viem types
+  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}. ` +
+        `Block number: ${block.number}, fields count: ${headerFields.length}`,
+    );
+  }
+
+  return rlpEncoded;
+}
+
+/**
+ * Update a loopback light client to a specific block height.
+ * The loopback client operates on the same chain, so only one RPC URL is needed.
+ *
+ * @param rpcUrl - RPC URL for the chain (same chain for fetching block and submitting tx)
+ * @param ibcHandlerAddress - Address of the IBCHandler contract
+ * @param clientId - The light client ID to update
+ * @param height - Block height to update to (bigint or 'latest')
+ * @param walletClient - viem WalletClient with account and chain configured
+ * @returns Transaction hash, block number, state root, and chain ID
+ * @public
+ */
+export async function updateLoopbackClient(
+  rpcUrl: string,
+  ibcHandlerAddress: Address,
+  clientId: number,
+  height: bigint | "latest",
+  walletClient: WalletClient,
+): Promise<UpdateLightClientResult> {
+  if (!walletClient.account) {
+    throw new Error("WalletClient must have an account");
+  }
+  if (!walletClient.chain) {
+    throw new Error("WalletClient must have a chain configured");
+  }
+
+  // Create public client
+  const publicClient = createPublicClient({
+    transport: http(rpcUrl),
+  });
+
+  // Get chain ID from RPC
+  const chainId = await publicClient.getChainId();
+
+  // 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");
+  }
+
+  // RLP encode the block header and verify the hash matches
+  const rlpEncodedHeader = rlpEncodeBlockHeader(block);
+
+  // Encode the Header struct: (uint64 height, bytes encodedHeader)
+  const clientMessage = encodeAbiParameters(
+    [
+      { type: "uint64", name: "height" },
+      { type: "bytes", name: "encodedHeader" },
+    ],
+    [block.number, rlpEncodedHeader],
+  );
+
+  // 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();
+  }
+
+  // Submit the transaction
+  const txHash = await walletClient
+    .writeContractSync({
+      address: ibcHandlerAddress,
+      abi: IBC_HANDLER_ABI,
+      functionName: "updateClient",
+      args: [
+        {
+          clientId,
+          clientMessage,
+          relayer: walletClient.account.address,
+        },
+      ],
+      chain: walletClient.chain,
+      account: walletClient.account,
+    })
+    .then((x) => x.transactionHash);
+
+  return {
+    txHash,
+    blockNumber: block.number,
+    stateRoot: block.stateRoot,
+    chainId: BigInt(chainId),
+  };
+}
+
+/**
+ * Deposit underlying tokens to ZAsset and transfer to a deposit address.
+ * Executes 3 transactions: approve → deposit → transfer.
+ *
+ * @param rpcUrl - RPC URL for the chain
+ * @param zAssetAddress - Address of the ZAsset contract
+ * @param depositAddress - Address to receive the ZAsset tokens (derived from secret)
+ * @param amount - Amount to deposit (in underlying token's smallest unit)
+ * @param walletClient - viem WalletClient with account and chain configured
+ * @returns Transaction hash of the final transfer, underlying token address, and chain ID
+ * @public
+ */
+export async function depositToZAsset(
+  rpcUrl: string,
+  zAssetAddress: Address,
+  depositAddress: Address,
+  amount: bigint,
+  walletClient: WalletClient,
+): Promise<DepositToZAssetResult> {
+  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({
+    transport: http(rpcUrl),
+  });
+
+  const chainId = await publicClient.getChainId();
+
+  // Get underlying token address
+  const underlyingToken = (await publicClient.readContract({
+    address: zAssetAddress,
+    abi: ZASSET_ABI,
+    functionName: "underlying",
+  })) as Address;
+
+  if (underlyingToken === "0x0000000000000000000000000000000000000000") {
+    throw new Error(
+      "ZAsset is not a wrapped token (underlying is zero address)",
+    );
+  }
+
+  // 1. Approve ZAsset to spend underlying tokens
+  const approveReceipt = await walletClient.writeContractSync({
+    address: underlyingToken,
+    abi: ERC20_ABI,
+    functionName: "approve",
+    args: [zAssetAddress, amount],
+    chain: walletClient.chain,
+    account: walletClient.account,
+  });
+  if (approveReceipt.status === "reverted") {
+    throw new Error(
+      `Approve transaction reverted: ${approveReceipt.transactionHash}`,
+    );
+  }
+
+  // 2. Deposit underlying to get ZAsset
+  const depositReceipt = await walletClient.writeContractSync({
+    address: zAssetAddress,
+    abi: ZASSET_ABI,
+    functionName: "deposit",
+    args: [amount],
+    chain: walletClient.chain,
+    account: walletClient.account,
+  });
+  if (depositReceipt.status === "reverted") {
+    throw new Error(
+      `Deposit transaction reverted: ${depositReceipt.transactionHash}`,
+    );
+  }
+
+  // 3. Transfer ZAsset to deposit address
+  const transferReceipt = await walletClient.writeContractSync({
+    address: zAssetAddress,
+    abi: ZASSET_ABI,
+    functionName: "transfer",
+    args: [depositAddress, amount],
+    chain: walletClient.chain,
+    account: walletClient.account,
+  });
+  if (transferReceipt.status === "reverted") {
+    throw new Error(
+      `Transfer transaction reverted: ${transferReceipt.transactionHash}`,
+    );
+  }
+
+  return {
+    txHash: transferReceipt.transactionHash,
+    underlyingToken,
+    chainId: BigInt(chainId),
+  };
+}