@palindromepay/sdk 1.9.7 → 1.9.9

package/dist/PalindromePaySDK.d.ts

@@ -0,0 +1,1214 @@
+/**
+ * PALINDROME Pay SDK
+ *
+ * Key contract functions:
+ * - createEscrow(token, buyer, amount, maturityDays, arbiter, title, ipfsHash, sellerWalletSig)
+ * - createEscrowAndDeposit(token, seller, amount, maturityDays, arbiter, title, ipfsHash, buyerWalletSig)
+ * - deposit(escrowId, buyerWalletSig)
+ * - acceptEscrow(escrowId, sellerWalletSig)
+ * - confirmDelivery(escrowId, buyerWalletSig)
+ * - confirmDeliverySigned(escrowId, coordSignature, deadline, nonce, buyerWalletSig)
+ * - requestCancel(escrowId, walletSig)
+ * - cancelByTimeout(escrowId)
+ * - autoRelease(escrowId)
+ * - startDispute(escrowId)
+ * - startDisputeSigned(escrowId, signature, deadline, nonce)
+ * - submitDisputeMessage(escrowId, role, ipfsHash)
+ * - submitArbiterDecision(escrowId, resolution, ipfsHash, arbiterWalletSig)
+ * - Wallet: withdraw()
+ */
+import { Address, Abi, PublicClient, WalletClient, Hex, Transport, Account, Chain } from "viem";
+import { ApolloClient } from "@apollo/client";
+export type ViemError = {
+    message: string;
+    shortMessage?: string;
+    cause?: {
+        reason?: string;
+        message?: string;
+    };
+    code?: number;
+    stack?: string;
+};
+export type ContractError = ViemError & {
+    contractAddress?: Address;
+    functionName?: string;
+    args?: readonly unknown[];
+};
+export type RPCError = {
+    message: string;
+    code?: number;
+    data?: unknown;
+};
+export type UnknownError = {
+    message?: string;
+    toString(): string;
+};
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
+export interface SDKLogger {
+    debug(message: string, context?: unknown): void;
+    info(message: string, context?: unknown): void;
+    warn(message: string, context?: unknown): void;
+    error(message: string, context?: unknown): void;
+}
+import { Escrow } from "./types/escrow";
+export declare enum EscrowState {
+    AWAITING_PAYMENT = 0,
+    AWAITING_DELIVERY = 1,
+    DISPUTED = 2,
+    COMPLETE = 3,
+    REFUNDED = 4,
+    CANCELED = 5
+}
+export declare enum DisputeResolution {
+    Complete = 3,
+    Refunded = 4
+}
+export declare enum Role {
+    None = 0,
+    Buyer = 1,
+    Seller = 2,
+    Arbiter = 3
+}
+export declare enum SDKErrorCode {
+    WALLET_NOT_CONNECTED = "WALLET_NOT_CONNECTED",
+    WALLET_ACCOUNT_MISSING = "WALLET_ACCOUNT_MISSING",
+    NOT_BUYER = "NOT_BUYER",
+    NOT_SELLER = "NOT_SELLER",
+    NOT_ARBITER = "NOT_ARBITER",
+    INVALID_STATE = "INVALID_STATE",
+    INSUFFICIENT_BALANCE = "INSUFFICIENT_BALANCE",
+    ALLOWANCE_FAILED = "ALLOWANCE_FAILED",
+    SIGNATURE_EXPIRED = "SIGNATURE_EXPIRED",
+    TRANSACTION_FAILED = "TRANSACTION_FAILED",
+    INVALID_ROLE = "INVALID_ROLE",
+    INVALID_TOKEN = "INVALID_TOKEN",
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    RPC_ERROR = "RPC_ERROR",
+    EVIDENCE_ALREADY_SUBMITTED = "EVIDENCE_ALREADY_SUBMITTED",
+    ESCROW_NOT_FOUND = "ESCROW_NOT_FOUND",
+    ALREADY_ACCEPTED = "ALREADY_ACCEPTED"
+}
+export type EscrowWalletClient = WalletClient<Transport, Chain, Account>;
+export declare class SDKError extends Error {
+    code: SDKErrorCode;
+    details?: ViemError | RPCError | UnknownError | Record<string, unknown>;
+    constructor(message: string, code: SDKErrorCode, details?: ViemError | RPCError | UnknownError | Record<string, unknown>);
+}
+export interface PalindromePaySDKConfig {
+    publicClient: PublicClient;
+    contractAddress: Address;
+    walletClient?: EscrowWalletClient;
+    apolloClient?: ApolloClient;
+    chain?: Chain;
+    /** Cache TTL in milliseconds (default: 5000) */
+    cacheTTL?: number;
+    /** Maximum cache entries before LRU eviction (default: 1000) */
+    maxCacheSize?: number;
+    /** Enable automatic retry on RPC failures (default: true) */
+    enableRetry?: boolean;
+    /** Maximum retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Retry delay in milliseconds (default: 1000) */
+    retryDelay?: number;
+    /** Gas buffer percentage (default: 20) */
+    gasBuffer?: number;
+    /** Transaction receipt timeout in milliseconds (default: 60000) */
+    receiptTimeout?: number;
+    subgraphUrl?: string;
+    /**
+     * Skip eth_call simulation before sending transactions (default: false)
+     * Enable this for chains with unreliable RPC simulation (e.g., Base Sepolia)
+     * When true, transactions are sent directly without pre-flight simulation
+     */
+    skipSimulation?: boolean;
+    /**
+     * Default gas limit when simulation is skipped (default: 500000n)
+     * Only used when skipSimulation is true
+     */
+    defaultGasLimit?: bigint;
+    /**
+     * Logger instance for SDK events and errors (default: console)
+     * Set to custom logger or use noOpLogger to disable
+     */
+    logger?: SDKLogger;
+    /**
+     * Minimum log level to output (default: 'info')
+     * 'debug' shows all logs, 'none' disables all logging
+     */
+    logLevel?: LogLevel;
+}
+export interface CreateEscrowParams {
+    token: Address;
+    buyer: Address;
+    amount: bigint;
+    maturityTimeDays?: bigint;
+    arbiter?: Address;
+    title: string;
+    ipfsHash?: string;
+}
+export interface CreateEscrowAndDepositParams {
+    token: Address;
+    seller: Address;
+    amount: bigint;
+    maturityTimeDays?: bigint;
+    arbiter?: Address;
+    title: string;
+    ipfsHash?: string;
+}
+/** Raw escrow data from contract (before type narrowing to Address/Hex) */
+export interface RawEscrowData {
+    token: `0x${string}`;
+    buyer: `0x${string}`;
+    seller: `0x${string}`;
+    arbiter: `0x${string}`;
+    wallet: `0x${string}`;
+    amount: bigint;
+    depositTime: bigint;
+    maturityTime: bigint;
+    disputeStartTime: bigint;
+    state: number;
+    buyerCancelRequested: boolean;
+    sellerCancelRequested: boolean;
+    tokenDecimals: number;
+    sellerWalletSig: `0x${string}`;
+    buyerWalletSig: `0x${string}`;
+    arbiterWalletSig: `0x${string}`;
+}
+/** Parsed escrow data with proper types */
+export interface EscrowData {
+    token: Address;
+    buyer: Address;
+    seller: Address;
+    arbiter: Address;
+    wallet: Address;
+    amount: bigint;
+    depositTime: bigint;
+    maturityTime: bigint;
+    disputeStartTime: bigint;
+    state: EscrowState;
+    buyerCancelRequested: boolean;
+    sellerCancelRequested: boolean;
+    tokenDecimals: number;
+    sellerWalletSig: Hex;
+    buyerWalletSig: Hex;
+    arbiterWalletSig: Hex;
+}
+export interface EscrowCreatedEvent {
+    escrowId: bigint;
+    buyer: Address;
+    seller: Address;
+    token: Address;
+    amount: bigint;
+    arbiter: Address;
+    maturityTime: bigint;
+    title: string;
+    ipfsHash: string;
+}
+export interface DisputeSubmissionStatus {
+    buyer: boolean;
+    seller: boolean;
+    arbiter: boolean;
+    allSubmitted: boolean;
+}
+export declare class PalindromePaySDK {
+    readonly contractAddress: Address;
+    readonly abiEscrow: Abi;
+    readonly abiWallet: Abi;
+    readonly abiERC20: Abi;
+    readonly publicClient: PublicClient;
+    readonly walletClient?: EscrowWalletClient;
+    readonly apollo: ApolloClient;
+    readonly chain: Chain;
+    private readonly cacheTTL;
+    private readonly maxCacheSize;
+    private readonly enableRetry;
+    private readonly maxRetries;
+    private readonly retryDelay;
+    private readonly gasBuffer;
+    private readonly receiptTimeout;
+    private readonly skipSimulation;
+    private readonly defaultGasLimit;
+    private readonly logger;
+    private readonly logLevel;
+    /** LRU cache for escrow data with automatic eviction */
+    private escrowCache;
+    /** Cache for token decimals (rarely changes, no eviction needed) */
+    private tokenDecimalsCache;
+    /** Cache for immutable contract values */
+    private feeReceiverCache;
+    /** Cached multicall support status per chain (null = not yet detected) */
+    private multicallSupported;
+    private readonly STATE_NAMES;
+    constructor(config: PalindromePaySDKConfig);
+    /**
+     * Internal logging helper that respects log level configuration
+     */
+    private log;
+    /**
+     * Execute a contract write with resilient simulation handling.
+     *
+     * This method handles unreliable RPC simulation on certain chains (e.g., Base Sepolia)
+     * by falling back to direct transaction sending when simulation fails.
+     *
+     * @param walletClient - The wallet client to use
+     * @param params - Contract call parameters
+     * @param params.address - Contract address
+     * @param params.abi - Contract ABI
+     * @param params.functionName - Function to call
+     * @param params.args - Function arguments
+     * @returns Transaction hash
+     */
+    private resilientWriteContract;
+    /**
+     * Wait for transaction receipt with timeout and retry logic.
+     */
+    private waitForReceipt;
+    /**
+     * Execute an async operation with retry logic.
+     */
+    private withRetry;
+    /**
+     * Extract error message from unknown error type.
+     */
+    private extractErrorMessage;
+    /**
+     * Validate common escrow creation parameters.
+     */
+    private validateCreateEscrowParams;
+    /**
+     * Verify caller is the buyer, throw if not.
+     */
+    private verifyBuyer;
+    /**
+     * Verify caller is the seller, throw if not.
+     */
+    private verifySeller;
+    /**
+     * Verify caller is the arbiter, throw if not.
+     */
+    private verifyArbiter;
+    /**
+     * Verify escrow is in expected state, throw if not.
+     */
+    private verifyState;
+    /**
+     * Send transaction directly without simulation.
+     * Encodes function data manually and sends with fixed gas limit.
+     *
+     * @param walletClient - The wallet client to send from
+     * @param params - Contract write parameters
+     * @returns Transaction hash
+     */
+    private sendTransactionDirect;
+    /**
+     * Detect if error is a simulation failure (not user rejection or validation error).
+     *
+     * @param error - The error to check
+     * @returns True if error is from simulation failure
+     */
+    private isSimulationErrorType;
+    /**
+     * Set a value in the LRU cache with automatic eviction.
+     */
+    private setCacheValue;
+    /**
+     * Get a value from the LRU cache, refreshing its position.
+     */
+    private getCacheValue;
+    /**
+     * Get the EIP-712 domain for wallet authorization signatures
+     */
+    private getWalletDomain;
+    /**
+     * Get the EIP-712 domain for escrow contract signatures
+     */
+    private getEscrowDomain;
+    private readonly walletAuthorizationTypes;
+    private readonly confirmDeliveryTypes;
+    private readonly startDisputeTypes;
+    /**
+     * Sign a wallet authorization for a participant
+     * Used for: deposit, confirmDelivery, requestCancel, submitArbiterDecision
+     */
+    signWalletAuthorization(walletClient: EscrowWalletClient, walletAddress: Address, escrowId: bigint): Promise<Hex>;
+    /**
+     * Sign a confirm delivery message (for gasless meta-tx)
+     */
+    signConfirmDelivery(walletClient: EscrowWalletClient, escrowId: bigint, deadline: bigint, nonce: bigint): Promise<Hex>;
+    /**
+     * Sign a start dispute message (for gasless meta-tx)
+     */
+    signStartDispute(walletClient: EscrowWalletClient, escrowId: bigint, deadline: bigint, nonce: bigint): Promise<Hex>;
+    /**
+     * Create a signature deadline (timestamp + minutes)
+     */
+    createSignatureDeadline(minutesFromNow?: number): Promise<bigint>;
+    /**
+     * Check if signature deadline has expired
+     */
+    isSignatureDeadlineExpired(deadline: bigint, safetySeconds?: number): boolean;
+    /**
+     * Predict the wallet address for a given escrow ID (before creation)
+     */
+    predictWalletAddress(escrowId: bigint): Promise<Address>;
+    /**
+     * Get raw escrow data from contract
+     */
+    getEscrowById(escrowId: bigint): Promise<RawEscrowData>;
+    /**
+     * Get parsed escrow data
+     */
+    getEscrowByIdParsed(escrowId: bigint): Promise<EscrowData>;
+    /**
+     * Get next escrow ID
+     */
+    getNextEscrowId(): Promise<bigint>;
+    /**
+     * Get the nonce bitmap from the contract.
+     *
+     * Each bitmap word contains NONCE_BITMAP_SIZE nonce states. A set bit means the nonce is used.
+     *
+     * @param escrowId - The escrow ID
+     * @param signer - The signer's address
+     * @param wordIndex - The word index (nonce / NONCE_BITMAP_SIZE)
+     * @returns The bitmap as a bigint
+     */
+    getNonceBitmap(escrowId: bigint, signer: Address, wordIndex?: bigint): Promise<bigint>;
+    /**
+     * Check if a specific nonce has been used.
+     *
+     * @param escrowId - The escrow ID
+     * @param signer - The signer's address
+     * @param nonce - The nonce to check
+     * @returns True if the nonce has been used
+     */
+    isNonceUsed(escrowId: bigint, signer: Address, nonce: bigint): Promise<boolean>;
+    /**
+     * Maximum nonce word index to prevent infinite loops.
+     * 100 words = 25,600 nonces per escrow per signer.
+     */
+    private static readonly MAX_NONCE_WORDS;
+    /**
+     * Get the next available nonce for a signer.
+     *
+     * Queries the contract's nonce bitmap and finds the first unused nonce.
+     * This is the recommended way to get a nonce for signed transactions.
+     *
+     * @param escrowId - The escrow ID
+     * @param signer - The signer's address
+     * @returns The next available nonce
+     * @throws SDKError if nonce space is exhausted (> 25,600 nonces used)
+     */
+    getUserNonce(escrowId: bigint, signer: Address): Promise<bigint>;
+    /**
+     * Calculate estimated number of bitmap words needed for nonce count.
+     * Uses conservative estimate with buffer to minimize round trips.
+     *
+     * @param count - Number of nonces needed
+     * @returns Estimated number of bitmap words to fetch
+     */
+    private getEstimatedWordCount;
+    /**
+     * Detect if chain supports Multicall3 and cache result.
+     * Performs a test multicall on first invocation and caches the result.
+     *
+     * @param escrowId - Escrow ID for test call
+     * @param signer - Signer address for test call
+     */
+    private detectMulticallSupport;
+    /**
+     * Fetch nonce bitmaps using either multicall or sequential calls.
+     * Automatically uses multicall if supported, otherwise falls back to sequential.
+     *
+     * @param escrowId - The escrow ID
+     * @param signer - The signer's address
+     * @param wordCount - Number of bitmap words to fetch
+     * @returns Array of bitmap results with status
+     */
+    private fetchNonceBitmaps;
+    /**
+     * Scan bitmap words for available (unused) nonces.
+     * Performs bit-level scanning with early exit when count is reached.
+     *
+     * @param bitmapResults - Array of bitmap words fetched from contract
+     * @param count - Maximum number of nonces to find
+     * @returns Array of available nonce values
+     */
+    private scanBitmapsForNonces;
+    /**
+     * Get multiple available nonces at once (for batch operations).
+     *
+     * @param escrowId - The escrow ID
+     * @param signer - The signer's address
+     * @param count - Number of nonces to retrieve (max NONCE_BITMAP_SIZE)
+     * @returns Array of available nonces
+     * @throws SDKError if count exceeds limit or nonce space is exhausted
+     */
+    getMultipleNonces(escrowId: bigint, signer: Address, count: number): Promise<bigint[]>;
+    /**
+     * @deprecated No longer needed - nonces are tracked by the contract
+     */
+    resetNonceTracker(): void;
+    /**
+     * Get dispute submission status
+     */
+    getDisputeSubmissionStatus(escrowId: bigint): Promise<DisputeSubmissionStatus>;
+    getTokenDecimals(tokenAddress: Address): Promise<number>;
+    getTokenBalance(account: Address, tokenAddress: Address): Promise<bigint>;
+    getTokenAllowance(owner: Address, spender: Address, tokenAddress: Address): Promise<bigint>;
+    formatTokenAmount(amount: bigint, decimals: number): string;
+    /**
+     * Approve token spending if needed
+     */
+    approveTokenIfNeeded(walletClient: EscrowWalletClient, token: Address, spender: Address, amount: bigint): Promise<Hex | null>;
+    /**
+     * Create a new escrow as the seller
+     *
+     * This function creates a new escrow where the caller (seller) is offering goods/services
+     * to a buyer. The escrow starts in AWAITING_PAYMENT state until the buyer deposits funds.
+     *
+     * The seller's wallet authorization signature is automatically generated and attached,
+     * which will be used later for 2-of-3 multisig withdrawals from the escrow wallet.
+     *
+     * @param walletClient - The seller's wallet client (must have account connected)
+     * @param params - Escrow creation parameters
+     * @param params.token - ERC20 token address for payment
+     * @param params.buyer - Buyer's wallet address
+     * @param params.amount - Payment amount in token's smallest unit (e.g., wei for 18 decimals)
+     * @param params.maturityTimeDays - Optional days until maturity (default: 1, min: 1, max: 3650)
+     * @param params.arbiter - Optional arbiter address for dispute resolution
+     * @param params.title - Escrow title/description (1-500 characters, supports encrypted hashes)
+     * @param params.ipfsHash - Optional IPFS hash for additional details
+     * @returns Object containing escrowId, transaction hash, and wallet address
+     * @throws {SDKError} WALLET_NOT_CONNECTED - If wallet client is not connected
+     * @throws {SDKError} VALIDATION_ERROR - If parameters are invalid
+     * @throws {SDKError} TRANSACTION_FAILED - If the transaction fails
+     */
+    createEscrow(walletClient: EscrowWalletClient, params: CreateEscrowParams): Promise<{
+        escrowId: bigint;
+        txHash: Hex;
+        walletAddress: Address;
+    }>;
+    /**
+     * Create a new escrow and deposit funds as the buyer (single transaction)
+     *
+     * This function creates a new escrow and immediately deposits the payment in one transaction.
+     * The escrow starts in AWAITING_DELIVERY state. The seller must call `acceptEscrow` to
+     * provide their wallet signature before funds can be released.
+     *
+     * Token approval is automatically handled if needed.
+     *
+     * @param walletClient - The buyer's wallet client (must have account connected)
+     * @param params - Escrow creation parameters
+     * @param params.token - ERC20 token address for payment
+     * @param params.seller - Seller's wallet address
+     * @param params.amount - Payment amount in token's smallest unit (e.g., wei for 18 decimals)
+     * @param params.maturityTimeDays - Optional days until maturity (default: 1, min: 1, max: 3650)
+     * @param params.arbiter - Optional arbiter address for dispute resolution
+     * @param params.title - Escrow title/description (1-500 characters, supports encrypted hashes)
+     * @param params.ipfsHash - Optional IPFS hash for additional details
+     * @returns Object containing escrowId, transaction hash, and wallet address
+     * @throws {SDKError} WALLET_NOT_CONNECTED - If wallet client is not connected
+     * @throws {SDKError} VALIDATION_ERROR - If parameters are invalid
+     * @throws {SDKError} INSUFFICIENT_BALANCE - If buyer has insufficient token balance
+     * @throws {SDKError} TRANSACTION_FAILED - If the transaction fails
+     */
+    createEscrowAndDeposit(walletClient: EscrowWalletClient, params: CreateEscrowAndDepositParams): Promise<{
+        escrowId: bigint;
+        txHash: Hex;
+        walletAddress: Address;
+    }>;
+    /**
+     * Deposit funds into an existing escrow as the buyer
+     *
+     * This function is used when the seller created the escrow via `createEscrow`.
+     * The buyer deposits the required payment amount, transitioning the escrow from
+     * AWAITING_PAYMENT to AWAITING_DELIVERY state.
+     *
+     * Token approval is automatically handled if needed.
+     * The buyer's wallet authorization signature is automatically generated.
+     *
+     * @param walletClient - The buyer's wallet client (must have account connected)
+     * @param escrowId - The escrow ID to deposit into
+     * @returns Transaction hash
+     * @throws {SDKError} WALLET_NOT_CONNECTED - If wallet client is not connected
+     * @throws {SDKError} NOT_BUYER - If caller is not the designated buyer
+     * @throws {SDKError} INVALID_STATE - If escrow is not in AWAITING_PAYMENT state
+     * @throws {SDKError} INSUFFICIENT_BALANCE - If buyer has insufficient token balance
+     */
+    deposit(walletClient: EscrowWalletClient, escrowId: bigint): Promise<Hex>;
+    /**
+     * Accept an escrow as the seller (for buyer-created escrows)
+     *
+     * This function is required when the buyer created the escrow via `createEscrowAndDeposit`.
+     * The seller must accept to provide their wallet authorization signature, which is
+     * required for the 2-of-3 multisig withdrawal mechanism.
+     *
+     * Without accepting, the seller cannot receive funds even if the buyer confirms delivery.
+     *
+     * @param walletClient - The seller's wallet client (must have account connected)
+     * @param escrowId - The escrow ID to accept
+     * @returns Transaction hash
+     * @throws {SDKError} WALLET_NOT_CONNECTED - If wallet client is not connected
+     * @throws {SDKError} NOT_SELLER - If caller is not the designated seller
+     * @throws {SDKError} INVALID_STATE - If escrow is not in AWAITING_DELIVERY state
+     * @throws {SDKError} ALREADY_ACCEPTED - If escrow was already accepted
+     */
+    acceptEscrow(walletClient: EscrowWalletClient, escrowId: bigint): Promise<Hex>;
+    /**
+     * Confirm delivery and release funds to the seller
+     *
+     * This function is called by the buyer after receiving the goods/services.
+     * It transitions the escrow to COMPLETE state and authorizes payment release to the seller.
+     *
+     * After confirmation, anyone can call `withdraw` on the escrow wallet to execute
+     * the actual token transfer (requires 2-of-3 signatures: buyer + seller).
+     *
+     * A 1% fee is deducted from the payment amount.
+     *
+     * @param walletClient - The buyer's wallet client (must have account connected)
+     * @param escrowId - The escrow ID to confirm
+     * @returns Transaction hash
+     * @throws {SDKError} WALLET_NOT_CONNECTED - If wallet client is not connected
+     * @throws {SDKError} NOT_BUYER - If caller is not the designated buyer
+     * @throws {SDKError} INVALID_STATE - If escrow is not in AWAITING_DELIVERY state
+     */
+    confirmDelivery(walletClient: EscrowWalletClient, escrowId: bigint): Promise<Hex>;
+    /**
+     * Confirm delivery via meta-transaction (gasless for buyer)
+     *
+     * This function allows a relayer to submit the confirm delivery transaction on behalf
+     * of the buyer. The buyer signs the confirmation off-chain, and the relayer pays the gas.
+     *
+     * Use `prepareConfirmDeliverySigned` to generate the required signatures.
+     *
+     * @param walletClient - The relayer's wallet client (pays gas)
+     * @param escrowId - The escrow ID to confirm
+     * @param coordSignature - Buyer's EIP-712 signature for the confirmation
+     * @param deadline - Signature expiration timestamp (must be within 24 hours)
+     * @param nonce - Buyer's nonce for replay protection
+     * @param buyerWalletSig - Buyer's wallet authorization signature
+     * @returns Transaction hash
+     * @throws {SDKError} WALLET_NOT_CONNECTED - If wallet client is not connected
+     * @throws {SDKError} SIGNATURE_EXPIRED - If deadline has passed
+     */
+    confirmDeliverySigned(walletClient: EscrowWalletClient, escrowId: bigint, coordSignature: Hex, deadline: bigint, nonce: bigint, buyerWalletSig: Hex): Promise<Hex>;
+    /**
+     * Prepare signatures for gasless confirm delivery
+     *
+     * This helper function generates all the signatures needed for a gasless confirm delivery.
+     * The buyer signs off-chain, and the resulting data can be sent to a relayer who will
+     * submit the transaction and pay the gas.
+     *
+     * The deadline is set to 60 minutes from the current block timestamp.
+     *
+     * @param buyerWalletClient - The buyer's wallet client (must have account connected)
+     * @param escrowId - The escrow ID to confirm
+     * @returns Object containing coordSignature, buyerWalletSig, deadline, and nonce
+     * @throws {SDKError} WALLET_NOT_CONNECTED - If wallet client is not connected
+     * @throws {SDKError} NOT_BUYER - If caller is not the designated buyer
+     */
+    prepareConfirmDeliverySigned(buyerWalletClient: EscrowWalletClient, escrowId: bigint): Promise<{
+        coordSignature: Hex;
+        buyerWalletSig: Hex;
+        deadline: bigint;
+        nonce: bigint;
+    }>;
+    /**
+     * Request cancellation of an escrow
+     *
+     * This function allows either the buyer or seller to request cancellation.
+     * Both parties must call this function for a mutual cancellation to occur.
+     *
+     * - If only one party requests: The request is recorded, awaiting the other party
+     * - If both parties request: The escrow is automatically canceled and funds returned to buyer
+     *
+     * Use `getCancelRequestStatus` to check if the other party has already requested.
+     *
+     * @param walletClient - The buyer's or seller's wallet client
+     * @param escrowId - The escrow ID to cancel
+     * @returns Transaction hash
+     * @throws {SDKError} WALLET_NOT_CONNECTED - If wallet client is not connected
+     * @throws {SDKError} INVALID_ROLE - If caller is not buyer or seller
+     * @throws {SDKError} INVALID_STATE - If escrow is not in AWAITING_DELIVERY state
+     */
+    requestCancel(walletClient: EscrowWalletClient, escrowId: bigint): Promise<Hex>;
+    /**
+     * Cancel escrow by timeout (unilateral cancellation by buyer)
+     *
+     * This function allows the buyer to cancel the escrow unilaterally if:
+     * - The buyer has already requested cancellation via `requestCancel`
+     * - The maturity time has passed
+     * - The seller has not agreed to mutual cancellation
+     * - No dispute is active
+     * - An arbiter is assigned to the escrow
+     *
+     * Funds are returned to the buyer without any fee deduction.
+     *
+     * @param walletClient - The buyer's wallet client (must have account connected)
+     * @param escrowId - The escrow ID to cancel
+     * @returns Transaction hash
+     * @throws {SDKError} WALLET_NOT_CONNECTED - If wallet client is not connected
+     * @throws {SDKError} NOT_BUYER - If caller is not the designated buyer
+     * @throws {SDKError} INVALID_STATE - If conditions for timeout cancel are not met
+     */
+    cancelByTimeout(walletClient: EscrowWalletClient, escrowId: bigint): Promise<Hex>;
+    /**
+     * Auto-release funds to seller after maturity time
+     *
+     * This function allows the seller to claim funds unilaterally after the maturity time
+     * has passed. This protects sellers when buyers become unresponsive after receiving
+     * goods/services.
+     *
+     * Requirements:
+     * - Escrow must be in AWAITING_DELIVERY state
+     * - No dispute has been started
+     * - Buyer has not requested cancellation
+     * - maturityTime has passed
+     * - Seller has already provided wallet signature (via createEscrow or acceptEscrow)
+     *
+     * A 1% fee is deducted from the payment amount.
+     *
+     * @param walletClient - The seller's wallet client (must have account connected)
+     * @param escrowId - The escrow ID to auto-release
+     * @returns Transaction hash
+     * @throws {SDKError} WALLET_NOT_CONNECTED - If wallet client is not connected
+     * @throws {SDKError} NOT_SELLER - If caller is not the designated seller
+     * @throws {SDKError} INVALID_STATE - If escrow is not in AWAITING_DELIVERY state
+     * @throws {SDKError} INVALID_STATE - If dispute is active or buyer requested cancel
+     * @throws {SDKError} VALIDATION_ERROR - If seller wallet signature is missing
+     */
+    autoRelease(walletClient: EscrowWalletClient, escrowId: bigint): Promise<Hex>;
+    /**
+     * Start a dispute for an escrow
+     *
+     * This function initiates a dispute when there's a disagreement between buyer and seller.
+     * Once started, the escrow enters DISPUTED state and requires arbiter resolution.
+     *
+     * Either the buyer or seller can start a dispute. An arbiter must be assigned to the
+     * escrow for disputes to be possible.
+     *
+     * After starting a dispute:
+     * 1. Both parties should submit evidence via `submitDisputeMessage`
+     * 2. The arbiter reviews evidence and makes a decision via `submitArbiterDecision`
+     * 3. The arbiter can rule in favor of buyer (REFUNDED) or seller (COMPLETE)
+     *
+     * @param walletClient - The buyer's or seller's wallet client
+     * @param escrowId - The escrow ID to dispute
+     * @returns Transaction hash
+     * @throws {SDKError} WALLET_NOT_CONNECTED - If wallet client is not connected
+     * @throws {SDKError} INVALID_STATE - If escrow is not in AWAITING_DELIVERY state
+     */
+    startDispute(walletClient: EscrowWalletClient, escrowId: bigint): Promise<Hex>;
+    /**
+     * Start a dispute via meta-transaction (gasless for buyer/seller)
+     *
+     * This function allows a relayer to submit the start dispute transaction on behalf
+     * of the buyer or seller. The initiator signs off-chain, and the relayer pays the gas.
+     *
+     * Use `signStartDispute` to generate the required signature.
+     *
+     * @param walletClient - The relayer's wallet client (pays gas)
+     * @param escrowId - The escrow ID to dispute
+     * @param signature - Buyer's or seller's EIP-712 signature
+     * @param deadline - Signature expiration timestamp (must be within 24 hours)
+     * @param nonce - Signer's nonce for replay protection
+     * @returns Transaction hash
+     * @throws {SDKError} WALLET_NOT_CONNECTED - If wallet client is not connected
+     * @throws {SDKError} SIGNATURE_EXPIRED - If deadline has passed
+     */
+    startDisputeSigned(walletClient: EscrowWalletClient, escrowId: bigint, signature: Hex, deadline: bigint, nonce: bigint): Promise<Hex>;
+    /**
+     * Submit evidence for a dispute
+     *
+     * This function allows the buyer or seller to submit evidence supporting their case.
+     * Each party can only submit evidence once. Evidence is stored on IPFS and the hash
+     * is recorded on-chain.
+     *
+     * The arbiter will review submitted evidence before making a decision. Both parties
+     * should submit evidence for a fair resolution. After 30 days, the arbiter can make
+     * a decision even without complete evidence.
+     *
+     * @param walletClient - The buyer's or seller's wallet client
+     * @param escrowId - The escrow ID
+     * @param role - The caller's role (Role.Buyer or Role.Seller)
+     * @param ipfsHash - IPFS hash containing the evidence (max 500 characters)
+     * @returns Transaction hash
+     * @throws {SDKError} WALLET_NOT_CONNECTED - If wallet client is not connected
+     * @throws {SDKError} EVIDENCE_ALREADY_SUBMITTED - If caller already submitted evidence
+     * @throws {SDKError} INVALID_STATE - If escrow is not in DISPUTED state
+     */
+    submitDisputeMessage(walletClient: EscrowWalletClient, escrowId: bigint, role: Role.Buyer | Role.Seller, ipfsHash: string): Promise<Hex>;
+    /**
+     * Submit arbiter's decision to resolve a dispute
+     *
+     * This function is called by the designated arbiter to resolve a dispute.
+     * The arbiter reviews evidence submitted by both parties and makes a final decision.
+     *
+     * The arbiter can rule:
+     * - DisputeResolution.Complete (3): Funds go to seller (with 1% fee)
+     * - DisputeResolution.Refunded (4): Funds go to buyer (no fee)
+     *
+     * Requirements:
+     * - Both parties must have submitted evidence, OR
+     * - 30 days + 1 hour timeout has passed since dispute started
+     *
+     * The arbiter's wallet signature is automatically generated for the multisig.
+     *
+     * @param walletClient - The arbiter's wallet client (must have account connected)
+     * @param escrowId - The escrow ID to resolve
+     * @param resolution - DisputeResolution.Complete or DisputeResolution.Refunded
+     * @param ipfsHash - IPFS hash containing the decision explanation
+     * @returns Transaction hash
+     * @throws {SDKError} WALLET_NOT_CONNECTED - If wallet client is not connected
+     * @throws {SDKError} NOT_ARBITER - If caller is not the designated arbiter
+     * @throws {SDKError} INVALID_STATE - If escrow is not in DISPUTED state
+     */
+    submitArbiterDecision(walletClient: EscrowWalletClient, escrowId: bigint, resolution: DisputeResolution, ipfsHash: string): Promise<Hex>;
+    /**
+     * Withdraw funds from the escrow wallet
+     *
+     * This function executes the actual token transfer from the escrow wallet to the
+     * designated recipient. The wallet contract uses a 2-of-3 multisig mechanism:
+     *
+     * - COMPLETE state: Requires buyer + seller signatures → funds go to seller
+     * - REFUNDED state: Requires buyer + arbiter signatures → funds go to buyer
+     * - CANCELED state: Requires buyer + seller signatures → funds go to buyer
+     *
+     * Anyone can call this function (typically the recipient), as the signatures
+     * were already collected during the escrow lifecycle. The wallet contract
+     * automatically reads and verifies signatures from the escrow contract.
+     *
+     * @param walletClient - Any wallet client (typically the recipient)
+     * @param escrowId - The escrow ID to withdraw from
+     * @returns Transaction hash
+     * @throws {SDKError} WALLET_NOT_CONNECTED - If wallet client is not connected
+     * @throws {SDKError} INVALID_STATE - If escrow is not in a final state (COMPLETE/REFUNDED/CANCELED)
+     */
+    withdraw(walletClient: EscrowWalletClient, escrowId: bigint): Promise<Hex>;
+    /**
+     * Get valid signature count for wallet
+     */
+    getWalletSignatureCount(escrowId: bigint): Promise<number>;
+    /**
+     * Get wallet balance
+     */
+    getWalletBalance(escrowId: bigint): Promise<bigint>;
+    getEscrows(): Promise<Escrow[]>;
+    getEscrowsByBuyer(buyer: string): Promise<Escrow[]>;
+    getEscrowsBySeller(seller: string): Promise<Escrow[]>;
+    getEscrowDetail(id: string): Promise<Escrow | undefined>;
+    getDisputeMessages(escrowId: string): Promise<any[]>;
+    /**
+     * Get a human-readable status label with color and description for an escrow state.
+     * This is useful for displaying escrow status in UIs.
+     *
+     * @param state - The escrow state enum value
+     * @returns An object containing:
+     *   - label: Human-readable status name
+     *   - color: Suggested UI color (orange, blue, red, green, gray)
+     *   - description: Detailed explanation of what this state means
+     *
+     * @example
+     * ```typescript
+     * const sdk = new PalindromePaySDK(...);
+     * const escrow = await sdk.getEscrowByIdParsed(1n);
+     * const status = sdk.getStatusLabel(escrow.state);
+     * console.log(status.label); // "Awaiting Payment"
+     * console.log(status.color); // "orange"
+     * console.log(status.description); // "Buyer needs to deposit funds"
+     * ```
+     */
+    getStatusLabel(state: EscrowState): {
+        label: string;
+        color: string;
+        description: string;
+    };
+    /**
+     * Get user role for an escrow
+     */
+    getUserRole(userAddress: Address, escrow: EscrowData): Role;
+    /**
+     * Simulate a transaction before executing
+     * Returns success status, gas estimate, and revert reason if failed
+     */
+    simulateTransaction(walletClient: EscrowWalletClient, functionName: string, args: any[], contractAddress?: Address): Promise<{
+        success: boolean;
+        gasEstimate?: bigint;
+        revertReason?: string;
+        result?: any;
+    }>;
+    /**
+     * Simulate deposit before executing
+     */
+    simulateDeposit(walletClient: EscrowWalletClient, escrowId: bigint): Promise<{
+        success: boolean;
+        gasEstimate?: bigint;
+        revertReason?: string;
+        needsApproval?: boolean;
+        approvalAmount?: bigint;
+    }>;
+    /**
+     * Simulate confirm delivery before executing
+     */
+    simulateConfirmDelivery(walletClient: EscrowWalletClient, escrowId: bigint): Promise<{
+        success: boolean;
+        gasEstimate?: bigint;
+        revertReason?: string;
+    }>;
+    /**
+     * Simulate withdraw before executing
+     */
+    simulateWithdraw(walletClient: EscrowWalletClient, escrowId: bigint): Promise<{
+        success: boolean;
+        gasEstimate?: bigint;
+        revertReason?: string;
+        signatureCount?: number;
+    }>;
+    /**
+     * Estimate gas for a transaction with buffer
+     */
+    estimateGasWithBuffer(walletClient: EscrowWalletClient, functionName: string, args: any[], contractAddress?: Address): Promise<bigint>;
+    /**
+     * Health check
+     */
+    healthCheck(): Promise<{
+        rpcConnected: boolean;
+        contractDeployed: boolean;
+        subgraphConnected: boolean;
+        errors: string[];
+    }>;
+    /**
+     * Get escrow status with optional caching
+     */
+    getEscrowStatus(escrowId: bigint, forceRefresh?: boolean): Promise<{
+        state: EscrowState;
+        stateName: string;
+        label: string;
+        color: string;
+        description: string;
+    }>;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        escrowCacheSize: number;
+        tokenDecimalsCacheSize: number;
+    };
+    /**
+     * Clear all caches
+     */
+    clearAllCaches(): void;
+    /**
+     * Clear escrow cache only
+     */
+    clearEscrowCache(): void;
+    /**
+     * Clear multicall cache (useful when switching chains)
+     */
+    clearMulticallCache(): void;
+    /**
+     * Watch for escrow events related to a user
+     */
+    watchUserEscrows(userAddress: Address, callback: (escrowId: bigint, event: EscrowCreatedEvent) => void, options?: {
+        fromBlock?: bigint;
+    }): {
+        dispose: () => void;
+    };
+    /**
+     * Watch for state changes on a specific escrow
+     */
+    watchEscrowStateChanges(escrowId: bigint, callback: (newState: EscrowState, previousState: EscrowState) => void, options?: {
+        pollingInterval?: number;
+    }): {
+        dispose: () => void;
+    };
+    /**
+     * Check if user has submitted evidence for a dispute
+     */
+    hasSubmittedEvidence(escrowId: bigint, role: Role): Promise<boolean>;
+    /**
+     * Get cancellation request status for an escrow
+     *
+     * This helper function checks whether the buyer and/or seller have requested
+     * cancellation. Use this to determine if mutual cancellation is pending or complete.
+     *
+     * Cancellation flow:
+     * - Either party calls `requestCancel` to initiate
+     * - If only one party requested, the other must also call `requestCancel` for mutual cancel
+     * - When both request, the escrow is automatically canceled and funds return to buyer
+     * - Alternatively, buyer can use `cancelByTimeout` after maturity time (if arbiter is set)
+     *
+     * @param escrowId - The escrow ID to check
+     * @returns Object with buyer/seller cancel request status and whether mutual cancel is complete
+     */
+    getCancelRequestStatus(escrowId: bigint): Promise<{
+        buyerRequested: boolean;
+        sellerRequested: boolean;
+        mutualCancelComplete: boolean;
+    }>;
+    /**
+     * Get user balances for multiple tokens (batched for performance).
+     * Uses Promise.all to fetch all balances and decimals in parallel.
+     */
+    getUserBalances(userAddress: Address, tokens: Address[]): Promise<Map<Address, {
+        balance: bigint;
+        decimals: number;
+        formatted: string;
+    }>>;
+    /**
+     * Get maturity info for an escrow
+     */
+    getMaturityInfo(depositTime: bigint, maturityDays: bigint): {
+        hasDeadline: boolean;
+        maturityDays: number;
+        maturityTimestamp: bigint;
+        isPassed: boolean;
+        remainingSeconds: number;
+    };
+    /**
+     * Get all escrows for a user (as buyer or seller)
+     */
+    getUserEscrows(userAddress: Address): Promise<Escrow[]>;
+    /**
+     * Check if a user can deposit to an escrow.
+     * A user can deposit if:
+     * - The escrow exists and is in AWAITING_PAYMENT state
+     * - The user is either the buyer or seller
+     *
+     * @param userAddress - The address of the user to check
+     * @param escrowId - The escrow ID to check
+     * @returns True if the user can deposit, false otherwise
+     */
+    canUserDeposit(userAddress: Address, escrowId: bigint): Promise<boolean>;
+    /**
+     * Check if a user can accept an escrow (seller accepting after buyer deposit).
+     * A user can accept if:
+     * - The escrow is in AWAITING_DELIVERY state
+     * - The user is the seller
+     *
+     * @param userAddress - The address of the user to check
+     * @param escrowId - The escrow ID to check
+     * @returns True if the user can accept, false otherwise
+     */
+    canUserAcceptEscrow(userAddress: Address, escrowId: bigint): Promise<boolean>;
+    /**
+     * Check if a user can confirm delivery (buyer confirming receipt).
+     * A user can confirm delivery if:
+     * - The escrow is in AWAITING_DELIVERY or DISPUTED state
+     * - The user is the buyer
+     *
+     * @param userAddress - The address of the user to check
+     * @param escrowId - The escrow ID to check
+     * @returns True if the user can confirm delivery, false otherwise
+     */
+    canUserConfirmDelivery(userAddress: Address, escrowId: bigint): Promise<boolean>;
+    /**
+     * Check if a user can start a dispute.
+     * A user can start a dispute if:
+     * - The escrow is in AWAITING_DELIVERY state
+     * - The escrow has an arbiter set
+     * - The user is either the buyer or seller
+     *
+     * @param userAddress - The address of the user to check
+     * @param escrowId - The escrow ID to check
+     * @returns True if the user can start a dispute, false otherwise
+     */
+    canUserStartDispute(userAddress: Address, escrowId: bigint): Promise<boolean>;
+    /**
+     * Check if an escrow can be withdrawn (auto-release check).
+     * An escrow can be withdrawn if:
+     * - It's in AWAITING_DELIVERY state
+     * - The maturity time has passed (if deadline is set)
+     *
+     * @param escrowId - The escrow ID to check
+     * @returns True if the escrow can be withdrawn, false otherwise
+     */
+    canUserWithdraw(escrowId: bigint): Promise<boolean>;
+    /**
+     * Check if a seller can perform auto-release.
+     * A seller can auto-release if:
+     * - The escrow is in AWAITING_DELIVERY state
+     * - The maturity time has passed (if deadline is set)
+     * - The user is the seller
+     *
+     * @param userAddress - The address of the user to check
+     * @param escrowId - The escrow ID to check
+     * @returns True if the seller can auto-release, false otherwise
+     */
+    canSellerAutoRelease(userAddress: Address, escrowId: bigint): Promise<boolean>;
+    /**
+     * Check if an address is the buyer in an escrow.
+     *
+     * @param userAddress - The address to check
+     * @param escrow - The escrow data
+     * @returns True if the address is the buyer
+     */
+    isBuyer(userAddress: Address, escrow: EscrowData): boolean;
+    /**
+     * Check if an address is the seller in an escrow.
+     *
+     * @param userAddress - The address to check
+     * @param escrow - The escrow data
+     * @returns True if the address is the seller
+     */
+    isSeller(userAddress: Address, escrow: EscrowData): boolean;
+    /**
+     * Check if an address is the arbiter in an escrow.
+     *
+     * @param userAddress - The address to check
+     * @param escrow - The escrow data
+     * @returns True if the address is the arbiter
+     */
+    isArbiter(userAddress: Address, escrow: EscrowData): boolean;
+    /**
+     * Check if an escrow has an arbiter set.
+     *
+     * @param escrow - The escrow data
+     * @returns True if the escrow has an arbiter (non-zero address)
+     */
+    hasArbiter(escrow: EscrowData): boolean;
+    /**
+     * Compare two addresses for equality (case-insensitive, normalized).
+     * This is a public utility method that can be used to compare Ethereum addresses.
+     *
+     * @param a - First address to compare
+     * @param b - Second address to compare
+     * @returns True if the addresses are equal (case-insensitive)
+     *
+     * @example
+     * ```typescript
+     * const sdk = new PalindromePaySDK(...);
+     * const areEqual = sdk.addressEquals(
+     *   "0xabc...",
+     *   "0xABC..."
+     * ); // true
+     * ```
+     */
+    addressEquals(a: Address | string, b: Address | string): boolean;
+    /**
+     * Get current gas price information from the network.
+     * Returns standard, fast, and instant gas price estimates in gwei.
+     *
+     * @returns Object containing gas price estimates
+     *
+     * @example
+     * ```typescript
+     * const gasPrice = await sdk.getCurrentGasPrice();
+     * console.log(`Standard: ${gasPrice.standard} gwei`);
+     * console.log(`Fast: ${gasPrice.fast} gwei`);
+     * console.log(`Instant: ${gasPrice.instant} gwei`);
+     * ```
+     */
+    getCurrentGasPrice(): Promise<{
+        standard: bigint;
+        fast: bigint;
+        instant: bigint;
+        wei: bigint;
+    }>;
+    /**
+     * Estimate gas cost for creating an escrow.
+     *
+     * @param params - Create escrow parameters
+     * @returns Gas estimation details
+     *
+     * @example
+     * ```typescript
+     * const estimate = await sdk.estimateGasForCreateEscrow({
+     *   token: tokenAddress,
+     *   buyer: buyerAddress,
+     *   amount: 1000000n,
+     *   maturityDays: 7n,
+     *   arbiter: zeroAddress,
+     *   title: 'Test',
+     *   ipfsHash: ''
+     * });
+     * console.log(`Gas limit: ${estimate.gasLimit}`);
+     * console.log(`Cost: ${estimate.estimatedCostEth} ETH`);
+     * ```
+     */
+    estimateGasForCreateEscrow(params: {
+        token: Address;
+        buyer: Address;
+        amount: bigint;
+        maturityDays: bigint;
+        arbiter: Address;
+        title: string;
+        ipfsHash: string;
+    }): Promise<{
+        gasLimit: bigint;
+        estimatedCostWei: bigint;
+        estimatedCostEth: string;
+    }>;
+    /**
+     * Estimate gas cost for depositing to an escrow.
+     *
+     * @param escrowId - The escrow ID
+     * @returns Gas estimation details
+     *
+     * @example
+     * ```typescript
+     * const estimate = await sdk.estimateGasForDeposit(escrowId);
+     * console.log(`Gas limit: ${estimate.gasLimit}`);
+     * ```
+     */
+    estimateGasForDeposit(escrowId: bigint): Promise<{
+        gasLimit: bigint;
+        estimatedCostWei: bigint;
+        estimatedCostEth: string;
+    }>;
+    /**
+     * Estimate gas cost for confirming delivery.
+     *
+     * @param escrowId - The escrow ID
+     * @returns Gas estimation details
+     *
+     * @example
+     * ```typescript
+     * const estimate = await sdk.estimateGasForConfirmDelivery(escrowId);
+     * console.log(`Cost: ${estimate.estimatedCostEth} ETH`);
+     * ```
+     */
+    estimateGasForConfirmDelivery(escrowId: bigint): Promise<{
+        gasLimit: bigint;
+        estimatedCostWei: bigint;
+        estimatedCostEth: string;
+    }>;
+    /**
+     * Estimate gas cost for withdrawing from escrow wallet.
+     *
+     * @returns Gas estimation details
+     *
+     * @example
+     * ```typescript
+     * const estimate = await sdk.estimateGasForWithdraw();
+     * ```
+     */
+    estimateGasForWithdraw(): Promise<{
+        gasLimit: bigint;
+        estimatedCostWei: bigint;
+        estimatedCostEth: string;
+    }>;
+    /**
+     * Get fee receiver address (cached - rarely changes)
+     * @param forceRefresh - Set to true to bypass cache and fetch fresh value
+     */
+    getFeeReceiver(forceRefresh?: boolean): Promise<Address>;
+    /** Cached fee basis points (lazily computed from contract) */
+    private cachedFeeBps;
+    /**
+     * Get fee percentage in basis points.
+     * Tries to read FEE_BPS from contract, falls back to default (100 = 1%).
+     * Result is cached for performance.
+     */
+    getFeeBps(): Promise<bigint>;
+    /**
+     * Calculate fee for an amount.
+     * Uses the same logic as the contract's _computeFeeAndNet.
+     */
+    calculateFee(amount: bigint, tokenDecimals?: number): Promise<{
+        fee: bigint;
+        net: bigint;
+    }>;
+}
+export default PalindromePaySDK;