@subly_fi/pay 0.3.0 → 0.4.0

package/dist/pay.js

@@ -1,3 +1,7 @@
+// src/pay.ts
+import { homedir } from "node:os";
+import { join as join2 } from "node:path";
+
 // ../../src/client/agent-wallet-signer.ts
 import { signBytes } from "@solana/kit";
 import bs584 from "bs58";
@@ -19,6 +23,7 @@ import {
 
 // ../../src/lib/hash.ts
 import { createHash } from "node:crypto";
+var EMPTY_BODY_HASH = "sha256-e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
 function sha256TaggedHex(data) {
   return `sha256-${createHash("sha256").update(data).digest("hex")}`;
 }
@@ -115,12 +120,12 @@ function deriveAssociatedTokenAddress(params) {
     "associatedTokenProgramId"
   );
   for (let bump = 255; bump >= 0; bump -= 1) {
-    const address3 = createProgramAddress(
+    const address2 = createProgramAddress(
       [owner, tokenProgramId, mint, Uint8Array.of(bump)],
       associatedTokenProgramId
     );
-    if (address3 !== null) {
-      return bs582.encode(address3);
+    if (address2 !== null) {
+      return bs582.encode(address2);
     }
   }
   throw new Error("Unable to derive associated token account address");
@@ -1036,9 +1041,6 @@ async function ensureWalletOnboarded(params) {
   await post("sync", `/v1/wallets/${wallet}/sync`, { source: "chain" });
 }
 
-// ../../src/client/relayer-yield-realizer.ts
-import { address as address2 } from "@solana/kit";
-
 // ../../src/client/lookup-tables.ts
 import { fetchAllMaybeAddressLookupTable } from "@solana-program/address-lookup-table";
 import { address, getCompiledTransactionMessageDecoder as getCompiledTransactionMessageDecoder2 } from "@solana/kit";
@@ -1079,124 +1081,165 @@ async function fetchLookupTablesForTransaction(rpc2, serializedTransaction) {
   return result;
 }
 
-// ../../src/client/relayer-yield-realizer.ts
-var RelayerRealizeError = class extends Error {
-  constructor(code, message, detail = null) {
+// ../../src/client/vault-flows.ts
+var VaultFlowClientError = class extends Error {
+  constructor(step, message, detail = null) {
     super(message);
-    this.code = code;
+    this.step = step;
     this.detail = detail;
-    this.name = "RelayerRealizeError";
+    this.name = "VaultFlowClientError";
   }
-  code;
+  step;
   detail;
 };
-var RelayerYieldRealizer = class {
-  config;
+var VaultFlowClient = class {
+  baseUrl;
   signer;
-  rpc;
   fetchImpl;
   lookupTablesFor;
+  pollTimeoutMs;
+  pollIntervalMs;
   constructor(config) {
-    this.config = {
-      facilitatorBaseUrl: config.facilitatorBaseUrl.replace(/\/$/, ""),
-      usdcMint: config.usdcMint ?? SUBLY_VAULT.usdcMint,
-      forceRealizeFullAmount: config.forceRealizeFullAmount ?? false
-    };
+    this.baseUrl = config.facilitatorBaseUrl.replace(/\/$/, "");
     this.signer = config.signer;
-    this.rpc = config.rpc;
     this.fetchImpl = config.fetchImpl ?? fetch;
-    this.lookupTablesFor = config.lookupTablesFor ?? ((serializedTransaction) => fetchLookupTablesForTransaction(this.rpc, serializedTransaction));
+    this.lookupTablesFor = config.lookupTablesFor ?? ((serializedTransaction) => fetchLookupTablesForTransaction(config.rpc, serializedTransaction));
+    this.pollTimeoutMs = config.pollTimeoutMs ?? 9e4;
+    this.pollIntervalMs = config.pollIntervalMs ?? 2500;
   }
-  async ensureUsdcAvailable(input) {
-    const agentAta = deriveAssociatedTokenAddress({
-      owner: this.signer.walletAddress,
-      mint: this.config.usdcMint
-    });
-    let shortfallRawUsdc;
-    if (this.config.forceRealizeFullAmount) {
-      shortfallRawUsdc = input.amountRawUsdc;
-    } else {
-      const currentBalance = await this.readTokenBalance(agentAta);
-      if (currentBalance >= input.amountRawUsdc) {
-        return { realizedRawUsdc: 0n, txSignature: null };
-      }
-      shortfallRawUsdc = input.amountRawUsdc - currentBalance;
-    }
-    await this.assertSpendableYield(shortfallRawUsdc);
-    const prepared = await this.postJson("/v1/withdrawals/prepare", {
+  /** Moves USDC from the agent wallet into the vault (fee sponsored). */
+  async deposit(input) {
+    const prepared = await this.postJson("prepare", "/v1/deposits/prepare", {
       wallet: this.signer.walletAddress,
-      amountRawUsdc: shortfallRawUsdc.toString()
+      amountRawUsdc: input.amountRawUsdc.toString()
+    });
+    const signed = await this.signer.signDeposit({
+      intent: prepared.signingIntent,
+      serializedTransaction: prepared.serializedTransaction,
+      lookupTables: await this.lookupTablesFor(prepared.serializedTransaction)
     });
+    let outcome = await this.postJson("submit", "/v1/deposits/submit", {
+      depositId: prepared.depositId,
+      serializedTransaction: signed.serializedTransaction,
+      agentSignature: signed.agentSignature
+    });
+    if (outcome.status === "submitted") {
+      outcome = await this.pollUntilTerminal(
+        `/v1/deposits/${prepared.depositId}`,
+        outcome
+      );
+    }
+    return {
+      depositId: prepared.depositId,
+      status: outcome.status,
+      txSignature: outcome.txSignature ?? null,
+      actualDepositRawUsdc: outcome.actualDepositRawUsdc ?? null,
+      sharesMintedRaw: outcome.sharesMintedRaw ?? null,
+      errorCode: outcome.errorCode ?? null
+    };
+  }
+  /**
+   * Moves USDC from the vault back to the agent wallet's USDC ATA (fee
+   * sponsored). A plain withdrawal is the exit path and MAY spend principal;
+   * with purpose "yield_realize" the relayer refuses anything beyond the
+   * spendable yield (the payment path, via RelayerYieldRealizer).
+   */
+  async withdraw(input) {
+    const prepared = await this.postJson(
+      "prepare",
+      "/v1/withdrawals/prepare",
+      {
+        wallet: this.signer.walletAddress,
+        amountRawUsdc: input.amountRawUsdc.toString(),
+        ...input.purpose === void 0 ? {} : { purpose: input.purpose }
+      }
+    );
     const signed = await this.signer.signWithdrawal({
       intent: prepared.signingIntent,
       serializedTransaction: prepared.serializedTransaction,
       lookupTables: await this.lookupTablesFor(prepared.serializedTransaction)
     });
-    let settled = await this.postJson("/v1/withdrawals/submit", {
+    let outcome = await this.postJson("submit", "/v1/withdrawals/submit", {
       withdrawalId: prepared.withdrawalId,
       serializedTransaction: signed.serializedTransaction,
       agentSignature: signed.agentSignature
     });
-    if (settled.status === "submitted") {
-      settled = await this.pollUntilSettled(prepared.withdrawalId);
-    }
-    if (settled.status !== "confirmed" || settled.txSignature === null) {
-      throw new RelayerRealizeError(
-        "realize_not_confirmed",
-        `yield realize withdrawal did not confirm (status=${settled.status})`,
-        settled
+    if (outcome.status === "submitted") {
+      outcome = await this.pollUntilTerminal(
+        `/v1/withdrawals/${prepared.withdrawalId}`,
+        outcome
       );
     }
     return {
-      realizedRawUsdc: BigInt(settled.actualWithdrawRawUsdc ?? "0"),
-      txSignature: settled.txSignature
+      withdrawalId: prepared.withdrawalId,
+      status: outcome.status,
+      txSignature: outcome.txSignature ?? null,
+      destinationUsdcAta: prepared.destinationUsdcAta,
+      actualWithdrawRawUsdc: outcome.actualWithdrawRawUsdc ?? null,
+      actualSharesBurnedRaw: outcome.actualSharesBurnedRaw ?? null,
+      errorCode: outcome.errorCode ?? null
     };
   }
-  /** Refuses to realize more than the ledger's spendable yield (principal). */
-  async assertSpendableYield(shortfallRawUsdc) {
-    const url2 = `${this.config.facilitatorBaseUrl}/v1/wallets/${this.signer.walletAddress}/budget`;
-    let response;
-    try {
-      response = await this.fetchImpl(url2, {
-        headers: await walletAuthHeaders({
-          signer: this.signer,
-          method: "GET",
-          url: url2
-        })
-      });
-    } catch (error) {
-      throw new RelayerRealizeError(
-        "budget_unavailable",
-        "could not read the spendable-yield budget",
-        error
-      );
+  /**
+   * Reads the yield budget. Syncs the relayer's ledger from chain first (so
+   * yield accrued since the last sync shows up); the sync is best-effort and
+   * on failure the last-synced view is returned.
+   */
+  async getBudget(options = {}) {
+    if (options.refreshFromChain !== false) {
+      try {
+        await this.postJson(
+          "sync",
+          `/v1/wallets/${this.signer.walletAddress}/sync`,
+          { source: "chain" }
+        );
+      } catch {
+      }
     }
+    const url2 = `${this.baseUrl}/v1/wallets/${this.signer.walletAddress}/budget`;
+    const response = await this.fetchImpl(url2, {
+      headers: await walletAuthHeaders({
+        signer: this.signer,
+        method: "GET",
+        url: url2
+      })
+    });
+    const text = await response.text();
     if (response.status !== 200) {
-      throw new RelayerRealizeError(
-        "budget_unavailable",
-        `budget endpoint returned ${response.status}`
+      throw new VaultFlowClientError(
+        "budget",
+        `budget endpoint returned ${response.status}: ${text}`
       );
     }
-    const body2 = await response.json();
-    const spendable = BigInt(body2.budget?.spendableYieldRawUsdc ?? "0");
-    if (spendable < shortfallRawUsdc) {
-      throw new RelayerRealizeError(
-        "insufficient_yield",
-        `spendable yield ${spendable} cannot cover ${shortfallRawUsdc} raw USDC; the principal is never spent \u2014 wait for more yield`,
-        { spendableYieldRawUsdc: spendable.toString() }
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      throw new VaultFlowClientError(
+        "budget",
+        "budget endpoint returned 200 with a non-JSON body",
+        text
       );
     }
+    const body2 = parsed;
+    return {
+      wallet: this.signer.walletAddress,
+      principalBasisRawUsdc: body2.position?.principalBasisRawUsdc ?? "0",
+      positionValueRawUsdc: body2.budget?.positionValueRawUsdc ?? "0",
+      grossYieldRawUsdc: body2.budget?.grossYieldRawUsdc ?? "0",
+      spendableYieldRawUsdc: body2.budget?.spendableYieldRawUsdc ?? "0"
+    };
   }
   /**
-   * Polls GET /v1/withdrawals/:id (which reconciles a submitted intent against
-   * the chain) until it leaves the "submitted" state or the timeout elapses.
+   * Polls the reconciling GET endpoint until the intent leaves "submitted"
+   * (each read looks the tx up on-chain) or the timeout elapses.
    */
-  async pollUntilSettled(withdrawalId, { timeoutMs = 9e4, intervalMs = 2500 } = {}) {
-    const deadline = Date.now() + timeoutMs;
-    let latest = null;
+  async pollUntilTerminal(path, last) {
+    const deadline = Date.now() + this.pollTimeoutMs;
+    let latest = last;
     while (Date.now() < deadline) {
-      await new Promise((resolve) => setTimeout(resolve, intervalMs));
-      const url2 = `${this.config.facilitatorBaseUrl}/v1/withdrawals/${withdrawalId}`;
+      await new Promise((resolve) => setTimeout(resolve, this.pollIntervalMs));
+      const url2 = `${this.baseUrl}${path}`;
       const response = await this.fetchImpl(url2, {
         headers: await walletAuthHeaders({
           signer: this.signer,
@@ -1207,19 +1250,19 @@ var RelayerYieldRealizer = class {
       if (response.status !== 200) {
         continue;
       }
-      latest = await response.json();
+      try {
+        latest = await response.json();
+      } catch {
+        continue;
+      }
       if (latest.status !== "submitted") {
         return latest;
       }
     }
-    return latest ?? {
-      status: "submitted",
-      txSignature: null,
-      actualWithdrawRawUsdc: null
-    };
+    return latest;
   }
-  async postJson(path, body2) {
-    const url2 = `${this.config.facilitatorBaseUrl}${path}`;
+  async postJson(step, path, body2) {
+    const url2 = `${this.baseUrl}${path}`;
     const serialized = JSON.stringify(body2);
     const response = await this.fetchImpl(url2, {
       method: "POST",
@@ -1236,22 +1279,133 @@ var RelayerYieldRealizer = class {
     });
     const text = await response.text();
     if (response.status !== 200) {
+      throw new VaultFlowClientError(
+        step,
+        `${path} failed with ${response.status}: ${text}`,
+        text
+      );
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new VaultFlowClientError(
+        step,
+        `${path} returned 200 with a non-JSON body`,
+        text
+      );
+    }
+  }
+};
+
+// ../../src/client/relayer-yield-realizer.ts
+var REALIZE_OVERHEAD_RAW_USDC = 2500n;
+var RelayerRealizeError = class extends Error {
+  constructor(code, message, detail = null) {
+    super(message);
+    this.code = code;
+    this.detail = detail;
+    this.name = "RelayerRealizeError";
+  }
+  code;
+  detail;
+};
+var RelayerYieldRealizer = class {
+  vaultFlows;
+  constructor(config) {
+    this.vaultFlows = new VaultFlowClient({
+      facilitatorBaseUrl: config.facilitatorBaseUrl,
+      signer: config.signer,
+      rpc: config.rpc,
+      ...config.fetchImpl === void 0 ? {} : { fetchImpl: config.fetchImpl },
+      ...config.lookupTablesFor === void 0 ? {} : { lookupTablesFor: config.lookupTablesFor }
+    });
+  }
+  async ensureUsdcAvailable(input) {
+    const shortfallRawUsdc = input.amountRawUsdc;
+    await this.assertSpendableYield(shortfallRawUsdc);
+    let outcome;
+    try {
+      outcome = await this.vaultFlows.withdraw({
+        amountRawUsdc: shortfallRawUsdc,
+        // The relayer refuses to prepare this withdrawal beyond the spendable
+        // yield — the principal-protection guard the client cannot bypass.
+        purpose: "yield_realize"
+      });
+    } catch (error) {
+      throw this.mapWithdrawError(error);
+    }
+    if (outcome.status !== "confirmed" || outcome.txSignature === null) {
       throw new RelayerRealizeError(
-        path.endsWith("/submit") ? "submit_failed" : "prepare_failed",
-        `${path} failed with ${response.status}: ${text}`
+        "realize_not_confirmed",
+        `yield realize withdrawal did not confirm (status=${outcome.status})`,
+        outcome
       );
     }
-    return JSON.parse(text);
+    return {
+      realizedRawUsdc: BigInt(outcome.actualWithdrawRawUsdc ?? "0"),
+      txSignature: outcome.txSignature
+    };
   }
-  async readTokenBalance(ata) {
+  /**
+   * Refuses to realize more than the ledger's spendable yield (principal).
+   * getBudget syncs the relayer's ledger from chain first (best-effort), so a
+   * long-running client sees yield as it accrues instead of a frozen view.
+   */
+  async assertSpendableYield(shortfallRawUsdc) {
+    let spendable;
     try {
-      const response = await this.rpc.getTokenAccountBalance(address2(ata), { commitment: "confirmed" }).send();
-      return BigInt(response.value.amount);
-    } catch {
-      return 0n;
+      const budget = await this.vaultFlows.getBudget();
+      spendable = BigInt(budget.spendableYieldRawUsdc);
+    } catch (error) {
+      throw new RelayerRealizeError(
+        "budget_unavailable",
+        "could not read the spendable-yield budget",
+        error
+      );
+    }
+    const requiredRawUsdc = shortfallRawUsdc + REALIZE_OVERHEAD_RAW_USDC;
+    if (spendable < requiredRawUsdc) {
+      throw new RelayerRealizeError(
+        "insufficient_yield",
+        `spendable yield ${spendable} cannot cover ${shortfallRawUsdc} raw USDC plus the ${REALIZE_OVERHEAD_RAW_USDC} raw fee headroom; the principal is never spent \u2014 wait for more yield`,
+        { spendableYieldRawUsdc: spendable.toString() }
+      );
+    }
+  }
+  mapWithdrawError(error) {
+    if (!(error instanceof VaultFlowClientError)) {
+      return new RelayerRealizeError(
+        "prepare_failed",
+        `yield realize failed: ${error instanceof Error ? error.message : String(error)}`,
+        error
+      );
+    }
+    const serverCode = errorCodeFrom(error.detail);
+    if (serverCode === "insufficient_yield" || serverCode === "post_state_principal_invariant_failed") {
+      return new RelayerRealizeError(
+        "insufficient_yield",
+        "the relayer refused to realize beyond the spendable yield; the principal is never spent \u2014 wait for more yield",
+        error.detail
+      );
     }
+    return new RelayerRealizeError(
+      error.step === "submit" ? "submit_failed" : "prepare_failed",
+      error.message,
+      error.detail
+    );
   }
 };
+function errorCodeFrom(detail) {
+  if (typeof detail !== "string") {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(detail);
+    return typeof parsed.error?.code === "string" ? parsed.error.code : null;
+  } catch {
+    return null;
+  }
+}
 
 // ../../src/x402/headers.ts
 import { z } from "zod";
@@ -1319,6 +1473,14 @@ function decodeX402Header(headerValue) {
     );
   }
 }
+function requestBodyHashFor(body2) {
+  if (body2 === null || body2 === void 0 || body2.length === 0) {
+    return EMPTY_BODY_HASH;
+  }
+  return sha256TaggedHex(
+    typeof body2 === "string" ? Buffer.from(body2, "utf8") : Buffer.from(body2)
+  );
+}
 
 // ../../src/x402/standard-requirements.ts
 import { z as z2 } from "zod";
@@ -1401,6 +1563,24 @@ function selectPayableSolanaRequirement(requirements, options) {
     feePayer: requirement.extra?.feePayer ?? null
   };
 }
+function standardRequirementMatchesSelected(candidate, selected) {
+  const parsed = standardExactRequirementSchema.safeParse(candidate);
+  return parsed.success && stableJson(parsed.data) === stableJson(selected.requirement);
+}
+function stableJson(value) {
+  return JSON.stringify(sortJson(value));
+}
+function sortJson(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortJson);
+  }
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).filter(([, entry]) => entry !== void 0).sort(([a], [b]) => a.localeCompare(b)).map(([key, entry]) => [key, sortJson(entry)])
+    );
+  }
+  return value;
+}
 
 // ../../src/client/standard-x402-payer.ts
 var StandardX402PayError = class extends Error {
@@ -1420,6 +1600,10 @@ var StandardX402Payer = class {
   defaultMaxAmountRawUsdc;
   network;
   usdcMint;
+  stateStore;
+  pending = /* @__PURE__ */ new Map();
+  inFlight = /* @__PURE__ */ new Map();
+  nowMs;
   constructor(config) {
     this.realizer = config.realizer;
     this.x402Fetch = config.x402Fetch;
@@ -1427,10 +1611,59 @@ var StandardX402Payer = class {
     this.defaultMaxAmountRawUsdc = config.defaultMaxAmountRawUsdc;
     this.network = config.network ?? SOLANA_MAINNET_NETWORK;
     this.usdcMint = config.usdcMint ?? SUBLY_VAULT.usdcMint;
+    this.stateStore = config.stateStore ?? null;
+    this.nowMs = config.nowMs ?? (() => Date.now());
+    if (this.stateStore !== null) {
+      for (const record of this.stateStore.load()) {
+        this.pending.set(record.key, record);
+      }
+    }
   }
-  async pay(input) {
+  pay(input) {
+    const method2 = (input.method ?? "GET").toUpperCase();
+    const requestBodyHash = requestBodyHashFor(input.body ?? null);
+    const pendingKey = pendingPaymentKey({
+      url: input.url,
+      method: method2,
+      requestBodyHash
+    });
+    const existingFlow = this.inFlight.get(pendingKey);
+    if (existingFlow !== void 0) {
+      return existingFlow;
+    }
+    const flow = this.run(input, {
+      method: method2,
+      requestBodyHash,
+      pendingKey
+    }).finally(() => {
+      this.inFlight.delete(pendingKey);
+    });
+    this.inFlight.set(pendingKey, flow);
+    return flow;
+  }
+  async run(input, computed) {
+    const { method: method2, requestBodyHash, pendingKey } = computed;
+    const existingPending = this.pending.get(pendingKey);
+    if (existingPending !== void 0 && input.forceNewPayment !== true) {
+      throw new StandardX402PayError(
+        "payment_outcome_unknown",
+        "a previous external x402 payment for this request has an unknown outcome. Verify whether it settled before purchasing again; to pay again anyway, call with forceNewPayment=true.",
+        existingPending
+      );
+    }
+    if (existingPending !== void 0 && input.forceNewPayment === true) {
+      try {
+        this.untrack(pendingKey);
+      } catch (error) {
+        throw new StandardX402PayError(
+          "state_persist_failed",
+          "could not clear the previous pending x402 marker before forcing a new payment",
+          error
+        );
+      }
+    }
     const init = {
-      method: input.method ?? "GET",
+      method: method2,
       ...input.body === void 0 ? {} : { body: input.body },
       ...input.headers === void 0 ? {} : { headers: input.headers }
     };
@@ -1459,15 +1692,55 @@ var StandardX402Payer = class {
         error
       );
     }
-    const response = await this.x402Fetch(input.url, init);
+    const pendingRecord = {
+      key: pendingKey,
+      url: input.url,
+      method: method2,
+      requestBodyHash,
+      amountRawUsdc: selected.amountRawUsdc.toString(),
+      payTo: selected.payTo,
+      feePayer: selected.feePayer,
+      realizedRawUsdc: realized.realizedRawUsdc.toString(),
+      realizeTxSignature: realized.txSignature,
+      status: "realized",
+      createdAtMs: this.nowMs(),
+      updatedAtMs: this.nowMs()
+    };
+    try {
+      this.track(pendingRecord);
+    } catch (error) {
+      throw new StandardX402PayError(
+        "state_persist_failed",
+        "could not persist the pending x402 marker; refusing to attempt the external payment because a restart would not be double-payment safe",
+        { error, pendingPayment: pendingRecord }
+      );
+    }
+    let response;
+    try {
+      response = await this.x402Fetch(input.url, init, selected);
+    } catch (error) {
+      const persistError = this.tryMarkUnknown(pendingKey, {
+        message: error instanceof Error ? error.message : String(error)
+      });
+      throw new StandardX402PayError(
+        "payment_outcome_unknown",
+        `the x402 payment attempt failed after yield was realized; verify whether it settled before paying again: ${error instanceof Error ? error.message : String(error)}`,
+        { error, persistError }
+      );
+    }
     const bodyText = await response.text();
     if (response.status !== 200) {
+      const persistError = this.tryMarkUnknown(pendingKey, {
+        status: response.status,
+        body: bodyText
+      });
       throw new StandardX402PayError(
-        "delivery_failed",
-        `the x402 payment did not deliver (status ${response.status})`,
-        { status: response.status, body: bodyText }
+        "payment_outcome_unknown",
+        `the x402 payment attempt returned ${response.status} after yield was realized; verify whether it settled before paying again`,
+        { status: response.status, body: bodyText, persistError }
       );
     }
+    this.clearDelivered(pendingKey);
     return {
       paid: true,
       status: response.status,
@@ -1513,25 +1786,153 @@ var StandardX402Payer = class {
       );
     }
   }
+  track(record) {
+    const previous = this.pending.get(record.key);
+    this.pending.set(record.key, record);
+    try {
+      this.persist();
+    } catch (error) {
+      if (previous === void 0) {
+        this.pending.delete(record.key);
+      } else {
+        this.pending.set(record.key, previous);
+      }
+      throw error;
+    }
+  }
+  markUnknown(key, detail) {
+    const current = this.pending.get(key);
+    if (current === void 0) {
+      return;
+    }
+    const next = {
+      ...current,
+      status: "external_outcome_unknown",
+      updatedAtMs: this.nowMs(),
+      detail
+    };
+    this.pending.set(key, next);
+    try {
+      this.persist();
+    } catch (error) {
+      this.pending.set(key, current);
+      throw error;
+    }
+  }
+  tryMarkUnknown(key, detail) {
+    try {
+      this.markUnknown(key, detail);
+      return null;
+    } catch (error) {
+      return error;
+    }
+  }
+  untrack(key) {
+    const previous = this.pending.get(key);
+    const existed = previous !== void 0;
+    this.pending.delete(key);
+    try {
+      this.persist();
+    } catch (error) {
+      if (existed) {
+        this.pending.set(key, previous);
+      }
+      throw error;
+    }
+  }
+  clearDelivered(key) {
+    const previous = this.pending.get(key);
+    this.pending.delete(key);
+    try {
+      this.persist();
+    } catch (error) {
+      if (previous !== void 0) {
+        this.pending.set(key, previous);
+      }
+      console.error(
+        `[subly-x402] payment delivered but pending marker could not be cleared: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  persist() {
+    if (this.stateStore === null) {
+      return;
+    }
+    this.stateStore.save([...this.pending.values()]);
+  }
 };
+function pendingPaymentKey(input) {
+  return `${input.method}:${input.url}:${input.requestBodyHash}`;
+}
 
 // ../../src/client/relayer-payer.ts
 function createRelayerX402Payer(config) {
   const realizer = new RelayerYieldRealizer({
     facilitatorBaseUrl: config.facilitatorBaseUrl,
     signer: config.signer,
-    rpc: config.rpc,
-    forceRealizeFullAmount: config.forceRealizeFullAmount ?? false
+    rpc: config.rpc
   });
   return new StandardX402Payer({
     realizer,
     x402Fetch: config.x402Fetch,
-    defaultMaxAmountRawUsdc: config.defaultMaxAmountRawUsdc
+    defaultMaxAmountRawUsdc: config.defaultMaxAmountRawUsdc,
+    ...config.stateStore === void 0 ? {} : { stateStore: config.stateStore }
   });
 }
 
+// ../../src/client/standard-x402-state-store.ts
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+function fileStandardX402StateStore(path) {
+  return {
+    load() {
+      let text;
+      try {
+        text = readFileSync(path, "utf8");
+      } catch (error) {
+        if (isMissingFileError(error)) {
+          return [];
+        }
+        throw error;
+      }
+      const parsed = JSON.parse(text);
+      if (!Array.isArray(parsed)) {
+        throw new Error(`pending payment state is not an array: ${path}`);
+      }
+      for (const [index, record] of parsed.entries()) {
+        if (!isPendingPaymentRecord(record)) {
+          throw new Error(
+            `pending payment state has an invalid record at index ${index}: ${path}`
+          );
+        }
+      }
+      return parsed;
+    },
+    save(records) {
+      const directory = dirname(path);
+      mkdirSync(directory, { recursive: true });
+      const tempPath = join(
+        directory,
+        `.${basename(path)}.${process.pid}.${Date.now()}.tmp`
+      );
+      writeFileSync(tempPath, JSON.stringify(records, null, 2));
+      renameSync(tempPath, path);
+    }
+  };
+}
+function isMissingFileError(error) {
+  return error !== null && typeof error === "object" && "code" in error && error.code === "ENOENT";
+}
+function isPendingPaymentRecord(value) {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  const record = value;
+  return typeof record.key === "string" && typeof record.url === "string" && typeof record.method === "string" && typeof record.requestBodyHash === "string" && typeof record.amountRawUsdc === "string" && typeof record.payTo === "string" && (record.feePayer === null || typeof record.feePayer === "string") && typeof record.realizedRawUsdc === "string" && (record.realizeTxSignature === null || typeof record.realizeTxSignature === "string") && (record.status === "realized" || record.status === "external_outcome_unknown") && typeof record.createdAtMs === "number" && typeof record.updatedAtMs === "number";
+}
+
 // ../../src/solana/keys.ts
-import { readFileSync } from "node:fs";
+import { readFileSync as readFileSync2 } from "node:fs";
 import bs586 from "bs58";
 import {
   createKeyPairSignerFromBytes
@@ -1546,7 +1947,7 @@ async function loadKeyPairSigner(params) {
     return createKeyPairSignerFromBytes(bytes);
   }
   if (jsonFilePath !== void 0 && jsonFilePath.length > 0) {
-    const raw = JSON.parse(readFileSync(jsonFilePath, "utf8"));
+    const raw = JSON.parse(readFileSync2(jsonFilePath, "utf8"));
     if (!Array.isArray(raw) || raw.length !== 64) {
       throw new Error(`${label} keypair file must be a 64-byte JSON array`);
     }
@@ -1564,7 +1965,7 @@ function loadSecretKeyBytes(params) {
     return bytes;
   }
   if (jsonFilePath !== void 0 && jsonFilePath.length > 0) {
-    const raw = JSON.parse(readFileSync(jsonFilePath, "utf8"));
+    const raw = JSON.parse(readFileSync2(jsonFilePath, "utf8"));
     if (!Array.isArray(raw) || raw.length !== 64) {
       throw new Error(`${label} keypair file must be a 64-byte JSON array`);
     }
@@ -1587,15 +1988,29 @@ async function createSvmX402Fetch(params) {
   const signer2 = toClientSvmSigner(
     await createKeyPairSignerFromBytes2(params.agentSecretKey)
   );
-  const wrapped = wrapFetchWithPaymentFromConfig(fetch, {
-    schemes: [
-      {
-        network: "solana:*",
-        client: new ExactSvmScheme(signer2, { rpcUrl: params.rpcUrl })
-      }
-    ]
-  });
-  return (url2, init) => wrapped(url2, init);
+  return (url2, init, expected) => {
+    const wrapped = wrapFetchWithPaymentFromConfig(fetch, {
+      schemes: [
+        {
+          network: expected.requirement.network,
+          client: new ExactSvmScheme(signer2, { rpcUrl: params.rpcUrl })
+        }
+      ],
+      paymentRequirementsSelector: (_x402Version, requirements) => selectExpectedRequirement(requirements, expected)
+    });
+    return wrapped(url2, init);
+  };
+}
+function selectExpectedRequirement(requirements, expected) {
+  const match = requirements.find(
+    (candidate) => standardRequirementMatchesSelected(candidate, expected)
+  );
+  if (match === void 0) {
+    throw new Error(
+      "x402 challenge changed after preflight; refusing to pay an unchecked requirement"
+    );
+  }
+  return match;
 }
 
 // src/pay.ts
@@ -1609,9 +2024,10 @@ if (url === void 0 || !/^https?:\/\//.test(url)) {
   fail("Usage: pay fetch <url> [maxAmountRawUsdc]");
 }
 var maxAmountArg = process.argv[3];
-var facilitatorBaseUrl = process.env.SUBLY_FACILITATOR_URL ?? "https://api.demo.sublyfi.com";
+var relayerBaseUrl = process.env.SUBLY_RELAYER_URL ?? process.env.SUBLY_FACILITATOR_URL ?? "https://api.demo.sublyfi.com";
 var rpcUrl = process.env.SOLANA_RPC_URL ?? "https://api.mainnet-beta.solana.com";
 var defaultMaxAmountRawUsdc = process.env.SUBLY_MCP_MAX_AMOUNT_RAW_USDC === void 0 ? 10000n : BigInt(process.env.SUBLY_MCP_MAX_AMOUNT_RAW_USDC);
+var pendingStatePath = process.env.SUBLY_MCP_STATE_PATH ?? join2(homedir(), ".subly", "standard-x402-pending.json");
 var keyPairSigner = await loadKeyPairSigner({
   base58Secret: process.env.SUBLY_DEMO_AGENT_KEYPAIR,
   jsonFilePath: process.env.SUBLY_DEMO_AGENT_KEYPAIR_PATH,
@@ -1625,17 +2041,18 @@ var agentSecretKey = loadSecretKeyBytes({
 var signer = new LocalKeypairAgentWalletSigner(keyPairSigner);
 var rpc = createRpc(rpcUrl);
 var payer = createRelayerX402Payer({
-  facilitatorBaseUrl,
+  facilitatorBaseUrl: relayerBaseUrl,
   signer,
   rpc,
   x402Fetch: await createSvmX402Fetch({ agentSecretKey, rpcUrl }),
-  defaultMaxAmountRawUsdc
+  defaultMaxAmountRawUsdc,
+  stateStore: fileStandardX402StateStore(pendingStatePath)
 });
 var method = process.env.SUBLY_PAY_METHOD;
 var body = process.env.SUBLY_PAY_BODY;
 console.error(`[pay] agent ${signer.walletAddress} -> ${url}`);
 try {
-  await ensureWalletOnboarded({ facilitatorBaseUrl, signer });
+  await ensureWalletOnboarded({ facilitatorBaseUrl: relayerBaseUrl, signer });
 } catch (error) {
   console.error(
     `[pay] onboarding skipped: ${error instanceof Error ? error.message : String(error)}`
@@ -1646,7 +2063,8 @@ try {
     url,
     ...method === void 0 ? {} : { method },
     ...body === void 0 ? {} : { body, headers: { "content-type": "application/json" } },
-    ...maxAmountArg === void 0 ? {} : { maxAmountRawUsdc: BigInt(maxAmountArg) }
+    ...maxAmountArg === void 0 ? {} : { maxAmountRawUsdc: BigInt(maxAmountArg) },
+    ...process.env.SUBLY_PAY_FORCE_NEW_PAYMENT === "1" ? { forceNewPayment: true } : {}
   });
   process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);