feat: fetch withdrawal proof to claim token withdrawal

Author: MicBun

.gitignore

@@ -21,4 +21,6 @@ out
 # env
 .env.*
 !.env.example
-*.env
+*.env
+
+CLAUDE.md

src/client/client.ts

@@ -321,6 +321,46 @@ export abstract class BaseTNClient<T extends EnvironmentType> {
     return action.listWalletRewards(chain, wallet, withPending);
   }
 
+  /**
+   * Gets withdrawal proof for a specific wallet address on a blockchain network
+   * Returns merkle proofs and validator signatures needed for withdrawal
+   *
+   * This method is used for non-custodial bridge withdrawals where users need to
+   * manually claim their withdrawals by submitting proofs to the destination chain.
+   * The proof includes validator signatures, merkle root, block hash, and amount.
+   *
+   * @param chain The chain identifier (e.g., "hoodi", "sepolia", etc.)
+   * @param walletAddress The wallet address to get withdrawal proof for
+   * @returns Promise that resolves to an array of withdrawal proof data
+   *
+   * @example
+   * ```typescript
+   * // Get withdrawal proofs for Hoodi
+   * const proofs = await client.getWithdrawalProof("hoodi", "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb");
+   *
+   * // Proofs will be an array like:
+   * // [{
+   * //   chain: "hoodi",
+   * //   chain_id: "3639",
+   * //   contract: "0x878D6aaeB6e746033f50B8dC268d54B4631554E7",
+   * //   created_at: 3080,
+   * //   recipient: "0x...",
+   * //   amount: "100000000000000000000",
+   * //   block_hash: <base64-encoded>,
+   * //   root: <base64-encoded>,
+   * //   proofs: [],
+   * //   signatures: [<base64-encoded-signatures>]
+   * // }]
+   * ```
+   *
+   * @note This method has been tested via integration tests in the node repository.
+   * See: /home/micbun/trufnetwork/kwil-db/node/exts/erc20-bridge/erc20/meta_extension_withdrawal_test.go
+   */
+  async getWithdrawalProof(chain: string, walletAddress: string): Promise<any[]> {
+    const action = this.loadAction();
+    return action.getWithdrawalProof(chain, walletAddress);
+  }
+
   /**
    * Gets taxonomies for specific streams in batch.
    * High-level wrapper for ComposedAction.getTaxonomiesForStreams()

src/contracts-api/action.ts

@@ -1080,4 +1080,45 @@ export class Action {
 
     return result.data?.result || [];
   }
+
+  /**
+   * Gets withdrawal proof for a wallet address on a blockchain network
+   * Returns merkle proofs and validator signatures needed for withdrawal on target chain
+   *
+   * This method is used for non-custodial bridge withdrawals where users need to
+   * manually claim their withdrawals by submitting proofs to the destination chain.
+   *
+   * @param chain The chain identifier (e.g., "hoodi", "sepolia", etc.)
+   * @param walletAddress The wallet address to get withdrawal proof for
+   * @returns Promise that resolves to array of withdrawal proofs
+   *
+   * @example
+   * ```typescript
+   * // Get withdrawal proofs for Hoodi
+   * const proofs = await action.getWithdrawalProof("hoodi", "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb");
+   * // Returns: [{ chain: "hoodi", recipient: "0x...", amount: "100000000000000000000", ... }]
+   * ```
+   *
+   * @note This method has been tested via integration tests in the node repository.
+   * See: /home/micbun/trufnetwork/kwil-db/node/exts/erc20-bridge/erc20/meta_extension_withdrawal_test.go
+   */
+  public async getWithdrawalProof(
+    chain: string,
+    walletAddress: string
+  ): Promise<any[]> {
+    const result = await this.call<any[]>(
+      `${chain}_get_withdrawal_proof`,
+      {
+        $wallet_address: walletAddress,
+      }
+    );
+
+    return result
+      .mapRight((rows) => {
+        // Return the array of withdrawal proofs
+        // May be empty if no unclaimed withdrawals
+        return rows || [];
+      })
+      .throw();
+  }
 }

src/internal.ts

@@ -76,5 +76,8 @@ export type {
   AttestationMetadata
 } from "./types/attestation";
 
+// Bridge types
+export type { WithdrawalProof } from "./types/bridge";
+
 // Visibility types
 export type { VisibilityEnum } from "./util/visibility";

src/types/bridge.ts

@@ -0,0 +1,77 @@
+/**
+ * Types for bridge-related operations
+ */
+
+/**
+ * Withdrawal proof returned from getWithdrawalProof()
+ *
+ * This proof contains all the data needed for a user to claim their withdrawal
+ * on the destination chain by submitting a transaction to the bridge contract.
+ *
+ * @example
+ * ```typescript
+ * const proofs = await client.getWithdrawalProof("hoodi", "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb");
+ * const proof = proofs[0];
+ *
+ * // Decode base64 data to use in smart contract call
+ * const blockHash = Buffer.from(proof.block_hash, 'base64').toString('hex');
+ * const root = Buffer.from(proof.root, 'base64').toString('hex');
+ * const signatures = proof.signatures.map(sig => Buffer.from(sig, 'base64'));
+ * ```
+ */
+export interface WithdrawalProof {
+  /**
+   * The chain identifier (e.g., "hoodi", "sepolia")
+   */
+  chain: string;
+
+  /**
+   * The numeric chain ID (e.g., "3639" for Hoodi)
+   */
+  chain_id: string;
+
+  /**
+   * The bridge contract address on the destination chain
+   */
+  contract: string;
+
+  /**
+   * The block number when the epoch was created
+   */
+  created_at: number;
+
+  /**
+   * The recipient wallet address
+   */
+  recipient: string;
+
+  /**
+   * The withdrawal amount in wei (as string to handle large numbers)
+   */
+  amount: string;
+
+  /**
+   * The Kwil block hash (base64-encoded bytes)
+   * Decode to bytes32 for smart contract call
+   */
+  block_hash: string;
+
+  /**
+   * The merkle root (base64-encoded bytes)
+   * Decode to bytes32 for smart contract call
+   */
+  root: string;
+
+  /**
+   * Array of merkle proofs (base64-encoded bytes)
+   * Usually empty for single withdrawals
+   */
+  proofs: string[];
+
+  /**
+   * Array of validator signatures (base64-encoded bytes)
+   * Each signature is 65 bytes: r[32] || s[32] || v[1]
+   * Decode and split into (v, r, s) for smart contract call
+   */
+  signatures: string[];
+}