@palindromepay/sdk 2.1.8 → 2.1.9

package/dist/PalindromePaySDK.d.ts

@@ -269,6 +269,14 @@ export declare class PalindromePaySDK {
      * Execute an async operation with retry logic.
      */
     private withRetry;
+    /**
+     * Execute a contract read with retry on transient RPC failures.
+     *
+     * Idempotent reads are safe to retry, so they honour the same
+     * enableRetry/maxRetries/retryDelay config as writes. On a persistent
+     * failure the original error is propagated unchanged (no API change).
+     */
+    private read;
     /**
      * Extract error message from unknown error type.
      */
@@ -360,13 +368,35 @@ export declare class PalindromePaySDK {
      */
     predictWalletAddress(escrowId: bigint): Promise<Address>;
     /**
-     * Get raw escrow data from contract
+     * Build the LRU cache key for an escrow's raw on-chain data.
+     */
+    private escrowCacheKey;
+    /**
+     * Drop all cached data for an escrow. Called after any write that may
+     * change the escrow's on-chain state so subsequent reads from this SDK
+     * instance never observe stale data.
+     */
+    private invalidateEscrow;
+    /**
+     * Get raw escrow data from contract.
+     *
+     * Results are cached in the LRU cache for `cacheTTL` ms to de-duplicate
+     * rapid repeated reads (e.g. a UI rendering several components for the same
+     * escrow). Writes that mutate the escrow invalidate this entry, and callers
+     * that require strictly fresh data (all write pre-flight checks) pass
+     * `forceRefresh = true`.
+     *
+     * @param escrowId - The escrow ID
+     * @param forceRefresh - Bypass the cache and read fresh from chain
      */
-    getEscrowById(escrowId: bigint): Promise<RawEscrowData>;
+    getEscrowById(escrowId: bigint, forceRefresh?: boolean): Promise<RawEscrowData>;
     /**
-     * Get parsed escrow data
+     * Get parsed escrow data.
+     *
+     * @param escrowId - The escrow ID
+     * @param forceRefresh - Bypass the cache and read fresh from chain
      */
-    getEscrowByIdParsed(escrowId: bigint): Promise<EscrowData>;
+    getEscrowByIdParsed(escrowId: bigint, forceRefresh?: boolean): Promise<EscrowData>;
     /**
      * Get next escrow ID
      */

package/dist/PalindromePaySDK.js

@@ -337,21 +337,24 @@ class PalindromePaySDK {
      * Wait for transaction receipt with timeout and retry logic.
      */
     async waitForReceipt(hash) {
-        const receipt = await this.withRetry(async () => {
-            try {
-                return await this.publicClient.waitForTransactionReceipt({
-                    hash,
-                    timeout: this.receiptTimeout,
-                });
-            }
-            catch (error) {
-                const errorMessage = isViemError(error) ? error.message : String(error);
-                if (errorMessage.includes("timed out") || errorMessage.includes("timeout")) {
-                    throw new SDKError(`Transaction receipt timeout after ${this.receiptTimeout}ms`, SDKErrorCode.TRANSACTION_FAILED, { hash });
-                }
-                throw error;
+        // Retry the raw receipt wait so transient timeouts get another attempt.
+        // The timeout is only converted to a (non-retryable) SDKError after all
+        // attempts are exhausted — throwing the SDKError inside withRetry would
+        // short-circuit the retry loop (see withRetry's errorName === "SDKError" guard).
+        let receipt;
+        try {
+            receipt = await this.withRetry(() => this.publicClient.waitForTransactionReceipt({
+                hash,
+                timeout: this.receiptTimeout,
+            }), "waitForTransactionReceipt");
+        }
+        catch (error) {
+            const errorMessage = isViemError(error) ? error.message : String(error);
+            if (errorMessage.includes("timed out") || errorMessage.includes("timeout")) {
+                throw new SDKError(`Transaction receipt timeout after ${this.receiptTimeout}ms`, SDKErrorCode.TRANSACTION_FAILED, { hash });
             }
-        }, "waitForTransactionReceipt");
+            throw error;
+        }
         // Check receipt status (post-Byzantium: status 'reverted' means on-chain failure)
         if (receipt.status === "reverted") {
             throw new SDKError(`Transaction reverted on-chain (hash: ${hash})`, SDKErrorCode.TRANSACTION_FAILED, { hash, blockNumber: receipt.blockNumber });
@@ -388,6 +391,16 @@ class PalindromePaySDK {
         }
         throw lastError ?? new SDKError(`${operationName} failed after ${this.maxRetries} attempts`, SDKErrorCode.RPC_ERROR);
     }
+    /**
+     * Execute a contract read with retry on transient RPC failures.
+     *
+     * Idempotent reads are safe to retry, so they honour the same
+     * enableRetry/maxRetries/retryDelay config as writes. On a persistent
+     * failure the original error is propagated unchanged (no API change).
+     */
+    async read(params) {
+        return this.withRetry(async () => (await (0, actions_1.readContract)(this.publicClient, params)), `read:${params.functionName}`);
+    }
     /**
      * Extract error message from unknown error type.
      */
@@ -690,34 +703,67 @@ class PalindromePaySDK {
      * Calls the contract's computeWalletAddress function - single source of truth
      */
     async predictWalletAddress(escrowId) {
-        const predicted = await (0, actions_1.readContract)(this.publicClient, {
+        return this.read({
             address: this.contractAddress,
             abi: PalindromePay_json_1.default.abi,
             functionName: "computeWalletAddress",
             args: [escrowId],
         });
-        return predicted;
     }
     // ==========================================================================
     // ESCROW DATA READING
     // ==========================================================================
     /**
-     * Get raw escrow data from contract
+     * Build the LRU cache key for an escrow's raw on-chain data.
      */
-    async getEscrowById(escrowId) {
-        const raw = await (0, actions_1.readContract)(this.publicClient, {
+    escrowCacheKey(escrowId) {
+        return `escrow-${escrowId}`;
+    }
+    /**
+     * Drop all cached data for an escrow. Called after any write that may
+     * change the escrow's on-chain state so subsequent reads from this SDK
+     * instance never observe stale data.
+     */
+    invalidateEscrow(escrowId) {
+        this.escrowCache.delete(this.escrowCacheKey(escrowId));
+        this.escrowCache.delete(`status-${escrowId}`);
+    }
+    /**
+     * Get raw escrow data from contract.
+     *
+     * Results are cached in the LRU cache for `cacheTTL` ms to de-duplicate
+     * rapid repeated reads (e.g. a UI rendering several components for the same
+     * escrow). Writes that mutate the escrow invalidate this entry, and callers
+     * that require strictly fresh data (all write pre-flight checks) pass
+     * `forceRefresh = true`.
+     *
+     * @param escrowId - The escrow ID
+     * @param forceRefresh - Bypass the cache and read fresh from chain
+     */
+    async getEscrowById(escrowId, forceRefresh = false) {
+        const cacheKey = this.escrowCacheKey(escrowId);
+        if (!forceRefresh) {
+            const cached = this.getCacheValue(cacheKey);
+            if (cached)
+                return cached;
+        }
+        const raw = await this.read({
             address: this.contractAddress,
             abi: this.abiEscrow,
             functionName: "getEscrow",
             args: [escrowId],
         });
+        this.setCacheValue(cacheKey, raw);
         return raw;
     }
     /**
-     * Get parsed escrow data
+     * Get parsed escrow data.
+     *
+     * @param escrowId - The escrow ID
+     * @param forceRefresh - Bypass the cache and read fresh from chain
      */
-    async getEscrowByIdParsed(escrowId) {
-        const raw = await this.getEscrowById(escrowId);
+    async getEscrowByIdParsed(escrowId, forceRefresh = false) {
+        const raw = await this.getEscrowById(escrowId, forceRefresh);
         return {
             token: raw.token,
             buyer: raw.buyer,
@@ -741,7 +787,7 @@ class PalindromePaySDK {
      * Get next escrow ID
      */
     async getNextEscrowId() {
-        return (0, actions_1.readContract)(this.publicClient, {
+        return this.read({
             address: this.contractAddress,
             abi: this.abiEscrow,
             functionName: "nextEscrowId",
@@ -761,7 +807,7 @@ class PalindromePaySDK {
      * @returns The bitmap as a bigint
      */
     async getNonceBitmap(escrowId, signer, wordIndex = 0n) {
-        return this.publicClient.readContract({
+        return this.read({
             address: this.contractAddress,
             abi: this.abiEscrow,
             functionName: "getNonceBitmap",
@@ -961,7 +1007,7 @@ class PalindromePaySDK {
      * Get dispute submission status
      */
     async getDisputeSubmissionStatus(escrowId) {
-        const status = await this.publicClient.readContract({
+        const status = await this.read({
             address: this.contractAddress,
             abi: this.abiEscrow,
             functionName: "disputeStatus",
@@ -979,7 +1025,7 @@ class PalindromePaySDK {
         if (this.tokenDecimalsCache.has(tokenAddress)) {
             return this.tokenDecimalsCache.get(tokenAddress);
         }
-        const decimals = await this.publicClient.readContract({
+        const decimals = await this.read({
             address: tokenAddress,
             abi: this.abiERC20,
             functionName: "decimals",
@@ -988,7 +1034,7 @@ class PalindromePaySDK {
         return decimals;
     }
     async getTokenBalance(account, tokenAddress) {
-        return this.publicClient.readContract({
+        return this.read({
             address: tokenAddress,
             abi: this.abiERC20,
             functionName: "balanceOf",
@@ -996,7 +1042,7 @@ class PalindromePaySDK {
         });
     }
     async getTokenAllowance(owner, spender, tokenAddress) {
-        return this.publicClient.readContract({
+        return this.read({
             address: tokenAddress,
             abi: this.abiERC20,
             functionName: "allowance",
@@ -1301,7 +1347,7 @@ class PalindromePaySDK {
      */
     async deposit(walletClient, escrowId) {
         assertWalletClient(walletClient);
-        const deal = await this.getEscrowByIdParsed(escrowId);
+        const deal = await this.getEscrowByIdParsed(escrowId, true);
         // Verify caller and state using helpers
         this.verifyBuyer(walletClient.account.address, deal);
         this.verifyState(deal, EscrowState.AWAITING_PAYMENT, "deposit");
@@ -1322,6 +1368,7 @@ class PalindromePaySDK {
             args: [escrowId, buyerWalletSig],
         });
         await this.waitForReceipt(hash);
+        this.invalidateEscrow(escrowId);
         // Verify buyer signature is valid on-chain after deposit
         let buyerSigValid = false;
         try {
@@ -1369,7 +1416,7 @@ class PalindromePaySDK {
      */
     async acceptEscrow(walletClient, escrowId) {
         assertWalletClient(walletClient);
-        const deal = await this.getEscrowByIdParsed(escrowId);
+        const deal = await this.getEscrowByIdParsed(escrowId, true);
         // Verify caller and state using helpers
         this.verifySeller(walletClient.account.address, deal);
         this.verifyState(deal, EscrowState.AWAITING_DELIVERY, "accept");
@@ -1392,6 +1439,7 @@ class PalindromePaySDK {
             args: [escrowId, sellerWalletSig],
         });
         await this.waitForReceipt(hash);
+        this.invalidateEscrow(escrowId);
         // Verify seller signature is valid on-chain after accept
         let sellerSigValid = false;
         try {
@@ -1440,7 +1488,7 @@ class PalindromePaySDK {
      */
     async confirmDelivery(walletClient, escrowId) {
         assertWalletClient(walletClient);
-        const deal = await this.getEscrowByIdParsed(escrowId);
+        const deal = await this.getEscrowByIdParsed(escrowId, true);
         // Verify caller and state using helpers
         this.verifyBuyer(walletClient.account.address, deal);
         this.verifyState(deal, EscrowState.AWAITING_DELIVERY, "confirm delivery");
@@ -1459,6 +1507,7 @@ class PalindromePaySDK {
             args: [escrowId, buyerWalletSig],
         });
         await this.waitForReceipt(hash);
+        this.invalidateEscrow(escrowId);
         return hash;
     }
     /**
@@ -1492,6 +1541,7 @@ class PalindromePaySDK {
             args: [escrowId, coordSignature, deadline, nonce, buyerWalletSig],
         });
         await this.waitForReceipt(hash);
+        this.invalidateEscrow(escrowId);
         return hash;
     }
     /**
@@ -1549,7 +1599,7 @@ class PalindromePaySDK {
      */
     async requestCancel(walletClient, escrowId) {
         assertWalletClient(walletClient);
-        const deal = await this.getEscrowByIdParsed(escrowId);
+        const deal = await this.getEscrowByIdParsed(escrowId, true);
         // Verify caller is buyer or seller
         const isBuyer = addressEquals(walletClient.account.address, deal.buyer);
         const isSeller = addressEquals(walletClient.account.address, deal.seller);
@@ -1575,6 +1625,7 @@ class PalindromePaySDK {
             args: [escrowId, walletSig],
         });
         await this.waitForReceipt(hash);
+        this.invalidateEscrow(escrowId);
         return hash;
     }
     /**
@@ -1598,7 +1649,7 @@ class PalindromePaySDK {
      */
     async cancelByTimeout(walletClient, escrowId) {
         assertWalletClient(walletClient);
-        const deal = await this.getEscrowByIdParsed(escrowId);
+        const deal = await this.getEscrowByIdParsed(escrowId, true);
         // Verify caller using helper
         this.verifyBuyer(walletClient.account.address, deal);
         // Cancel by timeout
@@ -1609,6 +1660,7 @@ class PalindromePaySDK {
             args: [escrowId],
         });
         await this.waitForReceipt(hash);
+        this.invalidateEscrow(escrowId);
         return hash;
     }
     /**
@@ -1638,7 +1690,7 @@ class PalindromePaySDK {
      */
     async autoRelease(walletClient, escrowId) {
         assertWalletClient(walletClient);
-        const deal = await this.getEscrowByIdParsed(escrowId);
+        const deal = await this.getEscrowByIdParsed(escrowId, true);
         // Verify caller and state using helpers
         this.verifySeller(walletClient.account.address, deal);
         this.verifyState(deal, EscrowState.AWAITING_DELIVERY, "auto-release");
@@ -1666,6 +1718,7 @@ class PalindromePaySDK {
             args: [escrowId],
         });
         await this.waitForReceipt(hash);
+        this.invalidateEscrow(escrowId);
         return hash;
     }
     // ==========================================================================
@@ -1701,6 +1754,7 @@ class PalindromePaySDK {
             args: [escrowId],
         });
         await this.waitForReceipt(hash);
+        this.invalidateEscrow(escrowId);
         return hash;
     }
     /**
@@ -1733,6 +1787,7 @@ class PalindromePaySDK {
             args: [escrowId, signature, deadline, nonce],
         });
         await this.waitForReceipt(hash);
+        this.invalidateEscrow(escrowId);
         return hash;
     }
     /**
@@ -1770,6 +1825,7 @@ class PalindromePaySDK {
             args: [escrowId, role, ipfsHash],
         });
         await this.waitForReceipt(hash);
+        this.invalidateEscrow(escrowId);
         return hash;
     }
     /**
@@ -1799,7 +1855,7 @@ class PalindromePaySDK {
      */
     async submitArbiterDecision(walletClient, escrowId, resolution, ipfsHash) {
         assertWalletClient(walletClient);
-        const deal = await this.getEscrowByIdParsed(escrowId);
+        const deal = await this.getEscrowByIdParsed(escrowId, true);
         // Verify caller using helper
         this.verifyArbiter(walletClient.account.address, deal);
         // Sign wallet authorization
@@ -1817,6 +1873,7 @@ class PalindromePaySDK {
             args: [escrowId, resolution, ipfsHash, arbiterWalletSig],
         });
         await this.waitForReceipt(hash);
+        this.invalidateEscrow(escrowId);
         return hash;
     }
     // ==========================================================================
@@ -1844,7 +1901,7 @@ class PalindromePaySDK {
      */
     async withdraw(walletClient, escrowId) {
         assertWalletClient(walletClient);
-        const deal = await this.getEscrowByIdParsed(escrowId);
+        const deal = await this.getEscrowByIdParsed(escrowId, true);
         // Verify final state
         if (![EscrowState.COMPLETE, EscrowState.REFUNDED, EscrowState.CANCELED].includes(deal.state)) {
             throw new SDKError(`Cannot withdraw in state: ${this.STATE_NAMES[deal.state]}`, SDKErrorCode.INVALID_STATE);
@@ -1857,6 +1914,7 @@ class PalindromePaySDK {
             args: [],
         });
         await this.waitForReceipt(hash);
+        this.invalidateEscrow(escrowId);
         return hash;
     }
     /**
@@ -1864,7 +1922,7 @@ class PalindromePaySDK {
      */
     async getWalletSignatureCount(escrowId) {
         const deal = await this.getEscrowByIdParsed(escrowId);
-        const count = await this.publicClient.readContract({
+        const count = await this.read({
             address: deal.wallet,
             abi: this.abiWallet,
             functionName: "getValidSignatureCount",
@@ -1876,7 +1934,7 @@ class PalindromePaySDK {
      */
     async getWalletBalance(escrowId) {
         const deal = await this.getEscrowByIdParsed(escrowId);
-        return this.publicClient.readContract({
+        return this.read({
             address: deal.wallet,
             abi: this.abiWallet,
             functionName: "getBalance",
@@ -2839,7 +2897,7 @@ class PalindromePaySDK {
         if (!forceRefresh && this.feeReceiverCache) {
             return this.feeReceiverCache;
         }
-        this.feeReceiverCache = await this.publicClient.readContract({
+        this.feeReceiverCache = await this.read({
             address: this.contractAddress,
             abi: this.abiEscrow,
             functionName: "FEE_RECEIVER",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palindromepay/sdk",
-  "version": "2.1.8",
+  "version": "2.1.9",
   "description": "TypeScript SDK for PalindromeCryptoEscrow - Secure blockchain escrow with buyer/seller protection",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",