metered-protocol 1.0.0

package/dist/src/bias.d.ts

@@ -0,0 +1,48 @@
+/**
+ * SPEC.md §5.1.1 -- the bias detector, as a one-sided CUSUM.
+ *
+ * WHAT THIS REPLACED. §5.1 used to say a party MAY halt on "a persistent one-sided residual".
+ * Persistent was never defined, so no two implementations could agree, and the rule decides when
+ * to stop taking someone's money. Study C measured it instead: `evidence/results-c.txt`.
+ *
+ * WHY ONE-SIDED. The threat is directional -- a buyer under-reporting makes providerUnits −
+ * buyerUnits POSITIVE -- and so is the only honest divergence ever observed (Study A's three
+ * counter-examples all had the buyer counting fewer). Sign therefore carries no information at
+ * all, and rate is the entire signal. That is what a CUSUM measures.
+ *
+ * WHAT IT CATCHES, measured rather than hoped:
+ *
+ *   a buyer shaving 1 token from every babel   caught, median 9 babels
+ *   ... from half of all babels                caught, median 80 babels
+ *   ... from a quarter                         1% of the time
+ *   ... from a tenth                           never
+ *
+ * with ZERO false alarms in 800,000 honest babels. So the leak §5.1 promises to bound is bounded
+ * at roughly 0.045% per babel -- not at zero. An implementation needing a tighter bound must
+ * lower `toleranceAbs`; tuning K below 0.5 is not supported, because Study C bounds the honest
+ * divergence rate at 0.075% rather than measuring it as exactly zero.
+ */
+/** Slack per babel. Above the honest drift (zero to measurement), below any real cheat. */
+export declare const K = 0.5;
+/** Alarm threshold. Chosen for zero false alarms across 400 sessions of 2,000 honest babels. */
+export declare const H = 5;
+/**
+ * Running detector state. Deliberately a plain value rather than a class: SPEC.md §4 requires a
+ * party to durably record what it has seen, and a value serialises without ceremony.
+ */
+export interface BiasState {
+    /** The CUSUM statistic. Never negative -- that is what makes it one-sided. */
+    sum: number;
+    /** Babels observed. Reported with an alarm so the operator can see how fast it fired. */
+    babels: number;
+}
+export declare const newBiasState: () => BiasState;
+/**
+ * Feed one babel's residual (providerUnits − buyerUnits) and return the updated state.
+ *
+ * Pure, so a caller can persist the result before acting on it, per §4's record-then-send rule.
+ */
+export declare function observeResidual(state: BiasState, residual: number): BiasState;
+/** SPEC.md §5.1.1: the session halts when the statistic reaches the threshold. */
+export declare const biasAlarm: (state: BiasState) => boolean;
+//# sourceMappingURL=bias.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bias.d.ts","sourceRoot":"","sources":["../../src/bias.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,2FAA2F;AAC3F,eAAO,MAAM,CAAC,MAAM,CAAC;AAErB,gGAAgG;AAChG,eAAO,MAAM,CAAC,IAAI,CAAC;AAEnB;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAC;IACZ,yFAAyF;IACzF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,YAAY,QAAO,SAAoC,CAAC;AAErE;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,CAK7E;AAED,kFAAkF;AAClF,eAAO,MAAM,SAAS,GAAI,OAAO,SAAS,KAAG,OAAyB,CAAC"}

package/dist/src/bias.js

@@ -0,0 +1,43 @@
+/**
+ * SPEC.md §5.1.1 -- the bias detector, as a one-sided CUSUM.
+ *
+ * WHAT THIS REPLACED. §5.1 used to say a party MAY halt on "a persistent one-sided residual".
+ * Persistent was never defined, so no two implementations could agree, and the rule decides when
+ * to stop taking someone's money. Study C measured it instead: `evidence/results-c.txt`.
+ *
+ * WHY ONE-SIDED. The threat is directional -- a buyer under-reporting makes providerUnits −
+ * buyerUnits POSITIVE -- and so is the only honest divergence ever observed (Study A's three
+ * counter-examples all had the buyer counting fewer). Sign therefore carries no information at
+ * all, and rate is the entire signal. That is what a CUSUM measures.
+ *
+ * WHAT IT CATCHES, measured rather than hoped:
+ *
+ *   a buyer shaving 1 token from every babel   caught, median 9 babels
+ *   ... from half of all babels                caught, median 80 babels
+ *   ... from a quarter                         1% of the time
+ *   ... from a tenth                           never
+ *
+ * with ZERO false alarms in 800,000 honest babels. So the leak §5.1 promises to bound is bounded
+ * at roughly 0.045% per babel -- not at zero. An implementation needing a tighter bound must
+ * lower `toleranceAbs`; tuning K below 0.5 is not supported, because Study C bounds the honest
+ * divergence rate at 0.075% rather than measuring it as exactly zero.
+ */
+/** Slack per babel. Above the honest drift (zero to measurement), below any real cheat. */
+export const K = 0.5;
+/** Alarm threshold. Chosen for zero false alarms across 400 sessions of 2,000 honest babels. */
+export const H = 5;
+export const newBiasState = () => ({ sum: 0, babels: 0 });
+/**
+ * Feed one babel's residual (providerUnits − buyerUnits) and return the updated state.
+ *
+ * Pure, so a caller can persist the result before acting on it, per §4's record-then-send rule.
+ */
+export function observeResidual(state, residual) {
+    return {
+        sum: Math.max(0, state.sum + residual - K),
+        babels: state.babels + 1,
+    };
+}
+/** SPEC.md §5.1.1: the session halts when the statistic reaches the threshold. */
+export const biasAlarm = (state) => state.sum >= H;
+//# sourceMappingURL=bias.js.map

package/dist/src/bias.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bias.js","sourceRoot":"","sources":["../../src/bias.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,2FAA2F;AAC3F,MAAM,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC;AAErB,gGAAgG;AAChG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAanB,MAAM,CAAC,MAAM,YAAY,GAAG,GAAc,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;AAErE;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAAgB,EAAE,QAAgB;IAChE,OAAO;QACL,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,GAAG,QAAQ,GAAG,CAAC,CAAC;QAC1C,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC;KACzB,CAAC;AACJ,CAAC;AAED,kFAAkF;AAClF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAgB,EAAW,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC"}

package/dist/src/checkpoint.d.ts

@@ -0,0 +1,57 @@
+import type { Offer, State } from './types.js';
+/**
+ * Anchors a 32-byte digest on-chain and returns the transaction that carries it.
+ *
+ * IT RETURNS THE TXID BECAUSE A CHECKPOINT NOBODY CAN FIND IS NOT EVIDENCE. SPEC.md 8's whole
+ * claim is that a checkpoint proves a State existed before a given block; proving it means
+ * fetching that transaction and reading the payload back. A record that says only "confirmed"
+ * asks a future reader to take this process's word for it, which is the opposite of the point.
+ *
+ * Still fire-and-forget: the session never waits on the promise.
+ */
+export type Anchor = (digest: string) => Promise<string>;
+export interface CheckpointRecord {
+    seq: number;
+    digest: string;
+    status: 'pending' | 'confirmed' | 'failed';
+    /** The transaction carrying the digest. Absent until the anchor resolves; this is the evidence. */
+    txid?: string;
+    error?: string;
+}
+/** §8: every `checkpointEvery` babels. `0` disables checkpointing entirely. */
+export declare function isCheckpointBabel(offer: Offer, seq: number): boolean;
+/**
+ * The checkpointer. Deliberately NOT async: `record` returns as soon as the anchor is dispatched,
+ * so there is no promise for a caller to await and no way for a slow chain to become a slow
+ * session. The only way to observe an anchor is to ask afterwards.
+ */
+export declare class Checkpointer {
+    private readonly anchor;
+    private readonly records;
+    /**
+     * In-flight anchors, held ONLY so a reporter can wait for them after a session is over.
+     * Nothing in a session ever reads this: the moment it does, a slow chain becomes a slow session,
+     * which is the exact failure 8 exists to prevent.
+     */
+    private readonly inFlight;
+    constructor(anchor: Anchor);
+    /**
+     * Anchor this State's digest if its babel calls for one. Returns the record immediately, always
+     * `pending`, because the point is that nothing waits.
+     */
+    record(offer: Offer, state: State): CheckpointRecord | null;
+    get(seq: number): CheckpointRecord | undefined;
+    all(): CheckpointRecord[];
+    /** Checkpoints still in flight. A session MAY close with these outstanding; §8 allows it. */
+    pending(): CheckpointRecord[];
+    /**
+     * Wait for every dispatched anchor to finish, for REPORTING ONLY.
+     *
+     * A session must never call this. It exists because a reporter that prints `pending` and stops
+     * has proved nothing -- it has printed the state a record is BORN in, which every record shows
+     * whether the anchor works or not. Waiting once, after the session has already closed, is what
+     * makes the difference between confirmed and failed visible.
+     */
+    settled(): Promise<void>;
+}
+//# sourceMappingURL=checkpoint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../../src/checkpoint.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;GASG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAEzD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC3C,mGAAmG;IACnG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAGpE;AAED;;;;GAIG;AACH,qBAAa,YAAY;IAUX,OAAO,CAAC,QAAQ,CAAC,MAAM;IATnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAE/D;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA+B;gBAE3B,MAAM,EAAE,MAAM;IAE3C;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,GAAG,gBAAgB,GAAG,IAAI;IAwB3D,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAI9C,GAAG,IAAI,gBAAgB,EAAE;IAIzB,6FAA6F;IAC7F,OAAO,IAAI,gBAAgB,EAAE;IAI7B;;;;;;;OAOG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B"}

package/dist/src/checkpoint.js

@@ -0,0 +1,84 @@
+/**
+ * SPEC.md §8 -- checkpoints, which MUST be non-blocking.
+ *
+ * WHY THE RULE EXISTS, in one measurement. Study B anchored 25 checkpoints on testnet-10 and found
+ * p50 1,053 ms and p90 1,879 ms. A session that awaited each anchor would stall for roughly two
+ * seconds every `checkpointEvery` babels, which for a streamed response is the difference between
+ * a working product and an unusable one. So the session continues while the anchor confirms, and
+ * this module never returns a promise the caller is tempted to await.
+ *
+ * WHAT A CHECKPOINT IS FOR, and what it is NOT. §8: "Checkpoints are evidence, not safety." They
+ * prove a State existed before a given block, which makes a stale close provable and attributable
+ * after the fact. They cannot PREVENT one -- the covenant cannot recover a State from a digest, so
+ * it cannot enforce a minimum seq. Prevention is §7.2's response window. A failed anchor therefore
+ * costs evidence, never funds, which is exactly why failing one is allowed not to stop anything.
+ */
+import { digestHex } from './encoding.js';
+/** §8: every `checkpointEvery` babels. `0` disables checkpointing entirely. */
+export function isCheckpointBabel(offer, seq) {
+    if (offer.checkpointEvery <= 0)
+        return false;
+    return (seq + 1) % offer.checkpointEvery === 0;
+}
+/**
+ * The checkpointer. Deliberately NOT async: `record` returns as soon as the anchor is dispatched,
+ * so there is no promise for a caller to await and no way for a slow chain to become a slow
+ * session. The only way to observe an anchor is to ask afterwards.
+ */
+export class Checkpointer {
+    anchor;
+    records = new Map();
+    /**
+     * In-flight anchors, held ONLY so a reporter can wait for them after a session is over.
+     * Nothing in a session ever reads this: the moment it does, a slow chain becomes a slow session,
+     * which is the exact failure 8 exists to prevent.
+     */
+    inFlight = new Set();
+    constructor(anchor) {
+        this.anchor = anchor;
+    }
+    /**
+     * Anchor this State's digest if its babel calls for one. Returns the record immediately, always
+     * `pending`, because the point is that nothing waits.
+     */
+    record(offer, state) {
+        if (!isCheckpointBabel(offer, state.seq))
+            return null;
+        const entry = { seq: state.seq, digest: digestHex(state), status: 'pending' };
+        this.records.set(state.seq, entry);
+        // A rejected anchor marks the record and stops there. It MUST NOT propagate: an unhandled
+        // rejection here would take down a session over lost evidence, and evidence is not safety.
+        const flight = this.anchor(entry.digest).then((txid) => {
+            entry.status = 'confirmed';
+            entry.txid = txid;
+        }, (err) => {
+            entry.status = 'failed';
+            entry.error = err instanceof Error ? err.message : String(err);
+        });
+        this.inFlight.add(flight);
+        void flight.finally(() => this.inFlight.delete(flight));
+        return entry;
+    }
+    get(seq) {
+        return this.records.get(seq);
+    }
+    all() {
+        return [...this.records.values()].sort((a, b) => a.seq - b.seq);
+    }
+    /** Checkpoints still in flight. A session MAY close with these outstanding; §8 allows it. */
+    pending() {
+        return this.all().filter((r) => r.status === 'pending');
+    }
+    /**
+     * Wait for every dispatched anchor to finish, for REPORTING ONLY.
+     *
+     * A session must never call this. It exists because a reporter that prints `pending` and stops
+     * has proved nothing -- it has printed the state a record is BORN in, which every record shows
+     * whether the anchor works or not. Waiting once, after the session has already closed, is what
+     * makes the difference between confirmed and failed visible.
+     */
+    async settled() {
+        await Promise.allSettled([...this.inFlight]);
+    }
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/src/checkpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.js","sourceRoot":"","sources":["../../src/checkpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAwB1C,+EAA+E;AAC/E,MAAM,UAAU,iBAAiB,CAAC,KAAY,EAAE,GAAW;IACzD,IAAI,KAAK,CAAC,eAAe,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAC7C,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,eAAe,KAAK,CAAC,CAAC;AACjD,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,YAAY;IAUM;IATZ,OAAO,GAAG,IAAI,GAAG,EAA4B,CAAC;IAE/D;;;;OAIG;IACc,QAAQ,GAAG,IAAI,GAAG,EAAoB,CAAC;IAExD,YAA6B,MAAc;QAAd,WAAM,GAAN,MAAM,CAAQ;IAAG,CAAC;IAE/C;;;OAGG;IACH,MAAM,CAAC,KAAY,EAAE,KAAY;QAC/B,IAAI,CAAC,iBAAiB,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAEtD,MAAM,KAAK,GAAqB,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QAChG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAEnC,0FAA0F;QAC1F,2FAA2F;QAC3F,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAC3C,CAAC,IAAI,EAAE,EAAE;YACP,KAAK,CAAC,MAAM,GAAG,WAAW,CAAC;YAC3B,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;QACpB,CAAC,EACD,CAAC,GAAY,EAAE,EAAE;YACf,KAAK,CAAC,MAAM,GAAG,QAAQ,CAAC;YACxB,KAAK,CAAC,KAAK,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,CAAC,CACF,CAAC;QACF,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC1B,KAAK,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QAExD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED,GAAG;QACD,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IAClE,CAAC;IAED,6FAA6F;IAC7F,OAAO;QACL,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC;IAC1D,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO;QACX,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC/C,CAAC;CACF"}

package/dist/src/deadline.d.ts

@@ -0,0 +1,71 @@
+/**
+ * SPEC.md §7.3a -- the response window is the PROVIDER'S DEADLINE, not merely a dispute window.
+ *
+ * `expire` lowers to `OpCheckSequenceVerify`, which measures the age of the covenant UTXO being
+ * spent. So the clock runs from the moment the covenant is funded, and each `settle` resets it by
+ * creating a fresh UTXO. That has a consequence §7.3 never stated:
+ *
+ *   ONCE THE COVENANT UTXO IS OLDER THAN THE WINDOW AND NO CLAIM IS PENDING, THE BUYER CAN CLOSE
+ *   AND TAKE BACK EVERYTHING -- INCLUDING PAYMENT FOR WORK ALREADY DELIVERED.
+ *
+ * The provider is not defenceless: it holds a doubly-signed State and can post it at any time, and
+ * a stale claim can never overwrite a fresher one (`seq > pendingSeq` is strict). But it must post
+ * BEFORE the deadline, not merely notice afterwards.
+ *
+ * WHY THIS IS NOT A WATCHTOWER PROBLEM. Lightning needs one because punishment is retrospective:
+ * you must detect an old state and answer it with a justice transaction, holding per-update
+ * revocation secrets, while being a wallet that is offline by nature -- so you delegate to a third
+ * party who must be trusted, can be bribed, and has to be paid. None of that shape is here. The
+ * party at risk is a SERVER, online by definition because serving is its job; it needs only the
+ * latest State, which it already holds; there is no secret, no third party, and nothing to
+ * delegate. What it needs is not vigilance but a DEADLINE it keeps, which is a policy it can
+ * evaluate locally from numbers it already has.
+ */
+export interface ExposurePolicy {
+    /**
+     * Post a claim once the covenant UTXO reaches this age, in DAA. MUST be below the Offer's
+     * `responseWindowDaa` by enough margin for the settle to confirm.
+     */
+    settleByAgeDaa: number;
+    /** Post a claim once this much has accrued unsettled, whatever the age. 0 disables. */
+    settleAtUnsettledSompi: number;
+}
+export declare class PolicyRejected extends Error {
+}
+/**
+ * The margin between the policy's deadline and the window itself, in DAA.
+ *
+ * A settle that is BROADCAST before the deadline but confirms after it has not defended anything,
+ * so the policy must fire early enough to land. Study B measured checkpoint confirmation at 1,879
+ * ms for the 90th percentile; at the ~10 blocks per second this network produces, 60 DAA is about
+ * six seconds, which is three times that.
+ */
+export declare const CONFIRM_MARGIN_DAA = 60;
+/** Check a policy against the window it has to fit inside. Throws rather than quietly clamping. */
+export declare function acceptPolicy(policy: ExposurePolicy, responseWindowDaa: number): ExposurePolicy;
+export interface Exposure {
+    /** Age of the covenant UTXO the next close would spend, in DAA. */
+    ageDaa: number;
+    /** Value agreed but not yet posted on chain. */
+    unsettledSompi: number;
+}
+/**
+ * Whether the provider should post its claim now, and why.
+ *
+ * Deliberately a pure function of two numbers. It does not poll, hold a socket, or know what a
+ * chain is -- the caller has those, and a decision that can be computed is easier to test, to
+ * reason about, and to disagree with than one buried in a daemon.
+ */
+export declare function shouldSettle(policy: ExposurePolicy, now: Exposure): {
+    settle: boolean;
+    why: string | null;
+};
+/**
+ * The most a provider can lose under a policy: everything that can accrue before it must post.
+ *
+ * This is the provider's counterpart to the babel, and it is the number to choose deliberately.
+ * `settleAtUnsettledSompi` caps it directly; without one it is bounded only by how much a session
+ * can bill in `settleByAgeDaa`, which is why leaving it at 0 is a decision rather than a default.
+ */
+export declare function worstCaseExposure(policy: ExposurePolicy, maxBillSompi: number): number;
+//# sourceMappingURL=deadline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deadline.d.ts","sourceRoot":"","sources":["../../src/deadline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,uFAAuF;IACvF,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAED,qBAAa,cAAe,SAAQ,KAAK;CAAG;AAE5C;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC,mGAAmG;AACnG,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,GAAG,cAAc,CAU9F;AAED,MAAM,WAAW,QAAQ;IACvB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,EAAE,QAAQ,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAS3G;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAGtF"}

package/dist/src/deadline.js

@@ -0,0 +1,77 @@
+/**
+ * SPEC.md §7.3a -- the response window is the PROVIDER'S DEADLINE, not merely a dispute window.
+ *
+ * `expire` lowers to `OpCheckSequenceVerify`, which measures the age of the covenant UTXO being
+ * spent. So the clock runs from the moment the covenant is funded, and each `settle` resets it by
+ * creating a fresh UTXO. That has a consequence §7.3 never stated:
+ *
+ *   ONCE THE COVENANT UTXO IS OLDER THAN THE WINDOW AND NO CLAIM IS PENDING, THE BUYER CAN CLOSE
+ *   AND TAKE BACK EVERYTHING -- INCLUDING PAYMENT FOR WORK ALREADY DELIVERED.
+ *
+ * The provider is not defenceless: it holds a doubly-signed State and can post it at any time, and
+ * a stale claim can never overwrite a fresher one (`seq > pendingSeq` is strict). But it must post
+ * BEFORE the deadline, not merely notice afterwards.
+ *
+ * WHY THIS IS NOT A WATCHTOWER PROBLEM. Lightning needs one because punishment is retrospective:
+ * you must detect an old state and answer it with a justice transaction, holding per-update
+ * revocation secrets, while being a wallet that is offline by nature -- so you delegate to a third
+ * party who must be trusted, can be bribed, and has to be paid. None of that shape is here. The
+ * party at risk is a SERVER, online by definition because serving is its job; it needs only the
+ * latest State, which it already holds; there is no secret, no third party, and nothing to
+ * delegate. What it needs is not vigilance but a DEADLINE it keeps, which is a policy it can
+ * evaluate locally from numbers it already has.
+ */
+export class PolicyRejected extends Error {
+}
+/**
+ * The margin between the policy's deadline and the window itself, in DAA.
+ *
+ * A settle that is BROADCAST before the deadline but confirms after it has not defended anything,
+ * so the policy must fire early enough to land. Study B measured checkpoint confirmation at 1,879
+ * ms for the 90th percentile; at the ~10 blocks per second this network produces, 60 DAA is about
+ * six seconds, which is three times that.
+ */
+export const CONFIRM_MARGIN_DAA = 60;
+/** Check a policy against the window it has to fit inside. Throws rather than quietly clamping. */
+export function acceptPolicy(policy, responseWindowDaa) {
+    if (policy.settleByAgeDaa < 1)
+        throw new PolicyRejected('settleByAgeDaa must be >= 1');
+    if (policy.settleAtUnsettledSompi < 0)
+        throw new PolicyRejected('settleAtUnsettledSompi must be >= 0');
+    if (policy.settleByAgeDaa + CONFIRM_MARGIN_DAA > responseWindowDaa) {
+        throw new PolicyRejected(`settleByAgeDaa ${policy.settleByAgeDaa} leaves less than ${CONFIRM_MARGIN_DAA} DAA of the ` +
+            `${responseWindowDaa}-DAA window for the settle to confirm`);
+    }
+    return policy;
+}
+/**
+ * Whether the provider should post its claim now, and why.
+ *
+ * Deliberately a pure function of two numbers. It does not poll, hold a socket, or know what a
+ * chain is -- the caller has those, and a decision that can be computed is easier to test, to
+ * reason about, and to disagree with than one buried in a daemon.
+ */
+export function shouldSettle(policy, now) {
+    if (now.unsettledSompi <= 0)
+        return { settle: false, why: null };
+    if (now.ageDaa >= policy.settleByAgeDaa) {
+        return { settle: true, why: `the covenant UTXO is ${now.ageDaa} DAA old, at or past the deadline` };
+    }
+    if (policy.settleAtUnsettledSompi > 0 && now.unsettledSompi >= policy.settleAtUnsettledSompi) {
+        return { settle: true, why: `${now.unsettledSompi} sompi unsettled, at or past the exposure limit` };
+    }
+    return { settle: false, why: null };
+}
+/**
+ * The most a provider can lose under a policy: everything that can accrue before it must post.
+ *
+ * This is the provider's counterpart to the babel, and it is the number to choose deliberately.
+ * `settleAtUnsettledSompi` caps it directly; without one it is bounded only by how much a session
+ * can bill in `settleByAgeDaa`, which is why leaving it at 0 is a decision rather than a default.
+ */
+export function worstCaseExposure(policy, maxBillSompi) {
+    if (policy.settleAtUnsettledSompi <= 0)
+        return maxBillSompi;
+    return Math.min(policy.settleAtUnsettledSompi, maxBillSompi);
+}
+//# sourceMappingURL=deadline.js.map

package/dist/src/deadline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deadline.js","sourceRoot":"","sources":["../../src/deadline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAYH,MAAM,OAAO,cAAe,SAAQ,KAAK;CAAG;AAE5C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAErC,mGAAmG;AACnG,MAAM,UAAU,YAAY,CAAC,MAAsB,EAAE,iBAAyB;IAC5E,IAAI,MAAM,CAAC,cAAc,GAAG,CAAC;QAAE,MAAM,IAAI,cAAc,CAAC,6BAA6B,CAAC,CAAC;IACvF,IAAI,MAAM,CAAC,sBAAsB,GAAG,CAAC;QAAE,MAAM,IAAI,cAAc,CAAC,qCAAqC,CAAC,CAAC;IACvG,IAAI,MAAM,CAAC,cAAc,GAAG,kBAAkB,GAAG,iBAAiB,EAAE,CAAC;QACnE,MAAM,IAAI,cAAc,CACtB,kBAAkB,MAAM,CAAC,cAAc,qBAAqB,kBAAkB,cAAc;YAC1F,GAAG,iBAAiB,uCAAuC,CAC9D,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AASD;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,MAAsB,EAAE,GAAa;IAChE,IAAI,GAAG,CAAC,cAAc,IAAI,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;IACjE,IAAI,GAAG,CAAC,MAAM,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;QACxC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,wBAAwB,GAAG,CAAC,MAAM,mCAAmC,EAAE,CAAC;IACtG,CAAC;IACD,IAAI,MAAM,CAAC,sBAAsB,GAAG,CAAC,IAAI,GAAG,CAAC,cAAc,IAAI,MAAM,CAAC,sBAAsB,EAAE,CAAC;QAC7F,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,GAAG,CAAC,cAAc,iDAAiD,EAAE,CAAC;IACvG,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;AACtC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAsB,EAAE,YAAoB;IAC5E,IAAI,MAAM,CAAC,sBAAsB,IAAI,CAAC;QAAE,OAAO,YAAY,CAAC;IAC5D,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,sBAAsB,EAAE,YAAY,CAAC,CAAC;AAC/D,CAAC"}

package/dist/src/encoding.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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 declare function canonicalize(value: unknown): string;
+/** 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 declare const utf8: (text: string) => Uint8Array;
+export declare function blake3Hex(input: Uint8Array | string): string;
+/**
+ * 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 declare function partiesCommitment(buyerPubkey: string, providerPubkey: string): string;
+/** BLAKE3-256 of the canonical form of a value, hex. The only digest this protocol uses. */
+export declare function digestHex(value: unknown): string;
+export declare function publicKeyHex(privateKeyHex: string): string;
+/**
+ * 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 declare function sign(message: object, privateKeyHex: string, field?: string): string;
+export declare function verify(message: object, publicKeyHexStr: string, field?: string): boolean;
+/** Attach a signature under `field`, leaving the original untouched. */
+export declare function signEnvelope<T extends object>(message: T, privateKeyHex: string, field?: string): T & Record<string, string>;
+/**
+ * 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 declare function settlementPreimage(state: Record<string, unknown>): Uint8Array;
+/**
+ * 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 declare function settlementDigest(state: Record<string, unknown>): Uint8Array;
+/** Hex of the preimage. A string, so it can be compared, logged and pinned in a vector. */
+export declare function stateSigningPayload(state: object): string;
+export declare function signState(state: object, privateKeyHex: string): string;
+export declare function verifyState(state: object, sigHex: string, publicKeyHexStr: string): boolean;
+//# sourceMappingURL=encoding.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../src/encoding.ts"],"names":[],"mappings":"AAkBA;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAUnD;AASD,sDAAsD;AACtD;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,MAAM,MAAM,KAAG,UAA+B,CAAC;AAEpE,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAG5D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAErF;AAED,4FAA4F;AAC5F,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEhD;AAED,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;GAGG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,KAAK,SAAQ,GAAG,MAAM,CAGlF;AAED,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,KAAK,SAAQ,GAAG,OAAO,CASvF;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,aAAa,EAAE,MAAM,EAAE,KAAK,SAAQ,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE3H;AAsBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,CAS7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,CAE3E;AAED,2FAA2F;AAC3F,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAO3F"}