@tapforce/pod-bridge-sdk 1.0.1

package/README.md

@@ -0,0 +1,454 @@
+# 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).
+
+## Features
+
+- 🌉 **Bridge Token Deposits**: Deposit ERC20 tokens and native tokens to the bridge
+- 🔍 **Track Bridge Requests**: Query deposits sent by or received by any address
+- ✅ **Claim Status Tracking**: Monitor claim status and finality of bridge requests
+- 📝 **Transaction Building**: Generate unsigned transactions ready for signing
+- 🔐 **Type-Safe**: Full TypeScript support with comprehensive type definitions
+
+## Installation
+
+```bash
+npm install @tapforce/pod-bridge-sdk
+```
+
+or
+
+```bash
+yarn add @tapforce/pod-bridge-sdk
+```
+
+or
+
+```bash
+pnpm add @tapforce/pod-bridge-sdk
+```
+
+## Quick Start
+
+### Import the SDK
+
+```typescript
+import { 
+  PodBridgeActionClient, 
+  PodBridgeTrackerClient,
+  PodBridgeConfig 
+} from '@tapforce/pod-bridge-sdk';
+```
+
+### Configuration
+
+Create a configuration object with source and destination chain details:
+
+```typescript
+const config: PodBridgeConfig = {
+  source: {
+    rpcUrl: 'https://sepolia.infura.io/v3/YOUR_KEY',
+    contractAddress: '0x...' // Source chain bridge contract
+  },
+  destination: {
+    rpcUrl: 'https://pod-rpc.example.com',
+    contractAddress: '0x...' // Destination chain bridge contract
+  }
+};
+```
+
+## Usage
+
+### 1. Action Client - Creating Transactions
+
+The `PodBridgeActionClient` creates unsigned transactions that you can sign and broadcast.
+
+#### Deposit ERC20 Tokens
+
+```typescript
+const actionClient = new PodBridgeActionClient();
+
+// Create unsigned transaction for ERC20 deposit
+const unsignedTx = actionClient.depositToken({
+  token: '0x...', // ERC20 token address
+  amount: '1000000000000000000', // Amount in wei (1 token with 18 decimals)
+  recipient: '0x...', // Recipient address on destination chain
+  contractAddress: config.source.contractAddress,
+  from: '0x...' // Optional: sender address
+});
+
+// Sign and send transaction using your wallet/provider
+// const tx = await signer.sendTransaction(unsignedTx);
+```
+
+#### Deposit Native Tokens (ETH)
+
+```typescript
+// Create unsigned transaction for native token deposit
+const unsignedTx = actionClient.depositNative({
+  amount: '1000000000000000000', // Amount in wei (1 ETH)
+  recipient: '0x...', // Recipient address on destination chain
+  contractAddress: config.source.contractAddress,
+  from: '0x...' // Optional: sender address
+});
+
+// Sign and send transaction
+// const tx = await signer.sendTransaction(unsignedTx);
+```
+
+#### Claim Tokens (with Certificate) - Sepolia from POD
+
+For claiming on Sepolia from POD deposits, use certificate-based claims:
+
+```typescript
+// Obtain certified log from POD certificate system
+const certifiedLog = {
+  log: {
+    addr: '0x...',
+    topics: ['0x...'],
+    data: '0x...'
+  },
+  sigs: [
+    { r: '0x...', s: '0x...', v: 27 }
+  ]
+};
+
+// Create unsigned claim transaction for ERC20
+const unsignedTx = actionClient.claimWithCertificate({
+  certifiedLog,
+  contractAddress: config.destination.contractAddress,
+  from: '0x...' // Optional: claimer address
+});
+
+// For native tokens
+const unsignedNativeTx = actionClient.claimNativeWithCertificate({
+  certifiedLog,
+  contractAddress: config.destination.contractAddress,
+  from: '0x...'
+});
+```
+
+#### Claim Tokens (with Block Number) - POD from Sepolia
+
+For claiming on POD from Sepolia deposits, use block number-based claims:
+
+```typescript
+// Create unsigned claim transaction for ERC20
+const unsignedTx = actionClient.claimWithBlockNumber({
+  id: '123', // Request ID from deposit event
+  token: '0x...', // Token address on source chain
+  blockNumber: 12345678, // Block number of deposit on source chain
+  contractAddress: config.destination.contractAddress,
+  from: '0x...' // Optional: claimer address
+});
+
+// For native tokens
+const unsignedNativeTx = actionClient.claimNativeWithBlockNumber({
+  id: '123',
+  blockNumber: 12345678,
+  contractAddress: config.destination.contractAddress,
+  from: '0x...'
+});
+```
+
+### 2. Tracker Client - Querying Bridge Activity
+
+The `PodBridgeTrackerClient` queries the blockchain for deposit and claim events.
+
+```typescript
+const trackerClient = new PodBridgeTrackerClient(config);
+```
+
+#### Get Deposits Sent by Address
+
+```typescript
+// Get all deposits sent by an address
+const deposits = await trackerClient.getDepositsSentBy(
+  '0x...', // sender address
+  0 // starting block (optional, default: 0)
+);
+
+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(`Claimed: ${deposit.isClaimed}`);
+  if (deposit.isClaimed) {
+    console.log(`Claimed by: ${deposit.claimedBy}`);
+    console.log(`Claimed tx: ${deposit.claimedTxHash}`);
+  }
+});
+```
+
+#### Get Deposits Received by Address
+
+```typescript
+// Get all deposits where the address is the recipient
+const deposits = await trackerClient.getDepositsReceivedBy(
+  '0x...', // recipient address
+  0 // starting block (optional)
+);
+```
+
+#### Get All Deposits (Sent + Received)
+
+```typescript
+// Get all deposits related to an address (both sent and received)
+const allDeposits = await trackerClient.getAllDepositsFor(
+  '0x...', // address
+  0 // starting block (optional)
+);
+
+// Deposits include a 'type' field indicating SENT or RECEIVED
+allDeposits.forEach(deposit => {
+  console.log(`Type: ${deposit.type}`); // 'sent' or 'received'
+  console.log(`Request ID: ${deposit.requestId}`);
+});
+```
+
+#### Check if Deposit Can Be Claimed
+
+```typescript
+// Check if a deposit has been finalized and can be claimed
+const canClaim = await trackerClient.canBeClaimed(deposit);
+
+if (canClaim) {
+  console.log('Deposit is ready to be claimed!');
+}
+```
+
+#### Batch Check Processed Requests
+
+```typescript
+// Check multiple deposits at once
+const deposits = await trackerClient.getDepositsSentBy('0x...');
+const processedStatuses = await trackerClient.areRequestsProcessed(deposits);
+
+processedStatuses.forEach((isProcessed, index) => {
+  console.log(`Deposit ${deposits[index].requestId} processed: ${isProcessed}`);
+});
+```
+
+## API Reference
+
+### PodBridgeActionClient
+
+#### Methods
+
+- **`depositToken(args)`**: Create unsigned transaction for ERC20 deposit
+  - `token`: Token address
+  - `amount`: Amount in wei (string | bigint)
+  - `recipient`: Recipient address on destination chain
+  - `contractAddress`: Bridge contract address
+  - `from?`: Optional sender address
+
+- **`depositNative(args)`**: Create unsigned transaction for native token deposit
+  - `amount`: Amount in wei (string | bigint)
+  - `recipient`: Recipient address on destination chain
+  - `contractAddress`: Bridge contract address
+  - `from?`: Optional sender address
+
+- **`claimWithCertificate(args)`**: Create unsigned transaction for claiming with certificate
+  - `certifiedLog`: Certified log from POD certificate system
+  - `contractAddress`: Bridge contract address
+  - `from?`: Optional claimer address
+
+- **`claimNativeWithCertificate(args)`**: Create unsigned transaction for claiming native tokens with certificate
+  - `certifiedLog`: Certified log from POD certificate system
+  - `contractAddress`: Bridge contract address
+  - `from?`: Optional claimer address
+
+- **`claimWithBlockNumber(args)`**: Create unsigned transaction for claiming with block number
+  - `id`: Request ID
+  - `token`: Token address
+  - `blockNumber`: Block number of deposit
+  - `contractAddress`: Bridge contract address
+  - `from?`: Optional claimer address
+
+- **`claimNativeWithBlockNumber(args)`**: Create unsigned transaction for claiming native tokens with block number
+  - `id`: Request ID
+  - `blockNumber`: Block number of deposit
+  - `contractAddress`: Bridge contract address
+  - `from?`: Optional claimer address
+
+### PodBridgeTrackerClient
+
+#### Methods
+
+- **`getDepositsSentBy(address, fromBlock?)`**: Get deposits sent by address
+  - Returns: `Promise<BridgeRequest[]>`
+
+- **`getDepositsReceivedBy(address, fromBlock?)`**: Get deposits received by address
+  - Returns: `Promise<BridgeRequest[]>`
+
+- **`getAllDepositsFor(address, fromBlock?)`**: Get all deposits for address (sent + received)
+  - Returns: `Promise<BridgeRequestWithType[]>`
+
+- **`canBeClaimed(deposit)`**: Check if deposit can be claimed
+  - Returns: `Promise<boolean>`
+
+- **`areRequestsProcessed(deposits)`**: Batch check if requests are processed
+  - Returns: `Promise<boolean[]>`
+
+## Types
+
+### BridgeRequest
+
+```typescript
+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
+  isClaimed: boolean;
+  claimedTxHash?: string;
+  claimedAt?: number;
+  claimedBy?: string;
+}
+```
+
+### UnsignedTransaction
+
+```typescript
+interface UnsignedTransaction {
+  to: string;
+  data: string;
+  value: string;
+  from?: string;
+  chainId?: number;
+  gasLimit?: bigint;
+}
+```
+
+### CertifiedLog
+
+```typescript
+interface CertifiedLog {
+  log: {
+    addr: string;
+    topics: string[];
+    data: string;
+  };
+  sigs: Array<{
+    r: string;
+    s: string;
+    v: number;
+  }>;
+}
+```
+
+## Bridge Types
+
+The SDK supports two bridge implementations:
+
+1. **BridgeDepositWithdraw** (Certificate-based)
+   - Used for claiming on Sepolia 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
+   - Uses block number verification via precompiles
+   - Methods: `claimWithBlockNumber`, `claimNativeWithBlockNumber`
+
+## Examples
+
+### Complete Deposit and Claim Flow
+
+```typescript
+import { ethers } from 'ethers';
+import { PodBridgeActionClient, PodBridgeTrackerClient } from '@tapforce/pod-bridge-sdk';
+
+// Setup
+const config = {
+  source: {
+    rpcUrl: 'https://sepolia.infura.io/v3/YOUR_KEY',
+    contractAddress: '0xSourceBridgeContract'
+  },
+  destination: {
+    rpcUrl: 'https://pod-rpc.example.com',
+    contractAddress: '0xDestBridgeContract'
+  }
+};
+
+const actionClient = new PodBridgeActionClient();
+const trackerClient = new PodBridgeTrackerClient(config);
+const provider = new ethers.JsonRpcProvider(config.source.rpcUrl);
+const signer = new ethers.Wallet('PRIVATE_KEY', provider);
+
+// Step 1: Deposit tokens
+const depositTx = actionClient.depositToken({
+  token: '0xTokenAddress',
+  amount: ethers.parseEther('10').toString(),
+  recipient: await signer.getAddress(),
+  contractAddress: config.source.contractAddress
+});
+
+const tx = await signer.sendTransaction(depositTx);
+await tx.wait();
+console.log(`Deposit tx: ${tx.hash}`);
+
+// Step 2: Track deposit
+const deposits = await trackerClient.getDepositsSentBy(await signer.getAddress());
+const latestDeposit = deposits[0];
+
+console.log(`Request ID: ${latestDeposit.requestId}`);
+console.log(`Amount: ${ethers.formatEther(latestDeposit.amount)}`);
+
+// Step 3: Wait for finality and claim
+const canClaim = await trackerClient.canBeClaimed(latestDeposit);
+if (canClaim) {
+  const claimTx = actionClient.claimWithBlockNumber({
+    id: latestDeposit.requestId,
+    token: latestDeposit.token,
+    blockNumber: latestDeposit.blockNumber,
+    contractAddress: config.destination.contractAddress
+  });
+  
+  // Submit claim on destination chain
+  // const destSigner = new ethers.Wallet('PRIVATE_KEY', destProvider);
+  // const claim = await destSigner.sendTransaction(claimTx);
+  // await claim.wait();
+}
+```
+
+## Development
+
+### Build
+
+```bash
+npm run build
+```
+
+### Clean
+
+```bash
+npm run clean
+```
+
+## Dependencies
+
+- **ethers**: ^6.15.0 - Ethereum library for interacting with contracts
+- **typescript**: ^5.8.3 - TypeScript support
+
+## License
+
+ISC
+
+## Repository
+
+- **Homepage**: [https://github.com/tapforce/pod-ts-bridge-sdk](https://github.com/tapforce/pod-ts-bridge-sdk)
+- **Issues**: [https://github.com/tapforce/pod-ts-bridge-sdk/issues](https://github.com/tapforce/pod-ts-bridge-sdk/issues)
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## Author
+
+Tapforce

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

@@ -0,0 +1,93 @@
+import { UnsignedTransaction, CertifiedLog } from "../../libs/types/pod-bridge.types";
+export declare class PodBridgeActionClient {
+    private readonly iface;
+    constructor();
+    /**
+     * Create unsigned transaction for depositing ERC20 tokens
+     * @param args.token Token address to deposit
+     * @param args.amount Amount to deposit (in wei)
+     * @param args.recipient Recipient address on destination chain
+     * @param args.contractAddress Bridge contract address (source chain)
+     * @param args.from Optional sender address
+     * @returns Unsigned transaction template with encoded deposit call
+     */
+    depositToken(args: {
+        token: string;
+        amount: string | bigint;
+        recipient: string;
+        contractAddress: string;
+        from?: string;
+    }): UnsignedTransaction;
+    /**
+     * Create unsigned transaction for depositing native tokens (ETH)
+     * @param args.amount Amount to deposit (in wei) - also set as transaction value
+     * @param args.recipient Recipient address on destination chain
+     * @param args.contractAddress Bridge contract address (source chain)
+     * @param args.from Optional sender address
+     * @returns Unsigned transaction template with encoded depositNative call
+     */
+    depositNative(args: {
+        amount: string | bigint;
+        recipient: string;
+        contractAddress: string;
+        from?: string;
+    }): UnsignedTransaction;
+    /**
+     * Create unsigned transaction for claiming tokens (BridgeDepositWithdraw - with certificates)
+     * Used for claiming on Sepolia from POD deposits
+     * @param args.certifiedLog Certified log from POD certificate system
+     * @param args.contractAddress Bridge contract address (destination chain)
+     * @param args.from Optional sender address
+     * @returns Unsigned transaction template with encoded claim call
+     */
+    claimWithCertificate(args: {
+        certifiedLog: CertifiedLog;
+        contractAddress: string;
+        from?: string;
+    }): UnsignedTransaction;
+    /**
+     * Create unsigned transaction for claiming native tokens (BridgeDepositWithdraw - with certificates)
+     * Used for claiming native tokens on Sepolia from POD deposits
+     * @param args.certifiedLog Certified log from POD certificate system
+     * @param args.contractAddress Bridge contract address (destination chain)
+     * @param args.from Optional sender address
+     * @returns Unsigned transaction template with encoded claimNative call
+     */
+    claimNativeWithCertificate(args: {
+        certifiedLog: CertifiedLog;
+        contractAddress: string;
+        from?: string;
+    }): UnsignedTransaction;
+    /**
+     * Create unsigned transaction for claiming tokens (BridgeMintBurn - using precompiles)
+     * Used for claiming on POD from Sepolia deposits
+     * @param args.id Request ID from deposit event
+     * @param args.token Token address that was deposited on source chain
+     * @param args.blockNumber Block number of the deposit on source chain
+     * @param args.contractAddress Bridge contract address (destination chain)
+     * @param args.from Optional sender address
+     * @returns Unsigned transaction template with encoded claim call
+     */
+    claimWithBlockNumber(args: {
+        id: string | bigint;
+        token: string;
+        blockNumber: string | bigint | number;
+        contractAddress: string;
+        from?: string;
+    }): UnsignedTransaction;
+    /**
+     * Create unsigned transaction for claiming native tokens (BridgeMintBurn - using precompiles)
+     * Used for claiming native tokens on POD from Sepolia deposits
+     * @param args.id Request ID from deposit event
+     * @param args.blockNumber Block number of the deposit on source chain
+     * @param args.contractAddress Bridge contract address (destination chain)
+     * @param args.from Optional sender address
+     * @returns Unsigned transaction template with encoded claimNative call
+     */
+    claimNativeWithBlockNumber(args: {
+        id: string | bigint;
+        blockNumber: string | bigint | number;
+        contractAddress: string;
+        from?: string;
+    }): UnsignedTransaction;
+}

package/dist/clients/action/client.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PodBridgeActionClient = void 0;
+const ethers_1 = require("ethers");
+const bridge_abi_1 = require("../../libs/abi/bridge.abi");
+class PodBridgeActionClient {
+    constructor() {
+        this.iface = new ethers_1.Interface(bridge_abi_1.POD_BRIDGE_ABI);
+    }
+    /**
+     * Create unsigned transaction for depositing ERC20 tokens
+     * @param args.token Token address to deposit
+     * @param args.amount Amount to deposit (in wei)
+     * @param args.recipient Recipient address on destination chain
+     * @param args.contractAddress Bridge contract address (source chain)
+     * @param args.from Optional sender address
+     * @returns Unsigned transaction template with encoded deposit call
+     */
+    depositToken(args) {
+        const data = this.iface.encodeFunctionData('deposit', [
+            args.token,
+            args.amount,
+            args.recipient
+        ]);
+        return {
+            to: args.contractAddress,
+            data,
+            value: '0',
+            from: args === null || args === void 0 ? void 0 : args.from
+        };
+    }
+    /**
+     * Create unsigned transaction for depositing native tokens (ETH)
+     * @param args.amount Amount to deposit (in wei) - also set as transaction value
+     * @param args.recipient Recipient address on destination chain
+     * @param args.contractAddress Bridge contract address (source chain)
+     * @param args.from Optional sender address
+     * @returns Unsigned transaction template with encoded depositNative call
+     */
+    depositNative(args) {
+        const data = this.iface.encodeFunctionData('depositNative', [args.recipient]);
+        return {
+            to: args.contractAddress,
+            data,
+            value: args.amount.toString(),
+            from: args === null || args === void 0 ? void 0 : args.from
+        };
+    }
+    /**
+     * Create unsigned transaction for claiming tokens (BridgeDepositWithdraw - with certificates)
+     * Used for claiming on Sepolia from POD deposits
+     * @param args.certifiedLog Certified log from POD certificate system
+     * @param args.contractAddress Bridge contract address (destination chain)
+     * @param args.from Optional sender address
+     * @returns Unsigned transaction template with encoded claim call
+     */
+    claimWithCertificate(args) {
+        const data = this.iface.encodeFunctionData('claim', [args.certifiedLog]);
+        return {
+            to: args.contractAddress,
+            data,
+            value: '0',
+            from: args === null || args === void 0 ? void 0 : args.from
+        };
+    }
+    /**
+     * Create unsigned transaction for claiming native tokens (BridgeDepositWithdraw - with certificates)
+     * Used for claiming native tokens on Sepolia from POD deposits
+     * @param args.certifiedLog Certified log from POD certificate system
+     * @param args.contractAddress Bridge contract address (destination chain)
+     * @param args.from Optional sender address
+     * @returns Unsigned transaction template with encoded claimNative call
+     */
+    claimNativeWithCertificate(args) {
+        const data = this.iface.encodeFunctionData('claimNative', [args.certifiedLog]);
+        return {
+            to: args.contractAddress,
+            data,
+            value: '0',
+            from: args === null || args === void 0 ? void 0 : args.from
+        };
+    }
+    /**
+     * Create unsigned transaction for claiming tokens (BridgeMintBurn - using precompiles)
+     * Used for claiming on POD from Sepolia deposits
+     * @param args.id Request ID from deposit event
+     * @param args.token Token address that was deposited on source chain
+     * @param args.blockNumber Block number of the deposit on source chain
+     * @param args.contractAddress Bridge contract address (destination chain)
+     * @param args.from Optional sender address
+     * @returns Unsigned transaction template with encoded claim call
+     */
+    claimWithBlockNumber(args) {
+        const data = this.iface.encodeFunctionData('claim(uint256,address,uint256)', [
+            args.id,
+            args.token,
+            args.blockNumber
+        ]);
+        return {
+            to: args.contractAddress,
+            data,
+            value: '0',
+            from: args === null || args === void 0 ? void 0 : args.from
+        };
+    }
+    /**
+     * Create unsigned transaction for claiming native tokens (BridgeMintBurn - using precompiles)
+     * Used for claiming native tokens on POD from Sepolia deposits
+     * @param args.id Request ID from deposit event
+     * @param args.blockNumber Block number of the deposit on source chain
+     * @param args.contractAddress Bridge contract address (destination chain)
+     * @param args.from Optional sender address
+     * @returns Unsigned transaction template with encoded claimNative call
+     */
+    claimNativeWithBlockNumber(args) {
+        const data = this.iface.encodeFunctionData('claimNative(uint256,uint256)', [args.id, args.blockNumber]);
+        return {
+            to: args.contractAddress,
+            data,
+            value: '0',
+            from: args === null || args === void 0 ? void 0 : args.from
+        };
+    }
+}
+exports.PodBridgeActionClient = PodBridgeActionClient;

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

@@ -0,0 +1,57 @@
+import { PodBridgeConfig, BridgeRequest, BridgeRequestWithType } from "../../libs/types/pod-bridge.types";
+export declare class PodBridgeTrackerClient {
+    private readonly config;
+    private readonly sourceProvider;
+    private readonly destProvider;
+    private readonly sourceBridge;
+    private readonly destBridge;
+    private readonly iface;
+    constructor(config: PodBridgeConfig);
+    /**
+     * Get all deposits SENT by an address
+     * @param address The address that sent deposits
+     * @param fromBlock Starting block number (default: 0)
+     * @returns Array of bridge requests sent by this address
+     */
+    getDepositsSentBy(address: string, fromBlock?: number): Promise<BridgeRequest[]>;
+    /**
+     * Get all deposits RECEIVED by an address
+     * @param address The address that will receive deposits
+     * @param fromBlock Starting block number (default: 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)
+     * @param address The address to check
+     * @param fromBlock Starting block number (default: 0)
+     * @returns Array of bridge requests with type indicator
+     */
+    getAllDepositsFor(address: string, fromBlock?: number): Promise<BridgeRequestWithType[]>;
+    /**
+     * Check if deposits can be claimed (block finalized on source chain)
+     * @param deposit The bridge request to check
+     * @returns True if the deposit can be claimed
+     */
+    canBeClaimed(deposit: Pick<BridgeRequest, 'isClaimed' | 'blockNumber'>): Promise<boolean>;
+    /**
+     * Batch check claim status for multiple deposits
+     * @param deposits Array of deposits to check
+     */
+    private updateClaimStatus;
+    /**
+     * Batch check if multiple requests have been processed on-chain
+     * @param deposits Array of deposits to check
+     * @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;
+}

package/dist/clients/tracker/client.js

@@ -0,0 +1,303 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PodBridgeTrackerClient = void 0;
+const ethers_1 = require("ethers");
+const pod_bridge_types_1 = require("../../libs/types/pod-bridge.types");
+const bridge_abi_1 = require("../../libs/abi/bridge.abi");
+class PodBridgeTrackerClient {
+    constructor(config) {
+        this.config = config;
+        // Initialize providers
+        this.sourceProvider = new ethers_1.ethers.JsonRpcProvider(config.source.rpcUrl);
+        this.destProvider = new ethers_1.ethers.JsonRpcProvider(config.destination.rpcUrl);
+        // Initialize contract instances
+        this.sourceBridge = new ethers_1.Contract(config.source.contractAddress, bridge_abi_1.POD_BRIDGE_ABI, this.sourceProvider);
+        this.destBridge = new ethers_1.Contract(config.destination.contractAddress, bridge_abi_1.POD_BRIDGE_ABI, this.destProvider);
+        // Interface for parsing logs
+        this.iface = new ethers_1.Interface(bridge_abi_1.POD_BRIDGE_ABI);
+    }
+    /**
+     * Get all deposits SENT by an address
+     * @param address The address that sent deposits
+     * @param fromBlock Starting block number (default: 0)
+     * @returns Array of bridge requests sent by this address
+     */
+    async getDepositsSentBy(address, fromBlock = 0) {
+        console.log(`Fetching deposits sent by ${address}...`);
+        const deposits = [];
+        const currentBlock = await this.sourceProvider.getBlockNumber();
+        const BLOCK_BATCH_SIZE = 10000;
+        for (let start = fromBlock; start <= currentBlock; start += BLOCK_BATCH_SIZE) {
+            const end = Math.min(start + BLOCK_BATCH_SIZE - 1, currentBlock);
+            // With improved events, we can filter by 'from' directly!
+            const depositFilter = this.sourceBridge.filters.Deposit(null, // id
+            address, // from (indexed) - Filter by sender!
+            null // to
+            );
+            const depositNativeFilter = this.sourceBridge.filters.DepositNative(null, // id
+            address, // from (indexed) - Filter by sender!
+            null // to
+            );
+            const [depositLogs, depositNativeLogs] = await Promise.all([
+                this.sourceBridge.queryFilter(depositFilter, start, end),
+                this.sourceBridge.queryFilter(depositNativeFilter, start, end)
+            ]);
+            // Process Deposit events
+            for (const log of depositLogs) {
+                const parsed = this.iface.parseLog({
+                    topics: [...log.topics],
+                    data: log.data
+                });
+                if (parsed) {
+                    deposits.push({
+                        requestId: parsed.args.id.toString(),
+                        blockNumber: Number(parsed.args.blockNumber),
+                        timestamp: Number(parsed.args.timestamp),
+                        txHash: log.transactionHash,
+                        from: parsed.args.from,
+                        to: parsed.args.to,
+                        token: parsed.args.token,
+                        amount: parsed.args.amount.toString(),
+                        isClaimed: false
+                    });
+                }
+            }
+            // Process DepositNative events
+            for (const log of depositNativeLogs) {
+                const parsed = this.iface.parseLog({
+                    topics: [...log.topics],
+                    data: log.data
+                });
+                if (parsed) {
+                    deposits.push({
+                        requestId: parsed.args.id.toString(),
+                        blockNumber: Number(parsed.args.blockNumber),
+                        timestamp: Number(parsed.args.timestamp),
+                        txHash: log.transactionHash,
+                        from: parsed.args.from,
+                        to: parsed.args.to,
+                        token: ethers_1.ethers.ZeroAddress, // Native token
+                        amount: parsed.args.amount.toString(),
+                        isClaimed: false
+                    });
+                }
+            }
+        }
+        // Check claim status
+        await this.updateClaimStatus(deposits);
+        return deposits.sort((a, b) => b.timestamp - a.timestamp);
+    }
+    /**
+     * Get all deposits RECEIVED by an address
+     * @param address The address that will receive deposits
+     * @param fromBlock Starting block number (default: 0)
+     * @returns Array of bridge requests sent to this address
+     */
+    async getDepositsReceivedBy(address, fromBlock = 0) {
+        console.log(`Fetching deposits received by ${address}...`);
+        const deposits = [];
+        const currentBlock = await this.sourceProvider.getBlockNumber();
+        const BLOCK_BATCH_SIZE = 10000;
+        for (let start = fromBlock; start <= currentBlock; start += BLOCK_BATCH_SIZE) {
+            const end = Math.min(start + BLOCK_BATCH_SIZE - 1, currentBlock);
+            // With improved events, we can filter by 'to' directly!
+            const depositFilter = this.sourceBridge.filters.Deposit(null, // id
+            null, // from
+            address // to (indexed) - Filter by recipient!
+            );
+            const depositNativeFilter = this.sourceBridge.filters.DepositNative(null, // id
+            null, // from
+            address // to (indexed) - Filter by recipient!
+            );
+            const [depositLogs, depositNativeLogs] = await Promise.all([
+                this.sourceBridge.queryFilter(depositFilter, start, end),
+                this.sourceBridge.queryFilter(depositNativeFilter, start, end)
+            ]);
+            // Process Deposit events
+            for (const log of depositLogs) {
+                const parsed = this.iface.parseLog({
+                    topics: [...log.topics],
+                    data: log.data
+                });
+                if (parsed) {
+                    deposits.push({
+                        requestId: parsed.args.id.toString(),
+                        blockNumber: Number(parsed.args.blockNumber),
+                        timestamp: Number(parsed.args.timestamp),
+                        txHash: log.transactionHash,
+                        from: parsed.args.from,
+                        to: parsed.args.to,
+                        token: parsed.args.token,
+                        amount: parsed.args.amount.toString(),
+                        isClaimed: false
+                    });
+                }
+            }
+            // Process DepositNative events
+            for (const log of depositNativeLogs) {
+                const parsed = this.iface.parseLog({
+                    topics: [...log.topics],
+                    data: log.data
+                });
+                if (parsed) {
+                    deposits.push({
+                        requestId: parsed.args.id.toString(),
+                        blockNumber: Number(parsed.args.blockNumber),
+                        timestamp: Number(parsed.args.timestamp),
+                        txHash: log.transactionHash,
+                        from: parsed.args.from,
+                        to: parsed.args.to,
+                        token: ethers_1.ethers.ZeroAddress,
+                        amount: parsed.args.amount.toString(),
+                        isClaimed: false
+                    });
+                }
+            }
+        }
+        // Check claim status
+        await this.updateClaimStatus(deposits);
+        return deposits.sort((a, b) => b.timestamp - a.timestamp);
+    }
+    /**
+     * Get ALL deposits for an address (both sent and received)
+     * @param address The address to check
+     * @param fromBlock Starting block number (default: 0)
+     * @returns Array of bridge requests with type indicator
+     */
+    async getAllDepositsFor(address, fromBlock = 0) {
+        console.log(`Fetching all deposits for ${address}...`);
+        // Fetch both sent and received in parallel
+        const [sent, received] = await Promise.all([
+            this.getDepositsSentBy(address, fromBlock),
+            this.getDepositsReceivedBy(address, fromBlock)
+        ]);
+        // Mark with type and combine
+        const sentWithType = sent.map(d => ({
+            ...d,
+            type: pod_bridge_types_1.DepositType.SENT
+        }));
+        const receivedWithType = received.map(d => ({
+            ...d,
+            type: pod_bridge_types_1.DepositType.RECEIVED
+        }));
+        // Combine and deduplicate (in case user sent to themselves)
+        const allDeposits = [...sentWithType, ...receivedWithType];
+        const uniqueDeposits = new Map();
+        for (const deposit of allDeposits) {
+            const key = `${deposit.requestId}-${deposit.txHash}`;
+            if (!uniqueDeposits.has(key)) {
+                uniqueDeposits.set(key, deposit);
+            }
+            else {
+                // If deposit appears in both (sent to self), mark as both
+                const existing = uniqueDeposits.get(key);
+                if (existing.from === address && existing.to === address) {
+                    uniqueDeposits.set(key, { ...existing, type: pod_bridge_types_1.DepositType.SENT });
+                }
+            }
+        }
+        return Array.from(uniqueDeposits.values())
+            .sort((a, b) => b.timestamp - a.timestamp);
+    }
+    /**
+     * Check if deposits can be claimed (block finalized on source chain)
+     * @param deposit The bridge request to check
+     * @returns True if the deposit can be claimed
+     */
+    async canBeClaimed(deposit) {
+        const currentBlock = await this.sourceProvider.getBlockNumber();
+        const finalizedBlock = currentBlock - 15; // ~15 minutes on Sepolia
+        return deposit.blockNumber <= finalizedBlock && !deposit.isClaimed;
+    }
+    /**
+     * Batch check claim status for multiple deposits
+     * @param deposits Array of deposits to check
+     */
+    async updateClaimStatus(deposits) {
+        if (deposits.length === 0)
+            return;
+        console.log(`Checking claim status for ${deposits.length} deposits...`);
+        try {
+            // Get claim events from destination chain
+            const claimFilter = this.destBridge.filters.Claim();
+            const claimNativeFilter = this.destBridge.filters.ClaimNative();
+            const [claimLogs, claimNativeLogs] = await Promise.all([
+                this.destBridge.queryFilter(claimFilter),
+                this.destBridge.queryFilter(claimNativeFilter)
+            ]);
+            // Create a map of claimed request IDs
+            const claimedMap = new Map();
+            for (const log of [...claimLogs, ...claimNativeLogs]) {
+                const parsed = this.iface.parseLog({
+                    topics: [...log.topics],
+                    data: log.data
+                });
+                if (parsed) {
+                    claimedMap.set(parsed.args.id.toString(), {
+                        txHash: log.transactionHash,
+                        timestamp: Number(parsed.args.timestamp),
+                        claimer: parsed.args.claimer
+                    });
+                }
+            }
+            // Update deposit status
+            for (const deposit of deposits) {
+                const claimInfo = claimedMap.get(deposit.requestId);
+                if (claimInfo) {
+                    deposit.isClaimed = true;
+                    deposit.claimedTxHash = claimInfo.txHash;
+                    deposit.claimedAt = claimInfo.timestamp;
+                    deposit.claimedBy = claimInfo.claimer;
+                }
+            }
+        }
+        catch (error) {
+            console.error('Error checking claim status:', error);
+        }
+    }
+    /**
+     * Batch check if multiple requests have been processed on-chain
+     * @param deposits Array of deposits to check
+     * @returns Array of boolean values
+     */
+    async areRequestsProcessed(deposits) {
+        if (deposits.length === 0)
+            return [];
+        try {
+            const ids = deposits.map(d => d.requestId);
+            const tokens = deposits.map(d => d.token);
+            const amounts = deposits.map(d => d.amount);
+            const tos = deposits.map(d => d.to);
+            const results = await this.destBridge.areRequestsProcessed(ids, tokens, amounts, tos);
+            return results;
+        }
+        catch (error) {
+            console.error('Batch check failed, falling back to individual checks:', error);
+            // Fallback: check individually
+            const results = [];
+            for (const deposit of deposits) {
+                try {
+                    const hash = this.computeRequestHash(deposit.requestId, deposit.token, deposit.amount, deposit.to);
+                    const isProcessed = await this.destBridge.processedRequests(hash);
+                    results.push(isProcessed);
+                }
+                catch (_a) {
+                    results.push(false);
+                }
+            }
+            return results;
+        }
+    }
+    /**
+     * 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
+     */
+    computeRequestHash(id, token, amount, to) {
+        return ethers_1.ethers.solidityPackedKeccak256(['uint256', 'address', 'uint256', 'address'], [id, token, amount, to]);
+    }
+}
+exports.PodBridgeTrackerClient = PodBridgeTrackerClient;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { PodBridgeActionClient } from './clients/action/client';
+export { PodBridgeTrackerClient } from './clients/tracker/client';
+export { POD_BRIDGE_ABI } from './libs/abi/bridge.abi';
+export { PodBridgeConfig, BridgeRequest, BridgeRequestWithType, DepositType, UnsignedTransaction, CertifiedLog, } from './libs/types/pod-bridge.types';

package/dist/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DepositType = exports.POD_BRIDGE_ABI = exports.PodBridgeTrackerClient = exports.PodBridgeActionClient = void 0;
+var client_1 = require("./clients/action/client");
+Object.defineProperty(exports, "PodBridgeActionClient", { enumerable: true, get: function () { return client_1.PodBridgeActionClient; } });
+var client_2 = require("./clients/tracker/client");
+Object.defineProperty(exports, "PodBridgeTrackerClient", { enumerable: true, get: function () { return client_2.PodBridgeTrackerClient; } });
+var bridge_abi_1 = require("./libs/abi/bridge.abi");
+Object.defineProperty(exports, "POD_BRIDGE_ABI", { enumerable: true, get: function () { return bridge_abi_1.POD_BRIDGE_ABI; } });
+var pod_bridge_types_1 = require("./libs/types/pod-bridge.types");
+Object.defineProperty(exports, "DepositType", { enumerable: true, get: function () { return pod_bridge_types_1.DepositType; } });

package/dist/libs/abi/bridge.abi.d.ts

@@ -0,0 +1 @@
+export declare const POD_BRIDGE_ABI: string[];

package/dist/libs/abi/bridge.abi.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POD_BRIDGE_ABI = void 0;
+// Updated ABI with improved event signatures
+exports.POD_BRIDGE_ABI = [
+    // Improved Deposit events with indexed from/to and additional data
+    "event Deposit(uint256 indexed id, address indexed from, address indexed to, address token, uint256 amount, uint256 timestamp, uint256 blockNumber)",
+    "event DepositNative(uint256 indexed id, address indexed from, address indexed to, uint256 amount, uint256 timestamp, uint256 blockNumber)",
+    // Improved Claim events with indexed claimer/to
+    "event Claim(uint256 indexed id, address indexed claimer, address indexed to, address mirrorToken, address token, uint256 amount, uint256 timestamp)",
+    "event ClaimNative(uint256 indexed id, address indexed claimer, address indexed to, uint256 amount, uint256 timestamp)",
+    // Action functions
+    "function deposit(address token, uint256 amount, address to) returns (uint256)",
+    "function depositNative(address to) payable returns (uint256)",
+    "function claim(tuple(tuple(address addr, bytes32[] topics, bytes data) log, tuple(bytes32 r, bytes32 s, uint8 v)[] sigs) certifiedLog)",
+    "function claimNative(tuple(tuple(address addr, bytes32[] topics, bytes data) log, tuple(bytes32 r, bytes32 s, uint8 v)[] sigs) certifiedLog)",
+    "function claim(uint256 id, address token, uint256 blockNumber)",
+    "function claimNative(uint256 id, uint256 blockNumber)",
+    // View functions
+    "function processedRequests(bytes32) view returns (bool)",
+    "function bridgeContract() view returns (address)",
+    "function getSourceChainId() view returns (uint96)",
+    "function getDestinationChainId() view returns (uint256)",
+    "function getBridgeCounterpart() view returns (address)",
+    // Batch status checks
+    "function isRequestProcessed(uint256 id, address token, uint256 amount, address to) view returns (bool)",
+    "function areRequestsProcessed(uint256[] ids, address[] tokens, uint256[] amounts, address[] tos) view returns (bool[])",
+    // Finality checks (BridgeMintBurn only)
+    "function canBeClaimed(uint256 blockNumber) view returns (bool)",
+    "function canBeClaimedBatch(uint256[] blockNumbers) view returns (bool[])",
+];

package/dist/libs/types/pod-bridge.types.d.ts

@@ -0,0 +1,49 @@
+export interface PodBridgeChainConfig {
+    rpcUrl: string;
+    contractAddress: string;
+}
+export interface PodBridgeConfig {
+    source: PodBridgeChainConfig;
+    destination: PodBridgeChainConfig;
+}
+export interface BridgeRequest {
+    requestId: string;
+    blockNumber: number;
+    timestamp: number;
+    txHash: string;
+    from: string;
+    to: string;
+    token: string;
+    amount: string;
+    isClaimed: boolean;
+    claimedTxHash?: string;
+    claimedAt?: number;
+    claimedBy?: string;
+}
+export declare enum DepositType {
+    SENT = "sent",
+    RECEIVED = "received"
+}
+export interface BridgeRequestWithType extends BridgeRequest {
+    type: DepositType;
+}
+export interface UnsignedTransaction {
+    to: string;
+    data: string;
+    value: string;
+    from?: string;
+    chainId?: number;
+    gasLimit?: bigint;
+}
+export interface CertifiedLog {
+    log: {
+        addr: string;
+        topics: string[];
+        data: string;
+    };
+    sigs: Array<{
+        r: string;
+        s: string;
+        v: number;
+    }>;
+}

package/dist/libs/types/pod-bridge.types.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DepositType = void 0;
+var DepositType;
+(function (DepositType) {
+    DepositType["SENT"] = "sent";
+    DepositType["RECEIVED"] = "received";
+})(DepositType || (exports.DepositType = DepositType = {}));

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@tapforce/pod-bridge-sdk",
+  "version": "1.0.1",
+  "description": "SDK for interacting with Bridges between pod and other chains",
+  "keywords": [
+    "pod",
+    "bridge",
+    "sdk"
+  ],
+  "homepage": "https://github.com/tapforce/pod-ts-bridge-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/tapforce/pod-ts-bridge-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tapforce/pod-ts-bridge-sdk.git"
+  },
+  "license": "ISC",
+  "author": "Tapforce",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "directories": {
+    "example": "examples"
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "prepare": "npm run clean && npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "ethers": "^6.15.0",
+    "typescript": "^5.8.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.18",
+    "prettier": "3.5.3",
+    "rimraf": "^5.0.5"
+  }
+}