@dvmkit/dvmctl 0.3.4-rc.1 → 0.4.0-rc.2

package/skills/build-dvm/references/patterns-auth.md

@@ -1,390 +0,0 @@
-## Patterns
-
-### Single-turn (simplest)
-
-```typescript
-import { configureDVM } from "@dvmkit/sdk";
-
-export default configureDVM({
-  name: "Uppercase",
-  capability: "uppercase",
-  tags: ["text"],
-
-  onJob(ctx) {
-    ctx.complete(ctx.input.toUpperCase());
-  },
-});
-```
-
-### Multi-turn linear
-
-```typescript
-import { configureDVM } from "@dvmkit/sdk";
-
-export default configureDVM({
-  name: "Translator",
-  capability: "translate",
-  tags: ["translation"],
-  price: "$0.02",
-  state: { detectedLanguage: "", targetLanguage: "" },
-
-  async onJob(ctx) {
-    const detected = await ctx.step("detect", async () => detectLanguage(ctx.input));
-    ctx.state.detectedLanguage = detected;
-    ctx.text(`Detected: ${detected}`);
-
-    const lang = await ctx.prompt("target-lang", `Translate to?`, {
-      options: ["Spanish", "French", "German"],
-    });
-    ctx.state.targetLanguage = lang.text;
-
-    ctx.text(`Translating to ${lang.text}...`);
-    const result = await ctx.step("translate", async () => translate(ctx.input, lang.text));
-
-    ctx.artifact({ data: result, mime_type: "text/plain" });
-    ctx.complete(`Translated to ${lang.text}`);
-  },
-});
-```
-
-### Event-driven (complex routing)
-
-```typescript
-import { configureDVM } from "@dvmkit/sdk";
-
-export default configureDVM({
-  name: "Translator",
-  capability: "translate",
-  tags: ["translation"],
-  state: { original: "" },
-
-  onJob(ctx) {
-    ctx.state.original = ctx.input;
-    ctx.prompt("lang", "What language?", {
-      options: ["Spanish", "French", "German"],
-    });
-  },
-
-  async onResponse(ctx, content) {
-    const result = await translate(ctx.state.original, content.text);
-    ctx.complete(result);
-  },
-});
-```
-
-### Multi-capability DVM (cast's pattern)
-
-When several related operations share resources (a Postgres pool, an auth verifier, an S3
-bucket), declare them as capabilities on one DVM instead of mounting separate DVMs. This is what
-cast does — a podcast-feed DVM with one descriptor-level auth scheme covering four capabilities:
-
-```typescript
-import { configureDVM } from "@dvmkit/sdk";
-import { secp256k1Auth } from "@dvmkit/sdk/server";
-
-import { addEpisodeSchema, deleteEpisodeSchema, updateFeedSchema } from "./types";
-
-export function createCastDVM(runtime: CastRuntime) {
-  return configureDVM({
-    name: "cast",
-    description: "Host RSS feeds and episodes for podcast distribution",
-    tags: ["podcast", "rss", "feed", "audio"],
-    idleTimeout: 1800,
-
-    // Descriptor-level auth: one scheme gates every capability (see below).
-    auth: secp256k1Auth({ replayStore: runtime.replays, driftSeconds: 300 }),
-
-    onBoot(env) {
-      // validate env; runtime is already built by the time we reach here
-    },
-
-    capabilities: {
-      "add-episode": {
-        description: "Add an episode to a private RSS feed by audio URL",
-        input: addEpisodeSchema,
-        onQuote: {
-          schema: addEpisodeSchema,
-          handler: async (ctx) => quoteAddEpisode(ctx, runtime),
-        },
-        async onJob(ctx) {
-          await runAddEpisodeJob(ctx, runtime);
-        },
-      },
-
-      "update-feed": {
-        description: "Update per-feed metadata",
-        input: updateFeedSchema,
-        async onJob(ctx) {
-          await runUpdateFeedJob(ctx, runtime);
-        },
-      },
-
-      "delete-episode": {
-        description: "Delete a single episode",
-        input: deleteEpisodeSchema,
-        async onJob(ctx) {
-          await runDeleteEpisodeJob(ctx, runtime);
-        },
-      },
-    },
-
-    routes(app, { authAudience }) {
-      // see "Custom HTTP routes" below
-    },
-  });
-}
-```
-
-Callers target a capability by passing `capability: "add-episode"` on the job submission; the
-wire (`POST /v1/job`) always carries the capability name. Each capability has its own input
-schema, pricing, and quote handler; the DVM-level `auth`, `paymentMethods`, and `routes` are
-shared.
-
-### Stateful DVM — signed-request auth
-
-When a DVM owns persistent state (feeds, accounts, subscriptions) and must verify the caller owns
-the resource being acted on, require **signed requests**. Signatures are **secp256k1 with BIP-340
-Schnorr** over a versioned statement containing the exact input plus the attested DVM audience, HTTP method, concrete path, and capability, with timestamp-drift and replay protection. A proof for one DVM or operation cannot be replayed against another. This is a protocol invariant — caller auth and builder identity are always
-secp256k1+Schnorr via `@noble/curves`, never Ed25519 or another curve. Don't introduce other
-curves into auth/identity paths.
-
-The schema must include the envelope fields `pubkey`, `signature`, `timestamp`, `nonce` alongside the operation's payload fields. `auth_statement` is protocol-owned and the SDK removes it before builder schema parsing:
-
-```typescript
-import { z } from "@dvmkit/sdk";
-
-const addEpisodeSchema = z.object({
-  // payload
-  feed_id: z.string(),
-  audio_url: z.string().url(),
-  // envelope (the SDK verifies these)
-  pubkey: z.string(),
-  signature: z.string(),
-  timestamp: z.number().int(),
-  nonce: z.string(),
-});
-```
-
-**What gets verified is the raw wire body**, on `/v1/quote`, on the `/v1/job` submit and on the
-cross-machine reactivation re-verify alike (`signedRequestInput`, — never the
-Zod-parsed input. So your schema is free to fill defaults at any depth, coerce, or transform: the
-parse shapes what the handler receives, not what the signature covers. The one thing that must
-match is the wire body itself, which is why a client signs the payload it is about to send rather
-than a normalised copy of it.
-
-#### Canonical pattern — `auth: secp256k1Auth({...})` at descriptor level
-
-For most stateful DVMs, declare auth on the descriptor (shown in the cast example above). The SDK
-then publishes `secp256k1-schnorr-v2` plus its attested `auth_audience` on `/v1/info`, and rejects unsigned / stale / replayed or wrong-domain envelopes with HTTP 401 **before payment is taken or any
-handler runs**, and records the replay nonce only after upfront payment verifies,
-. Inside the handler, the verified caller identity is on `ctx.auth`:
-
-```typescript
-import { secp256k1Auth } from "@dvmkit/sdk/server";
-
-// auth: secp256k1Auth({
-//   replayStore: runtime.replays,   // omit for the bounded in-memory FIFO default
-//   driftSeconds: 300,              // ±5 min clock drift (default)
-// }),
-
-async onJob(ctx) {
-  // The envelope is already verified. ctx.auth.pubkey is the trusted caller key;
-  // ctx.auth.envelope holds the parsed payload, so no re-parsing is needed.
-  const pubkey = ctx.auth!.pubkey;
-  const { feed_id } = ctx.auth!.envelope as { feed_id: string };
-
-  if (!(await runtime.db.ownsFeed(pubkey, feed_id))) {
-    ctx.fail("auth_error: caller does not own this feed");
-    return;
-  }
-  // ...
-}
-```
-
-`replayStore` accepts a `PostgresReplayStore` (cross-instance, also from `@dvmkit/sdk/server`);
-omit it for a bounded in-memory FIFO default suitable for single-instance DVMs.
-
-#### Lower-level primitive — `createSignedRequestVerifier`
-
-When you need hands-on control on a custom route, use the verifier directly. The SDK passes the resolved audience to `routes(app, context)`; combine it with the live request method and URL so mount prefixes remain covered. The descriptor-level `secp256k1Auth` is built on the same primitive.
-
-```typescript
-import { createSignedRequestVerifier, SignedRequestError } from "@dvmkit/sdk/server";
-
-const verifier = createSignedRequestVerifier(addEpisodeSchema, {
-  driftSeconds: 300,          // ±5 min clock drift (default)
-  replayStore: replays,       // pass null to disable replay protection
-});
-
-routes(app, { authAudience }) {
-  if (!authAudience) throw new Error("signed route requires descriptor auth");
-  app.post("/private/feed", async (c) => {
-  try {
-    // Two-step: `checkAuth` is sync — schema → drift → signature.
-    // `recordReplay` is async — commits the nonce, throws on duplicate. Split
-    // so validation does not burn a nonce before the operation is accepted.
-    const signed = verifier.checkAuth(await c.req.json(), {
-      audience: authAudience,
-      method: c.req.method,
-      path: new URL(c.req.url).pathname,
-      capability: null,
-    });
-    await verifier.recordReplay(signed);
-    // signed.pubkey is now trusted — use it for ownership checks
-    if (!(await runtime.db.ownsFeed(signed.pubkey, signed.feed_id))) {
-      return c.json({ error: "auth_error" }, 401);
-    }
-    // ...
-  } catch (err) {
-    if (err instanceof SignedRequestError) {
-      return c.json({ error: "auth_error", sub_reason: err.sub_reason }, 401);
-    }
-    throw err;
-  }
-  });
-}
-```
-
-`verifier.checkAuth(input, domain)` returns the parsed input typed as `T & CanonicalEnvelope` on success
-and throws `SignedRequestError` (`sub_reason`: `schema_invalid` | `timestamp_drift` |
-`signature_invalid`). `verifier.recordReplay(envelope)` commits the nonce and throws
-`SignedRequestError` (`replay_detected`) on a duplicate. Pair them with your own error taxonomy
-for a domain-specific error code (cast wraps both as `auth_error`).
-
-In `onQuote` (and the 402-discovery hop), call `checkAuth` only — skip `recordReplay`. The caller creates a separate `/v1/job` proof because method/path/capability are signed; quote and submit never reuse a proof.
-
-`verifier.signRequest(privkey, body, opts?, domain)` is the matching client-side primitive — useful for
-round-trip tests that exercise the real crypto path:
-
-```typescript
-import { schnorr } from "@noble/curves/secp256k1.js";
-
-const { secretKey } = schnorr.keygen();
-const signed = verifier.signRequest(secretKey, {
-  feed_id: "morning-news",
-  audio_url: "https://example.com/episode-1.mp3",
-}, undefined, {
-  audience: authAudience,
-  method: "POST",
-  path: "/private/feed",
-  capability: null,
-});
-// signed.pubkey, signed.signature, signed.timestamp, signed.nonce are filled in.
-```
-
-### Refund-on-failure policy
-
-A failed job never debits — the draw is released, on every rail, with nothing to wire (see
-[Prepaid credit](pricing-credit.md#prepaid-credit)). `{ refund: true }` is a separate annotation recording that the failure
-was the caller's fault; the first-party DVMs all key it off an `OPERATOR_FAULT_CODES` set:
-
-```typescript
-const refund = !OPERATOR_FAULT_CODES.has(err.code) ? { refund: true } : undefined;
-ctx.fail(`[${err.code}] ${err.hint}`, refund);
-```
-
-Keep annotating — but don't rely on it moving money. Its one runtime branch (hand back a Cashu change token
-from proofs still held in-process) never fires under the P2PK-accumulator path, and no rail reverses a
-settled payment. What decides whether the caller can _reach_ the released value is your **`auth` slot**, not your
-`credit` block — the draw path never reads `credit`, it needs a verified pubkey. Without `auth` every caller is
-the pooled `anonymous` requester and an explicit draw is refused, so the money stays with you in practice. With
-`auth`, the release lands on a credit keyed to their pubkey and the failed job's receipt carries its `credit_id`,
-so the protocol lets them spend it down on the next job with nothing extra wired (the `dvm` CLI doesn't do that
-automatically yet. Offering credit is the further step
-that makes it _reclaimable as money_ — that's what `drain` and `POST /v1/credit` are gated on.
-
-### Signed receipts
-
-Every job that reaches a terminal status — `completed`, `failed`, `cancelled` — carries a signed
-`receipt` block on its response. **Nothing to wire:** `dvmctl deploy` derives the key
-from the builder identity only after the platform returns the immutable DVM ID, binds both into the
-attestation, and provisions it; the SDK signs at the terminal.
-
-```jsonc
-"receipt": {
-  "v": 1, "job_id": "job-a7571b-1", "dvm_id": "<immutable-id>", "dvm": "<slug>", "capability": "count",
-  "outcome": "completed",           // completed | failed | cancelled
-  "reason": null,                   // terminal reason on failed/cancelled
-  "seq": 4213,                      // per-DVM monotonic terminal counter
-  "issued_at": 1789300000,
-  "requester_pubkey": null,         // set when signed-request auth was used
-  "paid": { "msats": 19000, "rail": "cashu", "native_amount": null,
-            "native_asset": null, "tx_hash": null, "mint": "https://..." },
-  "result_hash": "<sha256 hex>",    // sha256(canonicalize({summary, artifact_hashes})); summary
-                                    // only on completed, null otherwise; null if nothing delivered
-  "receipt_pubkey": "<64-hex>",
-  "signature": "<128-hex>",         // BIP-340 over canonicaliseForSigning(receipt minus signature)
-  "credit": {                       // present when the payment funded/drew the credit ledger
-    "credit_id": "imp:cashu:…", "draw_id": "…", "amount": 10000,
-    "balance_after": 240000,        // settled draw: the recorded trajectory.
-                                    // released draw (failed/cancelled): restored available balance
-    "ledger_seq": 7                 // per-credit monotonic draw counter
-  }
-}
-```
-
-What a builder needs to know:
-
-- Same receipt on the synchronous 200, the poll, and every later re-read — signed once at the
-  terminal and persisted, not re-signed per response (JSON key order can differ; canonicalisation
-  is what the signature covers).
-- Free jobs get receipts too (`paid.msats: 0`); they consume a `seq` like any other job.
-- `/v1/info` advertises `receipts: true` only when a key is wired **and** the job store can issue
-  (`claimReceiptSeq` / `saveReceipt` — both built-in stores do), so absence is detectable. A custom
-  `jobStore` that can't warns `receipts_disabled_store_unsupported` at boot.
-- Signing failure never breaks a job: the SDK logs `receipt_issue_failed` and serves without one.
-- `dvmctl dev` / `devMode` boots mint an ephemeral key — receipts verify locally but nothing
-  attests them. Outside dev, no key means no receipts and no flag.
-- Isolate-runtime DVMs don't issue receipts yet.
-
-Verifying one (four links, all required): the signature verifies under `receipt_pubkey`; the receipt's
-immutable `dvm_id` equals `/v1/info#builder`'s `attestation.dvm_id`; `receipt_pubkey` equals that
-attestation's `receipt_pubkey`; and the attestation verifies under `builder.pubkey`. The slug stays
-signed display metadata, never the trust identity. Use the published caller command
-`dvm receipts verify <job-id>` to check a stored receipt rather than reimplementing its canonicalisation.
-
-### Custom HTTP routes
-
-Two seams:
-
-- `routes(app)` on the descriptor — routes that **belong to this DVM**. They register on the DVM's
-  Hono sub-app and inherit any mount prefix.
-- `host.app` on the host — routes that **belong to the host** (cross-DVM `/health`, cron-callable
-  maintenance, anything not tied to one DVM).
-
-DVM-scoped (cast feed XML):
-
-```typescript
-configureDVM({
-  name: "cast",
-  capabilities: {
-    /* ... */
-  },
-
-  routes(app) {
-    app.get("/feeds/:owner/:slug", async (c) => {
-      const xml = await renderFeed(c.req.param("owner"), c.req.param("slug"));
-      return c.body(xml, 200, { "Content-Type": "application/rss+xml" });
-    });
-  },
-});
-```
-
-Host-scoped (scrape's pool-aware `/health`, registered before `host.mount`):
-
-```typescript
-import { createDVMHost } from "@dvmkit/sdk/server";
-
-const host = createDVMHost();
-
-let shuttingDown = false;
-host.app.get("/health", (c) => {
-  if (shuttingDown) return c.json({ ok: false, draining: true }, 503);
-  return c.json({ ok: true, pool: runtime.pool.health() });
-});
-
-host.mount(createScrapeDVM(runtime));
-await host.serve();
-```
-
----

package/skills/build-dvm/references/payment-rails.md

@@ -1,11 +0,0 @@
-# Payment rails for first builds
-
-`dvmctl dev` skips payment verification only when no rail is configured. When a rail is configured, the SDK verifies and settles its real credential, uses disposable in-process job/payment state, and reports completed paid jobs in the terminal. A dev server does not turn mainnet funds into test funds.
-
-| Rail | First-build proof | Test boundary |
-| --- | --- | --- |
-| Cashu | [Cashu recipe](local-cashu-test.md) with a local FakeWallet or explicitly approved hosted test mint. | The receipt's quoted msats and exact wallet debit are authoritative. |
-| x402 | [x402 recipe](local-x402-test.md) on Base Sepolia (`eip155:84532`). | Requires a separately funded testnet key and an approved micro-USDC cap. Never substitute Base mainnet. |
-| Tempo | [Tempo recipe](local-tempo-test.md) on Moderato (chain 42431). | `dvm wallet fund --rail tempo` uses the official testnet faucet. Never substitute Tempo mainnet. |
-
-A successful test proves only the selected local rail and test network. Production recipients, mints, facilitator credentials, payout settings, wallet connections, and funds are deployment decisions with separate approval.

package/skills/build-dvm/references/pricing-credit.md

@@ -1,155 +0,0 @@
-## Tags
-
-Tags are freeform strings describing what a DVM does, advertised in `/v1/info` and used by
-clients to discover providers:
-
-```typescript
-tag: "text"; // single tag
-tags: ["web", "extraction"]; // multiple tags
-```
-
----
-
-## Pricing
-
-Static prices are USD literals (`PriceValue`) — the only static price form:
-
-```typescript
-price: "$0.05"; // USD → converted at current BTC rate
-```
-
-A raw-msats price throws at `configureDVM`. So does anything below `"$0.0001"` or finer than four
-decimals — that's the precision every caller-facing surface advertises at, so a finer price would
-advertise one number and charge another. Free capabilities omit `price`. Need finer granularity?
-Price dynamically with `onQuote`; dynamic upfronts carry full micro-unit precision.
-
-Dynamic pricing with `onQuote` — fiat-first. The handler returns an `upfront` envelope
-(`{ amount, currency: "usd" }`) plus a `shape`:
-
-```typescript
-onQuote: {
-  schema: z.object({ duration: z.number() }),
-  async handler(ctx) {
-    return {
-      upfront: { amount: ctx.data.duration * 0.001, currency: "usd" },
-      description: `${ctx.data.duration}s of synthesis`,
-      shape: "fixed",
-    };
-  },
-},
-```
-
-(`ctx.data` here is the quote-time parsed input, distinct from a job's `ctx.input`.)
-
-Two-phase metered pricing — `shape: "rate"` returns an `upfront` floor plus a `rate` (per-unit)
-so the SDK advertises a max-units cap; the handler calls `ctx.requestPayment(...)` again mid-job
-once actual usage is known (this is scribe's pattern):
-
-```typescript
-onQuote: {
-  schema: transcribeSchema,
-  async handler(ctx) {
-    return {
-      upfront: { amount: 0.02, currency: "usd" },        // spam-gate floor
-      description: "Up to 15 minutes; metered per-minute after",
-      shape: "rate",
-      rate: {
-        per_unit: { amount: 0.02, currency: "usd" },
-        unit: "minute",
-        max_units: 15,
-      },
-    };
-  },
-},
-```
-
-All first-party DVMs quote in `currency: "usd"`; the SDK converts to sats at the 402 handshake.
-
-To price in something else, declare it once at the DVM level — `currency: "eur"` on `configureDVM`
-(ISO 4217 lowercase; the bundled fx fetcher carries usd/eur/gbp/jpy). That one field is what the
-credit ledger, the funding menu, and `POST /v1/credit` all denominate in, so the two ways it could
-drift are both refused rather than converted: an `onQuote` returning a different currency answers
-`quote_currency_mismatch` (500), and a static `price` on a non-USD DVM throws at `configureDVM`
-(`"$0.05"` is a USD literal — a non-USD DVM prices with `onQuote`). `credit.min`/`max` stay USD
-literals whatever you price in; the menu converts them.
-
----
-
-## Prepaid credit
-
-Every payment settles through a per-DVM **credit ledger**: the rail funds a balance, the job draws from it.
-Per-call payment is the N=1 case of that (fund the paid amount, draw it, same transaction) and happens
-whether or not you opt in. Declaring a `credit` block is the opt-in for callers to _hold_ a balance across
-jobs — the ledger, `POST /v1/credit`, the funding menu on quotes and 402s, per-draw idempotency and the
-quote balance echo are then wired for you:
-
-```typescript
-configureDVM({
-  name: "assessor",
-  capability: "assess",
-  price: "$0.01",
-  auth: secp256k1Auth(), // required — a balance belongs to a verified pubkey
-  credit: {
-    min: "$0.10", // smallest top-up accepted (default "$0.10")
-    max: "$5.00", // ceiling on a caller's *residual balance* (default "$5.00")
-    ttl: 30 * 24 * 60 * 60, // seconds; default 30 days
-    allowOneShotStablecoin: false, // default; stablecoin credit uses reusable channels
-  },
-  onJob(ctx) {
-    /* unchanged */
-  },
-});
-```
-
-`max` bounds what a caller may sit on, not what they may pay: a job priced above `max` still clears, because
-that request funds and draws in one step. Needs a Postgres-backed host — balances must survive a restart and
-be visible fleet-wide.
-
-- **`credit_id` / `draw_id` / `fund` are reserved at the top level of `data`.** A caller draws by putting
-  them in the same signed object your input schema validates. The SDK removes them before your schema sees
-  them and before the auth gate's schema check, so declare nothing for them, and **do** use `.strict()` if
-  you want it — unknown-key rejection still catches a caller's typo'd field with a 400 naming it.
-  The signature covers those keys either way, so tampering with one is still a 401. Don't name a field of
-  your own after one of them.
-- **Never hand-roll credit state.** The SDK ships the primitive (`credits` + `credit_draws`, `SELECT … FOR
-UPDATE` debits). `ctx.store` is **prohibited** for balances: last-write-wins KV on a multi-machine fleet
-  loses money under concurrency.
-- **Stablecoin credit is reusable-only unless you deliberately opt in.** Tempo `session` and x402
-  `batch-settlement` fund prepaid balances by default; Tempo `charge` and x402 `exact` still pay per call.
-  Set `allowOneShotStablecoin: true` only when you accept that every unused one-payment balance becomes a
-  manual refund obligation. Missing, malformed and older config fails closed.
-- **No debit on job failure**, with nothing to wire. A draw is a pending hold — settled on `completed`,
-  released on `failed` / `cancelled`, including `ctx.fail`, caller cancels and the stale-job reaper.
-- **Quote handlers see the caller.** `ctx.callerPubkey` is the verified pubkey (undefined without auth);
-  `ctx.credit` is a read-only snapshot `{ creditId, currency, balanceMicro, availableMicro, expiryMs,
-expired }` in micro-units — price against it, don't try to spend it (spending happens on the job path,
-  under the ledger's lock).
-- **Menu missing when you expected one?** The refusal ladder is ordered, and **only its last two rungs say
-  anything**. Isolate runtime (never offers credit), no `credit` block, and no descriptor auth all return
-  silently — check those three first, in that order, because no log will point you at them. A non-durable
-  ledger outside devMode warns `credit_menu_suppressed_non_durable`; bounds not expressible in the quote
-  currency warn `credit_menu_bounds_unavailable` (note the different prefix — don't grep for one pattern).
-  Both fire once per process (`warnOnce`), so a restart is what re-arms them. A rung never fails the quote —
-  the sale survives without credit.
-- **Reclaim is a builder obligation on the rails you hold the money on — and only those.** Who fulfils a
-  drain is decided by the rail, and treating one shape as another is how a self-settling refund lands on
-  your worklist or a real debt goes unpaid. **Ecash is the whole of your automatic obligation**:
-  `dvmctl melt-pending` parks notes P2PK-locked to the caller's refund key and holds your payout melt back
-  while refund liability is outstanding. A **Lightning-funded** credit reclaims that same way — direct
-  Lightning payout is not a reclaim method, so a `method: "lightning"` drain is refused
-  `drain_method_unsupported` and your deployment never needs a send-capable Lightning credential.
-  **Channel-backed x402 and Tempo drains settle themselves** on the caller's signed refund
-  voucher — no builder spending key, nothing to record; `drains-owed` never lists one and `drain-settle`
-  refuses it (`channel_bound_drain`), because a hand-recorded payout takes the row out of the reconciliation
-  that would have paid it. **One-payment x402 and Tempo drains are the only shape a person settles**: they
-  queue behind `drain_manual_settlement_required`, and `dvmctl credit drains-owed <handle>` then
-  `dvmctl credit drain-settle <handle> <credit-id> <drain-id> --tx <hash>` is the path. That one is manual
-  by design — automating it would put a chain spending key with your whole stablecoin balance behind it on
-  the `melt-pending` host. On the rails you hold, an
-  unfulfilled drain is a signed IOU the caller can prove. One-payment stablecoin credit exists only when
-  `allowOneShotStablecoin` explicitly enabled it; do not take that opt-in without an operating refund path.
-
-For wire shapes and supported options, consult the installed SDK declarations and the local `dvmctl`
-help for the version you installed.
-
----