@dvmkit/sdk 0.10.0 → 0.11.0-rc.1

package/dist/{chunk-3Q6FTZDB.js → chunk-3YFFZLW7.js}

@@ -2,7 +2,7 @@ import {
   createX402FacilitatorAuthHeaders,
   settleWithFacilitator,
   verifyWithFacilitator
-} from "./chunk-VTHYQCDB.js";
+} from "./chunk-E7ZBCT5U.js";
 import {
   buildPaymentRequirements,
   decodePayment,
@@ -15,7 +15,7 @@ import {
 } from "./chunk-66HGCPBU.js";
 import {
   diagnosticConsole
-} from "./chunk-QGNXYVBO.js";
+} from "./chunk-Z4FOPROB.js";
 
 // src/lib/x402/verify.ts
 async function verifyX402Payment(paymentHeader, config, requiredUsdcMicro, resource, btcUsdRate, exactVersions = { v1: true, v2: true }) {

package/dist/{chunk-YOSZIWC3.js → chunk-55DVLBCD.js}

@@ -10,12 +10,15 @@ import {
   fifoOrder,
   growthRailValue,
   inKindDrawMsats,
+  isFundingRail,
   isInKindDepletion,
   isNonChannelBitcoinRail,
   lotOwedSats,
   netOwedSats,
+  refundAssetDelta,
+  refundRequest,
   x402SettlementPending
-} from "./chunk-STJBBVNL.js";
+} from "./chunk-K2ZNIQZP.js";
 
 // src/sdk/server/memory-credit-ledger.ts
 import { randomUUID } from "crypto";
@@ -26,7 +29,9 @@ var MemoryCreditLedger = class _MemoryCreditLedger {
    * machine and drawing on another would `credit_not_found`.
    */
   durable = false;
+  tempoCreditLossEvidenceVersion = 1;
   credits = /* @__PURE__ */ new Map();
+  refunds = /* @__PURE__ */ new Map();
   fundings = /* @__PURE__ */ new Map();
   invoices = /* @__PURE__ */ new Map();
   tempoLosses = /* @__PURE__ */ new Map();
@@ -35,7 +40,7 @@ var MemoryCreditLedger = class _MemoryCreditLedger {
   /** Internal disposable transaction snapshot. The caller must serialize every ledger access. */
   forkForTransaction() {
     const fork = new _MemoryCreditLedger();
-    for (const name of ["credits", "fundings", "invoices", "tempoLosses", "x402Losses"]) {
+    for (const name of ["credits", "fundings", "invoices", "tempoLosses", "x402Losses", "refunds"]) {
       const target = fork[name];
       for (const [key, value] of this[name]) target.set(key, structuredClone(value));
     }
@@ -54,6 +59,90 @@ var MemoryCreditLedger = class _MemoryCreditLedger {
     if (wedged) throw x402SettlementPending(args.creditId ?? randomUUID(), wedged);
     return run(() => this.fundSync(args));
   }
+  /** Development accounting parity; this non-durable store cannot mount admin refunds. */
+  refundDraw(args) {
+    return run(() => {
+      const request = refundRequest(args);
+      const prior = this.refunds.get(args.refundId);
+      if (prior) {
+        if (prior.request !== request) throw new CreditLedgerError("refund_conflict", "This refundId was recorded with different arguments.");
+        return { ...prior.result, replayed: true };
+      }
+      const matches = [...this.credits.values()].flatMap((credit2) => [...credit2.draws.values()].filter((draw2) => args.jobId !== void 0 ? draw2.jobId === args.jobId : credit2.creditId === args.creditId && draw2.drawId === args.drawId).map((draw2) => ({ credit: credit2, draw: draw2 })));
+      if (matches.length !== 1 || !matches[0].draw.jobId) {
+        throw new CreditLedgerError("draw_not_found", "No unique job-bound draw matches this selector.");
+      }
+      const { credit, draw } = matches[0];
+      if (draw.status !== "settled") throw new CreditLedgerError("draw_not_completed", "Only a settled completed draw can be refunded.");
+      const nowMs = args.nowMs ?? Date.now();
+      const lastDrain = [...credit.drains.values()].filter((drain) => drain.status !== "released").sort((a, b) => b.ledgerSeq - a.ledgerSeq)[0];
+      const drained = lastDrain && lastDrain.balanceAfterMicro === 0 && (credit.lastFundingLedgerSeq === null || credit.lastFundingLedgerSeq < lastDrain.ledgerSeq) && ![...credit.draws.values()].some((later) => later.ledgerSeq > lastDrain.ledgerSeq && later.amountMicro > 0) && ![...this.fundings.values()].some((funding) => funding.creditId === credit.creditId && funding.ledgerSeq !== null && funding.ledgerSeq >= lastDrain.ledgerSeq && funding.amountMicro > 0);
+      if (credit.status !== "active" || credit.expiryMs <= nowMs) {
+        throw new CreditLedgerError("credit_not_open", "The original credit is no longer open for refunds.");
+      }
+      if (credit.tempoChannelId || credit.x402ChannelId) {
+        throw new CreditLedgerError("credit_refund_channel_unsupported", "Channel collateral cannot back a refund of settled spending.");
+      }
+      if (credit.balanceMicro === 0 && drained) {
+        if (credit.lastFundingLedgerSeq === null) {
+          throw new CreditLedgerError("credit_refund_state_unavailable", "The original credit's historical funding and drain order cannot be established.");
+        }
+        throw new CreditLedgerError("credit_not_open", "The original credit is no longer open for refunds.");
+      }
+      const before = [...this.refunds.values()].reduce((sum, refund) => sum + (refund.result.creditId === credit.creditId && refund.result.drawId === draw.drawId ? refund.result.amountMicro : 0), 0);
+      const amountMicro = args.amountMicro ?? draw.amountMicro - before;
+      if (amountMicro <= 0 || amountMicro > draw.amountMicro - before) {
+        throw new CreditLedgerError("refund_exceeds_draw", "The refund exceeds the draw's remaining unrefunded charge.");
+      }
+      if (!isFundingRail(credit.rail)) throw new CreditLedgerError("credit_refund_basis_unavailable", "The original funding rail is not recorded on this older credit.");
+      const bitcoin = isNonChannelBitcoinRail(credit.rail);
+      const originalSats = draw.settledSats ?? null;
+      if (bitcoin && originalSats === null) throw new CreditLedgerError("credit_refund_basis_unavailable", "The original Bitcoin value is not provable from this older draw.");
+      const after = before + amountMicro;
+      const restoredSats = bitcoin ? refundAssetDelta(originalSats, draw.amountMicro, before, after) : null;
+      const restoredMsats = restoredSats === null ? refundAssetDelta(draw.drawMsats, draw.amountMicro, before, after) : restoredSats * 1e3;
+      const restoredNative = draw.drawNative === null ? null : refundAssetDelta(draw.drawNative, draw.amountMicro, before, after);
+      const balanceAfterMicro = credit.balanceMicro + amountMicro;
+      const ledgerSeq = credit.lastLedgerSeq + 1;
+      if (![
+        balanceAfterMicro,
+        ledgerSeq,
+        credit.msatsRemaining + restoredMsats,
+        (credit.nativeRemaining ?? 0) + (restoredNative ?? 0)
+      ].every(Number.isSafeInteger)) {
+        throw new Error("credit ledger: refund exceeds safe integer range");
+      }
+      credit.balanceMicro = balanceAfterMicro;
+      credit.lastLedgerSeq = ledgerSeq;
+      credit.msatsRemaining += restoredMsats;
+      if (credit.nativeRemaining !== null) credit.nativeRemaining += restoredNative ?? 0;
+      if (bitcoin) credit.lots.push({
+        lotId: `lot:refund:${randomUUID()}`,
+        creditId: credit.creditId,
+        rail: credit.rail,
+        satsFunded: restoredSats,
+        satsBasisKnown: true,
+        creditedMicro: amountMicro,
+        remainingMicro: amountMicro,
+        fundingRef: args.refundId,
+        createdAt: nowMs
+      });
+      const result = {
+        refundId: args.refundId,
+        creditId: credit.creditId,
+        drawId: draw.drawId,
+        jobId: draw.jobId,
+        amountMicro,
+        currency: credit.currency,
+        ledgerSeq,
+        refundedAt: nowMs,
+        balanceAfterMicro,
+        replayed: false
+      };
+      this.refunds.set(args.refundId, { request, result });
+      return { ...result };
+    });
+  }
   async draw(args) {
     const blocking = await this.blockingRefundForCredit(
       args.creditId,
@@ -427,6 +516,7 @@ var MemoryCreditLedger = class _MemoryCreditLedger {
           }
         );
       }
+      existing.lastFundingLedgerSeq = existing.lastLedgerSeq;
       existing.balanceMicro += args.amountMicro;
       existing.expiryMs = args.expiryMs;
       applyBasis(existing, b);
@@ -457,6 +547,7 @@ var MemoryCreditLedger = class _MemoryCreditLedger {
       expiryMs: args.expiryMs,
       status: "active",
       lastLedgerSeq: 0,
+      lastFundingLedgerSeq: 0,
       createdAt: nowMs,
       draws: /* @__PURE__ */ new Map(),
       rail: null,
@@ -687,6 +778,15 @@ var MemoryCreditLedger = class _MemoryCreditLedger {
     return run(() => {
       const channelId = evidence.channelId.toLowerCase();
       const observedAt = evidence.observedAt ?? Date.now();
+      const refunded = evidence.refundedToPayerNative ?? 0n;
+      if (refunded < 0n) throw new Error("Tempo close refund must be nonnegative");
+      const payerExit = evidence.closeKind === "payer_exit";
+      if (payerExit && evidence.refundedToPayerNative !== void 0 || evidence.closeKind === "cooperative_close" && evidence.refundedToPayerNative === void 0) {
+        throw new Error("Tempo close kind requires matching exact cooperative refund evidence");
+      }
+      const lossNative = (payerExit ? evidence.consumedNative : evidence.highestVoucherNative) - evidence.settledOnChainNative - (payerExit ? 0n : refunded);
+      const lossBasis = payerExit ? "payer_exit" : evidence.refundedToPayerNative === void 0 ? "caller_asserted" : "cooperative_close";
+      if (lossNative <= 0n) return [...this.tempoLosses.values()].filter((loss) => loss.channelId === channelId);
       for (const credit of this.credits.values()) {
         if (credit.tempoChannelId !== channelId) continue;
         if (credit.status === "unbacked") continue;
@@ -701,6 +801,9 @@ var MemoryCreditLedger = class _MemoryCreditLedger {
           highestVoucherNative: evidence.highestVoucherNative,
           consumedServiceMicro,
           consumedNative: evidence.consumedNative,
+          refundedToPayerNative: evidence.refundedToPayerNative ?? null,
+          lossNative,
+          lossBasis,
           observedAt
         });
         credit.status = "unbacked";
@@ -708,9 +811,9 @@ var MemoryCreditLedger = class _MemoryCreditLedger {
       return [...this.tempoLosses.values()].filter((loss) => loss.channelId === channelId);
     });
   }
-  listTempoCreditLosses(args) {
+  listTempoCreditLosses(args, _tx) {
     return Promise.resolve(
-      [...this.tempoLosses.values()].sort((a, b) => b.observedAt - a.observedAt || a.creditId.localeCompare(b.creditId)).slice(0, args?.limit ?? 50)
+      [...this.tempoLosses.values()].filter((loss) => !args?.channelId || loss.channelId === args.channelId.toLowerCase()).sort((a, b) => b.observedAt - a.observedAt || a.creditId.localeCompare(b.creditId)).slice(0, args?.limit ?? 50)
     );
   }
   terminalizeX402Credit(evidence, _tx) {
@@ -841,7 +944,9 @@ var MemoryCreditLedger = class _MemoryCreditLedger {
         sentAt: null,
         releasedAt: null,
         writeOffNote: null,
-        writtenOffAt: null
+        writtenOffAt: null,
+        provenRefundNative: null,
+        refundPaymentProven: false
       };
       applyLotDebits(credit, drain.lotDebits, -1);
       credit.drains.set(args.drainId, drain);
@@ -874,7 +979,7 @@ var MemoryCreditLedger = class _MemoryCreditLedger {
       const lots = openLots(credit);
       const covered = lots.reduce((sum, lot) => sum + lot.remainingMicro, 0);
       const basisless = lots.reduce(
-        (sum, lot) => sum + (lot.satsFunded === 0 ? lot.remainingMicro : 0),
+        (sum, lot) => sum + (lot.satsFunded === 0 && !lot.satsBasisKnown ? lot.remainingMicro : 0),
         0
       );
       const inKind = covered >= credit.balanceMicro && basisless === 0;
@@ -947,7 +1052,7 @@ var MemoryCreditLedger = class _MemoryCreditLedger {
       for (const drain of credit.drains.values()) {
         if (drain.status !== "pending" && drain.status !== "exit_required" || drain.method !== "tempo") continue;
         if (drain.createdAt > args.createdBeforeMs) continue;
-        if (!args.includeResolved && drain.writtenOffAt !== null) continue;
+        if (!args.includeResolved && !args.includeWrittenOff && drain.writtenOffAt !== null) continue;
         out.push(drainRecord(drain, credit));
       }
     }
@@ -992,6 +1097,25 @@ var MemoryCreditLedger = class _MemoryCreditLedger {
       return { drain: drainRecord(drain, credit), replayed: false };
     });
   }
+  recordTempoDrainRefund(args) {
+    const amount = String(args.refundedNative);
+    if (!/^\d{1,78}$/.test(amount)) return Promise.reject(new CreditLedgerError("invalid_basis", "Tempo refund evidence must be a bounded non-negative integer."));
+    return this.recordTempoDrainRefundEvidence(args, amount);
+  }
+  recordTempoDrainPayment(args) {
+    return this.recordTempoDrainRefundEvidence(args, null);
+  }
+  recordTempoDrainRefundEvidence(args, amount) {
+    return run(() => {
+      const credit = this.credits.get(args.creditId);
+      const drain = credit?.drains.get(args.drainId);
+      if (!credit?.tempoChannelId || !drain || drain.method !== "tempo" || drain.status !== "pending" && drain.status !== "exit_required") return;
+      if (amount !== null && (drain.provenRefundNative === null || BigInt(amount) > BigInt(drain.provenRefundNative))) {
+        drain.provenRefundNative = amount;
+      }
+      drain.refundPaymentProven ||= amount === null || BigInt(amount) > 0n;
+    });
+  }
   releaseDrain(args) {
     return run(() => {
       const { credit, drain } = this.requireDrain(args.creditId, args.drainId);
@@ -1115,6 +1239,7 @@ var MemoryCreditLedger = class _MemoryCreditLedger {
         if (isNonChannelBitcoinRail(credit.rail)) {
           const depletion = depleteLots(openLots(credit), draw.amountMicro);
           const settledMsats = inKindDrawMsats(depletion, draw.amountMicro);
+          draw.settledSats = settledMsats === null ? null : settledMsats / 1e3;
           if (settledMsats !== null && settledMsats !== draw.drawMsats) {
             draw.allocatedMsats = draw.drawMsats;
             draw.drawMsats = settledMsats;
@@ -1295,7 +1420,9 @@ function drainRecord(drain, credit) {
     sentAt: drain.sentAt,
     releasedAt: drain.releasedAt,
     writeOffNote: drain.writeOffNote,
-    writtenOffAt: drain.writtenOffAt
+    writtenOffAt: drain.writtenOffAt,
+    provenRefundNative: drain.provenRefundNative,
+    refundPaymentProven: drain.refundPaymentProven
   };
 }
 function assertAmount(amountMicro, opts) {

package/dist/{chunk-VMHYGKWT.js → chunk-566CFXGU.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-COYKJRMM.js";
 import {
   diagnosticConsole
-} from "./chunk-QGNXYVBO.js";
+} from "./chunk-Z4FOPROB.js";
 
 // src/sdk/server/revenue-reporter.ts
 import { randomUUID } from "crypto";
@@ -13,6 +13,7 @@ var ENDPOINTS = {
   cost: "/_internal/job-cost",
   deposit: "/_internal/credit-deposit",
   release: "/_internal/credit-draw-release",
+  refund: "/_internal/credit-draw-refund",
   drain: "/_internal/credit-drain",
   payout: "/_internal/payout",
   expiry_release: "/_internal/credit-expiry-release"
@@ -166,6 +167,10 @@ var RevenueReporter = class _RevenueReporter {
   async enqueueDeposit(tx, payload) {
     await this.insertPending(tx, "deposit", payload);
   }
+  /** Persist without network delivery before the refund accounting transaction commits. */
+  async enqueueCreditDrawRefund(tx, payload) {
+    await this.insertPending(tx, "refund", payload);
+  }
   /** Join a released draw to the transaction that made the hold terminal. */
   async enqueueCreditDrawRelease(tx, payload) {
     await this.insertPending(tx, "release", payload);
@@ -620,6 +625,9 @@ var RevenueReporter = class _RevenueReporter {
       diagnosticConsole.log(`[revenue-reporter] reported ${kind} ${label}`);
       return;
     }
+    if (kind === "refund" && res.status === 409) {
+      throw new Error("Original draw revenue has not arrived yet");
+    }
     if (res.status === 401) {
       await this.markStale(id, "token_rotated");
       diagnosticConsole.warn(

package/dist/chunk-5H7P3ORL.js

@@ -0,0 +1,92 @@
+import {
+  canonicaliseForSigning
+} from "./chunk-H3GGFEE5.js";
+
+// src/lib/receipt.ts
+import { schnorr } from "@noble/curves/secp256k1.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { bytesToHex, hexToBytes } from "@noble/hashes/utils.js";
+function computeResultHash(summary, artifactContents) {
+  const artifactHashes = artifactContents.map(
+    (content) => bytesToHex(sha256(canonicaliseForSigning(content)))
+  );
+  return bytesToHex(
+    sha256(
+      canonicaliseForSigning({
+        summary: summary ?? null,
+        artifact_hashes: artifactHashes
+      })
+    )
+  );
+}
+function signReceipt(unsigned, secretHex) {
+  const bytes = canonicaliseForSigning(unsigned);
+  const signature = bytesToHex(schnorr.sign(bytes, hexToBytes(secretHex)));
+  return { ...unsigned, signature };
+}
+function verifyReceipt(receipt) {
+  try {
+    const { signature, ...unsigned } = receipt;
+    const bytes = canonicaliseForSigning(unsigned);
+    return schnorr.verify(hexToBytes(signature), bytes, hexToBytes(receipt.receipt_pubkey));
+  } catch {
+    return false;
+  }
+}
+function isSignedJobReceipt(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const r = value;
+  const paid = r.paid;
+  return r.v === 1 && typeof r.job_id === "string" && typeof r.dvm_id === "string" && typeof r.dvm === "string" && typeof r.capability === "string" && (r.outcome === "completed" || r.outcome === "failed" || r.outcome === "cancelled") && typeof r.seq === "number" && typeof r.issued_at === "number" && typeof r.receipt_pubkey === "string" && typeof r.signature === "string" && !!paid && typeof paid === "object" && !Array.isArray(paid) && typeof paid.msats === "number";
+}
+function signDrainReceipt(unsigned, secretHex) {
+  const bytes = canonicaliseForSigning(unsigned);
+  const signature = bytesToHex(schnorr.sign(bytes, hexToBytes(secretHex)));
+  return { ...unsigned, signature };
+}
+function signFundingReceipt(unsigned, secretHex) {
+  const bytes = canonicaliseForSigning(unsigned);
+  const signature = bytesToHex(schnorr.sign(bytes, hexToBytes(secretHex)));
+  return { ...unsigned, signature };
+}
+function isFundingReceipt(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const r = value;
+  return r.v === 1 && r.kind === "credit_funding" && typeof r.credit_id === "string" && typeof r.fund_id === "string" && typeof r.funded_micro === "number" && typeof r.balance_after_micro === "number" && typeof r.ledger_seq === "number" && typeof r.issued_at === "number" && typeof r.caller_pubkey === "string" && typeof r.dvm_id === "string" && typeof r.dvm === "string" && typeof r.receipt_pubkey === "string" && typeof r.signature === "string";
+}
+function verifyFundingReceipt(receipt) {
+  try {
+    const { signature, ...unsigned } = receipt;
+    const bytes = canonicaliseForSigning(unsigned);
+    return schnorr.verify(hexToBytes(signature), bytes, hexToBytes(receipt.receipt_pubkey));
+  } catch {
+    return false;
+  }
+}
+function isDrainReceipt(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const r = value;
+  return r.v === 1 && r.kind === "credit_drain" && typeof r.credit_id === "string" && typeof r.drain_id === "string" && (r.event === "requested" || r.event === "parked" || r.event === "picked_up" || r.event === "sent" || r.event === "released") && typeof r.method === "string" && typeof r.amount_micro === "number" && typeof r.issued_at === "number" && typeof r.caller_pubkey === "string" && typeof r.dvm_id === "string" && typeof r.dvm === "string" && typeof r.receipt_pubkey === "string" && typeof r.signature === "string";
+}
+function verifyDrainReceipt(receipt) {
+  try {
+    const { signature, ...unsigned } = receipt;
+    const bytes = canonicaliseForSigning(unsigned);
+    return schnorr.verify(hexToBytes(signature), bytes, hexToBytes(receipt.receipt_pubkey));
+  } catch {
+    return false;
+  }
+}
+
+export {
+  computeResultHash,
+  signReceipt,
+  verifyReceipt,
+  isSignedJobReceipt,
+  signDrainReceipt,
+  signFundingReceipt,
+  isFundingReceipt,
+  verifyFundingReceipt,
+  isDrainReceipt,
+  verifyDrainReceipt
+};

package/dist/{chunk-3R7NQA3Z.js → chunk-7KQLPVV7.js}

@@ -1,7 +1,7 @@
 import {
   emitDiagnostic,
   projectDiagnosticFields
-} from "./chunk-QGNXYVBO.js";
+} from "./chunk-Z4FOPROB.js";
 
 // src/sdk/logger.ts
 function createConsoleLogger(_jobId) {