@toon-protocol/sdk 2.1.0 → 3.0.0

package/dist/{chunk-7LBYFU4L.js → chunk-RAZRWSJF.js}

@@ -520,6 +520,313 @@ function decryptFulfillClaim(params) {
   }
 }
 
+// src/stream-receipts.ts
+import { schnorr } from "@noble/curves/secp256k1.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { bytesToHex as bytesToHex2, hexToBytes } from "@noble/hashes/utils.js";
+var STREAM_RECEIPT_VERSION = 1;
+var STREAM_RECEIPT_SIGNING_TAG = "toon.stream-receipt.v1";
+var STREAM_NONCE_REGEX = /^[0-9a-f]{32}$/;
+var SIG_REGEX = /^[0-9a-f]{128}$/;
+var HEX64_REGEX = /^[0-9a-f]{64}$/;
+var DECIMAL_UINT_REGEX = /^(0|[1-9]\d*)$/;
+var RATE_REGEX = /^(0|[1-9]\d*)(\.\d+)?$/;
+function isValidStreamNonce(value) {
+  return typeof value === "string" && STREAM_NONCE_REGEX.test(value);
+}
+function parseStreamReceipt(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("receipt must be an object");
+  }
+  const obj = value;
+  if (obj["v"] !== STREAM_RECEIPT_VERSION) {
+    throw new Error(
+      `receipt.v must be ${STREAM_RECEIPT_VERSION}, got ${String(obj["v"])}`
+    );
+  }
+  if (!isValidStreamNonce(obj["streamNonce"])) {
+    throw new Error("receipt.streamNonce must be 32-char lowercase hex");
+  }
+  const seq = obj["seq"];
+  if (typeof seq !== "number" || !Number.isSafeInteger(seq) || seq < 1) {
+    throw new Error("receipt.seq must be a positive safe integer");
+  }
+  const cumulativeDelivered = obj["cumulativeDelivered"];
+  if (typeof cumulativeDelivered !== "string" || !DECIMAL_UINT_REGEX.test(cumulativeDelivered)) {
+    throw new Error(
+      "receipt.cumulativeDelivered must be a non-negative integer decimal string"
+    );
+  }
+  const rate = obj["rate"];
+  if (typeof rate !== "string" || !RATE_REGEX.test(rate) || /^0(\.0+)?$/.test(rate)) {
+    throw new Error("receipt.rate must be a positive decimal string");
+  }
+  const rateTimestamp = obj["rateTimestamp"];
+  if (typeof rateTimestamp !== "number" || !Number.isInteger(rateTimestamp) || rateTimestamp <= 0) {
+    throw new Error(
+      "receipt.rateTimestamp must be a positive integer (unix ms)"
+    );
+  }
+  const sig = obj["sig"];
+  if (typeof sig !== "string" || !SIG_REGEX.test(sig)) {
+    throw new Error("receipt.sig must be 128-char lowercase hex");
+  }
+  return {
+    v: STREAM_RECEIPT_VERSION,
+    streamNonce: obj["streamNonce"],
+    seq,
+    cumulativeDelivered,
+    rate,
+    rateTimestamp,
+    sig
+  };
+}
+function encodeReceiptSigningPayload(fields) {
+  if (!isValidStreamNonce(fields.streamNonce)) {
+    throw new Error("streamNonce must be 32-char lowercase hex");
+  }
+  const tag = Buffer.from(STREAM_RECEIPT_SIGNING_TAG, "utf8");
+  const cumulative = Buffer.from(fields.cumulativeDelivered, "utf8");
+  const rate = Buffer.from(fields.rate, "utf8");
+  const buf = Buffer.alloc(
+    4 + tag.length + 1 + 16 + 8 + 4 + cumulative.length + 4 + rate.length + 8
+  );
+  let off = 0;
+  buf.writeUInt32BE(tag.length, off);
+  off += 4;
+  tag.copy(buf, off);
+  off += tag.length;
+  buf.writeUInt8(fields.v, off);
+  off += 1;
+  Buffer.from(hexToBytes(fields.streamNonce)).copy(buf, off);
+  off += 16;
+  buf.writeBigUInt64BE(BigInt(fields.seq), off);
+  off += 8;
+  buf.writeUInt32BE(cumulative.length, off);
+  off += 4;
+  cumulative.copy(buf, off);
+  off += cumulative.length;
+  buf.writeUInt32BE(rate.length, off);
+  off += 4;
+  rate.copy(buf, off);
+  off += rate.length;
+  buf.writeBigUInt64BE(BigInt(fields.rateTimestamp), off);
+  return new Uint8Array(buf);
+}
+function signStreamReceipt(fields, secretKey) {
+  if (!(secretKey instanceof Uint8Array) || secretKey.length !== 32) {
+    throw new Error("receipt secretKey must be a 32-byte Uint8Array");
+  }
+  const digest = sha256(encodeReceiptSigningPayload(fields));
+  const sig = bytesToHex2(schnorr.sign(digest, secretKey));
+  return { ...fields, sig };
+}
+function verifyStreamReceipt(receipt, makerPubkey) {
+  if (typeof makerPubkey !== "string" || !HEX64_REGEX.test(makerPubkey)) {
+    return false;
+  }
+  if (typeof receipt.sig !== "string" || !SIG_REGEX.test(receipt.sig)) {
+    return false;
+  }
+  try {
+    const { sig: _sig, ...fields } = receipt;
+    const digest = sha256(encodeReceiptSigningPayload(fields));
+    return schnorr.verify(
+      hexToBytes(receipt.sig),
+      digest,
+      hexToBytes(makerPubkey)
+    );
+  } catch {
+    return false;
+  }
+}
+var ReceiptChainTracker = class {
+  #streamNonce;
+  #makerPubkey;
+  /** Verified receipts, kept sorted by ascending seq. */
+  #receipts = [];
+  #seqs = /* @__PURE__ */ new Set();
+  constructor(input) {
+    if (!isValidStreamNonce(input.streamNonce)) {
+      throw new Error("streamNonce must be 32-char lowercase hex");
+    }
+    if (typeof input.makerPubkey !== "string" || !HEX64_REGEX.test(input.makerPubkey)) {
+      throw new Error("makerPubkey must be a 64-char lowercase hex string");
+    }
+    this.#streamNonce = input.streamNonce;
+    this.#makerPubkey = input.makerPubkey;
+  }
+  get streamNonce() {
+    return this.#streamNonce;
+  }
+  /** Number of verified receipts accumulated so far. */
+  get size() {
+    return this.#receipts.length;
+  }
+  /**
+   * Verify + accumulate one receipt. On `{ok: false}` the receipt is NOT
+   * added and the chain is unchanged.
+   */
+  add(receipt) {
+    if (receipt.streamNonce !== this.#streamNonce) {
+      return {
+        ok: false,
+        code: "WRONG_STREAM_NONCE",
+        message: `receipt streamNonce ${receipt.streamNonce} does not match session ${this.#streamNonce}`
+      };
+    }
+    if (!verifyStreamReceipt(receipt, this.#makerPubkey)) {
+      return {
+        ok: false,
+        code: "BAD_SIGNATURE",
+        message: `receipt seq ${receipt.seq} signature does not verify against maker key ${this.#makerPubkey}`
+      };
+    }
+    if (this.#seqs.has(receipt.seq)) {
+      return {
+        ok: false,
+        code: "DUPLICATE_SEQ",
+        message: `duplicate receipt seq ${receipt.seq}`
+      };
+    }
+    let lo = 0;
+    let hi = this.#receipts.length;
+    while (lo < hi) {
+      const mid = lo + hi >>> 1;
+      const midReceipt = this.#receipts[mid];
+      if (midReceipt.seq < receipt.seq) lo = mid + 1;
+      else hi = mid;
+    }
+    const cumulative = BigInt(receipt.cumulativeDelivered);
+    const lower = lo > 0 ? this.#receipts[lo - 1] : void 0;
+    const higher = lo < this.#receipts.length ? this.#receipts[lo] : void 0;
+    if (lower && BigInt(lower.cumulativeDelivered) > cumulative) {
+      return {
+        ok: false,
+        code: "NON_MONOTONIC",
+        message: `receipt seq ${receipt.seq} cumulativeDelivered ${receipt.cumulativeDelivered} is below seq ${lower.seq}'s ${lower.cumulativeDelivered}`
+      };
+    }
+    if (higher && BigInt(higher.cumulativeDelivered) < cumulative) {
+      return {
+        ok: false,
+        code: "NON_MONOTONIC",
+        message: `receipt seq ${receipt.seq} cumulativeDelivered ${receipt.cumulativeDelivered} is above seq ${higher.seq}'s ${higher.cumulativeDelivered}`
+      };
+    }
+    this.#receipts.splice(lo, 0, receipt);
+    this.#seqs.add(receipt.seq);
+    return { ok: true };
+  }
+  /**
+   * Snapshot the accumulated chain: sorted receipts, the superseding latest,
+   * the signed total delivered, and any `seq` holes in `[1, latest.seq]`.
+   */
+  chain() {
+    const receipts = [...this.#receipts];
+    const latest = receipts[receipts.length - 1];
+    const holes = [];
+    if (latest) {
+      for (let seq = 1; seq <= latest.seq; seq++) {
+        if (!this.#seqs.has(seq)) holes.push(seq);
+      }
+    }
+    return {
+      streamNonce: this.#streamNonce,
+      receipts,
+      ...latest !== void 0 && { latest },
+      totalDelivered: latest?.cumulativeDelivered ?? "0",
+      holes
+    };
+  }
+};
+function serializeReceiptChain(chain) {
+  return JSON.stringify({
+    kind: "toon.stream-receipt-chain",
+    v: STREAM_RECEIPT_VERSION,
+    streamNonce: chain.streamNonce,
+    totalDelivered: chain.totalDelivered,
+    holes: chain.holes,
+    receipts: chain.receipts.map((r) => ({
+      v: r.v,
+      streamNonce: r.streamNonce,
+      seq: r.seq,
+      cumulativeDelivered: r.cumulativeDelivered,
+      rate: r.rate,
+      rateTimestamp: r.rateTimestamp,
+      sig: r.sig
+    }))
+  });
+}
+var DEFAULT_RECEIPT_SESSIONS_CAP = 1e4;
+var BoundedReceiptSessions = class {
+  #map = /* @__PURE__ */ new Map();
+  #cap;
+  constructor(cap = DEFAULT_RECEIPT_SESSIONS_CAP) {
+    if (!Number.isInteger(cap) || cap <= 0) {
+      throw new Error(
+        `BoundedReceiptSessions cap must be a positive integer, got ${cap}`
+      );
+    }
+    this.#cap = cap;
+  }
+  get size() {
+    return this.#map.size;
+  }
+  get cap() {
+    return this.#cap;
+  }
+  get(streamNonce) {
+    const state = this.#map.get(streamNonce);
+    if (state === void 0) return void 0;
+    this.#map.delete(streamNonce);
+    this.#map.set(streamNonce, state);
+    return state;
+  }
+  set(streamNonce, state) {
+    this.#map.delete(streamNonce);
+    this.#map.set(streamNonce, state);
+    while (this.#map.size > this.#cap) {
+      const first = this.#map.keys().next();
+      if (first.done) break;
+      this.#map.delete(first.value);
+    }
+    return this;
+  }
+  delete(streamNonce) {
+    return this.#map.delete(streamNonce);
+  }
+};
+function issueSessionReceipt(input) {
+  const { sessions, streamNonce, deliveredAmount, rate, rateTimestamp } = input;
+  if (deliveredAmount < 0n) {
+    throw new Error(
+      `deliveredAmount must be non-negative, got ${deliveredAmount}`
+    );
+  }
+  const prev = sessions.get(streamNonce) ?? {
+    seq: 0,
+    cumulativeDelivered: 0n
+  };
+  const next = {
+    seq: prev.seq + 1,
+    cumulativeDelivered: prev.cumulativeDelivered + deliveredAmount
+  };
+  const receipt = signStreamReceipt(
+    {
+      v: STREAM_RECEIPT_VERSION,
+      streamNonce,
+      seq: next.seq,
+      cumulativeDelivered: next.cumulativeDelivered.toString(),
+      rate,
+      rateTimestamp
+    },
+    input.secretKey
+  );
+  sessions.set(streamNonce, next);
+  return receipt;
+}
+
 // src/swap-handler.ts
 import { createHash } from "crypto";
 var DEFAULT_SEEN_PACKET_IDS_CAP = 1e4;
@@ -611,10 +918,10 @@ var BoundedSeenPacketIds = class {
     for (const k of this.#map.keys()) yield [k, k];
   }
 };
-var RATE_REGEX = /^(0|[1-9]\d*)(\.\d+)?$/;
+var RATE_REGEX2 = /^(0|[1-9]\d*)(\.\d+)?$/;
 function applyRate(params) {
   const { sourceAmount, fromScale, toScale, rate } = params;
-  if (!RATE_REGEX.test(rate)) {
+  if (!RATE_REGEX2.test(rate)) {
     throw new SwapHandlerError(`Invalid rate format: ${rate}`);
   }
   if (/^0(\.0+)?$/.test(rate)) {
@@ -713,7 +1020,12 @@ function createSwapHandler(config) {
       "claimIssuer must implement issueClaim(params): Promise<IssueClaimResult>"
     );
   }
+  if (config.receiptSecretKey !== void 0 && (!(config.receiptSecretKey instanceof Uint8Array) || config.receiptSecretKey.length !== 32)) {
+    throw new SwapHandlerError("receiptSecretKey must be a 32-byte Uint8Array");
+  }
   const logger = config.logger ?? NOOP_LOGGER;
+  const receiptSecretKey = config.receiptSecretKey ?? config.recipientSecretKey;
+  const receiptSessions = config.receiptSessions ?? new BoundedReceiptSessions();
   const seenPacketIds = config.seenPacketIds ?? new BoundedSeenPacketIds();
   return async (ctx) => {
     if (ctx.kind !== 1059) {
@@ -888,6 +1200,32 @@ function createSwapHandler(config) {
       releaseReservation();
       return ctx.reject("T00", "Internal error");
     }
+    let receipt;
+    const streamNonceTag = findTagValue(rumor, "stream-nonce");
+    if (streamNonceTag !== void 0) {
+      if (!isValidStreamNonce(streamNonceTag)) {
+        logger.warn({
+          event: "swap_handler.invalid_stream_nonce",
+          destination: ctx.destination
+        });
+      } else {
+        try {
+          receipt = issueSessionReceipt({
+            sessions: receiptSessions,
+            streamNonce: streamNonceTag,
+            deliveredAmount: targetAmount,
+            rate,
+            rateTimestamp,
+            secretKey: receiptSecretKey
+          });
+        } catch (err) {
+          logger.error({
+            event: "swap_handler.receipt_issue_failed",
+            error: err instanceof Error ? err.message : String(err)
+          });
+        }
+      }
+    }
     const claimBase64 = Buffer.from(ciphertext).toString("base64");
     logger.info({
       event: "swap_handler.claim_issued",
@@ -902,6 +1240,7 @@ function createSwapHandler(config) {
       rateTimestamp
     };
     if (claimId !== void 0) metadata["claimId"] = claimId;
+    if (receipt !== void 0) metadata["receipt"] = receipt;
     if (settlementChannelId !== void 0 && settlementNonce !== void 0 && settlementCumulative !== void 0 && settlementRecipient !== void 0 && settlementSwapSigner !== void 0) {
       metadata["channelId"] = settlementChannelId;
       metadata["nonce"] = settlementNonce.toString();
@@ -928,8 +1267,8 @@ function computePacketId(senderPubkey, sourceAmount, rumor) {
 
 // src/stream-swap.ts
 import { getPublicKey as getPublicKey3 } from "nostr-tools/pure";
-var RATE_REGEX2 = /^(0|[1-9]\d*)(\.\d+)?$/;
-var HEX64_REGEX = /^[0-9a-f]{64}$/;
+var RATE_REGEX3 = /^(0|[1-9]\d*)(\.\d+)?$/;
+var HEX64_REGEX2 = /^[0-9a-f]{64}$/;
 var BASE64_REGEX = /^[A-Za-z0-9+/]+={0,2}$/;
 function isBase64(s) {
   if (s.length === 0 || s.length % 4 !== 0) return false;
@@ -965,26 +1304,29 @@ function buildSwapRumor(input) {
     totalPackets,
     nonce,
     createdAt,
-    chainRecipient
+    chainRecipient,
+    streamNonce
   } = input;
+  const tags = [
+    ["swap-from", `${pair.from.assetCode}:${pair.from.chain}`],
+    ["swap-to", `${pair.to.assetCode}:${pair.to.chain}`],
+    ["amount", sourceAmount.toString()],
+    ["seq", String(packetIndex), String(totalPackets)],
+    ["nonce", Buffer.from(nonce).toString("hex")],
+    ["chain-recipient", chainRecipient]
+  ];
+  if (streamNonce !== void 0) tags.push(["stream-nonce", streamNonce]);
   return {
     kind: 20032,
     pubkey: senderPubkey,
     content: "",
     created_at: createdAt,
-    tags: [
-      ["swap-from", `${pair.from.assetCode}:${pair.from.chain}`],
-      ["swap-to", `${pair.to.assetCode}:${pair.to.chain}`],
-      ["amount", sourceAmount.toString()],
-      ["seq", String(packetIndex), String(totalPackets)],
-      ["nonce", Buffer.from(nonce).toString("hex")],
-      ["chain-recipient", chainRecipient]
-    ]
+    tags
   };
 }
 var EVM_CHANNEL_ID_REGEX = /^0x[0-9a-f]{64}$/;
 var EVM_ADDRESS_REGEX = /^0x[0-9a-f]{40}$/;
-var DECIMAL_UINT_REGEX = /^(0|[1-9]\d*)$/;
+var DECIMAL_UINT_REGEX2 = /^(0|[1-9]\d*)$/;
 var BASE58_REGEX = /^[1-9A-HJ-NP-Za-km-z]+$/;
 function validateChainAddress(value, chain, kind) {
   if (chain.startsWith("evm:")) {
@@ -1051,7 +1393,7 @@ function decodeFulfillMetadata(data, chain, opts) {
       "FULFILL metadata.claim is missing or not base64 string"
     );
   }
-  if (typeof ephemeralPubkey !== "string" || !HEX64_REGEX.test(ephemeralPubkey)) {
+  if (typeof ephemeralPubkey !== "string" || !HEX64_REGEX2.test(ephemeralPubkey)) {
     throw new StreamSwapError(
       "FULFILL_DECODE_FAILED",
       "FULFILL metadata.ephemeralPubkey is missing or not 64-char hex"
@@ -1085,7 +1427,7 @@ function decodeFulfillMetadata(data, chain, opts) {
     );
   }
   if (hasRate) {
-    if (typeof tapeRate !== "string" || !RATE_REGEX2.test(tapeRate) || /^0(\.0+)?$/.test(tapeRate)) {
+    if (typeof tapeRate !== "string" || !RATE_REGEX3.test(tapeRate) || /^0(\.0+)?$/.test(tapeRate)) {
       throw new StreamSwapError(
         "FULFILL_DECODE_FAILED",
         "FULFILL metadata.rate must be a positive decimal string"
@@ -1105,16 +1447,27 @@ function decodeFulfillMetadata(data, chain, opts) {
       "FULFILL metadata is missing the quote tape (rate + rateTimestamp) required when minExchangeRate is set"
     );
   }
+  if (obj["receipt"] !== void 0) {
+    try {
+      result.receipt = parseStreamReceipt(obj["receipt"]);
+    } catch (err) {
+      throw new StreamSwapError(
+        "FULFILL_DECODE_FAILED",
+        `FULFILL metadata.receipt is malformed: ${err instanceof Error ? err.message : String(err)}`,
+        { cause: err }
+      );
+    }
+  }
   const channelId = obj["channelId"];
   if (typeof channelId === "string" && (!chain || validateChainAddress(channelId, chain, "channelId"))) {
     result.channelId = channelId;
   }
   const nonce = obj["nonce"];
-  if (typeof nonce === "string" && DECIMAL_UINT_REGEX.test(nonce)) {
+  if (typeof nonce === "string" && DECIMAL_UINT_REGEX2.test(nonce)) {
     result.nonce = nonce;
   }
   const cumulativeAmount = obj["cumulativeAmount"];
-  if (typeof cumulativeAmount === "string" && DECIMAL_UINT_REGEX.test(cumulativeAmount)) {
+  if (typeof cumulativeAmount === "string" && DECIMAL_UINT_REGEX2.test(cumulativeAmount)) {
     result.cumulativeAmount = cumulativeAmount;
   }
   const recipient = obj["recipient"];
@@ -1230,7 +1583,7 @@ function validateParams(params) {
       "senderSecretKey must be a 32-byte Uint8Array"
     );
   }
-  if (typeof params.swapPubkey !== "string" || !HEX64_REGEX.test(params.swapPubkey)) {
+  if (typeof params.swapPubkey !== "string" || !HEX64_REGEX2.test(params.swapPubkey)) {
     throw new StreamSwapError(
       "INVALID_STATE",
       "swapPubkey must be a 64-char lowercase hex string"
@@ -1251,10 +1604,10 @@ function validateParams(params) {
       "pair.to must have { assetCode: string, assetScale: number, chain: string }"
     );
   }
-  if (typeof params.pair.rate !== "string" || !RATE_REGEX2.test(params.pair.rate)) {
+  if (typeof params.pair.rate !== "string" || !RATE_REGEX3.test(params.pair.rate)) {
     throw new StreamSwapError(
       "INVALID_PAIR",
-      `pair.rate must match ${RATE_REGEX2}, got ${params.pair.rate}`
+      `pair.rate must match ${RATE_REGEX3}, got ${params.pair.rate}`
     );
   }
   try {
@@ -1278,15 +1631,27 @@ function validateParams(params) {
     );
   }
   if (params.minExchangeRate !== void 0) {
-    if (typeof params.minExchangeRate !== "string" || !RATE_REGEX2.test(params.minExchangeRate) || /^0(\.0+)?$/.test(params.minExchangeRate)) {
+    if (typeof params.minExchangeRate !== "string" || !RATE_REGEX3.test(params.minExchangeRate) || /^0(\.0+)?$/.test(params.minExchangeRate)) {
       throw new StreamSwapError(
         "INVALID_STATE",
-        `minExchangeRate must be a positive decimal string matching ${RATE_REGEX2}, got ${String(
+        `minExchangeRate must be a positive decimal string matching ${RATE_REGEX3}, got ${String(
           params.minExchangeRate
         )}`
       );
     }
   }
+  if (params.receiptPubkey !== void 0 && (typeof params.receiptPubkey !== "string" || !HEX64_REGEX2.test(params.receiptPubkey))) {
+    throw new StreamSwapError(
+      "INVALID_STATE",
+      "receiptPubkey must be a 64-char lowercase hex string"
+    );
+  }
+  if (params.requireReceipts !== void 0 && typeof params.requireReceipts !== "boolean") {
+    throw new StreamSwapError(
+      "INVALID_STATE",
+      `requireReceipts must be a boolean, got ${String(params.requireReceipts)}`
+    );
+  }
   if (params.packetExpiryMs !== void 0 && (typeof params.packetExpiryMs !== "number" || !Number.isInteger(params.packetExpiryMs) || params.packetExpiryMs <= 0)) {
     throw new StreamSwapError(
       "INVALID_STATE",
@@ -1323,6 +1688,9 @@ function streamSwapControlled(params) {
     rate: params.pair.rate
   });
   const senderPubkey = getPublicKey3(params.senderSecretKey);
+  const streamNonceBytes = new Uint8Array(16);
+  getRandomValues(streamNonceBytes);
+  const streamNonce = Buffer.from(streamNonceBytes).toString("hex");
   let streamState = "running";
   let resumeDeferred = null;
   const controller = {
@@ -1373,6 +1741,7 @@ function streamSwapControlled(params) {
     params,
     frozenPair,
     senderPubkey,
+    streamNonce,
     logger,
     getState,
     setState,
@@ -1382,6 +1751,7 @@ function streamSwapControlled(params) {
     frozenPair,
     schedule,
     senderPubkey,
+    streamNonce,
     logger,
     getState,
     setState,
@@ -1390,7 +1760,15 @@ function streamSwapControlled(params) {
   return { result, controller };
 }
 function buildAndWrapPacket(input) {
-  const { params, pair, senderPubkey, sourceAmount, seq, totalPackets } = input;
+  const {
+    params,
+    pair,
+    senderPubkey,
+    sourceAmount,
+    seq,
+    totalPackets,
+    streamNonce
+  } = input;
   const nonce = new Uint8Array(16);
   getRandomValues(nonce);
   const rumor = buildSwapRumor({
@@ -1401,7 +1779,8 @@ function buildAndWrapPacket(input) {
     totalPackets,
     nonce,
     createdAt: Math.floor(Date.now() / 1e3),
-    chainRecipient: params.chainRecipient
+    chainRecipient: params.chainRecipient,
+    streamNonce
   });
   const packetExpiresAt = params.packetExpiryMs !== void 0 ? new Date(Date.now() + params.packetExpiryMs) : void 0;
   const wrapped = wrapSwapPacketToToon({
@@ -1491,6 +1870,47 @@ async function processAcceptedPacket(ctx, args) {
       return { status: "below-floor" };
     }
   }
+  let verifiedReceipt;
+  if (metadata.receipt !== void 0) {
+    const receipt = metadata.receipt;
+    let failure;
+    if (metadata.rate !== void 0 && receipt.rate !== metadata.rate) {
+      failure = `receipt.rate ${receipt.rate} does not match tape rate ${metadata.rate}`;
+    } else if (metadata.rateTimestamp !== void 0 && receipt.rateTimestamp !== metadata.rateTimestamp) {
+      failure = `receipt.rateTimestamp ${receipt.rateTimestamp} does not match tape rateTimestamp ${metadata.rateTimestamp}`;
+    } else {
+      const added = ctx.receiptTracker.add(receipt);
+      if (!added.ok) failure = `${added.code}: ${added.message}`;
+    }
+    if (failure !== void 0) {
+      logger.warn({
+        event: "stream_swap.receipt_invalid",
+        packetIndex,
+        seq: receipt.seq,
+        error: failure
+      });
+      ctx.rejections.push({
+        packetIndex,
+        sourceAmount,
+        code: "RECEIPT_INVALID",
+        message: `Stream receipt failed verification: ${failure}`
+      });
+      return { status: "receipt-invalid" };
+    }
+    verifiedReceipt = receipt;
+  } else if (params.requireReceipts === true) {
+    logger.warn({
+      event: "stream_swap.receipt_missing",
+      packetIndex
+    });
+    ctx.rejections.push({
+      packetIndex,
+      sourceAmount,
+      code: "RECEIPT_MISSING",
+      message: "FULFILL carried no stream receipt but requireReceipts is set (legacy maker without rfc-0039 receipt support?)"
+    });
+    return { status: "receipt-invalid" };
+  }
   let claimBytes;
   try {
     const ciphertext = new Uint8Array(Buffer.from(metadata.claim, "base64"));
@@ -1566,6 +1986,7 @@ async function processAcceptedPacket(ctx, args) {
     accumulated.rate = metadata.rate;
     accumulated.rateTimestamp = metadata.rateTimestamp;
   }
+  if (verifiedReceipt !== void 0) accumulated.receipt = verifiedReceipt;
   ctx.claims.push(accumulated);
   logger.debug({
     event: "stream_swap.packet_accepted",
@@ -1590,6 +2011,8 @@ async function processAcceptedPacket(ctx, args) {
         rate: metadata.rate,
         rateTimestamp: metadata.rateTimestamp
       },
+      // Issue #84: surface the verified per-fulfill receipt to the callback.
+      ...verifiedReceipt !== void 0 && { receipt: verifiedReceipt },
       state: ctx.getState() === "paused" ? "paused" : ctx.getState() === "stopped" ? "stopped" : "running"
     });
     try {
@@ -1644,10 +2067,13 @@ function finalizeResult(input) {
     cumulativeSource: cumulative.source,
     cumulativeTarget: cumulative.target,
     packetsSent: input.packetsSent,
-    packetsScheduled: input.packetsScheduled
+    packetsScheduled: input.packetsScheduled,
+    // Issue #84: the verified receipt chain — present on abort too,
+    // covering exactly the packets that filled before the halt.
+    receipts: input.ctx.receiptTracker.chain()
   };
 }
-async function runLoop(params, pair, schedule, senderPubkey, logger, getState, setState, waitForResumeOrStop) {
+async function runLoop(params, pair, schedule, senderPubkey, streamNonce, logger, getState, setState, waitForResumeOrStop) {
   const ctx = {
     params,
     pair,
@@ -1656,7 +2082,11 @@ async function runLoop(params, pair, schedule, senderPubkey, logger, getState, s
     claims: [],
     rejections: [],
     errors: [],
-    cumulative: { source: 0n, target: 0n }
+    cumulative: { source: 0n, target: 0n },
+    receiptTracker: new ReceiptChainTracker({
+      streamNonce,
+      makerPubkey: params.receiptPubkey ?? params.swapPubkey
+    })
   };
   let packetsSent = 0;
   let abortReason = "complete";
@@ -1697,7 +2127,8 @@ async function runLoop(params, pair, schedule, senderPubkey, logger, getState, s
         senderPubkey,
         sourceAmount,
         seq: packetIndex + 1,
-        totalPackets
+        totalPackets,
+        streamNonce
       });
     } catch (err) {
       logger.error({
@@ -1760,6 +2191,10 @@ async function runLoop(params, pair, schedule, senderPubkey, logger, getState, s
       abortReason = "below-floor";
       break packetLoop;
     }
+    if (outcome.status === "receipt-invalid") {
+      abortReason = "receipt-invalid";
+      break packetLoop;
+    }
     if (outcome.status === "callback-throw") {
       abortReason = "callback-throw";
       break packetLoop;
@@ -1795,7 +2230,7 @@ function classifyReject(code, message) {
   }
   return "reject";
 }
-async function runAdaptiveLoop(params, pair, senderPubkey, logger, getState, setState, waitForResumeOrStop) {
+async function runAdaptiveLoop(params, pair, senderPubkey, streamNonce, logger, getState, setState, waitForResumeOrStop) {
   const controller = params.controller;
   const ctx = {
     params,
@@ -1805,7 +2240,11 @@ async function runAdaptiveLoop(params, pair, senderPubkey, logger, getState, set
     claims: [],
     rejections: [],
     errors: [],
-    cumulative: { source: 0n, target: 0n }
+    cumulative: { source: 0n, target: 0n },
+    receiptTracker: new ReceiptChainTracker({
+      streamNonce,
+      makerPubkey: params.receiptPubkey ?? params.swapPubkey
+    })
   };
   let packetsSent = 0;
   let abortReason = "complete";
@@ -1872,7 +2311,8 @@ async function runAdaptiveLoop(params, pair, senderPubkey, logger, getState, set
             seq: packetIndex + 1,
             // Adaptive mode: the final packet count is unknown upfront —
             // `0` in the rumor's `seq` tag total position means "open".
-            totalPackets: 0
+            totalPackets: 0,
+            streamNonce
           });
         } catch (err) {
           logger.error({
@@ -1992,6 +2432,14 @@ async function runAdaptiveLoop(params, pair, senderPubkey, logger, getState, set
         });
         halt("below-floor");
         break;
+      case "receipt-invalid":
+        await observeSafe({
+          resolution: "reject",
+          rttMs: settled.rttMs,
+          remaining
+        });
+        halt("receipt-invalid");
+        break;
       case "callback-throw":
         await observeSafe({
           resolution: "fulfill",
@@ -2079,6 +2527,18 @@ export {
   unwrapSwapPacketFromToon,
   encryptFulfillClaim,
   decryptFulfillClaim,
+  STREAM_RECEIPT_VERSION,
+  STREAM_RECEIPT_SIGNING_TAG,
+  isValidStreamNonce,
+  parseStreamReceipt,
+  encodeReceiptSigningPayload,
+  signStreamReceipt,
+  verifyStreamReceipt,
+  ReceiptChainTracker,
+  serializeReceiptChain,
+  DEFAULT_RECEIPT_SESSIONS_CAP,
+  BoundedReceiptSessions,
+  issueSessionReceipt,
   SWAP_HANDLER_REJECT_CODES,
   SWAP_HANDLER_REJECT_MESSAGES,
   applyRate,
@@ -2088,4 +2548,4 @@ export {
   streamSwapControlled,
   __testing
 };
-//# sourceMappingURL=chunk-7LBYFU4L.js.map
+//# sourceMappingURL=chunk-RAZRWSJF.js.map