@dvmkit/sdk 0.7.0-rc.1 → 0.7.0-rc.3

package/README.md

@@ -92,12 +92,16 @@ Builders can pass `onPaidJobCompleted` to observe settled customer charges after
 - A `credit` block opts into reusable prepaid balances and their reclaim obligations. Reusable channels return undrawn collateral through their channel lifecycle; one-payment stablecoin funding is disabled unless `allowOneShotStablecoin: true` because it creates manual refunds. Run and monitor the documented reclaim/payout worker.
 - Honour `ctx.signal`, use `ctx.fetch` for abortable provider calls, and declare provider cost with `ctx.cost` only after the durable step that incurred it.
 
+Reusable x402 channels default to a 24-hour payer withdrawal grace (86400 seconds) on every network. For Base Sepolia (`eip155:84532`) acceptance tests, set `x402.batchSettlement.withdrawDelay: 900` or `DVMKIT_X402_WITHDRAW_DELAY_SECONDS=900` with `DVMKIT_X402_BATCH_SETTLEMENT=true`. Explicit delays must be integer seconds and at least 900 on Base Sepolia; Base mainnet retains the 86400 minimum even in development mode and still requires self-relay. The grace is bound into each channel's immutable configuration: changing the server setting affects new channels, not existing deposits. A shorter testnet run exercises early-withdrawal refusal and post-deadline recovery; retain a separate 24-hour run to cover next-day recovery.
+
 For Bitcoin credit monitoring, `GET /admin/credit/bitcoin-liability` reports exact in-kind obligations in satoshis. Uncovered and basisless credits need live-rate pricing on reclaim, so their whole balances appear in `uncovered_by_currency` and `unbacked_by_currency` as `{ currency, micro, credits }` entries. Sum the credit counts if useful, but display or price each currency separately. Older consumers must replace the former `uncovered_micro` and `unbacked_micro` scalar reads; the [portable response fixture](./protocol-fixtures/bitcoin-liability.json) shows the full shape.
 
 The public [SDK guide](https://dvmkit.com/docs/sdk) covers signed requests, custom routes, rail configuration, credit reclaim, persistence, and deployment in depth. The [protocol guide](https://dvmkit.com/docs/protocol) specifies the HTTP contract.
 
 ## Diagnostic retention
 
+[Payment diagnostics](./docs/DIAGNOSTICS.md) documents the closed failure categories, stages, and top-up causes retained by safe logging sinks.
+
 The SDK advertises 730 days of retention for sanitized diagnostics in every existing span dataset: `platform`, `cashu`, `lightning`, `stripe`, `x402`, `tempo`, `isolate`, `audit`, and `cron`. Dataset names, producer permissions, and query semantics remain unchanged; only operator services may write to `audit`.
 
 This metadata describes the retention schedule. The SDK does not automatically delete diagnostics or override platform destruction or case controls. The platform must enforce the schedule and those controls.

package/dist/{chunk-S3OY533W.js → chunk-26W6GPCD.js}

@@ -1,9 +1,34 @@
 import {
   X402_DEFAULT_FACILITATOR
-} from "./chunk-CXCQLOOK.js";
+} from "./chunk-62FI3NJF.js";
 import {
   callerLoggers
-} from "./chunk-66HGCPBU.js";
+} from "./chunk-KXWROQGK.js";
+import {
+  diagnosticConsole
+} from "./chunk-LAKP6FUI.js";
+
+// src/observability/payment-diagnostics.ts
+import { AsyncLocalStorage } from "async_hooks";
+var scopes = new AsyncLocalStorage();
+function withPaymentDiagnostics(fn) {
+  return scopes.run({}, fn);
+}
+async function withPaymentStage(stage, fn) {
+  try {
+    return await fn();
+  } catch (error) {
+    const scope = scopes.getStore();
+    if (scope && (!scope.failure || !Object.is(scope.failure.error, error))) {
+      scope.failure = { error, stage };
+    }
+    throw error;
+  }
+}
+function paymentFailureStage(error) {
+  const failure = scopes.getStore()?.failure;
+  return failure && Object.is(failure.error, error) ? failure.stage : "unknown";
+}
 
 // src/lib/x402/facilitator.ts
 import { createPrivateKey, randomBytes } from "crypto";
@@ -82,7 +107,7 @@ async function verifyWithFacilitator(payload, requirements, config = {}, createA
   return callerLoggers.x402.span(
     "x402.verify_with_facilitator",
     { facilitator_url: url },
-    async () => {
+    () => withPaymentStage("verifier", async () => {
       const authHeaders = (await createAuthHeaders?.())?.verify ?? {};
       const res = await fetch(url, {
         method: "POST",
@@ -96,14 +121,17 @@ async function verifyWithFacilitator(payload, requirements, config = {}, createA
       if (!res.ok) {
         const rejection = await readFacilitatorRejection(res);
         if (rejection?.isValid === false && typeof rejection.invalidReason === "string" && rejection.invalidReason.length > 0) {
+          logRejected("verifier");
           return rejection;
         }
+        logRejected("verifier");
         return { isValid: false, invalidReason: `facilitator_status_${res.status}` };
       }
       const data = await res.json();
+      if (!data.isValid) logRejected("verifier");
       callerLoggers.x402.info("x402.verify_with_facilitator.result", { is_valid: data.isValid });
       return data;
-    }
+    })
   );
 }
 async function settleWithFacilitator(payload, requirements, config = {}, createAuthHeaders = createX402FacilitatorAuthHeaders(config)) {
@@ -112,7 +140,7 @@ async function settleWithFacilitator(payload, requirements, config = {}, createA
   return callerLoggers.x402.span(
     "x402.settle_with_facilitator",
     { facilitator_url: url },
-    async () => {
+    () => withPaymentStage("broadcast", async () => {
       const authHeaders = (await createAuthHeaders?.())?.settle ?? {};
       const res = await fetch(url, {
         method: "POST",
@@ -126,17 +154,20 @@ async function settleWithFacilitator(payload, requirements, config = {}, createA
       if (!res.ok) {
         const rejection = await readFacilitatorRejection(res);
         if (rejection?.success === false && typeof rejection.errorReason === "string" && rejection.errorReason.length > 0) {
+          logRejected("broadcast");
           return rejection;
         }
+        logRejected("broadcast");
         return { success: false, errorReason: `facilitator_status_${res.status}` };
       }
       const data = await res.json();
+      if (!data.success) logRejected("broadcast");
       callerLoggers.x402.info("x402.settle_with_facilitator.result", {
         success: data.success,
         tx_hash: data.transaction
       });
       return data;
-    }
+    })
   );
 }
 async function readFacilitatorRejection(res) {
@@ -151,8 +182,19 @@ async function readFacilitatorRejection(res) {
 function isRecord(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
+function logRejected(stage) {
+  diagnosticConsole.warn({
+    event: "x402_credential_rejected",
+    rail: "x402",
+    failure_category: stage === "verifier" ? "verification_failed" : "settlement_failed",
+    failure_stage: stage
+  });
+}
 
 export {
+  withPaymentDiagnostics,
+  withPaymentStage,
+  paymentFailureStage,
   createX402FacilitatorAuthHeaders,
   createX402FacilitatorClient,
   verifyWithFacilitator,

package/dist/{chunk-FWGWLPXF.js → chunk-2OM2QPBE.js}

@@ -1,10 +1,10 @@
 import {
   callerLoggers
-} from "./chunk-66HGCPBU.js";
+} from "./chunk-KXWROQGK.js";
 import {
   diagnosticConsole,
   projectSpanRow
-} from "./chunk-ETXDTUJO.js";
+} from "./chunk-LAKP6FUI.js";
 
 // src/lib/x402/env.ts
 import { isAddress } from "viem";