@dvmkit/sdk 0.2.0-rc.9 → 0.3.0-rc.9

package/dist/internal/caller.d.ts

@@ -1,16 +1,16 @@
-import { L as LightningTransactionListOptions, a as LightningTransactionSnapshot, b as LightningBackend, c as LightningPayment, d as LightningWalletInfo, C as CreatedInvoice, I as InvoiceStatus, M as MintAmountBounds, e as MintHealthCheckResult } from '../lightning-backend-CQBnQgsT.js';
-export { A as AttestationPayload, B as BuilderIdentityKeypair, f as CheckMintHealthOptions, g as LockPubkey, h as amountBoundsVerdict, i as assertNutSupport, j as buildAttestation, k as canSwap, l as checkMintHealth, m as generateIdentity, n as hashCapabilities, o as loadIdentitySecret, s as signAttestation, t as toLockPubkey, v as verifyAttestation, w as writeIdentity } from '../lightning-backend-CQBnQgsT.js';
+import { L as LightningTransactionListOptions, a as LightningTransactionSnapshot, b as LightningBackend, c as LightningPayment, d as LightningWalletInfo, C as CreatedInvoice, I as InvoiceStatus, M as MintAmountBounds, e as MintHealthCheckResult } from '../lightning-backend-BhsyrBLa.js';
+export { A as AttestationPayload, B as BuilderIdentityKeypair, f as CheckMintHealthOptions, g as LockPubkey, h as amountBoundsVerdict, i as assertNutSupport, j as buildAttestation, k as canSwap, l as checkMintHealth, m as generateIdentity, n as hashCapabilities, o as loadIdentitySecret, s as signAttestation, t as toLockPubkey, v as verifyAttestation, w as writeIdentity } from '../lightning-backend-BhsyrBLa.js';
 import { ProofLike, MeltQuoteBolt11Response, Proof, Wallet, SerializedDLEQ, MintQuoteBolt11Response, MintQuoteState, MintPreview, OutputDataLike, CounterSource, CounterRange } from '@cashu/cashu-ts';
 export { g as getWallet } from '../wallet-Dwjs5n_M.js';
-import { W as JsonValue, z as SignedRequestDomain, H as SignedRequestStatementHeader, X as FundingReceipt, Y as JobReceipt$1, y as SignedRequestAudience, _ as PaymentRequired, $ as X402Version, a0 as MppxCredential, a1 as Message, a2 as MessageType, a3 as MppxChallenge, a4 as X402_BATCH_SETTLEMENT_SCHEME, a5 as X402_EXACT_SCHEME, a6 as ReceiptCredit, C as Currency, a7 as X402Wallet, L as Logger$1, K as KVStore, a8 as ResourceInfo } from '../step-cache-CXg7ziML.js';
-export { a9 as BuildPaymentRequirementsOpts, aa as CapabilityDescriptor, ab as CashuMode, ac as CompleteContent, ad as DrainReceipt, ae as DrainReceiptEvent, af as ExactEvmPayload, ag as ExactEvmPayloadAuthorization, ah as FundingMethod, ai as MessageFrom, aj as PaymentPayload, ak as PaymentPayloadV1, al as PaymentPayloadV2, am as PaymentRequestContent, an as PaymentRequiredV2, ao as PaymentRequirements, ap as PaymentRequirementsV1, aq as PaymentRequirementsV2, ar as PromptContent, as as RAIL_REFUNDABLE, at as ReceiptOutcome, au as ReceiptPayment, av as SettleResponse, aw as StepCache, ax as StepRecord, ay as TextContent, az as UnsignedDrainReceipt, aA as UnsignedFundingReceipt, aB as UnsignedJobReceipt, aC as VerifyResponse, aD as WorkingContent, aE as X402Config, aF as X402ResponseBody, aG as X402SelfRelayRpcFailureReason, aH as X402_DEFAULT_NETWORK, aI as X402_V1_VERSION, aJ as X402_VERSION, aK as buildPaymentRequiredV2, aL as buildPaymentRequirements, aM as caip2ToX402Network, aN as canonicalRequestPath, aO as canonicaliseForSigning, aP as canonicalize, aQ as chainIdFromCaip2, aR as computeResultHash, aS as decodePayment, aT as decodePaymentRequiredHeader, aU as encodePayment, aV as encodePaymentRequiredHeader, aW as encodeSettleResponseHeader, aX as exactEvmAuthorization, aY as isArtifactMessage, aZ as isCancelMessage, a_ as isCompleteMessage, a$ as isDrainReceipt, b0 as isFundingReceipt, b1 as isPaymentRequestMessage, b2 as isPromptMessage, b3 as isSignedJobReceipt, b4 as isTextMessage, b5 as isWorkingMessage, b6 as paymentRequiredV2FromV1, b7 as signDrainReceipt, b8 as signFundingReceipt, b9 as signReceipt, ba as usdcContractByCaip2, bb as usdcContractFor, bc as usdcDomainNameFor, bd as usdcDomainVersionFor, be as verifyDrainReceipt, bf as verifyFundingReceipt, bg as verifyReceipt, bh as x402NetworkToCaip2 } from '../step-cache-CXg7ziML.js';
+import { W as JsonValue, z as SignedRequestDomain, H as SignedRequestStatementHeader, X as FundingReceipt, Y as JobReceipt$1, y as SignedRequestAudience, _ as PaymentRequired, $ as X402Version, a0 as MppxCredential, a1 as Message, a2 as MessageType, a3 as MppxChallenge, a4 as X402_BATCH_SETTLEMENT_SCHEME, a5 as X402_EXACT_SCHEME, a6 as ReceiptCredit, C as Currency, a7 as X402Wallet, L as Logger$1, K as KVStore, a8 as ResourceInfo } from '../step-cache-v2yhyhSZ.js';
+export { a9 as BuildPaymentRequirementsOpts, aa as CapabilityDescriptor, ab as CashuMode, ac as CompleteContent, ad as DrainReceipt, ae as DrainReceiptEvent, af as ExactEvmPayload, ag as ExactEvmPayloadAuthorization, ah as FundingMethod, ai as MessageFrom, aj as PaymentPayload, ak as PaymentPayloadV1, al as PaymentPayloadV2, am as PaymentRequestContent, an as PaymentRequiredV2, ao as PaymentRequirements, ap as PaymentRequirementsV1, aq as PaymentRequirementsV2, ar as PromptContent, as as RAIL_REFUNDABLE, at as ReceiptOutcome, au as ReceiptPayment, av as SettleResponse, aw as StepCache, ax as StepRecord, ay as TextContent, az as UnsignedDrainReceipt, aA as UnsignedFundingReceipt, aB as UnsignedJobReceipt, aC as VerifyResponse, aD as WorkingContent, aE as X402Config, aF as X402ResponseBody, aG as X402SelfRelayRpcFailureReason, aH as X402_DEFAULT_NETWORK, aI as X402_V1_VERSION, aJ as X402_VERSION, aK as buildPaymentRequiredV2, aL as buildPaymentRequirements, aM as caip2ToX402Network, aN as canonicalRequestPath, aO as canonicaliseForSigning, aP as canonicalize, aQ as chainIdFromCaip2, aR as computeResultHash, aS as decodePayment, aT as decodePaymentRequiredHeader, aU as encodePayment, aV as encodePaymentRequiredHeader, aW as encodeSettleResponseHeader, aX as exactEvmAuthorization, aY as isArtifactMessage, aZ as isCancelMessage, a_ as isCompleteMessage, a$ as isDrainReceipt, b0 as isFundingReceipt, b1 as isPaymentRequestMessage, b2 as isPromptMessage, b3 as isSignedJobReceipt, b4 as isTextMessage, b5 as isWorkingMessage, b6 as paymentRequiredV2FromV1, b7 as signDrainReceipt, b8 as signFundingReceipt, b9 as signReceipt, ba as usdcContractByCaip2, bb as usdcContractFor, bc as usdcDomainNameFor, bd as usdcDomainVersionFor, be as verifyDrainReceipt, bf as verifyFundingReceipt, bg as verifyReceipt, bh as x402NetworkToCaip2 } from '../step-cache-v2yhyhSZ.js';
 import { SimplePool } from 'nostr-tools/pool';
 import { Session } from 'mppx/tempo';
 import { Pool } from 'pg';
 import { PaymentRequired as PaymentRequired$1 } from '@x402/core/types';
 import { ClientChannelStorage, BatchSettlementClientContext, BatchSettlementEvmScheme } from '@x402/evm/batch-settlement/client';
-export { e as FX_CACHE_TTL_MS, g as FX_RETRY_COUNT, w as warmFxSnapshot } from '../fx-B0SLBe5x.js';
-export { c as InvalidUsdPriceError, p as parseUsdPrice } from '../usd-BNDg1715.js';
+export { e as FX_CACHE_TTL_MS, g as FX_RETRY_COUNT, w as warmFxSnapshot } from '../fx-DhyT1Cjh.js';
+export { c as InvalidUsdPriceError, p as parseUsdPrice } from '../usd-Cu9G6xv2.js';
 import 'hono';
 import 'mppx';
 import '@x402/core/server';
@@ -25,19 +25,12 @@ declare const CAPABILITY_NAME_RE: RegExp;
 declare const X402_DEFAULT_FACILITATOR = "https://x402.org/facilitator";
 
 /**
- * Verify a secp256k1+BIP-340 Schnorr signature over the canonical JSON form
- * of `payload`. The generic primitive behind `secp256k1Auth` and every
- * descriptor-level signed-request verifier in the SDK — not cast-specific
- * despite the file's historical location.
- *
- * `pubkeyHex` is the x-only (32-byte) public key in hex; `signatureHex` is
- * the 64-byte signature in hex.
- * Returns `false` on any failure (bad encoding, wrong length, invalid
- * signature) so callers can map a single boolean to `auth_error`.
+ * BIP-340 verification over canonical JSON, with a 32-byte x-only public key
+ * and a 64-byte signature, both hex-encoded. Bad wire encoding or failed crypto
+ * verification returns false; unsupported payload serialization can throw.
  */
 declare function verifyCanonicalSignedRequest(payload: JsonValue, signatureHex: string, pubkeyHex: string): boolean;
 
-/** Time window for a global spending cap. */
 type BudgetWindow = "daily" | "weekly" | "monthly";
 /** User-configured fiat caps. Any subset may be set. */
 interface BudgetCaps {
@@ -61,10 +54,7 @@ type BudgetSpendKind = "job" | "float_fund" | "credit_fund";
 interface BudgetLedgerEntry {
     /** Unix timestamp (ms) when the payment was confirmed. */
     timestamp: number;
-    /**
-     * Outflow kind. Absent on entries written before which were all
-     * job spends — {@link entryKind} normalises that.
-     */
+    /** Missing kind denotes a legacy job spend; entryKind supplies that default. */
     kind?: BudgetSpendKind;
     /** Job ID the payment belongs to. For `float_fund`, the funding reference (e.g. a mint quote id). */
     jobId: string;
@@ -87,10 +77,8 @@ interface BudgetLedgerEntry {
     /** USD equivalent at spend time. */
     usd: number;
     /**
-     * Short human context for the spend, shown by `dvm wallet history`. For
-     * upfront payments this is CLI-authored (`capability · N chars`); for mid-job
-     * `payment-request` spends it's the provider's stated reason. Optional — old
-     * entries recorded before lack it and render fine without it.
+     * Human context for wallet history: CLI-authored for upfront payments,
+     * provider-supplied for mid-job payment requests. Optional on legacy entries.
      */
     label?: string;
     /**
@@ -101,12 +89,10 @@ interface BudgetLedgerEntry {
      */
     labelSource?: "provider";
 }
-/** Persisted budget file shape. */
 interface BudgetLedger {
     caps: BudgetCaps;
     entries: BudgetLedgerEntry[];
 }
-/** Spend inside a window, split by what the money was for. */
 interface BudgetSpendBreakdown {
     /** Total USD spent in the window — the number caps are checked against. */
     totalUsd: number;
@@ -144,7 +130,6 @@ interface RecordSpendOptions {
     labelSource?: "provider";
     now?: Date;
 }
-/** Append a confirmed spend to the ledger. */
 declare function recordSpend(opts: RecordSpendOptions): void;
 /**
  * Enforce the global budget caps before a planned spend.
@@ -165,7 +150,6 @@ declare function enforceGlobalBudget(opts: {
     plannedMsats: number;
     btcRate?: number;
 }): Promise<number>;
-/** Snapshot of current spending vs caps for `dvm budget status`. */
 declare function statusSnapshot(now?: Date): {
     caps: BudgetCaps;
     windows: {
@@ -197,9 +181,7 @@ declare function buildAdminChallenge(args: {
     nonceHex: string;
     unixSeconds: number | string;
 }): Uint8Array;
-/** Parsed components of an `Authorization: P2PK <nonce>.<unix>.<sig>` header. */
 interface AdminAuthHeader {
-    /** Full header value, ready to drop into `Authorization`. */
     header: string;
     /** 16-byte hex nonce — exposed so callers/tests can introspect it. */
     nonceHex: string;
@@ -313,26 +295,9 @@ declare function getInputFeesForProofs(mintUrl: string, proofs: Pick<Proof, "id"
  */
 declare function fetchMeltQuote(mintUrl: string, bolt11: string): Promise<MeltQuoteInfo>;
 
-/**
- * What a cashu-ts swap actually costs, derived from cashu-ts's own fee
- * helpers rather than re-modelled here.
- *
- * Anything that picks proofs has to know a swap's input requirement *before*
- * it hands cashu-ts the proofs — that's what selection is. cashu-ts has no
- * side-effect-free oracle for it (`Wallet.prepareSwapToSend` mints blinded
- * outputs and reserves NUT-13 counters), so this module reconstructs the
- * requirement from the public primitives the library uses internally:
- * `Wallet.getFeesForProofs`, `Wallet.getFeesForKeyset` and `splitAmount`.
- * Keeping that reconstruction in one file is the point — the bug this
- * replaces was a hand-rolled `ceil(N * input_fee_ppk / 1000)` in the agent
- * wallet's selector drifting from the library that does the swap.
- *
- * It lives here rather than under `wallet-agent/` because the same
- * arithmetic prices both sides of the protocol: the caller's spend selection
- * (`wallet-agent/spend.ts`, `release.ts`) and the builder's drain-park batch
- * selection (`commands/builder/drain-service.ts`), which is where the same bug
- * class was found a second time.
- */
+/** Selection needs a reserve before swapping. prepareSwapToSend has side effects
+ * (blinded outputs and counter reservations), so price it through cashu-ts fee
+ * primitives shared by caller and builder proof selection. */
 
 /**
  * Sats a `wallet.ops.send(amountSats, …).includeFees(true)` swap consumes on
@@ -341,9 +306,7 @@ declare function fetchMeltQuote(mintUrl: string, bolt11: string): Promise<MeltQu
  * Selection is done when `sum(inputs) >= amountSats + reserve(inputs)`.
  */
 type SwapSendReserve = (inputs: ProofRef[]) => number;
-/** The one field of a proof the fee helpers read: its keyset id. */
 interface ProofRef {
-    /** Keyset id the proof was issued against. */
     id: string;
 }
 /**
@@ -595,7 +558,6 @@ type Rail = "cashu_p2pk" | "tempo" | "x402";
  * `cashu` maps to the P2PK agent-wallet rail.
  */
 type RailFlag = "cashu" | "tempo" | "x402";
-/** Recognise the user-facing rail flag values accepted on the CLI. */
 declare const RAIL_FLAGS: readonly RailFlag[];
 
 interface Config {
@@ -995,7 +957,6 @@ interface NwcTransaction {
     /** Unix seconds when the invoice settled (null/undefined means unpaid). */
     settledAt?: number;
 }
-/** Error from an NWC operation (invalid URI, timeout, wallet rejection, etc.). */
 declare class NwcError extends Error {
     code: string;
     /**
@@ -1016,7 +977,6 @@ declare class NwcError extends Error {
      */
     method?: string | undefined);
 }
-/** Per-request transport tunables. */
 interface NwcRequestOptions {
     /** Reuse an existing pool instead of opening (and closing) a fresh one. */
     pool?: SimplePool;
@@ -1079,7 +1039,6 @@ declare function parseNwcUri(uri: string): NwcConnection;
 declare function payInvoiceReconciling(conn: NwcConnection, bolt11: string, opts?: PayInvoiceReconcilingOptions): Promise<PayInvoiceOutcome>;
 /** Get wallet balance in millisatoshis. */
 declare function getBalance(conn: NwcConnection, opts?: NwcRequestOptions): Promise<number>;
-/** Get wallet metadata (alias, supported methods, any volunteered budget fields). */
 declare function getInfo(conn: NwcConnection, opts?: NwcRequestOptions): Promise<WalletInfo>;
 /**
  * Create a Lightning invoice on the remote wallet.
@@ -1579,11 +1538,9 @@ declare function receiptFailureDetail(reason: ReceiptInvalidReason): string;
 type ReceiptParseError = "shape_invalid";
 /** The highest protocol version this client supports. */
 declare const SUPPORTED_PROTOCOL_VERSION = 1;
-/** Reference to a DVM provider — identified by its HTTPS endpoint URL. */
 interface ProviderRef {
     endpoint: string;
 }
-/** Universal job envelope — transport-agnostic representation of a job request. */
 interface JobEnvelope {
     /**
      * Capability name on the target DVM. Set by callers that already
@@ -1601,7 +1558,6 @@ interface JobEnvelope {
     /** Max bid in millisatoshis */
     bidMsats?: number;
 }
-/** Payment token attached to a job submission. */
 interface Payment {
     /** Cashu token (for X-Cashu header) */
     cashuToken?: string;
@@ -1617,13 +1573,8 @@ interface Payment {
     cashuRequestId?: string;
 }
 /**
- * Quote returned by a provider before job execution.
- *
- * `upfront` is the protocol-enforced fiat commitment. `priceMsats` is the
- * client's local advisory sats estimate — derived via `fetchBtcUsdRate` from
- * `upfront.amount × current fx` at transport-read time. Binding sats settles
- * at the `/v1/job` 402 handshake; this field is for display + budget
- * comparison only.
+ * upfront is the binding fiat commitment. priceMsats is advisory; the 402
+ * handshake supplies the actual settlement amount.
  */
 interface Quote {
     /**
@@ -1673,15 +1624,9 @@ interface Quote {
     /** Quote expiration (unix seconds). */
     expiresAt?: number;
     /**
-     * The provider's `payment` envelope. `methods` is the
-     * settleable rail list; `refundable` maps each rail to whether that
-     * rail can hand value back, and is `false` on every rail today — Cashu proofs
-     * commit to the accumulator at receive time, Tempo and x402 are final
-     * settlement. It is **not** the answer to "does a failed job cost me money":
-     * since the behavior was introduced a failed job releases its draw and never debits, and whether
-     * the caller can reach that released value is told by {@link Quote.credit}
-     * `refundable` is omitted by legacy providers, in which case
-     * this field stays undefined.
+     * Rail refundability is separate from failed-job cost: failure releases the
+     * pending credit draw, while the credit menu states whether its value can be
+     * reclaimed. Legacy providers omit refundable.
      */
     payment?: {
         methods: string[];
@@ -1787,7 +1732,6 @@ declare function parseCreditMenu(raw: unknown): CreditMenu | undefined;
  * there is no header for the caller to hang a proof on.
  */
 interface LightningFundingOffer {
-    /** The bolt11 to pay. */
     invoice: string;
     /** Payment hash, for reconciling against the wallet's own record. */
     payment_hash: string;
@@ -1852,12 +1796,13 @@ interface DrainWire {
     token?: string;
     /** Structured settlement evidence for a non-cashu payout, once sent. */
     sent?: Record<string, unknown>;
-    /** DVM-signed `DrainReceipt`s for every state this drain has reached. */
+    /** Opaque receipt observations; consumers must shape-check and authenticate them. */
     receipts: unknown[];
 }
-/** `POST /v1/credit` response envelope — one op's answer (1436). */
+/**
+ * POST /v1/credit operation response.
+ */
 interface CreditOpResult {
-    /** Which op this answers. */
     op: "fund" | "balance" | "drain";
     /** Micro-units actually credited by a `fund` (pro-rata of the artifact's value). */
     funded_micro?: number;
@@ -1873,7 +1818,6 @@ interface CreditOpResult {
      * is on `credit.credit_id`, not the `credit_id` that was polled.
      */
     reconciled?: boolean;
-    /** The primary / affected credit. */
     credit?: CreditWire;
     /** Every credit this caller holds here (`balance` op; includes expired). */
     credits?: CreditWire[];
@@ -1885,7 +1829,6 @@ interface CreditOpResult {
      * treats it as no update and keeps whatever snapshot it already holds.
      */
     menu?: CreditMenu;
-    /** The drain record (`drain` op). */
     drain?: DrainWire;
     /** Relay-safe one-liner from the DVM (drain op). */
     display?: string;
@@ -1909,7 +1852,6 @@ interface CreditOpResult {
  * response; that one is a single block inside it.
  */
 interface JobReceipt {
-    /** Job ID (server-assigned) */
     jobId: string;
     status: "completed" | "processing" | "payment-required" | "failed" | "cancelled" | "awaiting-input";
     /** Tempo settlement transaction from the validated `Payment-Receipt` header. */
@@ -1922,17 +1864,12 @@ interface JobReceipt {
     artifactCount?: number;
     /** Tells agents where the payload lives: `"summary"` when the summary string is the full payload; `"messages"` when artifacts hold the actual output. */
     payloadIn?: "summary" | "messages";
-    /** Quotes collected during submission */
     quotes?: Quote[];
     /** Estimated seconds until completion (for async jobs) */
     estimatedSeconds?: number;
     /**
-     * A `X-Cashu-Change` token the provider returned.
-     *
-     * dvmkit DVMs no longer send one — overpayment funds the caller's credit and
-     * is drawn for the job, and deleted the server half. The reader
-     * stays because the header is still NUT-24, a third-party DVM may send it,
-     * and a token nobody claims is money on the floor.
+     * Third-party/legacy X-Cashu-Change token. Current SDK overpayment funds
+     * the caller's credit; transports retain this token for compatible recovery.
      */
     cashuChange?: string;
     /**
@@ -1968,19 +1905,16 @@ interface JobReceipt {
     fundedMicro?: number;
     credit?: CreditWire;
 }
-/** Options controlling how submit() waits for results. */
 interface SubmitOptions {
     /** Wait for result in ms. 0 = fire-and-forget. Default 30000. */
     timeoutMs?: number;
 }
-/** Options controlling how status() polls/subscribes. */
 interface StatusOptions {
     /** How long to subscribe/poll in ms. Default 5000. */
     timeoutMs?: number;
     /** opaque per-job token issued at create-time; sent as `X-Job-Token`. */
     jobToken?: string;
 }
-/** Options controlling how getMessages() polls/subscribes. */
 interface MessagePollOptions {
     /** How long to poll/subscribe in ms. */
     timeoutMs?: number;
@@ -2005,12 +1939,8 @@ interface JobStatus {
     payloadIn?: "summary" | "messages";
     message?: string;
     /**
-     * A `X-Cashu-Change` token the provider returned.
-     *
-     * dvmkit DVMs no longer send one — overpayment funds the caller's credit and
-     * is drawn for the job, and deleted the server half. The reader
-     * stays because the header is still NUT-24, a third-party DVM may send it,
-     * and a token nobody claims is money on the floor.
+     * Third-party/legacy X-Cashu-Change token. Current SDK overpayment funds
+     * the caller's credit; transports retain this token for compatible recovery.
      */
     cashuChange?: string;
     /**
@@ -2462,11 +2392,8 @@ interface PendingTempoChargeFunding {
  * around individual storage calls.
  */
 declare function withTempoChannelLock<T>(operation: () => Promise<T>): Promise<T>;
-/** List the caller's currently remembered Tempo credit channels. */
 declare function listTempoChannelAssociations(): TempoChannelAssociation[];
-/** Find the channel bound to one DVM credit and caller identity. */
 declare function loadTempoChannelAssociation(endpoint: string, callerPubkey: string, creditId: string): TempoChannelAssociation | undefined;
-/** Load the full mppx entry associated with one DVM credit. */
 declare function loadTempoChannelEntry(association: TempoChannelAssociation): Promise<ChannelEntry | undefined>;
 /**
  * The wallets a recorded channel's descriptor authorizes over its collateral.
@@ -2491,17 +2418,8 @@ interface TempoChannelController {
  */
 declare function loadTempoChannelController(association: TempoChannelAssociation): Promise<TempoChannelController | undefined>;
 /**
- * Whether one Tempo address is named by a recorded channel's descriptor.
- *
- * Both roles count. The payer is who the escrow refunds, and the authorized
- * signer is who can still commit that deposit — dropping either key changes
- * what the channel can do, so either one is reason enough to keep refusing.
- *
- * A record whose descriptor is already gone reads as controlled: ownership is
- * then unknowable, and guessing "stranger" would let a key be replaced over a
- * channel it may well own. A machine with no Tempo key configured controls
- * nothing, which is the opposite default and for the same reason — no key here
- * can sign for that channel, so nothing here is worth protecting.
+ * Either payer or delegated signer controls the channel. Unknown ownership is
+ * treated as controlled; with a known controller, an absent address does not match.
  */
 declare function tempoChannelControlledBy(controller: TempoChannelController | undefined, address: string | undefined): boolean;
 /** Every charge funding a sweep could still resume, optionally scoped to one DVM identity. */
@@ -2511,19 +2429,7 @@ declare function listResumableTempoChargeFundings(filter?: {
     now?: number;
 }): PendingTempoChargeFunding[];
 
-/**
- * The naming contract every stablecoin rail shares.
- *
- * A rail settles in exactly one token contract, and the caller-side balance
- * read queries exactly that contract — so a wallet funded with the wrong dollar
- * is indistinguishable from an unfunded one unless every surface that prints a
- * balance can name the asset the rail actually accepts. Each rail resolves that
- * name once, in its own module, and returns this shape; print sites carry no
- * literals.
- *
- * Deliberately type-only and dependency-free: it is imported by both the
- * caller-side CLI and the `src/lib/x402/` modules the SDK server shares.
- */
+/** Dependency-free display names for the token selected by a stablecoin rail. */
 interface RailAsset {
     /** Token contract the rail settles in. */
     address: `0x${string}`;
@@ -2535,7 +2441,6 @@ interface RailAsset {
     unit: string;
 }
 
-/** Where a resolved RPC URL came from. */
 type RpcSource = "override" | "bundled";
 /**
  * A resolved RPC URL and the source that supplied it.
@@ -2569,19 +2474,10 @@ declare function resolveRpcOverride(envValue: string | undefined, bundled?: stri
 declare function resolveRpcHttpTransportOptions(source: RpcSource, envValue: string | undefined): RpcHttpTransportOptions | undefined;
 
 /**
- * Tempo (EVM) wallet primitives for the agent-wallet multi-rail abstraction
- * Tempo's "wallet" reduces to an EVM private key — mppx's
- * `tempo.charge` signs a per-call EIP-712-style authorization with that key
- * for every 402 challenge. The on-chain USDC balance at the derived address
- * is the practical spending limit.
- *
- * Persistence reuses the existing `config.tempo` shape (set by
- * `dvm wallet tempo-connect --api-key 0x...`) so both the import-existing
- * path and the new generate-fresh path (`dvm wallet fund $X --rail tempo`)
- * write the same JSON. Older records without `network` resolve to mainnet.
+ * Imported and generated keys share `config.tempo`. Records without a network
+ * retain the mainnet default. Balance reads target the configured token.
  */
 
-/** A locally-persisted Tempo (EVM) account. */
 interface TempoAccount {
     /** Lowercase 0x-prefixed 40-char EVM address derived from {@link privateKey}. */
     address: `0x${string}`;
@@ -2590,24 +2486,14 @@ interface TempoAccount {
     /** Network this key is configured to spend on. */
     network?: TempoNetwork;
 }
-/** Supported Tempo wallet networks. */
 type TempoNetwork = "mainnet" | "moderato";
 /**
- * Live balance result from {@link getTempoUsdcBalance}.
- *
- * The endpoint the read went to is carried **only** in redacted form
- * ({@link rpcUrlRedacted}), never in the clear. A caller's
- * `DVM_TEMPO_RPC_URL` usually holds a provider API key in its path, and
- * this object is one JSON spread away from caller-visible output — which is
- * why removed the raw field outright. needs the endpoint on
- * the success path (a read against the wrong one returns a believable `$0.00`
- * that nothing else distinguishes from an unfunded wallet), so it comes back
- * pre-redacted: there is no clear value here for a future consumer to leak.
+ * Carries the queried endpoint only in redacted form, including on success:
+ * provider URLs may contain credentials and consumers may expose this object.
  */
 interface TempoBalance {
-    /** Account whose USDC balance was queried. */
     address: `0x${string}`;
-    /** Raw on-chain balance, in USDC base units (6 decimals). */
+    /** Raw configured-token balance, in base units (6 decimals). */
     rawBaseUnits: bigint;
     /** Balance in USDC (`rawBaseUnits / 10^6`, returned as a number for display). */
     usdc: number;
@@ -2625,13 +2511,10 @@ interface TempoBalance {
     /** Wall-clock ms when the balance was fetched. */
     fetchedAtMs: number;
 }
-/** Tempo mainnet chain id. */
 declare const TEMPO_CHAIN_ID = 4217;
-/** Tempo Moderato chain id. */
 declare const TEMPO_MODERATO_CHAIN_ID = 42431;
 /** Default pathUSD token on Tempo Moderato. */
 declare const TEMPO_PATH_USD_MODERATO: "0x20c0000000000000000000000000000000000000";
-/** Public Tempo Moderato RPC. */
 declare const TEMPO_MODERATO_RPC: "https://rpc.moderato.tempo.xyz";
 /** Stable chain, RPC, and default-token identity for a persisted Tempo network. */
 declare function resolveTempoNetwork(network?: TempoNetwork): {
@@ -2640,19 +2523,6 @@ declare function resolveTempoNetwork(network?: TempoNetwork): {
     rpcUrl: string;
     defaultToken: `0x${string}`;
 };
-/**
- * The single asset the Tempo rail settles in, resolved from the environment.
- *
- * Tempo carries more than one dollar-denominated stablecoin (USDC.e and USDT0
- * at minimum), but a DVM charges in exactly one contract and the caller-side
- * balance read queries exactly that contract. Every surface that names the
- * asset resolves it here so a caller running with `DVM_TEMPO_CURRENCY` set
- * never reads copy that contradicts the contract their wallet is actually
- * pointed at.
- *
- * Tempo needs no fields beyond the shared {@link RailAsset} contract. The
- * wallet's persisted network selects the default address before this resolves.
- */
 type TempoAsset = RailAsset;
 /**
  * Resolve the Tempo settlement asset from `DVM_TEMPO_CURRENCY`, falling
@@ -2738,14 +2608,9 @@ declare function generateTempoKey(opts?: {
  * surface the address + a "balance not queried" hint in `--human` output.
  */
 declare function getTempoUsdcBalance(account: TempoAccount): Promise<TempoBalance>;
-/** Derive the EVM address from a 0x-prefixed 32-byte hex private key. */
 declare function deriveTempoAddress(privateKey: `0x${string}`): Promise<`0x${string}`>;
 
-/** Caller-side TIP-1034 session credentials and unilateral channel recovery. */
-
-/** True when this caller can fund credit over either Tempo flavour. */
 declare function offersTempoCreditFunding(menu: CreditMenu | undefined): boolean;
-/** Test seam for supplying the challenge's Tempo chain client. */
 type TempoSessionClientResolver = NonNullable<NonNullable<Parameters<typeof Session.Client.session>[0]>["getClient"]>;
 type TempoSessionMethod = ReturnType<typeof Session.Client.session>;
 type TempoSessionChallenge = Parameters<TempoSessionMethod["createCredential"]>[0]["challenge"];
@@ -2759,7 +2624,6 @@ declare function tempoSessionChallenge(err: unknown): TempoSessionChallenge | un
  * crash on a path whose whole job is refusing what the DVM asks for.
  */
 declare function tempoSessionChallengeMicro(challenge: TempoSessionChallenge): number;
-/** Create the cooperative-close credential for a channel-backed credit drain. */
 declare function createTempoCloseCredential(args: {
     account: TempoAccount;
     association: TempoChannelAssociation;
@@ -2843,9 +2707,7 @@ interface TempoChannelExitArgs {
      * collateral an exit can still recover.
      */
     abandon?: boolean;
-    /** Test seam for the challenge chain client. */
     client?: Parameters<typeof Session.Precompile.Chain.getChannelState>[0];
-    /** Test seam for on-chain state transitions. */
     chain?: TempoChannelExitChain;
 }
 /**
@@ -2874,13 +2736,12 @@ interface TempoChannelReconcileResult {
     status: TempoChannelChainStatus;
     /** Whether the local record is gone once this call returns. Only ever on `closed`. */
     retired: boolean;
-    /** The channel the verdict is about. */
     channelId: string;
     /** The escrow's deposit, falling back to the record's figure when unread. */
     depositMicro: number;
     /** What the escrow has already paid the DVM, zero when unread. */
     settledMicro: number;
-    /** Why the chain could not be read — redacted, and present only on `unreadable`. */
+    /** Redacted read or local-retirement failure; the chain verdict can still be closed. */
     error?: DvmError;
 }
 /**
@@ -2898,9 +2759,10 @@ interface TempoChannelReconcileResult {
  * It broadcasts nothing: the chain seam is narrowed to `getChannelState`, and
  * the retirement is a local file write. It also never throws — a drain that
  * moved real money must not come back as an error because an RPC was down, and
- * a balance read must still report the rest of the wallet. Every failure is an
- * `unreadable` verdict carrying the redacted reason, and an `unreadable` or
- * still-live channel keeps its record.
+ * a balance read must still report the rest of the wallet. Failures are
+ * redacted in the result. A read failure is `unreadable`; a local retirement
+ * failure retains the chain's `closed` verdict and the record. Still-live
+ * channels keep their recovery records.
  */
 declare function reconcileTempoChannelOnChain(args: {
     association: TempoChannelAssociation;
@@ -3318,19 +3180,7 @@ interface JobCompletion {
  * a one-liner, not the payload, when the real output sits in artifact messages
  */
 declare function buildCompletionHintFields(jobId: string, input: JobCompletion): Record<string, unknown>;
-/**
- * Pre-rendered hint string an agent can pass through verbatim to its user when
- * a job's payload lives in artifact messages rather than the `summary` field.
- * Pluralised when the count is known.
- *
- * The `--no-stream` is load-bearing, not decoration. A bare `dvm messages <id>`
- * reads from the job's stored cursor, and by the time this hint is rendered the
- * cursor is at the end of the log — so following it verbatim returned an **empty
- * batch**, which is the worst possible answer to "fetch the artifacts".
- * `--no-stream` replays a terminal job from seq 0 — that flag belongs to the
- * caller CLI, which lives in its own repository — which is what a caller asking
- * for the payload actually wants.
- */
+/** `--no-stream` replays from seq 0: the stored cursor may already be past the artifacts. */
 declare function nextStepHint(jobId: string, payloadIn: "summary" | "messages" | undefined, artifactCount: number | undefined): string | undefined;
 /**
  * Pick the terminal-outcome fields off a receipt or status response, dropping
@@ -3368,9 +3218,7 @@ declare function asProviderTextOpt(text: string | undefined): ProviderText | und
 /** Render a ProviderText (or string) back to plain text — used by --human output paths. */
 declare function providerTextToString(value: string | ProviderText): string;
 
-/** Tells the agent exactly what to do after a command returns. */
 type NextAction = null | NextActionRespond | NextActionPay | NextActionApprove | NextActionPoll | NextActionRefund;
-/** Provider asked a question — agent should answer. */
 interface NextActionRespond {
     type: "respond";
     job_id: string;
@@ -3381,7 +3229,6 @@ interface NextActionRespond {
     /** CLI-owned guidance for the agent. */
     hint: string;
 }
-/** Payment requested above auto-pay threshold — agent should decide. */
 interface NextActionPay {
     type: "pay";
     job_id: string;
@@ -3459,7 +3306,6 @@ declare function pollNextAction(jobId: string, hint?: string): NextActionPoll;
  */
 declare function computeNextAction(jobId: string, messages: Message[]): NextAction;
 
-/** Persisted record of a submitted DVM job. */
 interface JobRecord {
     id: string;
     endpoint: string;
@@ -3563,33 +3409,17 @@ interface JobRecord {
      */
     builderAnchor?: ReceiptTrustAnchor;
 }
-/** Reference to a received artifact, indexed in the job record. */
 interface ArtifactRef {
-    /** Sequence number of the artifact message. */
     seq: number;
-    /** Artifact name, if provided. */
     name?: string;
     mimeType?: string;
 }
 declare function saveJob(job: JobRecord): void;
 /** Merge a partial update into an existing job record. No-op if job not found. */
 declare function updateJob(id: string, update: Partial<Omit<JobRecord, "id">>): void;
-/**
- * Mark a job as over, persisting the terminal outcome alongside the status
- * The only writer of a terminal `status` — routing every such write
- * through here keeps the invariant that a terminal record always carries its
- * `completion` snapshot, which is what lets `dvm status` replay the full
- * payload locally. Pass `{}` when the provider gave nothing to snapshot (e.g.
- * a caller-initiated cancel). No-op if the job is not found.
- *
- * Idempotent on `completedAt`: a job can be marked terminal more than once (a
- * `dvm status --messages` re-read, or the first read of a record that predates
- * the snapshot), and the job finished when it first finished — re-stamping would
- * drift the recorded time forward and skew `avgLatencyMs` in local provider
- * history.
- */
+/** Persist status and completion together for offline replay. Empty completion is allowed.
+ * Repeated terminal updates preserve the original completedAt. Missing jobs are unchanged. */
 declare function markJobTerminal(id: string, status: TerminalJobStatus, completion: JobCompletion, extra?: Partial<Omit<JobRecord, "id" | "status" | "completedAt" | "completion">>): void;
-/** Load a single job record by ID, or null if not found. */
 declare function loadJob(id: string): JobRecord | null;
 /** Load all job records. Returns [] on missing/corrupt file. */
 declare function loadAllJobs(): JobRecord[];
@@ -5003,15 +4833,10 @@ declare function fetchCoinGeckoSpot(opts?: CoinGeckoFetchOptions): Promise<CoinG
  */
 declare function fetchCoinGeckoBtcUsd(opts?: CoinGeckoFetchOptions): Promise<CoinGeckoBtcSpot>;
 
-/** Parsed components of a Lightning address (user@domain). */
 interface LnAddressParts {
     user: string;
     domain: string;
 }
-/**
- * Parse a Lightning address into user and domain components.
- * Validates the format is `user@domain` with reasonable constraints.
- */
 declare function parseLnAddress(address: string): LnAddressParts;
 /**
  * Resolve a payee identifier to the LNURL-pay metadata URL to GET.
@@ -5026,14 +4851,6 @@ declare function parseLnAddress(address: string): LnAddressParts;
  *     here rather than at an unrelated HTTP error later.
  */
 declare function resolveLnurlPayMetadataUrl(target: string): string;
-/**
- * Fetch a bolt11 invoice from a Lightning address or `lnurl1…` string via the
- * LNURL-pay protocol.
- *
- * 1. GET the metadata URL ({@link resolveLnurlPayMetadataUrl}) for pay params
- * 2. Validate amount is within [minSendable, maxSendable]
- * 3. GET `{callback}?amount={amountMsats}` for the bolt11 invoice
- */
 declare function fetchLnurlPayInvoice(lnAddress: string, amountMsats: number): Promise<string>;
 /**
  * Validate a Lightning address (or `lnurl1…` string) by probing its LNURL-pay
@@ -5049,38 +4866,10 @@ declare function validateLnAddress(address: string): Promise<void>;
  * Returned by {@link createMonotonicClock}.
  */
 type MonotonicNowMs = () => number;
-/**
- * A `Date.now()` reading floored so it can never run backwards inside this
- * closure's lifetime. The reading is projected forward from the
- * last anchor by the monotonic clock, so a wall clock that steps back — NTP
- * correcting a drifted host, the recurring CI-runner step behind * — is ignored until the wall catches up, while a legitimate forward
- * jump re-anchors immediately.
- *
- * The anchor is taken when the clock is created, so a sweeper that was already
- * running when the clock stepped is covered; one started afterwards has no way
- * to know, and simply trusts the clock it was born with.
- *
- * **One implementation, held by everything that needs it.** Two copies of this
- * would drift on exactly the reasoning that is hard to re-derive — the anchor
- * ordering, the re-anchor on the un-floored value, why the return is floored.
- * `JobManager` (the SDK stale-job sweep, the orphan-draw sweep and the
- * reactivation grace) and `IsolateJobReaper` (the isolate-tier mirror of that
- * sweep) each hold one.
- *
- * **What it costs is the reader's to weigh, and it is not the same everywhere.**
- * While the guard is compensating a step of `S`, a cutoff read off it is eager
- * by up to `S`. On the orphan-draw sweep that is the safe direction
- * outright: holds younger than `orphanDrawAgeMs` become candidates, but the
- * sweep still refuses any draw whose job row exists and isn't terminal, so the
- * eagerness only reaches draws inside the millisecond-scale window between the
- * ledger commit and `persistJob` — the window that age gate widens away from.
- * Blindness, the alternative, strands a caller's money with no signal at all.
- * On a stale-job watchdog it force-*fails* a job that may well be alive, so
- * both sweeps reading this for a watchdog cutoff clamp how far they lean on
- * it; see `JobManager#staleSweepCompensationCapMs` and
- * `IsolateJobReaper#compensationCapMs` for where each arm's cap
- * comes from, and why they differ.
- */
+/** Wall-clock epoch ms projected forward by performance.now() after a backward step.
+ * A forward step re-anchors immediately; the anchor starts at construction.
+ * During compensation a cutoff can be eager by the backward-step size, so watchdog
+ * callers must cap compensation separately. Results are floored to integer milliseconds. */
 declare function createMonotonicClock(): MonotonicNowMs;
 
 /** NWC-backed implementation of LightningBackend. */
@@ -5109,26 +4898,11 @@ declare const X402_EXACT_AUTHORIZATION_TTL_SECONDS = 600;
 declare const X402_REFUSAL_TRANSACTION_DISCOVERY_WINDOW_MS: number;
 
 /**
- * Build an mppx-shaped Tempo credential from a 402 challenge + a locally-held
- * EVM private key. Shared between the mid-job `payment-request` responder and
- * the upfront-payment path that lands in `dvm request` — both in the
- * caller CLI, which lives in its own repository.
- *
- * The credential is a structured `Credential.Credential` — an EIP-712-style
- * signature over the challenge plus mppx metadata. mppx's
- * `tempo.charge({ account }).createCredential({ challenge, context })`
- * performs the signing; this wrapper just plumbs it through the open-union
- * Challenge type and the `viem`/`mppx` dynamic imports so consumers don't
- * carry the dependency surface directly.
- *
- * The DVM authors the amount, so this is also where the caller refuses one it
- * never agreed to. Every Tempo signing path in the CLI goes through here —
- * credit funding, upfront per-call, mid-job top-up — which is why the ceiling
- * lives at this choke point rather than in each leg, exactly as
- * x402's lives inside `tryX402Payment`.
+ * Refuse an advertised charge above the caller's tolerance before handing it
+ * to mppx for signing. Nonzero pull charges sign a Tempo transaction; zero
+ * charges sign a typed proof and push mode returns a transaction hash.
  */
 
-/** Inputs to {@link buildTempoCredential}. */
 interface BuildTempoCredentialArgs {
     /** mppx challenges from the DVM (one per advertised method/intent). */
     challenges: readonly MppxChallenge[];
@@ -5330,20 +5104,10 @@ declare function computeSmartDenominations(amountSats: number, opts?: SmartDenom
 declare const WALLET_VERSION: 9;
 /** Cap on the number of recent-spends entries persisted to the wallet. */
 declare const RECENT_SPENDS_CAP = 10;
-/**
- * Default Cashu mint for the agent wallet. Used when
- * `wallet.mints` is empty. May 8 mint matrix selected Coinos as the alpha
- * default; runtime can fall back across the configured mint list.
- */
+/** Used when wallet.mints is empty; configured alternatives remain available. */
 declare const DEFAULT_AGENT_MINT_URL: "https://mint.coinos.io";
-/**
- * A Cashu proof persisted in the agent wallet, tagged with the issuing mint
- * and the lock pubkey it's locked to. Schema v2 widens the v1 shape (a
- * bare ProofLike) so multi-mint balance views in don't have to
- * back-fill mint information.
- */
+/** Persisted proof with issuing mint and independent NUT-11 lock authority. */
 interface AgentProof {
-    /** Mint URL that issued this proof. */
     mint: string;
     /** Per-proof secret string (NUT-00 / NUT-11 envelope). */
     secret: string;
@@ -5351,7 +5115,6 @@ interface AgentProof {
     C: string;
     /** Denomination, in sats. */
     amount: number;
-    /** Keyset ID under which the proof was issued. */
     id: string;
     /** Optional NUT-12 proof, including the blinding factor needed by enforcing mints. */
     dleq?: SerializedDLEQ;
@@ -5363,12 +5126,8 @@ interface AgentProof {
      * appears on outputs from `dvm wallet release --output unlocked`.
      */
     locked_to_pubkey: string | null;
-    /**
-     * Lifecycle status. `"in_flight"` is set the moment proofs are handed
-     * to a DVM and reverted (or removed on success) once the response lands.
-     * Stale `in_flight` proofs older than `in_flight_until_ms` are returned
-     * to the spendable pool by the next wallet-touching command.
-     */
+    /** Stale in_flight proofs become sweep candidates, except those committed to
+     * pending melts or prepared swaps, whose outcomes require mint evidence. */
     status: "valid" | "in_flight";
     /**
      * Wall-clock millis at which an `in_flight` proof becomes eligible for
@@ -5406,9 +5165,7 @@ interface AgentProof {
 interface AgentRecentSpend {
     /** UUIDv4 used as the per-call replay key (`X-Cashu-Request-Id`). */
     request_id: string;
-    /** HTTPS endpoint of the DVM the spend was sent to. */
     dvm_endpoint: string;
-    /** Mint URL the spent proofs were issued at. */
     mint: string;
     /** Total spend amount, in sats. */
     amount_sats: number;
@@ -5457,7 +5214,6 @@ interface PendingMintMintingState {
  * cleared once those outputs have been signed and persisted as proofs.
  */
 interface PendingMint {
-    /** Mint URL the quote was requested at. */
     mint: string;
     /** Quote ID returned by the mint; passed to `checkMintQuoteBolt11`. */
     quote_id: string;
@@ -5752,7 +5508,7 @@ interface AgentWallet {
     mnemonic_fingerprint: string | null;
     /** Cashu mint URLs the wallet trusts, in selection order. */
     mints: string[];
-    /** Locally-held Cashu proofs, P2PK-locked to `lock_pubkey`. */
+    /** Locally held proofs, with each proof recording its own lock authority. */
     proofs: AgentProof[];
     /**
      * NUT-13 deterministic-secret counters per `(mint_url, keyset_id)`
@@ -5789,31 +5545,10 @@ interface AgentWallet {
     /** ISO-8601 wallet creation timestamp. */
     created_at: string;
 }
-/**
- * Read `~/.dvm/wallet.json` and return the parsed wallet. Returns `null` if
- * the file does not exist. Migrates older wallets in-memory to v9:
- * - v1 → v9: rejects populated proofs/pending_mints (the v1 shape predated
- * the fund flow and is expected to be empty); fresh recent_spends,
- * pending_submissions, nut13_counters; `mnemonic_fingerprint: null`.
- * - v2 → v9: preserves all v2 fields, adds empty recent_spends,
- * pending_submissions, nut13_counters.
- * - v3 → v9: renames recovery_pubkey/recovery_privkey → lock_pubkey/lock_privkey;
- * adds empty pending_submissions, nut13_counters.
- * - v4 → v9: adds empty pending_submissions, nut13_counters
- * - v5 → v9: adds empty nut13_counters and a null mnemonic_fingerprint
- * A v5 wallet inherits NUT-13 inactive — `getWallet` will
- * stay in degraded mode until the user runs `dvm wallet restore
- * <mnemonic>` to re-attach the sibling `~/.dvm/wallet.mnemonic`.
- * - v6 → v9: pass-through for the v7 step. Existing proofs are
- * free-balance, so `reserved_for` and `t_expire` remain unset;
- * `dvm wallet reserve` populates them on new pre-fund proofs.
- * - v7 → v9: adds empty pending_melts. No wallet predating the
- * cash-out verb can have a melt in flight, so an empty list is exact.
- * - v8 → v9: preserves pending mints without `expires_at`; the recovery sweep
- * applies its bounded legacy fallback to those entries.
- * Throws `DvmError("wallet_unknown_version", ...)` for files written by a
- * newer CLI so we never silently corrupt a future schema by treating it as v9.
- */
+/** Missing files return null; earlier supported schemas migrate in memory to v9.
+ * Populated v1 legacy state is refused. Wallets without a bound mnemonic stay
+ * NUT-13 inactive; old pending mints retain missing expiry for recovery fallback.
+ * Unknown versions fail instead of being interpreted as the current schema. */
 declare function loadAgentWallet(): AgentWallet | null;
 /**
  * Atomically write the wallet to `~/.dvm/wallet.json` with mode 0600. The
@@ -5965,16 +5700,7 @@ declare function prepareP2PKMint(cashuWallet: Wallet, sats: number, quote: MintQ
  */
 declare function maxKeysetDenomination(cashuWallet: Wallet): number | undefined;
 
-/**
- * Single source of truth for mint inventory across `dvm wallet show`,
- * `dvm wallet mint-list`, and `dvm wallet mint-health`. All three
- * commands historically disagreed: `mint-add` wrote to `config.cashuMints`
- * while `wallet show` read from `wallet.mints` via `effectiveMints()`, which
- * silently injected {@link DEFAULT_AGENT_MINT_URL} as a fallback. This
- * module makes `wallet.mints` the canonical store and surfaces the implicit
- * default as a labeled `source: "default"` entry rather than conflating it
- * with explicit configuration.
- */
+/** `wallet.mints` is canonical; the implicit default is labeled separately from configuration. */
 
 /**
  * Where an entry in the wallet's displayed mint inventory came from. Shared
@@ -5994,9 +5720,7 @@ declare function maxKeysetDenomination(cashuWallet: Wallet): number | undefined;
  * callers that probe arbitrary URLs against the wallet's configured list.
  */
 type MintSource = "configured" | "default" | "proofs" | "pending" | "ad_hoc";
-/** A single entry in the wallet's displayed mint inventory. */
 interface MintInventoryEntry {
-    /** Mint URL. */
     url: string;
     /** Why this URL appears in the inventory — see {@link MintSource}. */
     source: MintSource;
@@ -6076,11 +5800,9 @@ type SelectError = {
     message: string;
     hint: string;
 };
-/** Successful per-mint selection. */
 interface SelectionResult {
     /** The chosen proofs, in the order they should be sent to the DVM. */
     selected: AgentProof[];
-    /** The mint URL all selected proofs are issued at. */
     mint: string;
     /** Sum of `selected[].amount`, in sats. Equals `amountSats + the swap's reserve` or more — overshoot returns as `keep` change. */
     totalSats: number;
@@ -6159,7 +5881,6 @@ declare function coveringMintsForSpend(args: {
 interface CashuSubmissionBinding {
     /** Immutable DVM identity resolved from the live descriptor. */
     dvmId: string;
-    /** Capability dispatched by the request. */
     capability: string;
     /** Exact unsigned `/v1/job` payload persisted for same-request recovery. */
     requestBody: Record<string, unknown>;
@@ -6326,8 +6047,6 @@ declare const X402_BATCH_CHANNEL_ABI: readonly [{
     }];
 }];
 
-/** Durable caller-side storage for reusable x402 batch-settlement channels. */
-
 /** Immutable channel configuration needed by the unilateral withdrawal verbs. */
 interface StoredX402ChannelConfig {
     payer: `0x${string}`;
@@ -6367,7 +6086,8 @@ interface PendingX402Funding {
      * payer put its name to, and a deposit's authorized value can exceed the funded amount
      * so both are journalled from the payload at signing time
      * rather than recomputed from the request. Optional because entries written
-     * before this field existed are still on disk; every read fails closed.
+     * before this field existed are still on disk; reservation consumers must
+     * handle missing or unreadable authority conservatively.
      */
     maxClaimableMicro?: string;
     /** ERC-3009 value on a deposit payload; absent on a voucher-only payload. */
@@ -6375,7 +6095,7 @@ interface PendingX402Funding {
     /** Unix seconds after which a deposit authorization can no longer be submitted. */
     authorizationValidBefore?: string;
     /**
-     * When a DVM refused this funding in a way it will repeat forever. Marked
+     * A recorded terminal refusal, excluded from verbatim resumption. Marked
      * rather than deleted, because the entry carries two signed things with
      * different lifetimes and only one of them dies on a clock: the
      * ERC-3009 deposit authorization, dead at `authorizationValidBefore`, and the
@@ -6478,12 +6198,9 @@ declare function listResumableX402ExactFundings(filter?: {
  */
 declare function clearPendingX402ExactFunding(pending: PendingX402ExactFunding): void;
 /**
- * How long an unacknowledged voucher reads as "in flight" rather than
- * abandoned. Past it the CLI stops suggesting a retry and starts offering the
- * escape hatch — a threshold for what the caller is told and for what
- * `x402-clear-pending` will retire without `--force`. Never a gate: nothing
- * refuses on age, because a signed authorization is exactly as claimable at 25
- * hours as at 25 minutes.
+ * Age at which an active unacknowledged voucher is reported as abandoned and
+ * may be retired without force. Age alone does not revoke its signed authority.
+ * Retired deposits have a separate authorization-expiry gate.
  */
 declare const X402_PENDING_STALE_MS: number;
 /** Whether an entry has gone long enough unacknowledged to read as abandoned. */
@@ -6624,7 +6341,6 @@ declare function acknowledgeX402ChannelOwner(owner: Pick<StoredX402ChannelMetada
 declare function listX402Channels(filter?: {
     payer?: string;
 }): StoredX402ChannelMetadata[];
-/** Find a channel by id, or by the DVM credit it backs. */
 declare function findX402Channel(args: {
     channelId?: string;
     endpoint?: string;
@@ -6734,22 +6450,19 @@ declare function x402ReservationRelease(journalled: PendingX402Funding[]): {
     retriable: boolean;
 };
 
-/** Caller-side x402 batch-settlement signing, recovery, and cooperative refund. */
-
 /** Signed payment, the channel it advances, and what its signature covers. */
 interface X402BatchPayment extends X402VoucherFacts {
     paymentHeader: string;
     channelId: `0x${string}`;
     scheme: BatchSettlementEvmScheme;
 }
-/** Build one deposit or cumulative voucher from a server challenge. */
 declare function createX402BatchPayment(args: {
     wallet: X402Wallet;
     paymentRequired: PaymentRequired$1;
     endpoint: string;
     callerPubkey: string;
     creditId: string;
-    /** Caller policy size in token micro-units; upstream's 5x default is never used. */
+    /** Deposit policy in token micro-units, raised to upstream's required minimum. */
     depositMicro: number;
 }): Promise<X402BatchPayment>;
 /**
@@ -6789,41 +6502,17 @@ interface X402ChannelReconciliation {
     /** What the contract says has already been claimed out of it. */
     totalClaimedMicro: string;
     /**
-     * The refused fundings journalled on this channel at the moment of the read.
-     *
-     * Deliberately not a list of amounts being taken back off. No refused funding
-     * ever added to the stored balance in the first place, and the chain figure
-     * replaces the whole projection rather than reversing anything entry by
-     * entry — so these ids say which journal the repair was taken beside, not
-     * what it subtracted.
-     *
-     * At least one of them is provably lapsed and unconsumed. One, not all:
-     * `channels()` answers for the entire channel, so the probe stops at the
-     * first proof and the rest carry no claim about their own deadlines or
-     * nonces, including ones still inside their validity window.
+     * Refused candidate IDs associated with replacing the whole-channel projection,
+     * not individually subtracted amounts. Only one is necessarily proven expired
+     * and unused; the remaining authorizations may still be live.
      */
     fundIds: string[];
 }
 /**
- * Take a refused funding's deposit back off the stored channel balance, once
- * its ERC-3009 authorization has provably lapsed unconsumed.
- *
- * The repair is a `channels()` read rather than arithmetic, for the same reason
- * every money decision on this rail already reads the chain: the stored figure
- * is a running local sum with no audit trail, so subtracting from it would
- * produce a second guess rather than an answer. Overwriting it with what the
- * contract holds is the only move that ends with the projection *equal* to
- * chain rather than merely less wrong.
- *
- * The proof is {@link canReplaceExpiredX402Deposit}'s, unchanged: the
- * authorization is past its deadline and its nonce was never consumed, so the
- * deposit can no longer land and never did. Without it the read would be a
- * race — a deposit still in flight reads as absent one block before it settles,
- * and writing that back would push the projection *below* chain.
- *
- * `chargedCumulativeAmount` is deliberately untouched. It is the base the next
- * voucher signs from, and lowering it to a figure the DVM has already exceeded
- * is how a caller signs a cumulative cap that reads as a replay.
+ * Replace the channel projection from `channels()` only after a refused deposit
+ * is expired and its nonce proven unused. Subtracting a local deposit would
+ * not establish chain truth; reading while it can still land races submission.
+ * Keep the authorized cumulative cursor, which the DVM may already have used.
  */
 declare function reconcileRefusedX402Deposits(args: {
     wallet: X402Wallet;
@@ -6859,18 +6548,14 @@ interface X402RefundOutcome {
  * while returning the DVM's credit result to the CLI.
  */
 declare function refundX402BatchChannel(args: X402RefundArgs): Promise<X402RefundOutcome>;
-/** What the drain needs to find the channel it is closing, and to close it. */
 interface X402RefundArgs {
     wallet: X402Wallet;
     endpoint: string;
-    /** Caller identity the channel was recorded under, half of the metadata key. */
     callerPubkey: string;
-    /** DVM credit the channel backs — the other half. */
     creditId: string;
     depositMicro: number;
     post: (paymentHeader?: string) => Promise<CreditOpResult>;
 }
-/** Read a decoded x402 challenge attached by the HTTPS transport. */
 declare function x402RequiredFromError(err: DvmError): PaymentRequired$1 | undefined;
 /**
  * Assert that a DVM challenge still derives the channel recorded for this
@@ -6884,7 +6569,6 @@ declare function assertX402RequirementDescribesChannel(args: {
     depositMicro: number;
 }): void;
 
-/** x402 private-key environment variables understood by the shared validator. */
 declare const X402_SELF_RELAY_KEY = "DVMKIT_X402_SELF_RELAY_KEY";
 declare const X402_RECEIVER_AUTHORIZER_KEY = "DVMKIT_X402_RECEIVER_AUTHORIZER_KEY";
 declare const X402_BATCH_SETTLEMENT_KEY = "DVMKIT_X402_BATCH_SETTLEMENT";
@@ -6894,7 +6578,6 @@ interface X402DerivedAddresses {
     relay?: `0x${string}`;
     authorizer?: `0x${string}`;
 }
-/** Options for validating a complete environment or a write-only environment patch. */
 interface X402EnvValidationOptions {
     /** Require a key-rotation patch to carry every value needed for proof. */
     requireCompleteBundle?: boolean;
@@ -6905,15 +6588,12 @@ interface X402EnvValidationOptions {
 }
 /** Safe validation failure which names variables and public addresses, never private values. */
 declare class X402EnvValidationError extends Error {
-    /** Machine-readable validation code. */
     readonly code: string;
     /** Environment variable whose value or dependency failed validation. */
     readonly variable: string;
     /** Expected public address, when the failure was an address mismatch. */
     readonly expectedAddress?: string | undefined;
-    constructor(
-    /** Machine-readable validation code. */
-    code: string, 
+    constructor(code: string, 
     /** Environment variable whose value or dependency failed validation. */
     variable: string, message: string, 
     /** Expected public address, when the failure was an address mismatch. */
@@ -6928,23 +6608,11 @@ declare class X402EnvValidationError extends Error {
  */
 declare function validateX402Env(env: Record<string, string | undefined>, opts?: X402EnvValidationOptions): X402DerivedAddresses;
 
-/**
- * The chains the x402 rail settles on — one row each, and the only place a
- * chain is described.
- *
- * This file exists because the rail used to describe a chain in four places: a
- * contract map and two EIP-712 domain maps in `spec.ts`, a viem chain-loader
- * map in `wallet.ts`, and a label/confusable pair in `asset.ts`. They drifted —
- * the loader map carried two chains, the contract map six — so `--network`
- * accepted five chains the balance read then threw on, and a funded Polygon
- * wallet reported as unreachable. A row here is the whole description of a
- * chain; a chain the rail can't do everything for doesn't get one.
- */
 /** Everything the x402 rail needs to know about one settlement chain. */
 interface X402Network {
     /** CAIP-2 chain id — the form the caller wallet and DVM configs are written in. */
     caip2: string;
-    /** x402-spec network slug — the form the facilitator API speaks. */
+    /** Legacy v1 network slug; v2 uses CAIP-2. */
     slug: string;
     /** Human name for copy ("Base"). */
     label: string;
@@ -6969,27 +6637,9 @@ interface X402Network {
      * test pins it against viem so the two can't drift.
      */
     nativeGas: string;
-    /**
-     * Ticker of the dollar most often confused for the native one here, or null
-     * where there isn't a well-known one.
-     *
-     * Every mainnet listed predates Circle issuing natively on it, so each
-     * carries a widely-held bridged dollar from that era: USDbC on Base, USDC.e
-     * on Polygon (the PoS-bridge dollar) and on Avalanche (the Avalanche-bridge
-     * dollar). All three still appear in wallet and exchange menus, and none is
-     * spendable here. Testnets are null — nobody holds a bridged testnet dollar
-     * by accident.
-     */
+    /** Bridged token commonly confused with native USDC, or null if unnamed. */
     confusable: string | null;
 }
-/**
- * Every chain the rail supports end to end: a USDC contract to settle against,
- * an EIP-712 domain to sign with, and a viem chain to read the balance on.
- *
- * Adding a row is the whole job of adding a chain. Dropping one of the three
- * facts is what this table exists to prevent, and `networks.test.ts` fails a
- * row whose `viemChain` doesn't resolve to a chain with the matching id.
- */
 declare const X402_NETWORKS: readonly X402Network[];
 /** Look up a chain by CAIP-2 id (`eip155:8453`). Undefined when unsupported. */
 declare function x402NetworkByCaip2(caip2: string): X402Network | undefined;
@@ -7020,33 +6670,8 @@ declare function x402SupportedNetworksHint(): string;
 
 declare function loadX402Wallet(): X402Wallet | null;
 declare function ensureAddress(wallet: X402Wallet): Promise<X402Wallet>;
-/**
- * The payer address the configured x402 key pays as, or `null` when no usable
- * key is configured.
- *
- * A purely local read, and the x402 twin of `connectedTempoAccount`: every
- * channel record names the payer that opened it, so "is this channel this
- * wallet's" is answerable with no chain call and no network at all, which is
- * what lets `dvm doctor` answer it under `--no-network`.
- *
- * A key too malformed to derive an address from reads as no key, exactly as its
- * Tempo twin does. It is the one answer that can't mislead here: the reporting
- * surfaces say "nothing on this machine can withdraw these channels", which is
- * true of an unusable key, and the shape of the key itself is `dvm doctor`'s
- * `config_x402_shape` row to report rather than this one's.
- */
+/** Local ownership read; returns null for an absent or unusable configured key. */
 declare function connectedX402Payer(): Promise<string | null>;
-/**
- * Mint a fresh EVM private key for the x402 rail.
- *
- * The caller shouldn't have to manufacture and transport a 32-byte secret to
- * get onto a rail — `dvm wallet x402-connect` with no key source calls this,
- * exactly as `dvm wallet tempo-connect` calls `generateTempoKey`. viem's
- * generator is the one implementation; it reads from the platform CSPRNG.
- *
- * The key goes straight into `saveX402Wallet` and is never returned to an
- * output surface — only the address derived from it is.
- */
 declare function generateX402PrivateKey(): Promise<`0x${string}`>;
 /** What `saveX402Wallet` persisted — the derived address and the chain it resolved to. */
 interface X402ConnectedWallet {
@@ -7574,22 +7199,12 @@ declare function railLabelAtSentenceStart(label: string): string;
 /** Quote one argument for safe copy/paste into a POSIX shell command. */
 declare function shellQuoteArg(value: string): string;
 
-/**
- * Verify a BIP-340 Schnorr signature against a 32-byte challenge and a
- * compressed (33-byte, `02`/`03` prefix) or x-only (32-byte) public key.
- * Compressed inputs have their parity byte dropped — BIP-340 keys are
- * x-only — and the y-coordinate is recomputed inside cashu-ts when
- * needed.
- */
+/** BIP-340 verification accepts compressed or x-only public keys; compressed parity bytes are dropped. */
 declare function verifyChallenge(pubkeyHex: string, challenge: Uint8Array, sigHex: string): boolean;
 
 /**
- * Root for the consumer CLI's state — wallet mnemonic, proofs, budget, jobs.
- *
- * Defaults to `~/.dvm`. The `DVM_CONFIG_DIR` env override lets an operator
- * run a parallel state tree (e.g. `DVM_CONFIG_DIR=~/.dvm-test`) without
- * touching their real wallet. Resolved once at import time;
- * setting the env after the process boots has no effect.
+ * Caller state defaults to ~/.dvm; DVM_CONFIG_DIR redirects it at import time.
+ * Builder state is independently redirected, so the two identities stay separate.
  */
 declare const CONFIG_DIR: string;
 declare const CONFIG_FILE: string;
@@ -7663,10 +7278,8 @@ declare const FEEDBACK_NUDGES_FILE: string;
 declare const RECOVERY_MNEMONIC_FILE: string;
 declare const WALLET_FILE: string;
 /**
- * Sibling file holding the agent wallet's BIP-39 mnemonic (mode 0600). The
- * mnemonic stays out of `wallet.json` per §4.6 of the cashu-from-first-
- * principles design note; only its `mnemonic_fingerprint` lives on the
- * wallet record. Mirrors the builder pattern at {@link BUILDER_MNEMONIC_FILE}.
+ * Agent BIP-39 mnemonic, mode 0600. Kept outside wallet.json so resetting
+ * proof state does not discard the recovery identity.
  */
 declare const AGENT_MNEMONIC_FILE: string;
 /**
@@ -8017,7 +7630,6 @@ declare function redactUrl(url: string): string;
  */
 declare function redactUrlsInText(text: string): string;
 
-/** Outcome of a {@link writeAgentMnemonic} call. */
 interface WriteAgentMnemonicResult {
     /**
      * Path of the timestamped 0600 copy of the mnemonic that was replaced, or
@@ -8192,11 +7804,8 @@ interface CashOutMintOptions {
 declare function cashOutFromMint(opts: CashOutMintOptions): Promise<CashOutMintOutcome>;
 declare function spendableAt(proofs: AgentProof[], mintUrl: string): AgentProof[];
 
-/** Return value from {@link sweepStaleInFlight}. */
 interface InFlightSweepResult {
-    /** New wallet object with stale `in_flight` proofs reverted. */
     wallet: AgentWallet;
-    /** Number of proofs swept back to `valid`. */
     reverted: number;
 }
 /**
@@ -8218,7 +7827,6 @@ interface InFlightSweepResult {
  */
 declare function sweepStaleInFlight(wallet: AgentWallet, nowMs: number): InFlightSweepResult;
 
-/** Regex for a 32-byte secp256k1 private key in lowercase or mixed-case hex. */
 declare const PRIVKEY_HEX_RE: RegExp;
 /**
  * Derive the compressed secp256k1 public key from a hex-encoded private key.
@@ -8256,9 +7864,7 @@ declare function formatLocktime(seconds: number): string;
 
 /** Why the selector replaced the preferred funding mint. */
 type FundFallbackKind = "health" | "capability" | "bounds" | null;
-/** Details of a preferred mint replaced by a configured alternative. */
 interface FundMintFallback {
-    /** Mint the caller would otherwise have used. */
     preferred: string;
     /** Configured mint selected for this amount. */
     selected: string;
@@ -8266,7 +7872,6 @@ interface FundMintFallback {
     reason: string;
 }
 interface FundMintSelection {
-    /** Mint URL the caller should use for the fund operation. */
     url: string;
     /** Category of fallback, or `null` when the preferred mint was selected. */
     fallbackKind: FundFallbackKind;
@@ -8275,7 +7880,6 @@ interface FundMintSelection {
     /** Present when an alternative replaced the preferred mint. */
     fallback?: FundMintFallback;
 }
-/** Inputs for {@link resolveFundMint}. */
 interface ResolveFundMintOptions {
     /** Mint selected by the caller or wallet configuration. */
     preferred: string;
@@ -8297,7 +7901,6 @@ interface ResolveFundMintOptions {
  * manual fund flow has always exposed.
  */
 declare function resolveFundMint(args: ResolveFundMintOptions): Promise<FundMintSelection>;
-/** Format advertised issuance bounds for caller-facing explanations. */
 declare function describeMintBounds(bounds: MintAmountBounds | undefined): string;
 
 /** The agent master keypair derived from a BIP-39 mnemonic. Both halves are hex. */
@@ -8307,7 +7910,6 @@ interface AgentMasterKeypair {
     /** 33-byte compressed secp256k1 public key, lowercase hex (66 chars). */
     pubkey: string;
 }
-/** Structured result of validating a candidate BIP-39 mnemonic. */
 type MnemonicValidationResult = {
     ok: true;
 } | {
@@ -8325,13 +7927,7 @@ type MnemonicValidationResult = {
 };
 /** Generate a fresh 12-word BIP-39 mnemonic for a new agent wallet. */
 declare function generateAgentMnemonic(): string;
-/**
- * Derive the agent master keypair from a BIP-39 mnemonic at `m/1789'/1'`.
- *
- * The privkey is the wallet's signing identity (what we store today as
- * `lock_privkey` in `~/.dvm/wallet.json`). The mnemonic itself is never
- * persisted — the user is responsible for backing it up out-of-band.
- */
+/** The wallet signing identity at `m/1789'/1'`; persistence is handled separately. */
 declare function deriveAgentMasterKeypair(mnemonic: string): AgentMasterKeypair;
 /**
  * Validate a candidate mnemonic and report which check failed, so the CLI can
@@ -8432,41 +8028,15 @@ interface ToAgentProofTags {
 /** Convert a cashu-ts proof into the lossless agent-wallet disk shape. */
 declare function toAgentProof(proof: Proof, mintUrl: string, lockedTo: string | null, tags?: ToAgentProofTags): AgentProof;
 
-/**
- * Claim an external Cashu token into the agent wallet. This is the
- * single supported path for taking an inbound token (a refund/change token a
- * DVM delivered, or a token handed over out-of-band) into spendable agent-
- * wallet balance — it replaces the deleted legacy `dvm wallet deposit --token`
- * plain-Cashu rail.
- *
- * The incoming swap is signed with the agent's master private key when a
- * NUT-11 P2PK lock's currently-required witness set includes the agent's
- * master pubkey, and its outputs are
- * **re-locked to that same** `lock_pubkey`. Plain proofs and expired P2PK locks
- * without a refund path pass the preflight: plain secrets are not NUT-11, and
- * cashu-ts reports no currently-required witness for the latter. An expired
- * lock with a refund path still exposes expected refund witnesses and is
- * checked against the agent's master key. This input-lock check is separate
- * from the wallet's `reserved_for` bookkeeping used by spend selection.
- *
- * A token P2PK-locked to a third party (one whose currently-required witness
- * pubkey the agent doesn't hold) is rejected up-front with `cashu_not_claimable`
- * rather than attempted-and-lost — a token locked to the agent's own key is
- * claimable (the agent signs the witness).
- */
-
 interface ReceiveResult {
-    /** Mint the token was claimed against. */
     mintUrl: string;
     /** Total sats claimed into spendable balance. */
     claimedSats: number;
-    /** Number of proofs persisted. */
     proofCount: number;
 }
 interface ReceiveOptions {
     /** Override `getWallet` for tests. */
     getWalletForMint?: (mintUrl: string) => Promise<Wallet>;
-    /** `Date.now` override for tests (locktime-expiry check). */
     now?: () => number;
 }
 /**
@@ -9112,19 +8682,7 @@ declare function abandonPendingSubmission(args: {
     requestId: string;
 }): Promise<void>;
 
-/**
- * Shared prose for a rail's status, so `dvm doctor` and `dvm wallet balance`
- * describe the same failure with the same words.
- *
- * The probe layer (`wallet-probe.ts`) stays data-only; this is the rendering
- * half — what to call a rail, and what to say when one is configured but the
- * balance couldn't be read.
- *
- * The channel-exit refusals in `payment-rails/tempo-session.ts` render their
- * key-import advice from here too. Same reason, one surface wider:
- * a caller meets that advice from doctor, from a balance row and from a failed
- * exit, and three copies of it drifted onto two different import routes.
- */
+/** Rendering stays separate from data-only probes; status and recovery hints share this vocabulary. */
 
 /**
  * ` via <endpoint>` for a balance a rail read over RPC, else `""`.
@@ -9140,24 +8698,9 @@ declare function rpcEndpointSuffix(rail: RailProbe): string;
  * for a rail that read no endpoint.
  */
 declare function rpcEndpointLine(rail: RailProbe): string | null;
-/**
- * The one-line diagnosis for a rail that is configured but wasn't reachable.
- *
- * "Not reachable" is the honest summary of an RPC that didn't answer, and a
- * wrong one for a wallet pinned to a chain this rail was never able to serve:
- * nothing is down, and no amount of retrying or reinstalling viem will change
- * the answer. The probe distinguishes them, so the copy does too.
- */
+/** Unsupported chains need configuration changes rather than an unreachable-RPC diagnosis. */
 declare function unreachableRailDisplay(rail: RailProbe): string;
-/**
- * The diagnosis line for an NWC connection the wallet *answered* and rejected,
- * or null for any other failure.
- *
- * "Not reachable" is wrong twice over here: the wallet is up and talking, and
- * the two rejections it can send want opposite things done about them. A
- * revoked connection has to be recreated; a restricted one exists, works, and
- * needs a permission or a higher cap — recreating that one reproduces it.
- */
+/** Revoked connections need replacement; restricted connections need permission or budget changes. */
 declare function nwcRejectionDisplay(rail: RailProbe): string | null;
 /**
  * The remedy for an unreachable rail. A probe that diagnosed the failure
@@ -9166,52 +8709,15 @@ declare function nwcRejectionDisplay(rail: RailProbe): string | null;
  */
 declare function unreachableRailHint(rail: RailProbe): string;
 /**
- * The routes that put a Tempo private key back on this machine, as a
- * parenthetical a recovery hint drops into a sentence.
- *
- * Written once because six hints across `dvm doctor`, `dvm wallet balance` and
- * the channel-exit path each carried their own copy, and all six named
- * `--api-key <key>` — a flag whose value lands in shell history, `ps`,
- * `/proc/<pid>/cmdline` and any agent transcript that reads a command line back
- * Every one of them fires with real collateral locked behind a key
- * this machine no longer holds, which is the worst moment to teach that route.
- * Named routes only: `DVM_TEMPO_KEY` and `--key-file` mirror what the x402 twin
- * publishes, so a caller crossing rails reads one shape.
- *
- * `replacingConnectedKey` is a liveness question, not a stylistic one. A hint
- * that is safe but names a command the current state refuses has only traded
- * one defect for another, and `tempo-connect` refuses to import over
- * a wallet already configured without `--force`. Both sides judge "configured"
- * with the same secp256k1 scalar validator — `tempoAccountFromConfig` for the
- * connected account, `walletMppConnect` for the guard — so "a key is connected"
- * and "the import needs `--force`" are the same fact, and the caller passes it
- * exactly when they have one.
+ * Key-import hints use a file or environment variable rather than a positional spending key.
+ * Replacing an already connected key requires --force so the suggested command can run.
  */
 declare function tempoKeyImportRoutes(opts: {
     replacingConnectedKey: boolean;
 }): string;
-/**
- * The whole hint for a chain-touching Tempo exit leg with no key to sign it.
- *
- * A constant rather than a sentence written twice: `advanceTempoChannelExit`
- * and `dvm wallet tempo-exit` refuse this same state one call apart, and their
- * two copies had already drifted — the caller's route was migrated off argv in
- * one and left on `--api-key` in the other. No `--force`, because
- * nothing reached this line with a key connected.
- */
+/** With no connected key to replace, the exit recovery hint omits --force. */
 declare const TEMPO_EXIT_KEY_MISSING_HINT: string;
 
-/**
- * Naming the dollar the x402 rail actually reads, so a wrong-asset or
- * wrong-chain balance stops reading as a plain `$0.00`.
- *
- * Mirrors the Tempo shape landed in `payment-rails/tempo-wallet.ts`
- * one resolver, one shared hint string, no copy literals at the
- * print sites — with the one structural difference that x402 is multi-network:
- * the settlement contract is a function of the wallet's configured chain, so
- * the copy has to name the network as well as the token.
- */
-
 /** The USDC the x402 rail reads on one configured network. */
 interface X402Asset extends RailAsset {
     /** Human network name for copy ("Base"); the CAIP-2 id when we can't name it. */
@@ -9224,17 +8730,7 @@ interface X402Asset extends RailAsset {
      */
     confusable: string | null;
 }
-/**
- * Resolve the USDC the rail reads on `network`, defaulting to the same Base
- * chain id the wallet loader does.
- *
- * Returns null — rather than throwing, as `resolveTempoAsset` does on a bad
- * override — for a network outside the supported table. `--network` rejects
- * those at connect time, so the only way to reach this branch is a
- * config persisted before that validation existed; here it means "we have no
- * name to print", and a status surface must not abort over copy it merely
- * wanted.
- */
+/** Returns null for unsupported networks so read-only naming can omit the asset. */
 declare function resolveX402Asset(network?: string): X402Asset | null;
 /**
  * Why a funded-looking x402 wallet reads zero: the rail reads one contract on
@@ -9287,7 +8783,6 @@ interface X402ChannelRpc {
  */
 declare function resolveX402ChannelRpc(channelNetwork: string, configuredNetwork: string, bundled: string | undefined): X402ChannelRpc;
 
-/** Inputs for `tryX402Payment`. */
 interface X402PaymentRequest {
     amountMsats: number;
     /**
@@ -9300,7 +8795,6 @@ interface X402PaymentRequest {
     payTo: string;
     /** CAIP-2 chain id (`eip155:8453`). */
     network: string;
-    /** Asset ticker or contract address. Defaults to USDC for known networks. */
     asset?: string;
     /** Versioned challenge selected from `PAYMENT-REQUIRED` or the legacy 402 body. */
     paymentRequired?: PaymentRequired;
@@ -9324,9 +8818,8 @@ interface X402PaymentRequest {
      */
     btcRate?: number;
 }
-/** Successfully-signed x402 payment header (base64 PaymentPayload). */
 interface X402PaymentProof {
-    /** Base64-encoded payment-header value. */
+    /** Base64-encoded payment payload for the selected protocol header. */
     paymentHeader: string;
     /** Protocol version that selects `PAYMENT-SIGNATURE` (v2) or `X-PAYMENT` (v1). */
     x402Version: X402Version;
@@ -9338,70 +8831,21 @@ interface X402PaymentProof {
     btcRate: number;
 }
 /**
- * Sign an EIP-3009 `TransferWithAuthorization` against the USDC contract on
- * the resolved EVM chain and encode it as an x402 `X-PAYMENT` header
- * (replaces the legacy custom EIP-712 path that shipped pre-spec).
- *
- * Returns `null` to signal "fall through to the next rail" — preserves the
- * upstream responder's chained-fallback semantics for callers that hold
- * multiple wallets. Throws `DvmError("x402_build_failed", ...)` on any
- * unexpected failure (RPC, viem signing, malformed wallet) so the failure
- * surfaces with a stable code instead of a silent `null`; callers
- * that want soft fall-through should catch and continue.
- *
- * The server's advertised `requiredUsdcMicro` is authoritative for the signed
- * amount. The caller still resolves a BTC/USD rate to refuse an advertisement
- * more than 10% above its own conversion and to book the actual signed amount
- * in the msat-denominated ledger. The rate comes from `request.btcRate` when
- * the caller already resolved one, else from `resolveBtcUsdRate` — which serves
- * the last cached rate when CoinGecko is down.
- *
- * With no rate *anywhere* this rail simply can't quote a USDC amount, so it
- * soft-falls-through like any other unbuildable payload. Only an uncapped
- * caller reaches that state — `enforceGlobalBudget` hard-fails a capped one
- * upstream — and Lightning, ordered after x402, can still settle the spend the
- * ledger already agreed to let through. Tempo answers a missing rate the same
- * way x402 does, for the same reason: it prices in dollars too, so with no rate
- * there is nothing to check the DVM's advertisement against.
+ * Signs the selected USDC amount and returns a v1 or v2 payment header. Refuses
+ * malformed or excessive advertisements before signing. Unsupported networks
+ * or an unavailable BTC/USD rate return null for rail fallback; build failures
+ * have a typed error. A cached rate can price the ceiling and budget ledger.
  */
 declare function tryX402Payment(request: X402PaymentRequest, wallet: X402Wallet): Promise<X402PaymentProof | null>;
 
 /**
- * The safety preflight that stands between the caller's x402 key and the funds
- * only that key can move.
- *
- * A reusable batch-settlement channel is keyed by a salt derived
- * from the payer address, and the contract will only pay a withdrawal out to
- * the payer that opened it. So replacing `config.x402.privateKey` — or deleting
- * it — is not a settings change: any channel balance the old key still controls
- * becomes unreachable, behind a timed exit nobody holds the key for.
- *
- * The check is therefore fail-closed and grounded in chain state rather than in
- * what the local journal remembers. A cooperatively drained channel leaves its
- * metadata behind forever; refusing on metadata alone would make the caller's
- * first rotation impossible. Refusing only when the chain says the channel
- * still holds value — or that a timed withdrawal is mid-flight — is the line
- * that is both safe and eventually passable.
- *
- * The other half of the same protection — a signed voucher still waiting for
- * its acknowledgement — is journal state rather than chain state, and
- * already owns it in `wallet-x402.ts` alongside `x402-clear-pending`, the one
- * command that discards such a voucher on purpose. This module deliberately
- * doesn't second-guess it: chain state read a moment ago cannot speak for a
- * header that is still replayable, and one refusal is easier to act on.
- *
- * The same question read the other way round — given *this* channel, may the
- * currently connected wallet move it — is {@link assertX402ChannelPayer},
- * shared by both exits so a caller who reconnected reads one sentence rather
- * than two dialects of it. There is deliberately no chain twin of it: both
- * exits now follow the channel onto the chain it was opened on, so a re-pin
- * costs the caller nothing.
+ * Key replacement and disconnect require chain proof that every owned channel
+ * has neither collateral nor a pending withdrawal. Local metadata survives
+ * drainage, so its presence alone cannot block key rotation. Pending signed
+ * vouchers are guarded separately: a chain read cannot revoke their authority.
  *
- * The reporting direction of the same read is {@link readX402ChannelOnChain},
- * which the caller's read surfaces use to say what the contract holds for each
- * recorded channel. It shares this module's chain seam and inverts
- * only its posture on failure: a guard that cannot read refuses, a report that
- * cannot read says so and carries on.
+ * Exits and reports follow each channel's recorded chain. Guards fail closed
+ * when reads fail; reports retain the failure and continue with other rails.
  */
 
 /** What the caller is about to do to the configured key — drives the remedy copy. */
@@ -9493,45 +8937,12 @@ interface X402ChannelClient {
     }) => Promise<readonly [bigint, number | bigint] | bigint>;
 }
 /**
- * Report what the settlement contract holds for one recorded channel, without
- * ever failing the command that asked.
- *
- * The reporting twin of {@link assertX402WalletIdle}: same chain seam, opposite
- * posture on failure. A guard that cannot reach the chain has to refuse, since
- * silence is not evidence a channel is empty; a balance report that cannot
- * reach it has to say so and go on reporting the rest of the wallet, or one
- * unreachable chain hides every other rail the caller holds.
- *
- * The verdict rests on the contract's own views. `pendingWithdrawals` outranks
- * everything, because a timed exit in its delay window is the state a caller
- * has an unfinished action in. Otherwise escrow the contract still accounts for
- * is `open`. With none, the question is whether the contract has ever seen this
- * channel, and two counters answer it: `totalClaimed`, which nothing resets,
- * and `refundNonce`, which only ever increments. Either being non-zero makes it
- * `closed` — a channel that ran its course rather than one that never existed.
- *
- * One case defeats all of them, and the copy on an `unconfirmed` row is written
- * around it: a channel funded, never claimed, never refunded, and then emptied
- * through the timed exit. `finalizeWithdraw` sets `ws.amount = 0` and
- * `ws.initiatedAt = 0` and decrements `balance`, so every view reads zero and
- * the contract is genuinely indistinguishable from one that never held the
- * channel at all. `unconfirmed` therefore means "the contract holds nothing and
- * cannot say why", not "the deposit never landed", and the row must not assert
- * the second.
- *
- * The two verdicts where the contract's zero is an absence rather than a
- * balance — `unconfirmed`, and `unreadable` where it answered nothing at all —
- * fall back to the caller's own stored figure instead, exactly as the Tempo
- * rows do. That figure is the one taught the store to distrust, so a
- * row reporting it also reports {@link X402ChannelChainReport.balanceUnreconciledAt}
- * when it carries the stamp. Reporting an assumption as an observation in the
- * one case the chain cannot correct it is what that stamp exists to prevent.
- *
- * Broadcasts nothing: every chain call here is a `view`. A successful read
- * writes its authoritative balance and claimed total back to the local
- * projection; a failed read changes nothing. Unlike the Tempo twin there is no
- * retirement to perform — the x402 record is the only local copy of the
- * channel config a timed exit needs, and no chain state makes it safe to drop.
+ * Report contract views without broadcasting. Successful views attempt to write
+ * authoritative balance and claimed total locally; failed reads use available local
+ * fallback figures and retain their unreconciled provenance stamp. For all-zero
+ * views, refundNonce distinguishes a refunded channel when readable; otherwise
+ * unconfirmed means the contract cannot establish its history. Keep config for
+ * timed exits even after a terminal observation.
  */
 declare function readX402ChannelOnChain(args: {
     channel: StoredX402ChannelMetadata;