mtok-bridge 0.3.4 → 0.4.0

package/README.md

@@ -41,10 +41,47 @@ tool, one layer on top.
 (and the workers-ai house seller) run: validate request => verify the on-chain DrawPaid
 (request-hash bound) => bound both legs against the payment => claim => upstream => complete,
 fail-closed. The redemption store is a pluggable interface (`{ state, get, claim, complete,
-retentionMs }`, each method sync or async: the core awaits every call), so a filesystem store and a Workers KV store drive the same code path. If you
+retentionMs }`, each method sync or async: the core awaits every call). The store must make
+claims atomic across every host serving that offer. Independent local files and eventually
+consistent KV read/write pairs do not provide that guarantee. If you
 are just serving a model for a key, you never need it; it is here so every mtok seller host
 shares one money path.
 
+`state(key, { claimKey })` and `get(key, { claimKey })` receive the canonical commitment
+identity even when `key` names a legacy record. `claim(key, markerKey, { paidAtMs })` receives
+the verifier's payment timestamp, so a store migrating old claims can refuse ambiguous
+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.
+
+The counted-input change is not ready to publish. The reference HTTP relay and SDK
+quote flow are integrated; the house seller's provider counters and rollout are still pending.
+
+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.4",
+  "version": "0.4.0",
   "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

@@ -8,7 +8,7 @@
 // payer-screen POLICY stay in the host.
 //
 // The redemption dependency is an INTERFACE the caller passes:
-//   { state(key), get(key), claim(key, markerKey), complete(key, payload), retentionMs }
+//   { state(key, { claimKey }), get(key, { claimKey }), claim(key, markerKey, { paidAtMs }), complete(key, payload), retentionMs }
 // state(key) returns 'pending' | 'complete' | null. claim(key, markerKey) returns false when the
 // draw is already claimed and THROWS when it cannot claim durably (the core then refuses before
 // upstream spend). complete(key, payload) throws when the payload cannot be persisted; the claim
@@ -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,37 @@ export function createServeCore({
   offerId, sellerAgentId, sellerWallet,
   dripContractAddress, feeRecipient, feeBps,
   screenPayer,
+  // 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) => {
+    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;
@@ -268,6 +280,7 @@ export function createServeCore({
     // Legacy redemption remains only to honor draws already paid by old SDKs.
     const cacheKey = `${requestHashScheme}:${bookingId}:${n}:${requestHash}`;
     const oldLegacyKey = hasRequestNonce ? null : `${bookingId}:${n}:${requestHash}`;
+    const redemptionContext = { claimKey: cacheKey };
 
     // Contract mode is the ONLY mode (#487): the legacy direct-transfer FUND
     // lane and its /api/bookings/:id balance read are gone. If the platform is
@@ -281,18 +294,18 @@ export function createServeCore({
     // The redemption interface may be sync (fs store) or async (a Workers KV
     // store): await normalizes both, and identity-awaits cost nothing under the
     // host's per-booking lock.
-    let redemptionState = await redemption.state(storedKey);
+    let redemptionState = await redemption.state(storedKey, redemptionContext);
     // Preserve an upgrade's pre-scheme redemption log; missing this alias
     // would let a legacy paid draw run upstream again after relay upgrade.
     if (!redemptionState && oldLegacyKey) {
-      const oldLegacyState = await redemption.state(oldLegacyKey);
+      const oldLegacyState = await redemption.state(oldLegacyKey, redemptionContext);
       if (oldLegacyState) {
         storedKey = oldLegacyKey;
         redemptionState = oldLegacyState;
       } else {
         // Checking the legacy marker may have refreshed a prefixed record
         // appended by another upgraded process.
-        redemptionState = await redemption.state(cacheKey);
+        redemptionState = await redemption.state(cacheKey, redemptionContext);
       }
     }
     let paid;
@@ -332,7 +345,11 @@ export function createServeCore({
         return { status: 403, body: { error: 'payer_denied', detail: 'payer screening failed: ' + e.message } };
       }
     }
-    if (redemptionState === 'complete') return { status: 200, body: await redemption.get(storedKey) };
+    if (redemptionState === 'complete') {
+      const payload = await redemption.get(storedKey, redemptionContext);
+      if (payload == null) return { status: 503, body: { error: 'redemption_unavailable', detail: 'saved completion is no longer readable; retry this same paid draw', _bookingId: bookingId } };
+      return { status: 200, body: payload };
+    }
     if (redemptionState === 'pending') {
       return { status: 409, body: { error: 'draw_pending', detail: 'this paid draw was already claimed; refusing to run upstream again', _bookingId: bookingId } };
     }
@@ -355,28 +372,39 @@ 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 };
 
     try {
       // Legacy uses its old unprefixed identity only for the atomic marker so
       // parallel upgraded stores and an existing log converge on one claim.
-      if (!(await redemption.claim(cacheKey, oldLegacyKey ?? cacheKey))) {
+      if (!(await redemption.claim(cacheKey, oldLegacyKey ?? cacheKey, { paidAtMs: paid.paidAtMs }))) {
         return { status: 409, body: { error: 'draw_pending', detail: 'this paid draw was already claimed; refusing to run upstream again', _bookingId: bookingId } };
       }
     } catch (e) {
@@ -423,5 +451,5 @@ export function createServeCore({
     return { status: 200, body: payload };
   };
 
-  return { serve };
+  return { serve, quote };
 }