metered-protocol 1.0.0

package/dist/src/encoding.js

@@ -0,0 +1,187 @@
+/**
+ * Canonical encoding, digests and signatures for Metered.
+ *
+ * Vendored deliberately rather than imported. The golden vector was previously generated by
+ * kaspa-depin's protocol package, which meant CI could not regenerate it and the specification's
+ * most foundational claims were unverifiable from this repository. Two bugs had already survived
+ * that gap; a third was found while writing this file.
+ *
+ * ONE HASH, EVERYWHERE. The borrowed code used BLAKE2b for message digests and BLAKE3 for content
+ * addressing, and the specification said "digests are blake3" about both. An implementer following
+ * the specification would have produced different `prevState` values and a different checkpoint
+ * digest -- total incompatibility, from one sentence. Rather than document the accident, this
+ * settles it: BLAKE3-256 for everything. The specification is now true.
+ */
+import { blake3 } from '@noble/hashes/blake3';
+import { schnorr } from '@noble/curves/secp256k1';
+import { bytesToHex, hexToBytes, utf8ToBytes } from '@noble/hashes/utils';
+/**
+ * RFC 8785 (JCS) canonical JSON.
+ *
+ * Keys sort by UTF-16 code unit, which is what JCS mandates and what JavaScript's default sort
+ * does. This is NOT Unicode code-point order -- they diverge above the BMP, where surrogate pairs
+ * sort below U+E000-FFFF. The specification said code point until a check caught it.
+ */
+export function canonicalize(value) {
+    if (value === null || typeof value === 'boolean')
+        return JSON.stringify(value);
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new Error(`canonicalize: non-finite number ${value}`);
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalize).join(',')}]`;
+    if (typeof value === 'object')
+        return canonicalizeObject(value);
+    throw new Error(`canonicalize: unsupported value of type ${typeof value}`);
+}
+function canonicalizeObject(value) {
+    const keys = Object.keys(value)
+        .filter((k) => value[k] !== undefined)
+        .sort(); // default sort is UTF-16 code unit order, which is what JCS requires
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalize(value[k])}`).join(',')}}`;
+}
+/** BLAKE3-256 of raw bytes or a UTF-8 string, hex. */
+/**
+ * Text as the bytes that represent it.
+ *
+ * Delivered content is bytes (SPEC.md 6), so anything that starts life as a string has to become
+ * bytes at some boundary. This is that boundary, named once, so no caller invents its own.
+ */
+export const utf8 = (text) => utf8ToBytes(text);
+export function blake3Hex(input) {
+    const bytes = typeof input === 'string' ? utf8ToBytes(input) : input;
+    return bytesToHex(blake3(bytes, { dkLen: 32 }));
+}
+/**
+ * SPEC.md 3.1's `partiesCommitment`: blake3 over the two public keys, as BYTES.
+ *
+ * THE ONE DEFINITION, because there were two and they disagreed. "blake3(buyerPubkey || providerPubkey)"
+ * never said whether the concatenation joins the 64 raw key bytes or the 128 characters of hex
+ * that represent them, and those produce different digests. The live provider hashed the bytes;
+ * the conformance generator hashed the hex text. Both were correct for as long as nothing
+ * compared them -- and consensus settles the argument, because the covenant recomputes
+ * blake3(byte[](buyer) + byte[](provider)) and will not pay out against anything else.
+ *
+ * So the bytes reading is normative, and this is the only place it is computed.
+ */
+export function partiesCommitment(buyerPubkey, providerPubkey) {
+    return blake3Hex(new Uint8Array([...hexToBytes(buyerPubkey), ...hexToBytes(providerPubkey)]));
+}
+/** BLAKE3-256 of the canonical form of a value, hex. The only digest this protocol uses. */
+export function digestHex(value) {
+    return blake3Hex(canonicalize(value));
+}
+export function publicKeyHex(privateKeyHex) {
+    return bytesToHex(schnorr.getPublicKey(hexToBytes(privateKeyHex)));
+}
+/**
+ * Sign a message. The signature covers the canonical form with the signature field ABSENT --
+ * not present-and-empty, which is a different byte string and a classic source of divergence.
+ */
+export function sign(message, privateKeyHex, field = 'sig') {
+    const payload = withoutField(message, field);
+    return bytesToHex(schnorr.sign(utf8ToBytes(canonicalize(payload)), hexToBytes(privateKeyHex)));
+}
+export function verify(message, publicKeyHexStr, field = 'sig') {
+    const sig = message[field];
+    if (typeof sig !== 'string')
+        return false;
+    try {
+        const payload = withoutField(message, field);
+        return schnorr.verify(hexToBytes(sig), utf8ToBytes(canonicalize(payload)), hexToBytes(publicKeyHexStr));
+    }
+    catch {
+        return false;
+    }
+}
+/** Attach a signature under `field`, leaving the original untouched. */
+export function signEnvelope(message, privateKeyHex, field = 'sig') {
+    return { ...message, [field]: sign(message, privateKeyHex, field) };
+}
+/**
+ * Kaspa script number, 8 bytes: little-endian magnitude with the sign in the top bit of the last
+ * byte. This is what `OpNum2Bin(x, 8)` produces, and the covenant rebuilds the preimage with it,
+ * so any disagreement here is a signature the chain cannot verify.
+ */
+function num2bin8(value) {
+    if (!Number.isSafeInteger(value))
+        throw new Error(`num2bin8: ${value} is not a safe integer`);
+    const out = new Uint8Array(8);
+    let magnitude = Math.abs(value);
+    for (let i = 0; i < 8; i += 1) {
+        out[i] = magnitude % 256;
+        magnitude = Math.floor(magnitude / 256);
+    }
+    // The index is in range by construction (out is a fixed 8-byte array), but the typechecker
+    // cannot know that and noUncheckedIndexedAccess is worth keeping -- out-of-bounds is precisely
+    // the family of bug this project keeps finding. Written so the compiler can see it too.
+    if (value < 0)
+        out[7] = (out[7] ?? 0) | 0x80;
+    return out;
+}
+/**
+ * SPEC.md 3.4.1 -- the settlement preimage. 72 bytes, fixed width, fixed order, no delimiters:
+ * sessionId(16) + seq(8) + cumulativeUnits(8) + cumulativeSompi(8) + prevState(32).
+ *
+ * These 72 bytes are unique to a session only if the sessionId is. It is provider-chosen, so that
+ * is not a property of this function -- SPEC.md 3.1a puts the obligation on the buyer to reject a
+ * sessionId it has seen before, which src/offer.ts enforces.
+ *
+ * A State is the ONE signed object here whose signatures do not cover its canonical JSON. They
+ * cannot: the covenant must reconstruct what it verifies and a Kaspa script cannot build canonical
+ * JSON. Signing the JSON form yields a signature two peers accept and the chain cannot check --
+ * a session that can never settle.
+ *
+ * `prevState` is 32 zero bytes at seq 0, where the JSON carries null. A null has no byte form.
+ */
+export function settlementPreimage(state) {
+    const out = new Uint8Array(72);
+    out.set(hexToBytes(state.sessionId), 0);
+    out.set(num2bin8(state.seq), 16);
+    out.set(num2bin8(state.cumulativeUnits), 24);
+    out.set(num2bin8(state.cumulativeSompi), 32);
+    const prev = state.prevState;
+    if (prev)
+        out.set(hexToBytes(prev), 40);
+    return out;
+}
+/**
+ * The 32 bytes both parties actually sign: blake3 of the preimage. The covenant computes exactly
+ * this and hands it to `checkMsgSig`, which verifies a BIP340 signature over supplied data rather
+ * than over the spending transaction.
+ *
+ * Neither signature field appears in the preimage at all, so the two parties sign identical bytes
+ * and neither depends on the other having signed first. The old "canonical JSON with both fields
+ * absent" rule is gone; there is nothing left to omit.
+ */
+export function settlementDigest(state) {
+    return blake3(settlementPreimage(state), { dkLen: 32 });
+}
+/** Hex of the preimage. A string, so it can be compared, logged and pinned in a vector. */
+export function stateSigningPayload(state) {
+    return bytesToHex(settlementPreimage(state));
+}
+export function signState(state, privateKeyHex) {
+    return bytesToHex(schnorr.sign(settlementDigest(state), hexToBytes(privateKeyHex)));
+}
+export function verifyState(state, sigHex, publicKeyHexStr) {
+    try {
+        const digest = settlementDigest(state);
+        return schnorr.verify(hexToBytes(sigHex), digest, hexToBytes(publicKeyHexStr));
+    }
+    catch {
+        return false;
+    }
+}
+function withoutField(obj, field) {
+    const copy = {};
+    for (const [k, v] of Object.entries(obj))
+        if (k !== field)
+            copy[k] = v;
+    return copy;
+}
+//# sourceMappingURL=encoding.js.map

package/dist/src/encoding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.js","sourceRoot":"","sources":["../../src/encoding.ts"],"names":[],"mappings":"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"}

package/dist/src/history.d.ts

@@ -0,0 +1,33 @@
+/**
+ * SPEC.md §3.1a -- the buyer's record of which session identifiers it has already been offered.
+ *
+ * WHY THIS IS NOT A FIELD WIDTH. `sessionId` is provider-CHOSEN. Every threat its width appears
+ * to address -- accidental collision, an outsider guessing or grinding one -- is a threat the
+ * provider is not subject to, because it does not guess its own identifiers. It picks them, and
+ * picking a previous one costs nothing.
+ *
+ * A reused `sessionId` makes the §3.4.1 preimage of two different sessions identical, so the
+ * buyer's signature from the first is a valid signature for the second. That is threat X1 executed
+ * by the one party no width defends against, and no on-chain rule can see it either: the covenant
+ * is instantiated per session and cannot observe the other one. The buyer is the only party
+ * positioned to catch it, and only by remembering.
+ *
+ * Synchronous by design, for the same reason SignerStore is (§4.2): an async check invites a
+ * caller to forget the await, which silently turns a refusal into an acceptance.
+ */
+/** Durable storage for §3.1a. Keyed by provider: two providers may pick the same id honestly. */
+export interface SessionHistory {
+    seen(providerPubkey: string, sessionId: string): boolean;
+    record(providerPubkey: string, sessionId: string): void;
+}
+/**
+ * The default history: correct for the life of a process, and FORGETFUL ACROSS RESTART.
+ *
+ * SPEC.md §3.1a requires an implementation that keeps no history to say so, and this is that
+ * disclosure: a buyer using this is protected against a provider reusing an identifier during one
+ * run, and unprotected against one that waits for the buyer to restart. It is the default because
+ * a default of "no check at all" would make the rule an intention rather than a mechanism; a buyer
+ * that needs the real guarantee supplies a store that survives restart.
+ */
+export declare function memoryHistory(): SessionHistory;
+//# sourceMappingURL=history.d.ts.map

package/dist/src/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,iGAAiG;AACjG,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IACzD,MAAM,CAAC,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,IAAI,cAAc,CAU9C"}

package/dist/src/history.js

@@ -0,0 +1,38 @@
+/**
+ * SPEC.md §3.1a -- the buyer's record of which session identifiers it has already been offered.
+ *
+ * WHY THIS IS NOT A FIELD WIDTH. `sessionId` is provider-CHOSEN. Every threat its width appears
+ * to address -- accidental collision, an outsider guessing or grinding one -- is a threat the
+ * provider is not subject to, because it does not guess its own identifiers. It picks them, and
+ * picking a previous one costs nothing.
+ *
+ * A reused `sessionId` makes the §3.4.1 preimage of two different sessions identical, so the
+ * buyer's signature from the first is a valid signature for the second. That is threat X1 executed
+ * by the one party no width defends against, and no on-chain rule can see it either: the covenant
+ * is instantiated per session and cannot observe the other one. The buyer is the only party
+ * positioned to catch it, and only by remembering.
+ *
+ * Synchronous by design, for the same reason SignerStore is (§4.2): an async check invites a
+ * caller to forget the await, which silently turns a refusal into an acceptance.
+ */
+/**
+ * The default history: correct for the life of a process, and FORGETFUL ACROSS RESTART.
+ *
+ * SPEC.md §3.1a requires an implementation that keeps no history to say so, and this is that
+ * disclosure: a buyer using this is protected against a provider reusing an identifier during one
+ * run, and unprotected against one that waits for the buyer to restart. It is the default because
+ * a default of "no check at all" would make the rule an intention rather than a mechanism; a buyer
+ * that needs the real guarantee supplies a store that survives restart.
+ */
+export function memoryHistory() {
+    const byProvider = new Map();
+    return {
+        seen: (providerPubkey, sessionId) => byProvider.get(providerPubkey)?.has(sessionId) ?? false,
+        record: (providerPubkey, sessionId) => {
+            const ids = byProvider.get(providerPubkey) ?? new Set();
+            ids.add(sessionId);
+            byProvider.set(providerPubkey, ids);
+        },
+    };
+}
+//# sourceMappingURL=history.js.map

package/dist/src/history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.js","sourceRoot":"","sources":["../../src/history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAQH;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,UAAU,GAAG,IAAI,GAAG,EAAuB,CAAC;IAClD,OAAO;QACL,IAAI,EAAE,CAAC,cAAc,EAAE,SAAS,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,GAAG,CAAC,SAAS,CAAC,IAAI,KAAK;QAC5F,MAAM,EAAE,CAAC,cAAc,EAAE,SAAS,EAAE,EAAE;YACpC,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,IAAI,GAAG,EAAU,CAAC;YAChE,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACnB,UAAU,CAAC,GAAG,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACtC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/src/http/buyer.d.ts

@@ -0,0 +1,57 @@
+import { type SignerStore } from '../signer.js';
+import { type SessionHistory } from '../history.js';
+import type { Measurement, Offer, Reservation, State } from '../types.js';
+import type { Meter } from './provider.js';
+export declare class BuyerRefused extends Error {
+}
+export declare class BuyerSession {
+    readonly offer: Offer;
+    private readonly buyerSk;
+    private readonly meter;
+    /** SPEC.md 4, and the same warning as the provider's: the default forgets on restart. */
+    private readonly store;
+    /**
+     * SPEC.md 7.4b. What the covenant actually holds, if this buyer funded one. Supplying it lets
+     * the buyer refuse to agree a total the covenant could never pay out -- see `countersign`.
+     */
+    private readonly fundedSompi?;
+    private seq;
+    private cumulativeUnits;
+    private cumulativeSompi;
+    private lastStateDigest;
+    private bias;
+    constructor(offer: Offer, buyerSk: string, meter: Meter, expectedNetwork?: string, 
+    /**
+     * SPEC.md 3.1a. Defaults to a history that remembers nothing before this session, which
+     * catches nothing -- a single session cannot repeat an identifier. A buyer that runs more
+     * than one session against a provider MUST pass a history that outlives them all.
+     */
+    history?: SessionHistory, 
+    /** SPEC.md 4, and the same warning as the provider's: the default forgets on restart. */
+    store?: SignerStore, 
+    /**
+     * SPEC.md 7.4b. What the covenant actually holds, if this buyer funded one. Supplying it lets
+     * the buyer refuse to agree a total the covenant could never pay out -- see `countersign`.
+     */
+    fundedSompi?: number | undefined);
+    get spentSompi(): number;
+    /** Authorise exactly one chunk. Never the session (SPEC.md 3.2). */
+    reserve(units?: number): Reservation;
+    /**
+     * Count the delivered content and produce the buyer's Measurement.
+     *
+     * The provider's Measurement is checked here for signature and content digest, but its COUNT is
+     * not adopted -- that is the point. A mismatched digest means the two sides are describing
+     * different bytes, and no amount of counting can reconcile that (SPEC.md 5 rule 3).
+     */
+    measure(content: Uint8Array, providerMeasurement: Measurement, seq: number): Measurement;
+    /**
+     * Check the State the provider proposes, and countersign it if it is right.
+     *
+     * RECOMPUTED, NEVER TRUSTED. The amount is derived from the Offer's price and the agreed units,
+     * not read off the wire -- a buyer that signs whatever `cumulativeSompi` arrives has handed the
+     * provider a blank cheque with a signature already on it.
+     */
+    countersign(state: State, providerSig: string, myUnits: number): string;
+}
+//# sourceMappingURL=buyer.d.ts.map

package/dist/src/http/buyer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buyer.d.ts","sourceRoot":"","sources":["../../../src/http/buyer.ts"],"names":[],"mappings":"AAWA,OAAO,EAAyC,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAEvF,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAInE,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAE3C,qBAAa,YAAa,SAAQ,KAAK;CAAG;AAE1C,qBAAa,YAAY;IAQrB,QAAQ,CAAC,KAAK,EAAE,KAAK;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAQtB,yFAAyF;IACzF,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAvB/B,OAAO,CAAC,GAAG,CAAM;IACjB,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,IAAI,CAA6B;gBAG9B,KAAK,EAAE,KAAK,EACJ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,KAAK,EAC7B,eAAe,CAAC,EAAE,MAAM;IACxB;;;;OAIG;IACH,OAAO,GAAE,cAAgC;IACzC,yFAAyF;IACxE,KAAK,GAAE,WAA2B;IACnD;;;OAGG;IACc,WAAW,CAAC,EAAE,MAAM,YAAA;IAKvC,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,oEAAoE;IACpE,OAAO,CAAC,KAAK,SAAwB,GAAG,WAAW;IAenD;;;;;;OAMG;IACH,OAAO,CAAC,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW;IA0BxF;;;;;;OAMG;IACH,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;CA0CxE"}

package/dist/src/http/buyer.js

@@ -0,0 +1,151 @@
+/**
+ * The buyer's half of a metered session.
+ *
+ * WHAT THE BUYER IS TRUSTED FOR: nothing either (SPEC.md 1). It counts what it actually received
+ * and signs that. If its count and the provider's disagree past tolerance the session stops --
+ * there is no arbiter, and "the only remedy for disagreement is to stop."
+ *
+ * THE BUYER COUNTS THE BYTES IT WAS GIVEN, not the ones it was told about. That sentence is the
+ * whole product. Everything else here is bookkeeping around it.
+ */
+import { blake3Hex, digestHex, signEnvelope, verify, verifyState } from '../encoding.js';
+import { signStateWithObligations, memoryStore } from '../signer.js';
+import { acceptOffer } from '../offer.js';
+import { memoryHistory } from '../history.js';
+import { priceOf, CLOSE_FEE_SOMPI } from '../reservation.js';
+import { newBiasState, observeResidual, biasAlarm } from '../bias.js';
+import { toleranceBound } from '../reconcile.js';
+export class BuyerRefused extends Error {
+}
+export class BuyerSession {
+    offer;
+    buyerSk;
+    meter;
+    store;
+    fundedSompi;
+    seq = -1;
+    cumulativeUnits = 0;
+    cumulativeSompi = 0;
+    lastStateDigest = null;
+    bias = newBiasState();
+    constructor(offer, buyerSk, meter, expectedNetwork, 
+    /**
+     * SPEC.md 3.1a. Defaults to a history that remembers nothing before this session, which
+     * catches nothing -- a single session cannot repeat an identifier. A buyer that runs more
+     * than one session against a provider MUST pass a history that outlives them all.
+     */
+    history = memoryHistory(), 
+    /** SPEC.md 4, and the same warning as the provider's: the default forgets on restart. */
+    store = memoryStore(), 
+    /**
+     * SPEC.md 7.4b. What the covenant actually holds, if this buyer funded one. Supplying it lets
+     * the buyer refuse to agree a total the covenant could never pay out -- see `countersign`.
+     */
+    fundedSompi) {
+        this.offer = offer;
+        this.buyerSk = buyerSk;
+        this.meter = meter;
+        this.store = store;
+        this.fundedSompi = fundedSompi;
+        acceptOffer(offer, expectedNetwork, history);
+    }
+    get spentSompi() {
+        return this.cumulativeSompi;
+    }
+    /** Authorise exactly one chunk. Never the session (SPEC.md 3.2). */
+    reserve(units = this.offer.babelUnits) {
+        if (units > this.offer.babelUnits)
+            throw new BuyerRefused('refusing to reserve more than one chunk');
+        const next = this.seq + 1;
+        const reservation = {
+            v: 1,
+            sessionId: this.offer.sessionId,
+            seq: next,
+            units,
+            cumulativeUnits: this.cumulativeUnits + units,
+            cumulativeSompi: this.cumulativeSompi + priceOf(this.offer, units),
+            prevState: this.lastStateDigest,
+        };
+        return signEnvelope(reservation, this.buyerSk);
+    }
+    /**
+     * Count the delivered content and produce the buyer's Measurement.
+     *
+     * The provider's Measurement is checked here for signature and content digest, but its COUNT is
+     * not adopted -- that is the point. A mismatched digest means the two sides are describing
+     * different bytes, and no amount of counting can reconcile that (SPEC.md 5 rule 3).
+     */
+    measure(content, providerMeasurement, seq) {
+        if (!verify(providerMeasurement, this.offer.providerPubkey)) {
+            throw new BuyerRefused('the provider Measurement does not verify');
+        }
+        const contentDigest = blake3Hex(content);
+        if (providerMeasurement.contentDigest !== contentDigest) {
+            throw new BuyerRefused('the provider is describing different bytes than it delivered');
+        }
+        const units = this.meter(content);
+        const bound = toleranceBound(this.offer, providerMeasurement.units);
+        if (Math.abs(units - providerMeasurement.units) > bound) {
+            throw new BuyerRefused(`counts differ by more than ${bound}: ${units} vs ${providerMeasurement.units}`);
+        }
+        const measurement = {
+            v: 1,
+            sessionId: this.offer.sessionId,
+            seq,
+            by: 'buyer',
+            units,
+            cumulativeUnits: this.cumulativeUnits + units,
+            contentDigest,
+            measurementId: blake3Hex(`${this.offer.sessionId}/${seq}/buyer`).slice(0, 32),
+        };
+        return signEnvelope(measurement, this.buyerSk);
+    }
+    /**
+     * Check the State the provider proposes, and countersign it if it is right.
+     *
+     * RECOMPUTED, NEVER TRUSTED. The amount is derived from the Offer's price and the agreed units,
+     * not read off the wire -- a buyer that signs whatever `cumulativeSompi` arrives has handed the
+     * provider a blank cheque with a signature already on it.
+     */
+    countersign(state, providerSig, myUnits) {
+        if (state.sessionId !== this.offer.sessionId)
+            throw new BuyerRefused('State is for another session');
+        if (state.seq !== this.seq + 1)
+            throw new BuyerRefused(`State seq ${state.seq} does not follow ${this.seq}`);
+        if (state.prevState !== this.lastStateDigest)
+            throw new BuyerRefused('State does not chain to the last one');
+        const expected = state.cumulativeUnits * this.offer.unitPriceSompi;
+        if (state.cumulativeSompi !== expected) {
+            throw new BuyerRefused(`State bills ${state.cumulativeSompi}, recomputed ${expected}`);
+        }
+        if (state.cumulativeUnits > this.cumulativeUnits + myUnits) {
+            throw new BuyerRefused('State bills more units than the buyer counted');
+        }
+        // SPEC.md 7.4b. `expire` pays the provider EXACTLY `pendingSompi`, so a total the covenant
+        // cannot cover -- including the fee for the transaction that pays it -- has NO valid close,
+        // and the entire balance is stranded. The covenant cannot check this itself: it would need to
+        // know the fee of a transaction that does not exist yet. The buyer can, and must.
+        if (this.fundedSompi !== undefined) {
+            const payable = this.fundedSompi - CLOSE_FEE_SOMPI;
+            if (state.cumulativeSompi > payable) {
+                throw new BuyerRefused(`State bills ${state.cumulativeSompi}, above the ${payable} this covenant can pay out ` +
+                    `(funded ${this.fundedSompi} less the ${CLOSE_FEE_SOMPI} close fee) -- SPEC.md 7.4b`);
+            }
+        }
+        if (!verifyState(state, providerSig, this.offer.providerPubkey)) {
+            throw new BuyerRefused('the provider signature over the State does not verify');
+        }
+        // SPEC.md 5.1.1, buyer side. The provider can ride the tolerance too.
+        this.bias = observeResidual(this.bias, state.cumulativeUnits - (this.cumulativeUnits + myUnits));
+        if (biasAlarm(this.bias))
+            throw new BuyerRefused('bias detector tripped -- halting the session');
+        this.seq = state.seq;
+        this.cumulativeUnits = state.cumulativeUnits;
+        this.cumulativeSompi = state.cumulativeSompi;
+        this.lastStateDigest = digestHex(state);
+        // SPEC.md 4, buyer side. The obligations are symmetric: a buyer that signs two States at one
+        // seq has handed the provider a choice of which to settle, and it will not choose the cheaper.
+        return signStateWithObligations(this.store, state, this.buyerSk);
+    }
+}
+//# sourceMappingURL=buyer.js.map

package/dist/src/http/buyer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buyer.js","sourceRoot":"","sources":["../../../src/http/buyer.ts"],"names":[],"mappings":"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"}

package/dist/src/http/client.d.ts

@@ -0,0 +1,55 @@
+/**
+ * A buyer that drives a metered session over HTTP, start to finish.
+ *
+ * This is the reference client: read the 402, decide whether the terms are acceptable, then run
+ * chunks until the work is done or something disagrees. It is short because every decision it
+ * makes lives in buyer.ts, which is where the rules are.
+ */
+import { digestHex } from '../encoding.js';
+import { BuyerSession } from './buyer.js';
+import type { SessionHistory } from '../history.js';
+import type { Meter } from './provider.js';
+import type { Offer, State } from '../types.js';
+export declare class ProtocolError extends Error {
+}
+/**
+ * Fetch the 402 and take the Offer out of it. The 402 is the answer, not a failure.
+ *
+ * The buyer's key goes UP with the request because the Offer commits to
+ * blake3(buyer || provider); a provider cannot sign terms for a buyer it has not been told about.
+ */
+export declare function readOffer(base: string, buyerPubkey: string): Promise<Offer>;
+export interface ChunkOutcome {
+    content: Uint8Array;
+    state: State;
+    billedUnits: number;
+    /**
+     * The two signatures over this State's 72-byte preimage.
+     *
+     * Returned because SETTLEMENT NEEDS THEM and nothing else could reach them. The covenant's
+     * `settle` entry takes both, and a caller holding only the State holds a number it cannot
+     * enforce -- which was true of every caller of this function until a product tried to settle.
+     */
+    providerSig: string;
+    buyerSig: string;
+}
+/**
+ * Run one chunk: reserve, receive, count, reconcile, countersign.
+ *
+ * Two round trips, because the buyer cannot honestly sign a count for content it has not seen.
+ */
+export declare function runBabel(base: string, session: BuyerSession, prompt: string, units?: number): Promise<ChunkOutcome>;
+/**
+ * Open a session against a server and hand back the buyer half, ready to run chunks.
+ *
+ * `history` is SPEC.md 3.1a's obligation and belongs to the CALLER, because it has to outlive any
+ * one session to mean anything: a buyer opening many sessions against one provider creates the
+ * history once and passes it to every call. Omitting it leaves that buyer unprotected against a
+ * provider that reuses a session identifier deliberately.
+ */
+export declare function openSession(base: string, buyerSk: string, meter: Meter, expectedNetwork?: string, history?: SessionHistory): Promise<{
+    offer: Offer;
+    session: BuyerSession;
+}>;
+export { digestHex };
+//# sourceMappingURL=client.d.ts.map

package/dist/src/http/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/http/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,SAAS,EAAgB,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEhD,qBAAa,aAAc,SAAQ,KAAK;CAAG;AAa3C;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAWjF;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,UAAU,CAAC;IACpB,KAAK,EAAE,KAAK,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,YAAY,CAAC,CAoBvB;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,KAAK,EACZ,eAAe,CAAC,EAAE,MAAM,EACxB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC,CAMlD;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/dist/src/http/client.js

@@ -0,0 +1,83 @@
+/**
+ * A buyer that drives a metered session over HTTP, start to finish.
+ *
+ * This is the reference client: read the 402, decide whether the terms are acceptable, then run
+ * chunks until the work is done or something disagrees. It is short because every decision it
+ * makes lives in buyer.ts, which is where the rules are.
+ */
+import { digestHex, publicKeyHex } from '../encoding.js';
+import { BuyerSession } from './buyer.js';
+import { fromBase64 } from './protocol.js';
+export class ProtocolError extends Error {
+}
+async function post(base, path, body) {
+    const res = await fetch(`${base}${path}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    if (!res.ok)
+        throw new ProtocolError(`${path} -> ${res.status} ${text}`);
+    return JSON.parse(text);
+}
+/**
+ * Fetch the 402 and take the Offer out of it. The 402 is the answer, not a failure.
+ *
+ * The buyer's key goes UP with the request because the Offer commits to
+ * blake3(buyer || provider); a provider cannot sign terms for a buyer it has not been told about.
+ */
+export async function readOffer(base, buyerPubkey) {
+    const res = await fetch(`${base}/metered/open`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ buyerPubkey }),
+    });
+    if (res.status !== 402)
+        throw new ProtocolError(`expected 402, got ${res.status}`);
+    const body = (await res.json());
+    const offer = body.accepts.find((a) => a.scheme === 'metered');
+    if (!offer)
+        throw new ProtocolError('no metered offer in accepts');
+    return offer;
+}
+/**
+ * Run one chunk: reserve, receive, count, reconcile, countersign.
+ *
+ * Two round trips, because the buyer cannot honestly sign a count for content it has not seen.
+ */
+export async function runBabel(base, session, prompt, units) {
+    const reservation = session.reserve(units);
+    const delivered = await post(base, '/metered/babel', { reservation, prompt });
+    // Decoded before anything is measured, so every number below is taken over the bytes the buyer
+    // actually keeps -- not over the transit encoding they arrived in.
+    const content = fromBase64(delivered.contentB64);
+    const mine = session.measure(content, delivered.measurement, reservation.seq);
+    const settled = await post(base, '/metered/state', { measurement: mine });
+    const buyerSig = session.countersign(settled.state, settled.providerSig, mine.units);
+    await post(base, '/metered/countersign', { state: settled.state, buyerSig });
+    return {
+        content,
+        state: settled.state,
+        billedUnits: settled.billedUnits,
+        providerSig: settled.providerSig,
+        buyerSig,
+    };
+}
+/**
+ * Open a session against a server and hand back the buyer half, ready to run chunks.
+ *
+ * `history` is SPEC.md 3.1a's obligation and belongs to the CALLER, because it has to outlive any
+ * one session to mean anything: a buyer opening many sessions against one provider creates the
+ * history once and passes it to every call. Omitting it leaves that buyer unprotected against a
+ * provider that reuses a session identifier deliberately.
+ */
+export async function openSession(base, buyerSk, meter, expectedNetwork, history) {
+    const offer = await readOffer(base, publicKeyHex(buyerSk));
+    if (offer.buyerPubkey !== publicKeyHex(buyerSk)) {
+        throw new ProtocolError('the Offer names a different buyer than the one that asked');
+    }
+    return { offer, session: new BuyerSession(offer, buyerSk, meter, expectedNetwork, history) };
+}
+export { digestHex };
+//# sourceMappingURL=client.js.map