@tapforce/pod-bridge-sdk 1.2.3 → 1.2.4

package/README.md

@@ -110,6 +110,11 @@ const receipt = await tx.wait();
 Deposits on Pod require manual claim on ETH with aggregated validator signatures.
 
 ```typescript
+import { 
+  PodToSourceChainActionClient,
+  extractAggregatedSignaturesWithValidators 
+} from '@tapforce/pod-bridge-sdk';
+
 const client = new PodToSourceChainActionClient(actionConfig);
 
 // Step 1: Deposit on Pod
@@ -123,17 +128,26 @@ const depositTx = client.deposit({
 const tx = await podSigner.sendTransaction(depositTx);
 const receipt = await tx.wait();
 
-// Step 2: Get aggregated signatures from your indexer/API
-// (Implementation depends on your backend)
+// Step 2: Get the receipt with validator signatures
+const podReceipt = await podProvider.send('eth_getTransactionReceipt', [tx.hash]);
+
+// Step 3: Get committee for v-value recovery
+const committee = await podProvider.send('pod_getCommittee', {});
 
-// Step 3: Claim on ETH
+// Step 4: Extract aggregated signatures (65-byte format with correct v-values)
+const aggregatedSignatures = extractAggregatedSignaturesWithValidators(
+  podReceipt,
+  committee.validators  // [[0, "02..."], [1, "03..."], ...] compressed pubkeys
+);
+
+// Step 5: 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
+    aggregatedSignatures,                   // 65-byte signatures (r,s,v) concatenated
     depositTxHash: tx.hash                  // Deposit TX hash from Pod
   },
   from: '0x...'
@@ -269,30 +283,68 @@ interface ClaimProofData {
 
 ### Signature Recovery Helpers
 
-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.
+Pod returns DER-encoded 64-byte signatures without the parity bit (v), but the ETH contract requires 65-byte (r,s,v) format.
+The SDK handles this by trying both v values (27/28) and verifying against the committee's validator public keys.
 
 ```typescript
 import { 
+  extractAggregatedSignaturesWithValidators,
   extractAggregatedSignatures,
-  recoverSignature65B,
-  addressFromPublicKey 
+  parseDerSignature,
+  addressFromPublicKey,
+  recoverSignatureWithoutPubkey
 } from '@tapforce/pod-bridge-sdk';
 
-// Recommended: Extract signatures directly from Pod receipt
+// Recommended: Extract with validator verification (correct v-values)
 const podReceipt = await podProvider.send('eth_getTransactionReceipt', [depositTxHash]);
-const aggregatedSignatures = extractAggregatedSignatures(podReceipt, msgHash);
-
-// 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 committee = await podProvider.send('pod_getCommittee', {});
+const aggregatedSignatures = extractAggregatedSignaturesWithValidators(
+  podReceipt,
+  committee.validators  // [[index, compressedPubKey], ...]
 );
 
-// Utility: Derive address from public key
-const address = addressFromPublicKey(publicKey);
+// Alternative: Extract without validator verification (may have wrong v-values)
+const sigs = extractAggregatedSignatures(podReceipt);
+
+// Low-level: Parse DER signature to r,s components
+const { r, s } = parseDerSignature(derEncodedSig);
+
+// Low-level: Recover 65-byte signature without pubkey (tries v=27 first)
+const sig65 = recoverSignatureWithoutPubkey(r, s, msgHash);
+
+// Utility: Derive address from uncompressed public key
+const address = addressFromPublicKey(uncompressedPubKey);
+```
+
+#### Pod Receipt Format
+
+```typescript
+interface PodTransactionReceipt {
+  // ... standard fields ...
+  attested_tx: {
+    hash: string;           // Hash signed by validators
+    committee_epoch: number;
+  };
+  signatures: {
+    "0": string;  // DER-encoded signature from validator 0
+    "1": string;  // DER-encoded signature from validator 1
+    // ...
+  };
+}
+```
+
+#### Committee Format
+
+```typescript
+// pod_getCommittee response
+{
+  validators: [
+    [0, "024ee7..."],  // [index, compressed_secp256k1_pubkey]
+    [1, "025c59..."],
+    // ...
+  ],
+  quorum_size: 3
+}
 ```
 
 ## Events

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tapforce/pod-bridge-sdk",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "description": "SDK for interacting with Bridges between pod and other chains",
   "keywords": [
     "pod",