@palindromepay/sdk 1.9.4 → 1.9.6

package/LICENCE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Palindrome Finance
+Copyright (c) 2025 Palindrome Pay
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,10 +1,10 @@
-# PalindromeEscrowSDK
+# PalindromePay SDK
 
-[![npm version](https://img.shields.io/npm/v/@palindromecryptoescrow/sdk.svg)](https://www.npmjs.com/package/@palindromecryptoescrow/sdk)
+[![npm version](https://img.shields.io/npm/v/@palindromepay/sdk.svg)](https://www.npmjs.com/package/@palindromepay/sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Documentation](https://img.shields.io/badge/docs-sdk.palindromefinance.com-blue)](https://sdk.palindromefinance.com)
 
-A TypeScript/Node SDK for interacting with the PalindromeCryptoEscrow smart contract and subgraph, including signature flows, event utilities, token helpers, and robust error handling.
+A TypeScript/Node SDK for interacting with the PalindromePay escrow smart contract and subgraph, including signature flows, event utilities, token helpers, and robust error handling.
 
 ---
 
@@ -25,273 +25,14 @@ A TypeScript/Node SDK for interacting with the PalindromeCryptoEscrow smart cont
 - Flexible error classes and codes for wallet/client state
 - Utilities for fee calculation, token formatting, deadlines, and maturity times
 - Gas estimation helpers for transaction planning
-- Comprehensive state and role validation helpers (v1.9.3+)
+- Comprehensive state and role validation helpers
 
 ---
 
 ## 📦 Installation
 
 ```bash
-npm install @palindromecryptoescrow/sdk
-```
-
-## 🚀 Quick Start
-
-```typescript
-import { PalindromeEscrowSDK } from '@palindromecryptoescrow/sdk';
-import { createPublicClient, createWalletClient, http } from 'viem';
-
-// Create clients
-const publicClient = createPublicClient({
-  chain: yourChain,
-  transport: http()
-});
-
-const walletClient = createWalletClient({
-  chain: yourChain,
-  transport: http(),
-  account: yourAccount
-});
-
-// Initialize SDK
-const sdk = new PalindromeEscrowSDK({
-  publicClient,
-  walletClient,
-  contractAddress: '0x...',
-  subgraphUrl: 'https://...'
-});
-
-// Create an escrow
-const escrow = await sdk.createEscrow({
-  token: '0x...', // ERC20 token address
-  buyer: '0x...', // Buyer address
-  amount: 1000000n, // Amount in smallest unit
-  maturityDays: 7n, // 7 days until auto-release
-  arbiter: '0x...', // Optional arbiter
-  title: 'Purchase of Product X',
-  ipfsHash: 'Qm...' // Optional IPFS metadata
-});
-```
-
----
-
-## ⚠️ Token Compatibility
-
-**CRITICAL: Not all ERC20 tokens are compatible with this escrow system.**
-
-### ✅ Supported Tokens
-
-The escrow contract works correctly with **standard ERC20 tokens** that:
-- Transfer the exact amount specified (no fees on transfer)
-- Have fixed supply (no rebasing)
-- Cannot be paused by admin once deposited
-- Do not have address blocklists
-
-**Examples of Safe Tokens:**
-- DAI
-- WETH
-- Standard ERC20 tokens without special features
-
-### ❌ Unsupported Tokens
-
-**1. Fee-on-Transfer Tokens**
-- **What:** Tokens that deduct a fee during transfers
-- **Why Unsafe:** Escrow will receive less than the deposit amount, breaking accounting
-- **Examples:** SafeMoon, PAXG, some tax tokens
-- **Risk Level:** 🔴 CRITICAL - Will cause fund loss
-
-**2. Rebasing Tokens**
-- **What:** Tokens whose balance changes automatically over time
-- **Why Unsafe:** Escrow balance will change unexpectedly, breaking release amounts
-- **Examples:** stETH, AMPL, OHM
-- **Risk Level:** 🔴 CRITICAL - Unpredictable outcomes
-
-**3. Pausable Tokens**
-- **What:** Tokens that can be paused by admin, freezing all transfers
-- **Why Unsafe:** Escrow may become permanently locked if token is paused
-- **Examples:** USDC, USDT (admin can pause)
-- **Risk Level:** 🟡 MEDIUM - Temporary freeze possible
-- **Mitigation:** Only use with trusted token issuers
-
-**4. Blocklist Tokens**
-- **What:** Tokens where admin can blocklist specific addresses
-- **Why Unsafe:** Escrow wallet could be blocklisted, freezing funds
-- **Examples:** USDC, USDT (admin can blocklist)
-- **Risk Level:** 🟡 MEDIUM - Funds could be frozen
-- **Mitigation:** Only use with trusted token issuers
-
-### 🔍 How to Check Token Compatibility
-
-```typescript
-// Use the SDK to verify token decimals and basic functionality
-const decimals = await sdk.getTokenDecimals(tokenAddress);
-const balance = await sdk.getTokenBalance(userAddress, tokenAddress);
-
-// For production, additionally check:
-// 1. Token contract source code for transfer fees
-// 2. Token documentation for rebasing mechanics
-// 3. Token admin capabilities (pause, blocklist)
-```
-
-**Best Practice:** Always test with small amounts first on mainnet or use testnet for new tokens.
-
----
-
-## 🌐 Rate Limiting Best Practices
-
-### RPC Provider Limits
-
-The SDK makes multiple RPC calls for operations like:
-- Creating escrows (3-5 calls)
-- Fetching multiple nonces (1-20+ calls depending on count)
-- Batch operations (N calls per item)
-
-**Recommended RPC Providers & Limits:**
-
-| Provider | Free Tier | Recommended Plan | Notes |
-|----------|-----------|------------------|-------|
-| Alchemy | 300M CU/month | Growth ($49/mo) | Best for production |
-| Infura | 100k req/day | Developer ($50/mo) | Good reliability |
-| QuickNode | 10M credits | Pro ($49/mo) | Low latency |
-
-### SDK Rate Limiting Features
-
-The SDK includes built-in optimizations:
-- **Multicall support:** Batches multiple reads into one RPC call (when supported)
-- **Caching:** Fee receiver, decimals, multicall support cached
-- **Efficient nonce fetching:** Automatically uses multicall for bulk nonce queries
-
-### Implementing Your Own Rate Limiting
-
-```typescript
-// Example: Rate limit with p-queue
-import PQueue from 'p-queue';
-
-const queue = new PQueue({
-  concurrency: 5,  // Max 5 concurrent requests
-  interval: 1000,  // Per second
-  intervalCap: 10  // Max 10 requests per interval
-});
-
-// Wrap SDK calls
-const escrow = await queue.add(() =>
-  sdk.getEscrowByIdParsed(escrowId)
-);
-```
-
-### Monitoring RPC Usage
-
-```typescript
-// Enable debug logging to monitor RPC calls
-const sdk = new PalindromeEscrowSDK({
-  // ... other config
-  logger: customLogger, // Implement custom logger to track calls
-  logLevel: 'debug'
-});
-```
-
-**Production Tip:** Use a dedicated RPC endpoint with higher limits for user-facing applications.
-
----
-
-## ⛽ Gas Estimation
-
-The SDK provides gas estimation helpers to help users plan transaction costs:
-
-### Estimating Gas for Operations
-
-```typescript
-// Estimate gas for creating an escrow
-const gasEstimate = await sdk.estimateGasForCreateEscrow({
-  token: tokenAddress,
-  buyer: buyerAddress,
-  amount: 1000000n,
-  maturityDays: 7n,
-  arbiter: arbiterAddress,
-  title: 'Test Escrow',
-  ipfsHash: ''
-});
-
-console.log(`Estimated gas: ${gasEstimate.gasLimit}`);
-console.log(`Estimated cost: ${gasEstimate.estimatedCostWei} wei`);
-console.log(`Estimated cost: ${gasEstimate.estimatedCostEth} ETH`);
-
-// Estimate gas for deposit
-const depositGas = await sdk.estimateGasForDeposit(escrowId);
-
-// Estimate gas for confirm delivery
-const confirmGas = await sdk.estimateGasForConfirmDelivery(escrowId);
-```
-
-### Gas Price Information
-
-```typescript
-// Get current gas prices
-const gasPrice = await sdk.getCurrentGasPrice();
-console.log(`Current gas price: ${gasPrice.standard} gwei`);
-console.log(`Fast: ${gasPrice.fast} gwei`);
-console.log(`Instant: ${gasPrice.instant} gwei`);
-```
-
-### Setting Custom Gas Limits
-
-```typescript
-const sdk = new PalindromeEscrowSDK({
-  // ... other config
-  defaultGasLimit: 500000n // Custom gas limit for all transactions
-});
-```
-
----
-
-## 🛡️ Security Best Practices
-
-1. **Always validate addresses** before creating escrows
-2. **Use arbiter for high-value transactions**
-3. **Set appropriate maturity times** (7-30 days recommended)
-4. **Test with small amounts first**
-5. **Verify token compatibility** before using (see Token Compatibility section)
-6. **Monitor for pausable/blocklist tokens**
-
----
-
-## 📚 API Reference
-
-### Helper Methods (New in v1.9.3)
-
-#### State Validation Helpers
-```typescript
-// Check if user can deposit
-const canDeposit = await sdk.canUserDeposit(userAddress, escrowId);
-
-// Check if user can accept escrow
-const canAccept = await sdk.canUserAcceptEscrow(userAddress, escrowId);
-
-// Check if user can confirm delivery
-const canConfirm = await sdk.canUserConfirmDelivery(userAddress, escrowId);
-
-// Check if user can start dispute
-const canDispute = await sdk.canUserStartDispute(userAddress, escrowId);
-
-// Check if escrow can be auto-released
-const canWithdraw = await sdk.canUserWithdraw(escrowId);
-
-// Check if seller can auto-release
-const canAutoRelease = await sdk.canSellerAutoRelease(userAddress, escrowId);
-```
-
-#### Role Validation Helpers
-```typescript
-const escrow = await sdk.getEscrowByIdParsed(escrowId);
-
-// Check roles
-const isBuyer = sdk.isBuyer(userAddress, escrow);
-const isSeller = sdk.isSeller(userAddress, escrow);
-const isArbiter = sdk.isArbiter(userAddress, escrow);
-const hasArbiter = sdk.hasArbiter(escrow);
-
-// Compare addresses safely
-const areEqual = sdk.addressEquals(address1, address2);
+npm install @palindromepay/sdk
 ```
 
 ---

package/dist/{PalindromeEscrowSDK.d.ts → PalindromePaySDK.d.ts}

@@ -1,7 +1,5 @@
 /**
- * PALINDROME CRYPTO ESCROW SDK
- *
- * Corrected and optimized SDK matching the actual smart contract interfaces.
+ * PALINDROME Pay SDK
  *
  * Key contract functions:
  * - createEscrow(token, buyer, amount, maturityDays, arbiter, title, ipfsHash, sellerWalletSig)
@@ -96,7 +94,7 @@ export declare class SDKError extends Error {
     details?: ViemError | RPCError | UnknownError | Record<string, unknown>;
     constructor(message: string, code: SDKErrorCode, details?: ViemError | RPCError | UnknownError | Record<string, unknown>);
 }
-export interface PalindromeEscrowSDKConfig {
+export interface PalindromePaySDKConfig {
     publicClient: PublicClient;
     contractAddress: Address;
     walletClient?: EscrowWalletClient;
@@ -212,7 +210,7 @@ export interface DisputeSubmissionStatus {
     arbiter: boolean;
     allSubmitted: boolean;
 }
-export declare class PalindromeEscrowSDK {
+export declare class PalindromePaySDK {
     readonly contractAddress: Address;
     readonly abiEscrow: Abi;
     readonly abiWallet: Abi;
@@ -242,7 +240,7 @@ export declare class PalindromeEscrowSDK {
     /** Cached multicall support status per chain (null = not yet detected) */
     private multicallSupported;
     private readonly STATE_NAMES;
-    constructor(config: PalindromeEscrowSDKConfig);
+    constructor(config: PalindromePaySDKConfig);
     /**
      * Internal logging helper that respects log level configuration
      */
@@ -814,7 +812,7 @@ export declare class PalindromeEscrowSDK {
      *
      * @example
      * ```typescript
-     * const sdk = new PalindromeEscrowSDK(...);
+     * const sdk = new PalindromePaySDK(...);
      * const escrow = await sdk.getEscrowByIdParsed(1n);
      * const status = sdk.getStatusLabel(escrow.state);
      * console.log(status.label); // "Awaiting Payment"
@@ -1081,7 +1079,7 @@ export declare class PalindromeEscrowSDK {
      *
      * @example
      * ```typescript
-     * const sdk = new PalindromeEscrowSDK(...);
+     * const sdk = new PalindromePaySDK(...);
      * const areEqual = sdk.addressEquals(
      *   "0xabc...",
      *   "0xABC..."
@@ -1214,4 +1212,4 @@ export declare class PalindromeEscrowSDK {
         net: bigint;
     }>;
 }
-export default PalindromeEscrowSDK;
+export default PalindromePaySDK;

package/dist/{PalindromeEscrowSDK.js → PalindromePaySDK.js}

@@ -1,15 +1,13 @@
 "use strict";
-// Copyright (c) 2025 Palindrome Finance
+// Copyright (c) 2025 Palindrome Pay
 // Licensed under the MIT License. See LICENSE file for details.
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PalindromeEscrowSDK = exports.SDKError = exports.SDKErrorCode = exports.Role = exports.DisputeResolution = exports.EscrowState = void 0;
+exports.PalindromePaySDK = exports.SDKError = exports.SDKErrorCode = exports.Role = exports.DisputeResolution = exports.EscrowState = void 0;
 /**
- * PALINDROME CRYPTO ESCROW SDK
- *
- * Corrected and optimized SDK matching the actual smart contract interfaces.
+ * PALINDROME Pay SDK
  *
  * Key contract functions:
  * - createEscrow(token, buyer, amount, maturityDays, arbiter, title, ipfsHash, sellerWalletSig)
@@ -29,8 +27,8 @@ exports.PalindromeEscrowSDK = exports.SDKError = exports.SDKErrorCode = exports.
  */
 const viem_1 = require("viem");
 const actions_1 = require("viem/actions");
-const PalindromeCryptoEscrow_json_1 = __importDefault(require("./contract/PalindromeCryptoEscrow.json"));
-const PalindromeEscrowWallet_json_1 = __importDefault(require("./contract/PalindromeEscrowWallet.json"));
+const PalindromePay_json_1 = __importDefault(require("./contract/PalindromePay.json"));
+const PalindromePayWallet_json_1 = __importDefault(require("./contract/PalindromePayWallet.json"));
 const USDT_json_1 = __importDefault(require("./contract/USDT.json"));
 const client_1 = require("@apollo/client");
 /** Type guard to check if error is a Viem error */
@@ -194,7 +192,7 @@ function addressEquals(a, b) {
 // ============================================================================
 // MAIN SDK CLASS
 // ============================================================================
-class PalindromeEscrowSDK {
+class PalindromePaySDK {
     constructor(config) {
         /** LRU cache for escrow data with automatic eviction */
         this.escrowCache = new Map();
@@ -252,8 +250,8 @@ class PalindromeEscrowSDK {
             throw new SDKError("contractAddress is required", SDKErrorCode.VALIDATION_ERROR);
         }
         this.contractAddress = config.contractAddress;
-        this.abiEscrow = PalindromeCryptoEscrow_json_1.default.abi;
-        this.abiWallet = PalindromeEscrowWallet_json_1.default.abi;
+        this.abiEscrow = PalindromePay_json_1.default.abi;
+        this.abiWallet = PalindromePayWallet_json_1.default.abi;
         this.abiERC20 = USDT_json_1.default.abi;
         this.publicClient = config.publicClient;
         this.walletClient = config.walletClient;
@@ -539,7 +537,7 @@ class PalindromeEscrowSDK {
      */
     getWalletDomain(walletAddress) {
         return {
-            name: "PalindromeEscrowWallet",
+            name: "PalindromePayWallet",
             version: "1",
             chainId: this.chain.id,
             verifyingContract: walletAddress,
@@ -662,7 +660,7 @@ class PalindromeEscrowSDK {
         const encodedArgs = (0, viem_1.encodeAbiParameters)([{ type: "address" }, { type: "uint256" }], [this.contractAddress, escrowId]);
         // Note: For accurate prediction, need actual bytecode + args hash
         // This is a simplified version - in production, use the contract's computation
-        const initCodeHash = (0, viem_1.keccak256)((PalindromeEscrowWallet_json_1.default.bytecode + encodedArgs.slice(2)));
+        const initCodeHash = (0, viem_1.keccak256)((PalindromePayWallet_json_1.default.bytecode + encodedArgs.slice(2)));
         const raw = (0, viem_1.keccak256)((`0xff${this.contractAddress.slice(2)}${salt.slice(2)}${initCodeHash.slice(2)}`));
         return (0, viem_1.getAddress)(`0x${raw.slice(26)}`);
     }
@@ -764,7 +762,7 @@ class PalindromeEscrowSDK {
     async getUserNonce(escrowId, signer) {
         // Start with word 0 (nonces 0-255)
         let wordIndex = 0n;
-        while (wordIndex < PalindromeEscrowSDK.MAX_NONCE_WORDS) {
+        while (wordIndex < PalindromePaySDK.MAX_NONCE_WORDS) {
             const bitmap = await this.getNonceBitmap(escrowId, signer, wordIndex);
             // If bitmap is all 1s (all NONCE_BITMAP_SIZE nonces used), check next word
             if (bitmap === (1n << 256n) - 1n) {
@@ -791,7 +789,7 @@ class PalindromeEscrowSDK {
      */
     getEstimatedWordCount(count) {
         return Math.min(Math.ceil(count / 128) + 1, // Conservative estimate with buffer
-        Number(PalindromeEscrowSDK.MAX_NONCE_WORDS));
+        Number(PalindromePaySDK.MAX_NONCE_WORDS));
     }
     /**
      * Detect if chain supports Multicall3 and cache result.
@@ -1766,7 +1764,7 @@ class PalindromeEscrowSDK {
      *
      * @example
      * ```typescript
-     * const sdk = new PalindromeEscrowSDK(...);
+     * const sdk = new PalindromePaySDK(...);
      * const escrow = await sdk.getEscrowByIdParsed(1n);
      * const status = sdk.getStatusLabel(escrow.state);
      * console.log(status.label); // "Awaiting Payment"
@@ -2421,7 +2419,7 @@ class PalindromeEscrowSDK {
      *
      * @example
      * ```typescript
-     * const sdk = new PalindromeEscrowSDK(...);
+     * const sdk = new PalindromePaySDK(...);
      * const areEqual = sdk.addressEquals(
      *   "0xabc...",
      *   "0xABC..."
@@ -2698,13 +2696,13 @@ class PalindromeEscrowSDK {
         return { fee, net: amount - fee };
     }
 }
-exports.PalindromeEscrowSDK = PalindromeEscrowSDK;
+exports.PalindromePaySDK = PalindromePaySDK;
 /**
  * Maximum nonce word index to prevent infinite loops.
  * 100 words = 25,600 nonces per escrow per signer.
  */
-PalindromeEscrowSDK.MAX_NONCE_WORDS = 100n;
+PalindromePaySDK.MAX_NONCE_WORDS = 100n;
 // ============================================================================
 // EXPORT DEFAULT
 // ============================================================================
-exports.default = PalindromeEscrowSDK;
+exports.default = PalindromePaySDK;