@tapforce/pod-bridge-sdk 1.1.17 → 1.2.2

package/README.md

@@ -1,387 +1,223 @@
 # Pod Bridge SDK
 
-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).
+TypeScript SDK for bridging ERC20 tokens between POD and EVM chains (e.g., Sepolia/ETH).
+
+## Architecture
+
+```
+ETH → Pod: Deposit on ETH, AUTO-CLAIM on Pod (no claim TX needed)
+Pod → ETH: Deposit on Pod, claim on ETH with aggregated validator signatures
+```
+
+**Key points:**
+- Only ERC20 tokens supported (wrap ETH to WETH first)
+- `Deposit.id` on source chain = `Claim.id` on destination chain (for tracking)
+- Token addresses differ between chains
 
 ## 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
-- 🔗 **Dual Architecture Support**: Handles both certificate-based (Source Chain) and precompile-based (POD) claim verification
+- **Bridge ERC20 Deposits**: Deposit tokens to the bridge
+- **Track Bridge Requests**: Query deposits sent/received by any address  
+- **Claim Status Tracking**: Monitor claim status and finality
+- **Transaction Building**: Generate unsigned transactions ready for signing
+- **Type-Safe**: Full TypeScript support
 
 ## Installation
 
 ```bash
 npm install @tapforce/pod-bridge-sdk
-```
-
-or
-
-```bash
+# or
 yarn add @tapforce/pod-bridge-sdk
-```
-
-or
-
-```bash
+# or
 pnpm add @tapforce/pod-bridge-sdk
 ```
 
 ## Quick Start
 
-### Import the SDK
-
 ```typescript
 import { 
   SourceChainToPodActionClient,
   PodToSourceChainActionClient,
   PodBridgeTrackerClient,
   PodBridgeConfig,
-  POD_BRIDGE_ABI,
-  SOURCE_CHAIN_BRIDGE_ABI
+  BRIDGE_ABI
 } from '@tapforce/pod-bridge-sdk';
 ```
 
-### Configuration
+## Configuration
 
-Create a configuration object with source and destination chain details:
+### For Action Clients (creating transactions)
 
 ```typescript
-const config: PodBridgeConfig = {
+import { PodBridgeActionsClientConfig } from '@tapforce/pod-bridge-sdk';
+
+const actionConfig: PodBridgeActionsClientConfig = {
   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)
+    contractAddress: '0x...' // Bridge contract on ETH/Sepolia
   },
   pod: {
-    rpcUrl: 'https://rpc.v1.dev.pod.network',
-    contractAddress: '0x...', // Destination chain bridge contract
-    deploymentBlock: 0        // Optional: POD deployment block
+    contractAddress: '0x...' // Bridge contract on Pod
   }
 };
 ```
 
-## Usage
-
-### 1. Action Clients - Creating Transactions
-
-The SDK provides two action clients for different bridge directions:
-
-- **`SourceChainToPodActionClient`**: For Source Chain → POD transfers (e.g., Sepolia → POD)
-- **`PodToSourceChainActionClient`**: For POD → Source Chain transfers (e.g., POD → Sepolia)
-
-#### Configuration for Action Clients
+### For Tracker Client (querying events)
 
 ```typescript
-const actionConfig = {
+import { PodBridgeConfig } from '@tapforce/pod-bridge-sdk';
+import { ethers } from 'ethers';
+
+const trackerConfig: PodBridgeConfig = {
   sourceChain: {
-    contractAddress: '0x...' // Source chain bridge contract (e.g., Sepolia)
+    provider: new ethers.JsonRpcProvider('https://sepolia.infura.io/v3/YOUR_KEY'),
+    contractAddress: '0x...',
+    deploymentBlock: 9502541 // Optional: avoids indexing empty blocks
   },
   pod: {
-    contractAddress: '0x...' // POD chain bridge contract
+    provider: new ethers.JsonRpcProvider('https://rpc.pod.network'),
+    contractAddress: '0x...',
+    deploymentBlock: 0
   }
 };
-
-const sourceChainToPodClient = new SourceChainToPodActionClient(actionConfig);
-const podToSourceChainClient = new PodToSourceChainActionClient(actionConfig);
 ```
 
-#### Deposit from Source Chain (e.g., Sepolia → POD)
-
-```typescript
-// 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
-  from: '0x...' // Optional: sender address
-});
-
-// Deposit native tokens
-const unsignedNativeTx = sourceChainToPodClient.depositNative({
-  amount: '1000000000000000000', // Amount in wei (1 ETH)
-  destinationWalletAddress: '0x...', // Recipient address on POD
-  from: '0x...' // Optional: sender address
-});
-
-// Sign and send transaction using your wallet/provider
-// const tx = await signer.sendTransaction(unsignedTx);
-```
+## Usage
 
-#### Claim on POD from Source Chain Deposits
+### ETH → Pod (Auto-claim)
 
-For claiming on POD from Source chain deposits, use block number-based claims:
+Deposits on ETH are automatically claimed on Pod after block finalization (~15 min on Sepolia).
 
 ```typescript
-// Create unsigned claim transaction for ERC20 on POD
-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
-  from: '0x...' // Optional: claimer address
-});
-
-// For native tokens
-const unsignedNativeTx = sourceChainToPodClient.claimNativeWithBlockNumber({
-  id: '123',
-  blockNumber: 12345678,
-  from: '0x...'
+const client = new SourceChainToPodActionClient(actionConfig);
+
+// Create deposit transaction
+const depositTx = client.deposit({
+  token: '0xWETH_ADDRESS',        // ERC20 token on ETH
+  amount: ethers.parseEther('1'),
+  destinationWalletAddress: '0x...', // Recipient on Pod
+  from: '0x...'                      // Optional
 });
-```
-
-#### Deposit from POD (POD → Source Chain)
 
-```typescript
-// Create unsigned transaction for ERC20 deposit on POD
-const unsignedTx = podToSourceChainClient.depositToken({
-  token: '0x...', // ERC20 token address
-  amount: '1000000000000000000', // Amount in wei
-  destinationWalletAddress: '0x...', // Recipient address on Source chain
-  from: '0x...' // Optional: sender address
-});
+// Send transaction
+const tx = await signer.sendTransaction(depositTx);
+const receipt = await tx.wait();
 
-// Deposit native tokens
-const unsignedNativeTx = podToSourceChainClient.depositNative({
-  amount: '1000000000000000000',
-  destinationWalletAddress: '0x...',
-  from: '0x...'
-});
+// No claim needed - balance auto-credited on Pod after finalization
 ```
 
-#### Claim on Source Chain from POD Deposits
+### Pod → ETH (Manual claim with signatures)
 
-For claiming on Source chain from POD deposits, use certificate-based claims. You'll need to get the certified log from an external indexer service:
+Deposits on Pod require manual claim on ETH with aggregated validator signatures.
 
 ```typescript
-import { PodIndexerHttpClient } from '@tapforce/pod-indexer-sdk';
-
-// Initialize the POD indexer client
-const indexerClient = new PodIndexerHttpClient({
-  apiUrl: 'YOUR_INDEXER_API_URL',
-  apiKey: 'YOUR_INDEXER_API_KEY'
-});
-
-// Get certified log from POD deposit transaction
-const certifiedLogResponse = await indexerClient.getBridgeCertifiedLog({
-  transactionHash: '0x...', // Transaction hash of deposit on POD
-  bridgeContractAddress: config.pod.contractAddress,
-  rpcUrl: config.pod.rpcUrl
-});
+const client = new PodToSourceChainActionClient(actionConfig);
 
-const certifiedLog = certifiedLogResponse.result;
-
-// Create unsigned claim transaction for ERC20 on Source chain
-const unsignedTx = podToSourceChainClient.claimWithCertificate({
-  certifiedLog,
-  from: '0x...' // Optional: claimer address
-});
-
-// For native tokens
-const unsignedNativeTx = podToSourceChainClient.claimNativeWithCertificate({
-  certifiedLog,
+// Step 1: Deposit on Pod
+const depositTx = client.deposit({
+  token: '0xPOD_TOKEN_ADDRESS',   // ERC20 token on Pod
+  amount: ethers.parseEther('1'),
+  destinationWalletAddress: '0x...', // Recipient on ETH
   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)
-);
+const tx = await podSigner.sendTransaction(depositTx);
+const receipt = await tx.wait();
 
-deposits.forEach(deposit => {
-  console.log(`Request ID: ${deposit.requestId}`);
-  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 && deposit.claim) {
-    console.log(`Claim Chain: ${deposit.claim.chain}`);
-    console.log(`Claimed by: ${deposit.claim.claimer}`);
-    console.log(`Claimed tx: ${deposit.claim.txHash}`);
-  }
+// Step 2: Get aggregated signatures from your indexer/API
+// (Implementation depends on your backend)
+
+// Step 3: Claim on ETH
+const claimTx = client.claim({
+  claimData: {
+    ethTokenAddress: '0xETH_TOKEN_ADDRESS', // Token on ETH (different from Pod)
+    amount: ethers.parseEther('1'),
+    to: '0x...',                            // Recipient
+    committeeEpoch: 0,                      // Hardcoded for now
+    aggregatedSignatures: '0x...',          // 65-byte signatures (r,s,v) concatenated
+    depositTxHash: tx.hash                  // Deposit TX hash from Pod
+  },
+  from: '0x...'
 });
-```
-
-#### 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}`);
-});
+const claim = await ethSigner.sendTransaction(claimTx);
 ```
 
-#### Check if Deposit Can Be Claimed
+### Tracking Deposits
 
 ```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!');
+const tracker = new PodBridgeTrackerClient(trackerConfig);
+
+// Get all deposits for an address
+const deposits = await tracker.getAllDepositsFor('0x...');
+
+for (const deposit of deposits) {
+  console.log('Request ID:', deposit.requestId);
+  console.log('Direction:', deposit.deposit.chain === 'sourceChain' ? 'ETH → Pod' : 'Pod → ETH');
+  console.log('From:', deposit.deposit.depositor);
+  console.log('To:', deposit.deposit.destination);
+  console.log('Token:', deposit.deposit.token);
+  console.log('Amount:', deposit.deposit.amount);
+  console.log('Claimed:', deposit.isClaimed);
+  console.log('Claimable:', deposit.isClaimable);
 }
-```
 
-#### Batch Check Processed Requests
+// Get deposits sent by address
+const sent = await tracker.getDepositsSentBy('0x...');
 
-```typescript
-// Check multiple deposits at once
-const deposits = await trackerClient.getDepositsSentBy('0x...');
-const processedStatuses = await trackerClient.areRequestsProcessed(deposits);
+// Get deposits received by address  
+const received = await tracker.getDepositsReceivedBy('0x...');
 
-processedStatuses.forEach((isProcessed, index) => {
-  console.log(`Deposit ${deposits[index].requestId} processed: ${isProcessed}`);
-});
+// Check if deposit can be claimed (Pod → ETH only)
+const canClaim = await tracker.canBeClaimed(deposit);
+
+// Batch check processed status
+const statuses = await tracker.areRequestsProcessed(deposits);
 ```
 
 ## API Reference
 
 ### SourceChainToPodActionClient
 
-Handles transactions for Source Chain → POD direction.
-
-#### Constructor
+For ETH → Pod deposits (auto-claim on Pod).
 
 ```typescript
-new SourceChainToPodActionClient(config: PodBridgeActionsClientConfig)
+// Deposit ERC20 tokens
+deposit(args: {
+  token: string;
+  amount: string | bigint;
+  destinationWalletAddress: string;
+  from?: string;
+}): UnsignedTransaction
 ```
 
-#### Methods
-
-- **`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 Source chain
-  - `amount`: Amount in wei (string | bigint)
-  - `destinationWalletAddress`: Recipient address on POD
-  - `from?`: Optional sender address
-
-- **`claimWithBlockNumber(args)`**: Create unsigned transaction for claiming on POD with block number
-  - `id`: Request ID
-  - `token`: Token address
-  - `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 Source chain
-  - `from?`: Optional claimer address
-
 ### PodToSourceChainActionClient
 
-Handles transactions for POD → Source Chain direction.
-
-#### Constructor
+For Pod → ETH deposits and claims.
 
 ```typescript
-new PodToSourceChainActionClient(config: PodBridgeActionsClientConfig)
-```
-
-#### Methods
-
-- **`depositToken(args)`**: Create unsigned transaction for ERC20 deposit on POD
-  - `token`: Token address
-  - `amount`: Amount in wei (string | bigint)
-  - `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 Source chain
-  - `from?`: Optional sender address
-
-- **`claimWithCertificate(args)`**: Create unsigned transaction for claiming on Source chain with certificate
-  - `certifiedLog`: Certified log from POD certificate system
-  - `from?`: Optional claimer address
+// Deposit ERC20 tokens on Pod
+deposit(args: {
+  token: string;
+  amount: string | bigint;
+  destinationWalletAddress: string;
+  from?: string;
+}): UnsignedTransaction
 
-- **`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
+// Claim on ETH with aggregated signatures
+claim(args: {
+  claimData: ClaimProofData;
+  from?: string;
+}): UnsignedTransaction
+```
 
 ### 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[]>`
-
-## ABIs
-
-The SDK exports two separate ABIs for the different bridge contract types:
-
-### POD_BRIDGE_ABI
-
-Used for the **BridgeMintBurn** contract on POD Chain:
-- Deposit functions: `deposit()`, `depositNative()`
-- Claim functions: `claim(uint256 id, address token, uint256 blockNumber)`, `claimNative(uint256 id, uint256 blockNumber)`
-- Claims use block number verification via POD precompiles
-- Events: `Deposit`, `DepositNative`, `Claim`, `ClaimNative`
-
-### SOURCE_CHAIN_BRIDGE_ABI
-
-Used for the **BridgeDepositWithdraw** contract on Source Chain (e.g., Sepolia):
-- Deposit functions: `deposit()`, `depositNative()`
-- Claim functions: `claim(CertifiedLog)`, `claimNative(CertifiedLog)`
-- Claims use POD certificate system with attestations and merkle proofs
-- Events: `Deposit`, `DepositNative`, `Claim`, `ClaimNative`
-
-Both are exported from the package and can be used with ethers.js:
-
 ```typescript
-import { POD_BRIDGE_ABI, SOURCE_CHAIN_BRIDGE_ABI } from '@tapforce/pod-bridge-sdk';
-import { ethers } from 'ethers';
-
-// Create contract interface
-const podBridge = new ethers.Contract(podAddress, POD_BRIDGE_ABI, provider);
-const sourceChainBridge = new ethers.Contract(sepoliaAddress, SOURCE_CHAIN_BRIDGE_ABI, provider);
+getDepositsSentBy(address: string, fromBlock?: number): Promise<BridgeRequest[]>
+getDepositsReceivedBy(address: string, fromBlock?: number): Promise<BridgeRequest[]>
+getAllDepositsFor(address: string, fromBlock?: number): Promise<BridgeRequestWithType[]>
+canBeClaimed(deposit: BridgeRequest): Promise<boolean>
+areRequestsProcessed(deposits: BridgeRequest[]): Promise<boolean[]>
 ```
 
 ## Types
@@ -389,264 +225,95 @@ const sourceChainBridge = new ethers.Contract(sepoliaAddress, SOURCE_CHAIN_BRIDG
 ### BridgeRequest
 
 ```typescript
-enum BridgeChain {
-  SOURCE_CHAIN = 'sourceChain',
-  POD = 'pod'
-}
-
 interface BridgeRequest {
   requestId: string;
   
-  // Deposit information
   deposit: {
-    chain: BridgeChain;        // Which chain the deposit occurred on
+    chain: 'sourceChain' | 'pod';
     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
+    depositor: string;
+    destination: string;
+    token: string;
+    amount: string;
     chainId: number;
-    blockNumber: number;       // Block number (for POD, this is essentially a timestamp)
-    timestamp: number;         // Unix timestamp
+    blockNumber: number;
+    timestamp: number;
   };
   
-  // Claim information (optional, only if claimed)
   claim?: {
-    chain: BridgeChain;        // Which chain the claim occurred on
+    chain: 'sourceChain' | 'pod';
     txHash: string;
-    claimer: string;           // Address that claimed
+    claimer: string;
     chainId: number;
-    blockNumber: number;       // Block number (for POD, this is essentially a timestamp)
-    timestamp: number;         // Unix timestamp
+    blockNumber: number;
+    timestamp: number;
   };
   
-  // Status
   isClaimed: boolean;
-  isClaimable: boolean;        // Can be claimed (finalized and not yet claimed)
+  isClaimable: boolean;
 }
 ```
 
-### UnsignedTransaction
+### ClaimProofData
 
 ```typescript
-interface UnsignedTransaction {
-  to: string;
-  data: string;
-  value: string;
-  from?: string;
-  chainId?: number;
-  gasLimit?: bigint;
+interface ClaimProofData {
+  ethTokenAddress: string;       // Token address on ETH (different from Pod)
+  amount: string | bigint;       // Same amount as deposited
+  to: string;                    // Recipient address
+  committeeEpoch: number;        // Hardcoded to 0 for now
+  aggregatedSignatures: string;  // Concatenated 65-byte ECDSA signatures (r,s,v)
+  depositTxHash: string;         // Deposit TX hash from Pod
 }
 ```
 
-### CertifiedLog
-
-```typescript
-interface CertifiedLog {
-  log: {
-    addr: string;
-    topics: string[];
-    data: string;
-  };
-  log_index: bigint | string;
-  certificate: {
-    leaf: string;
-    certified_receipt: {
-      receipt_root: string;
-      aggregate_signature: string;
-      sorted_attestation_timestamps: bigint[] | string[];
-    };
-    proof: {
-      path: string[];
-    };
-  };
-}
-```
-
-## Bridge Types
-
-The SDK supports two bridge implementations:
-
-1. **BridgeDepositWithdraw** (Certificate-based) - Source Chain
-   - Used for claiming on Source chain from POD deposits
-   - Requires certified logs from POD's certificate system via indexer
-   - Uses `SOURCE_CHAIN_BRIDGE_ABI`
-   - Methods: `claimWithCertificate`, `claimNativeWithCertificate`
-   - Certified logs include attestations, receipt root, aggregate signatures, and merkle proofs
-
-2. **BridgeMintBurn** (Precompile-based) - POD Chain
-   - Used for claiming on POD from Source chain deposits
-   - Uses block number verification via POD precompiles
-   - Uses `POD_BRIDGE_ABI`
-   - Methods: `claimWithBlockNumber`, `claimNativeWithBlockNumber`
-   - POD has instant finality (single-block architecture)
+### Signature Recovery Helpers
 
-## Examples
-
-### Complete Deposit and Claim Flow (Sepolia → POD)
+Pod uses 64-byte signatures without the parity bit (v), but the ETH contract requires 65-byte (r,s,v) format.
+The helpers exactly match the Rust implementation - they try both recovery IDs and verify against the public key.
 
 ```typescript
-import { ethers } from 'ethers';
-import { SourceChainToPodActionClient, PodBridgeTrackerClient } from '@tapforce/pod-bridge-sdk';
-
-// Setup
-const trackerConfig = {
-  sourceChain: {
-    rpcUrl: 'https://sepolia.infura.io/v3/YOUR_KEY',
-    contractAddress: '0xSepoliaBridgeContract'
-  },
-  pod: {
-    rpcUrl: 'https://rpc.v1.dev.pod.network',
-    contractAddress: '0xPodBridgeContract'
-  }
-};
-
-const actionConfig = {
-  sourceChain: { contractAddress: '0xSepoliaBridgeContract' },
-  pod: { contractAddress: '0xPodBridgeContract' }
-};
+import { 
+  extractAggregatedSignatures,
+  recoverSignature65B,
+  addressFromPublicKey 
+} from '@tapforce/pod-bridge-sdk';
 
-const actionClient = new SourceChainToPodActionClient(actionConfig);
-const trackerClient = new PodBridgeTrackerClient(trackerConfig);
-const sepoliaProvider = new ethers.JsonRpcProvider(trackerConfig.sourceChain.rpcUrl);
-const sepoliaSigner = new ethers.Wallet('PRIVATE_KEY', sepoliaProvider);
+// Recommended: Extract signatures directly from Pod receipt
+const podReceipt = await podProvider.send('eth_getTransactionReceipt', [depositTxHash]);
+const aggregatedSignatures = extractAggregatedSignatures(podReceipt, msgHash);
 
-// Step 1: Deposit tokens on Sepolia
-const depositTx = actionClient.depositToken({
-  token: '0xTokenAddress',
-  amount: ethers.parseEther('10').toString(),
-  destinationWalletAddress: await sepoliaSigner.getAddress()
-});
+// Low-level: Recover single signature (matches Rust recover_65b_signature)
+const sig65 = recoverSignature65B(
+  r,           // r component (32 bytes hex)
+  s,           // s component (32 bytes hex)
+  msgHash,     // message hash that was signed
+  publicKey    // signer's public key (to verify recovery)
+);
 
-const tx = await sepoliaSigner.sendTransaction(depositTx);
-await tx.wait();
-console.log(`Deposit tx: ${tx.hash}`);
-
-// Step 2: Track deposit
-const deposits = await trackerClient.getDepositsSentBy(await sepoliaSigner.getAddress());
-const latestDeposit = deposits[0];
-
-console.log(`Request ID: ${latestDeposit.requestId}`);
-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.deposit.token,
-    blockNumber: latestDeposit.deposit.blockNumber
-  });
-  
-  // Submit claim on POD
-  const podProvider = new ethers.JsonRpcProvider(trackerConfig.pod.rpcUrl);
-  const podSigner = new ethers.Wallet('PRIVATE_KEY', podProvider);
-  const claim = await podSigner.sendTransaction(claimTx);
-  await claim.wait();
-  console.log(`Claimed on POD: ${claim.hash}`);
-}
+// Utility: Derive address from public key
+const address = addressFromPublicKey(publicKey);
 ```
 
-### Complete Deposit and Claim Flow (POD → Sepolia)
-
-```typescript
-import { ethers } from 'ethers';
-import { PodToSourceChainActionClient, PodBridgeTrackerClient } from '@tapforce/pod-bridge-sdk';
-import { PodIndexerHttpClient } from '@tapforce/pod-indexer-sdk';
-
-// Setup
-const trackerConfig = {
-  sourceChain: {
-    rpcUrl: 'https://sepolia.infura.io/v3/YOUR_KEY',
-    contractAddress: '0xSepoliaBridgeContract'
-  },
-  pod: {
-    rpcUrl: 'https://rpc.v1.dev.pod.network',
-    contractAddress: '0xPodBridgeContract'
-  }
-};
-
-const actionConfig = {
-  sourceChain: { contractAddress: '0xSepoliaBridgeContract' },
-  pod: { contractAddress: '0xPodBridgeContract' }
-};
-
-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);
-
-// Initialize indexer client for getting certified logs
-const indexerClient = new PodIndexerHttpClient({
-  apiUrl: 'YOUR_INDEXER_API_URL',
-  apiKey: 'YOUR_INDEXER_API_KEY'
-});
-
-// Step 1: Deposit tokens on POD
-const depositTx = actionClient.depositToken({
-  token: '0xTokenAddress',
-  amount: ethers.parseEther('10').toString(),
-  destinationWalletAddress: await podSigner.getAddress()
-});
-
-const tx = await podSigner.sendTransaction(depositTx);
-const receipt = await tx.wait();
-console.log(`Deposit tx on POD: ${tx.hash}`);
-
-// Step 2: Get certified log from POD transaction using indexer
-const certifiedLogResponse = await indexerClient.getBridgeCertifiedLog({
-  transactionHash: tx.hash,
-  bridgeContractAddress: trackerConfig.pod.contractAddress,
-  rpcUrl: trackerConfig.pod.rpcUrl
-});
+## Events
 
-const certifiedLog = certifiedLogResponse.result;
-if (!certifiedLog) {
-  throw new Error('Certified log not found');
-}
-console.log('Got certified log with attestations');
+The bridge contract emits:
 
-// Step 3: Claim on Sepolia using certified log
-const claimTx = actionClient.claimWithCertificate({
-  certifiedLog,
-  from: await podSigner.getAddress()
-});
-
-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();
-console.log(`Claimed on Sepolia: ${claim.hash}`);
+```solidity
+event Deposit(bytes32 indexed id, address indexed from, address indexed to, address token, uint256 amount);
+event Claim(bytes32 indexed id, address indexed to, address token, uint256 amount);
 ```
 
 ## Development
 
-### Build
-
-```bash
-npm run build
-```
-
-### Clean
-
 ```bash
-npm run clean
+npm run build   # Build
+npm run clean   # Clean
 ```
 
 ## Dependencies
 
-- **ethers**: ^6.15.0 - Ethereum library for interacting with contracts
-- **typescript**: ^5.8.3 - TypeScript support
-
-### External Dependencies for Claims
-
-To claim tokens on Source Chain from POD deposits, you'll need:
-
-- **@tapforce/pod-indexer-sdk**: For retrieving certified logs from POD transactions
-
-```bash
-npm install @tapforce/pod-indexer-sdk
-```
+- **ethers**: ^6.15.0
 
 ## License
 
@@ -654,13 +321,5 @@ 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
+- [GitHub](https://github.com/tapforce/pod-ts-bridge-sdk)
+- [Issues](https://github.com/tapforce/pod-ts-bridge-sdk/issues)