@dvmkit/sdk 0.1.0-rc.2 → 0.1.0-rc.3

package/dist/chunk-RHP3BRTH.js

@@ -0,0 +1,1090 @@
+import {
+  authorizeProtectedRemoval,
+  fundingReachableAt,
+  info,
+  isValidEvmPrivateKey,
+  listCredits,
+  loadConfig,
+  maxAdvertisedMicro,
+  updateConfig,
+  withinAdvertisedTolerance
+} from "./chunk-FT7IM66W.js";
+import {
+  X402_DEFAULT_NETWORK,
+  X402_V1_VERSION,
+  X402_VERSION,
+  assertSupportedX402Network,
+  buildPaymentRequirements,
+  chainIdFromCaip2,
+  createX402FacilitatorAuthHeaders,
+  decodePayment,
+  encodePayment,
+  encodeSettleResponseHeader,
+  exactEvmAuthorization,
+  settleWithFacilitator,
+  usdcContractFor,
+  usdcDomainNameFor,
+  usdcDomainVersionFor,
+  verifyWithFacilitator,
+  x402NetworkByCaip2,
+  x402NetworkToCaip2,
+  x402SupportedNetworksHint
+} from "./chunk-XY5Y5REG.js";
+import {
+  DvmError,
+  X402_CHANNELS_FILE,
+  costAnchor,
+  ensureConfigDir,
+  fetchBtcUsdRate,
+  formatStaleness,
+  formatUsd,
+  getLastKnownBtcRate,
+  msatsToUsdc,
+  resolveRpcHttpTransportOptions,
+  resolveRpcOverride,
+  usdcToMsats
+} from "./chunk-5SO7ZVOH.js";
+import {
+  callerLoggers
+} from "./chunk-66HGCPBU.js";
+import {
+  redactUrl,
+  redactUrlsInText
+} from "./chunk-FUJ36YDV.js";
+
+// src/lib/x402/asset.ts
+function resolveX402Asset(network = X402_DEFAULT_NETWORK) {
+  const spec = x402NetworkByCaip2(network);
+  if (!spec) return null;
+  return {
+    address: spec.usdc,
+    symbol: "USDC",
+    // "native" is the load-bearing word: every contract in the table is
+    // Circle's own USDC, and the dollars that read as zero here are the
+    // bridged ones.
+    label: "native USDC",
+    unit: "USDC",
+    networkLabel: spec.label,
+    confusable: spec.confusable
+  };
+}
+function x402WrongAssetHint(asset) {
+  const wrongToken = asset.confusable ? `Another dollar on ${asset.networkLabel} \u2014 ${asset.confusable}, the legacy bridged dollar, or any other stablecoin \u2014 is a different contract and will never show up here, however much of it your wallet says you hold.` : `Another dollar on ${asset.networkLabel} is a different contract and will never show up here, however much of it your wallet says you hold.`;
+  return `This rail reads only ${asset.label} (${asset.address}) on ${asset.networkLabel}. ${wrongToken} USDC on a different chain is invisible here too \u2014 this wallet reads ${asset.networkLabel} alone. If you funded the wrong one, swap it to ${asset.label} on ${asset.networkLabel}, or bridge the funds across to ${asset.networkLabel}; either way they land where this rail can spend them.`;
+}
+
+// src/lib/x402/client.ts
+import { randomBytes } from "crypto";
+
+// src/lib/btc-rate.ts
+async function resolveBtcUsdRate(purpose) {
+  try {
+    return { rate: await fetchBtcUsdRate(), stale: false };
+  } catch {
+    const cached = getLastKnownBtcRate();
+    if (cached) {
+      warnStaleRate(cached.cachedAt);
+      return { rate: cached.rate, stale: true, cachedAt: cached.cachedAt };
+    }
+    throw rateUnavailable(purpose);
+  }
+}
+async function tryResolveBtcUsdRate() {
+  try {
+    return await resolveBtcUsdRate("conversion");
+  } catch {
+    return null;
+  }
+}
+var warnedStale = false;
+function warnStaleRate(cachedAt) {
+  if (warnedStale) return;
+  warnedStale = true;
+  info(
+    `Warning: the BTC/USD rate provider is unreachable \u2014 using the last rate this machine saw (cached ${formatStaleness(cachedAt)}). Dollar figures may have drifted.`
+  );
+}
+function rateUnavailable(purpose) {
+  const outcome = purpose === "payment" ? "nothing was paid" : "no conversion was performed";
+  const noun = purpose === "payment" ? "payment" : "conversion";
+  const capped = outcome.charAt(0).toUpperCase() + outcome.slice(1);
+  return new DvmError(
+    "rate_unavailable",
+    `Could not price this ${noun}: the BTC/USD rate provider is unreachable and no cached rate is available.`,
+    `${capped}. The rate provider (CoinGecko) is rate-limiting or down, and this machine has never cached a rate. Retry in a minute; if it keeps failing, check network access to api.coingecko.com.${purpose === "payment" ? " Budgets are denominated in dollars, so a payment cannot be authorised without a rate." : ""}`,
+    {
+      display: `BTC/USD rate unavailable \u2014 ${outcome}.`,
+      anchor: "rate_unavailable",
+      purpose,
+      provider: "coingecko",
+      retryable: true
+    }
+  );
+}
+
+// src/lib/payment-authorization-bounds.ts
+var X402_EXACT_AUTHORIZATION_TTL_SECONDS = 600;
+var X402_REFUSAL_TRANSACTION_DISCOVERY_WINDOW_MS = 15 * 6e4;
+
+// src/lib/x402/channel-store.ts
+import { AsyncLocalStorage } from "async_hooks";
+import { existsSync, readFileSync, renameSync, writeFileSync } from "fs";
+import lockfile from "proper-lockfile";
+function x402ExactFundingDead(pending, now = Date.now()) {
+  const seconds = pending.authorizationValidBefore ? Number(pending.authorizationValidBefore) : NaN;
+  return Number.isFinite(seconds) ? now >= seconds * 1e3 : now >= pending.requestedAt + X402_EXACT_AUTHORIZATION_TTL_SECONDS * 1e3;
+}
+function recordPendingX402ExactFunding(pending) {
+  const { file, credits } = loadFundingFile();
+  file.exact = [
+    ...file.exact.filter((entry) => !sameFundingCredit(entry, pending, credits)),
+    pending
+  ];
+  saveFile(file);
+}
+function loadResumableX402ExactFunding(args) {
+  const { file, credits } = loadFundingFile();
+  return file.exact.find(
+    (entry) => sameFundingCredit(entry, args, credits) && !x402ExactFundingDead(entry, args.now)
+  );
+}
+function listResumableX402ExactFundings(filter = {}) {
+  const endpoint = filter.endpoint ? normalizeEndpoint(filter.endpoint) : void 0;
+  const { file, credits } = loadFundingFile();
+  return file.exact.filter(
+    (entry) => (!endpoint || fundingReachableAt(entry, endpoint, credits)) && (!filter.callerPubkey || entry.callerPubkey === filter.callerPubkey) && !x402ExactFundingDead(entry, filter.now)
+  );
+}
+function clearPendingX402ExactFunding(pending) {
+  const { file } = loadFundingFile();
+  const key = pendingKey(pending);
+  file.exact = file.exact.filter(
+    (entry) => pendingKey(entry) !== key || entry.fundId !== pending.fundId
+  );
+  saveFile(file);
+}
+var X402_PENDING_STALE_MS = 24 * 60 * 60 * 1e3;
+function x402PendingStale(pending, now = Date.now()) {
+  return now - pending.requestedAt >= X402_PENDING_STALE_MS;
+}
+function x402PendingRetired(pending) {
+  return pending.refusedAt !== void 0 || pending.supersededAt !== void 0;
+}
+function x402PendingBlockExpiresAt(pending) {
+  return x402PendingDepositExpiresAt(pending) ?? pending.requestedAt + X402_PENDING_STALE_MS;
+}
+function x402PendingDepositExpiresAt(pending) {
+  const seconds = pending.authorizationValidBefore ? Number(pending.authorizationValidBefore) : NaN;
+  return Number.isFinite(seconds) ? seconds * 1e3 : void 0;
+}
+function x402PendingUnsettled(pending, now = Date.now()) {
+  return !x402PendingRetired(pending) || now <= x402PendingBlockExpiresAt(pending);
+}
+function x402PendingFundingJson(entry) {
+  return {
+    credit_id: entry.creditId,
+    fund_id: entry.fundId,
+    endpoint: entry.endpoint,
+    channel_id: entry.channelId,
+    amount_micro: entry.amountMicro,
+    // What the ERC-3009 authorization can still pull, which is the figure a
+    // `--force` retirement is really deciding about: a deposit's authorized
+    // value can exceed the amount funded (internal-review), so `amount_micro` alone
+    // understates it. Null on a voucher-only payload, which authorizes no
+    // deposit at all.
+    deposit_micro: entry.depositMicro ?? null,
+    signed_max_claimable_micro: entry.maxClaimableMicro ?? null,
+    requested_at: new Date(entry.requestedAt).toISOString(),
+    stale: x402PendingStale(entry),
+    ...entry.authorizationValidBefore ? {
+      authorization_valid_before: new Date(
+        Number(entry.authorizationValidBefore) * 1e3
+      ).toISOString()
+    } : {},
+    ...entry.refusedAt !== void 0 ? {
+      refused_at: new Date(entry.refusedAt).toISOString(),
+      funding_blocked_until: new Date(x402PendingBlockExpiresAt(entry)).toISOString()
+    } : {},
+    ...entry.supersededAt !== void 0 ? {
+      superseded_at: new Date(entry.supersededAt).toISOString(),
+      funding_blocked_until: new Date(x402PendingBlockExpiresAt(entry)).toISOString()
+    } : {}
+  };
+}
+var EMPTY = { version: 1, channels: {}, pending: [], exact: [] };
+var x402LockOwner = new AsyncLocalStorage();
+async function withX402ChannelLock(operation) {
+  if (x402LockOwner.getStore()?.active) return operation();
+  ensureX402ChannelFile();
+  const release = await lockfile.lock(X402_CHANNELS_FILE, {
+    realpath: false,
+    retries: { retries: 20, minTimeout: 25, maxTimeout: 250 }
+  });
+  const owner = { active: true };
+  try {
+    return await x402LockOwner.run(owner, operation);
+  } finally {
+    owner.active = false;
+    await release();
+  }
+}
+var DvmX402ChannelStorage = class {
+  nextBalanceProvenance;
+  get(key) {
+    return fromSynchronousStore(() => loadFile().channels[canonicalChannelId(key)]?.context);
+  }
+  /** Read the highest cumulative amount a DVM has acknowledged for this channel. */
+  getAcknowledgedCumulativeAmount(key) {
+    return fromSynchronousStore(
+      () => readAcknowledgedCumulativeAmount(loadFile().channels[canonicalChannelId(key)])
+    );
+  }
+  /**
+   * Upstream's ordinary write. Its chain-recovery paths are authoritative and
+   * clear the unreconciled stamp. DVM-response paths scope this same write to
+   * persist their weaker provenance atomically with the balance (internal-review).
+   */
+  set(key, context) {
+    return fromSynchronousStore(() => {
+      const provenance = this.nextBalanceProvenance?.provenance ?? "observed";
+      this.nextBalanceProvenance = void 0;
+      writeContext(key, context, provenance, "advance");
+    });
+  }
+  /**
+   * Apply non-chain provenance to the next upstream `set` on this instance.
+   * Returns a cleanup for paths where upstream rejects or deletes instead, so a
+   * later chain recovery cannot inherit a stale provenance decision.
+   */
+  stageNextUnobservedBalanceProvenance(provenance) {
+    const staged = { provenance };
+    this.nextBalanceProvenance = staged;
+    return () => {
+      if (this.nextBalanceProvenance === staged) this.nextBalanceProvenance = void 0;
+    };
+  }
+  /**
+   * Write a context whose `balance` carries a deposit this machine added on its
+   * own authority, and stamp the record as unreconciled (internal-review).
+   *
+   * Separate from {@link set} because the two differ in exactly one thing that
+   * matters later: where the figure came from. Nothing else about the write
+   * differs.
+   */
+  setLocallyAppliedDeposit(key, context) {
+    return fromSynchronousStore(() => {
+      writeContext(key, context, "unreconciled", "advance");
+    });
+  }
+  /**
+   * Write a context whose `balance` is byte-for-byte the one already stored,
+   * leaving the unreconciled stamp exactly as it found it (internal-review).
+   *
+   * The replay acknowledgement's idempotent second pass is what needs this: it
+   * restates a cumulative base without adding to the balance, so it observes
+   * nothing and must not certify the local sum it left alone. The caller owes
+   * the precondition in the name — a write that does move `balance` belongs on
+   * one of the other two.
+   */
+  setUnchangedBalance(key, context) {
+    return fromSynchronousStore(() => {
+      writeContext(key, context, "unchanged", "advance");
+    });
+  }
+  /**
+   * Seed upstream's cooperative-refund probe without changing the acknowledged
+   * base. Records written before internal-review have only the upstream context, so
+   * `hold` adopts its acknowledged value rather than losing that base to the
+   * chain floor this seeds. The seed itself is a `channels()` read, so it is
+   * `observed` and settles the unreconciled question like any other.
+   */
+  setRefundProbe(key, context) {
+    return fromSynchronousStore(() => {
+      writeContext(key, context, "observed", "hold");
+    });
+  }
+  /**
+   * Replace the stored projection with a successful `channels()` read.
+   *
+   * Only `balance` and `totalClaimed` move. The highest DVM-acknowledged
+   * cumulative base stays fail-closed, and the chain observation clears the
+   * unreconciled stamp.
+   */
+  reconcileChainState(key, state) {
+    return fromSynchronousStore(() => {
+      const file = loadFile();
+      const id = canonicalChannelId(key);
+      const record = file.channels[id] ?? {};
+      file.channels[id] = channelRecordWithContext(
+        record,
+        { ...record.context ?? {}, ...state },
+        "observed",
+        "hold"
+      );
+      saveFile(file);
+    });
+  }
+  delete(key) {
+    return fromSynchronousStore(() => {
+      const file = loadFile();
+      const id = canonicalChannelId(key);
+      const record = file.channels[id];
+      if (!record) return;
+      if (record.metadata) file.channels[id] = { metadata: record.metadata };
+      else {
+        const { [id]: _removed, ...channels } = file.channels;
+        file.channels = channels;
+      }
+      saveFile(file);
+    });
+  }
+};
+function recordX402ChannelMetadata(metadata) {
+  const file = loadFile();
+  const id = canonicalChannelId(metadata.channelId);
+  const acknowledged = file.channels[id]?.metadata;
+  const sameOwner = acknowledged?.endpoint === metadata.endpoint && acknowledged.callerPubkey === metadata.callerPubkey && acknowledged.creditId === metadata.creditId;
+  file.channels[id] = {
+    ...file.channels[id],
+    metadata: !acknowledged || sameOwner ? { ...metadata, channelId: id } : { ...acknowledged, channelId: id }
+  };
+  saveFile(file);
+}
+function acknowledgeX402ChannelOwner(owner) {
+  const file = loadFile();
+  const id = canonicalChannelId(owner.channelId);
+  const record = file.channels[id];
+  if (!record?.metadata) {
+    throw new Error(
+      `Cannot acknowledge credit ${owner.creditId}: x402 channel ${id} has no metadata`
+    );
+  }
+  file.channels[id] = {
+    ...record,
+    metadata: {
+      ...record.metadata,
+      endpoint: owner.endpoint,
+      callerPubkey: owner.callerPubkey,
+      creditId: owner.creditId,
+      updatedAt: Date.now()
+    }
+  };
+  saveFile(file);
+}
+function listX402Channels(filter = {}) {
+  const payer = filter.payer?.toLowerCase();
+  return allChannelMetadata().filter((entry) => !payer || entry.config.payer.toLowerCase() === payer).sort((a, b) => b.updatedAt - a.updatedAt);
+}
+function findX402Channel(args) {
+  const channels = allChannelMetadata();
+  if (args.channelId) {
+    const channelId = canonicalChannelId(args.channelId);
+    return channels.find((entry) => entry.channelId === channelId);
+  }
+  const endpoint = args.endpoint ? normalizeEndpoint(args.endpoint) : void 0;
+  return channels.filter(
+    (entry) => (!endpoint || entry.endpoint === endpoint) && (!args.callerPubkey || entry.callerPubkey === args.callerPubkey) && (!args.creditId || entry.creditId === args.creditId)
+  ).sort((a, b) => b.updatedAt - a.updatedAt)[0];
+}
+function x402ChannelBalanceUnreconciledAt(channelId) {
+  return loadFile().channels[canonicalChannelId(channelId)]?.unreconciledBalanceAt;
+}
+function recordPendingX402Funding(pending) {
+  const { file, credits } = loadFundingFile();
+  const pendingOrigin = normalizeEndpoint(pending.endpoint);
+  file.pending = [
+    ...file.pending.flatMap((entry) => {
+      if (!sameFundingCredit(entry, pending, credits) || x402PendingRetired(entry)) return [entry];
+      if (normalizeEndpoint(entry.endpoint) === pendingOrigin) return [];
+      return [{ ...entry, supersededAt: pending.requestedAt }];
+    }),
+    pending
+  ];
+  saveFile(file);
+}
+function loadResumableX402Funding(args) {
+  const { file, credits } = loadFundingFile();
+  return file.pending.find(
+    (entry) => sameFundingCredit(entry, args, credits) && !x402PendingRetired(entry)
+  );
+}
+function listPendingX402Fundings(filter = {}) {
+  const endpoint = filter.endpoint ? normalizeEndpoint(filter.endpoint) : void 0;
+  const { file, credits } = loadFundingFile();
+  return file.pending.filter(
+    (entry) => (!endpoint || fundingReachableAt(entry, endpoint, credits)) && (!filter.callerPubkey || entry.callerPubkey === filter.callerPubkey)
+  );
+}
+function listResumableX402Fundings(filter = {}) {
+  return listPendingX402Fundings(filter).filter((entry) => !x402PendingRetired(entry));
+}
+function listPendingX402FundingsForChannel(channelId) {
+  const canonical = canonicalChannelId(channelId);
+  return loadFundingFile().file.pending.filter(
+    (entry) => canonicalChannelId(entry.channelId) === canonical
+  );
+}
+function retirePendingX402Funding(pending) {
+  const { file } = loadFundingFile();
+  const key = pendingKey(pending);
+  const target = file.pending.find(
+    (entry) => pendingKey(entry) === key && !x402PendingRetired(entry)
+  );
+  if (!target) return;
+  const refusedAt = Date.now();
+  file.pending = file.pending.map((entry) => entry === target ? { ...entry, refusedAt } : entry);
+  saveFile(file);
+}
+function clearPendingX402Funding(pending) {
+  const { file } = loadFundingFile();
+  const next = file.pending.filter((entry) => !sameJournalEntry(entry, pending));
+  if (next.length === file.pending.length) return;
+  file.pending = next;
+  saveFile(file);
+}
+function writeContext(key, context, provenance, base) {
+  const file = loadFile();
+  const id = canonicalChannelId(key);
+  const record = file.channels[id] ?? {};
+  file.channels[id] = channelRecordWithContext(record, context, provenance, base);
+  saveFile(file);
+}
+function channelRecordWithContext(record, context, provenance, base) {
+  const { unreconciledBalanceAt: previousStamp, ...kept } = record;
+  const stamp = provenance === "unreconciled" ? Date.now() : provenance === "unchanged" ? previousStamp : void 0;
+  const stored = readAcknowledgedCumulativeAmount(record);
+  const acknowledgedCumulativeAmount = base === "advance" ? highestCumulativeAmount(stored, context.chargedCumulativeAmount) : stored;
+  return {
+    ...kept,
+    context,
+    ...acknowledgedCumulativeAmount !== void 0 ? { acknowledgedCumulativeAmount } : {},
+    ...stamp !== void 0 ? { unreconciledBalanceAt: stamp } : {}
+  };
+}
+function allChannelMetadata() {
+  return Object.values(loadFile().channels).filter((record) => record !== void 0).map((record) => record.metadata).filter((entry) => entry !== void 0);
+}
+function pendingKey(entry) {
+  return `${normalizeEndpoint(entry.endpoint)}\0${entry.callerPubkey}\0${entry.creditId}`;
+}
+function sameFundingCredit(entry, target, credits) {
+  return entry.callerPubkey === target.callerPubkey && entry.creditId === target.creditId && fundingReachableAt(entry, normalizeEndpoint(target.endpoint), credits);
+}
+function loadFundingFile() {
+  const snapshot = collapseFundingFile();
+  if (!snapshot.changed) return snapshot;
+  const persisted = tryWithX402ChannelLockSync(() => {
+    const current = collapseFundingFile();
+    if (current.changed) saveFile(current.file);
+    return current;
+  });
+  return persisted ?? snapshot;
+}
+function collapseFundingFile() {
+  const file = loadFile();
+  const credits = listCredits();
+  const pending = dedupeX402FundingCredits(file.pending, credits);
+  const exact = dedupeFundingCredits(file.exact, credits);
+  if (pending.changed) file.pending = pending.entries;
+  if (exact.changed) file.exact = exact.entries;
+  return { file, credits, changed: pending.changed || exact.changed };
+}
+function dedupeX402FundingCredits(entries, credits) {
+  const kept = [];
+  let changed = false;
+  for (const entry of entries) {
+    if (x402PendingRetired(entry)) {
+      kept.push(entry);
+      continue;
+    }
+    const index = kept.findIndex(
+      (candidate) => !x402PendingRetired(candidate) && sameFundingCredit(candidate, entry, credits)
+    );
+    if (index === -1) {
+      kept.push(entry);
+      continue;
+    }
+    const seen = kept[index];
+    const seenAt = Number.isFinite(seen.requestedAt) ? seen.requestedAt : 0;
+    const entryAt = Number.isFinite(entry.requestedAt) ? entry.requestedAt : 0;
+    const sameOrigin = normalizeEndpoint(seen.endpoint) === normalizeEndpoint(entry.endpoint);
+    if (entryAt > seenAt) {
+      kept[index] = entry;
+      if (!sameOrigin) kept.push({ ...seen, supersededAt: entry.requestedAt });
+    } else if (!sameOrigin) {
+      kept.push({ ...entry, supersededAt: seen.requestedAt });
+    }
+    changed = true;
+  }
+  return { entries: kept, changed };
+}
+function dedupeFundingCredits(entries, credits) {
+  const kept = [];
+  let changed = false;
+  for (const entry of entries) {
+    const index = kept.findIndex((candidate) => sameFundingCredit(candidate, entry, credits));
+    if (index === -1) {
+      kept.push(entry);
+      continue;
+    }
+    const seenAt = Number.isFinite(kept[index].requestedAt) ? kept[index].requestedAt : 0;
+    const entryAt = Number.isFinite(entry.requestedAt) ? entry.requestedAt : 0;
+    if (entryAt > seenAt) kept[index] = entry;
+    changed = true;
+  }
+  return { entries: kept, changed };
+}
+function sameJournalEntry(entry, target) {
+  return pendingKey(entry) === pendingKey(target) && entry.fundId === target.fundId && x402PendingRetired(entry) === x402PendingRetired(target);
+}
+function fromSynchronousStore(operation) {
+  try {
+    return Promise.resolve(operation());
+  } catch (error) {
+    return Promise.reject(error instanceof Error ? error : new Error(String(error)));
+  }
+}
+function highestCumulativeAmount(previous, next) {
+  if (previous === void 0) return next;
+  if (next === void 0) return previous;
+  return BigInt(next) > BigInt(previous) ? next : previous;
+}
+function readAcknowledgedCumulativeAmount(record) {
+  return record?.acknowledgedCumulativeAmount ?? record?.context?.chargedCumulativeAmount;
+}
+function canonicalChannelId(value) {
+  return value.toLowerCase();
+}
+function normalizeEndpoint(endpoint) {
+  try {
+    return new URL(endpoint).origin;
+  } catch {
+    return endpoint.replace(/\/+$/, "");
+  }
+}
+function tryWithX402ChannelLockSync(operation) {
+  if (x402LockOwner.getStore()?.active) return operation();
+  ensureX402ChannelFile();
+  let release;
+  try {
+    release = lockfile.lockSync(X402_CHANNELS_FILE, { realpath: false });
+  } catch (error) {
+    if (error.code === "ELOCKED") return void 0;
+    throw error;
+  }
+  const owner = { active: true };
+  try {
+    return x402LockOwner.run(owner, operation);
+  } finally {
+    owner.active = false;
+    release();
+  }
+}
+function ensureX402ChannelFile() {
+  ensureConfigDir();
+  if (existsSync(X402_CHANNELS_FILE)) return;
+  try {
+    writeFileSync(X402_CHANNELS_FILE, `${JSON.stringify(EMPTY, null, 2)}
+`, {
+      mode: 384,
+      flag: "wx"
+    });
+  } catch {
+  }
+}
+function loadFile() {
+  if (!existsSync(X402_CHANNELS_FILE)) return { ...EMPTY, channels: {}, pending: [], exact: [] };
+  try {
+    const raw = JSON.parse(readFileSync(X402_CHANNELS_FILE, "utf8"));
+    if (raw.version !== 1 || !raw.channels || typeof raw.channels !== "object" || Array.isArray(raw.channels) || !Array.isArray(raw.pending)) {
+      throw new Error("unsupported x402 channel store shape");
+    }
+    return {
+      version: 1,
+      channels: raw.channels,
+      pending: raw.pending,
+      // Tolerated rather than required, unlike its two siblings: every file
+      // written before internal-review lacks the key, and failing closed on it would
+      // read as a corrupt journal on a store that is perfectly intact.
+      exact: Array.isArray(raw.exact) ? raw.exact : []
+    };
+  } catch (cause) {
+    throw new DvmError(
+      "x402_channel_store_invalid",
+      "The saved x402 channel journal cannot be read safely.",
+      `Do not delete ${X402_CHANNELS_FILE}; restore or repair it before signing another channel voucher.`,
+      { cause: cause instanceof Error ? cause.message : String(cause) }
+    );
+  }
+}
+function saveFile(file) {
+  ensureConfigDir();
+  const tmp = `${X402_CHANNELS_FILE}.${String(process.pid)}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(file, null, 2)}
+`, { mode: 384 });
+  renameSync(tmp, X402_CHANNELS_FILE);
+}
+
+// src/lib/x402/wallet.ts
+function loadX402Wallet() {
+  const config = loadConfig();
+  const x402 = config?.x402;
+  const privateKey = x402?.privateKey;
+  if (!privateKey || !isValidEvmPrivateKey(privateKey)) return null;
+  return {
+    privateKey,
+    address: "",
+    network: x402.network ?? X402_DEFAULT_NETWORK
+  };
+}
+async function ensureAddress(wallet) {
+  if (!isValidEvmPrivateKey(wallet.privateKey)) throw invalidX402PrivateKey();
+  if (wallet.address) return wallet;
+  const { privateKeyToAccount } = await import("viem/accounts");
+  const account = privateKeyToAccount(wallet.privateKey);
+  return { ...wallet, address: account.address };
+}
+async function connectedX402Payer() {
+  const wallet = loadX402Wallet();
+  if (!wallet) return null;
+  return (await ensureAddress(wallet)).address;
+}
+async function generateX402PrivateKey() {
+  const { generatePrivateKey } = await import("viem/accounts");
+  return generatePrivateKey();
+}
+async function repinX402WalletNetwork(network) {
+  assertSupportedX402Network(network);
+  return withX402ChannelLock(async () => {
+    const { previous } = await updateConfig({
+      reason: "x402_wallet_repin",
+      patch: (current) => {
+        if (!current) throw new DvmError("no_config", "No config found.", "Run: dvm init");
+        const privateKey = current.x402?.privateKey;
+        if (privateKey === void 0) throw x402WalletMissingError();
+        if (!isValidEvmPrivateKey(privateKey)) throw invalidX402PrivateKey();
+        return { set: { x402: { privateKey, network } } };
+      }
+    });
+    const stored = previous?.x402;
+    if (stored === void 0) throw x402WalletMissingError();
+    if (!isValidEvmPrivateKey(stored.privateKey)) throw invalidX402PrivateKey();
+    const { privateKeyToAccount } = await import("viem/accounts");
+    return {
+      address: privateKeyToAccount(stored.privateKey).address,
+      previousNetwork: stored.network ?? X402_DEFAULT_NETWORK,
+      network
+    };
+  });
+}
+async function saveX402Wallet(privateKey, network) {
+  if (network !== void 0) assertSupportedX402Network(network);
+  if (!isValidEvmPrivateKey(privateKey)) throw invalidX402PrivateKey();
+  const { privateKeyToAccount } = await import("viem/accounts");
+  const account = privateKeyToAccount(privateKey);
+  let resolved;
+  await updateConfig({
+    reason: "x402_wallet_connect",
+    patch: (current) => {
+      resolved = network ?? current?.x402?.network;
+      return {
+        set: { x402: resolved === void 0 ? { privateKey } : { privateKey, network: resolved } }
+      };
+    }
+  });
+  return { address: account.address, network: resolved ?? X402_DEFAULT_NETWORK };
+}
+async function removeX402Wallet() {
+  await updateConfig({
+    reason: "x402_wallet_disconnect",
+    authorize: authorizeProtectedRemoval("x402"),
+    patch: () => ({ unset: ["x402"] })
+  });
+}
+function invalidX402PrivateKey() {
+  return new DvmError(
+    "invalid_key",
+    "Invalid secp256k1 private key.",
+    "Reconnect with `dvm wallet x402-connect --key-file <path>`, set DVM_X402_KEY, or pipe a valid 0x-prefixed 32-byte secp256k1 private key through stdin."
+  );
+}
+function x402WalletMissingError() {
+  return new DvmError(
+    "x402_wallet_missing",
+    "No x402 wallet is connected.",
+    "Run 'dvm wallet x402-connect' to create one, or add --key-file <path> to import a key you already hold."
+  );
+}
+async function getX402Balance(wallet) {
+  const w = await ensureAddress(wallet);
+  const spec = x402NetworkByCaip2(w.network);
+  if (!spec) {
+    throw new DvmError(
+      "x402_unsupported_network",
+      `The x402 wallet is configured for ${w.network}, a chain this rail can't settle on.`,
+      `${x402SupportedNetworksHint()} Re-pin the connected wallet without handling its key: 'dvm wallet x402-network ${X402_DEFAULT_NETWORK}'.`
+    );
+  }
+  const chains = await import("viem/chains");
+  const { createPublicClient, http, erc20Abi } = await import("viem");
+  const chain = chains[spec.viemChain];
+  const { url: rpcUrl, source: rpcSource } = resolveRpcOverride(
+    process.env.DVM_X402_RPC_URL,
+    chain?.rpcUrls.default.http[0]
+  );
+  try {
+    const transportOptions = resolveRpcHttpTransportOptions(
+      rpcSource,
+      process.env.DVM_X402_RPC_HEADERS_JSON
+    );
+    const client = createPublicClient({
+      chain,
+      transport: transportOptions ? http(rpcUrl, transportOptions) : http(rpcUrl)
+    });
+    const balance = await client.readContract({
+      address: spec.usdc,
+      abi: erc20Abi,
+      functionName: "balanceOf",
+      args: [w.address]
+    });
+    return {
+      address: w.address,
+      usdc: Number(balance) / 1e6,
+      network: w.network,
+      tokenAddress: spec.usdc,
+      // internal-review: redacted here rather than at a display surface, so the clear
+      // endpoint never leaves this function on the success path either.
+      rpcUrlRedacted: rpcUrl ? redactUrl(rpcUrl) : void 0,
+      rpcSource
+    };
+  } catch (err) {
+    const cause = redactUrlsInText(err instanceof Error ? err.message : String(err));
+    throw new DvmError(
+      "x402_rpc_error",
+      `x402 USDC balance lookup on ${spec.label} failed: ${cause}`,
+      // A caller who set the override doesn't need to be told to set it. Which
+      // knob is theirs to turn depends on whose endpoint this was.
+      rpcSource === "override" ? `DVM_X402_RPC_URL sent this read to ${redactUrl(rpcUrl)}. Correct it, or unset it to fall back to ${spec.label}'s bundled endpoint.` : `Verify connectivity to ${spec.label}'s bundled endpoint${rpcUrl ? ` (${redactUrl(rpcUrl)})` : ""}, or send the read somewhere else with DVM_X402_RPC_URL.`
+    );
+  }
+}
+
+// src/lib/x402/client.ts
+async function tryX402Payment(request, wallet) {
+  const selection = selectPaymentRequirement(request);
+  let networkSlug;
+  let networkCaip2;
+  let chainId;
+  let usdc;
+  try {
+    networkCaip2 = x402NetworkToCaip2(selection.network);
+    const mapped = x402NetworkByCaip2(networkCaip2);
+    networkSlug = mapped?.slug ?? selection.network;
+    chainId = chainIdFromCaip2(networkCaip2);
+    usdc = usdcContractFor(networkSlug);
+  } catch (err) {
+    throw new DvmError(
+      "x402_build_failed",
+      `Could not resolve x402 network from '${selection.network}': ${err instanceof Error ? err.message : String(err)}`,
+      "Check that the DVM's advertised x402.network is a CAIP-2 chain id (e.g. 'eip155:8453' for Base)."
+    );
+  }
+  if (!usdc) return null;
+  const rate = await priceableRate(request.btcRate);
+  if (rate === null) return null;
+  const localUsdcMicro = BigInt(msatsToUsdc(request.amountMsats, rate));
+  const requiredUsdcMicro = resolveRequiredUsdcMicro(selection.amount, localUsdcMicro);
+  const signedAmountMsats = usdcToMsats(Number(requiredUsdcMicro) / 1e6, rate);
+  try {
+    const w = await ensureAddress(wallet);
+    const validAfter = 0n;
+    const validBefore = BigInt(
+      Math.floor(Date.now() / 1e3) + X402_EXACT_AUTHORIZATION_TTL_SECONDS
+    );
+    const nonce = request.nonce ?? `0x${randomBytes(32).toString("hex")}`;
+    const domainName = selectedDomainField(selection.accepted?.extra?.name, "name") ?? usdcDomainNameFor(networkSlug) ?? "USD Coin";
+    const domainVersion = selectedDomainField(selection.accepted?.extra?.version, "version") ?? usdcDomainVersionFor(networkSlug) ?? "2";
+    const { signTypedData } = await import("viem/accounts");
+    const signature = await signTypedData({
+      privateKey: w.privateKey,
+      domain: {
+        name: domainName,
+        version: domainVersion,
+        chainId,
+        verifyingContract: usdc
+      },
+      types: {
+        TransferWithAuthorization: [
+          { name: "from", type: "address" },
+          { name: "to", type: "address" },
+          { name: "value", type: "uint256" },
+          { name: "validAfter", type: "uint256" },
+          { name: "validBefore", type: "uint256" },
+          { name: "nonce", type: "bytes32" }
+        ]
+      },
+      primaryType: "TransferWithAuthorization",
+      message: {
+        from: w.address,
+        to: selection.payTo,
+        value: requiredUsdcMicro,
+        validAfter,
+        validBefore,
+        nonce
+      }
+    });
+    const exactPayload = {
+      signature,
+      payload: {
+        authorization: {
+          from: w.address,
+          to: selection.payTo,
+          value: requiredUsdcMicro.toString(),
+          validAfter: validAfter.toString(),
+          validBefore: validBefore.toString(),
+          nonce
+        }
+      }
+    };
+    const payload = selection.version === X402_V1_VERSION ? {
+      x402Version: X402_V1_VERSION,
+      scheme: "exact",
+      network: networkSlug,
+      payload: { signature: exactPayload.signature, ...exactPayload.payload }
+    } : {
+      x402Version: X402_VERSION,
+      ...selection.resource ? { resource: selection.resource } : {},
+      accepted: selection.accepted ?? buildPaymentRequirements({
+        x402Config: {
+          payTo: selection.payTo,
+          network: networkCaip2,
+          ...selection.asset ? { asset: selection.asset } : {}
+        },
+        requiredUsdcMicro,
+        resource: selection.resource?.url ?? "",
+        version: X402_VERSION
+      }),
+      payload: { signature: exactPayload.signature, ...exactPayload.payload },
+      extensions: selection.extensions ?? {}
+    };
+    return {
+      paymentHeader: encodePayment(payload),
+      x402Version: selection.version,
+      amountUsdcMicro: requiredUsdcMicro.toString(),
+      amountMsats: signedAmountMsats,
+      btcRate: rate
+    };
+  } catch (err) {
+    throw new DvmError(
+      "x402_build_failed",
+      `Failed to build x402 payment: ${err instanceof Error ? err.message : String(err)}`,
+      "Check the configured x402 private key and RPC reachability for the target chain."
+    );
+  }
+}
+function isSignableExactRequirement(requirement) {
+  const transferMethod = requirement.extra?.assetTransferMethod;
+  return requirement.scheme === "exact" && (transferMethod === void 0 || transferMethod === "eip3009");
+}
+function selectPaymentRequirement(request) {
+  const challenge = request.paymentRequired;
+  if (challenge?.x402Version === X402_VERSION) {
+    const accepted = challenge.accepts.find(isSignableExactRequirement);
+    if (!accepted) {
+      throw invalidChallenge("The DVM's v2 x402 challenge has no exact EIP-3009 requirement.");
+    }
+    return {
+      version: X402_VERSION,
+      network: accepted.network,
+      amount: accepted.amount,
+      payTo: accepted.payTo,
+      asset: accepted.asset,
+      accepted,
+      resource: challenge.resource,
+      extensions: challenge.extensions
+    };
+  }
+  if (challenge?.x402Version === X402_V1_VERSION) {
+    const accepted = challenge.accepts.find((candidate) => candidate.scheme === "exact");
+    if (!accepted) throw invalidChallenge("The DVM's v1 x402 challenge has no exact requirement.");
+    return {
+      version: X402_V1_VERSION,
+      network: accepted.network,
+      amount: accepted.maxAmountRequired,
+      payTo: accepted.payTo,
+      asset: accepted.asset
+    };
+  }
+  return {
+    version: request.x402Version ?? X402_V1_VERSION,
+    network: request.network,
+    amount: request.requiredUsdcMicro,
+    payTo: request.payTo,
+    asset: request.asset,
+    resource: request.resource
+  };
+}
+function invalidChallenge(message) {
+  return new DvmError(
+    "x402_build_failed",
+    message,
+    "Ask the DVM operator to advertise an exact x402 payment requirement."
+  );
+}
+function selectedDomainField(value, field) {
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value === "string" && value.length > 0) return value;
+  throw invalidChallenge(`The DVM advertised an invalid x402 ${field}.`);
+}
+function resolveRequiredUsdcMicro(advertised, localUsdcMicro) {
+  if (advertised === void 0) return localUsdcMicro;
+  if (!/^[1-9]\d*$/.test(advertised)) {
+    throw new DvmError(
+      "x402_amount_invalid",
+      `The DVM advertised an invalid x402 maxAmountRequired: '${advertised}'.`,
+      "Do not sign this payment. Ask the DVM operator to return a positive integer number of USDC micro-units."
+    );
+  }
+  const required = BigInt(advertised);
+  if (withinAdvertisedTolerance(required, localUsdcMicro)) return required;
+  const advertisedUsd = Number(required) / 1e6;
+  const localUsd = Number(localUsdcMicro) / 1e6;
+  throw new DvmError(
+    "x402_amount_exceeds_limit",
+    `The DVM's x402 charge ($${formatUsd(advertisedUsd)} USDC) is more than 10% above the caller's local price ($${formatUsd(localUsd)} USDC).`,
+    "The payment was not signed. Refresh the quote or ask the DVM operator to check its BTC/USD rate.",
+    {
+      advertised_usdc_microunits: required.toString(),
+      local_usdc_microunits: localUsdcMicro.toString(),
+      max_usdc_microunits: maxAdvertisedMicro(localUsdcMicro).toString(),
+      anchor: costAnchor(advertisedUsd),
+      display: `Payment refused: $${formatUsd(advertisedUsd)} USDC exceeds the 10% safety margin over the caller's $${formatUsd(localUsd)} USDC estimate.`
+    }
+  );
+}
+async function priceableRate(btcRate) {
+  if (btcRate && btcRate > 0) return btcRate;
+  try {
+    return (await resolveBtcUsdRate("payment")).rate;
+  } catch (err) {
+    if (err instanceof DvmError && err.code === "rate_unavailable") {
+      info(
+        "Skipping the x402 rail: it prices in USDC and the BTC/USD rate is unavailable (no cached rate on this machine). Trying the remaining rails."
+      );
+      return null;
+    }
+    throw err;
+  }
+}
+
+// src/lib/x402/verify.ts
+async function verifyX402Payment(paymentHeader, config, requiredUsdcMicro, resource, btcUsdRate, exactVersions = { v1: true, v2: true }) {
+  return callerLoggers.x402.span(
+    "x402.verify_payment",
+    {
+      resource,
+      required_usdc_micro: Number(requiredUsdcMicro),
+      facilitator_url: config.facilitator
+    },
+    async () => {
+      let payload;
+      try {
+        payload = decodePayment(paymentHeader);
+      } catch {
+        return { verified: false, amountMsats: 0, invalidReason: "decode_failed" };
+      }
+      if (payload.x402Version === 1 && !exactVersions.v1 || payload.x402Version === 2 && !exactVersions.v2) {
+        return { verified: false, amountMsats: 0, invalidReason: "unsupported_version" };
+      }
+      const requirementOpts = { x402Config: config, requiredUsdcMicro, resource };
+      const requirements = payload.x402Version === 1 ? buildPaymentRequirements({ ...requirementOpts, version: 1 }) : buildPaymentRequirements({ ...requirementOpts, version: 2 });
+      const createAuthHeaders = createX402FacilitatorAuthHeaders(config);
+      const verifyRes = await verifyWithFacilitator(
+        payload,
+        requirements,
+        config,
+        createAuthHeaders
+      );
+      if (!verifyRes.isValid) {
+        return {
+          verified: false,
+          amountMsats: 0,
+          invalidReason: verifyRes.invalidReason ?? "verify_failed"
+        };
+      }
+      const settleRes = await settleWithFacilitator(
+        payload,
+        requirements,
+        config,
+        createAuthHeaders
+      );
+      if (!settleRes.success) {
+        return {
+          verified: false,
+          amountMsats: 0,
+          invalidReason: settleRes.errorReason ?? "settle_failed"
+        };
+      }
+      const amountUsdcMicro = Number.parseInt(exactEvmAuthorization(payload).value, 10);
+      const amountMsats = usdcToMsats(amountUsdcMicro / 1e6, btcUsdRate);
+      callerLoggers.x402.info("x402.verify_payment.result", {
+        verified: true,
+        tx_hash: settleRes.transaction,
+        amount_msats: amountMsats
+      });
+      return {
+        verified: true,
+        amountMsats,
+        amountUsdcMicro,
+        txHash: settleRes.transaction,
+        settleResponseHeader: encodeSettleResponseHeader(settleRes)
+      };
+    }
+  );
+}
+
+export {
+  resolveX402Asset,
+  x402WrongAssetHint,
+  resolveBtcUsdRate,
+  tryResolveBtcUsdRate,
+  X402_EXACT_AUTHORIZATION_TTL_SECONDS,
+  X402_REFUSAL_TRANSACTION_DISCOVERY_WINDOW_MS,
+  x402ExactFundingDead,
+  recordPendingX402ExactFunding,
+  loadResumableX402ExactFunding,
+  listResumableX402ExactFundings,
+  clearPendingX402ExactFunding,
+  X402_PENDING_STALE_MS,
+  x402PendingStale,
+  x402PendingRetired,
+  x402PendingBlockExpiresAt,
+  x402PendingDepositExpiresAt,
+  x402PendingUnsettled,
+  x402PendingFundingJson,
+  withX402ChannelLock,
+  DvmX402ChannelStorage,
+  recordX402ChannelMetadata,
+  acknowledgeX402ChannelOwner,
+  listX402Channels,
+  findX402Channel,
+  x402ChannelBalanceUnreconciledAt,
+  recordPendingX402Funding,
+  loadResumableX402Funding,
+  listPendingX402Fundings,
+  listResumableX402Fundings,
+  listPendingX402FundingsForChannel,
+  retirePendingX402Funding,
+  clearPendingX402Funding,
+  loadX402Wallet,
+  ensureAddress,
+  connectedX402Payer,
+  generateX402PrivateKey,
+  repinX402WalletNetwork,
+  saveX402Wallet,
+  removeX402Wallet,
+  getX402Balance,
+  tryX402Payment,
+  isSignableExactRequirement,
+  verifyX402Payment
+};