@tapforce/pod-bridge-sdk 1.1.8 → 1.1.10

package/README.md

@@ -1,6 +1,6 @@
 # Pod Bridge SDK
 
-TypeScript SDK for interacting with the Pod Bridge - enabling cross-chain token transfers between POD and other EVM chains (e.g., Sepolia).
+TypeScript SDK for interacting with Bridges between POD and other chains - enabling cross-chain token transfers between POD and other EVM chains (e.g., Sepolia).
 
 ## Features
 
@@ -34,8 +34,8 @@ pnpm add @tapforce/pod-bridge-sdk
 
 ```typescript
 import { 
-  BridgedToPodActionClient,
-  PodToBridgedActionClient,
+  SourceChainToPodActionClient,
+  PodToSourceChainActionClient,
   PodBridgeTrackerClient,
   PodBridgeConfig 
 } from '@tapforce/pod-bridge-sdk';
@@ -47,13 +47,13 @@ Create a configuration object with source and destination chain details:
 
 ```typescript
 const config: PodBridgeConfig = {
-  bridged: {
+  sourceChain: {
     rpcUrl: 'https://sepolia.infura.io/v3/YOUR_KEY',
     contractAddress: '0x...', // Source chain bridge contract
     deploymentBlock: 9502541  // Optional: Start indexing from deployment block (avoids querying empty blocks)
   },
   pod: {
-    rpcUrl: 'https://pod-rpc.example.com',
+    rpcUrl: 'https://rpc.v1.dev.pod.network',
     contractAddress: '0x...', // Destination chain bridge contract
     deploymentBlock: 0        // Optional: POD deployment block
   }
@@ -66,30 +66,30 @@ const config: PodBridgeConfig = {
 
 The SDK provides two action clients for different bridge directions:
 
-- **`BridgedToPodActionClient`**: For Bridged → POD transfers (e.g., Sepolia → POD)
-- **`PodToBridgedActionClient`**: For POD → Bridged transfers (e.g., POD → Sepolia)
+- **`SourceChainToPodActionClient`**: For Source Chain → POD transfers (e.g., Sepolia → POD)
+- **`PodToSourceChainActionClient`**: For POD → Source Chain transfers (e.g., POD → Sepolia)
 
 #### Configuration for Action Clients
 
 ```typescript
 const actionConfig = {
-  bridged: {
-    contractAddress: '0x...' // Bridged chain bridge contract (e.g., Sepolia)
+  sourceChain: {
+    contractAddress: '0x...' // Source chain bridge contract (e.g., Sepolia)
   },
   pod: {
     contractAddress: '0x...' // POD chain bridge contract
   }
 };
 
-const bridgedToPodClient = new BridgedToPodActionClient(actionConfig);
-const podToBridgedClient = new PodToBridgedActionClient(actionConfig);
+const sourceChainToPodClient = new SourceChainToPodActionClient(actionConfig);
+const podToSourceChainClient = new PodToSourceChainActionClient(actionConfig);
 ```
 
-#### Deposit from Bridged Chain (e.g., Sepolia → POD)
+#### Deposit from Source Chain (e.g., Sepolia → POD)
 
 ```typescript
-// Create unsigned transaction for ERC20 deposit on Bridged chain
-const unsignedTx = bridgedToPodClient.depositToken({
+// Create unsigned transaction for ERC20 deposit on Source chain
+const unsignedTx = sourceChainToPodClient.depositToken({
   token: '0x...', // ERC20 token address
   amount: '1000000000000000000', // Amount in wei (1 token with 18 decimals)
   destinationWalletAddress: '0x...', // Recipient address on POD
@@ -97,7 +97,7 @@ const unsignedTx = bridgedToPodClient.depositToken({
 });
 
 // Deposit native tokens
-const unsignedNativeTx = bridgedToPodClient.depositNative({
+const unsignedNativeTx = sourceChainToPodClient.depositNative({
   amount: '1000000000000000000', // Amount in wei (1 ETH)
   destinationWalletAddress: '0x...', // Recipient address on POD
   from: '0x...' // Optional: sender address
@@ -107,13 +107,13 @@ const unsignedNativeTx = bridgedToPodClient.depositNative({
 // const tx = await signer.sendTransaction(unsignedTx);
 ```
 
-#### Claim on POD from Bridged Chain Deposits
+#### Claim on POD from Source Chain Deposits
 
-For claiming on POD from Bridged chain deposits, use block number-based claims:
+For claiming on POD from Source chain deposits, use block number-based claims:
 
 ```typescript
 // Create unsigned claim transaction for ERC20 on POD
-const unsignedTx = bridgedToPodClient.claimWithBlockNumber({
+const unsignedTx = sourceChainToPodClient.claimWithBlockNumber({
   id: '123', // Request ID from deposit event
   token: '0x...', // Token address on source chain
   blockNumber: 12345678, // Block number of deposit on source chain
@@ -121,49 +121,49 @@ const unsignedTx = bridgedToPodClient.claimWithBlockNumber({
 });
 
 // For native tokens
-const unsignedNativeTx = bridgedToPodClient.claimNativeWithBlockNumber({
+const unsignedNativeTx = sourceChainToPodClient.claimNativeWithBlockNumber({
   id: '123',
   blockNumber: 12345678,
   from: '0x...'
 });
 ```
 
-#### Deposit from POD (POD → Bridged Chain)
+#### Deposit from POD (POD → Source Chain)
 
 ```typescript
 // Create unsigned transaction for ERC20 deposit on POD
-const unsignedTx = podToBridgedClient.depositToken({
+const unsignedTx = podToSourceChainClient.depositToken({
   token: '0x...', // ERC20 token address
   amount: '1000000000000000000', // Amount in wei
-  destinationWalletAddress: '0x...', // Recipient address on Bridged chain
+  destinationWalletAddress: '0x...', // Recipient address on Source chain
   from: '0x...' // Optional: sender address
 });
 
 // Deposit native tokens
-const unsignedNativeTx = podToBridgedClient.depositNative({
+const unsignedNativeTx = podToSourceChainClient.depositNative({
   amount: '1000000000000000000',
   destinationWalletAddress: '0x...',
   from: '0x...'
 });
 ```
 
-#### Claim on Bridged Chain from POD Deposits
+#### Claim on Source Chain from POD Deposits
 
-For claiming on Bridged chain from POD deposits, use certificate-based claims. First, get the certified log from the POD deposit transaction:
+For claiming on Source chain from POD deposits, use certificate-based claims. First, get the certified log from the POD deposit transaction:
 
 ```typescript
 // Get certified log from POD deposit transaction
 const depositTxHash = '0x...'; // Transaction hash of deposit on POD
 const certifiedLog = await trackerClient.getDepositCertifiedLog(depositTxHash);
 
-// Create unsigned claim transaction for ERC20 on Bridged chain
-const unsignedTx = podToBridgedClient.claimWithCertificate({
+// Create unsigned claim transaction for ERC20 on Source chain
+const unsignedTx = podToSourceChainClient.claimWithCertificate({
   certifiedLog,
   from: '0x...' // Optional: claimer address
 });
 
 // For native tokens
-const unsignedNativeTx = podToBridgedClient.claimNativeWithCertificate({
+const unsignedNativeTx = podToSourceChainClient.claimNativeWithCertificate({
   certifiedLog,
   from: '0x...'
 });
@@ -188,13 +188,16 @@ const deposits = await trackerClient.getDepositsSentBy(
 
 deposits.forEach(deposit => {
   console.log(`Request ID: ${deposit.requestId}`);
-  console.log(`From: ${deposit.from} -> To: ${deposit.to}`);
-  console.log(`Token: ${deposit.token}`);
-  console.log(`Amount: ${deposit.amount}`);
+  console.log(`Deposit Chain: ${deposit.deposit.chain}`);
+  console.log(`From: ${deposit.deposit.from} -> To: ${deposit.deposit.to}`);
+  console.log(`Token: ${deposit.deposit.token}`);
+  console.log(`Amount: ${deposit.deposit.amount}`);
+  console.log(`Block: ${deposit.deposit.blockNumber}, Time: ${deposit.deposit.timestamp}`);
   console.log(`Claimed: ${deposit.isClaimed}`);
-  if (deposit.isClaimed) {
-    console.log(`Claimed by: ${deposit.claimedBy}`);
-    console.log(`Claimed tx: ${deposit.claimedTxHash}`);
+  if (deposit.isClaimed && deposit.claim) {
+    console.log(`Claim Chain: ${deposit.claim.chain}`);
+    console.log(`Claimed by: ${deposit.claim.claimer}`);
+    console.log(`Claimed tx: ${deposit.claim.txHash}`);
   }
 });
 ```
@@ -250,25 +253,25 @@ processedStatuses.forEach((isProcessed, index) => {
 
 ## API Reference
 
-### BridgedToPodActionClient
+### SourceChainToPodActionClient
 
-Handles transactions for Bridged → POD direction.
+Handles transactions for Source Chain → POD direction.
 
 #### Constructor
 
 ```typescript
-new BridgedToPodActionClient(config: PodBridgeActionsClientConfig)
+new SourceChainToPodActionClient(config: PodBridgeActionsClientConfig)
 ```
 
 #### Methods
 
-- **`depositToken(args)`**: Create unsigned transaction for ERC20 deposit on Bridged chain
+- **`depositToken(args)`**: Create unsigned transaction for ERC20 deposit on Source chain
   - `token`: Token address
   - `amount`: Amount in wei (string | bigint)
   - `destinationWalletAddress`: Recipient address on POD
   - `from?`: Optional sender address
 
-- **`depositNative(args)`**: Create unsigned transaction for native token deposit on Bridged chain
+- **`depositNative(args)`**: Create unsigned transaction for native token deposit on Source chain
   - `amount`: Amount in wei (string | bigint)
   - `destinationWalletAddress`: Recipient address on POD
   - `from?`: Optional sender address
@@ -276,22 +279,22 @@ new BridgedToPodActionClient(config: PodBridgeActionsClientConfig)
 - **`claimWithBlockNumber(args)`**: Create unsigned transaction for claiming on POD with block number
   - `id`: Request ID
   - `token`: Token address
-  - `blockNumber`: Block number of deposit on Bridged chain
+  - `blockNumber`: Block number of deposit on Source chain
   - `from?`: Optional claimer address
 
 - **`claimNativeWithBlockNumber(args)`**: Create unsigned transaction for claiming native tokens on POD with block number
   - `id`: Request ID
-  - `blockNumber`: Block number of deposit on Bridged chain
+  - `blockNumber`: Block number of deposit on Source chain
   - `from?`: Optional claimer address
 
-### PodToBridgedActionClient
+### PodToSourceChainActionClient
 
-Handles transactions for POD → Bridged direction.
+Handles transactions for POD → Source Chain direction.
 
 #### Constructor
 
 ```typescript
-new PodToBridgedActionClient(config: PodBridgeActionsClientConfig)
+new PodToSourceChainActionClient(config: PodBridgeActionsClientConfig)
 ```
 
 #### Methods
@@ -299,19 +302,19 @@ new PodToBridgedActionClient(config: PodBridgeActionsClientConfig)
 - **`depositToken(args)`**: Create unsigned transaction for ERC20 deposit on POD
   - `token`: Token address
   - `amount`: Amount in wei (string | bigint)
-  - `destinationWalletAddress`: Recipient address on Bridged chain
+  - `destinationWalletAddress`: Recipient address on Source chain
   - `from?`: Optional sender address
 
 - **`depositNative(args)`**: Create unsigned transaction for native token deposit on POD
   - `amount`: Amount in wei (string | bigint)
-  - `destinationWalletAddress`: Recipient address on Bridged chain
+  - `destinationWalletAddress`: Recipient address on Source chain
   - `from?`: Optional sender address
 
-- **`claimWithCertificate(args)`**: Create unsigned transaction for claiming on Bridged chain with certificate
+- **`claimWithCertificate(args)`**: Create unsigned transaction for claiming on Source chain with certificate
   - `certifiedLog`: Certified log from POD certificate system
   - `from?`: Optional claimer address
 
-- **`claimNativeWithCertificate(args)`**: Create unsigned transaction for claiming native tokens on Bridged chain with certificate
+- **`claimNativeWithCertificate(args)`**: Create unsigned transaction for claiming native tokens on Source chain with certificate
   - `certifiedLog`: Certified log from POD certificate system
   - `from?`: Optional claimer address
 
@@ -334,7 +337,7 @@ new PodToBridgedActionClient(config: PodBridgeActionsClientConfig)
 - **`areRequestsProcessed(deposits)`**: Batch check if requests are processed
   - Returns: `Promise<boolean[]>`
 
-- **`getDepositCertifiedLog(txHash)`**: Get certified log for claiming on Sepolia from POD deposit
+- **`getDepositCertifiedLog(txHash)`**: Get certified log for claiming on Source chain from POD deposit
   - `txHash`: Transaction hash of deposit on POD
   - Returns: `Promise<CertifiedLog>` with attestations and merkle proof
 
@@ -343,19 +346,40 @@ new PodToBridgedActionClient(config: PodBridgeActionsClientConfig)
 ### BridgeRequest
 
 ```typescript
+enum BridgeChain {
+  SOURCE_CHAIN = 'sourceChain',
+  POD = 'pod'
+}
+
 interface BridgeRequest {
   requestId: string;
-  blockNumber: number;
-  timestamp: number;
-  txHash: string;
-  from: string;
-  to: string;
-  token: string; // Token address or ZeroAddress for native
-  amount: string; // Amount in wei
+  
+  // Deposit information
+  deposit: {
+    chain: BridgeChain;        // Which chain the deposit occurred on
+    txHash: string;
+    from: string;              // Sender address
+    to: string;                // Recipient address on destination chain
+    token: string;             // Token address (or 0x0 for native)
+    amount: string;            // Amount in wei
+    chainId: number;
+    blockNumber: number;       // Block number (for POD, this is essentially a timestamp)
+    timestamp: number;         // Unix timestamp
+  };
+  
+  // Claim information (optional, only if claimed)
+  claim?: {
+    chain: BridgeChain;        // Which chain the claim occurred on
+    txHash: string;
+    claimer: string;           // Address that claimed
+    chainId: number;
+    blockNumber: number;       // Block number (for POD, this is essentially a timestamp)
+    timestamp: number;         // Unix timestamp
+  };
+  
+  // Status
   isClaimed: boolean;
-  claimedTxHash?: string;
-  claimedAt?: number;
-  claimedBy?: string;
+  isClaimable: boolean;        // Can be claimed (finalized and not yet claimed)
 }
 ```
 
@@ -401,12 +425,12 @@ interface CertifiedLog {
 The SDK supports two bridge implementations:
 
 1. **BridgeDepositWithdraw** (Certificate-based)
-   - Used for claiming on Sepolia from POD deposits
+   - Used for claiming on Source chain from POD deposits
    - Requires certified logs from POD's certificate system
    - Methods: `claimWithCertificate`, `claimNativeWithCertificate`
 
 2. **BridgeMintBurn** (Precompile-based)
-   - Used for claiming on POD from Sepolia deposits
+   - Used for claiming on POD from Source chain deposits
    - Uses block number verification via precompiles
    - Methods: `claimWithBlockNumber`, `claimNativeWithBlockNumber`
 
@@ -416,11 +440,11 @@ The SDK supports two bridge implementations:
 
 ```typescript
 import { ethers } from 'ethers';
-import { BridgedToPodActionClient, PodBridgeTrackerClient } from '@tapforce/pod-bridge-sdk';
+import { SourceChainToPodActionClient, PodBridgeTrackerClient } from '@tapforce/pod-bridge-sdk';
 
 // Setup
 const trackerConfig = {
-  bridged: {
+  sourceChain: {
     rpcUrl: 'https://sepolia.infura.io/v3/YOUR_KEY',
     contractAddress: '0xSepoliaBridgeContract'
   },
@@ -431,13 +455,13 @@ const trackerConfig = {
 };
 
 const actionConfig = {
-  bridged: { contractAddress: '0xSepoliaBridgeContract' },
+  sourceChain: { contractAddress: '0xSepoliaBridgeContract' },
   pod: { contractAddress: '0xPodBridgeContract' }
 };
 
-const actionClient = new BridgedToPodActionClient(actionConfig);
+const actionClient = new SourceChainToPodActionClient(actionConfig);
 const trackerClient = new PodBridgeTrackerClient(trackerConfig);
-const sepoliaProvider = new ethers.JsonRpcProvider(trackerConfig.bridged.rpcUrl);
+const sepoliaProvider = new ethers.JsonRpcProvider(trackerConfig.sourceChain.rpcUrl);
 const sepoliaSigner = new ethers.Wallet('PRIVATE_KEY', sepoliaProvider);
 
 // Step 1: Deposit tokens on Sepolia
@@ -456,15 +480,15 @@ const deposits = await trackerClient.getDepositsSentBy(await sepoliaSigner.getAd
 const latestDeposit = deposits[0];
 
 console.log(`Request ID: ${latestDeposit.requestId}`);
-console.log(`Amount: ${ethers.formatEther(latestDeposit.amount)}`);
+console.log(`Amount: ${ethers.formatEther(latestDeposit.deposit.amount)}`);
 
 // Step 3: Wait for finality and claim on POD
 const canClaim = await trackerClient.canBeClaimed(latestDeposit);
 if (canClaim) {
   const claimTx = actionClient.claimWithBlockNumber({
     id: latestDeposit.requestId,
-    token: latestDeposit.token,
-    blockNumber: latestDeposit.blockNumber
+    token: latestDeposit.deposit.token,
+    blockNumber: latestDeposit.deposit.blockNumber
   });
   
   // Submit claim on POD
@@ -480,11 +504,11 @@ if (canClaim) {
 
 ```typescript
 import { ethers } from 'ethers';
-import { PodToBridgedActionClient, PodBridgeTrackerClient } from '@tapforce/pod-bridge-sdk';
+import { PodToSourceChainActionClient, PodBridgeTrackerClient } from '@tapforce/pod-bridge-sdk';
 
 // Setup
 const trackerConfig = {
-  bridged: {
+  sourceChain: {
     rpcUrl: 'https://sepolia.infura.io/v3/YOUR_KEY',
     contractAddress: '0xSepoliaBridgeContract'
   },
@@ -495,11 +519,11 @@ const trackerConfig = {
 };
 
 const actionConfig = {
-  bridged: { contractAddress: '0xSepoliaBridgeContract' },
+  sourceChain: { contractAddress: '0xSepoliaBridgeContract' },
   pod: { contractAddress: '0xPodBridgeContract' }
 };
 
-const actionClient = new PodToBridgedActionClient(actionConfig);
+const actionClient = new PodToSourceChainActionClient(actionConfig);
 const trackerClient = new PodBridgeTrackerClient(trackerConfig);
 const podProvider = new ethers.JsonRpcProvider(trackerConfig.pod.rpcUrl);
 const podSigner = new ethers.Wallet('PRIVATE_KEY', podProvider);
@@ -524,7 +548,7 @@ const claimTx = actionClient.claimWithCertificate({
   certifiedLog
 });
 
-const sepoliaProvider = new ethers.JsonRpcProvider(trackerConfig.bridged.rpcUrl);
+const sepoliaProvider = new ethers.JsonRpcProvider(trackerConfig.sourceChain.rpcUrl);
 const sepoliaSigner = new ethers.Wallet('PRIVATE_KEY', sepoliaProvider);
 const claim = await sepoliaSigner.sendTransaction(claimTx);
 await claim.wait();

package/dist/clients/tracker/client.d.ts

@@ -1,28 +1,39 @@
 import { PodBridgeConfig, BridgeRequest, BridgeRequestWithType, CertifiedLog } from "../../libs/types/pod-bridge.types";
+/**
+ * PodBridgeTrackerClient - Main orchestrator for bridge tracking
+ *
+ * This client coordinates between SourceChainTrackerService and PodTrackerService
+ * to provide a unified view of bridge activity across both chains.
+ *
+ * Bridge Architecture:
+ * - Source Chain (e.g., Sepolia): BridgeDepositWithdraw contract
+ *   - Deposits lock tokens
+ *   - Claims use POD certificates (requires attestations)
+ *
+ * - POD Chain: BridgeMintBurn contract
+ *   - Deposits burn tokens (POD has instant finality - single block)
+ *   - Claims use block number verification via precompiles
+ */
 export declare class PodBridgeTrackerClient {
-    private readonly config;
-    private readonly bridgedProvider;
-    private readonly podProvider;
-    private readonly bridgedBridge;
-    private readonly podBridge;
-    private readonly iface;
+    private readonly sourceChainTracker;
+    private readonly podTracker;
     constructor(config: PodBridgeConfig);
     /**
-     * Get all deposits SENT by an address
+     * Get all deposits SENT by an address from BOTH chains
      * @param address The address that sent deposits
      * @param fromBlock Starting block number (default: contract deployment block or 0)
      * @returns Array of bridge requests sent by this address
      */
     getDepositsSentBy(address: string, fromBlock?: number): Promise<BridgeRequest[]>;
     /**
-     * Get all deposits RECEIVED by an address
+     * Get all deposits RECEIVED by an address from BOTH chains
      * @param address The address that will receive deposits
      * @param fromBlock Starting block number (default: contract deployment block or 0)
      * @returns Array of bridge requests sent to this address
      */
     getDepositsReceivedBy(address: string, fromBlock?: number): Promise<BridgeRequest[]>;
     /**
-     * Get ALL deposits for an address (both sent and received)
+     * Get ALL deposits for an address (both sent and received) from BOTH chains
      * @param address The address to check
      * @param fromBlock Starting block number (default: contract deployment block or 0)
      * @returns Array of bridge requests with type indicator
@@ -33,10 +44,11 @@ export declare class PodBridgeTrackerClient {
      * @param deposit The bridge request to check
      * @returns True if the deposit can be claimed
      */
-    canBeClaimed(deposit: Pick<BridgeRequest, 'isClaimed' | 'blockNumber'>): Promise<boolean>;
+    canBeClaimed(deposit: BridgeRequest): Promise<boolean>;
     /**
      * Batch check claim status for multiple deposits
-     * @param deposits Array of deposits to check
+     * Claims are checked on the opposite chain from where the deposit was made
+     * @private
      */
     private updateClaimStatus;
     /**
@@ -45,45 +57,11 @@ export declare class PodBridgeTrackerClient {
      * @returns Array of boolean values
      */
     areRequestsProcessed(deposits: BridgeRequest[]): Promise<boolean[]>;
-    /**
-     * Compute the request hash (replicates Solidity's _hashRequest)
-     * @param id Request ID
-     * @param token Token address
-     * @param amount Amount in wei
-     * @param to Recipient address
-     * @returns Request hash
-     */
-    private computeRequestHash;
     /**
      * Get certified log for a deposit transaction from POD
-     * This is required to claim tokens on Sepolia from POD deposits
+     * This is required to claim tokens on Source Chain from POD deposits
      * @param txHash Transaction hash of the deposit on POD
      * @returns Certified log with attestations and merkle proof
      */
     getDepositCertifiedLog(txHash: string): Promise<CertifiedLog>;
-    /**
-     * Compute receipt root hash
-     * @private
-     */
-    private computeReceiptRoot;
-    /**
-     * Aggregate signatures from attestations
-     * @private
-     */
-    private aggregateSignatures;
-    /**
-     * Hash a log entry
-     * @private
-     */
-    private hashLog;
-    /**
-     * Hash a leaf for merkle tree
-     * @private
-     */
-    private hashLeaf;
-    /**
-     * Generate merkle proof for a log at given index
-     * @private
-     */
-    private generateMerkleProof;
 }