@routedock/routedock 0.3.1 → 0.4.0

package/dist/react.js

@@ -1,20 +1,17 @@
 import { createContext, useContext, useMemo, useEffect, useState, useRef, useCallback } from 'react';
 import { jsx } from 'react/jsx-runtime';
-import { Keypair, Horizon, Networks, rpc, xdr, Address, scValToNative, hash } from '@stellar/stellar-sdk';
+import { Keypair, Horizon, Networks, rpc, contract, nativeToScVal } from '@stellar/stellar-sdk';
+import { NulthPolicyError, usdcToStroops, stroopsToUsdc, createPolicyState, setNulthPaymentContext, paymentContextFromManifest, isNulthStellarSigner, createNulthSigner as createNulthSigner$1, NulthConfigError, nulthAuthorizeEntry } from '@routedock/nulth-sdk';
+import { sha256 as sha256$1 } from '@noble/hashes/sha2.js';
 import { Validator } from '@cfworker/json-schema';
-import { usdcToStroops, stroopsToUsdc } from '@routedock/nulth-sdk';
-import { createHash } from 'crypto';
-import { createEd25519Signer } from '@x402/stellar';
-import { ExactStellarScheme } from '@x402/stellar/exact/client';
+import { createEd25519Signer, ExactStellarScheme, getRpcUrl, getNetworkPassphrase, handleSimulationResult, isStellarNetwork, validateStellarDestinationAddress, validateStellarAssetAddress, getRpcClient, getEstimatedLedgerCloseTimeSeconds } from '@x402/stellar';
 import { x402Client, x402HTTPClient } from '@x402/core/client';
 import { decodePaymentRequiredHeader, decodePaymentResponseHeader } from '@x402/core/http';
 import { stellar } from '@stellar/mpp/charge/client';
 import { Mppx } from 'mppx/client';
+import { Challenge, Receipt } from 'mppx';
 import { STELLAR_PUBNET, STELLAR_TESTNET } from '@stellar/mpp';
 import { stellar as stellar$1 } from '@stellar/mpp/channel/client';
-import { Challenge } from 'mppx';
-import 'fs/promises';
-import 'path';
 
 // src/react/context.tsx
 var RouteDockContext = createContext(null);
@@ -121,6 +118,20 @@ var RouteDockPolicyRejectError = class extends RouteDockError {
     this.reason = reason;
   }
 };
+var RouteDockPaymentRejectedError = class extends RouteDockError {
+  status;
+  /** The provider's `reason` field, if its response body was JSON and had one. */
+  reason;
+  /** The provider's `error` field (short summary), if present. */
+  providerError;
+  constructor(message, status, details = {}, options = {}) {
+    super(message, "PAYMENT_REJECTED", false, options);
+    this.name = "RouteDockPaymentRejectedError";
+    this.status = status;
+    if (details.reason !== void 0) this.reason = details.reason;
+    if (details.providerError !== void 0) this.providerError = details.providerError;
+  }
+};
 var RouteDockChannelStateError = class extends RouteDockError {
   constructor(message, options = {}) {
     super(message, "CHANNEL_STATE", false, options);
@@ -157,6 +168,59 @@ function httpStatusToError(message, status, response) {
   }
   return new RouteDockNetworkError(message, opts);
 }
+var MAX_REJECTION_BODY_BYTES = 64 * 1024;
+var MAX_REJECTION_FIELD_CHARS = 500;
+async function readBoundedText(response, limit) {
+  const body = response.body;
+  if (!body) return null;
+  const reader = body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > limit) {
+        await reader.cancel().catch(() => void 0);
+        return null;
+      }
+      chunks.push(value);
+    }
+  } catch {
+    return null;
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(bytes);
+}
+async function paymentRejectedError(label, status, response) {
+  let reason;
+  let providerError;
+  try {
+    const text = await readBoundedText(response, MAX_REJECTION_BODY_BYTES);
+    const body = text === null ? null : JSON.parse(text);
+    if (body !== null && typeof body === "object") {
+      const { reason: r, error: e } = body;
+      if (typeof r === "string" && r.length > 0) reason = r.slice(0, MAX_REJECTION_FIELD_CHARS);
+      if (typeof e === "string" && e.length > 0) providerError = e.slice(0, MAX_REJECTION_FIELD_CHARS);
+    }
+  } catch {
+  }
+  const detail = reason ?? providerError;
+  return new RouteDockPaymentRejectedError(
+    `${label}: HTTP ${status}${detail ? ` \u2014 ${detail}` : ""}`,
+    status,
+    {
+      ...reason !== void 0 ? { reason } : {},
+      ...providerError !== void 0 ? { providerError } : {}
+    }
+  );
+}
 function wrapFetchError(err, context) {
   if (err instanceof RouteDockError) return err;
   return new RouteDockNetworkError(`${context}: ${String(err)}`, { cause: err });
@@ -218,7 +282,10 @@ async function withRetry(fn, policy = {}) {
       if (!err.retryable || attempt >= maxAttempts - 1) {
         throw err;
       }
-      const delay = err.retryAfterMs !== void 0 ? err.retryAfterMs : backoffDelayMs(attempt, baseDelayMs, maxDelayMs);
+      const delay = Math.min(
+        err.retryAfterMs ?? backoffDelayMs(attempt, baseDelayMs, maxDelayMs),
+        maxDelayMs
+      );
       if (onRetry) {
         try {
           await onRetry(attempt, err, delay);
@@ -231,10 +298,116 @@ async function withRetry(fn, policy = {}) {
   }
   throw lastError ?? new RouteDockError("Retry exhausted", "NETWORK", false);
 }
+
+// src/network.ts
 var USDC_ISSUERS = {
   testnet: "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
   mainnet: "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
 };
+var HORIZON_URLS = {
+  testnet: "https://horizon-testnet.stellar.org",
+  mainnet: "https://horizon.stellar.org"
+};
+
+// package.json
+var package_default = {
+  version: "0.4.0"};
+
+// src/internal/encoding.ts
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+function utf8ToBytes(text) {
+  return encoder.encode(text);
+}
+function bytesToUtf8(bytes) {
+  return decoder.decode(bytes);
+}
+function base64ToBytes(b64) {
+  const end = b64.indexOf("=");
+  let clean = (end === -1 ? b64 : b64.slice(0, end)).replace(/-/g, "+").replace(/_/g, "/").replace(/[^A-Za-z0-9+/]/g, "");
+  if (clean.length % 4 === 1) clean = clean.slice(0, -1);
+  const binary = atob(clean);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+function bytesToHex(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    out += bytes[i].toString(16).padStart(2, "0");
+  }
+  return out;
+}
+function sha256(data) {
+  return sha256$1(typeof data === "string" ? utf8ToBytes(data) : data);
+}
+
+// src/manifest/sign.ts
+var MANIFEST_SIGNATURE_VERSION = "2";
+function canonicalize(value) {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value).sort().map((key) => [key, canonicalize(value[key])])
+    );
+  }
+  return value;
+}
+function manifestDigest(manifest) {
+  const { signature: _omit, ...rest } = manifest;
+  const canonical = JSON.stringify(canonicalize(rest));
+  return sha256(utf8ToBytes(canonical));
+}
+function verifyManifestSignature(manifest, expectedPayee) {
+  if (!manifest.signature) {
+    throw new RouteDockSignatureError(
+      "Manifest is missing a signature field \u2014 cannot verify payee authenticity"
+    );
+  }
+  if (manifest.signature_version !== MANIFEST_SIGNATURE_VERSION) {
+    throw new RouteDockSignatureError(
+      `Manifest signature version must be ${MANIFEST_SIGNATURE_VERSION}; legacy signatures are not safe because nested fields were excluded from their digest`
+    );
+  }
+  if (expectedPayee !== void 0 && manifest.payee !== expectedPayee) {
+    throw new RouteDockSignatureError(
+      `Manifest payee ${manifest.payee} does not match expected payee ${expectedPayee}`
+    );
+  }
+  let keypair;
+  try {
+    keypair = Keypair.fromPublicKey(manifest.payee);
+  } catch (err) {
+    throw new RouteDockSignatureError(
+      `Manifest payee ${manifest.payee} is not a valid Stellar public key`,
+      { cause: err }
+    );
+  }
+  const digest = manifestDigest(manifest);
+  let sigBytes;
+  try {
+    sigBytes = base64ToBytes(manifest.signature);
+  } catch {
+    throw new RouteDockSignatureError("Manifest signature is not valid base64");
+  }
+  let valid = false;
+  try {
+    valid = keypair.verify(digest, sigBytes);
+  } catch {
+    throw new RouteDockSignatureError(
+      `Manifest signature verification failed for payee ${manifest.payee}`
+    );
+  }
+  if (!valid) {
+    throw new RouteDockSignatureError(
+      `Manifest signature verification failed for payee ${manifest.payee}`
+    );
+  }
+}
 
 // src/schemas/routedock.schema.json
 var routedock_schema_default = {
@@ -313,6 +486,7 @@ var routedock_schema_default = {
     },
     asset_contract: {
       type: "string",
+      pattern: "^C[A-Z2-7]{55}$",
       description: "Stellar Asset Contract (SAC) address for the payment asset"
     },
     assets: {
@@ -325,6 +499,7 @@ var routedock_schema_default = {
     },
     payee: {
       type: "string",
+      pattern: "^G[A-Z2-7]{55}$",
       description: "Stellar address (G...) that receives payments"
     },
     pricing: {
@@ -495,6 +670,7 @@ var routedock_schema_default = {
       properties: {
         amount: {
           type: "string",
+          pattern: "^[0-9]+(\\.[0-9]{1,7})?$",
           description: "Cost per request in the payment asset (decimal string, e.g. '0.001')"
         },
         per: {
@@ -508,6 +684,7 @@ var routedock_schema_default = {
         },
         payee: {
           type: "string",
+          pattern: "^G[A-Z2-7]{55}$",
           description: "Optional per-mode payee override (Stellar G... address). Directs settlements for this mode to a separate account for treasury separation. Falls back to the top-level 'payee' when omitted."
         }
       }
@@ -520,6 +697,7 @@ var routedock_schema_default = {
       properties: {
         rate: {
           type: "string",
+          pattern: "^[0-9]+(\\.[0-9]{1,7})?$",
           description: "Cost per voucher in the payment asset (decimal string, e.g. '0.0001')"
         },
         per: {
@@ -529,10 +707,12 @@ var routedock_schema_default = {
         },
         channel_factory: {
           type: "string",
+          pattern: "^C[A-Z2-7]{55}$",
           description: "Stable Soroban factory address (C...) used to deploy a per-session channel"
         },
         min_deposit: {
           type: "string",
+          pattern: "^[0-9]+(\\.[0-9]{1,7})?$",
           description: "Minimum initial deposit to open a channel (decimal string)"
         },
         refund_waiting_period_ledgers: {
@@ -630,68 +810,110 @@ var routedock_schema_default = {
   }
 };
 
-// package.json
-var package_default = {
-  version: "0.3.1"};
-var MANIFEST_SIGNATURE_VERSION = "2";
-function canonicalize(value) {
-  if (Array.isArray(value)) {
-    return value.map(canonicalize);
-  }
-  if (value !== null && typeof value === "object") {
-    return Object.fromEntries(
-      Object.keys(value).sort().map((key) => [key, canonicalize(value[key])])
-    );
+// src/manifest/validate.ts
+var validator = new Validator(routedock_schema_default, "7");
+function validateManifestSchema(manifest, source) {
+  const result = validator.validate(manifest);
+  if (!result.valid) {
+    const msgs = result.errors.map((err) => err.error).join("; ");
+    throw new RouteDockManifestError(`Invalid manifest${source ? ` at ${source}` : ""}: ${msgs}`);
   }
-  return value;
 }
-function manifestDigest(manifest) {
-  const { signature: _omit, ...rest } = manifest;
-  const canonical = JSON.stringify(canonicalize(rest));
-  return createHash("sha256").update(canonical, "utf8").digest();
-}
-function verifyManifestSignature(manifest, expectedPayee) {
-  if (!manifest.signature) {
-    throw new RouteDockSignatureError(
-      "Manifest is missing a signature field \u2014 cannot verify payee authenticity"
-    );
-  }
-  if (manifest.signature_version !== MANIFEST_SIGNATURE_VERSION) {
-    throw new RouteDockSignatureError(
-      `Manifest signature version must be ${MANIFEST_SIGNATURE_VERSION}; legacy signatures are not safe because nested fields were excluded from their digest`
-    );
+function assertManifestValid(manifest, baseUrl) {
+  const context = baseUrl ? ` at ${baseUrl}` : "";
+  if (manifest.latency_hints !== void 0) {
+    if (!Array.isArray(manifest.regions) || manifest.regions.length === 0) {
+      throw new RouteDockManifestError(
+        `Invalid manifest${context}: latency_hints defined without declaring regions`
+      );
+    }
+    const regionSet = new Set(manifest.regions);
+    for (const region of Object.keys(manifest.latency_hints)) {
+      if (!regionSet.has(region)) {
+        throw new RouteDockManifestError(
+          `Invalid manifest${context}: latency_hints key '${region}' is not declared in regions (${manifest.regions.join(", ")})`
+        );
+      }
+    }
   }
-  if (expectedPayee !== void 0 && manifest.payee !== expectedPayee) {
-    throw new RouteDockSignatureError(
-      `Manifest payee ${manifest.payee} does not match expected payee ${expectedPayee}`
-    );
+  if (manifest.assets !== void 0) {
+    if (!Array.isArray(manifest.assets) || manifest.assets.length === 0) {
+      throw new RouteDockManifestError(
+        `Invalid manifest${context}: assets must be a non-empty array when defined`
+      );
+    }
+    for (let i = 0; i < manifest.assets.length; i++) {
+      const a = manifest.assets[i];
+      if (!a || typeof a.asset !== "string" || typeof a.asset_contract !== "string") {
+        throw new RouteDockManifestError(
+          `Invalid manifest${context}: assets[${i}] must define asset and asset_contract strings`
+        );
+      }
+    }
+    const first = manifest.assets[0];
+    if (first.asset !== manifest.asset || first.asset_contract !== manifest.asset_contract) {
+      throw new RouteDockManifestError(
+        `Invalid manifest${context}: assets[0] (${first.asset}:${first.asset_contract}) must match root asset fields (${manifest.asset}:${manifest.asset_contract})`
+      );
+    }
   }
-  const keypair = Keypair.fromPublicKey(manifest.payee);
-  const digest = manifestDigest(manifest);
-  let sigBytes;
-  try {
-    sigBytes = Buffer.from(manifest.signature, "base64");
-  } catch {
-    throw new RouteDockSignatureError("Manifest signature is not valid base64");
+  assertPricingMatchesModes(manifest, context);
+  assertDeprecatedModesListed(manifest, context);
+  assertPricesParse(manifest, context);
+}
+function assertPricingMatchesModes(manifest, context) {
+  const pricing = manifest.pricing ?? {};
+  for (const mode of manifest.modes ?? []) {
+    if (pricing[mode] === void 0 || pricing[mode] === null) {
+      throw new RouteDockManifestError(
+        `Invalid manifest${context}: mode '${mode}' is listed in modes but pricing.${mode} is missing`
+      );
+    }
   }
-  let valid = false;
-  try {
-    valid = keypair.verify(digest, sigBytes);
-  } catch {
-    throw new RouteDockSignatureError(
-      `Manifest signature verification failed for payee ${manifest.payee}`
-    );
+}
+function assertDeprecatedModesListed(manifest, context) {
+  if (manifest.deprecated_modes === void 0) return;
+  const modes = new Set(manifest.modes ?? []);
+  for (const mode of manifest.deprecated_modes) {
+    if (!modes.has(mode)) {
+      throw new RouteDockManifestError(
+        `Invalid manifest${context}: deprecated_modes entry '${mode}' is not listed in modes`
+      );
+    }
   }
-  if (!valid) {
-    throw new RouteDockSignatureError(
-      `Manifest signature verification failed for payee ${manifest.payee}`
-    );
+}
+var PRICE_FIELDS = {
+  x402: ["amount"],
+  "mpp-charge": ["amount"],
+  "mpp-session": ["rate", "min_deposit"],
+  "mpp-session-ws": ["rate", "min_deposit"]
+};
+function assertPricesParse(manifest, context) {
+  const pricing = manifest.pricing ?? {};
+  for (const [mode, fields] of Object.entries(PRICE_FIELDS)) {
+    const entry = pricing[mode];
+    if (entry === void 0 || entry === null) continue;
+    for (const field of fields) {
+      const value = entry[field];
+      try {
+        if (typeof value !== "string") {
+          throw new RangeError(`expected a decimal string, got ${typeof value}`);
+        }
+        usdcToStroops(value);
+      } catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new RouteDockManifestError(
+          `Invalid manifest${context}: pricing.${mode}.${field} ${JSON.stringify(value)} is not a valid amount (${detail})`,
+          { cause: err }
+        );
+      }
+    }
   }
 }
 
 // src/client/ModeRouter.ts
-var validator = new Validator(routedock_schema_default, "7");
 var SDK_VERSION = package_default.version;
+var SUPPORTED_MANIFEST_MAJOR = 1;
 function parseMajorMinor(version) {
   const parts = version.split(".");
   return [Number.parseInt(parts[0] ?? "0", 10), Number.parseInt(parts[1] ?? "0", 10)];
@@ -709,6 +931,14 @@ function assertClientVersionSupported(manifest, baseUrl) {
     );
   }
 }
+function assertManifestVersionSupported(manifest, baseUrl) {
+  const [major] = parseMajorMinor(manifest.routedock);
+  if (major > SUPPORTED_MANIFEST_MAJOR) {
+    throw new RouteDockClientVersionError(
+      `Manifest version ${manifest.routedock} from provider at ${baseUrl} has schema major version ${major}, which is newer than the highest version this SDK supports (${SUPPORTED_MANIFEST_MAJOR}.x). Please upgrade the SDK.`
+    );
+  }
+}
 function assertManifestActive(manifest, baseUrl) {
   const sunsetAt = manifest.sunset_at;
   if (!sunsetAt) return;
@@ -724,11 +954,16 @@ function assertManifestActive(manifest, baseUrl) {
     );
   }
 }
-function assertEndpointActive(manifest, url, logger) {
+function assertEndpointActive(manifest, url, logger, method) {
   const pathname = new URL(url).pathname;
-  const matches = Object.entries(manifest.endpoints).filter(
+  const pathMatches = Object.entries(manifest.endpoints).filter(
     ([, descriptor]) => descriptor.path === pathname
   );
+  if (pathMatches.length === 0) return;
+  const requestedMethod = method?.toUpperCase();
+  const matches = requestedMethod ? pathMatches.filter(
+    ([, descriptor]) => descriptor.method.toUpperCase() === requestedMethod
+  ) : pathMatches;
   if (matches.length === 0) return;
   const now = Date.now();
   const allSunset = matches.every(([, descriptor]) => {
@@ -751,45 +986,6 @@ function assertEndpointActive(manifest, url, logger) {
     );
   }
 }
-function assertManifestValid(manifest, baseUrl) {
-  const context = baseUrl ? ` at ${baseUrl}` : "";
-  if (manifest.latency_hints !== void 0) {
-    if (!Array.isArray(manifest.regions) || manifest.regions.length === 0) {
-      throw new RouteDockManifestError(
-        `Invalid manifest${context}: latency_hints defined without declaring regions`
-      );
-    }
-    const regionSet = new Set(manifest.regions);
-    for (const region of Object.keys(manifest.latency_hints)) {
-      if (!regionSet.has(region)) {
-        throw new RouteDockManifestError(
-          `Invalid manifest${context}: latency_hints key '${region}' is not declared in regions (${manifest.regions.join(", ")})`
-        );
-      }
-    }
-  }
-  if (manifest.assets !== void 0) {
-    if (!Array.isArray(manifest.assets) || manifest.assets.length === 0) {
-      throw new RouteDockManifestError(
-        `Invalid manifest${context}: assets must be a non-empty array when defined`
-      );
-    }
-    for (let i = 0; i < manifest.assets.length; i++) {
-      const a = manifest.assets[i];
-      if (!a || typeof a.asset !== "string" || typeof a.asset_contract !== "string") {
-        throw new RouteDockManifestError(
-          `Invalid manifest${context}: assets[${i}] must define asset and asset_contract strings`
-        );
-      }
-    }
-    const first = manifest.assets[0];
-    if (first.asset !== manifest.asset || first.asset_contract !== manifest.asset_contract) {
-      throw new RouteDockManifestError(
-        `Invalid manifest${context}: assets[0] (${first.asset}:${first.asset_contract}) must match root asset fields (${manifest.asset}:${manifest.asset_contract})`
-      );
-    }
-  }
-}
 var CACHE_TTL_MS = 6e4;
 var DEFAULT_MANIFEST_CACHE_MAX_SIZE = 512;
 var DEFAULT_MANIFEST_TIMEOUT_MS = 5e3;
@@ -830,6 +1026,7 @@ var LruCache = class {
   }
 };
 var manifestCache = new LruCache(DEFAULT_MANIFEST_CACHE_MAX_SIZE);
+var inflightManifestFetches = /* @__PURE__ */ new Map();
 function invalidateManifest(baseUrl) {
   manifestCache.delete(baseUrl);
 }
@@ -859,10 +1056,27 @@ async function fetchManifest(baseUrl, retryPolicy, manifestTimeoutMs = DEFAULT_M
   if (cached && Date.now() < cached.expiresAt) {
     verifyManifestSignature(cached.manifest, expectedPayee);
     assertClientVersionSupported(cached.manifest, baseUrl);
+    assertManifestVersionSupported(cached.manifest, baseUrl);
     assertManifestValid(cached.manifest, baseUrl);
     assertManifestActive(cached.manifest, baseUrl);
     return cached.manifest;
   }
+  let inflight = inflightManifestFetches.get(baseUrl);
+  if (!inflight) {
+    inflight = fetchAndCacheManifest(baseUrl, retryPolicy, manifestTimeoutMs).finally(() => {
+      inflightManifestFetches.delete(baseUrl);
+    });
+    inflightManifestFetches.set(baseUrl, inflight);
+  }
+  const manifest = await inflight;
+  verifyManifestSignature(manifest, expectedPayee);
+  assertClientVersionSupported(manifest, baseUrl);
+  assertManifestVersionSupported(manifest, baseUrl);
+  assertManifestValid(manifest, baseUrl);
+  assertManifestActive(manifest, baseUrl);
+  return manifest;
+}
+async function fetchAndCacheManifest(baseUrl, retryPolicy, manifestTimeoutMs = DEFAULT_MANIFEST_TIMEOUT_MS) {
   const url = baseUrl.replace(/\/$/, "") + "/.well-known/routedock.json";
   return withRetry(async () => {
     let raw;
@@ -899,15 +1113,12 @@ async function fetchManifest(baseUrl, retryPolicy, manifestTimeoutMs = DEFAULT_M
     } catch (err) {
       throw new RouteDockManifestError(`Manifest at ${url} is not valid JSON`, { cause: err });
     }
-    const result = validator.validate(raw);
-    if (!result.valid) {
-      const msgs = result.errors.map((err) => err.error).join("; ");
-      throw new RouteDockManifestError(`Invalid manifest at ${url}: ${msgs}`);
-    }
+    validateManifestSchema(raw, url);
     const manifest = raw;
     assertManifestValid(manifest, baseUrl);
-    verifyManifestSignature(manifest, expectedPayee);
+    verifyManifestSignature(manifest);
     assertClientVersionSupported(manifest, baseUrl);
+    assertManifestVersionSupported(manifest, baseUrl);
     assertManifestActive(manifest, baseUrl);
     manifestCache.set(baseUrl, { manifest, fetchedAt: Date.now(), expiresAt });
     return manifest;
@@ -1006,6 +1217,48 @@ function selectMode(manifest, options = {}) {
   );
 }
 
+// src/internal/settleResult.ts
+function readSettleResult(result) {
+  const settle = result;
+  const failed = (reason) => reason ? { ok: false, reason } : { ok: false };
+  if (!settle || settle.success !== true) return failed(settle?.errorReason);
+  if (typeof settle.transaction !== "string" || settle.transaction.length === 0) {
+    return failed(settle.errorReason);
+  }
+  return { ok: true, txHash: settle.transaction };
+}
+
+// src/internal/request.ts
+var DEFAULT_METHOD = "GET";
+var BODYLESS_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD"]);
+function isReplayable(body) {
+  return typeof body === "string" || body instanceof ArrayBuffer || ArrayBuffer.isView(body) || typeof Blob !== "undefined" && body instanceof Blob || typeof FormData !== "undefined" && body instanceof FormData || typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams;
+}
+async function bufferBody(body) {
+  if (isReplayable(body)) return body;
+  return new Response(body).arrayBuffer();
+}
+async function prepareRequest(request) {
+  const method = (request?.method ?? DEFAULT_METHOD).toUpperCase();
+  const headers = new Headers(request?.headers);
+  const body = request?.body;
+  if (body === void 0 || BODYLESS_METHODS.has(method)) {
+    return { method, headers };
+  }
+  return { method, headers, body: await bufferBody(body) };
+}
+function toRequestInit(prepared, overrides) {
+  const headers = new Headers(prepared.headers);
+  if (overrides) {
+    new Headers(overrides).forEach((value, name) => headers.set(name, value));
+  }
+  const init = { method: prepared.method, headers };
+  if (prepared.body !== void 0) {
+    init.body = prepared.body;
+  }
+  return init;
+}
+
 // src/internal/payee.ts
 function resolvePayee(manifest, mode) {
   const override = manifest.pricing[mode]?.payee;
@@ -1066,6 +1319,102 @@ function checkChargeChallenge(request, manifest, network, maxAmount) {
   }
   return checkAmount(request["amount"], maxAmount);
 }
+var defaultIo = {
+  async expirationLedger(network, maxTimeoutSeconds) {
+    const { sequence } = await getRpcClient(network).getLatestLedger();
+    const secondsPerLedger = await getEstimatedLedgerCloseTimeSeconds(network);
+    return sequence + Math.ceil(maxTimeoutSeconds / secondsPerLedger);
+  },
+  async assemble({ asset, from, payTo, amount, networkPassphrase, rpcUrl }) {
+    return contract.AssembledTransaction.build({
+      contractId: asset,
+      method: "transfer",
+      // SEP-41: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0041.md#interface
+      args: [
+        nativeToScVal(from, { type: "address" }),
+        nativeToScVal(payTo, { type: "address" }),
+        nativeToScVal(amount, { type: "i128" })
+      ],
+      networkPassphrase,
+      rpcUrl,
+      parseResultXdr: (result) => result
+    });
+  }
+};
+var NulthStellarScheme = class {
+  constructor(signer, io = defaultIo) {
+    this.signer = signer;
+    this.io = io;
+  }
+  signer;
+  io;
+  scheme = "exact";
+  async createPaymentPayload(x402Version, paymentRequirements) {
+    try {
+      this.validateRequirements(paymentRequirements);
+    } catch (err) {
+      throw new Error(
+        `Invalid input parameters for creating Nulth Stellar payment, cause: ${String(err)}`
+      );
+    }
+    const from = this.signer.address;
+    const { network, payTo, asset, amount, maxTimeoutSeconds } = paymentRequirements;
+    if (!paymentRequirements.extra.areFeesSponsored) {
+      throw new Error("Nulth exact scheme requires areFeesSponsored to be true");
+    }
+    const maxLedger = await this.io.expirationLedger(network, maxTimeoutSeconds);
+    const tx = await this.io.assemble({
+      asset,
+      from,
+      payTo,
+      amount,
+      networkPassphrase: getNetworkPassphrase(network),
+      rpcUrl: getRpcUrl(network)
+    });
+    handleSimulationResult(tx.simulation);
+    const signers = tx.needsNonInvokerSigningBy();
+    if (!signers.includes(from) || signers.length > 1) {
+      throw new Error(`Expected to sign with [${from}], but got [${signers.join(", ")}]`);
+    }
+    await tx.signAuthEntries({
+      address: from,
+      signAuthEntry: this.signer.signAuthEntry,
+      expiration: maxLedger,
+      authorizeEntry: nulthAuthorizeEntry
+    });
+    await tx.simulate();
+    handleSimulationResult(tx.simulation);
+    const remaining = tx.needsNonInvokerSigningBy();
+    if (remaining.length > 0) {
+      throw new Error(`unexpected signer(s) required: [${remaining.join(", ")}]`);
+    }
+    if (!tx.built) {
+      throw new Error("Nulth payment transaction has no assembled envelope to send");
+    }
+    return { x402Version, payload: { transaction: tx.built.toXDR() } };
+  }
+  validateRequirements(requirements) {
+    const { scheme, network, payTo, asset, amount } = requirements;
+    if (typeof amount !== "string" || !Number.isInteger(Number(amount)) || Number(amount) <= 0) {
+      throw new Error(`Invalid amount: ${amount}. Amount must be a positive integer.`);
+    }
+    if (scheme !== this.scheme) {
+      throw new Error(`Unsupported scheme: ${scheme}`);
+    }
+    if (!isStellarNetwork(network)) {
+      throw new Error(`Unsupported Stellar network: ${network}`);
+    }
+    if (!validateStellarDestinationAddress(payTo)) {
+      throw new Error(`Invalid Stellar destination address: ${payTo}`);
+    }
+    if (!validateStellarAssetAddress(asset)) {
+      throw new Error(`Invalid Stellar asset address: ${asset}`);
+    }
+  }
+};
+function selectStellarScheme(signer) {
+  return isNulthStellarSigner(signer) ? new NulthStellarScheme(signer) : new ExactStellarScheme(signer);
+}
 
 // src/client/x402Client.ts
 var CAIP2 = {
@@ -1073,25 +1422,29 @@ var CAIP2 = {
   mainnet: "stellar:pubnet"
 };
 var X402Client = class _X402Client {
-  constructor(secretKeyOrSigner, network, retryPolicy) {
+  constructor(secretKeyOrSigner, network, retryPolicy, preSignHook, logger) {
     this.network = network;
     this.retryPolicy = retryPolicy;
+    this.preSignHook = preSignHook;
     const caip2 = CAIP2[network];
     this.signer = typeof secretKeyOrSigner === "string" ? createEd25519Signer(secretKeyOrSigner, caip2) : secretKeyOrSigner;
-    const scheme = new ExactStellarScheme(this.signer);
+    const scheme = selectStellarScheme(this.signer);
     const core = new x402Client();
     core.register(caip2, scheme);
     this.httpClient = new x402HTTPClient(core);
+    this.logger = logger;
   }
   network;
   retryPolicy;
+  preSignHook;
   httpClient;
   signer;
+  logger;
   /** Replace signer (e.g. swap to Nulth ZK account payer before pay) */
   withSigner(signer) {
-    return new _X402Client(signer, this.network, this.retryPolicy);
+    return new _X402Client(signer, this.network, this.retryPolicy, this.preSignHook, this.logger);
   }
-  async pay(url, manifest) {
+  async pay(url, manifest, request) {
     const pricing = manifest.pricing.x402;
     if (!pricing) {
       throw new RouteDockManifestError("manifest.pricing.x402 missing");
@@ -1100,13 +1453,15 @@ var X402Client = class _X402Client {
       throw new RouteDockManifestError("manifest.pricing.x402.facilitator missing");
     }
     const caip2 = CAIP2[this.network];
+    const prepared = await prepareRequest(request);
     const probe = await withRetry(async () => {
       let init2;
       try {
-        init2 = await fetch(url, { headers: { "X-Preferred-Mode": "x402" } });
+        init2 = await fetch(url, toRequestInit(prepared, { "X-Preferred-Mode": "x402" }));
       } catch (err) {
         throw wrapFetchError(err, "x402 initial request");
       }
+      this.logger?.("debug", "[x402] unpaid probe response", { status: init2.status });
       if (init2.status !== 402) {
         if (!init2.ok) {
           throw httpStatusToError(
@@ -1123,6 +1478,11 @@ var X402Client = class _X402Client {
             `Failed to parse JSON from non-402 response (HTTP ${init2.status})`
           );
         }
+        this.logger?.(
+          "debug",
+          "[x402] unpaid probe returned non-402 success \u2014 serving as free response",
+          { status: init2.status }
+        );
         return { kind: "free", data: data2 };
       }
       return { kind: "payment-required", init: init2 };
@@ -1151,6 +1511,18 @@ var X402Client = class _X402Client {
     if (allowed.length === 0) {
       throw checkX402Accept(firstAccept, manifest, caip2, pricing.amount);
     }
+    if (this.preSignHook) {
+      let decision;
+      try {
+        decision = await this.preSignHook({ url, manifest, accepts: allowed });
+      } catch (err) {
+        throw new RouteDockPolicyRejectError("pre_sign_hook_error", { cause: err });
+      }
+      if (!decision || decision.approve !== true) {
+        const reason = decision && decision.approve === false ? decision.reason : void 0;
+        throw new RouteDockPolicyRejectError(reason ?? "pre_sign_rejected");
+      }
+    }
     let paymentPayload;
     try {
       paymentPayload = await this.httpClient.createPaymentPayload({
@@ -1164,13 +1536,15 @@ var X402Client = class _X402Client {
     }
     const paymentHeaders = this.httpClient.encodePaymentSignatureHeader(paymentPayload);
     const signedAmount = stroopsToUsdc(BigInt(paymentPayload.accepted.amount));
+    this.logger?.("debug", "[x402] sending paid request with payment header");
     const settled = await withRetry(async () => {
       let response;
       try {
-        response = await fetch(url, { headers: paymentHeaders });
+        response = await fetch(url, toRequestInit(prepared, paymentHeaders));
       } catch (err) {
         throw wrapFetchError(err, "x402 settlement request");
       }
+      this.logger?.("debug", "[x402] paid request response", { status: response.status });
       if (!response.ok) {
         if (response.status >= 500 || response.status === 429 || response.status === 503) {
           throw httpStatusToError(
@@ -1179,17 +1553,28 @@ var X402Client = class _X402Client {
             response
           );
         }
-        throw new RouteDockManifestError(`x402 payment failed: HTTP ${response.status}`);
+        throw await paymentRejectedError("x402 payment failed", response.status, response);
       }
       return response;
     }, this.retryPolicy);
     let txHash = null;
     const responseHeader = settled.headers.get("X-Payment-Response");
-    if (responseHeader) {
+    if (!responseHeader) {
+      this.logger?.("debug", "[x402] settled 2xx carried no X-Payment-Response header");
+    } else {
       try {
-        const settleResponse = decodePaymentResponseHeader(responseHeader);
-        txHash = settleResponse.transaction ?? null;
-      } catch {
+        const outcome = readSettleResult(decodePaymentResponseHeader(responseHeader));
+        if (outcome.ok) {
+          txHash = outcome.txHash;
+        } else {
+          this.logger?.("debug", "[x402] X-Payment-Response reports an unsettled payment", {
+            ...outcome.reason !== void 0 ? { reason: outcome.reason } : {}
+          });
+        }
+      } catch (err) {
+        this.logger?.("debug", "[x402] X-Payment-Response header present but undecodable", {
+          error: err
+        });
       }
     }
     let data;
@@ -1210,13 +1595,13 @@ var MppChargeClient = class {
   keypair;
   network;
   retryPolicy;
-  async pay(url, manifest) {
+  async pay(url, manifest, request) {
     const pricing = manifest.pricing["mpp-charge"];
     if (!pricing) {
       throw new RouteDockManifestError("manifest.pricing.mpp-charge missing");
     }
     const caip2 = this.network === "mainnet" ? "stellar:pubnet" : "stellar:testnet";
-    let txHash = null;
+    const prepared = await prepareRequest(request);
     let signedAmount;
     let credential;
     const mppx = Mppx.create({
@@ -1224,19 +1609,14 @@ var MppChargeClient = class {
       methods: [
         stellar.charge({
           keypair: this.keypair,
-          mode: "pull",
-          onProgress(event) {
-            if (event.type === "paid") {
-              txHash = event.hash;
-            }
-          }
+          mode: "pull"
         })
       ],
       onChallenge: async (challenge, { createCredential }) => {
-        const request = challenge.request;
-        const rejection = checkChargeChallenge(request, manifest, caip2, pricing.amount);
+        const request2 = challenge.request;
+        const rejection = checkChargeChallenge(request2, manifest, caip2, pricing.amount);
         if (rejection) throw rejection;
-        const amount = request["amount"];
+        const amount = request2["amount"];
         if (typeof amount !== "string") {
           throw new RouteDockPolicyRejectError("challenge_amount_invalid");
         }
@@ -1248,7 +1628,7 @@ var MppChargeClient = class {
     return withRetry(async () => {
       let response;
       try {
-        response = credential ? await mppx.rawFetch(url, { headers: { Authorization: credential } }) : await mppx.fetch(url);
+        response = credential ? await mppx.rawFetch(url, toRequestInit(prepared, { Authorization: credential })) : await mppx.fetch(url, toRequestInit(prepared));
       } catch (err) {
         throw wrapMppError(err, "MPP charge request");
       }
@@ -1260,8 +1640,9 @@ var MppChargeClient = class {
             response
           );
         }
-        throw new RouteDockManifestError(`MPP charge failed: HTTP ${response.status}`);
+        throw await paymentRejectedError("MPP charge failed", response.status, response);
       }
+      const txHash = readSettlementHash(response);
       let data;
       try {
         data = await response.json();
@@ -1281,6 +1662,13 @@ var MppChargeClient = class {
     }, this.retryPolicy);
   }
 };
+function readSettlementHash(response) {
+  try {
+    return Receipt.fromResponse(response).reference;
+  } catch {
+    return null;
+  }
+}
 
 // src/types.ts
 var DEFAULT_MAX_SESSION_DURATION_MS = 36e5;
@@ -1288,6 +1676,31 @@ var DEFAULT_MAX_SESSION_DURATION_MS = 36e5;
 // src/client/MppSessionClient.ts
 var MIN_REFUND_WAITING_PERIOD = 17280;
 var STREAM_CLEANUP_TIMEOUT_MS = 3e3;
+var TX_CONFIRM_INTERVAL_MS = 1e3;
+var TX_CONFIRM_TIMEOUT_MS = 3e4;
+async function confirmTransaction(server, hash, label, timeoutMs = TX_CONFIRM_TIMEOUT_MS, intervalMs = TX_CONFIRM_INTERVAL_MS) {
+  const deadline = Date.now() + timeoutMs;
+  while (true) {
+    const txResponse = await server.getTransaction(hash);
+    const status = txResponse?.status;
+    if (status === "SUCCESS") {
+      return hash;
+    }
+    if (status === "FAILED") {
+      throw new RouteDockDisputeError(
+        `${label} transaction failed on-chain: status FAILED (resultXdr: ${txResponse.resultXdr.toXDR("base64")})`
+      );
+    }
+    if (Date.now() >= deadline) {
+      break;
+    }
+    const remaining = deadline - Date.now();
+    await new Promise((resolve) => setTimeout(resolve, Math.min(intervalMs, Math.max(1, remaining))));
+  }
+  throw new RouteDockDisputeError(
+    `${label} transaction confirmation timed out after ${timeoutMs}ms (hash: ${hash})`
+  );
+}
 var WS_CONNECTING = 0;
 var WS_OPEN = 1;
 function defaultWebSocketFactory(url, init, handlers) {
@@ -1301,9 +1714,9 @@ function defaultWebSocketFactory(url, init, handlers) {
     if (typeof data === "string") {
       handlers.onMessage(data);
     } else if (data instanceof ArrayBuffer) {
-      handlers.onMessage(Buffer.from(data).toString("utf8"));
+      handlers.onMessage(bytesToUtf8(new Uint8Array(data)));
     } else {
-      void data.arrayBuffer().then((buffer) => handlers.onMessage(Buffer.from(buffer).toString("utf8"))).catch(() => {
+      void data.arrayBuffer().then((buffer) => handlers.onMessage(bytesToUtf8(new Uint8Array(buffer)))).catch(() => {
       });
     }
   };
@@ -1456,7 +1869,7 @@ var MppSessionClient = class {
         throw err;
       }
     };
-    const streamWs = (u, m, createCredential, onSigned) => this.streamWebSocket(u, m, createCredential, onSigned);
+    const streamWs = (u, m, createCredential, onSigned, request) => this.streamWebSocket(u, m, createCredential, onSigned, request);
     const mppx = Mppx.create({
       polyfill: false,
       methods: [
@@ -1528,6 +1941,7 @@ var MppSessionClient = class {
         };
       },
       async *stream(options2) {
+        const prepared = await prepareRequest(options2?.request);
         const checkSpend = () => {
           if (!onSpend) return Promise.resolve();
           return onSpend(pricing.rate);
@@ -1537,7 +1951,13 @@ var MppSessionClient = class {
           const onSigned = () => {
             vouchersIssued++;
           };
-          for await (const item of streamWs(url, mppx, createGuardedCredential, onSigned)) {
+          for await (const item of streamWs(
+            url,
+            mppx,
+            createGuardedCredential,
+            onSigned,
+            prepared
+          )) {
             yield item;
           }
           return;
@@ -1552,7 +1972,10 @@ var MppSessionClient = class {
         const doFetch = () => withRetry(async () => {
           let resp;
           try {
-            resp = await mppx.fetch(url, { signal: abortController.signal });
+            resp = await mppx.fetch(url, {
+              ...toRequestInit(prepared),
+              signal: abortController.signal
+            });
           } catch (err) {
             if (abortController.signal.aborted) {
               throw err;
@@ -1637,10 +2060,10 @@ var MppSessionClient = class {
       async close() {
         clearSessionTimer();
         closed = true;
-        const { rpc: rpcMod, Contract, nativeToScVal, TransactionBuilder, BASE_FEE } = await import('@stellar/stellar-sdk');
+        const { rpc: rpcMod, Contract, nativeToScVal: nativeToScVal2, TransactionBuilder, BASE_FEE } = await import('@stellar/stellar-sdk');
         const rpcUrl = network === "testnet" ? "https://soroban-testnet.stellar.org" : "https://soroban.stellar.org";
         const server = new rpcMod.Server(rpcUrl);
-        const contract = new Contract(channelFactory);
+        const contract2 = new Contract(channelFactory);
         const passphrase = network === "mainnet" ? Networks.PUBLIC : Networks.TESTNET;
         const account = await withRetry(async () => {
           try {
@@ -1655,9 +2078,9 @@ var MppSessionClient = class {
               fee: BASE_FEE,
               networkPassphrase: passphrase
             }).addOperation(
-              contract.call(
+              contract2.call(
                 "prepare_commitment",
-                nativeToScVal(currentCumulative, { type: "i128" })
+                nativeToScVal2(currentCumulative, { type: "i128" })
               )
             ).setTimeout(30).build();
             return await server.simulateTransaction(simTx);
@@ -1676,7 +2099,7 @@ var MppSessionClient = class {
         }
         let signature;
         try {
-          signature = commitmentKey.sign(Buffer.from(commitmentBytes));
+          signature = commitmentKey.sign(commitmentBytes);
         } catch (err) {
           throw new RouteDockSignatureError("Channel close commitment signing failed", {
             cause: err
@@ -1690,7 +2113,7 @@ var MppSessionClient = class {
               headers: { "Content-Type": "application/json" },
               body: JSON.stringify({
                 amount: currentCumulative.toString(),
-                signature: Buffer.from(signature).toString("hex")
+                signature: bytesToHex(signature)
               })
             });
           } catch (err) {
@@ -1732,15 +2155,19 @@ var MppSessionClient = class {
           vouchersIssued
         };
       },
-      async requestRefund() {
+      /**
+       * Request refund from the channel contract (initiates dispute).
+       * Returns the transaction hash only after on-chain confirmation (SUCCESS).
+       */
+      async requestRefund(options2) {
         const { rpc: rpcMod, Contract, TransactionBuilder, BASE_FEE } = await import('@stellar/stellar-sdk');
         const rpcUrl = network === "testnet" ? "https://soroban-testnet.stellar.org" : "https://soroban.stellar.org";
         const server = new rpcMod.Server(rpcUrl);
-        const contract = new Contract(channelFactory);
+        const contract2 = new Contract(channelFactory);
         const passphrase = network === "mainnet" ? Networks.PUBLIC : Networks.TESTNET;
         try {
           const account = await server.getAccount(agentPublicKey);
-          const tx = new TransactionBuilder(account, { fee: BASE_FEE, networkPassphrase: passphrase }).addOperation(contract.call("request_refund")).setTimeout(30).build();
+          const tx = new TransactionBuilder(account, { fee: BASE_FEE, networkPassphrase: passphrase }).addOperation(contract2.call("request_refund")).setTimeout(30).build();
           const simResult = await server.simulateTransaction(tx);
           if (rpcMod.Api.isSimulationError(simResult)) {
             throw new RouteDockDisputeError(`request_refund simulation failed: ${simResult.error}`);
@@ -1752,37 +2179,50 @@ var MppSessionClient = class {
             const errDetail = result.errorResult ? JSON.stringify(result.errorResult) : "status ERROR";
             throw new RouteDockDisputeError(`Refund request transaction failed: ${errDetail}`);
           }
+          if (result.status === "TRY_AGAIN_LATER") {
+            throw new RouteDockDisputeError("Refund request transaction rejected with TRY_AGAIN_LATER: transaction not queued");
+          }
           if (!result.hash) {
             throw new RouteDockDisputeError("Refund request transaction not sent");
           }
-          return result.hash;
+          return await confirmTransaction(
+            server,
+            result.hash,
+            "Refund request",
+            options2?.timeoutMs,
+            options2?.intervalMs
+          );
         } catch (err) {
           if (err instanceof RouteDockDisputeError) throw err;
           throw new RouteDockDisputeError(`Failed to request refund: ${err instanceof Error ? err.message : String(err)}`);
         }
       },
-      async settleWithLatestVoucher() {
-        const { rpc: rpcMod, Contract, nativeToScVal, TransactionBuilder, BASE_FEE } = await import('@stellar/stellar-sdk');
+      /**
+       * Server-side counter-mechanism to settle with latest voucher before refund window expires.
+       * Returns the transaction hash only after on-chain confirmation (SUCCESS).
+       */
+      async settleWithLatestVoucher(options2) {
+        const { rpc: rpcMod, Contract, nativeToScVal: nativeToScVal2, TransactionBuilder, BASE_FEE } = await import('@stellar/stellar-sdk');
         const rpcUrl = network === "testnet" ? "https://soroban-testnet.stellar.org" : "https://soroban.stellar.org";
         const server = new rpcMod.Server(rpcUrl);
-        const contract = new Contract(channelFactory);
+        const contract2 = new Contract(channelFactory);
         const passphrase = network === "mainnet" ? Networks.PUBLIC : Networks.TESTNET;
         try {
           const account = await server.getAccount(agentPublicKey);
-          const simTx = new TransactionBuilder(account, { fee: BASE_FEE, networkPassphrase: passphrase }).addOperation(contract.call("prepare_commitment", nativeToScVal(currentCumulative, { type: "i128" }))).setTimeout(30).build();
+          const simTx = new TransactionBuilder(account, { fee: BASE_FEE, networkPassphrase: passphrase }).addOperation(contract2.call("prepare_commitment", nativeToScVal2(currentCumulative, { type: "i128" }))).setTimeout(30).build();
           const simResult = await server.simulateTransaction(simTx);
           if (rpcMod.Api.isSimulationError(simResult)) {
             throw new RouteDockDisputeError(`prepare_commitment simulation failed: ${simResult.error}`);
           }
           const commitmentBytes = simResult.result?.retval?.bytes();
           if (!commitmentBytes) throw new RouteDockDisputeError("prepare_commitment returned no bytes");
-          const signature = commitmentKey.sign(Buffer.from(commitmentBytes));
+          const signature = commitmentKey.sign(commitmentBytes);
           const settleAccount = await server.getAccount(agentPublicKey);
           const settleTx = new TransactionBuilder(settleAccount, { fee: BASE_FEE, networkPassphrase: passphrase }).addOperation(
-            contract.call(
+            contract2.call(
               "settle_with_signature",
-              nativeToScVal(currentCumulative, { type: "i128" }),
-              nativeToScVal(Buffer.from(signature))
+              nativeToScVal2(currentCumulative, { type: "i128" }),
+              nativeToScVal2(signature)
             )
           ).setTimeout(30).build();
           const preparedSettleTx = await server.prepareTransaction(settleTx);
@@ -1792,10 +2232,19 @@ var MppSessionClient = class {
             const errDetail = settleResult.errorResult ? JSON.stringify(settleResult.errorResult) : "status ERROR";
             throw new RouteDockDisputeError(`Settlement transaction failed: ${errDetail}`);
           }
+          if (settleResult.status === "TRY_AGAIN_LATER") {
+            throw new RouteDockDisputeError("Settlement transaction rejected with TRY_AGAIN_LATER: transaction not queued");
+          }
           if (!settleResult.hash) {
             throw new RouteDockDisputeError("Settlement transaction not sent");
           }
-          return settleResult.hash;
+          return await confirmTransaction(
+            server,
+            settleResult.hash,
+            "Settlement",
+            options2?.timeoutMs,
+            options2?.intervalMs
+          );
         } catch (err) {
           if (err instanceof RouteDockDisputeError) throw err;
           throw new RouteDockDisputeError(`Failed to settle with latest voucher: ${err instanceof Error ? err.message : String(err)}`);
@@ -1805,11 +2254,11 @@ var MppSessionClient = class {
         const { rpc: rpcMod, Contract, TransactionBuilder, BASE_FEE } = await import('@stellar/stellar-sdk');
         const rpcUrl = network === "testnet" ? "https://soroban-testnet.stellar.org" : "https://soroban.stellar.org";
         const server = new rpcMod.Server(rpcUrl);
-        const contract = new Contract(channelFactory);
+        const contract2 = new Contract(channelFactory);
         const passphrase = network === "mainnet" ? Networks.PUBLIC : Networks.TESTNET;
         try {
           const account = await server.getAccount(agentPublicKey);
-          const tx = new TransactionBuilder(account, { fee: BASE_FEE, networkPassphrase: passphrase }).addOperation(contract.call("get_channel_state")).setTimeout(30).build();
+          const tx = new TransactionBuilder(account, { fee: BASE_FEE, networkPassphrase: passphrase }).addOperation(contract2.call("get_channel_state")).setTimeout(30).build();
           const simResult = await server.simulateTransaction(tx);
           if (rpcMod.Api.isSimulationError(simResult)) {
             throw new RouteDockChannelStateError(`Failed to query channel state: ${simResult.error}`);
@@ -1875,11 +2324,11 @@ var MppSessionClient = class {
    * close code (1000/1001); abnormal closes and connection failures surface as
    * RouteDockChannelStateError.
    */
-  async *streamWebSocket(url, mppx, createCredential, onSigned) {
-    const request = { method: "GET" };
+  async *streamWebSocket(url, mppx, createCredential, onSigned, request) {
+    const probeInit = toRequestInit(request);
     let probe;
     try {
-      probe = await mppx.rawFetch(url, request);
+      probe = await mppx.rawFetch(url, probeInit);
     } catch (err) {
       throw wrapFetchError(err, "Voucher request");
     }
@@ -1983,230 +2432,19 @@ var MppSessionClient = class {
     }
   }
 };
-var NulthPolicyError = class extends Error {
-  code;
-  constructor(code, message) {
-    super(message);
-    this.name = "NulthPolicyError";
-    this.code = code;
-  }
-};
-function sha256Hex(data) {
-  const buf = typeof data === "string" ? Buffer.from(data, "utf8") : data;
-  return createHash("sha256").update(buf).digest("hex");
-}
-function commitDailyCap(dailyCapStroops, witnessSecret) {
-  return sha256Hex(`${witnessSecret}:cap:${dailyCapStroops.toString()}`);
-}
-function commitAllowlist(payees, witnessSecret) {
-  const sorted = [...payees].sort().join(",");
-  return sha256Hex(`${witnessSecret}:allowlist:${sorted}`);
-}
-function hashPayee(payee) {
-  return sha256Hex(`payee:${payee}`);
-}
-function dayBucketFromLedger(ledgerSequence) {
-  return Math.floor(ledgerSequence / 17280);
-}
-function authDigestFromEntry(authEntryBase64) {
-  const entryHash = hash(Buffer.from(authEntryBase64, "base64"));
-  return sha256Hex(entryHash);
-}
-function assertAuthEntryMatchesContext(authEntry, from, ctx) {
-  let preimage;
+function createNulthSigner(config) {
+  const sharedConfig = { ...config, logger: resolveLogger(config.logger) };
+  Object.defineProperty(sharedConfig, "paymentContext", {
+    get: () => config.paymentContext
+  });
   try {
-    preimage = xdr.HashIdPreimage.fromXDR(authEntry, "base64");
-  } catch {
-    throw new NulthPolicyError("auth_entry_mismatch", "authEntry does not decode as a HashIdPreimage");
-  }
-  if (preimage.switch() !== xdr.EnvelopeType.envelopeTypeSorobanAuthorization()) {
-    throw new NulthPolicyError(
-      "auth_entry_mismatch",
-      "authEntry is not a Soroban authorization preimage"
-    );
-  }
-  const inv = preimage.sorobanAuthorization().invocation();
-  if (inv.subInvocations().length !== 0) {
-    throw new NulthPolicyError("auth_entry_mismatch", "authEntry has unexpected sub-invocations");
-  }
-  if (inv.function().switch() !== xdr.SorobanAuthorizedFunctionType.sorobanAuthorizedFunctionTypeContractFn()) {
-    throw new NulthPolicyError("auth_entry_mismatch", "authEntry does not invoke a contract function");
-  }
-  const fn = inv.function().contractFn();
-  const contractAddress = Address.fromScAddress(fn.contractAddress()).toString();
-  if (contractAddress !== ctx.assetContract) {
-    throw new NulthPolicyError(
-      "auth_entry_mismatch",
-      `authEntry contract ${contractAddress} does not match assetContract ${ctx.assetContract}`
-    );
-  }
-  const functionName = fn.functionName().toString();
-  if (functionName !== "transfer") {
-    throw new NulthPolicyError(
-      "auth_entry_mismatch",
-      `authEntry function ${functionName} does not match expected transfer`
-    );
-  }
-  const args = fn.args();
-  if (args.length !== 3) {
-    throw new NulthPolicyError("auth_entry_mismatch", `authEntry transfer has ${args.length} args, expected 3`);
-  }
-  const entryFrom = scValToNative(args[0]);
-  if (entryFrom !== from) {
-    throw new NulthPolicyError(
-      "auth_entry_mismatch",
-      `authEntry from ${entryFrom} does not match nulthAccount ${from}`
-    );
-  }
-  const entryTo = scValToNative(args[1]);
-  if (entryTo !== ctx.payee) {
-    throw new NulthPolicyError(
-      "auth_entry_mismatch",
-      `authEntry to ${entryTo} does not match paymentContext.payee ${ctx.payee}`
-    );
-  }
-  const entryAmount = scValToNative(args[2]);
-  if (entryAmount !== ctx.amountStroops) {
-    throw new NulthPolicyError(
-      "auth_entry_mismatch",
-      `authEntry amount ${entryAmount} does not match paymentContext.amountStroops ${ctx.amountStroops}`
-    );
-  }
-}
-function insecureMockProof(preimage) {
-  return createHash("sha512").update(`nulth:${preimage}`).digest("base64");
-}
-function encodeAuthSignature(proof) {
-  const payload = { nulth: "zk-v1", proof };
-  return Buffer.from(JSON.stringify(payload), "utf8").toString("base64");
-}
-var NulthClient = class {
-  constructor(config) {
-    this.config = config;
-    this.policy = { ...config.policy };
-    this.prover = config.prover ?? "mock";
-    if (this.prover !== "mock") {
-      throw new RouteDockManifestError(
-        `NulthClient: unknown prover backend ${String(config.prover)}; only 'mock' is implemented`
-      );
-    }
-    if (config.network !== "testnet") {
-      throw new RouteDockManifestError(
-        `NulthClient cannot use the insecure mock prover on mainnet; a production prover is required (network must be 'testnet', got ${String(config.network)})`
-      );
-    }
-    resolveLogger(config.logger)(
-      "warn",
-      "NulthClient is using the insecure mock prover; proofs are not cryptographically sound"
-    );
-  }
-  config;
-  policy;
-  prover;
-  get proverBackend() {
-    return this.prover;
-  }
-  get nulthAccount() {
-    return this.config.nulthAccount;
-  }
-  get allowlistCommitment() {
-    return this.policy.allowlistCommitment;
-  }
-  get capCommitment() {
-    return commitDailyCap(this.policy.dailyCapStroops, this.policy.witnessSecret);
-  }
-  buildPaymentAuthProof(context) {
-    this.enforcePolicy(context);
-    const bucket = dayBucketFromLedger(context.ledgerSequence);
-    if (bucket !== this.policy.dayBucket) {
-      this.policy.dayBucket = bucket;
-      this.policy.dailySpendStroops = 0n;
-    }
-    const authDigest = authDigestFromEntry(context.authEntry);
-    const capCommitment = this.capCommitment;
-    const payeeHash = hashPayee(context.payee);
-    const preimage = [
-      authDigest,
-      this.policy.allowlistCommitment,
-      capCommitment,
-      payeeHash,
-      context.amountStroops.toString(),
-      bucket.toString(),
-      this.config.nulthAccount
-    ].join("|");
-    const proof = {
-      version: 1,
-      proof: insecureMockProof(preimage),
-      publicInputs: {
-        authDigest,
-        allowlistCommitment: this.policy.allowlistCommitment,
-        capCommitment,
-        payeeHash,
-        amountStroops: context.amountStroops.toString(),
-        dayBucket: bucket.toString()
-      }
-    };
-    this.policy.dailySpendStroops += context.amountStroops;
-    return proof;
-  }
-  enforcePolicy(context) {
-    if (context.amountStroops < 0n) {
-      throw new RangeError(`Invalid amountStroops: ${context.amountStroops}`);
-    }
-    if (!Number.isSafeInteger(context.ledgerSequence) || context.ledgerSequence < 0) {
-      throw new RangeError(`Invalid ledgerSequence: ${context.ledgerSequence}`);
-    }
-    if (this.policy.expiryLedger !== void 0 && context.ledgerSequence > this.policy.expiryLedger) {
-      throw new NulthPolicyError("session_expired", "Nulth session expired");
-    }
-    if (!this.policy.allowedPayees.includes(context.payee)) {
-      throw new NulthPolicyError("payee_not_allowed", `Payee ${context.payee} not in off-chain allowlist`);
-    }
-    const bucket = dayBucketFromLedger(context.ledgerSequence);
-    const spend = bucket === this.policy.dayBucket ? this.policy.dailySpendStroops : 0n;
-    if (spend + context.amountStroops > this.policy.dailyCapStroops) {
-      throw new NulthPolicyError("daily_cap_exceeded", "Nulth daily cap exceeded");
+    return createNulthSigner$1(sharedConfig);
+  } catch (error) {
+    if (error instanceof NulthConfigError) {
+      throw new RouteDockManifestError(error.message, { cause: error });
     }
+    throw error;
   }
-};
-function createNulthSigner(config) {
-  const client = new NulthClient(config);
-  const nulthAccount = config.nulthAccount;
-  return {
-    address: nulthAccount,
-    signAuthEntry: async (authEntry) => {
-      const ctx = config.paymentContext;
-      if (!ctx) throw new Error("Nulth paymentContext must be set before signing");
-      assertAuthEntryMatchesContext(authEntry, nulthAccount, ctx);
-      const proof = client.buildPaymentAuthProof({ authEntry, ...ctx });
-      return { signedAuthEntry: encodeAuthSignature(proof), signerAddress: nulthAccount };
-    }
-  };
-}
-function setNulthPaymentContext(config, context) {
-  config.paymentContext = context;
-}
-function paymentContextFromManifest(manifest, mode, ledgerSequence) {
-  const pricing = manifest.pricing[mode];
-  if (!pricing) throw new Error(`manifest.pricing.${mode} missing`);
-  return {
-    payee: pricing.payee ?? manifest.payee,
-    amountStroops: usdcToStroops(pricing.amount),
-    assetContract: manifest.asset_contract,
-    ledgerSequence
-  };
-}
-function createPolicyState(input) {
-  const dailyCapStroops = usdcToStroops(input.dailyCapUsdc);
-  return {
-    dailyCapStroops,
-    allowlistCommitment: commitAllowlist(input.allowedPayees, input.witnessSecret),
-    allowedPayees: input.allowedPayees,
-    dailySpendStroops: 0n,
-    dayBucket: dayBucketFromLedger(input.ledgerSequence ?? 0),
-    witnessSecret: input.witnessSecret,
-    ...input.expiryLedger !== void 0 ? { expiryLedger: input.expiryLedger } : {}
-  };
 }
 function assertNulthVaultManifest(manifest, nulthAccount) {
   if (manifest.vault !== void 0 && manifest.vault !== "nulth") {
@@ -2431,7 +2669,7 @@ var RouteDockClient = class _RouteDockClient {
     }
     const secretKey = this.keypair.secret();
     const retryPolicy = this.logger ? { ...this.retryPolicy, logger: this.logger } : this.retryPolicy;
-    this.x402 = new X402Client(secretKey, this.network, retryPolicy);
+    this.x402 = new X402Client(secretKey, this.network, retryPolicy, config.preSignHook, this.logger);
     this.charge = new MppChargeClient(this.keypair, this.network, retryPolicy);
     this.session = new MppSessionClient(this.keypair, this.network, retryPolicy, void 0, this.logger);
   }
@@ -2439,7 +2677,7 @@ var RouteDockClient = class _RouteDockClient {
   async _resolveManifest(url, options) {
     const baseUrl = new URL(url).origin;
     const manifest = await fetchManifest(baseUrl, this.retryPolicy, this.manifestTimeoutMs, this.expectedPayee);
-    assertEndpointActive(manifest, url, this.logger);
+    assertEndpointActive(manifest, url, this.logger, options?.request?.method);
     const mode = selectMode(manifest, options);
     return { manifest, mode };
   }
@@ -2456,13 +2694,9 @@ var RouteDockClient = class _RouteDockClient {
     });
     return next;
   }
-  /**
-   * Check that the payer has a trustline for the payment asset and surface
-   * manifest metadata (regions, latency hints, capabilities). Safe to
-   * call before committing to a payment — for approval gates and manual
-   * trustline remediation.
-   */
-  async preflight(manifest, mode, endpoint) {
+  async preflight(target, mode, endpoint) {
+    if (typeof target === "string") return this._preflightUrl(target);
+    const manifest = target;
     assertManifestValid(manifest);
     const selectedAsset = mode ? selectAsset(manifest, mode, endpoint).asset : manifest.asset;
     await this._checkTrustline(manifest, selectedAsset);
@@ -2475,6 +2709,42 @@ var RouteDockClient = class _RouteDockClient {
       ...manifest.capabilities && { capabilities: manifest.capabilities }
     };
   }
+  /** Manifest-only preflight for a URL — no trustline check, no payment. */
+  async _preflightUrl(url) {
+    const baseUrl = new URL(url).origin;
+    const manifest = await fetchManifest(baseUrl, this.retryPolicy, this.manifestTimeoutMs, this.expectedPayee);
+    assertEndpointActive(manifest, url);
+    const costs = manifest.modes.map((mode) => {
+      const asset = selectAsset(manifest, mode, url).asset;
+      switch (mode) {
+        case "x402":
+        case "mpp-charge": {
+          const pricing = manifest.pricing[mode];
+          return { mode, amount: pricing.amount, per: "request", asset };
+        }
+        case "mpp-session":
+        case "mpp-session-ws": {
+          const pricing = manifest.pricing[mode];
+          return { mode, amount: pricing.rate, per: "voucher", asset, min_deposit: pricing.min_deposit };
+        }
+        default:
+          throw new RouteDockManifestError(`Unknown payment mode: ${mode}`);
+      }
+    });
+    const pathname = new URL(url).pathname;
+    const matches = Object.values(manifest.endpoints).filter((descriptor) => descriptor.path === pathname);
+    const endpointSunsets = matches.map((descriptor) => descriptor.sunset_at).filter((value) => typeof value === "string").sort((a, b) => Date.parse(a) - Date.parse(b));
+    return {
+      modes: manifest.modes,
+      costs,
+      compliance: {
+        deprecated_modes: manifest.deprecated_modes ?? [],
+        ...manifest.sunset_at && { sunset_at: manifest.sunset_at },
+        endpoint_deprecated: matches.some((descriptor) => descriptor.deprecated === true),
+        ...endpointSunsets[0] && { endpoint_sunset_at: endpointSunsets[0] }
+      }
+    };
+  }
   /**
    * Verify via Horizon that the payer account has a trustline for the
    * payment asset declared in the manifest. Throws RouteDockTrustlineError
@@ -2486,8 +2756,7 @@ var RouteDockClient = class _RouteDockClient {
     const cacheKey = `${this.network}:${this.keypair.publicKey()}:${targetAsset}`;
     const cached = _RouteDockClient._trustlineCache.get(cacheKey);
     if (cached && Date.now() < cached.expiresAt) return;
-    const horizonUrl = this.network === "testnet" ? "https://horizon-testnet.stellar.org" : "https://horizon.stellar.org";
-    const server = new Horizon.Server(horizonUrl);
+    const server = new Horizon.Server(HORIZON_URLS[this.network]);
     try {
       const account = await server.loadAccount(this.keypair.publicKey());
       const balances = account.balances;
@@ -2523,9 +2792,11 @@ var RouteDockClient = class _RouteDockClient {
   async pay(url, options) {
     const baseUrl = new URL(url).origin;
     const manifest = await fetchManifest(baseUrl, this.retryPolicy, this.manifestTimeoutMs, this.expectedPayee);
-    assertEndpointActive(manifest, url, this.logger);
+    const request = options?.request;
+    assertEndpointActive(manifest, url, this.logger, request?.method);
     const mode = selectMode(manifest, { ...options, ...this.logger && { logger: this.logger } });
     const selectedAsset = selectAsset(manifest, mode, url).asset;
+    this._assertCapAsset(selectedAsset);
     await this._checkTrustline(manifest, selectedAsset);
     let amount;
     switch (mode) {
@@ -2543,18 +2814,18 @@ var RouteDockClient = class _RouteDockClient {
       default:
         throw new RouteDockManifestError(`Unknown payment mode: ${mode}`);
     }
-    const reserveId = await this._checkAndReserveSpend(amount, baseUrl);
+    const reserveId = await this._checkAndReserveSpend(amount, baseUrl, selectedAsset);
     let result;
     try {
       if (this.vault?.mode === "nulth") {
-        result = await this._payWithNulthVault(url, manifest, mode);
+        result = await this._payWithNulthVault(url, manifest, mode, request);
       } else {
         switch (mode) {
           case "x402":
-            result = await this.x402.pay(url, manifest);
+            result = await this.x402.pay(url, manifest, request);
             break;
           case "mpp-charge":
-            result = await this.charge.pay(url, manifest);
+            result = await this.charge.pay(url, manifest, request);
             break;
           default:
             throw new RouteDockManifestError(`Unknown payment mode: ${mode}`);
@@ -2573,7 +2844,7 @@ var RouteDockClient = class _RouteDockClient {
     return result;
   }
   /** Nulth ZK vault path — proof built off-chain, attached as auth signature */
-  async _payWithNulthVault(url, manifest, mode) {
+  async _payWithNulthVault(url, manifest, mode, request) {
     const prover = this.vault?.prover ?? "mock";
     if (this.network === "mainnet" && prover === "mock") {
       throw new RouteDockManifestError("nulth vault uses a MOCK Groth16 prover and cannot be used on mainnet");
@@ -2586,7 +2857,7 @@ var RouteDockClient = class _RouteDockClient {
     try {
       const { signer } = await prepareNulthSigner(this.vault, manifest, mode, this.network);
       const x402 = this.x402.withSigner(signer);
-      const result = await x402.pay(url, manifest);
+      const result = await x402.pay(url, manifest, request);
       return result;
     } catch (err) {
       if (err instanceof NulthPolicyError) {
@@ -2655,17 +2926,35 @@ var RouteDockClient = class _RouteDockClient {
       );
     }
     const endpointKey = new URL(url).origin;
-    const onSpend = this.spendCap ? (amount) => this._recordSessionSpend(amount, endpointKey) : void 0;
+    let onSpend;
+    if (this.spendCap) {
+      const sessionAsset = selectAsset(manifest, mode, url).asset;
+      this._assertCapAsset(sessionAsset);
+      onSpend = (amount) => this._recordSessionSpend(amount, endpointKey, sessionAsset);
+    }
     return this.session.openSession(url, manifest, secret, options, onSpend);
   }
+  /**
+   * The local cap accumulates one USDC total. Refuse to count any other asset
+   * against it (or let it through uncounted) when a cap is configured.
+   */
+  _assertCapAsset(asset) {
+    if (this.spendCap && asset !== this.spendCap.asset) {
+      throw new RouteDockPolicyRejectError("local_cap_asset_mismatch", {
+        cause: new Error(
+          `spendCap is denominated in ${this.spendCap.asset} but the selected payment asset is ${asset}`
+        )
+      });
+    }
+  }
   /**
    * Record spend for an MPP session voucher. Called before each voucher
    * fetch in stream(). Enforces the same local daily and per-endpoint caps
    * as discrete pay() calls. Returns a commit function to clean up the
    * reservation after the voucher fetch succeeds.
    */
-  async _recordSessionSpend(amount, endpointKey) {
-    const reserveId = await this._checkAndReserveSpend(amount, endpointKey);
+  async _recordSessionSpend(amount, endpointKey, asset) {
+    const reserveId = await this._checkAndReserveSpend(amount, endpointKey, asset);
     if (reserveId) {
       await this._commitSpend(reserveId);
     }
@@ -2704,15 +2993,16 @@ var RouteDockClient = class _RouteDockClient {
    * Both limits are independent: a payment is only reserved after **both** pass.
    * All spend (regardless of endpoint) counts toward the global accumulator.
    */
-  async _checkAndReserveSpend(amount, endpointKey) {
+  async _checkAndReserveSpend(amount, endpointKey, asset) {
     if (!this.spendCap) return "";
-    return this._withSpendMutex(async () => {
+    this._assertCapAsset(asset);
+    const spendCap = this.spendCap;
+    const amountMicros = usdcToStroops(amount);
+    const reserve = (prev) => {
       const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-      const persisted = await this.spendStore.read();
-      const current = persisted && persisted.date === today ? persisted : { date: today, totalMicros: "0", endpoints: {} };
-      const amountMicros = usdcToStroops(amount);
+      const current = prev && prev.date === today ? { ...prev, endpoints: { ...prev.endpoints } } : { date: today, totalMicros: "0", endpoints: {} };
       const total = BigInt(current.totalMicros);
-      const endpointCapStr = this.spendCap.endpointCaps?.[endpointKey];
+      const endpointCapStr = spendCap.endpointCaps?.[endpointKey];
       if (endpointCapStr !== void 0) {
         const endpointCapMicros = usdcToStroops(endpointCapStr);
         const endpointTotal = BigInt(current.endpoints[endpointKey] ?? "0");
@@ -2720,17 +3010,25 @@ var RouteDockClient = class _RouteDockClient {
           throw new RouteDockPolicyRejectError("local_endpoint_cap_exceeded");
         }
       }
-      const globalCapMicros = usdcToStroops(this.spendCap.daily);
+      const globalCapMicros = usdcToStroops(spendCap.daily);
       if (total + amountMicros > globalCapMicros) {
         throw new RouteDockPolicyRejectError("local_daily_cap_exceeded");
       }
-      const reserveId = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
-      this._pendingReserves.set(reserveId, { endpointKey, amountMicros });
       current.totalMicros = (total + amountMicros).toString();
       if (endpointCapStr !== void 0) {
         current.endpoints[endpointKey] = (BigInt(current.endpoints[endpointKey] ?? "0") + amountMicros).toString();
       }
-      await this.spendStore.write(current);
+      return current;
+    };
+    return this._withSpendMutex(async () => {
+      const store = this.spendStore;
+      if (store.update) {
+        await store.update(reserve);
+      } else {
+        await store.write(reserve(await store.read()));
+      }
+      const reserveId = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+      this._pendingReserves.set(reserveId, { endpointKey, amountMicros });
       return reserveId;
     });
   }
@@ -2752,22 +3050,29 @@ var RouteDockClient = class _RouteDockClient {
     if (!reserve) return;
     this._pendingReserves.delete(reserveId);
     const { endpointKey, amountMicros } = reserve;
-    await this._withSpendMutex(async () => {
+    const release = (prev) => {
       const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-      const persisted = await this.spendStore.read();
-      if (!persisted || persisted.date !== today) return;
-      const currentTotal = BigInt(persisted.totalMicros);
-      persisted.totalMicros = (currentTotal - amountMicros).toString();
+      if (!prev || prev.date !== today) return void 0;
+      const persisted = { ...prev, endpoints: { ...prev.endpoints } };
+      persisted.totalMicros = (BigInt(persisted.totalMicros) - amountMicros).toString();
       if (persisted.endpoints[endpointKey]) {
-        const endpointTotal = BigInt(persisted.endpoints[endpointKey]);
-        const newEndpointTotal = endpointTotal - amountMicros;
+        const newEndpointTotal = BigInt(persisted.endpoints[endpointKey]) - amountMicros;
         if (newEndpointTotal <= 0n) {
           delete persisted.endpoints[endpointKey];
         } else {
           persisted.endpoints[endpointKey] = newEndpointTotal.toString();
         }
       }
-      await this.spendStore.write(persisted);
+      return persisted;
+    };
+    await this._withSpendMutex(async () => {
+      const store = this.spendStore;
+      if (store.update) {
+        await store.update(release);
+      } else {
+        const next = release(await store.read());
+        if (next) await store.write(next);
+      }
     });
   }
 };