@oobe-protocol-labs/synapse-sap-sdk 0.14.0 → 0.15.1

package/dist/esm/registries/x402.js

@@ -0,0 +1,664 @@
+/**
+ * @module registries/x402
+ * @description x402 payment flow registry — high-level helpers for
+ * the complete x402 HTTP micropayment lifecycle.
+ *
+ * Implements the x402 payment standard on SAP:
+ *
+ *   ┌──────────┐    HTTP 402    ┌──────────┐
+ *   │  Client  │ ──────────────→│  Agent   │
+ *   └────┬─────┘                └────┬─────┘
+ *        │  1. Discover pricing      │
+ *        │  2. Create/fund escrow    │
+ *        │  3. Call via x402 header  │
+ *        │                           │
+ *        │  4. Agent serves request  │
+ *        │  5. Agent settles onchain │
+ *        │  ← PaymentSettledEvent ←  │
+ *        │  6. Client verifies       │
+ *        └───────────────────────────┘
+ *
+ * This registry provides:
+ *   - Pricing estimation with volume curve support
+ *   - x402 HTTP header generation
+ *   - Escrow lifecycle management
+ *   - Settlement verification
+ *   - Balance/expiry monitoring
+ *
+ * @category Registries
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * const x402 = client.x402;
+ *
+ * // === CLIENT SIDE ===
+ *
+ * // 1. Estimate cost before committing
+ * const estimate = x402.estimateCost(agentWallet, 100);
+ *
+ * // 2. Prepare payment (creates escrow + deposits)
+ * const ctx = await x402.preparePayment(agentWallet, {
+ *   pricePerCall: 1000,
+ *   maxCalls: 100,
+ *   deposit: 100_000,
+ * });
+ *
+ * // 3. Build x402 HTTP headers for API calls
+ * const headers = x402.buildPaymentHeaders(ctx);
+ *
+ * // 4. Check balance
+ * const balance = await x402.getBalance(agentWallet);
+ *
+ * // === AGENT SIDE ===
+ *
+ * // 5. Settle after serving calls
+ * const receipt = await x402.settle(depositorWallet, 5, serviceData);
+ *
+ * // 6. Batch settle for efficiency
+ * const batchReceipt = await x402.settleBatch(depositorWallet, settlements);
+ *
+ * // 7. Verify a settlement TX
+ * const verified = await x402.verifySettlement(txSignature);
+ * ```
+ */
+import { SystemProgram, } from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+import { deriveAgent, deriveAgentStats, deriveEscrow, deriveEscrowV2, } from "../pda";
+import { sha256, hashToArray } from "../utils";
+import { SapNetwork } from "../constants/network";
+import { buildPriorityFeeIxs, computeBatchSettleCu, buildRpcOptions, } from "../utils/priority-fee";
+// ═══════════════════════════════════════════════════════════════════
+//  x402 Registry
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name X402Registry
+ * @description x402 payment flow registry for the SAP network.
+ *
+ * Provides the complete x402 HTTP micropayment lifecycle: pricing
+ * estimation, escrow management, HTTP header generation, settlement,
+ * and balance monitoring. Used by both clients (payers) and agents (payees).
+ *
+ * @category Registries
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * const x402 = client.x402;
+ *
+ * // Client: prepare payment and build headers
+ * const ctx = await x402.preparePayment(agentWallet, {
+ *   pricePerCall: 1000, maxCalls: 100, deposit: 100_000,
+ * });
+ * const headers = x402.buildPaymentHeaders(ctx);
+ *
+ * // Agent: settle calls after serving
+ * const receipt = await x402.settle(depositorWallet, 5, "service-data");
+ * ```
+ */
+export class X402Registry {
+    program;
+    wallet;
+    constructor(program) {
+        this.program = program;
+        this.wallet = program.provider.wallet.publicKey;
+    }
+    // ── Pricing & Estimation ─────────────────────────────
+    /**
+     * @name estimateCost
+     * @description Estimate the cost of N calls to an agent.
+     * Reads the escrow data if it exists, falls back to the agent’s pricing.
+     * Supports volume curve pricing for tiered cost calculation.
+     *
+     * @param agentWallet - Agent wallet address.
+     * @param calls - Number of calls to estimate.
+     * @param opts - Optional: provide pricing directly to avoid on-chain fetch.
+     * @param opts.pricePerCall - Base price per call.
+     * @param opts.volumeCurve - Volume curve breakpoints.
+     * @param opts.totalCallsBefore - Total calls already settled (for curve offset).
+     * @returns A {@link CostEstimate} with total cost and per-tier breakdown.
+     * @since v0.1.0
+     */
+    async estimateCost(agentWallet, calls, opts) {
+        let pricePerCall;
+        let volumeCurve;
+        let totalBefore;
+        if (opts?.pricePerCall) {
+            pricePerCall = opts.pricePerCall;
+            volumeCurve = opts.volumeCurve ?? [];
+            totalBefore = opts.totalCallsBefore ?? 0;
+        }
+        else {
+            // Try to read from existing escrow (V2 first, then V1)
+            const [agentPda] = deriveAgent(agentWallet);
+            const resolved = await this.resolveEscrow(agentPda, this.wallet);
+            if (resolved) {
+                pricePerCall = resolved.escrow.pricePerCall;
+                volumeCurve = resolved.escrow.volumeCurve ?? [];
+                totalBefore = resolved.escrow.totalCallsSettled.toNumber();
+            }
+            else {
+                // Fall back to agent's first pricing tier
+                const agent = await this.fetchNullable("agentAccount", agentPda);
+                if (!agent || agent.pricing.length === 0) {
+                    return {
+                        totalCost: new BN(0),
+                        calls,
+                        effectivePricePerCall: new BN(0),
+                        hasVolumeCurve: false,
+                        tiers: [],
+                    };
+                }
+                pricePerCall = agent.pricing[0].pricePerCall;
+                volumeCurve = agent.pricing[0].volumeCurve ?? [];
+                totalBefore = 0;
+            }
+        }
+        return this.calculateCost(pricePerCall, volumeCurve, totalBefore, calls);
+    }
+    /**
+     * @name calculateCost
+     * @description Pure cost calculation (no network calls).
+     * Implements the same tiered pricing logic as the on-chain program.
+     *
+     * @param basePrice - Base price per call in smallest token unit.
+     * @param volumeCurve - Volume curve breakpoints.
+     * @param totalCallsBefore - Total calls already settled (cursor offset).
+     * @param calls - Number of calls to calculate cost for.
+     * @returns A {@link CostEstimate} with total cost and per-tier breakdown.
+     * @since v0.1.0
+     */
+    calculateCost(basePrice, volumeCurve, totalCallsBefore, calls) {
+        const tiers = [];
+        if (volumeCurve.length === 0) {
+            const totalCost = basePrice.mul(new BN(calls));
+            return {
+                totalCost,
+                calls,
+                effectivePricePerCall: basePrice,
+                hasVolumeCurve: false,
+                tiers: [{ calls, pricePerCall: basePrice, subtotal: totalCost }],
+            };
+        }
+        let remaining = calls;
+        let cursor = totalCallsBefore;
+        let totalCost = new BN(0);
+        while (remaining > 0) {
+            let currentPrice = basePrice;
+            let nextThreshold = null;
+            for (const bp of volumeCurve) {
+                const threshold = bp.afterCalls;
+                if (cursor >= threshold) {
+                    currentPrice = bp.pricePerCall;
+                }
+                else {
+                    nextThreshold = threshold;
+                    break;
+                }
+            }
+            const callsAtPrice = nextThreshold !== null
+                ? Math.min(remaining, nextThreshold - cursor)
+                : remaining;
+            const subtotal = currentPrice.mul(new BN(callsAtPrice));
+            totalCost = totalCost.add(subtotal);
+            tiers.push({ calls: callsAtPrice, pricePerCall: currentPrice, subtotal });
+            remaining -= callsAtPrice;
+            cursor += callsAtPrice;
+        }
+        const effectivePricePerCall = calls > 0
+            ? totalCost.div(new BN(calls))
+            : new BN(0);
+        return {
+            totalCost,
+            calls,
+            effectivePricePerCall,
+            hasVolumeCurve: true,
+            tiers,
+        };
+    }
+    // ── Escrow Lifecycle (Client Side) ───────────────────
+    /**
+     * @name preparePayment
+     * @description Prepare an x402 payment flow — creates and funds an escrow.
+     * Derives the escrow PDA, sends the `createEscrow` instruction, and returns
+     * a {@link PaymentContext} for building x402 headers.
+     *
+     * @param agentWallet - The agent’s wallet public key.
+     * @param opts - Payment options (price, max calls, deposit, etc.).
+     * @returns A {@link PaymentContext} with escrow details and transaction signature.
+     * @since v0.1.0
+     * @deprecated Since v0.7.0 — Creates a V1 escrow. Use `client.escrowV2.create()` for
+     * V2 escrows with dispute windows, co-signing, and settlement security.
+     *
+     * @example
+     * ```ts
+     * const ctx = await x402.preparePayment(agentWallet, {
+     *   pricePerCall: 1000,
+     *   maxCalls: 100,
+     *   deposit: 100_000,
+     * });
+     * ```
+     */
+    async preparePayment(agentWallet, opts) {
+        const [agentPda] = deriveAgent(agentWallet);
+        const [escrowPda] = deriveEscrow(agentPda, this.wallet);
+        const pricePerCall = new BN(opts.pricePerCall.toString());
+        const maxCalls = new BN((opts.maxCalls ?? 0).toString());
+        const initialDeposit = new BN(opts.deposit.toString());
+        const expiresAt = new BN((opts.expiresAt ?? 0).toString());
+        const volumeCurve = (opts.volumeCurve ?? []).map((v) => ({
+            afterCalls: v.afterCalls,
+            pricePerCall: new BN(v.pricePerCall.toString()),
+        }));
+        const txSignature = await this.methods
+            .createEscrow(pricePerCall, maxCalls, initialDeposit, expiresAt, volumeCurve, opts.tokenMint ?? null, opts.tokenDecimals ?? 9)
+            .accounts({
+            depositor: this.wallet,
+            agent: agentPda,
+            escrow: escrowPda,
+            systemProgram: SystemProgram.programId,
+        })
+            .rpc();
+        return {
+            escrowPda,
+            agentPda,
+            agentWallet,
+            depositorWallet: this.wallet,
+            pricePerCall,
+            maxCalls,
+            txSignature,
+            networkIdentifier: opts.networkIdentifier ?? SapNetwork.SOLANA_MAINNET,
+        };
+    }
+    /**
+     * @name addFunds
+     * @description Add more funds to an existing escrow.
+     *
+     * @param agentWallet - Agent wallet of the escrow.
+     * @param amount - Amount to deposit in smallest token unit.
+     * @returns The transaction signature.
+     * @since v0.1.0
+     * @deprecated Since v0.7.0 — Operates on V1 escrows only. Use `client.escrowV2.deposit()` instead.
+     */
+    async addFunds(agentWallet, amount) {
+        const [agentPda] = deriveAgent(agentWallet);
+        const [escrowPda] = deriveEscrow(agentPda, this.wallet);
+        return this.methods
+            .depositEscrow(new BN(amount.toString()))
+            .accounts({
+            depositor: this.wallet,
+            escrow: escrowPda,
+            systemProgram: SystemProgram.programId,
+        })
+            .rpc();
+    }
+    /**
+     * @name withdrawFunds
+     * @description Withdraw remaining funds from an escrow.
+     *
+     * @param agentWallet - Agent wallet of the escrow.
+     * @param amount - Amount to withdraw in smallest token unit.
+     * @returns The transaction signature.
+     * @since v0.1.0
+     * @deprecated Since v0.7.0 — Operates on V1 escrows only. Use `client.escrowV2.withdraw()` instead.
+     */
+    async withdrawFunds(agentWallet, amount) {
+        const [agentPda] = deriveAgent(agentWallet);
+        const [escrowPda] = deriveEscrow(agentPda, this.wallet);
+        return this.methods
+            .withdrawEscrow(new BN(amount.toString()))
+            .accounts({
+            depositor: this.wallet,
+            escrow: escrowPda,
+            systemProgram: SystemProgram.programId,
+        })
+            .rpc();
+    }
+    /**
+     * @name closeEscrow
+     * @description Close an empty escrow (balance must be 0).
+     * Reclaims the rent-exempt lamports.
+     *
+     * @param agentWallet - Agent wallet of the escrow.
+     * @returns The transaction signature.
+     * @since v0.1.0
+     * @deprecated Since v0.7.0 — Operates on V1 escrows only. Use `client.escrowV2.close()` instead.
+     */
+    async closeEscrow(agentWallet) {
+        const [agentPda] = deriveAgent(agentWallet);
+        const [escrowPda] = deriveEscrow(agentPda, this.wallet);
+        return this.methods
+            .closeEscrow()
+            .accounts({
+            depositor: this.wallet,
+            escrow: escrowPda,
+        })
+            .rpc();
+    }
+    // ── x402 HTTP Headers ────────────────────────────────
+    /**
+     * @name buildPaymentHeaders
+     * @description Build x402 HTTP headers for API requests.
+     * Include these headers when calling an agent’s x402 endpoint.
+     *
+     * @param ctx - Payment context from {@link X402Registry.preparePayment}.
+     * @param opts - Optional settings.
+     * @param opts.network - Solana cluster name (defaults to `"mainnet-beta"`).
+     * @returns An {@link X402Headers} object ready to merge into HTTP requests.
+     * @since v0.1.0
+     */
+    buildPaymentHeaders(ctx, opts) {
+        // Prefer: explicit override → ctx.networkIdentifier → default
+        const rawNetwork = opts?.network ?? ctx.networkIdentifier ?? SapNetwork.SOLANA_MAINNET;
+        return {
+            "X-Payment-Protocol": "SAP-x402",
+            "X-Payment-Escrow": ctx.escrowPda.toBase58(),
+            "X-Payment-Agent": ctx.agentPda.toBase58(),
+            "X-Payment-Depositor": ctx.depositorWallet.toBase58(),
+            "X-Payment-MaxCalls": ctx.maxCalls.toString(),
+            "X-Payment-PricePerCall": ctx.pricePerCall.toString(),
+            "X-Payment-Program": this.program.programId.toBase58(),
+            "X-Payment-Network": rawNetwork,
+        };
+    }
+    /**
+     * @name buildPaymentHeadersFromEscrow
+     * @description Build x402 headers directly from an agent wallet (fetches escrow data).
+     * Convenience method that fetches the escrow account on-chain.
+     *
+     * @param agentWallet - Agent wallet to look up the escrow for.
+     * @param opts - Optional settings.
+     * @param opts.network - Network identifier for the `X-Payment-Network` header.
+     *   Defaults to `SapNetwork.SOLANA_MAINNET`.
+     * @returns An {@link X402Headers} object, or `null` if no escrow exists.
+     * @since v0.1.0
+     */
+    async buildPaymentHeadersFromEscrow(agentWallet, opts) {
+        const [agentPda] = deriveAgent(agentWallet);
+        const resolved = await this.resolveEscrow(agentPda, this.wallet);
+        if (!resolved)
+            return null;
+        const escrow = resolved.escrow;
+        return {
+            "X-Payment-Protocol": "SAP-x402",
+            "X-Payment-Escrow": resolved.escrowPda.toBase58(),
+            "X-Payment-Agent": agentPda.toBase58(),
+            "X-Payment-Depositor": this.wallet.toBase58(),
+            "X-Payment-MaxCalls": escrow.maxCalls.toString(),
+            "X-Payment-PricePerCall": escrow.pricePerCall.toString(),
+            "X-Payment-Program": this.program.programId.toBase58(),
+            "X-Payment-Network": opts?.network ?? SapNetwork.SOLANA_MAINNET,
+        };
+    }
+    // ── Settlement (Agent Side) ──────────────────────────
+    /**
+     * @name settle
+     * @description Settle calls — agent claims payment for calls served.
+     * Must be called by the agent owner wallet. Calculates the settlement
+     * amount using the escrow’s pricing and volume curve.
+     *
+     * @param depositorWallet - The client wallet that funded the escrow.
+     * @param callsToSettle - Number of calls to settle.
+     * @param serviceData - Raw service data (auto-hashed to `service_hash`).
+     * @param opts - Optional {@link SettleOptions} for priority fees and RPC tuning.
+     * @returns A {@link SettlementResult} with transaction details and amount.
+     * @since v0.1.0
+     * @updated v0.6.2 — Added optional `opts` parameter for priority fees.
+     *
+     * @example
+     * ```ts
+     * // Default (no priority fee)
+     * const receipt = await x402.settle(depositor, 1, "data");
+     *
+     * // Fast settlement with priority fee
+     * import { FAST_SETTLE_OPTIONS } from "@synapse-sap/sdk";
+     * const receipt = await x402.settle(depositor, 1, "data", FAST_SETTLE_OPTIONS);
+     *
+     * // Custom priority fee
+     * const receipt = await x402.settle(depositor, 1, "data", {
+     *   priorityFeeMicroLamports: 10_000,
+     *   computeUnits: 100_000,
+     *   skipPreflight: true,
+     * });
+     * ```
+     */
+    async settle(depositorWallet, callsToSettle, serviceData, opts) {
+        const serviceHash = hashToArray(sha256(typeof serviceData === "string" ? serviceData : Buffer.from(serviceData)));
+        const [agentPda] = deriveAgent(this.wallet);
+        const [statsPda] = deriveAgentStats(agentPda);
+        // Auto-detect escrow version
+        const resolved = await this.resolveEscrow(agentPda, depositorWallet);
+        if (!resolved) {
+            throw new Error("No escrow found for this agent + depositor pair");
+        }
+        const escrow = resolved.escrow;
+        const escrowPda = resolved.escrowPda;
+        const estimate = this.calculateCost(escrow.pricePerCall, escrow.volumeCurve, escrow.totalCallsSettled.toNumber(), callsToSettle);
+        // Build priority fee instructions (empty array if no opts)
+        const preIxs = buildPriorityFeeIxs(opts);
+        const rpcOpts = buildRpcOptions(opts);
+        let builder;
+        if (resolved.version === 2) {
+            // V2: settleCallsV2 requires escrow_nonce (default 0)
+            builder = this.methods
+                .settleCallsV2(new BN(0), new BN(callsToSettle), serviceHash)
+                .accounts({
+                wallet: this.wallet,
+                agent: agentPda,
+                agentStats: statsPda,
+                escrow: escrowPda,
+                systemProgram: SystemProgram.programId,
+            });
+        }
+        else {
+            builder = this.methods
+                .settleCalls(new BN(callsToSettle), serviceHash)
+                .accounts({
+                wallet: this.wallet,
+                agent: agentPda,
+                agentStats: statsPda,
+                escrow: escrowPda,
+                systemProgram: SystemProgram.programId,
+            });
+        }
+        if (preIxs.length > 0) {
+            builder = builder.preInstructions(preIxs);
+        }
+        const txSignature = await builder.rpc(rpcOpts);
+        return {
+            txSignature,
+            callsSettled: callsToSettle,
+            amount: estimate.totalCost,
+            serviceHash,
+        };
+    }
+    /**
+     * @name settleBatch
+     * @description Batch settle — process up to 10 settlements in one TX.
+     * Must be called by the agent owner wallet. More gas-efficient than
+     * individual settlements.
+     *
+     * Optionally accepts {@link SettleOptions} to configure priority fees,
+     * compute budget, and RPC behavior for faster confirmation.
+     *
+     * @param depositorWallet - The client wallet that funded the escrow.
+     * @param entries - Array of `{ calls, serviceData }` settlement entries.
+     * @param opts - Optional {@link SettleOptions} for priority fees and RPC tuning.
+     * @returns A {@link BatchSettlementResult} with aggregated totals.
+     * @since v0.1.0
+     * @updated v0.6.2 — Added optional `opts` parameter for priority fees.
+     *
+     * @example
+     * ```ts
+     * import { FAST_BATCH_SETTLE_OPTIONS } from "@synapse-sap/sdk";
+     * const receipt = await x402.settleBatch(depositor, entries, FAST_BATCH_SETTLE_OPTIONS);
+     * ```
+     */
+    async settleBatch(depositorWallet, entries, opts) {
+        const settlements = entries.map((e) => ({
+            callsToSettle: new BN(e.calls),
+            serviceHash: hashToArray(sha256(typeof e.serviceData === "string" ? e.serviceData : Buffer.from(e.serviceData))),
+        }));
+        const totalCalls = entries.reduce((sum, e) => sum + e.calls, 0);
+        const [agentPda] = deriveAgent(this.wallet);
+        const [statsPda] = deriveAgentStats(agentPda);
+        // Auto-detect escrow version
+        const resolved = await this.resolveEscrow(agentPda, depositorWallet);
+        if (!resolved) {
+            throw new Error("No escrow found for this agent + depositor pair");
+        }
+        const escrow = resolved.escrow;
+        const escrowPda = resolved.escrowPda;
+        const estimate = this.calculateCost(escrow.pricePerCall, escrow.volumeCurve, escrow.totalCallsSettled.toNumber(), totalCalls);
+        // Auto-size CU to the batch length when the caller didn't pin one.
+        // Default Solana cap (200k) is tight past ~8 entries; a CU limit
+        // costs nothing extra (only caps the maximum charge).
+        const effectiveOpts = {
+            ...opts,
+            computeUnits: opts?.computeUnits ?? computeBatchSettleCu(settlements.length),
+        };
+        const preIxs = buildPriorityFeeIxs(effectiveOpts);
+        const rpcOpts = buildRpcOptions(effectiveOpts);
+        let builder = this.methods
+            .settleBatch(settlements)
+            .accountsPartial({
+            wallet: this.wallet,
+            agent: agentPda,
+            agentStats: statsPda,
+            escrow: escrowPda,
+            systemProgram: SystemProgram.programId,
+        });
+        if (preIxs.length > 0) {
+            builder = builder.preInstructions(preIxs);
+        }
+        const txSignature = await builder.rpc(rpcOpts);
+        return {
+            txSignature,
+            totalCalls,
+            totalAmount: estimate.totalCost,
+            settlementCount: entries.length,
+        };
+    }
+    // ── Balance & Status ─────────────────────────────────
+    /**
+     * @name getBalance
+     * @description Get the current escrow balance and status.
+     * Returns balance, deposit/settlement totals, remaining calls,
+     * expiry status, and affordable call estimate.
+     *
+     * @param agentWallet - Agent wallet of the escrow.
+     * @param depositor - Depositor wallet (defaults to caller).
+     * @returns An {@link EscrowBalance}, or `null` if no escrow exists.
+     * @since v0.1.0
+     */
+    async getBalance(agentWallet, depositor) {
+        const [agentPda] = deriveAgent(agentWallet);
+        const dep = depositor ?? this.wallet;
+        const resolved = await this.resolveEscrow(agentPda, dep);
+        if (!resolved)
+            return null;
+        const escrow = resolved.escrow;
+        const now = Math.floor(Date.now() / 1000);
+        const isExpired = escrow.expiresAt.toNumber() > 0 && now >= escrow.expiresAt.toNumber();
+        const maxCalls = escrow.maxCalls.toNumber();
+        const settled = escrow.totalCallsSettled.toNumber();
+        const callsRemaining = maxCalls > 0 ? maxCalls - settled : Infinity;
+        const pricePerCall = escrow.pricePerCall.toNumber();
+        const balance = escrow.balance.toNumber();
+        const affordableCalls = pricePerCall > 0
+            ? Math.floor(balance / pricePerCall)
+            : Infinity;
+        return {
+            balance: escrow.balance,
+            totalDeposited: escrow.totalDeposited,
+            totalSettled: escrow.totalSettled,
+            totalCallsSettled: escrow.totalCallsSettled,
+            callsRemaining: Math.min(callsRemaining, affordableCalls),
+            isExpired,
+            affordableCalls,
+        };
+    }
+    /**
+     * @name hasEscrow
+     * @description Check if an escrow exists for a given agent + depositor pair.
+     *
+     * @param agentWallet - Agent wallet to check.
+     * @param depositor - Depositor wallet (defaults to caller).
+     * @returns `true` if the escrow account exists on-chain.
+     * @since v0.1.0
+     */
+    async hasEscrow(agentWallet, depositor) {
+        const [agentPda] = deriveAgent(agentWallet);
+        const dep = depositor ?? this.wallet;
+        const conn = this.program.provider.connection;
+        // Check V2 first (nonce=0)
+        const [v2Pda] = deriveEscrowV2(agentPda, dep, 0);
+        const v2Info = await conn.getAccountInfo(v2Pda);
+        if (v2Info !== null)
+            return true;
+        // Fall back to V1
+        const [v1Pda] = deriveEscrow(agentPda, dep);
+        const v1Info = await conn.getAccountInfo(v1Pda);
+        return v1Info !== null;
+    }
+    /**
+     * @name fetchEscrow
+     * @description Fetch the raw escrow account data.
+     *
+     * @param agentWallet - Agent wallet of the escrow.
+     * @param depositor - Depositor wallet (defaults to caller).
+     * @returns The raw {@link EscrowAccountData}, or `null` if not found.
+     * @since v0.1.0
+     */
+    async fetchEscrow(agentWallet, depositor) {
+        const [agentPda] = deriveAgent(agentWallet);
+        const dep = depositor ?? this.wallet;
+        const resolved = await this.resolveEscrow(agentPda, dep);
+        return resolved?.escrow ?? null;
+    }
+    // ── Internals ────────────────────────────────────────
+    /**
+     * @name methods
+     * @description Accessor for the Anchor program methods namespace.
+     * @returns The program methods object for building RPC calls.
+     * @private
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    get methods() {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return this.program.methods;
+    }
+    /**
+     * @name fetchNullable
+     * @description Fetch an on-chain account by name and PDA. Returns `null` if not found.
+     * @param name - Anchor account discriminator name.
+     * @param pda - Account public key to fetch.
+     * @returns The deserialized account data, or `null` if the account does not exist.
+     * @private
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async fetchNullable(name, pda) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+        return this.program.account[name].fetchNullable(pda);
+    }
+    /**
+     * @name resolveEscrow
+     * @description Try to find an escrow: V2 (nonce=0) first, then V1 fallback.
+     * Returns the escrow data, PDA, and version indicator.
+     * @private
+     */
+    async resolveEscrow(agentPda, depositor) {
+        // Try V2 first (nonce=0 is the default)
+        const [v2Pda] = deriveEscrowV2(agentPda, depositor, 0);
+        const v2 = await this.fetchNullable("escrowAccountV2", v2Pda);
+        if (v2)
+            return { escrow: v2, escrowPda: v2Pda, version: 2 };
+        // Fall back to V1
+        const [v1Pda] = deriveEscrow(agentPda, depositor);
+        const v1 = await this.fetchNullable("escrowAccount", v1Pda);
+        if (v1)
+            return { escrow: v1, escrowPda: v1Pda, version: 1 };
+        return null;
+    }
+}
+//# sourceMappingURL=x402.js.map