mtok-bridge 0.3.5 → 0.4.1

package/README.md

@@ -53,6 +53,38 @@ the verifier's payment timestamp, so a store migrating old claims can refuse amb
 pre-cutover payments. Existing stores may ignore these additional arguments. The core still
 verifies the payment before reading a completion, and known claims never run upstream again.
 
+Set `replayOnly: true` when retiring a payment domain. The core still verifies the
+payment before replaying a saved completion or returning its pending status. An
+unrecorded payment returns 503 before fee evaluation, input counting, claiming or
+inference. Quotes also return 503. Keep the legacy payment verifier and store
+available for these retries; this mode never admits new paid work.
+
+The new core requires `countInputTokens(safeRequest)`, returning a nonnegative safe integer
+or a promise for one. The host must count its actual provider prompt, including its chat
+template and special tokens. A missing, failed or invalid counter returns 503 before claiming
+a fresh draw. Completed and pending retries retain their existing outcomes without counting
+again. The old byte-estimate export is retained for compatibility; neither the core nor
+the current SDK uses it to authorize spending.
+
+`core.quote(request)` validates the same request and returns `{ status, body }` with
+`model`, `offerId`, `inputTokens`, `maxInputTokens`, `maxOutputTokens`, and the decimal-string
+prices `inputPricePerMTokAtomic` / `outputPricePerMTokAtomic`. It performs no payment
+verification, claim or inference. Expose it at `POST /quote` with `{ request }` under the
+same request-size, concurrency and rate limits as `/chunk`. The paid path recounts before
+claiming; a quote does not override payment verification or lock provider configuration.
+
+For a vLLM-compatible provider, `httpInputCounter({ url, key })` calls its native `/tokenize`
+chat endpoint with the same model and messages, `add_generation_prompt:true`, and
+`add_special_tokens:false`. The provider must render exactly the chat template used by
+inference. Unsupported providers need their own counter; there is no character-estimate
+fallback. The tokenization request has a five-second deadline and a bounded response body.
+
+`maxInputTokens` sets the hard input ceiling (default 131072). `maxOutputTokens` retains its
+32768 default. `boundServe` now takes `inputTokens`, `budgetUsdAtomic`, `inPriceAtomic` and
+`outPriceAtomic`. Prices are atomic USD per million tokens. It reserves input in integer
+arithmetic and funds output only from the remainder. The core uses the higher of the host's
+price and the verified payment's committed price for each leg.
+
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtok-bridge",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "description": "Serve any model as an OpenAI-compatible API with a key. No payment, no market, runs anywhere node runs. The transport core behind mtok.market's seller relay.",
   "type": "module",
   "bin": {

package/src/bridge.mjs

@@ -75,6 +75,33 @@ export function httpUpstream({ baseUrl, key, timeoutMs }) {
   };
 }
 
+// The provider owns the chat template. Its tokenization endpoint must use the
+// same model and renderer as /chat/completions; a character estimate cannot
+// replace this call. This is the vLLM TokenizeChatRequest contract.
+export function httpInputCounter({ url, key, timeoutMs = 5000 }) {
+  return async ({ model, messages }) => {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...(key ? { authorization: `Bearer ${key}` } : {}) },
+      body: JSON.stringify({ model, messages, add_generation_prompt: true, add_special_tokens: false }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!response.ok) throw new Error(`upstream tokenization ${response.status}`);
+    // Native tokenizers also return every token ID. Bound that response before
+    // parsing, while allowing a full token array for the relay's 256 KB input.
+    const decoder = new TextDecoder();
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of response.body) {
+      size += chunk.byteLength;
+      if (size > 4 * 1024 * 1024) throw new Error('upstream tokenization response is too large');
+      chunks.push(decoder.decode(chunk, { stream: true }));
+    }
+    chunks.push(decoder.decode());
+    return JSON.parse(chunks.join('')).count;
+  };
+}
+
 // The SECOND upstream mode (#566): a Cloudflare Workers AI binding instead of an HTTP endpoint.
 // `ai` is the Worker's `env.AI` (has `.run(model, { messages, max_tokens })`). Returns the same
 // upstream(payload) contract as httpUpstream, normalizing Workers AI's output (native `{ response,

package/src/serve-core.mjs

@@ -161,24 +161,8 @@ export function configuredFeeAtomic({ sellerUsdAtomic, feeAddress, feeBps }) {
   return (BigInt(sellerUsdAtomic || 0) * bps + 5000n) / 10000n;
 }
 
-// Tokenizer-independent input estimate, byte-aware with a safety margin.
-//
-// #626: this used to count one token per UTF-8 byte, i.e. a true worst-case
-// bound (a tokenizer cannot emit more text tokens than bytes). That bound is
-// correct and roughly 4x too pessimistic for real text, and the over-estimate
-// is NOT free: boundServe refuses a draw whose estimated input cost alone meets
-// the payment, and that refusal happens AFTER the buyer has paid on chain. A
-// real buyer sending a ~4KB prompt on a budget that comfortably covered it was
-// refused every night for two weeks and auto-disputed, silently.
-//
-// So estimate realistically and keep the margin explicit. BYTES_PER_TOKEN_EST
-// of 3.2 is the English average (~4 bytes/token) with ~25% headroom, and
-// staying in BYTES rather than characters keeps multibyte prompts from reading
-// artificially cheap. The seller's residual exposure when an estimate lands
-// low is bounded: actual usage is metered from the upstream response after the
-// serve, and the output cap is computed from whatever budget the input
-// estimate left, so an under-estimate eats into output headroom rather than
-// running unpriced.
+// Legacy buyer estimate. It is not an upper bound and must never authorize
+// inference: digit-dense prompts can consume more than three times this count.
 export const MESSAGE_OVERHEAD_TOKENS = 4;
 export const BYTES_PER_TOKEN_EST = 3.2;
 export function estimateInputTokens(messages) {
@@ -193,33 +177,37 @@ export function estimateInputTokens(messages) {
   return envelope + Math.ceil(bytes / BYTES_PER_TOKEN_EST);
 }
 
-// Bound a serve against the paid budget in BOTH legs (#495/#460). The relay used
-// to cap only OUTPUT, so a dust draw + a huge prompt got its output capped but the
-// whole prompt forwarded, making the seller eat unbounded upstream INPUT compute.
-// Estimate the input cost and REFUSE before any upstream call if it alone meets or
-// exceeds the payment; otherwise cap output over the budget LEFT after input. inPrice
-// and outPrice are USD per MTok. The estimate gates the refuse ONLY; real billing
-// still meters the upstream's reported token counts, so this never over-charges.
-// #654: DEFAULT_MAX_OUTPUT_TOKENS is a generous sanity ceiling, not a money guard
-// (the paid budget below already bounds output, and billing meters real usage). The
-// old 4096 was low enough to cap honest large-output requests below what the buyer
-// funded, so they overpaid. A relay operator can raise or lower it per their upstream
-// (see createServeCore's maxOutputTokens); this default just keeps a no-max_tokens
-// request on a big budget from triggering one runaway generation.
+// Reserve the counted input before output. Prices are atomic USD per million
+// tokens; keeping that denominator until division avoids rounding a fractional
+// input charge away or spending one atomic unit twice. Billing still uses usage.
 export const DEFAULT_MAX_OUTPUT_TOKENS = 32768;
-export function boundServe({ messages, budgetUsd, inPrice, outPrice, reqMax, contextCeil = DEFAULT_MAX_OUTPUT_TOKENS }) {
-  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;
+export const DEFAULT_MAX_INPUT_TOKENS = 131072;
+function withinInputLimit(inputTokens, inputCeil) {
+  if (!Number.isSafeInteger(inputTokens) || inputTokens < 0) throw new TypeError('input token count must be a nonnegative safe integer');
+  if (!Number.isSafeInteger(inputCeil) || inputCeil <= 0) throw new TypeError('input token ceiling must be a positive safe integer');
+  return inputTokens <= inputCeil;
+}
+const offerPriceAtomic = value => BigInt(Math.ceil(Number(value) * 1e6));
+
+export function boundServe({ inputTokens, budgetUsdAtomic, inPriceAtomic, outPriceAtomic, reqMax, inputCeil = DEFAULT_MAX_INPUT_TOKENS, contextCeil = DEFAULT_MAX_OUTPUT_TOKENS }) {
+  const inputAllowed = withinInputLimit(inputTokens, inputCeil);
+  if (!Number.isSafeInteger(contextCeil) || contextCeil <= 0) throw new TypeError('output token ceiling must be a positive safe integer');
+  const budget = BigInt(budgetUsdAtomic);
+  const inputPrice = BigInt(inPriceAtomic);
+  const outputPrice = BigInt(outPriceAtomic);
+  if (budget < 0n || inputPrice < 0n || outputPrice < 0n) throw new RangeError('token budget and prices must be nonnegative');
+  const inputCost = BigInt(inputTokens) * inputPrice;
+  const details = { inputTokens, inputCostUsd: Number(inputCost) / 1e12 };
+  if (!inputAllowed) return { refuse: true, reason: 'input_limit', ...details };
+  const outputBudget = budget * 1_000_000n - inputCost;
+  if (outputBudget <= 0n) return { refuse: true, reason: 'input', ...details };
+  if (outputPrice === 0n) return { refuse: true, reason: 'output_price', ...details };
   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 };
+  const fundedOutput = outputBudget / outputPrice;
+  if (fundedOutput < BigInt(maxTok)) maxTok = Number(fundedOutput);
+  if (maxTok < 1) return { refuse: true, reason: 'output', ...details };
+  return { refuse: false, maxTok, ...details };
 }
 
 // The core factory. `verifier` is an mtok-verify createOnchainVerifier instance (or anything
@@ -235,13 +223,41 @@ export function createServeCore({
   offerId, sellerAgentId, sellerWallet,
   dripContractAddress, feeRecipient, feeBps,
   screenPayer,
+  // A retired payment domain may honor verified receipts without admitting
+  // quotes or another inference attempt for an unrecorded payment.
+  replayOnly = false,
+  // The host counts its actual sanitized provider input. Missing or failed
+  // accounting refuses a fresh claim; saved completions do not need recounting.
+  countInputTokens,
+  maxInputTokens = DEFAULT_MAX_INPUT_TOKENS,
   // #654: the output-token sanity ceiling for boundServe. The PAID budget already
   // bounds output (and metering is on real usage), so this is a defensive cap on a
   // single generation, not a money guard. It is a per-relay knob: the reference host
   // passes MTOK_MAX_OUTPUT_TOKENS / a config value; operators serving large-context
   // models raise it. Falls back to boundServe's own generous default when unset.
-  maxOutputTokens,
+  maxOutputTokens = DEFAULT_MAX_OUTPUT_TOKENS,
 }) {
+  const quote = async (request) => {
+    if (replayOnly) return { status: 503, body: { error: 'redemption_unavailable', detail: 'this relay only replays saved completions' } };
+    const checked = validateRequest(request, model);
+    if (checked.error) return { status: 400, body: { error: 'bad_request', detail: checked.error } };
+    try {
+      const inputTokens = await countInputTokens(checked.safeRequest);
+      if (!withinInputLimit(inputTokens, maxInputTokens)) return { status: 413, body: { error: 'input_too_large', detail: `input (${inputTokens} tokens) exceeds this relay's input-token limit` } };
+      if (!Number.isSafeInteger(maxOutputTokens) || maxOutputTokens <= 0) throw new TypeError('output token ceiling must be a positive safe integer');
+      const inputPrice = offerPriceAtomic(inPrice);
+      const outputPrice = offerPriceAtomic(outPrice);
+      if (inputPrice < 0n || outputPrice <= 0n) throw new RangeError('invalid offer prices');
+      return { status: 200, body: {
+        model, offerId, inputTokens, maxInputTokens, maxOutputTokens,
+        inputPricePerMTokAtomic: inputPrice.toString(),
+        outputPricePerMTokAtomic: outputPrice.toString(),
+      } };
+    } catch (e) {
+      return { status: 503, body: { error: 'input_accounting_unavailable', detail: e.message } };
+    }
+  };
+
   const serve = async (body) => {
     const currentFeeRecipient = typeof feeRecipient === 'function' ? feeRecipient() : feeRecipient;
     const { bookingId, n, buyerId, request, requestNonce, drawPaidTxHash } = body;
@@ -341,6 +357,9 @@ export function createServeCore({
     if (redemptionState === 'pending') {
       return { status: 409, body: { error: 'draw_pending', detail: 'this paid draw was already claimed; refusing to run upstream again', _bookingId: bookingId } };
     }
+    if (replayOnly) {
+      return { status: 503, body: { error: 'redemption_unavailable', detail: 'this payment has no saved completion; retry this same paid draw after reconciliation', _bookingId: bookingId } };
+    }
     // Completed/pending claims already crossed the fee gate and cannot spend
     // again. New claims use the policy at the verified payment time.
     let currentFeeBps;
@@ -360,21 +379,32 @@ export function createServeCore({
       return { status: 402, body: { error: 'balance_exhausted', detail: `remainingUsd=${remainingUsd}`, _bookingId: bookingId, remainingUsd } };
     }
 
-    // Bound BOTH legs against what the draw paid for (#495/#460). The relay used
-    // to cap only OUTPUT, so a dust draw + a huge prompt got its output capped but
-    // the whole prompt forwarded => the seller ate unbounded upstream INPUT compute.
-    // Now: REFUSE before any upstream call if the estimated input cost alone meets
-    // the payment, else cap output over the budget LEFT after input. Input is priced
-    // at the higher of our offer price and the buyer's committed event price, so the
-    // buyer can't zero the input leg to sneak a big prompt.
-    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, ...(Number(maxOutputTokens) > 0 ? { contextCeil: Math.floor(Number(maxOutputTokens)) } : {}) });
+    let bound;
+    try {
+      const inputTokens = await countInputTokens(checked.safeRequest);
+      const price = (offered, committed) => {
+        const local = offerPriceAtomic(offered);
+        const paid = BigInt(committed);
+        return local > paid ? local : paid;
+      };
+      bound = boundServe({
+        inputTokens,
+        budgetUsdAtomic: paidEvent.sellerUsdAtomic,
+        inPriceAtomic: price(inPrice, paidEvent.inputPricePerMTokAtomic),
+        outPriceAtomic: price(outPrice, paidEvent.outputPricePerMTokAtomic),
+        reqMax: checked.safeRequest.max_tokens,
+        inputCeil: maxInputTokens,
+        contextCeil: maxOutputTokens,
+      });
+    } catch (e) {
+      return { status: 503, body: { error: 'input_accounting_unavailable', detail: e.message, _bookingId: bookingId } };
+    }
     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 error = bound.reason === 'input' || bound.reason === 'input_limit' ? 'input_too_large' : 'output_unfunded';
+      const detail = bound.reason === 'input_limit'
+        ? `input (${bound.inputTokens} tokens) exceeds this relay's input-token limit`
+        : `input (${bound.inputTokens} tokens, $${bound.inputCostUsd.toFixed(6)}) leaves no safely funded output in the paid amount ($${remainingUsd})`;
+      return { status: 402, body: { error, detail, _bookingId: bookingId, remainingUsd } };
     }
     const safeRequest = { ...checked.safeRequest, model, max_tokens: bound.maxTok };
 
@@ -428,5 +458,5 @@ export function createServeCore({
     return { status: 200, body: payload };
   };
 
-  return { serve };
+  return { serve, quote };
 }