@bsvkey/inference-mcp 1.1.1 → 1.2.0

package/README.md

@@ -12,6 +12,18 @@ Two ways to pay: a **prepaid channel** (`infer`, fund once, draw down per token)
 with its own key). `x402_infer` needs a funded WIF (`wif` arg or `BSVKEY_WIF`) and the
 optional `@bsvkey/x402-bsv-client` + `@bsv/sdk` packages (installed with this one).
 
+**Verifiable metering.** Each `infer` call returns a signed usage receipt, and the
+tool auto-verifies it offline (with the optional packages installed): the result
+includes `receiptVerified` and `meterVerified` (`true`, `false` + `receiptCheck`,
+or `null` if the verifier isn't installed). It recovers the broker key (pinned
+from `GET /v1/receipt-key`); checks channel binding, a monotonic sequence (no
+replay/gap), and running totals within the funded amount; **recomputes the charge**
+from the published rate (you can never be overcharged); and **recomputes the token
+count from the exact bytes** of your system/prompt and the completion, under the
+pinned `bsvkey-meter/1` tokenizer. So the channel payment is on-chain and both the
+meter and the charge are auditable, without trusting the broker's word. Spec:
+https://inference.bsvkey.com/usage-receipts.md
+
 ## Quick start
 1. **Fund a channel once** at https://inference.bsvkey.com (BRC-100 wallet, or
    load a key in-page). Copy the key it returns: `channelId:channelSecret`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsvkey/inference-mcp",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "MCP server: buy Claude & Grok inference metered per token, settled in BSV, through the hosted inference.bsvkey.com gateway. Channels or per-call x402.",
   "mcpName": "io.github.BSVKey/inference-mcp",
   "type": "module",
@@ -9,7 +9,7 @@
   "engines": { "node": ">=18" },
   "files": ["server.js", "SKILL.md", "README.md", "LICENSE"],
   "optionalDependencies": {
-    "@bsvkey/x402-bsv-client": "^0.2.0",
+    "@bsvkey/x402-bsv-client": "^0.4.0",
     "@bsv/sdk": "^2"
   },
   "keywords": ["mcp", "model-context-protocol", "bsv", "inference", "pay-per-token", "http-402", "x402", "claude", "grok", "micropayments", "agents"],

package/server.js

@@ -45,6 +45,56 @@ async function http(method, path, { headers = {}, body } = {}) {
   return { ok: res.ok, status: res.status, json };
 }
 
+// Best-effort, offline verification of the broker's signed usage receipt. Local
+// only (a secp256k1 recovery + sha256): no payment, no network beyond a one-time
+// key fetch, no effect on the x402 path. Gated on the optional
+// @bsvkey/x402-bsv-client verifier so the server keeps zero REQUIRED deps: if it
+// isn't installed we return verified:null (skipped), never an error.
+let _verifier; // module | false | undefined
+let _brokerKey; // hex | null | undefined
+const _seen = new Map(); // channelId -> { seq, cumSats, cumTokens }  (this session)
+async function loadVerifier() {
+  if (_verifier !== undefined) return _verifier;
+  try { _verifier = await import('@bsvkey/x402-bsv-client/usage-receipt'); } catch { _verifier = false; }
+  return _verifier;
+}
+async function brokerReceiptKey() {
+  if (_brokerKey !== undefined) return _brokerKey;
+  try { const r = await http('GET', '/receipt-key'); _brokerKey = r.ok ? (r.json.receiptPubKey || null) : null; } catch { _brokerKey = null; }
+  return _brokerKey;
+}
+async function verifyUsageReceipt(receipt, bytes = {}) {
+  if (!receipt) return { verified: null, reason: 'no receipt returned' };
+  const V = await loadVerifier();
+  if (!V) return { verified: null, reason: 'verifier not installed (npm i @bsvkey/x402-bsv-client)' };
+  const one = await V.verifyReceipt(receipt);
+  if (!one.ok) return { verified: false, reason: one.reason };
+  const pinned = await brokerReceiptKey();
+  if (pinned && one.signer !== pinned) return { verified: false, reason: 'signer_not_pinned_broker_key' };
+  // The charge recomputes from the receipt's own rates (overcharge is a dispute).
+  if (typeof V.verifyCharge === 'function') {
+    const c = V.verifyCharge(receipt);
+    if (!c.ok) return { verified: false, reason: `charge:${c.reason}` };
+  }
+  // The meter: recompute token counts + byte digests from the exact bytes we hold.
+  let meterVerified = null;
+  if (typeof V.verifyMeter === 'function' && (bytes.prompt !== undefined || bytes.completion !== undefined)) {
+    const mv = V.verifyMeter(receipt, bytes);
+    if (!mv.ok) return { verified: false, reason: `meter:${mv.reason}`, meterVerified: false };
+    meterVerified = true;
+  }
+  if (receipt.cumSats > receipt.fundedSats) return { verified: false, reason: 'cumSats_exceeds_funded' };
+  const prev = _seen.get(receipt.channelId);
+  if (prev) {
+    // Continuity across calls this session actually observed.
+    if (receipt.seq !== prev.seq + 1) return { verified: false, reason: receipt.seq === prev.seq ? 'replayed_seq' : (receipt.seq < prev.seq ? 'seq_regressed' : 'seq_gap') };
+    if (receipt.cumSats !== prev.cumSats + receipt.sats) return { verified: false, reason: 'cumSats_does_not_reconcile' };
+    if (receipt.cumTokens !== prev.cumTokens + receipt.inputTokens + receipt.outputTokens) return { verified: false, reason: 'cumTokens_does_not_reconcile' };
+  }
+  _seen.set(receipt.channelId, { seq: receipt.seq, cumSats: receipt.cumSats, cumTokens: receipt.cumTokens });
+  return { verified: true, meterVerified, ...(prev ? {} : { note: 'baseline: signature + funded-conservation checked; seq continuity verified from here' }) };
+}
+
 export const TOOLS = [
   {
     name: 'list_models',
@@ -141,13 +191,23 @@ async function callTool(name, args = {}) {
         throw new Error(typeof msg === 'string' ? msg : JSON.stringify(msg));
       }
       const x = r.json.x_bsv || {};
+      const completion = r.json.choices?.[0]?.message?.content ?? '';
+      const rc = await verifyUsageReceipt(x.usageReceipt, { system: args.system, prompt: String(args.prompt || ''), completion });
       return {
         model: r.json.model || args.model,
-        completion: r.json.choices?.[0]?.message?.content ?? '',
+        completion,
         charge: x.charge,
         routedTo: x.routedTo,
         balanceSatsAfter: x.balanceSatsAfter,
         truncated: x.truncated || false,
+        // Offline-verified signed usage receipt (see usage-receipt spec). null =
+        // not checked (verifier not installed); false w/ receiptCheck = a real
+        // mismatch, treat the meter as untrusted for this call. meterVerified is
+        // true when the token count was recomputed from the exact bytes.
+        receiptVerified: rc.verified,
+        meterVerified: rc.meterVerified,
+        ...(rc.reason ? { receiptCheck: rc.reason } : {}),
+        usageReceipt: x.usageReceipt,
       };
     }
     case 'channel_balance': {