mtok-relay 0.1.10 → 0.2.1

package/README.md

@@ -2,7 +2,7 @@
 
 Reference seller relay for [mtok.market](https://mtok.market). Run with:
 
-    npx mtok-relay --offer <id> --model <id> --upstream <url>
+    npx mtok-relay --offer <id> --model <id> --upstream <url> --out-price <positive-usd-per-MTok>
 
 
 ---

package/dist/mtok-relay.mjs

@@ -3,7 +3,7 @@
 
 // node_modules/@noble/hashes/esm/cryptoNode.js
 import * as nc from "node:crypto";
-var crypto = nc && typeof nc === "object" && "webcrypto" in nc ? nc.webcrypto : nc && typeof nc === "object" && "randomBytes" in nc ? nc : void 0;
+var crypto2 = nc && typeof nc === "object" && "webcrypto" in nc ? nc.webcrypto : nc && typeof nc === "object" && "randomBytes" in nc ? nc : void 0;
 
 // node_modules/@noble/hashes/esm/utils.js
 function isBytes(a) {
@@ -100,11 +100,11 @@ function createHasher(hashCons) {
   return hashC;
 }
 function randomBytes(bytesLength = 32) {
-  if (crypto && typeof crypto.getRandomValues === "function") {
-    return crypto.getRandomValues(new Uint8Array(bytesLength));
+  if (crypto2 && typeof crypto2.getRandomValues === "function") {
+    return crypto2.getRandomValues(new Uint8Array(bytesLength));
   }
-  if (crypto && typeof crypto.randomBytes === "function") {
-    return Uint8Array.from(crypto.randomBytes(bytesLength));
+  if (crypto2 && typeof crypto2.randomBytes === "function") {
+    return Uint8Array.from(crypto2.randomBytes(bytesLength));
   }
   throw new Error("crypto.getRandomValues must be defined");
 }
@@ -2157,7 +2157,7 @@ var secp256k1 = createCurve({
 }, sha256);
 
 // node_modules/viem/_esm/errors/version.js
-var version = "2.54.6";
+var version = "2.55.1";
 
 // node_modules/viem/_esm/errors/base.js
 var errorConfig = {
@@ -4646,15 +4646,22 @@ function readRelayConfig({ argv = process.argv.slice(2), env = process.env } = {
   const rpcFlag = flag(argv, "--rpc");
   const settlementPubkeyFlag = flag(argv, "--settlement-pubkey");
   const sellerAgentId = flag(argv, "--seller-agent");
-  const outPrice = Number(flag(argv, "--out-price") ?? 0);
+  const outPrice = Number(flag(argv, "--out-price"));
   const inPrice = Number(flag(argv, "--in-price") ?? outPrice);
   const redemptionFlag = flag(argv, "--redemption-file") ?? env.RELAY_REDEMPTION_FILE;
-  const redemptionFile = redemptionFlag === void 0 ? "./.mtok-redemption.jsonl" : redemptionFlag || null;
+  if (redemptionFlag === "") throw new Error("--redemption-file cannot be empty; paid serves require durable redemption");
+  const redemptionFile = redemptionFlag === void 0 ? "./.mtok-redemption.jsonl" : redemptionFlag;
   const denylistRaw = flag(argv, "--payer-denylist") ?? env.RELAY_PAYER_DENYLIST ?? "";
   const payerDenylist = String(denylistRaw).split(",").map((a) => a.trim().toLowerCase()).filter(Boolean);
   if (!offerId) throw new Error("--offer <id> is required");
   if (!model) throw new Error("--model <id> is required (the offer model you serve)");
   if (!upstream) throw new Error("--upstream <url> is required");
+  if (!Number.isFinite(outPrice) || outPrice <= 0) {
+    throw new Error("--out-price <usd/MTok> is required and must be finite and positive");
+  }
+  if (!Number.isFinite(inPrice) || inPrice <= 0) {
+    throw new Error("--in-price <usd/MTok> must be finite and positive");
+  }
   const mtokApiKey = env.MTOK_API_KEY;
   const upstreamKey = env.UPSTREAM_KEY;
   const relayWalletKey = env.RELAY_WALLET_KEY;
@@ -4771,66 +4778,125 @@ function startRelayServer({ config, handleDraw }) {
   return server;
 }
 
-// lib.mjs
-function enforceModelEcho(upstreamModel, offerModel) {
-  if (String(upstreamModel) !== String(offerModel))
-    throw new Error(`model mismatch: upstream ${upstreamModel} != offer ${offerModel}`);
-}
-function configuredFeeAtomic({ sellerUsdAtomic, feeAddress, feeBps }) {
-  const bps = BigInt(Math.trunc(Math.max(0, Number(feeBps) || 0)));
-  if (!feeAddress || bps === 0n) return 0n;
-  return (BigInt(sellerUsdAtomic || 0) * bps + 5000n) / 10000n;
-}
-var CHARS_PER_TOKEN_EST = 3.2;
-function estimateInputTokens(messages) {
-  let chars = 0;
-  for (const m of messages ?? []) {
-    const c = m?.content;
-    if (typeof c === "string") chars += c.length;
-    else if (Array.isArray(c)) for (const part of c) chars += String(part?.text ?? "").length;
-  }
-  return Math.ceil(chars / CHARS_PER_TOKEN_EST);
-}
-function boundServe({ messages, budgetUsd, inPrice, outPrice, reqMax, contextCeil = 4096 }) {
-  const estIn = estimateInputTokens(messages);
-  const estInCostUsd = estIn * (Number(inPrice) > 0 ? Number(inPrice) : 0) / 1e6;
-  if (estInCostUsd >= budgetUsd) return { refuse: true, estIn, estInCostUsd };
-  const outBudgetUsd = budgetUsd - estInCostUsd;
-  let maxTok = contextCeil;
-  if (Number(reqMax) > 0) maxTok = Math.min(maxTok, Math.floor(Number(reqMax)));
-  if (Number(outPrice) > 0) maxTok = Math.min(maxTok, Math.floor(outBudgetUsd / Number(outPrice) * 1e6));
-  return { refuse: false, maxTok: Math.max(1, maxTok), estIn, estInCostUsd };
-}
-
 // src/redemption.mjs
 import fs from "node:fs";
+import crypto3 from "node:crypto";
 var DEFAULT_RETENTION_MS = 7 * 24 * 60 * 60 * 1e3;
 function createRedemptionStore({ file = null, retentionMs = DEFAULT_RETENTION_MS, now = () => Date.now(), log = console } = {}) {
   const map = /* @__PURE__ */ new Map();
+  const claimsDir = file ? `${file}.claims` : null;
   let durable = false;
+  let seenVersion = null;
+  const recordFor = (key, entry) => ({
+    k: key,
+    at: entry.at,
+    state: entry.state,
+    ...entry.state === "complete" ? { payload: entry.payload } : {}
+  });
+  const syncWrite = (target, flags, data) => {
+    const fd = fs.openSync(target, flags);
+    try {
+      fs.writeFileSync(fd, data);
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+  };
+  const readRecords = () => {
+    const loaded = /* @__PURE__ */ new Map();
+    if (!fs.existsSync(file)) return loaded;
+    const cutoff = now() - retentionMs;
+    let lineNumber = 0;
+    for (const line of fs.readFileSync(file, "utf8").split("\n")) {
+      lineNumber += 1;
+      if (!line.trim()) continue;
+      let parsed;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        throw new Error(`malformed redemption record at line ${lineNumber}`);
+      }
+      const { k, at } = parsed;
+      if (typeof k !== "string" || !k || !Number.isFinite(Number(at))) {
+        throw new Error(`malformed redemption record at line ${lineNumber}`);
+      }
+      if (Number(at) < cutoff) continue;
+      const state2 = parsed.state === "pending" ? "pending" : "complete";
+      loaded.set(k, { state: state2, at: Number(at), ...state2 === "complete" ? { payload: parsed.payload } : {} });
+    }
+    return loaded;
+  };
+  const fileVersion = () => {
+    try {
+      const stat = fs.statSync(file);
+      return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeMs}`;
+    } catch {
+      return null;
+    }
+  };
   if (file) {
     try {
-      if (fs.existsSync(file)) {
-        const cutoff = now() - retentionMs;
-        for (const line of fs.readFileSync(file, "utf8").split("\n")) {
-          if (!line.trim()) continue;
-          try {
-            const { k, at, payload } = JSON.parse(line);
-            if (k && Number(at) >= cutoff) map.set(k, { payload, at: Number(at) });
-          } catch {
-          }
+      for (const [key, entry] of readRecords()) map.set(key, entry);
+      const compact = `${file}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+      try {
+        syncWrite(compact, "w", [...map].map(([k, e]) => JSON.stringify(recordFor(k, e))).join("\n") + (map.size ? "\n" : ""));
+        fs.renameSync(compact, file);
+      } finally {
+        fs.rmSync(compact, { force: true });
+      }
+      fs.mkdirSync(claimsDir, { recursive: true });
+      const markerCutoff = Date.now() - retentionMs;
+      for (const name of fs.readdirSync(claimsDir)) {
+        try {
+          const marker = `${claimsDir}/${name}`;
+          if (fs.statSync(marker).mtimeMs < markerCutoff) fs.unlinkSync(marker);
+        } catch {
         }
       }
-      fs.writeFileSync(file, [...map].map(([k, e]) => JSON.stringify({ k, at: e.at, payload: e.payload })).join("\n") + (map.size ? "\n" : ""));
       durable = true;
+      seenVersion = fileVersion();
       log.log?.(`mtok-relay: durable redemption at ${file} (${map.size} entries loaded)`);
     } catch (e) {
-      log.warn?.(`mtok-relay: redemption file ${file} not writable (${e.message}); redemption is IN-MEMORY ONLY, a restart can re-serve a paid draw (#495). Point --redemption-file at a durable path.`);
+      map.clear();
+      log.warn?.(`mtok-relay: redemption file ${file} not writable (${e.message}); paid serves will fail closed. Point --redemption-file at a durable path.`);
       durable = false;
     }
   } else {
-    log.warn?.("mtok-relay: no --redemption-file, redemption is IN-MEMORY ONLY, a restart or long idle can re-serve one payment for a fresh inference (#495). Set --redemption-file to a durable path.");
+    log.warn?.("mtok-relay: no --redemption-file; paid serves will fail closed because a claim cannot be persisted. Set --redemption-file to a durable path.");
   }
+  const append = (key, entry) => {
+    if (!durable) throw new Error("durable redemption unavailable");
+    syncWrite(file, "a", JSON.stringify(recordFor(key, entry)) + "\n");
+    seenVersion = fileVersion();
+  };
+  const markerFor = (key) => `${claimsDir}/${crypto3.createHash("sha256").update(String(key)).digest("hex")}`;
+  const markClaimed = (key) => {
+    if (!durable) throw new Error("durable redemption unavailable");
+    const marker = markerFor(key);
+    try {
+      syncWrite(marker, "wx", String(key) + "\n");
+      return true;
+    } catch (e) {
+      if (e?.code === "EEXIST") return false;
+      throw e;
+    }
+  };
+  const refresh = () => {
+    if (!durable) return;
+    const version2 = fileVersion();
+    if (!version2 || version2 === seenVersion) return;
+    try {
+      for (const [key, entry] of readRecords()) map.set(key, entry);
+      seenVersion = version2;
+    } catch (e) {
+      log.warn?.(`mtok-relay: could not refresh redemption file ${file} (${e.message}); keeping the existing fail-closed state`);
+    }
+  };
+  const state = (key) => {
+    const current = map.get(key)?.state;
+    if (durable && (!current || current === "pending")) refresh();
+    return map.get(key)?.state ?? null;
+  };
   return {
     durable,
     retentionMs,
@@ -4838,18 +4904,30 @@ function createRedemptionStore({ file = null, retentionMs = DEFAULT_RETENTION_MS
     has(key) {
       return map.has(key);
     },
+    state,
     get(key) {
-      return map.get(key)?.payload;
+      return state(key) === "complete" ? map.get(key).payload : void 0;
+    },
+    claim(key, markerKey = key) {
+      if (map.has(key)) return false;
+      if (!markClaimed(markerKey)) return false;
+      const entry = { state: "pending", at: now() };
+      append(key, entry);
+      map.set(key, entry);
+      return true;
     },
+    complete(key, payload) {
+      if (map.get(key)?.state !== "pending") throw new Error("redemption is not pending");
+      const entry = { state: "complete", payload, at: now() };
+      append(key, entry);
+      map.set(key, entry);
+    },
+    // Backward-compatible store API for callers which only persist completed
+    // payloads. The relay runtime itself always uses claim() then complete().
     set(key, payload) {
-      const at = now();
-      map.set(key, { payload, at });
-      if (durable) {
-        try {
-          fs.appendFileSync(file, JSON.stringify({ k: key, at, payload }) + "\n");
-        } catch {
-        }
-      }
+      const entry = { state: "complete", payload, at: now() };
+      if (durable) append(key, entry);
+      map.set(key, entry);
     }
   };
 }
@@ -5124,6 +5202,263 @@ function createOnchainVerifier({
   };
 }
 
+// bridge/serve-core.mjs
+var BALANCE_EPSILON = 1e-6;
+var REQUEST_NONCE_RE = /^0x[0-9a-fA-F]{32}$/;
+var CHAT_ROLES = /* @__PURE__ */ new Set(["developer", "system", "user", "assistant"]);
+var REQUEST_KEYS = /* @__PURE__ */ new Set(["model", "messages", "max_tokens", "temperature", "response_format", "stream", "n"]);
+async function hash32(v) {
+  const bytes = new TextEncoder().encode(typeof v === "string" ? v : JSON.stringify(v ?? null));
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return "0x" + [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function legacyContentText(content) {
+  const render = (part) => {
+    if (typeof part === "string") return part;
+    if (Array.isArray(part)) return part.map(render).filter(Boolean).join("\n");
+    if (part == null) return "";
+    if (typeof part !== "object") return String(part);
+    if (typeof part.text === "string") return part.text;
+    if (typeof part.content === "string") return part.content;
+    const type = typeof part.type === "string" && /^[a-z0-9_-]{1,32}$/i.test(part.type) ? part.type : "non-text";
+    return `[${type} omitted]`;
+  };
+  return render(content) || "[empty legacy content]";
+}
+function sanitizeLegacyMessage(message) {
+  const source = message && typeof message === "object" && !Array.isArray(message) ? message : { content: message };
+  if (CHAT_ROLES.has(source.role)) return { role: source.role, content: legacyContentText(source.content) };
+  const label = source.role === "tool" || source.role === "function" ? source.role : "legacy";
+  return { role: "user", content: `[${label} message]
+${legacyContentText(source.content)}` };
+}
+function validateRequest(request, model, { legacy = false } = {}) {
+  if (!request || typeof request !== "object" || Array.isArray(request)) {
+    return { error: "request must be an object" };
+  }
+  const unknown = Object.keys(request).find((key) => !REQUEST_KEYS.has(key));
+  if (unknown && !legacy) return { error: `unsupported request field: ${unknown}` };
+  if (!legacy && request.model != null && String(request.model) !== String(model)) {
+    return { error: `request model ${request.model} is not served here` };
+  }
+  if (!Array.isArray(request.messages) || request.messages.length === 0) {
+    return { error: "request.messages must be a nonempty array" };
+  }
+  if (!legacy) {
+    for (const message of request.messages) {
+      if (!message || typeof message !== "object" || Array.isArray(message)) {
+        return { error: "each message must be an object" };
+      }
+      const extra = Object.keys(message).find((key) => key !== "role" && key !== "content");
+      if (extra) return { error: `unsupported message field: ${extra}` };
+      if (!CHAT_ROLES.has(message.role)) return { error: `unsupported message role: ${message.role}` };
+      if (typeof message.content !== "string") return { error: "message content must be plain text" };
+    }
+  }
+  if (!legacy && request.stream != null && request.stream !== false) return { error: "streaming is not supported" };
+  if (!legacy && request.n != null && request.n !== 1) return { error: "request.n must be 1" };
+  const validMaxTokens = Number.isInteger(request.max_tokens) && request.max_tokens > 0;
+  if (!legacy && request.max_tokens != null && !validMaxTokens) {
+    return { error: "max_tokens must be a positive integer" };
+  }
+  const validTemperature = Number.isFinite(request.temperature) && request.temperature >= 0 && request.temperature <= 2;
+  if (!legacy && request.temperature != null && !validTemperature) {
+    return { error: "temperature must be between 0 and 2" };
+  }
+  let validResponseFormat = false;
+  if (request.response_format != null) {
+    const format = request.response_format;
+    validResponseFormat = !!format && typeof format === "object" && !Array.isArray(format) && Object.keys(format).length === 1 && ["json_object", "text"].includes(format.type);
+    if (!legacy && !validResponseFormat) {
+      return { error: 'response_format must be exactly { type: "json_object" } or { type: "text" }' };
+    }
+  }
+  return {
+    safeRequest: {
+      model,
+      messages: legacy ? request.messages.map(sanitizeLegacyMessage) : request.messages.map(({ role, content }) => ({ role, content })),
+      ...validMaxTokens ? { max_tokens: request.max_tokens } : {},
+      ...validTemperature ? { temperature: request.temperature } : {},
+      ...validResponseFormat ? { response_format: { type: request.response_format.type } } : {}
+    }
+  };
+}
+function enforceModelEcho(upstreamModel, offerModel) {
+  if (String(upstreamModel) !== String(offerModel))
+    throw new Error(`model mismatch: upstream ${upstreamModel} != offer ${offerModel}`);
+}
+function configuredFeeAtomic({ sellerUsdAtomic, feeAddress, feeBps }) {
+  const bps = BigInt(Math.trunc(Math.max(0, Number(feeBps) || 0)));
+  if (!feeAddress || bps === 0n) return 0n;
+  return (BigInt(sellerUsdAtomic || 0) * bps + 5000n) / 10000n;
+}
+var MESSAGE_OVERHEAD_TOKENS = 4;
+function estimateInputTokens(messages) {
+  const utf8 = new TextEncoder();
+  let tokens = 3;
+  for (const m of messages ?? []) {
+    tokens += MESSAGE_OVERHEAD_TOKENS;
+    tokens += utf8.encode(String(m?.role ?? "")).length;
+    tokens += utf8.encode(typeof m?.content === "string" ? m.content : JSON.stringify(m?.content ?? null)).length;
+  }
+  return tokens;
+}
+function boundServe({ messages, budgetUsd, inPrice, outPrice, reqMax, contextCeil = 4096 }) {
+  const estIn = estimateInputTokens(messages);
+  const estInCostUsd = estIn * (Number(inPrice) > 0 ? Number(inPrice) : 0) / 1e6;
+  if (estInCostUsd >= budgetUsd) return { refuse: true, reason: "input", estIn, estInCostUsd };
+  const outBudgetUsd = budgetUsd - estInCostUsd;
+  let maxTok = contextCeil;
+  if (Number(reqMax) > 0) maxTok = Math.min(maxTok, Math.floor(Number(reqMax)));
+  if (!Number.isFinite(Number(outPrice)) || Number(outPrice) <= 0) {
+    return { refuse: true, reason: "output_price", estIn, estInCostUsd };
+  }
+  maxTok = Math.min(maxTok, Math.floor(outBudgetUsd / Number(outPrice) * 1e6));
+  if (maxTok < 1) return { refuse: true, reason: "output", estIn, estInCostUsd };
+  return { refuse: false, maxTok, estIn, estInCostUsd };
+}
+function createServeCore({
+  model,
+  inPrice,
+  outPrice,
+  verifier,
+  redemption,
+  upstream,
+  log,
+  offerId,
+  sellerAgentId,
+  sellerWallet,
+  dripContractAddress,
+  feeRecipient,
+  feeBps,
+  screenPayer
+}) {
+  const serve = async (body) => {
+    const { bookingId, n, buyerId, request, requestNonce, drawPaidTxHash } = body;
+    const hasRequestNonce = Object.hasOwn(body, "requestNonce");
+    if (!bookingId) return { status: 400, body: { error: "bad_request", detail: "DRAW needs bookingId" } };
+    if (n == null) return { status: 400, body: { error: "bad_request", detail: "DRAW needs a delivery index n (per-booking idempotency key)" } };
+    if (!Number.isSafeInteger(n) || n < 0 || n > 4294967295) {
+      return { status: 400, body: { error: "bad_request", detail: "DRAW delivery index n must be a nonnegative uint32 integer" } };
+    }
+    if (hasRequestNonce && !REQUEST_NONCE_RE.test(requestNonce)) {
+      return { status: 400, body: { error: "bad_request", detail: "DRAW needs requestNonce as 16 random bytes encoded as 0x-prefixed hex" } };
+    }
+    const checked = validateRequest(request, model, { legacy: !hasRequestNonce });
+    if (checked.error) return { status: 400, body: { error: "bad_request", detail: checked.error } };
+    const requestHashScheme = hasRequestNonce ? "nonce-v1" : "legacy-v0";
+    const requestHash = hasRequestNonce ? await hash32({ request, requestNonce }) : await hash32(request);
+    const cacheKey = `${requestHashScheme}:${bookingId}:${n}:${requestHash}`;
+    const oldLegacyKey = hasRequestNonce ? null : `${bookingId}:${n}:${requestHash}`;
+    if (!dripContractAddress) {
+      return { status: 402, body: { error: "contract_mode_required", detail: "this relay only serves contract-mode draws; the platform is not reporting a dripContractAddress" } };
+    }
+    if (!drawPaidTxHash) return { status: 402, body: { error: "draw_payment_required", detail: "contract mode requires drawPaidTxHash before upstream delivery" } };
+    let paid;
+    try {
+      paid = await verifier.verifyDrawPaid(drawPaidTxHash, {
+        contractAddress: dripContractAddress,
+        buyerAgentId: buyerId,
+        sellerAgentId,
+        // when set, enforces the offer-owner match (#codex review)
+        bookingId,
+        offerId,
+        model,
+        n,
+        requestHash,
+        sellerWallet,
+        feeRecipient,
+        // #580: refuse a payment older than the redemption window. The JSONL
+        // payload cache AND the claim markers are both aged out at boot (#600),
+        // so past retention this age bound is the sole replay defense (its
+        // skip-on-unreadable-block residual is named in redemption.mjs). An
+        // honest retry is seconds-to-minutes old, never days.
+        maxPaidAgeMs: redemption.retentionMs
+      });
+    } catch (e) {
+      return { status: 402, body: { error: "payment_unverified", detail: e.message } };
+    }
+    if (!paid?.ok) return { status: 402, body: { error: "payment_unverified", detail: paid?.reason || "unknown" } };
+    const expectedFee = configuredFeeAtomic({
+      sellerUsdAtomic: paid.event.sellerUsdAtomic,
+      feeAddress: feeRecipient,
+      feeBps
+    });
+    if (BigInt(paid.event.feeUsdAtomic || 0) < expectedFee) {
+      return { status: 402, body: { error: "payment_unverified", detail: "fee_amount_too_low" } };
+    }
+    if (screenPayer) {
+      try {
+        if (await screenPayer(String(paid.from || "").toLowerCase())) {
+          return { status: 403, body: { error: "payer_denied", detail: "the verified payer wallet is denylisted by this relay" } };
+        }
+      } catch (e) {
+        return { status: 403, body: { error: "payer_denied", detail: "payer screening failed: " + e.message } };
+      }
+    }
+    let storedKey = cacheKey;
+    let redemptionState = await redemption.state(storedKey);
+    if (!redemptionState && oldLegacyKey) {
+      const oldLegacyState = await redemption.state(oldLegacyKey);
+      if (oldLegacyState) {
+        storedKey = oldLegacyKey;
+        redemptionState = oldLegacyState;
+      } else {
+        redemptionState = await redemption.state(cacheKey);
+      }
+    }
+    if (redemptionState === "complete") return { status: 200, body: await redemption.get(storedKey) };
+    if (redemptionState === "pending") {
+      return { status: 409, body: { error: "draw_pending", detail: "this paid draw was already claimed; refusing to run upstream again", _bookingId: bookingId } };
+    }
+    const paidEvent = paid.event;
+    const remainingUsd = Number(paid.event.sellerUsdAtomic || 0) / 1e6;
+    if (remainingUsd < BALANCE_EPSILON) {
+      return { status: 402, body: { error: "balance_exhausted", detail: `remainingUsd=${remainingUsd}`, _bookingId: bookingId, remainingUsd } };
+    }
+    const eventInPriceUsd = Number(paidEvent.inputPricePerMTokAtomic || 0) / 1e6;
+    const eventOutPriceUsd = Number(paidEvent.outputPricePerMTokAtomic || 0) / 1e6;
+    const boundInPrice = Math.max(Number(inPrice) || 0, eventInPriceUsd);
+    const boundOutPrice = Math.max(Number(outPrice) || 0, eventOutPriceUsd);
+    const bound = boundServe({ messages: checked.safeRequest.messages, budgetUsd: remainingUsd, inPrice: boundInPrice, outPrice: boundOutPrice, reqMax: checked.safeRequest.max_tokens });
+    if (bound.refuse) {
+      const error = bound.reason === "input" ? "input_too_large" : "output_unfunded";
+      return { status: 402, body: { error, detail: `estimated input (~${bound.estIn} tokens, $${bound.estInCostUsd.toFixed(6)}) leaves no safely funded output in the paid amount ($${remainingUsd})`, _bookingId: bookingId, remainingUsd } };
+    }
+    const safeRequest = { ...checked.safeRequest, model, max_tokens: bound.maxTok };
+    try {
+      if (!await redemption.claim(cacheKey, oldLegacyKey ?? cacheKey)) {
+        return { status: 409, body: { error: "draw_pending", detail: "this paid draw was already claimed; refusing to run upstream again", _bookingId: bookingId } };
+      }
+    } catch (e) {
+      return { status: 503, body: { error: "redemption_unavailable", detail: `could not durably claim the paid draw: ${e.message}`, _bookingId: bookingId } };
+    }
+    let completion;
+    try {
+      completion = await upstream(safeRequest);
+    } catch (e) {
+      return { status: 502, body: { error: "upstream_error", detail: e.message } };
+    }
+    try {
+      enforceModelEcho(completion.model, model);
+    } catch (e) {
+      return { status: 502, body: { error: "model_mismatch", detail: e.message } };
+    }
+    const usage = completion.usage ?? {};
+    const inTok = Number(usage.prompt_tokens ?? usage.input_tokens ?? 0) || 0;
+    const outTok = Number(usage.completion_tokens ?? usage.output_tokens ?? 0) || 0;
+    const usedUsd = (inTok * Number(paidEvent.inputPricePerMTokAtomic || 0) + outTok * Number(paidEvent.outputPricePerMTokAtomic || 0)) / 1e12;
+    const payload = { ...completion, _bookingId: bookingId, remainingUsd: Math.max(0, Math.round((remainingUsd - usedUsd) * 1e6) / 1e6) };
+    try {
+      await redemption.complete(cacheKey, payload);
+    } catch (e) {
+      (log ?? console).error?.(`mtok serve core: completion for ${cacheKey} could not be persisted (${e.message}); retries will remain pending`);
+    }
+    return { status: 200, body: payload };
+  };
+  return { serve };
+}
+
 // bridge/bridge.mjs
 function httpUpstream({ baseUrl, key }) {
   const url = String(baseUrl || "").replace(/\/$/, "") + "/chat/completions";
@@ -5162,11 +5497,8 @@ var BASE_SEPOLIA_RPCS = [
 var rpcUrlsFor = (chainId, override) => override ? [override] : Number(chainId) === 8453 ? BASE_MAINNET_RPCS : BASE_SEPOLIA_RPCS;
 
 // src/runtime.mjs
-import crypto2 from "node:crypto";
-var BALANCE_EPSILON = 1e-6;
-var hash32 = (v) => "0x" + crypto2.createHash("sha256").update(typeof v === "string" ? v : JSON.stringify(v ?? null)).digest("hex");
 async function createRelayRuntime(config) {
-  const served = createRedemptionStore({ file: config.redemptionFile });
+  const served = createRedemptionStore({ file: config.redemptionFile, log: config.log });
   const drawLocks = /* @__PURE__ */ new Map();
   const platform = await fetchPlatformConfig(config);
   const verifier = createOnchainVerifier({ rpcUrls: rpcUrlsFor(platform.chainId, config.rpcFlag), usdcAddress: platform.usdcAddress, expectedChainId: platform.chainId });
@@ -5180,6 +5512,22 @@ async function createRelayRuntime(config) {
     if (screenPayer && await screenPayer(payer)) return true;
     return false;
   };
+  const core = createServeCore({
+    model: config.model,
+    inPrice: config.inPrice,
+    outPrice: config.outPrice,
+    verifier,
+    redemption: served,
+    upstream,
+    log: config.log,
+    offerId: config.offerId,
+    sellerAgentId: config.sellerAgentId,
+    sellerWallet: config.settlementAddr,
+    dripContractAddress: platform.dripContractAddress,
+    feeRecipient: platform.feeAddress,
+    feeBps: platform.feeBps,
+    screenPayer: payerDenied
+  });
   const withBookingLock = async (bookingId, fn) => {
     const previous = drawLocks.get(bookingId) || Promise.resolve();
     let release;
@@ -5198,89 +5546,10 @@ async function createRelayRuntime(config) {
       if (drawLocks.get(bookingId) === tail) drawLocks.delete(bookingId);
     }
   };
-  const handleDraw = async (body, res) => {
-    const { bookingId, n, buyerId, request, drawPaidTxHash } = body;
-    if (!bookingId) return send(res, 400, { error: "bad_request", detail: "DRAW needs bookingId" });
-    if (n == null) return send(res, 400, { error: "bad_request", detail: "DRAW needs a delivery index n (per-booking idempotency key)" });
-    return withBookingLock(bookingId, async () => {
-      const requestHash = hash32(request);
-      const cacheKey = `${bookingId}:${n}:${requestHash}`;
-      if (!platform.dripContractAddress) {
-        return send(res, 402, { error: "contract_mode_required", detail: "this relay only serves contract-mode draws; the platform is not reporting a dripContractAddress" });
-      }
-      if (!drawPaidTxHash) return send(res, 402, { error: "draw_payment_required", detail: "contract mode requires drawPaidTxHash before upstream delivery" });
-      let paid;
-      try {
-        paid = await verifier.verifyDrawPaid(drawPaidTxHash, {
-          contractAddress: platform.dripContractAddress,
-          buyerAgentId: buyerId,
-          sellerAgentId: config.sellerAgentId,
-          // when set, enforces the offer-owner match (#codex review)
-          bookingId,
-          offerId: config.offerId,
-          model: config.model,
-          n,
-          requestHash,
-          sellerWallet: config.settlementAddr,
-          feeRecipient: platform.feeAddress,
-          // #580: refuse a payment older than the redemption window. served.has() is the
-          // primary one-serve guard, but it's pruned by age and lost on an in-memory restart;
-          // this on-chain age bound closes the re-serve hole those cases open (a stale replay
-          // buying a fresh inference). An honest retry is seconds-to-minutes old, never days.
-          maxPaidAgeMs: served.retentionMs
-        });
-      } catch (e) {
-        return send(res, 402, { error: "payment_unverified", detail: e.message });
-      }
-      if (!paid?.ok) return send(res, 402, { error: "payment_unverified", detail: paid?.reason || "unknown" });
-      const expectedFee = configuredFeeAtomic({
-        sellerUsdAtomic: paid.event.sellerUsdAtomic,
-        feeAddress: platform.feeAddress,
-        feeBps: platform.feeBps
-      });
-      if (BigInt(paid.event.feeUsdAtomic || 0) < expectedFee) {
-        return send(res, 402, { error: "payment_unverified", detail: "fee_amount_too_low" });
-      }
-      try {
-        if (await payerDenied(String(paid.from || "").toLowerCase())) {
-          return send(res, 403, { error: "payer_denied", detail: "the verified payer wallet is denylisted by this relay" });
-        }
-      } catch (e) {
-        return send(res, 403, { error: "payer_denied", detail: "payer screening failed: " + e.message });
-      }
-      if (served.has(cacheKey)) return send(res, 200, served.get(cacheKey));
-      const paidEvent = paid.event;
-      const remainingUsd = Number(paid.event.sellerUsdAtomic || 0) / 1e6;
-      if (remainingUsd <= BALANCE_EPSILON) {
-        return send(res, 402, { error: "balance_exhausted", detail: `remainingUsd=${remainingUsd}`, _bookingId: bookingId, remainingUsd });
-      }
-      const eventInPriceUsd = Number(paidEvent.inputPricePerMTokAtomic || 0) / 1e6;
-      const inPrice = Math.max(Number(config.inPrice) || 0, eventInPriceUsd);
-      const bound = boundServe({ messages: request?.messages, budgetUsd: remainingUsd, inPrice, outPrice: config.outPrice, reqMax: Number(request?.max_tokens) });
-      if (bound.refuse) {
-        return send(res, 402, { error: "input_too_large", detail: `estimated input (~${bound.estIn} tokens, $${bound.estInCostUsd.toFixed(6)}) meets or exceeds the paid amount ($${remainingUsd}); send a shorter prompt or pay for more`, _bookingId: bookingId, remainingUsd });
-      }
-      const safeRequest = { ...request, max_tokens: bound.maxTok };
-      let completion;
-      try {
-        completion = await upstream(safeRequest);
-      } catch (e) {
-        return send(res, 502, { error: "upstream_error", detail: e.message });
-      }
-      try {
-        enforceModelEcho(completion.model, config.model);
-      } catch (e) {
-        return send(res, 502, { error: "model_mismatch", detail: e.message });
-      }
-      const usage = completion.usage ?? {};
-      const inTok = Number(usage.prompt_tokens ?? usage.input_tokens ?? 0) || 0;
-      const outTok = Number(usage.completion_tokens ?? usage.output_tokens ?? 0) || 0;
-      const usedUsd = (inTok * Number(paidEvent.inputPricePerMTokAtomic || 0) + outTok * Number(paidEvent.outputPricePerMTokAtomic || 0)) / 1e12;
-      const payload = { ...completion, _bookingId: bookingId, remainingUsd: Math.max(0, Math.round((remainingUsd - usedUsd) * 1e6) / 1e6) };
-      served.set(cacheKey, payload);
-      return send(res, 200, payload);
-    });
-  };
+  const handleDraw = (body, res) => withBookingLock(String(body?.bookingId ?? ""), async () => {
+    const out = await core.serve(body);
+    return send(res, out.status, out.body);
+  });
   return { handleDraw };
 }
 async function fetchPlatformConfig(config) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mtok-relay",
-  "version": "0.1.10",
-  "description": "Reference seller relay for mtok.market — accepts on-chain-prepaid chunk draws and serves inference from an upstream you control. Run with: npx mtok-relay --offer <id> --model <id> --upstream <url>.",
+  "version": "0.2.1",
+  "description": "Reference seller relay for mtok.market — accepts on-chain-prepaid chunk draws and serves inference from an upstream you control.",
   "type": "module",
   "bin": {
     "mtok-relay": "dist/mtok-relay.mjs"