@dvmkit/sdk 0.1.3-rc.7 → 0.1.5-rc.7

package/README.md

@@ -2,21 +2,113 @@
 
 Build Digital Vending Machines: accountless HTTPS services with typed inputs, jobs, and payment rails.
 
-## Development
+Requires Node.js 22 or later. This is pre-1.0 alpha software: pin the exact package version and read the [release notes](./CHANGELOG.md) before upgrading.
 
-Use the Node.js release in `.nvmrc` (Node 22). Install with `npm ci`, then run the same gate CI runs with `npm run verify`: the toolchain check, lint, build, typecheck (including the release scripts under `checkJs`), unit and database tests, the public API surface and package-shape checks, a consumer install, a public-safety scan, the release contract, and a clean-install smoke.
+## Quickstart: a free DVM
+
+Create a project and install the SDK:
+
+```sh
+mkdir hello-dvm && cd hello-dvm
+npm init -y
+npm install --save-exact @dvmkit/sdk
+```
+
+Save this as `handler.mjs`:
+
+```js
+import { configureDVM, z } from "@dvmkit/sdk";
+
+export default configureDVM({
+  name: "hello",
+  capability: "echo",
+  input: z.object({ text: z.string().min(1) }),
+  example: { text: "hello" },
+  onJob(ctx) {
+    ctx.artifact({ mime_type: "text/plain", data: ctx.input.text });
+    ctx.complete("Echoed the input");
+  },
+});
+```
+
+Save this as `server.mjs`, then run it with `node server.mjs`:
+
+```js
+import { serve } from "@dvmkit/sdk/server";
+import dvm from "./handler.mjs";
+
+await serve(dvm, { devMode: true });
+```
+
+Submit a local request. `devMode` makes Postgres optional and skips payment verification only when no Cashu, x402, or Tempo rail is configured:
+
+```sh
+curl -sS http://localhost:8080/v1/job \
+  -H 'content-type: application/json' \
+  --data '{"capability":"echo","data":{"text":"hello"}}'
+```
+
+Test the handler without opening a port or configuring a payment rail:
+
+```js
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createTestContext } from "@dvmkit/sdk/testing";
+import dvm from "./handler.mjs";
+
+test("echoes its input", async () => {
+  const ctx = createTestContext({ input: { text: "hello" } });
+  await dvm.capabilities.echo.onJob(ctx);
+  assert.equal(ctx.completed, true);
+  assert.equal(ctx.messages[0].content.data, "hello");
+});
+```
+
+Run that file with `node --test handler.test.mjs`. The repository carries the complete version under [`examples/quickstart`](./examples/quickstart), plus runnable [signed-auth/custom-route](./examples/authenticated-route) and [payment/lifecycle](./examples/payments-and-lifecycle) examples.
+
+## Public entry points
+
+| Import | Use it for |
+| --- | --- |
+| `@dvmkit/sdk` | DVM descriptors, handler context, bundled Zod, pricing, signing and safe-fetch helpers |
+| `@dvmkit/sdk/server` | Node hosting, Postgres stores, signed-request auth, compatibility gates and payment infrastructure |
+| `@dvmkit/sdk/testing` | Deterministic handler contexts and in-memory stores |
+
+The generated [API reference](./docs/API.md) lists every declaration under these three entries. Deep imports from `dist/` are unsupported.
+
+## Verified payments in development
+
+`serve()` returns a `paymentModes` snapshot describing whether each configured rail is verifying, unavailable, or absent. A priced development server skips verification only when it has no configured payment rail. Configuring an unusable rail fails closed instead of turning the request into a synthetic development payment.
+
+Cashu development without Postgres is limited to known test or loopback mints. It uses a fresh lock identity and process-local accounting on every boot, so proofs, balances, and jobs do not survive restart. Production Cashu remains PostgreSQL-backed. Both paths require valid mint-provided NUT-12 DLEQ evidence on every proof before accepting its value; older tokens without that evidence must be replaced with fresh tokens from a compatible mint.
+
+Builders can pass `onPaidJobCompleted` to observe settled customer charges after successful completion. The event contains `jobId`, verified rail, checked integer `amountMicro`, the credit currency, and whether configuration identifies test funds. Reconciliation can repeat an event, so consumers deduplicate by `jobId`. Free jobs, synthetic development payments, failed jobs, and released draws do not emit.
+
+## Production next steps
+
+- Use Postgres through `DATABASE_URL`; production boot refuses an in-memory job store unless you deliberately supply another durable implementation.
+- Add `auth: secp256k1Auth()` for caller-owned state. The host automatically uses a Postgres replay store when one is available; a per-process replay window is unsafe across replicas.
+- Configure only the rails you operate: Cashu, x402, and Tempo are job payment methods. Lightning is a receive-only prepaid-credit funding leg. Keep every private key, wallet connection, and platform token in your secret store rather than source.
+- A `credit` block opts into reusable prepaid balances and their reclaim obligations. Reusable channels return undrawn collateral through their channel lifecycle; one-payment stablecoin funding is disabled unless `allowOneShotStablecoin: true` because it creates manual refunds. Run and monitor the documented reclaim/payout worker.
+- Honour `ctx.signal`, use `ctx.fetch` for abortable provider calls, and declare provider cost with `ctx.cost` only after the durable step that incurred it.
+
+The public [SDK guide](https://dvmkit.com/docs/sdk) covers signed requests, custom routes, rail configuration, credit reclaim, persistence, and deployment in depth. The [protocol guide](https://dvmkit.com/docs/protocol) specifies the HTTP contract.
+
+## Repository development
+
+Use the Node.js release in `.nvmrc` (Node 22). Install with `npm ci`, then run the same gate CI runs with `npm run verify`. The gate checks repository metadata in the checkout, copies only tracked and unignored source into an isolated directory, installs its locked dependencies, and runs lint, build, typecheck (including the release scripts under `checkJs`), unit and database tests, API, package, consumer, packed-artifact safety, and release checks there. The clean source tree owns the complete build and test pass, so verification never depends on the checkout's `node_modules` or pre-existing `dist` and does not repeat the full suite; after every check passes, its verified `dist` replaces the checkout's build output for release packaging.
 
 `DATABASE_URL` is optional locally. Without it the database suite is skipped rather than passed, and `verify` says so in its summary, because a skipped suite verified nothing and must not be reported as green. Point `DATABASE_URL` at a scratch Postgres to run it, and pass `npm run verify -- --require-database` to make a missing one a failure, which is what CI does.
 
-The public surface is exactly `@dvmkit/sdk`, `@dvmkit/sdk/server`, and `@dvmkit/sdk/testing`. There is a fourth entry point, `@dvmkit/sdk/internal`, which is not part of it; see below. Documentation is at [dvmkit.ai](https://dvmkit.ai/docs/sdk).
+The public surface is exactly `@dvmkit/sdk`, `@dvmkit/sdk/server`, and `@dvmkit/sdk/testing`.
 
 ## Compatibility and versioning
 
 This is pre-1.0 alpha software and the promises match that. Breaking changes can land in any release, they are announced in the release notes for the release that carries them, and there is no long-term support release. Security fixes are made on the latest published release rather than backported.
 
-The public surface is exactly three entry points: `@dvmkit/sdk`, `@dvmkit/sdk/server`, and `@dvmkit/sdk/testing`. Nothing reachable only through a deep path into `dist/` is public, nothing under `@dvmkit/sdk/internal` is public, and `npm run check:api` pins every exported declaration name against `api-surface.json`, so a change to that surface is a deliberate, reviewed act rather than a side effect.
+Nothing reachable only through a deep path into `dist/` is public. `npm run check:api` pins every exported declaration name against `api-surface.json` and the generated API reference, so a change to the supported surface is a deliberate, reviewed act rather than a side effect.
 
-Wire compatibility with callers is separate from the package version and is declared per endpoint. A server built on this SDK answers `DVM-Protocol-Version: 1`, and an individual endpoint may require a set of named capability tokens the caller advertises, a minimum caller version, or both. Capability tokens are additive, so an endpoint that declares no requirement stays reachable by a caller that sends no compatibility headers at all. A caller that cannot meet what an endpoint declares gets HTTP 426 naming the required capabilities and, where one is declared, the minimum version. The protocol is specified at [dvmkit.ai/docs/protocol](https://dvmkit.ai/docs/protocol).
+Wire compatibility with callers is separate from the package version and is declared per endpoint. A server built on this SDK answers `DVM-Protocol-Version: 1`, and an individual endpoint may require a set of named capability tokens the caller advertises, a minimum caller version, or both. Capability tokens are additive, so an endpoint that declares no requirement stays reachable by a caller that sends no compatibility headers at all. A caller that cannot meet what an endpoint declares gets HTTP 426 naming the required capabilities and, where one is declared, the minimum version. The protocol is specified at [dvmkit.com/docs/protocol](https://dvmkit.com/docs/protocol).
 
 ## Job credentials
 
@@ -34,13 +126,28 @@ The same values are accepted as `--endpoint <url>` and `--job-token <hex>`. Thes
 
 If an upgrade broke something for you, an [API compatibility report](https://github.com/dvmkit/sdk/issues/new/choose) is the most useful thing you can send us. It tells us which parts of the published surface people actually build on, which no test of ours can.
 
-## Internal entry point
+## Per-job costs
+
+A handler can declare what a job cost **you**, the builder, to serve — a vendor API call, a GPU minute, a per-request licence fee — and the SDK reports it to the platform alongside what the caller paid, so your dashboard can state a margin instead of guessing at one.
+
+```ts
+const transcript = await ctx.step("transcribe", async () => {
+  const result = await whisper(audio);
+  ctx.cost({ amount: result.seconds * 0.0001, currency: "usd" });
+  return result;
+});
+ctx.artifact({ mime_type: "text/plain", data: transcript.text });
+```
+
+`amount` is in whole currency units, like every other money figure you hand the SDK. Call it once per cost you incur; the declarations for one job are summed, and only the total is rounded, to a millionth of a unit. That ordering is what makes fine-grained declarations safe: a per-token charge of $0.0000003 is below the reported resolution on its own, but a thousand of them still add up to $0.0003 rather than to nothing. Every call in a job must name the same currency.
 
-`@dvmkit/sdk/internal` exists for one consumer: the dvmkit platform, which runs on this source instead of keeping a fork of it. Do not build on it.
+Three things worth knowing:
 
-It carries no stability promise of any kind. A name under it can change meaning, change signature, or disappear in any release, including a patch release, and that is not a breaking change: it needs no `!` marker, no `BREAKING CHANGE:` footer, and no note in the release notes. It is not documented, its contents track what the platform happens to need, and it is excluded from everything the three public entry points promise above.
+- **Declaring nothing is not declaring zero.** A job whose handler never calls `ctx.cost` reports no cost at all, and the dashboard says the margin is unknown rather than showing it as 100%. `ctx.cost({ amount: 0, currency: "usd" })` is how you say a job genuinely cost you nothing.
+- **Declare the cost where you incur it, including inside `ctx.step`.** The step cache carries those declarations with the result and applies them once when a replay skips the body.
+- **Every terminal job reports its declared cost.** A paid completion carries the cost on its revenue report. A free completion, failure, or cancellation sends a separate cost-only report and does not create revenue.
 
-The names in it are still pinned in `api-surface.json`, so a change to them is visible in review rather than silent; the pin records what moved, it does not promise that it will not move. If something under `./internal` is genuinely useful to a third party, the way to get it is to ask for it: graduating a name to `.`, `./server` or `./testing` is a deliberate, reviewed `feat`, and only then does it acquire the compatibility promises on this page.
+The cost is yours, never the caller's: it is recorded separately from what the caller paid and is never netted against it. Both report shapes use the same durable outbox. Cost-only reports are keyed on the job id and revisioned, so retries and cross-machine updates converge on the latest cumulative value. With the Postgres job store, boot-time and periodic reconciliation enqueue any terminal cost revision that a process exited before reporting.
 
 ## Contributing
 

package/dist/{chunk-ANFX5HEG.js → chunk-2UUXIIOC.js}

@@ -2,7 +2,7 @@ import {
   isValidEvmPrivateKey,
   loadConfig,
   updateConfig
-} from "./chunk-TSWKITGR.js";
+} from "./chunk-CGKZDODG.js";
 import {
   DvmError,
   resolveRpcHttpTransportOptions,
@@ -16,8 +16,24 @@ import {
 // src/lib/payment-rails/tempo-wallet.ts
 var TEMPO_USDC_MAINNET = "0x20C000000000000000000000b9537d11c60E8b50";
 var TEMPO_CHAIN_ID = 4217;
-function resolveTempoAsset(env = process.env) {
-  const address = env.DVM_TEMPO_CURRENCY ?? TEMPO_USDC_MAINNET;
+var TEMPO_MODERATO_CHAIN_ID = 42431;
+var TEMPO_PATH_USD_MODERATO = "0x20c0000000000000000000000000000000000000";
+var TEMPO_MODERATO_RPC = "https://rpc.moderato.tempo.xyz";
+function resolveTempoNetwork(network = "mainnet") {
+  return network === "moderato" ? {
+    network,
+    chainId: TEMPO_MODERATO_CHAIN_ID,
+    rpcUrl: TEMPO_MODERATO_RPC,
+    defaultToken: TEMPO_PATH_USD_MODERATO
+  } : {
+    network,
+    chainId: TEMPO_CHAIN_ID,
+    rpcUrl: "https://rpc.tempo.xyz",
+    defaultToken: TEMPO_USDC_MAINNET
+  };
+}
+function resolveTempoAsset(env = process.env, network = "mainnet") {
+  const address = env.DVM_TEMPO_CURRENCY ?? resolveTempoNetwork(network).defaultToken;
   if (!HEX_ADDRESS_RE.test(address)) {
     throw new DvmError(
       "tempo_config_invalid",
@@ -58,7 +74,9 @@ function tempoWrongAssetHint(asset) {
   return `This rail settles only in ${asset.label} (${asset.address}) on Tempo. Another Tempo dollar \u2014 USDT0 or any other stablecoin \u2014 is a different contract and will never show up here, however much of it your wallet says you hold. If you funded with the wrong one, swap it to ${asset.label} on Tempo (an on-chain swap, fees are sub-cent) or send ${asset.label} to this address.`;
 }
 function tempoTokenSymbol(address) {
-  return address.toLowerCase() === TEMPO_USDC_MAINNET.toLowerCase() ? "USDC.e" : null;
+  if (address.toLowerCase() === TEMPO_USDC_MAINNET.toLowerCase()) return "USDC.e";
+  if (address.toLowerCase() === TEMPO_PATH_USD_MODERATO.toLowerCase()) return "pathUSD";
+  return null;
 }
 var HEX_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
 async function connectedTempoAccount() {
@@ -83,7 +101,7 @@ async function generateTempoKey(opts = {}) {
     );
   }
   if (existing && opts.force) {
-    const { assertTempoWalletIdle } = await import("./tempo-lifecycle-SQL3KLEZ.js");
+    const { assertTempoWalletIdle } = await import("./tempo-lifecycle-DFIXQ54Q.js");
     await assertTempoWalletIdle("replace");
   }
   const { privateKeyToAccount, generatePrivateKey } = await import("viem/accounts");
@@ -91,22 +109,30 @@ async function generateTempoKey(opts = {}) {
   const account = privateKeyToAccount(privateKey);
   const generated = {
     privateKey,
-    address: account.address.toLowerCase()
+    address: account.address.toLowerCase(),
+    network: opts.network ?? "mainnet"
   };
   await opts.beforePersist?.(generated);
   await updateConfig({
     reason: "tempo_wallet_generate",
-    patch: () => ({ set: { tempo: { method: "tempo", apiKey: privateKey } } })
+    patch: () => ({
+      set: {
+        tempo: { method: "tempo", apiKey: privateKey, network: generated.network }
+      }
+    })
   });
   return generated;
 }
 async function getTempoUsdcBalance(account) {
-  const tokenAddress = resolveTempoAsset().address;
+  const accountNetwork = account.network ?? "mainnet";
+  const network = resolveTempoNetwork(accountNetwork);
+  const tokenAddress = resolveTempoAsset(process.env, accountNetwork).address;
   const { createPublicClient, http, erc20Abi } = await import("viem");
-  const { tempo } = await import("viem/chains");
+  const { tempo, tempoModerato } = await import("viem/chains");
+  const chain = accountNetwork === "moderato" ? tempoModerato : tempo;
   const { url: rpcUrl, source: rpcSource } = resolveRpcOverride(
     process.env.DVM_TEMPO_RPC_URL,
-    tempo.rpcUrls.default.http[0]
+    network.rpcUrl
   );
   try {
     const transportOptions = resolveRpcHttpTransportOptions(
@@ -114,7 +140,7 @@ async function getTempoUsdcBalance(account) {
       process.env.DVM_TEMPO_RPC_HEADERS_JSON
     );
     const client = createPublicClient({
-      chain: tempo,
+      chain,
       transport: transportOptions ? http(rpcUrl, transportOptions) : http(rpcUrl)
     });
     const raw = await client.readContract({
@@ -128,7 +154,7 @@ async function getTempoUsdcBalance(account) {
       rawBaseUnits: raw,
       usdc: Number(raw) / 1e6,
       tokenAddress,
-      chainId: TEMPO_CHAIN_ID,
+      chainId: network.chainId,
       // internal-review: redacted here rather than at a display surface, so the clear
       // endpoint never leaves this function on the success path either.
       rpcUrlRedacted: redactUrl(rpcUrl),
@@ -160,7 +186,7 @@ async function tempoAccountFromConfig(config) {
   if (!apiKey || !isValidEvmPrivateKey(apiKey)) return null;
   const privateKey = apiKey;
   const address = await deriveTempoAddress(privateKey);
-  return { privateKey, address };
+  return { privateKey, address, network: config.tempo.network ?? "mainnet" };
 }
 function invalidTempoPrivateKey() {
   return new DvmError(
@@ -173,6 +199,10 @@ function invalidTempoPrivateKey() {
 export {
   TEMPO_USDC_MAINNET,
   TEMPO_CHAIN_ID,
+  TEMPO_MODERATO_CHAIN_ID,
+  TEMPO_PATH_USD_MODERATO,
+  TEMPO_MODERATO_RPC,
+  resolveTempoNetwork,
   resolveTempoAsset,
   tempoTokenLabel,
   tempoTokenReference,

package/dist/{chunk-C6JHBLMW.js → chunk-BIP6G74V.js}

@@ -10,7 +10,7 @@ import {
   isValidEvmPrivateKey,
   loadConfig,
   updateConfig
-} from "./chunk-TSWKITGR.js";
+} from "./chunk-CGKZDODG.js";
 import {
   X402_DEFAULT_NETWORK,
   X402_V1_VERSION,

package/dist/{chunk-EPNDZ5DH.js → chunk-CEOAHV2I.js}

@@ -2,34 +2,6 @@ import {
   callerLoggers
 } from "./chunk-66HGCPBU.js";
 
-// src/lib/mints.ts
-var RECOMMENDED_MINTS = [
-  {
-    name: "Testnut",
-    description: "Cashu test mint \u2014 use for testing only, not real funds",
-    url: "https://testnut.cashu.space"
-  },
-  {
-    name: "Voltz Mint",
-    description: "Production Cashu mint by the Voltz Wallet team",
-    url: "https://mint.lnvoltz.com"
-  }
-];
-function isTestMintUrl(url) {
-  let host;
-  try {
-    host = new URL(url).hostname.toLowerCase();
-  } catch {
-    return false;
-  }
-  if (host.startsWith("[") && host.endsWith("]")) host = host.slice(1, -1);
-  if (LOOPBACK_HOSTS.has(host)) return true;
-  if (host.endsWith(".localhost")) return true;
-  return TEST_MINT_HOSTS.has(host);
-}
-var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "0.0.0.0", "::1"]);
-var TEST_MINT_HOSTS = /* @__PURE__ */ new Set(["testnut.cashu.space"]);
-
 // src/lib/x402/env.ts
 import { isAddress } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
@@ -981,8 +953,6 @@ var NwcBackend = class {
 };
 
 export {
-  RECOMMENDED_MINTS,
-  isTestMintUrl,
   X402_SELF_RELAY_KEY,
   X402_RECEIVER_AUTHORIZER_KEY,
   X402_BATCH_SETTLEMENT_KEY,

package/dist/{chunk-TSWKITGR.js → chunk-CGKZDODG.js}

@@ -181,6 +181,13 @@ function assertValidConfig(config, fields) {
     const value = owner[leaf];
     if (value === void 0 || !matchesKind(value, kind)) throw invalidFieldError(path, kind);
   }
+  if ((!scope || scope.has("tempo")) && isPlainObject(record.tempo) && record.tempo.network !== void 0 && record.tempo.network !== "mainnet" && record.tempo.network !== "moderato") {
+    throw new DvmError(
+      "config_invalid",
+      `The caller configuration field 'tempo.network' must be 'mainnet' or 'moderato'.`,
+      `Correct tempo.network in ${CONFIG_FILE}.${rollbackSuffix()}`
+    );
+  }
 }
 function readRawConfig() {
   if (!existsSync(CONFIG_FILE)) return null;
@@ -308,7 +315,7 @@ var PROTECTED_FIELDS = {
 var CONFIG_PATH_SHAPE = {
   float: { statedBudget: {}, connectedAt: {}, alias: {}, methods: {} },
   x402: { privateKey: {}, network: {} },
-  tempo: { method: {}, accountId: {}, apiKey: {} },
+  tempo: { method: {}, accountId: {}, apiKey: {}, network: {} },
   credit: {
     targetJobs: {},
     posture: {},

package/dist/{chunk-YDIYXGYL.js → chunk-E4EVGPDX.js}

@@ -11,24 +11,31 @@ var StepCache = class _StepCache {
   }
   /** Get a cached step result. Throws if not present. */
   get(id) {
-    if (!this.cache.has(id)) {
-      throw new Error(`StepCache: no cached result for step "${id}"`);
-    }
-    return this.cache.get(id);
+    return this.getRecord(id).value;
+  }
+  /** Get a cached step record, including replay metadata. Throws if not present. */
+  getRecord(id) {
+    const record = this.cache.get(id);
+    if (record === void 0) throw new Error(`StepCache: no cached result for step "${id}"`);
+    return record;
   }
   /** Cache a step result. */
-  set(id, value) {
-    this.cache.set(id, value);
+  set(id, value, costs) {
+    this.cache.set(id, {
+      id,
+      value,
+      ...costs !== void 0 && costs.length > 0 ? { costs: costs.map(({ amount, currency }) => ({ amount, currency })) } : {}
+    });
   }
   /** Export all cached steps for persistence. */
   serialize() {
-    return [...this.cache.entries()].map(([id, value]) => ({ id, value }));
+    return [...this.cache.values()];
   }
   /** Restore a StepCache from persisted records. */
   static deserialize(records) {
     const cache = new _StepCache();
-    for (const { id, value } of records) {
-      cache.set(id, value);
+    for (const { id, value, costs } of records) {
+      cache.set(id, value, costs);
     }
     return cache;
   }

package/dist/{chunk-NFRM5QYP.js → chunk-EVBK675R.js}

@@ -6,6 +6,7 @@ import {
 import { randomUUID } from "crypto";
 var ENDPOINTS = {
   revenue: "/_internal/job-revenue",
+  cost: "/_internal/job-cost",
   deposit: "/_internal/credit-deposit",
   release: "/_internal/credit-draw-release",
   drain: "/_internal/credit-drain",
@@ -129,6 +130,10 @@ var RevenueReporter = class _RevenueReporter {
   async report(payload) {
     return this.enqueue("revenue", payload, payload.jobId);
   }
+  /** Persist a zero-revenue job cost and attempt immediate delivery. */
+  async reportCost(payload) {
+    return this.enqueue("cost", payload, payload.jobId);
+  }
   /**
    * Join a credit deposit to the caller-owned rail transaction.
    *

package/dist/{chunk-DBCLBYHP.js → chunk-KVEHHC7W.js}

@@ -19,7 +19,7 @@ import {
 
 // src/sdk/server/memory-credit-ledger.ts
 import { randomUUID } from "crypto";
-var MemoryCreditLedger = class {
+var MemoryCreditLedger = class _MemoryCreditLedger {
   /**
    * Per-process and lost on restart, so a DVM backed by this ledger never
    * advertises the funding menu outside devMode (internal-review) — funding on one
@@ -32,6 +32,16 @@ var MemoryCreditLedger = class {
   tempoLosses = /* @__PURE__ */ new Map();
   x402Losses = /* @__PURE__ */ new Map();
   x402Settlements;
+  /** Internal disposable transaction snapshot. The caller must serialize every ledger access. */
+  forkForTransaction() {
+    const fork = new _MemoryCreditLedger();
+    for (const name of ["credits", "fundings", "invoices", "tempoLosses", "x402Losses"]) {
+      const target = fork[name];
+      for (const [key, value] of this[name]) target.set(key, structuredClone(value));
+    }
+    fork.x402Settlements = this.x402Settlements;
+    return fork;
+  }
   /** See {@link CreditLedger.useX402SettlementGate} — same contract (internal-review). */
   useX402SettlementGate(gate) {
     this.x402Settlements = gate;

package/dist/{chunk-2K7E3N2D.js → chunk-KXCKFIJI.js}

@@ -29,6 +29,34 @@ function isX402SettlementReconciliationReason(value) {
   return value === "settlement_not_on_chain" || value === "chain_unreachable" || value === "settlement_unbookmarked" || value === "facilitator_channel_state_unavailable";
 }
 
+// src/lib/mints.ts
+var RECOMMENDED_MINTS = [
+  {
+    name: "Coinos",
+    description: "Primary Cashu mint accepted by dvmkit DVMs",
+    url: "https://mint.coinos.io"
+  },
+  {
+    name: "Voltz Mint",
+    description: "Fallback Cashu mint accepted by dvmkit DVMs",
+    url: "https://mint.lnvoltz.com"
+  }
+];
+function isTestMintUrl(url) {
+  let host;
+  try {
+    host = new URL(url).hostname.toLowerCase();
+  } catch {
+    return false;
+  }
+  if (host.startsWith("[") && host.endsWith("]")) host = host.slice(1, -1);
+  if (LOOPBACK_HOSTS.has(host)) return true;
+  if (host.endsWith(".localhost")) return true;
+  return TEST_MINT_HOSTS.has(host);
+}
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "0.0.0.0", "::1"]);
+var TEST_MINT_HOSTS = /* @__PURE__ */ new Set(["testnut.cashu.space", "dvmkit-testmint.fly.dev"]);
+
 // src/lib/secret-backup.ts
 import { existsSync, readFileSync, writeFileSync } from "fs";
 function backupSecretFile(file, nextContent) {
@@ -162,7 +190,7 @@ var LOCK_FILE = `${WALLET_FILE}.lock`;
 var DEFAULT_LOCK_STALE_MS = 3e4;
 var DEFAULT_LOCK_RETRIES = 30;
 var DEFAULT_LOCK_RETRY_INTERVAL_MS = 1e3;
-var WALLET_VERSION = 8;
+var WALLET_VERSION = 9;
 var RECENT_SPENDS_CAP = 10;
 var DEFAULT_AGENT_MINT_URL = "https://mint.coinos.io";
 function loadAgentWallet() {
@@ -187,37 +215,54 @@ function loadAgentWallet() {
   }
   const version = parsed.version;
   if (version === 1) {
-    return migrateV7ToV8(
-      migrateV6ToV7(migrateV5ToV6(migrateV4ToV5(migrateV1ToV4(parsed))))
+    return migrateV8ToV9(
+      migrateV7ToV8(
+        migrateV6ToV7(
+          migrateV5ToV6(migrateV4ToV5(migrateV1ToV4(parsed)))
+        )
+      )
     );
   }
   if (version === 2) {
-    return migrateV7ToV8(
-      migrateV6ToV7(
-        migrateV5ToV6(
-          migrateV4ToV5(migrateV3ToV4(migrateV2ToV3(parsed)))
+    return migrateV8ToV9(
+      migrateV7ToV8(
+        migrateV6ToV7(
+          migrateV5ToV6(
+            migrateV4ToV5(migrateV3ToV4(migrateV2ToV3(parsed)))
+          )
         )
       )
     );
   }
   if (version === 3) {
-    return migrateV7ToV8(
-      migrateV6ToV7(migrateV5ToV6(migrateV4ToV5(migrateV3ToV4(parsed))))
+    return migrateV8ToV9(
+      migrateV7ToV8(
+        migrateV6ToV7(
+          migrateV5ToV6(migrateV4ToV5(migrateV3ToV4(parsed)))
+        )
+      )
     );
   }
   if (version === 4) {
-    return migrateV7ToV8(
-      migrateV6ToV7(migrateV5ToV6(migrateV4ToV5(parsed)))
+    return migrateV8ToV9(
+      migrateV7ToV8(
+        migrateV6ToV7(migrateV5ToV6(migrateV4ToV5(parsed)))
+      )
     );
   }
   if (version === 5) {
-    return migrateV7ToV8(migrateV6ToV7(migrateV5ToV6(parsed)));
+    return migrateV8ToV9(
+      migrateV7ToV8(migrateV6ToV7(migrateV5ToV6(parsed)))
+    );
   }
   if (version === 6) {
-    return migrateV7ToV8(migrateV6ToV7(parsed));
+    return migrateV8ToV9(migrateV7ToV8(migrateV6ToV7(parsed)));
   }
   if (version === 7) {
-    return migrateV7ToV8(parsed);
+    return migrateV8ToV9(migrateV7ToV8(parsed));
+  }
+  if (version === 8) {
+    return migrateV8ToV9(parsed);
   }
   if (version !== WALLET_VERSION) {
     throw new DvmError(
@@ -366,6 +411,22 @@ function migrateV6ToV7(parsed) {
   };
 }
 function migrateV7ToV8(parsed) {
+  return {
+    version: 8,
+    lock_privkey: String(parsed.lock_privkey),
+    lock_pubkey: String(parsed.lock_pubkey),
+    mnemonic_fingerprint: typeof parsed.mnemonic_fingerprint === "string" ? parsed.mnemonic_fingerprint : null,
+    mints: Array.isArray(parsed.mints) ? parsed.mints : [],
+    proofs: Array.isArray(parsed.proofs) ? parsed.proofs : [],
+    nut13_counters: isCounterMap(parsed.nut13_counters) ? parsed.nut13_counters : {},
+    pending_mints: Array.isArray(parsed.pending_mints) ? parsed.pending_mints : [],
+    pending_melts: Array.isArray(parsed.pending_melts) ? parsed.pending_melts : [],
+    pending_submissions: Array.isArray(parsed.pending_submissions) ? parsed.pending_submissions : [],
+    recent_spends: Array.isArray(parsed.recent_spends) ? parsed.recent_spends : [],
+    created_at: typeof parsed.created_at === "string" ? parsed.created_at : (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function migrateV8ToV9(parsed) {
   return {
     version: WALLET_VERSION,
     lock_privkey: String(parsed.lock_privkey),
@@ -1633,6 +1694,8 @@ export {
   verifyCashuToken,
   normaliseMintUrl,
   TEMPO_SESSION_UPDATED_REASON,
+  RECOMMENDED_MINTS,
+  isTestMintUrl,
   backupSecretFile,
   readAgentMnemonic,
   assertAgentMnemonicReplaceable,