@oobe-protocol-labs/synapse-sap-sdk 0.13.0 → 0.15.0

package/dist/esm/utils/validate.js

@@ -0,0 +1,221 @@
+// ================================================================
+//  synapse-sap-sdk / src/utils/validate.ts
+//  Client-side validation — mirrors every on-chain check (v0.13)
+// ================================================================
+import BN from "bn.js";
+import { SettlementSecurity } from "../types";
+import { MAX_CALLS_PER_SETTLEMENT, MAX_VOLUME_CURVE_POINTS, MAX_RECEIPTS_PER_PROOF, MAX_MERKLE_DEPTH, MAX_SUBSCRIPTION_DURATION_YEARS, STAKE_COVERAGE_BPS, MIN_STAKE_LAMPORTS, } from "../constants";
+function fail(msg) {
+    return { ok: false, errors: [msg] };
+}
+function ok() {
+    return { ok: true, errors: [] };
+}
+/** Validate agent creation parameters */
+export function validateAgentInput(params) {
+    if (params.name.length < 3)
+        return fail("Agent name must be ≥3 characters");
+    if (params.name.length > 64)
+        return fail("Agent name must be ≤64 characters");
+    if (params.endpointUri.length > 256)
+        return fail("Endpoint URI must be ≤256 characters");
+    if (!/^https?:\/\//.test(params.endpointUri))
+        return fail("Endpoint URI must start with http:// or https://");
+    return ok();
+}
+/** Compute max_obligation for an escrow (must match on-chain logic) */
+export function computeEscrowMaxObligation(pricePerCall, maxCalls, initialDeposit) {
+    // If maxCalls == 0 → unlimited calls: cap at initialDeposit (v0.13 logic)
+    if (maxCalls.isZero())
+        return initialDeposit;
+    const maxPotential = pricePerCall.mul(maxCalls);
+    // On-chain: required = maxPotential * 50% (5000 bps)
+    const coverage = maxPotential.mul(new BN(STAKE_COVERAGE_BPS)).div(new BN(10_000));
+    const min = new BN(MIN_STAKE_LAMPORTS);
+    return BN.max(coverage, min);
+}
+/** Validate escrow V2 creation parameters (mirrors create_escrow_v2 on-chain checks) */
+export function validateEscrowCreate(params) {
+    const errors = [];
+    // C1: price_per_call > 0
+    if (params.pricePerCall.isZero()) {
+        errors.push("[C1] price_per_call must be > 0");
+    }
+    // H6: escrow cannot be already expired
+    const nowSec = Math.floor(Date.now() / 1000);
+    if (!params.expiresAt.isZero() && params.expiresAt.lt(new BN(nowSec))) {
+        errors.push(`[H6] expires_at (${params.expiresAt}) is in the past (${nowSec})`);
+    }
+    // Volume curve validation
+    if (params.volumeCurve.length > MAX_VOLUME_CURVE_POINTS) {
+        errors.push(`[C1] Volume curve exceeds ${MAX_VOLUME_CURVE_POINTS} points`);
+    }
+    for (let i = 0; i < params.volumeCurve.length; i++) {
+        const bp = params.volumeCurve[i];
+        // C1: price_per_call > 0 for every breakpoint
+        if (bp.pricePerCall.isZero()) {
+            errors.push(`[C1] Volume curve[${i}] price_per_call must be > 0`);
+        }
+        // Strictly increasing after_calls
+        if (i > 0 && bp.afterCalls <= params.volumeCurve[i - 1].afterCalls) {
+            errors.push(`[C1] Volume curve[${i}] after_calls must be > previous`);
+        }
+        // Non-increasing prices
+        if (i > 0 && bp.pricePerCall.gt(params.volumeCurve[i - 1].pricePerCall)) {
+            errors.push(`[C1] Volume curve[${i}] price must be ≤ previous`);
+        }
+    }
+    // Settlement security specific
+    if (params.settlementSecurity === SettlementSecurity.CoSigned) {
+        if (!params.coSigner) {
+            errors.push("[H9] CoSigned mode requires a co_signer");
+        }
+        else if (params.coSigner.equals(params.agentWallet)) {
+            errors.push("[H9] co_signer cannot be the agent wallet itself");
+        }
+    }
+    if (params.settlementSecurity === SettlementSecurity.DisputeWindow) {
+        if (params.disputeWindowSlots === 0) {
+            errors.push("[H6] DisputeWindow mode requires dispute_window_slots > 0");
+        }
+        if (!params.arbiter) {
+            errors.push("[H6] DisputeWindow mode requires an arbiter");
+        }
+    }
+    return errors.length > 0 ? { ok: false, errors } : ok();
+}
+/** Validate deposit parameters */
+export function validateEscrowDeposit(params) {
+    const errors = [];
+    if (params.amount.isZero())
+        errors.push("[C2] Deposit amount must be > 0");
+    // H-2: projection must not exceed max_obligation (if set)
+    if (!params.escrowMaxObligation.isZero()) {
+        const projected = params.escrowBalance.add(params.amount);
+        if (projected.gt(params.escrowMaxObligation)) {
+            errors.push(`[H2] Deposit would exceed max_obligation (${projected.toString()} > ${params.escrowMaxObligation.toString()})`);
+        }
+    }
+    return errors.length > 0 ? { ok: false, errors } : ok();
+}
+/** Validate settle_calls_v2 parameters (pre-computation) */
+export function validateEscrowSettle(params) {
+    const errors = [];
+    if (params.callsToSettle <= 0)
+        errors.push("callsToSettle must be > 0");
+    // C1: max calls per settlement ≤ 10,000
+    if (params.callsToSettle > MAX_CALLS_PER_SETTLEMENT) {
+        errors.push(`[C1] callsToSettle (${params.callsToSettle}) exceeds MAX_CALLS_PER_SETTLEMENT (${MAX_CALLS_PER_SETTLEMENT})`);
+    }
+    const callsBN = new BN(params.callsToSettle);
+    // Max calls check
+    if (!params.escrowMaxCalls.isZero()) {
+        const projected = params.escrowTotalCallsSettled
+            .add(params.escrowPendingCalls)
+            .add(callsBN);
+        if (projected.gt(params.escrowMaxCalls)) {
+            errors.push(`Max calls would be exceeded (${projected.toString()} > ${params.escrowMaxCalls.toString()})`);
+        }
+    }
+    // Compute amount (client-side mirror of calculate_settle_amount)
+    const amount = calculateSettleAmount(params.pricePerCall, params.basePrice ?? params.pricePerCall, params.volumeCurve ?? [], params.callsToSettle);
+    // Available balance check
+    const available = params.escrowBalance.sub(params.escrowPendingAmount);
+    if (available.lt(amount)) {
+        errors.push(`Insufficient balance: available ${available.toString()} < required ${amount.toString()}`);
+    }
+    return errors.length > 0 ? { ok: false, errors, amount: new BN(0) } : { ok: true, errors: [], amount };
+}
+/** Client-side mirror of on-chain calculate_settle_amount (v0.13) */
+export function calculateSettleAmount(pricePerCall, basePrice, volumeCurve, calls) {
+    if (calls <= 0)
+        return new BN(0);
+    if (volumeCurve.length === 0) {
+        return pricePerCall.mul(new BN(calls));
+    }
+    let amount = new BN(0);
+    let remaining = calls;
+    let cursor = 0;
+    let currentPrice = basePrice;
+    while (remaining > 0) {
+        // Find applicable breakpoint
+        let threshold = 0;
+        for (const bp of volumeCurve) {
+            if (cursor >= bp.afterCalls) {
+                currentPrice = bp.pricePerCall;
+            }
+            else {
+                threshold = bp.afterCalls;
+                break;
+            }
+        }
+        const range = threshold === 0
+            ? remaining
+            : Math.min(threshold - cursor, remaining);
+        amount = amount.add(new BN(range).mul(currentPrice));
+        remaining -= range;
+        cursor += range;
+        // Safety: break if stuck
+        if (range === 0)
+            break;
+    }
+    return amount;
+}
+/** Validate receipt proof submission (C4 bounds check) */
+export function validateReceiptProof(receiptHashes, merkleProofs) {
+    const errors = [];
+    if (receiptHashes.length > MAX_RECEIPTS_PER_PROOF) {
+        errors.push(`[C4] receipt_hashes (${receiptHashes.length}) > MAX_RECEIPTS_PER_PROOF (${MAX_RECEIPTS_PER_PROOF})`);
+    }
+    if (receiptHashes.length !== merkleProofs.length) {
+        errors.push(`receipt_hashes.length (${receiptHashes.length}) !== merkleProofs.length (${merkleProofs.length})`);
+    }
+    for (let i = 0; i < merkleProofs.length; i++) {
+        if (merkleProofs[i].length > MAX_MERKLE_DEPTH) {
+            errors.push(`[C4] merkleProofs[${i}] depth (${merkleProofs[i].length}) > MAX_MERKLE_DEPTH (${MAX_MERKLE_DEPTH})`);
+        }
+    }
+    return errors.length > 0 ? { ok: false, errors } : ok();
+}
+/** Validate subscription parameters */
+export function validateSubscriptionCreate(params) {
+    const errors = [];
+    // M13: cap duration at 10 years
+    const maxIntervals = MAX_SUBSCRIPTION_DURATION_YEARS * 365 * 24; // hourly max
+    if (params.durationIntervals > maxIntervals && params.durationIntervals <= 0) {
+        errors.push(`[M13] Duration exceeds ${MAX_SUBSCRIPTION_DURATION_YEARS} years`);
+    }
+    if (params.pricePerInterval.isZero()) {
+        errors.push("price_per_interval must be > 0");
+    }
+    return errors.length > 0 ? { ok: false, errors } : ok();
+}
+/** Validate close_escrow_v2 can proceed (H8 check) */
+export function validateEscrowClose(pendingSettlementCount, balance, pendingAmount) {
+    const errors = [];
+    if (pendingSettlementCount > 0) {
+        errors.push(`[H8] Escrow has ${pendingSettlementCount} pending settlement(s). Finalize or dispute before closing.`);
+    }
+    if (balance.gt(new BN(0)) && !balance.eq(pendingAmount)) {
+        errors.push("Escrow has non-pending balance remaining — withdraw first.");
+    }
+    return errors.length > 0 ? { ok: false, errors } : ok();
+}
+/** Validate agent close (stake + active_escrows) */
+export function validateAgentClose(stakedAmount, activeEscrows, unstakeAvailableAt) {
+    const errors = [];
+    if (!stakedAmount.isZero()) {
+        errors.push("Agent has staked amount — unstake first.");
+    }
+    if (activeEscrows > 0) {
+        errors.push(`[H1] Agent has ${activeEscrows} active escrow(s) — close all escrows first.`);
+    }
+    if (!unstakeAvailableAt.isZero() && stakedAmount.gt(new BN(0))) {
+        const now = Math.floor(Date.now() / 1000);
+        if (unstakeAvailableAt.gt(new BN(now))) {
+            errors.push("Unstake cooldown has not expired yet.");
+        }
+    }
+    return errors.length > 0 ? { ok: false, errors } : ok();
+}
+//# sourceMappingURL=validate.js.map

package/dist/esm/utils/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../src/utils/validate.ts"],"names":[],"mappings":"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"}

package/{src/utils/validation.ts → dist/esm/utils/validation.d.ts}

@@ -5,7 +5,6 @@
  * @category Utils
  * @since v0.1.0
  */
-
 /**
  * Assert that a condition holds, throwing a descriptive error otherwise.
  *
@@ -26,11 +25,5 @@
  * assert(name.length <= 64, "Agent name exceeds MAX_NAME_LEN");
  * ```
  */
-export function assert(
-  condition: boolean,
-  message: string,
-): asserts condition {
-  if (!condition) {
-    throw new RangeError(`[SAP SDK] ${message}`);
-  }
-}
+export declare function assert(condition: boolean, message: string): asserts condition;
+//# sourceMappingURL=validation.d.ts.map

package/dist/esm/utils/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/utils/validation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,MAAM,CACpB,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,SAAS,CAInB"}

package/{src/utils/volume-curve.ts → dist/esm/utils/volume-curve.d.ts}

@@ -14,32 +14,8 @@
  * @since v0.13.0
  * @packageDocumentation
  */
-
 import { BN } from "@coral-xyz/anchor";
 import type { VolumeCurveBreakpoint } from "../types/common";
-
-const U64_MAX = new BN("18446744073709551615");
-
-function checkedMul(a: BN, b: BN): BN {
-  const r = a.mul(b);
-  if (r.gt(U64_MAX)) {
-    throw new Error(
-      `volume-curve: u64 overflow on multiply (${a.toString()} * ${b.toString()})`,
-    );
-  }
-  return r;
-}
-
-function checkedAdd(a: BN, b: BN): BN {
-  const r = a.add(b);
-  if (r.gt(U64_MAX)) {
-    throw new Error(
-      `volume-curve: u64 overflow on add (${a.toString()} + ${b.toString()})`,
-    );
-  }
-  return r;
-}
-
 /**
  * @function calculateSettleAmount
  * @description Compute the lamport (or token base-unit) amount the on-chain
@@ -80,52 +56,5 @@ function checkedAdd(a: BN, b: BN): BN {
  *
  * @since v0.13.0
  */
-export function calculateSettleAmount(
-  basePrice: BN,
-  curve: VolumeCurveBreakpoint[],
-  totalCallsBefore: BN,
-  calls: BN,
-): BN {
-  if (calls.isZero()) return new BN(0);
-  if (!curve || curve.length === 0) {
-    return checkedMul(calls, basePrice);
-  }
-
-  let amount = new BN(0);
-  let remaining = calls.clone();
-  let cursor = totalCallsBefore.clone();
-
-  while (remaining.gtn(0)) {
-    let currentPrice = basePrice;
-    let nextThreshold: BN | null = null;
-
-    for (const bp of curve) {
-      const threshold = new BN(bp.afterCalls);
-      if (cursor.gte(threshold)) {
-        currentPrice = bp.pricePerCall;
-      } else {
-        nextThreshold = threshold;
-        break;
-      }
-    }
-
-    let callsAtPrice: BN;
-    if (nextThreshold) {
-      const room = nextThreshold.sub(cursor);
-      callsAtPrice = BN.min(remaining, room.isNeg() ? new BN(0) : room);
-      if (callsAtPrice.isZero()) {
-        // Defensive: shouldn't happen because cursor < nextThreshold by
-        // the `else` branch above, but guard anyway.
-        callsAtPrice = remaining;
-      }
-    } else {
-      callsAtPrice = remaining;
-    }
-
-    amount = checkedAdd(amount, checkedMul(callsAtPrice, currentPrice));
-    remaining = remaining.sub(callsAtPrice);
-    cursor = cursor.add(callsAtPrice);
-  }
-
-  return amount;
-}
+export declare function calculateSettleAmount(basePrice: BN, curve: VolumeCurveBreakpoint[], totalCallsBefore: BN, calls: BN): BN;
+//# sourceMappingURL=volume-curve.d.ts.map

package/dist/esm/utils/volume-curve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"volume-curve.d.ts","sourceRoot":"","sources":["../../../src/utils/volume-curve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,EAAE,EAAE,MAAM,mBAAmB,CAAC;AACvC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAwB7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,EAAE,EACb,KAAK,EAAE,qBAAqB,EAAE,EAC9B,gBAAgB,EAAE,EAAE,EACpB,KAAK,EAAE,EAAE,GACR,EAAE,CA2CJ"}

package/dist/esm/utils/volume-curve.js

@@ -79,7 +79,7 @@ export function calculateSettleAmount(basePrice, curve, totalCallsBefore, calls)
     let amount = new BN(0);
     let remaining = calls.clone();
     let cursor = totalCallsBefore.clone();
-    while (remaining.gtn(0)) {
+    while (remaining.gt(new BN(0))) {
         let currentPrice = basePrice;
         let nextThreshold = null;
         for (const bp of curve) {

package/dist/esm/utils/volume-curve.js.map

@@ -1 +1 @@
-{"version":3,"file":"volume-curve.js","sourceRoot":"","sources":["../../../src/utils/volume-curve.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"volume-curve.js","sourceRoot":"","sources":["../../../src/utils/volume-curve.ts"],"names":[],"mappings":"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"}

package/dist/esm/utils/x402-direct.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @module utils/x402-direct
+ * @description Recognize x402 direct SPL token payments on an agent's ATA
+ * by scanning transaction history and filtering for x402 patterns.
+ *
+ * @category Utils
+ * @since v0.6.4
+ */
+import { type Connection, PublicKey } from "@solana/web3.js";
+/**
+ * @interface SettlementPayload
+ * @description Settlement metadata from the merchant's PAYMENT-RESPONSE.
+ * @category Utils
+ * @since v0.6.4
+ */
+export interface SettlementPayload {
+    /** SHA-256 service hash. */
+    readonly serviceHash: string;
+    /** Resource identifier. */
+    readonly resource: string;
+    /** Agent wallet (base58). */
+    readonly agentWallet: string;
+    /** Depositor wallet (base58). */
+    readonly depositorWallet: string;
+    /** Amount in smallest unit. */
+    readonly amount: string;
+    /** Service timestamp. */
+    readonly timestamp: number;
+}
+/**
+ * @interface X402DirectPayment
+ * @description A recognized x402 direct SPL transfer on an agent's ATA.
+ * @category Utils
+ * @since v0.6.4
+ */
+export interface X402DirectPayment {
+    /** Transaction signature. */
+    readonly signature: string;
+    /** Transfer amount (in smallest token unit). */
+    readonly amount: bigint;
+    /** Source ATA (payer). */
+    readonly payerAta: PublicKey;
+    /** Destination ATA (payTo / agent). */
+    readonly payeeAta: PublicKey;
+    /** Token mint used for transfer. */
+    readonly mint: PublicKey;
+    /** Memo data (if a Memo instruction was included). */
+    readonly memo: string | null;
+    /** Matched settlement payload (if server-side verification is available). */
+    readonly settlement: SettlementPayload | null;
+    /** Block time (unix seconds). */
+    readonly blockTime: number | null;
+    /** Slot number. */
+    readonly slot: number;
+}
+/**
+ * @interface GetX402DirectOptions
+ * @description Options for {@link getX402DirectPayments}.
+ * @category Utils
+ * @since v0.6.4
+ */
+export interface GetX402DirectOptions {
+    /** Max signatures to scan (default: 100). */
+    readonly limit?: number;
+    /** Only return transfers from this specific payer. */
+    readonly filterPayer?: PublicKey;
+    /** Known settlements from server-side PAYMENT-RESPONSE logs.
+     *  Used for deterministic hash matching. */
+    readonly knownSettlements?: SettlementPayload[];
+    /** Only include payments that match x402 memo prefix. Default: false. */
+    readonly requireMemo?: boolean;
+    /** Scan before this TX signature (pagination). */
+    readonly before?: string;
+    /** Scan after this TX signature (pagination). */
+    readonly until?: string;
+}
+/**
+ * @name getX402DirectPayments
+ * @description Scan an agent's ATA for x402 direct payments.
+ *
+ * Fetches recent transaction signatures for the given `payTo` ATA,
+ * inspects each transaction for SPL token transfers, and filters
+ * for x402 payment patterns (memo prefix, settlement hash match, etc.).
+ *
+ * @param connection - Solana RPC connection.
+ * @param payToAta   - The agent's receiving ATA (e.g. USDC ATA of Syra).
+ * @param opts       - Filter and pagination options.
+ * @returns Array of recognized x402 direct payments, newest first.
+ *
+ * @category Utils
+ * @since v0.6.4
+ *
+ * @example
+ * ```ts
+ * import { getX402DirectPayments, findATA } from "@oobe-protocol-labs/synapse-sap-sdk";
+ *
+ * const USDC_MINT = new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
+ * const payToAta = findATA(agentWallet, USDC_MINT);
+ *
+ * const payments = await getX402DirectPayments(connection, payToAta, {
+ *   limit: 50,
+ *   knownSettlements: savedSettlements, // from your API PAYMENT-RESPONSE logs
+ * });
+ *
+ * for (const p of payments) {
+ *   console.log(`${p.signature}: ${p.amount} from ${p.payerAta.toBase58()}`);
+ *   if (p.settlement) {
+ *     console.log(`  Matched settlement: ${p.settlement.serviceHash}`);
+ *   }
+ * }
+ * ```
+ */
+export declare function getX402DirectPayments(connection: Connection, payToAta: PublicKey, opts?: GetX402DirectOptions): Promise<X402DirectPayment[]>;
+//# sourceMappingURL=x402-direct.d.ts.map

package/dist/esm/utils/x402-direct.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-direct.d.ts","sourceRoot":"","sources":["../../../src/utils/x402-direct.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,KAAK,UAAU,EACf,SAAS,EAGV,MAAM,iBAAiB,CAAC;AAOzB;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,4BAA4B;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2BAA2B;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6BAA6B;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iCAAiC;IACjC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yBAAyB;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,6BAA6B;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0BAA0B;IAC1B,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC9C,iCAAiC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,mBAAmB;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,sDAAsD;IACtD,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,CAAC;IACjC;gDAC4C;IAC5C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAChD,yEAAyE;IACzE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,kDAAkD;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AA6KD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAsB,qBAAqB,CACzC,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,SAAS,EACnB,IAAI,CAAC,EAAE,oBAAoB,GAC1B,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAmE9B"}

package/dist/types/constants/seeds.d.ts

@@ -56,6 +56,8 @@ export declare const SEEDS: {
     readonly SUBSCRIPTION: "sap_sub";
     readonly SHARD: "sap_shard";
     readonly INDEX_PAGE: "sap_idx_page";
+    /** v0.12 — On-chain pricing menu for escrow price validation. Seeds: `["sap_pricing", agent_pda]`. */
+    readonly PRICING: "sap_pricing";
     /**
      * @since v0.10.0 — Anti-replay receipt PDA bound to (escrow, service_hash) or (escrow, batch_root).
      * Created via `init` on every settle_calls / settle_batch / settle_calls_v2; replays fail.

package/dist/types/constants/seeds.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"seeds.d.ts","sourceRoot":"","sources":["../../../src/constants/seeds.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA8BhB;;;OAGG;;IAEH;;;OAGG;;CAEK,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,KAAK,CAAC"}
+{"version":3,"file":"seeds.d.ts","sourceRoot":"","sources":["../../../src/constants/seeds.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA8BhB,sGAAsG;;IAEtG;;;OAGG;;IAEH;;;OAGG;;CAEK,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,KAAK,CAAC"}

package/dist/types/core/client.d.ts

@@ -30,7 +30,6 @@ import { FeedbackModule } from "../modules/feedback";
 import { IndexingModule } from "../modules/indexing";
 import { ToolsModule } from "../modules/tools";
 import { VaultModule } from "../modules/vault";
-import { EscrowModule } from "../modules/escrow";
 import { EscrowV2Module } from "../modules/escrow-v2";
 import { ReceiptModule } from "../modules/receipt";
 import { StakingModule } from "../modules/staking";
@@ -208,14 +207,30 @@ export declare class SapClient {
     get vault(): VaultModule;
     /**
      * @name escrow
-     * @description x402 escrow settlement: create escrow accounts, deposit
-     * funds, settle payments, and withdraw balances.
-     * @returns {EscrowModule} The lazily-instantiated `EscrowModule` singleton.
+     * @description ⚠️ **DEPRECATED — redirected to EscrowV2** —
+     *   `client.escrow` now returns {@link EscrowV2Module} automatically.
+     *   The legacy v1 `EscrowModule` (`createEscrow`, `depositEscrow`, `settleCalls`,
+     *   `withdrawEscrow`, `closeEscrow`, `batchSettle`) was removed from the on-chain
+     *   program in v0.12. All escrow operations are now V2-only (USDC-only, dispute
+     *   support, pricing validation).
+     *
+     *   ```ts
+     *   // ✅ v0.12+ — works via automatic redirection
+     *   await client.escrow.create(agentWallet, args);
+     *   //   ^ this calls EscrowV2Module.create() internally
+     *
+     *   // ✅ Explicit (same result)
+     *   await client.escrowV2.create(agentWallet, args);
+     *   ```
+     *
+     * @returns {EscrowV2Module} The lazily-instantiated `EscrowV2Module` singleton.
      * @category Modules
      * @since v0.1.0
-     * @see {@link EscrowModule}
+     * @updated v0.12 — redirects to EscrowV2Module (v1 instructions removed from program)
+     * @see {@link EscrowV2Module}
+     * @deprecated v0.12 — v1 escrow removed; `escrow` getter now auto-redirects to `escrowV2`.
      */
-    get escrow(): EscrowModule;
+    get escrow(): EscrowV2Module;
     /**
      * @name escrowV2
      * @description V2 escrow settlement with dispute windows, co-signing,

package/dist/types/core/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/core/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/core/client.ts"],"names":[],"mappings":"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"}

package/dist/types/errors/index.d.ts

@@ -273,4 +273,63 @@ export declare class SapPermissionError extends SapError {
      */
     constructor(message: string);
 }
+/**
+ * @name SapTransientError
+ * @description Wraps RPC failures that are *retryable* — network errors,
+ * 429 rate limits, 5xx, blockhash-not-found, node-behind, fetch-failed.
+ *
+ * SDK fetch helpers (`safeFetch`) auto-retry these with exponential backoff
+ * before re-throwing. Callers can also catch and retry at higher layers.
+ *
+ * @category Errors
+ * @since v0.13.1
+ * @extends {SapError}
+ */
+export declare class SapTransientError extends SapError {
+    readonly attempt: number;
+    readonly cause?: unknown;
+    constructor(message: string, opts?: {
+        attempt?: number;
+        cause?: unknown;
+    });
+}
+/**
+ * @name SapAlreadyExistsError
+ * @description Thrown when an `init` instruction would collide with an
+ * already-existing PDA. Detected by SDK preflight — prevents a wasted tx
+ * and surfaces an idempotent success path to callers.
+ *
+ * @category Errors
+ * @since v0.13.1
+ * @extends {SapError}
+ */
+export declare class SapAlreadyExistsError extends SapError {
+    readonly address: string;
+    readonly accountType?: string;
+    constructor(address: string, accountType?: string, hint?: string);
+}
+/**
+ * @name SapIdempotencyError
+ * @description Thrown by `safeRpc` when a transaction would replay an action
+ * that has already been recorded on-chain (e.g. settlement-receipt PDA already
+ * exists). Treat as a non-fatal idempotent success and drop the queued action.
+ *
+ * @category Errors
+ * @since v0.13.1
+ * @extends {SapError}
+ */
+export declare class SapIdempotencyError extends SapError {
+    readonly receiptAddress?: string;
+    constructor(message: string, receiptAddress?: string);
+}
+/**
+ * @name isTransientRpcError
+ * @description Heuristic classifier for RPC errors. Returns `true` for
+ * network failures, rate limits, 5xx, blockhash-not-found, node-behind,
+ * fetch-failed, ECONNRESET, ETIMEDOUT, socket hang up.
+ *
+ * @category Errors
+ * @since v0.13.1
+ */
+export declare function isTransientRpcError(err: unknown): boolean;
 //# sourceMappingURL=index.d.ts.map

package/dist/types/errors/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAMH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;OAGG;gBACS,OAAO,EAAE,MAAM,EAAE,IAAI,SAAc;CAOhD;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;IAC9C;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;gBACS,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;CAK5C;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,WAAY,SAAQ,QAAQ;IACvC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAElC;;;;;OAKG;gBAED,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE;IAQvD;;;;;;;;;;;;;;;;;;OAkBG;IAEH,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,WAAW;CAOzC;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,uBAAwB,SAAQ,QAAQ;IACnD;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B;;;OAGG;gBACS,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;CAOlD;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;;OAGG;gBACS,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAK/C;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;IAC9C;;OAEG;gBACS,OAAO,EAAE,MAAM;CAI5B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAMH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;OAGG;gBACS,OAAO,EAAE,MAAM,EAAE,IAAI,SAAc;CAOhD;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;IAC9C;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;gBACS,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;CAK5C;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,WAAY,SAAQ,QAAQ;IACvC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAElC;;;;;OAKG;gBAED,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE;IAQvD;;;;;;;;;;;;;;;;;;OAkBG;IAEH,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,WAAW;CAOzC;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,uBAAwB,SAAQ,QAAQ;IACnD;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B;;;OAGG;gBACS,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;CAOlD;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;;OAGG;gBACS,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAK/C;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;IAC9C;;OAEG;gBACS,OAAO,EAAE,MAAM;CAI5B;AAMD;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAkB,SAAQ,QAAQ;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;gBACb,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAM1E;AAED;;;;;;;;;GASG;AACH,qBAAa,qBAAsB,SAAQ,QAAQ;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;gBAClB,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAQjE;AAED;;;;;;;;;GASG;AACH,qBAAa,mBAAoB,SAAQ,QAAQ;IAC/C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;gBACrB,OAAO,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM;CAKrD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAsBzD"}