@bsvkey/x402-bsv-client 0.3.0 → 0.4.0

package/README.md

@@ -88,12 +88,26 @@ const audit = await verifyReceiptChain(receipts, {
 `verifyReceiptChain` checks, across the whole chain, that: each signature
 recovers to the pinned broker key, every receipt is for your channel, the
 sequence has no gap or replay, the running totals reconcile
-(`cumSats`/`cumTokens`), and spending never exceeds the funded amount. There is
-also a single-receipt `verifyReceipt(receipt)` → `{ ok, signer }`.
+(`cumSats`/`cumTokens`), spending never exceeds the funded amount, and each
+**charge** recomputes from the published formula (you can be charged less, never
+more). Single-receipt helpers: `verifyReceipt(receipt)` → `{ ok, signer }`,
+`verifyCharge(receipt)`, and `verifyMeter(receipt, { system, prompt, completion })`.
 
-**What this proves:** the broker signed these exact numbers (non-repudiable),
-none were double-counted, and the totals add up and stay within what you funded.
-**What it does not prove:** that the token counts equal the model's true usage.
-That is still the broker's meter. Spec: https://inference.bsvkey.com/usage-receipts.md
+### Verify the meter (the token count itself)
+
+The v2 receipt binds the exact bytes and is metered by a pinned, deterministic
+tokenizer, so you recompute the token count from what you sent and received:
+
+```js
+import { verifyMeter } from '@bsvkey/x402-bsv-client/usage-receipt';
+const m = verifyMeter(receipt, { system, prompt, completion }); // { ok } / { ok:false, reason }
+```
+
+**What this proves:** the broker signed these exact numbers (non-repudiable), the
+token count is the published function of the exact bytes you exchanged, the charge
+is the published function of those tokens, none were double-counted, and the
+totals stay within what you funded. **What it does not prove:** that
+`bsvkey-meter/1` equals a model provider's internal token count (it is BSVKey's
+own published unit). Spec: https://inference.bsvkey.com/usage-receipts.md
 
 MIT.

package/package.json

@@ -1,18 +1,18 @@
-{
-  "name": "@bsvkey/x402-bsv-client",
-  "version": "0.3.0",
-  "description": "Pay an x402 HTTP 402 in BSV — the missing bsv-p2pkh payment builder for x402 agents. Also verifies BSVKey inference usage receipts.",
-  "type": "module",
-  "main": "index.js",
-  "exports": { ".": "./index.js", "./usage-receipt": "./usage-receipt.js" },
-  "files": ["index.js", "usage-receipt.js", "example.js", "README.md", "LICENSE"],
-  "scripts": { "test": "node --test" },
-  "author": "Embryo Space Inc. (DBA BSVKey)",
-  "homepage": "https://inference.bsvkey.com/v1/x402",
-  "engines": { "node": ">=18" },
-  "peerDependencies": { "@bsv/sdk": "^2" },
-  "devDependencies": { "@bsv/sdk": "^2.4.2" },
-  "keywords": ["x402", "bsv", "micropayments", "ai-agents", "402", "payments", "http-402", "usage-receipt", "verifiable"],
-  "license": "MIT",
-  "repository": { "type": "git", "url": "https://github.com/BSVKey/x402-bsv-client" }
-}
+{
+  "name": "@bsvkey/x402-bsv-client",
+  "version": "0.4.0",
+  "description": "Pay an x402 HTTP 402 in BSV — the missing bsv-p2pkh payment builder for x402 agents. Also verifies BSVKey inference usage receipts.",
+  "type": "module",
+  "main": "index.js",
+  "exports": { ".": "./index.js", "./usage-receipt": "./usage-receipt.js" },
+  "files": ["index.js", "usage-receipt.js", "example.js", "README.md", "LICENSE"],
+  "scripts": { "test": "node --test" },
+  "author": "Embryo Space Inc. (DBA BSVKey)",
+  "homepage": "https://inference.bsvkey.com/v1/x402",
+  "engines": { "node": ">=18" },
+  "peerDependencies": { "@bsv/sdk": "^2" },
+  "devDependencies": { "@bsv/sdk": "^2.4.2" },
+  "keywords": ["x402", "bsv", "micropayments", "ai-agents", "402", "payments", "http-402", "usage-receipt", "verifiable"],
+  "license": "MIT",
+  "repository": { "type": "git", "url": "https://github.com/BSVKey/x402-bsv-client" }
+}

package/usage-receipt.js

@@ -1,22 +1,21 @@
-// Verify BSVKey inference usage receipts, client-side, offline.
+// Verify BSVKey inference usage receipts (v2), client-side, offline.
 //
-// The BSVKey inference broker returns a signed `usageReceipt` on every settled
-// prepaid-channel call. This module lets an agent audit the broker's meter
-// WITHOUT trusting its word and WITHOUT a round-trip: it recovers the signer
-// from the signature, and checks channel binding, a monotonic sequence (no
-// replay/gap), and running totals bounded by the funded amount.
+// The broker returns a signed `usageReceipt` on every settled prepaid-channel
+// call. This verifies it with no round-trip and no trust in the broker's word:
+//   - verifyReceipt      authorship + integrity (claimId + BSM signature recovery)
+//   - verifyCharge       the sats are the published formula over the receipt's
+//                        own token counts + pinned rates (overcharge is a dispute;
+//                        undercharge, e.g. a channel cap, is allowed)
+//   - verifyMeter        the token counts + byte digests recompute from the EXACT
+//                        system/prompt/completion you hold, under the pinned
+//                        tokenizer (bsvkey-meter/1). This is the 'last inch': the
+//                        count is a deterministic function of the bytes exchanged.
+//   - verifyReceiptChain the whole channel: pinned broker key, channel binding,
+//                        monotonic seq (no gap/replay), reconciling running totals
+//                        within the funded amount, and each charge.
 //
-// Pin the broker's key once from GET /v1/receipt-key, then pass it as
-// `expectedSigner` to verifyReceiptChain. Spec:
-// https://inference.bsvkey.com/usage-receipts.md
-//
-// Peer dependency: @bsv/sdk (v2), the same one this package already needs to
-// build payments. `verifyReceipt` / `verifyReceiptChain` are async.
-//
-// What it proves: the broker signed these exact numbers (non-repudiable), none
-// were double-counted, and the totals reconcile and stay within what you funded.
-// What it does NOT prove: that the token counts equal the model's true usage.
-// That last inch is still the broker's meter.
+// Pin the broker key once from GET /v1/receipt-key. Peer dep: @bsv/sdk (v2).
+// Spec: https://inference.bsvkey.com/usage-receipts.md
 
 import { createHash } from 'node:crypto';
 
@@ -27,15 +26,19 @@ async function sdk() {
   return _sdk;
 }
 
-export const RECEIPT_SCHEMA = 'bsvkey.usage-receipt/1';
+export const RECEIPT_SCHEMA = 'bsvkey.usage-receipt/2';
+export const METER_ID = 'bsvkey-meter/1';
 
 const CONTENT_FIELDS = [
-  'v', 'channelId', 'seq', 'model',
-  'inputTokens', 'outputTokens', 'sats',
-  'cumTokens', 'cumSats', 'fundedSats', 'timestamp',
+  'v', 'channelId', 'seq', 'model', 'meter', 'pricebookId',
+  'inputTokens', 'outputTokens', 'inputDigest', 'outputDigest',
+  'rateInPer1k', 'rateOutPer1k', 'webSearchSats', 'discountPct', 'minChargeSats',
+  'sats', 'cumTokens', 'cumSats', 'fundedSats', 'timestamp',
 ];
 const ALLOWED_KEYS = new Set([...CONTENT_FIELDS, 'claimId', 'signature', 'brokerPubKey']);
 
+const sha256hex = (s) => createHash('sha256').update(String(s), 'utf8').digest('hex');
+
 function sortKeysDeep(value) {
   if (Array.isArray(value)) return value.map(sortKeysDeep);
   if (value !== null && typeof value === 'object') {
@@ -45,37 +48,46 @@ function sortKeysDeep(value) {
   }
   return value;
 }
-export function canonicalize(value) {
-  return JSON.stringify(sortKeysDeep(value));
-}
+export function canonicalize(value) { return JSON.stringify(sortKeysDeep(value)); }
 function pickContent(obj) {
   const c = {};
   for (const k of CONTENT_FIELDS) if (obj[k] !== undefined) c[k] = obj[k];
   return c;
 }
 export function computeClaimId(obj) {
-  const hash = createHash('sha256').update(canonicalize(pickContent(obj)), 'utf8').digest('hex');
-  return `0x${hash}`;
+  return `0x${createHash('sha256').update(canonicalize(pickContent(obj)), 'utf8').digest('hex')}`;
+}
+
+// --- the pinned meter (bsvkey-meter/1): byte-identical to the broker's -------
+export function meterInputText(system, prompt) {
+  return (system ? String(system) + '\n\n' : '') + String(prompt || '');
+}
+export function estimateTokens(text) {
+  if (!text) return 0;
+  const byChars = Math.ceil(text.length / 4);
+  const byWords = Math.ceil(text.trim().split(/\s+/).filter(Boolean).length * 1.3);
+  return Math.max(byChars, byWords, 1);
+}
+
+// --- the frozen, integer-only charge formula (identical to the broker's) ------
+export function computeChargeSats({ inputTokens, outputTokens, rateInPer1k, rateOutPer1k, webSearchSats = 0, discountPct = 0, minChargeSats }) {
+  const tokenSats = Math.ceil((inputTokens * rateInPer1k + outputTokens * rateOutPer1k) / 1000);
+  const gross = tokenSats + webSearchSats;
+  const afterDiscount = Math.ceil((gross * (100 - discountPct)) / 100);
+  return Math.max(minChargeSats, afterDiscount);
 }
 
-// Verify ONE receipt is internally consistent and recover its signer.
-// Returns { ok:true, signer } (signer = recovered pubkey hex) or { ok:false, reason }.
+// Authorship + integrity: strict shape, claimId content-address, and recover the
+// signer from the compact BSM signature. { ok:true, signer } / { ok:false, reason }.
 export async function verifyReceipt(receipt) {
   if (receipt === null || typeof receipt !== 'object') return { ok: false, reason: 'not_an_object' };
-  for (const k of Object.keys(receipt)) {
-    if (!ALLOWED_KEYS.has(k)) return { ok: false, reason: `unknown_field:${k}` };
-  }
+  for (const k of Object.keys(receipt)) if (!ALLOWED_KEYS.has(k)) return { ok: false, reason: `unknown_field:${k}` };
   if (receipt.v !== RECEIPT_SCHEMA) return { ok: false, reason: `bad_schema:${receipt.v}` };
-  const expected = computeClaimId(receipt);
-  if (expected.toLowerCase() !== String(receipt.claimId).toLowerCase()) {
-    return { ok: false, reason: 'claimId_mismatch' };
-  }
+  if (computeClaimId(receipt).toLowerCase() !== String(receipt.claimId).toLowerCase()) return { ok: false, reason: 'claimId_mismatch' };
   const { BSM, Utils, Signature, BigNumber } = await sdk();
   let raw;
   try { raw = Utils.toArray(receipt.signature, 'base64'); } catch (e) { return { ok: false, reason: `bad_signature_encoding: ${e.message}` }; }
-  if (!Array.isArray(raw) || raw.length !== 65 || raw[0] < 27 || raw[0] >= 35) {
-    return { ok: false, reason: 'bad_signature_encoding: not a 65-byte BSM compact signature' };
-  }
+  if (!Array.isArray(raw) || raw.length !== 65 || raw[0] < 27 || raw[0] >= 35) return { ok: false, reason: 'bad_signature_encoding: not a 65-byte BSM compact signature' };
   const recoveryId = (raw[0] - 27) & 3;
   const msg = Utils.toArray(receipt.claimId, 'utf8');
   let recovered;
@@ -83,21 +95,39 @@ export async function verifyReceipt(receipt) {
     const sig = Signature.fromCompact(receipt.signature, 'base64');
     recovered = sig.RecoverPublicKey(recoveryId, new BigNumber(BSM.magicHash(msg)));
     if (!BSM.verify(msg, sig, recovered)) return { ok: false, reason: 'signature_invalid' };
-  } catch (e) {
-    return { ok: false, reason: `signature_recovery_failed: ${e.message}` };
-  }
+  } catch (e) { return { ok: false, reason: `signature_recovery_failed: ${e.message}` }; }
   const signer = recovered.toString();
-  if (receipt.brokerPubKey !== undefined && receipt.brokerPubKey !== signer) {
-    return { ok: false, reason: 'brokerPubKey_does_not_match_recovered' };
-  }
+  if (receipt.brokerPubKey !== undefined && receipt.brokerPubKey !== signer) return { ok: false, reason: 'brokerPubKey_does_not_match_recovered' };
   return { ok: true, signer };
 }
 
-// Verify a whole channel's receipt chain offline (the agent audit).
-//   opts.expectedSigner : the broker key pinned from GET /v1/receipt-key
-//   opts.channelId      : your channel (all receipts must match)
-//   opts.fundedSats     : the channel's on-chain funded amount (conservation cap)
-// Returns { ok, count, cumSats, cumTokens } or { ok:false, reason, seq }.
+// The charge is the published formula over the receipt's own fields. You can
+// never be charged MORE than that; being charged less is allowed (channel cap).
+export function verifyCharge(receipt) {
+  const expected = computeChargeSats(receipt);
+  if (receipt.sats > expected) return { ok: false, reason: 'overcharge', expected, got: receipt.sats };
+  if (receipt.sats < receipt.minChargeSats) return { ok: false, reason: 'below_min_charge', expected: receipt.minChargeSats, got: receipt.sats };
+  return receipt.sats === expected ? { ok: true } : { ok: true, note: 'undercharged' };
+}
+
+// The meter: recompute token counts + byte digests from the EXACT bytes you hold.
+export function verifyMeter(receipt, { system, prompt, completion } = {}) {
+  if (receipt.meter !== METER_ID) return { ok: false, reason: `unknown_meter:${receipt.meter}` };
+  const input = meterInputText(system, prompt);
+  const output = String(completion || '');
+  if (sha256hex(input) !== receipt.inputDigest) return { ok: false, reason: 'inputDigest_mismatch' };
+  if (sha256hex(output) !== receipt.outputDigest) return { ok: false, reason: 'outputDigest_mismatch' };
+  if (estimateTokens(input) !== receipt.inputTokens) return { ok: false, reason: 'inputTokens_mismatch' };
+  if (estimateTokens(output) !== receipt.outputTokens) return { ok: false, reason: 'outputTokens_mismatch' };
+  return { ok: true };
+}
+
+// Verify a whole channel's receipt chain offline.
+//   opts.expectedSigner : broker key pinned from GET /v1/receipt-key
+//   opts.channelId      : your channel
+//   opts.fundedSats     : the channel's on-chain funded amount
+// Also recomputes each charge. Returns { ok, count, cumSats, cumTokens } or
+// { ok:false, reason, seq }.
 export async function verifyReceiptChain(receipts, opts = {}) {
   const list = [...receipts].sort((a, b) => (a.seq || 0) - (b.seq || 0));
   let prevSeq = 0, prevCumSats = 0, prevCumTokens = 0;
@@ -105,6 +135,8 @@ export async function verifyReceiptChain(receipts, opts = {}) {
     const v = await verifyReceipt(r);
     if (!v.ok) return { ok: false, reason: v.reason, seq: r.seq };
     if (opts.expectedSigner && v.signer !== opts.expectedSigner) return { ok: false, reason: 'signer_not_pinned_broker_key', seq: r.seq };
+    const c = verifyCharge(r);
+    if (!c.ok) return { ok: false, reason: c.reason, seq: r.seq };
     if (opts.channelId && r.channelId !== opts.channelId) return { ok: false, reason: 'wrong_channel', seq: r.seq };
     if (r.seq !== prevSeq + 1) return { ok: false, reason: prevSeq && r.seq === prevSeq ? 'replayed_seq' : 'seq_gap', seq: r.seq };
     if (r.cumSats !== prevCumSats + r.sats) return { ok: false, reason: 'cumSats_does_not_reconcile', seq: r.seq };