feat: bridge different kind of token in a chain (#148)

Author: MicBun

docs/api-reference.md

@@ -910,6 +910,227 @@ parsed.result.forEach(row => {
 });
 ```
 
+## Bridge Operations
+
+The SDK provides methods for interacting with bridge instances on TN, enabling token transfers between TN and supported blockchain networks.
+
+### Understanding Bridge Identifiers
+
+Bridge instances on TN are identified by specific names that may differ from network names. For example:
+- Network `"sepolia"` → Bridge identifier `"sepolia"` (matches)
+- Network `"hoodi"` → Bridge identifier `"hoodi_tt"` (different due to multiple token support)
+
+Always use the **bridge identifier** when calling bridge methods, not the network name.
+
+### `client.getWalletBalance(bridgeIdentifier: string, walletAddress: string): Promise<string>`
+
+Gets the wallet balance for a specific bridge instance.
+
+#### Parameters
+- `bridgeIdentifier: string` - Bridge instance identifier (e.g., `"sepolia"`, `"hoodi_tt"`, `"ethereum"`)
+- `walletAddress: string` - Ethereum address to check balance for
+
+#### Returns
+- `Promise<string>` - Balance in wei as a string (to handle large numbers safely)
+
+#### Example
+```typescript
+// Simple case - identifier matches network name
+const sepoliaBalance = await client.getWalletBalance("sepolia", "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb");
+console.log(`Balance: ${sepoliaBalance} wei`);
+
+// Multi-token bridge - specify bridge instance explicitly
+const hoodiBalance = await client.getWalletBalance("hoodi_tt", "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb");
+
+// Convert wei to human-readable format
+import { formatEther } from 'ethers';
+const balanceInTokens = formatEther(hoodiBalance);
+console.log(`Balance: ${balanceInTokens} tokens`);
+```
+
+### `client.withdraw(bridgeIdentifier: string, amount: string, recipient: string): Promise<string>`
+
+Initiates a withdrawal by bridging tokens from TN to a destination chain. This is a convenience method that calls `bridgeTokens` and waits for transaction confirmation.
+
+#### Parameters
+- `bridgeIdentifier: string` - Bridge instance identifier (e.g., `"sepolia"`, `"hoodi_tt"`)
+- `amount: string` - Amount to withdraw in wei (as string to preserve precision)
+- `recipient: string` - Recipient address on the destination chain
+
+#### Returns
+- `Promise<string>` - Transaction hash of the withdrawal
+
+#### Example
+```typescript
+import { parseEther } from 'ethers';
+
+// Withdraw 100 tokens to Sepolia
+const amount = parseEther("100"); // Convert to wei
+const txHash = await client.withdraw("sepolia", amount.toString(), "0x742d35Cc...");
+
+console.log(`Withdrawal initiated: ${txHash}`);
+
+// For non-custodial bridges (like Hoodi), you must claim the withdrawal manually
+// See getWithdrawalProof() for claiming process
+```
+
+**Important Notes:**
+- **Non-custodial bridges** (Hoodi): You must manually claim withdrawals using `getWithdrawalProof()`
+- **Wait time**: Withdrawals become claimable after the epoch period (typically 10 minutes)
+
+### `client.getWithdrawalProof(bridgeIdentifier: string, walletAddress: string): Promise<WithdrawalProof[]>`
+
+Gets withdrawal proofs for claiming withdrawals on non-custodial bridges. Returns merkle proofs and validator signatures needed for submitting claims to the destination chain contract.
+
+#### Parameters
+- `bridgeIdentifier: string` - Bridge instance identifier (e.g., `"hoodi_tt"`)
+- `walletAddress: string` - Wallet address to get withdrawal proofs for
+
+#### Returns
+- `Promise<WithdrawalProof[]>` - Array of withdrawal proofs (empty array if no unclaimed withdrawals)
+
+#### WithdrawalProof Type
+```typescript
+interface WithdrawalProof {
+  chain: string;           // Source chain name (e.g., "hoodi")
+  chain_id: string;        // Numeric chain ID (e.g., "560048")
+  contract: string;        // Bridge contract address on destination chain
+  created_at: number;      // Block number when withdrawal was created
+  recipient: string;       // Recipient wallet address
+  amount: string;          // Withdrawal amount in wei
+  block_hash: string;      // Kwil block hash (base64-encoded)
+  root: string;            // Merkle root (base64-encoded)
+  proofs: string[];        // Merkle proofs (base64-encoded, usually empty)
+  signatures: string[];    // Validator signatures (base64-encoded, 65 bytes each)
+}
+```
+
+#### Example - Check for Claimable Withdrawals
+```typescript
+// Check for claimable withdrawals
+const proofs = await client.getWithdrawalProof("hoodi_tt", "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb");
+
+if (proofs.length === 0) {
+  console.log("No withdrawals ready to claim");
+} else {
+  console.log(`${proofs.length} withdrawal(s) ready to claim`);
+
+  for (const proof of proofs) {
+    console.log(`Amount: ${proof.amount} wei`);
+    console.log(`Recipient: ${proof.recipient}`);
+    console.log(`Contract: ${proof.contract}`);
+  }
+}
+```
+
+#### Example - Claim Withdrawal On-Chain
+```typescript
+import { Contract, ethers } from 'ethers';
+
+// 1. Get withdrawal proof from TN
+const proofs = await client.getWithdrawalProof("hoodi_tt", walletAddress);
+if (proofs.length === 0) {
+  throw new Error("No withdrawals to claim");
+}
+
+const proof = proofs[0];
+
+// 2. Decode base64 data for smart contract call
+const blockHash = Buffer.from(proof.block_hash, 'base64');
+const root = Buffer.from(proof.root, 'base64');
+const merkleProofs = proof.proofs.map(p => Buffer.from(p, 'base64'));
+
+// 3. Split signatures into v, r, s components
+const signatures = proof.signatures.map(sig => {
+  const sigBytes = Buffer.from(sig, 'base64');
+  return {
+    v: sigBytes[64],
+    r: '0x' + sigBytes.slice(0, 32).toString('hex'),
+    s: '0x' + sigBytes.slice(32, 64).toString('hex')
+  };
+});
+
+// 4. Call bridge contract to claim withdrawal
+const bridgeContract = new Contract(proof.contract, BRIDGE_ABI, signer);
+
+const tx = await bridgeContract.claimWithdrawal(
+  proof.recipient,
+  proof.amount,
+  '0x' + blockHash.toString('hex'),
+  '0x' + root.toString('hex'),
+  merkleProofs.map(p => '0x' + p.toString('hex')),
+  signatures.map(s => ({ v: s.v, r: s.r, s: s.s }))
+);
+
+await tx.wait();
+console.log(`Withdrawal claimed! Tx: ${tx.hash}`);
+```
+
+### `action.listWalletRewards(bridgeIdentifier: string, wallet: string, withPending: boolean): Promise<any[]>`
+
+Lists wallet rewards for a specific bridge instance. This is a low-level method that directly accesses the bridge extension namespace.
+
+**⚠️ Deprecated**: Most users should use `getWithdrawalProof()` instead, which provides a higher-level interface.
+
+#### Parameters
+- `bridgeIdentifier: string` - Bridge instance identifier
+- `wallet: string` - Wallet address to query
+- `withPending: boolean` - Whether to include pending (not yet finalized) rewards
+
+#### Returns
+- `Promise<any[]>` - Array of reward records
+
+#### Example
+```typescript
+const action = client.loadAction();
+const rewards = await action.listWalletRewards("hoodi_tt", walletAddress, true);
+console.log(`Found ${rewards.length} reward(s)`);
+```
+
+### Bridge Configuration Best Practices
+
+When integrating bridge functionality in your application:
+
+1. **Use bridge identifiers directly**:
+```typescript
+// Always use the exact bridge identifier
+const balance = await client.getWalletBalance('hoodi_tt', address);
+const sepoliaBalance = await client.getWalletBalance('sepolia', address);
+
+// For multiple Hoodi bridges
+const tt2Balance = await client.getWalletBalance('hoodi_tt2', address);
+```
+
+2. **Handle custodial vs non-custodial bridges differently**:
+```typescript
+const isCustodial = {
+  ethereum: true,  // Auto-claimed
+  sepolia: true,   // Auto-claimed
+  hoodi_tt: false, // Manual claim required
+};
+
+if (isCustodial[bridgeId]) {
+  console.log("Withdrawal will be automatically claimed");
+} else {
+  console.log("You must claim withdrawal manually using getWithdrawalProof()");
+}
+```
+
+3. **Poll for withdrawal proofs** on non-custodial bridges:
+```typescript
+async function waitForClaimableWithdrawal(bridgeId: string, address: string, maxAttempts = 60) {
+  for (let i = 0; i < maxAttempts; i++) {
+    const proofs = await client.getWithdrawalProof(bridgeId, address);
+    if (proofs.length > 0) {
+      return proofs[0];
+    }
+    // Wait 10 seconds before checking again
+    await new Promise(resolve => setTimeout(resolve, 10000));
+  }
+  throw new Error("Withdrawal not ready after 10 minutes");
+}
+```
+
 ## Performance Recommendations
 - Use batch record insertions
 - Implement client-side caching

src/client/client.ts

@@ -279,65 +279,73 @@ export abstract class BaseTNClient<T extends EnvironmentType> {
     return action.listMetadataByHeight(params);
   }
 
-  async getWalletBalance(chain: string, walletAddress: string) {
+  /**
+   * Gets the wallet balance for a specific bridge instance
+   * @param bridgeIdentifier The bridge instance identifier (e.g., "sepolia", "hoodi_tt", "ethereum")
+   * @param walletAddress The wallet address to check balance for
+   * @returns Promise that resolves to the balance as a string (in wei)
+   */
+  async getWalletBalance(bridgeIdentifier: string, walletAddress: string) {
     const action = this.loadAction();
-    return action.getWalletBalance(chain, walletAddress);
+    return action.getWalletBalance(bridgeIdentifier, walletAddress);
   }
 
   /**
-   * Performs a withdrawal operation by bridging tokens
-   * @param chain The chain identifier (e.g., "sepolia", "mainnet", "polygon", etc.)
-   * @param amount The amount to withdraw
+   * Performs a withdrawal operation by bridging tokens from TN to a destination chain
+   * @param bridgeIdentifier The bridge instance identifier (e.g., "sepolia", "hoodi_tt")
+   * @param amount The amount to withdraw (in wei)
+   * @param recipient The recipient address on the destination chain
    * @returns Promise that resolves to the transaction hash, or throws on error
    */
-  async withdraw(chain: string, amount: string, recipient: string): Promise<string> {
+  async withdraw(bridgeIdentifier: string, amount: string, recipient: string): Promise<string> {
     const action = this.loadAction();
-    
+
     // Bridge tokens in a single operation
-    const bridgeResult = await action.bridgeTokens(chain, amount, recipient);
+    const bridgeResult = await action.bridgeTokens(bridgeIdentifier, amount, recipient);
     if (!bridgeResult.data?.tx_hash) {
       throw new Error("Bridge tokens operation failed: no transaction hash returned");
     }
-    
+
     // Wait for bridge transaction to be mined - let waitForTx errors bubble up
     try {
       await this.waitForTx(bridgeResult.data.tx_hash);
     } catch (error) {
       throw new Error(`Bridge tokens transaction failed: ${error instanceof Error ? error.message : String(error)}`);
     }
-    
+
     // Return the transaction hash
     return bridgeResult.data.tx_hash;
   }
 
   /**
-   * Lists wallet rewards for a specific wallet address on a blockchain network
-   * @param chain The chain identifier (e.g., "sepolia", "mainnet", "polygon", etc.)
+   * Lists wallet rewards for a specific bridge instance
+   * @param bridgeIdentifier The bridge instance identifier (e.g., "sepolia", "hoodi_tt")
    * @param wallet The wallet address to list rewards for
    * @param withPending Whether to include pending rewards
    * @returns Promise that resolves to an array of rewards data
+   * @deprecated This method uses the extension namespace directly. Most users should use getWithdrawalProof instead.
    */
-  async listWalletRewards(chain: string, wallet: string, withPending: boolean): Promise<any[]> {
+  async listWalletRewards(bridgeIdentifier: string, wallet: string, withPending: boolean): Promise<any[]> {
     const action = this.loadAction();
-    return action.listWalletRewards(chain, wallet, withPending);
+    return action.listWalletRewards(bridgeIdentifier, wallet, withPending);
   }
 
   /**
-   * Gets withdrawal proof for a specific wallet address on a blockchain network
-   * Returns merkle proofs and validator signatures needed for withdrawal
+   * Gets withdrawal proof for a specific bridge instance
+   * Returns merkle proofs and validator signatures needed for claiming withdrawals on the destination 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.
+   * manually claim their withdrawals by submitting proofs to the destination chain contract.
    * The proof includes validator signatures, merkle root, block hash, and amount.
    *
-   * @param chain The chain identifier (e.g., "hoodi", "sepolia", etc.)
+   * @param bridgeIdentifier The bridge instance identifier (e.g., "hoodi_tt", "sepolia", "ethereum")
    * @param walletAddress The wallet address to get withdrawal proof for
-   * @returns Promise that resolves to an array of withdrawal proof data
+   * @returns Promise that resolves to an array of withdrawal proof data (empty array if no unclaimed withdrawals)
    *
    * @example
    * ```typescript
-   * // Get withdrawal proofs for Hoodi
-   * const proofs = await client.getWithdrawalProof("hoodi", "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb");
+   * // Get withdrawal proofs for Hoodi Test Token bridge
+   * const proofs = await client.getWithdrawalProof("hoodi_tt", "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb");
    *
    * // Proofs will be an array like:
    * // [{
@@ -352,14 +360,20 @@ export abstract class BaseTNClient<T extends EnvironmentType> {
    * //   proofs: [],
    * //   signatures: [<base64-encoded-signatures>]
    * // }]
+   *
+   * // Use the proofs to claim withdrawal on destination chain
+   * if (proofs.length > 0) {
+   *   const proof = proofs[0];
+   *   await bridgeContract.claimWithdrawal(proof.recipient, proof.amount, proof.root, proof.proofs, proof.signatures);
+   * }
    * ```
    *
    * @note This method has been tested via integration tests in the node repository.
    * See: https://github.com/trufnetwork/kwil-db/blob/main/node/exts/erc20-bridge/erc20/meta_extension_withdrawal_test.go
    */
-  async getWithdrawalProof(chain: string, walletAddress: string): Promise<WithdrawalProof[]> {
+  async getWithdrawalProof(bridgeIdentifier: string, walletAddress: string): Promise<WithdrawalProof[]> {
     const action = this.loadAction();
-    return action.getWithdrawalProof(chain, walletAddress);
+    return action.getWithdrawalProof(bridgeIdentifier, walletAddress);
   }
 
   /**