metered-protocol 1.0.0

package/dist/src/session.js

@@ -0,0 +1,92 @@
+/**
+ * The session driver -- the pieces of SPEC.md §§3-8, in the order a real chunk goes through them.
+ *
+ * Nothing new is decided here. Every rule lives in its own module and this composes them, which is
+ * deliberate: the rules are testable without a session, and the ORDER is testable without
+ * re-testing the rules.
+ *
+ * THE ONE THING WORTH READING TWICE. A Reservation's `cumulativeSompi` and a State's are different
+ * numbers and must not be conflated. The Reservation authorises `units × unitPriceSompi` -- what
+ * the buyer is willing to be exposed to for this chunk. The State settles `min(buyer, provider) ×
+ * unitPriceSompi` -- what was actually delivered, per §5 rule 6. Authorised is a ceiling, billed
+ * is a fact, and billing the authorised figure would quietly discard rule 6 and with it the
+ * entire reason the counts are two-sided.
+ */
+import { digestHex } from './encoding.js';
+import { acceptReservation, priceOf } from './reservation.js';
+import { reconcileBabel } from './reconcile.js';
+import { newBiasState, observeResidual, biasAlarm } from './bias.js';
+import { signStateWithObligations } from './signer.js';
+export class SessionHalted extends Error {
+    halt;
+    constructor(halt) {
+        super(`${halt.reason}: ${halt.detail}`);
+        this.halt = halt;
+    }
+}
+/**
+ * Drives one session for BOTH parties, which is what a test needs and what a real deployment
+ * splits in half. Keeping them together here is the only way to assert that the two halves agree.
+ */
+export class Session {
+    offer;
+    buyerStore;
+    providerStore;
+    checkpointer;
+    cursor = null;
+    bias = newBiasState();
+    constructor(offer, buyerStore, providerStore, checkpointer) {
+        this.offer = offer;
+        this.buyerStore = buyerStore;
+        this.providerStore = providerStore;
+        this.checkpointer = checkpointer;
+    }
+    get residualState() {
+        return this.bias;
+    }
+    get cumulativeSompi() {
+        return this.cursor?.cumulativeSompi ?? 0;
+    }
+    /**
+     * Run one chunk end to end: reserve, reconcile, bill, doubly sign, checkpoint.
+     *
+     * Throws SessionHalted on any rule failure. §1: "The only remedy for disagreement is to stop."
+     */
+    chunk(reservation, buyerMeasurement, providerMeasurement, keys) {
+        acceptReservation(this.offer, reservation, this.cursor);
+        const outcome = reconcileBabel(this.offer, buyerMeasurement, providerMeasurement, reservation.seq);
+        if (!outcome.ok)
+            throw new SessionHalted(outcome);
+        // §5.1.1. The residual is observed BEFORE the State is signed, so an alarming chunk is never
+        // settled -- halting after signing would leave a signed State the counterparty could close on.
+        this.bias = observeResidual(this.bias, outcome.residual);
+        if (biasAlarm(this.bias)) {
+            throw new SessionHalted({
+                ok: false,
+                reason: 'bias',
+                detail: `CUSUM reached ${this.bias.sum} after ${this.bias.babels} chunks`,
+            });
+        }
+        const state = {
+            v: 1,
+            sessionId: this.offer.sessionId,
+            seq: reservation.seq,
+            cumulativeUnits: outcome.billedCumulativeUnits,
+            cumulativeSompi: priceOf(this.offer, outcome.billedCumulativeUnits),
+            prevState: this.cursor?.stateDigest ?? null,
+        };
+        // Both parties sign the same bytes, each under its own obligations (§4). Neither signature
+        // depends on the other existing, so the order here carries no meaning.
+        const buyerSig = signStateWithObligations(this.buyerStore, state, keys.buyerSk);
+        const providerSig = signStateWithObligations(this.providerStore, state, keys.providerSk);
+        const checkpoint = this.checkpointer.record(this.offer, state);
+        this.cursor = {
+            seq: state.seq,
+            cumulativeUnits: state.cumulativeUnits,
+            cumulativeSompi: state.cumulativeSompi,
+            stateDigest: digestHex(state),
+        };
+        return { state, buyerSig, providerSig, billedUnits: outcome.billedUnits, checkpointed: checkpoint !== null };
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/src/session.js.map

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

package/dist/src/signer.d.ts

@@ -0,0 +1,31 @@
+import type { State } from './types.js';
+/** What a party must durably hold. Small on purpose: this gets written on every chunk. */
+export interface SignerRecord {
+    sessionId: string;
+    /** Highest seq this party has signed. -1 before anything is signed. */
+    highestSeq: number;
+    /** Digest of the State at `highestSeq`, which the next State's `prevState` must match. */
+    lastStateDigest: string | null;
+}
+/**
+ * Durable storage. Synchronous by design -- an async save invites a caller to forget the await,
+ * which turns record-then-send back into send-then-record silently.
+ */
+export interface SignerStore {
+    load(sessionId: string): SignerRecord | null;
+    save(record: SignerRecord): void;
+}
+export declare class SignerObligationError extends Error {
+}
+export declare const emptyRecord: (sessionId: string) => SignerRecord;
+/**
+ * Sign a State, or refuse. The refusals ARE the feature.
+ *
+ * §4.4's restart rule needs no separate code path: the record is loaded from the store on every
+ * call, so a fresh process behaves exactly like a long-running one. A restart that forgets is a
+ * store that lost data, not a signer that skipped a step.
+ */
+export declare function signStateWithObligations(store: SignerStore, state: State, privateKeyHex: string): string;
+/** An in-memory store. Fine for tests; a real party needs something that survives a crash. */
+export declare function memoryStore(): SignerStore;
+//# sourceMappingURL=signer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"signer.d.ts","sourceRoot":"","sources":["../../src/signer.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,0FAA0F;AAC1F,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAAC;IAC7C,IAAI,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;CAClC;AAED,qBAAa,qBAAsB,SAAQ,KAAK;CAAG;AAEnD,eAAO,MAAM,WAAW,GAAI,WAAW,MAAM,KAAG,YACQ,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,KAAK,EACZ,aAAa,EAAE,MAAM,GACpB,MAAM,CA4BR;AAED,8FAA8F;AAC9F,wBAAgB,WAAW,IAAI,WAAW,CAQzC"}

package/dist/src/signer.js

@@ -0,0 +1,57 @@
+/**
+ * SPEC.md §4 -- the signer obligations.
+ *
+ * These are the rules that lose money without any message being malformed. Nothing here is
+ * checkable by a counterparty and nothing here appears on the wire; a party that ignores them
+ * produces perfectly valid States and then gets closed against on a stale one.
+ *
+ * RECORD-THEN-SEND, never send-then-record. §4.2 is the whole reason this module holds a store
+ * rather than a variable. The dangerous interleaving is: sign, transmit, crash, restart, and sign
+ * a DIFFERENT State at the same seq because the first was never written down. The counterparty
+ * now holds two signed States at one seq and picks whichever pays it more, which is §4.1's
+ * violation arriving through the back door. So the write happens before the signature is returned
+ * to the caller, and a store that throws means no signature was ever handed out.
+ */
+import { digestHex, signState } from './encoding.js';
+export class SignerObligationError extends Error {
+}
+export const emptyRecord = (sessionId) => ({ sessionId, highestSeq: -1, lastStateDigest: null });
+/**
+ * Sign a State, or refuse. The refusals ARE the feature.
+ *
+ * §4.4's restart rule needs no separate code path: the record is loaded from the store on every
+ * call, so a fresh process behaves exactly like a long-running one. A restart that forgets is a
+ * store that lost data, not a signer that skipped a step.
+ */
+export function signStateWithObligations(store, state, privateKeyHex) {
+    const record = store.load(state.sessionId) ?? emptyRecord(state.sessionId);
+    // §4.1 and §4.4: at most one State per seq, and never at or below the highest already signed.
+    if (state.seq <= record.highestSeq) {
+        throw new SignerObligationError(`refusing to sign seq ${state.seq}: already signed ${record.highestSeq} for this session`);
+    }
+    // §4.3: the chain must be unbroken. A State whose prevState does not match what this party last
+    // agreed to is either a fork or a splice, and signing it endorses a history it never saw.
+    if (state.prevState !== record.lastStateDigest) {
+        throw new SignerObligationError(`refusing to sign seq ${state.seq}: prevState ${state.prevState ?? 'null'} does not chain to ` +
+            `${record.lastStateDigest ?? 'null'}`);
+    }
+    // §4.2: RECORD, then sign, then return. The signature does not escape this function until the
+    // store has accepted the write -- so a throw here means nothing was ever transmitted.
+    store.save({
+        sessionId: state.sessionId,
+        highestSeq: state.seq,
+        lastStateDigest: digestHex(state),
+    });
+    return signState(state, privateKeyHex);
+}
+/** An in-memory store. Fine for tests; a real party needs something that survives a crash. */
+export function memoryStore() {
+    const rows = new Map();
+    return {
+        load: (sessionId) => rows.get(sessionId) ?? null,
+        save: (record) => {
+            rows.set(record.sessionId, { ...record });
+        },
+    };
+}
+//# sourceMappingURL=signer.js.map

package/dist/src/signer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signer.js","sourceRoot":"","sources":["../../src/signer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAqBrD,MAAM,OAAO,qBAAsB,SAAQ,KAAK;CAAG;AAEnD,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,SAAiB,EAAgB,EAAE,CAC7D,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC,CAAC,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAAkB,EAClB,KAAY,EACZ,aAAqB;IAErB,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAE3E,8FAA8F;IAC9F,IAAI,KAAK,CAAC,GAAG,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACnC,MAAM,IAAI,qBAAqB,CAC7B,wBAAwB,KAAK,CAAC,GAAG,oBAAoB,MAAM,CAAC,UAAU,mBAAmB,CAC1F,CAAC;IACJ,CAAC;IAED,gGAAgG;IAChG,0FAA0F;IAC1F,IAAI,KAAK,CAAC,SAAS,KAAK,MAAM,CAAC,eAAe,EAAE,CAAC;QAC/C,MAAM,IAAI,qBAAqB,CAC7B,wBAAwB,KAAK,CAAC,GAAG,eAAe,KAAK,CAAC,SAAS,IAAI,MAAM,qBAAqB;YAC5F,GAAG,MAAM,CAAC,eAAe,IAAI,MAAM,EAAE,CACxC,CAAC;IACJ,CAAC;IAED,8FAA8F;IAC9F,sFAAsF;IACtF,KAAK,CAAC,IAAI,CAAC;QACT,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,UAAU,EAAE,KAAK,CAAC,GAAG;QACrB,eAAe,EAAE,SAAS,CAAC,KAAK,CAAC;KAClC,CAAC,CAAC;IAEH,OAAO,SAAS,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;AACzC,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,WAAW;IACzB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC7C,OAAO;QACL,IAAI,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,IAAI;QAChD,IAAI,EAAE,CAAC,MAAM,EAAE,EAAE;YACf,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;QAC5C,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/src/store.d.ts

@@ -0,0 +1,30 @@
+import type { SignerStore } from './signer.js';
+import type { SessionHistory } from './history.js';
+import type { SessionSnapshot } from './http/provider.js';
+/**
+ * A SignerStore that survives a restart, and a power cut.
+ *
+ * Later records win: the log is a history of what was signed, and §4.4 only ever moves `highestSeq`
+ * upward, so replaying it in order lands on the same state the process held.
+ */
+export declare function fileStore(path: string): SignerStore;
+/** A SessionHistory that survives a restart. SPEC.md §3.1a; see src/history.ts for why it matters. */
+export declare function fileHistory(path: string): SessionHistory;
+/** Durable storage for open sessions, so a restart does not make every buyer start again. */
+export interface SessionStore {
+    load(sessionId: string): SessionSnapshot | null;
+    save(snapshot: SessionSnapshot): void;
+    drop(sessionId: string): void;
+}
+/**
+ * Sessions that survive a restart.
+ *
+ * Weaker guarantees than `fileStore`, deliberately. A signer record must be durable BEFORE a
+ * signature exists, because losing one lets a party sign twice at the same seq; losing a session
+ * costs at most the babel in flight, which the buyer simply reserves again. So this appends
+ * without fsync -- fast enough to write on every message -- and the last few entries may be lost
+ * to a power cut. That is a considered trade, not an oversight: paying for durability here would
+ * put a disk flush on the path of every delivery, in exchange for something nobody loses money to.
+ */
+export declare function fileSessionStore(path: string): SessionStore;
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/store.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAgB,WAAW,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AA+B1D;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAanD;AAED,sGAAsG;AACtG,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAaxD;AAGD,6FAA6F;AAC7F,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IACtC,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAa3D"}

package/dist/src/store.js

@@ -0,0 +1,120 @@
+/**
+ * Durable stores for the two obligations that lose something when a process forgets.
+ *
+ * SPEC.md §4.2 (record-then-send) and §4.4 (the restart rule) are already implemented by
+ * `signer.ts`: it loads from the store on every call, so a fresh process behaves exactly like a
+ * long-running one, and "a restart that forgets is a store that lost data, not a signer that
+ * skipped a step." This is the store that does not lose data. `memoryStore()` is the one that
+ * does, and it is honest about it.
+ *
+ * SPEC.md §3.1a needs the same thing for a different reason: a buyer that forgets which session
+ * identifiers it has seen is unprotected against a provider that waits for it to restart.
+ *
+ * WHY APPEND-ONLY, AND WHY fsync.
+ *
+ *   A signature must not exist unless the record is already durable. Rewriting a whole JSON file
+ *   per save has a window where the old file is gone and the new one is not yet written; a crash
+ *   inside it loses EVERY record, not one. Appending a line cannot lose what came before.
+ *
+ *   Writing without fsync puts the record in the operating system's buffer, not on the disk. The
+ *   process crashing is survivable either way; the machine losing power is not. §4.2 says the
+ *   write happens before the signature is returned, and a buffered write has not happened.
+ *
+ *   A TORN FINAL LINE IS DISCARDED, and that is correct rather than merely convenient: if the
+ *   append did not complete, `save` did not return, so no signature was ever handed out. The
+ *   record describes something that never happened.
+ */
+import { appendFileSync, closeSync, existsSync, fsyncSync, openSync, readFileSync, writeSync } from 'node:fs';
+/** Read a JSONL file, discarding any trailing line that a crash cut in half. */
+function replay(path) {
+    if (!existsSync(path))
+        return [];
+    const rows = [];
+    for (const line of readFileSync(path, 'utf8').split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            rows.push(JSON.parse(line));
+        }
+        catch {
+            // Only the LAST line can legitimately be torn. An unparseable line anywhere else means the
+            // file was damaged by something other than a crash, and replaying past it would silently
+            // resurrect a stale record -- so stop here and keep what was whole.
+            break;
+        }
+    }
+    return rows;
+}
+/** Append one record and put it on the disk before returning. */
+function appendDurable(path, row) {
+    const fd = openSync(path, 'a');
+    try {
+        writeSync(fd, `${JSON.stringify(row)}\n`);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * A SignerStore that survives a restart, and a power cut.
+ *
+ * Later records win: the log is a history of what was signed, and §4.4 only ever moves `highestSeq`
+ * upward, so replaying it in order lands on the same state the process held.
+ */
+export function fileStore(path) {
+    const rows = new Map();
+    for (const r of replay(path))
+        rows.set(r.sessionId, r);
+    return {
+        load: (sessionId) => rows.get(sessionId) ?? null,
+        save: (record) => {
+            // Disk first, memory second. The other order would let an in-process reader see a record
+            // that a crash one instruction later would erase -- which is send-then-record wearing a
+            // different hat.
+            appendDurable(path, record);
+            rows.set(record.sessionId, { ...record });
+        },
+    };
+}
+/** A SessionHistory that survives a restart. SPEC.md §3.1a; see src/history.ts for why it matters. */
+export function fileHistory(path) {
+    const seen = new Set();
+    const key = (provider, sessionId) => `${provider}/${sessionId}`;
+    for (const r of replay(path)) {
+        seen.add(key(r.provider, r.sessionId));
+    }
+    return {
+        seen: (provider, sessionId) => seen.has(key(provider, sessionId)),
+        record: (provider, sessionId) => {
+            appendDurable(path, { provider, sessionId });
+            seen.add(key(provider, sessionId));
+        },
+    };
+}
+/**
+ * Sessions that survive a restart.
+ *
+ * Weaker guarantees than `fileStore`, deliberately. A signer record must be durable BEFORE a
+ * signature exists, because losing one lets a party sign twice at the same seq; losing a session
+ * costs at most the babel in flight, which the buyer simply reserves again. So this appends
+ * without fsync -- fast enough to write on every message -- and the last few entries may be lost
+ * to a power cut. That is a considered trade, not an oversight: paying for durability here would
+ * put a disk flush on the path of every delivery, in exchange for something nobody loses money to.
+ */
+export function fileSessionStore(path) {
+    const rows = new Map();
+    for (const r of replay(path))
+        rows.set(r.id, r.snapshot);
+    const append = (id, snapshot) => {
+        appendFileSync(path, `${JSON.stringify({ id, snapshot })}
+`);
+        rows.set(id, snapshot);
+    };
+    return {
+        load: (sessionId) => rows.get(sessionId) ?? null,
+        save: (snapshot) => append(snapshot.offer.sessionId, snapshot),
+        drop: (sessionId) => append(sessionId, null),
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/src/store.js.map

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

package/dist/src/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The wire messages of SPEC.md §3, as types.
+ *
+ * These are the shapes the covenant measurement pinned. Nothing here should change without
+ * changing §3, because `spec/vectors.ts` and `contracts/metered_session.tests.json` both encode
+ * the same fields and the golden vector is compared byte for byte.
+ */
+/** SPEC.md §3.1. The provider's signed commitment, carried in the HTTP 402 response. */
+export interface Offer {
+    v: 1;
+    scheme: 'metered';
+    network: string;
+    asset: 'KAS';
+    sessionId: string;
+    unit: string;
+    meter: string;
+    unitPriceSompi: number;
+    babelUnits: number;
+    maxBabels: number;
+    toleranceAbs: number;
+    checkpointEvery: number;
+    responseWindowDaa: number;
+    buyerPubkey: string;
+    providerPubkey: string;
+    partiesCommitment: string;
+    sig?: string;
+}
+/** SPEC.md §3.2. The buyer's authorisation for ONE chunk. Never for the session. */
+export interface Reservation {
+    v: 1;
+    sessionId: string;
+    seq: number;
+    units: number;
+    cumulativeUnits: number;
+    cumulativeSompi: number;
+    prevState: string | null;
+    sig?: string;
+}
+/** SPEC.md §3.3. One per party per chunk boundary. */
+export interface Measurement {
+    v: 1;
+    sessionId: string;
+    seq: number;
+    by: 'buyer' | 'provider';
+    units: number;
+    cumulativeUnits: number;
+    contentDigest: string;
+    measurementId: string;
+    sig?: string;
+}
+/**
+ * SPEC.md §3.4. The only object that can settle, and the only one whose signatures cover a byte
+ * concatenation (§3.4.1) rather than canonical JSON.
+ */
+export interface State {
+    v: 1;
+    sessionId: string;
+    seq: number;
+    cumulativeUnits: number;
+    cumulativeSompi: number;
+    prevState: string | null;
+    buyerSig?: string;
+    providerSig?: string;
+}
+/** Why a session stopped. SPEC.md §5: "the only remedy for disagreement is to stop." */
+export type HaltReason = 'signature' | 'sequence' | 'content-digest' | 'tolerance-babel' | 'tolerance-cumulative' | 'bias';
+export interface Halt {
+    ok: false;
+    reason: HaltReason;
+    detail: string;
+}
+export interface Reconciled {
+    ok: true;
+    /** Rule 6: the LOWER of the two counts, which is what gets billed. */
+    billedUnits: number;
+    billedCumulativeUnits: number;
+    /** SPEC.md §5.1: providerUnits − buyerUnits, the quantity the bias detector consumes. */
+    residual: number;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,wFAAwF;AACxF,MAAM,WAAW,KAAK;IACpB,CAAC,EAAE,CAAC,CAAC;IACL,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,oFAAoF;AACpF,MAAM,WAAW,WAAW;IAC1B,CAAC,EAAE,CAAC,CAAC;IACL,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,sDAAsD;AACtD,MAAM,WAAW,WAAW;IAC1B,CAAC,EAAE,CAAC,CAAC;IACL,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,OAAO,GAAG,UAAU,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,WAAW,KAAK;IACpB,CAAC,EAAE,CAAC,CAAC;IACL,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wFAAwF;AACxF,MAAM,MAAM,UAAU,GAClB,WAAW,GACX,UAAU,GACV,gBAAgB,GAChB,iBAAiB,GACjB,sBAAsB,GACtB,MAAM,CAAC;AAEX,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,IAAI,CAAC;IACT,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,yFAAyF;IACzF,QAAQ,EAAE,MAAM,CAAC;CAClB"}

package/dist/src/types.js

@@ -0,0 +1,9 @@
+/**
+ * The wire messages of SPEC.md §3, as types.
+ *
+ * These are the shapes the covenant measurement pinned. Nothing here should change without
+ * changing §3, because `spec/vectors.ts` and `contracts/metered_session.tests.json` both encode
+ * the same fields and the golden vector is compared byte for byte.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/tools/anchor-cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=anchor-cli.d.ts.map

package/dist/tools/anchor-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchor-cli.d.ts","sourceRoot":"","sources":["../../tools/anchor-cli.ts"],"names":[],"mappings":""}

package/dist/tools/anchor-cli.js

@@ -0,0 +1,101 @@
+/**
+ * `npm run anchor -- <command>` -- set up and exercise the checkpoint anchor on testnet.
+ *
+ *   address   generate the anchor key if there is none, and show where to fund it
+ *   balance   what the anchor key can currently pay for
+ *   test      anchor one digest for real, then read it back off the chain and verify it
+ *
+ * TESTNET ONLY, and the network is not a flag by accident. Nothing in this project has any
+ * business writing to mainnet, and a default that could be overridden by a typo is the kind of
+ * thing that only has to be wrong once.
+ */
+import { randomBytes } from 'node:crypto';
+import { blake3Hex } from '../src/encoding.js';
+import { loadAnchorKey, saveAnchorKey, anchorAddress, KEY_FILE, loadSdk } from './kaspa.js';
+import { submitAnchor, ANCHOR_FEE_SOMPI, currentTip, readAnchoredPayload } from './anchor.js';
+const NETWORK = 'testnet-10';
+/** Existing key, or a fresh one. Generating is safe: an unfunded key holds nothing to lose. */
+function keyOrCreate() {
+    const existing = loadAnchorKey();
+    if (existing)
+        return { key: existing, created: false };
+    const key = randomBytes(32).toString('hex');
+    saveAnchorKey(key);
+    return { key, created: true };
+}
+async function utxoTotal(address) {
+    const sdk = await loadSdk();
+    const rpc = new sdk.RpcClient({
+        resolver: new sdk.Resolver(),
+        encoding: sdk.Encoding.Borsh,
+        networkId: new sdk.NetworkId(NETWORK),
+    });
+    await rpc.connect();
+    try {
+        const { entries } = await rpc.getUtxosByAddresses([address]);
+        return entries.reduce((sum, e) => sum + e.amount, 0n);
+    }
+    finally {
+        await rpc.disconnect().catch(() => undefined);
+    }
+}
+async function showAddress() {
+    const { key, created } = keyOrCreate();
+    const address = await anchorAddress(key, NETWORK);
+    console.log(`\n  ${created ? 'Generated a new anchor key' : 'Using the existing anchor key'}`);
+    console.log(`  stored at ${KEY_FILE} (outside the repository, never printed)\n`);
+    console.log(`  network  ${NETWORK}`);
+    console.log(`  address  ${address}\n`);
+    console.log('  Fund it from a testnet-10 faucet. One anchor costs 200,000 sompi (0.002 KAS),');
+    console.log('  so even a small faucet drip covers hundreds of checkpoints.\n');
+}
+async function showBalance() {
+    const key = loadAnchorKey();
+    if (!key)
+        return void console.log('\n  No anchor key yet. Run: npm run anchor -- address\n');
+    const address = await anchorAddress(key, NETWORK);
+    const total = await utxoTotal(address);
+    const anchors = total / ANCHOR_FEE_SOMPI;
+    console.log(`\n  address  ${address}`);
+    console.log(`  balance  ${total} sompi  (${Number(total) / 1e8} KAS)`);
+    console.log(`  buys     ${anchors} anchor${anchors === 1n ? '' : 's'}\n`);
+    if (total === 0n)
+        console.log('  Unfunded. Send testnet-10 coins to the address above.\n');
+}
+async function testAnchor() {
+    const key = loadAnchorKey();
+    if (!key)
+        return void console.log('\n  No anchor key yet. Run: npm run anchor -- address\n');
+    const cfg = { network: NETWORK, privateKeyHex: key };
+    const digest = blake3Hex(`metered/anchor-test/${Date.now()}`);
+    // Captured BEFORE submitting, or the forward walk could start past our own block.
+    const from = await currentTip(cfg);
+    console.log(`\n  anchoring ${digest}`);
+    const txid = await submitAnchor(cfg, digest);
+    console.log(`  accepted  ${txid}`);
+    console.log('  reading it back off the chain -- acceptance is not proof...');
+    const payload = await readAnchoredPayload(cfg, txid, from);
+    const stored = payload.toLowerCase();
+    console.log(`  payload   ${stored || '(EMPTY)'}`);
+    if (stored !== digest) {
+        throw new Error(`the chain stored ${stored || 'nothing'}, not the digest -- the anchor is worthless`);
+    }
+    console.log('  VERIFIED  the chain stored exactly the digest that was anchored');
+    console.log(`  explorer  https://explorer-tn10.kaspa.org/txs/${txid}\n`);
+}
+const COMMANDS = {
+    address: showAddress,
+    balance: showBalance,
+    test: testAnchor,
+};
+const command = process.argv[2] ?? 'address';
+const run = COMMANDS[command];
+if (!run) {
+    console.error(`unknown command '${command}'. Try: ${Object.keys(COMMANDS).join(', ')}`);
+    process.exit(1);
+}
+run().catch((err) => {
+    console.error(`\n  ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=anchor-cli.js.map

package/dist/tools/anchor-cli.js.map

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

package/dist/tools/anchor.d.ts

@@ -0,0 +1,68 @@
+/**
+ * A real Kaspa anchor for SPEC.md §8 checkpoints -- the `Anchor` that src/checkpoint.ts takes.
+ *
+ * Every hard-won detail below came from kaspa-depin's proven implementation, and each one cost a
+ * live run to learn. They are restated rather than imported because that repository is a separate
+ * project and this one must build without it; but they are its findings, not new ones.
+ *
+ *   BUILD THE TRANSACTION BY HAND. `createTransactions` hands back a PendingTransaction whose
+ *   `.transaction` is a COPY -- setting subnetworkId and payload on it mutates a throwaway, the
+ *   chain receives neither, and nothing reports a problem. A first attempt confirmed happily and
+ *   landed a plain payment with an empty payload. `createTransaction` returns a Transaction we
+ *   own, so what is signed is what was built.
+ *
+ *   A VERSION 1 TRANSACTION BUDGETS ITS INPUTS. Toccata replaced sigOpCount with an explicit
+ *   computeBudget, and a node refuses a v1 transaction still carrying the old field.
+ *
+ * WHAT THIS DELIBERATELY DOES NOT DO: wait. §8 requires checkpointing to be non-blocking because
+ * Study B measured p90 confirmation at 1,879 ms. This resolves once the node ACCEPTS the
+ * transaction, not once it is mined -- src/checkpoint.ts already treats the record as pending and
+ * never awaits it. Proving a checkpoint later means fetching the block, which is a verifier's job
+ * and needs nothing from here.
+ */
+import { type Network } from './kaspa.js';
+import type { Anchor } from '../src/checkpoint.js';
+/** KIP-21 subnetwork. Anchors go in their own lane so the stream is separable later. */
+export declare const ANCHOR_LANE = "00a0c40100000000000000000000000000000000";
+/**
+ * Measured, not guessed, and the first three guesses were wrong. At budget 10 the mass is 1,666
+ * and the node requires 166,600 sompi; this pays 200,000 for headroom -- about 0.002 KAS, the
+ * figure SPEC.md §0.1 quotes from Study B.
+ */
+export declare const ANCHOR_FEE_SOMPI = 200000n;
+export interface AnchorConfig {
+    network: Network;
+    privateKeyHex: string;
+    /** ws(s):// node URL. Omitted, the public Resolver pool is used -- which speaks borsh only. */
+    url?: string;
+}
+/**
+ * Put one digest on chain. Resolves with the transaction id once the node has accepted it.
+ *
+ * The payload is the raw 32 digest bytes. There is no framing: a checkpoint proves a State existed
+ * before a block, and the State's digest is the whole claim.
+ */
+export declare function submitAnchor(cfg: AnchorConfig, digest: string): Promise<string>;
+/** A tip to start a forward walk from. Must be captured BEFORE submitting. */
+export declare function currentTip(cfg: AnchorConfig): Promise<string>;
+/**
+ * Find an anchor in a block and return the payload the chain actually stored.
+ *
+ * ACCEPTANCE IS NOT PROOF, and this exists because of that. kaspa-depin's first live anchor
+ * confirmed perfectly and landed a plain payment with an EMPTY payload, because the payload had
+ * been set on a copy. Nothing anywhere reported a problem. The only way to know a checkpoint is
+ * real is to read it back off the chain.
+ *
+ * SCANNING TIPS DOES NOT WORK. At ten blocks a second a block stops being a tip within about a
+ * second, so polling tipHashes misses the block nearly every time and reports a timeout that
+ * reads like a failure. Walking forward from a hash captured before submission is the only
+ * approach that does not race the DAG.
+ */
+export declare function readAnchoredPayload(cfg: AnchorConfig, txid: string, fromHash: string, timeoutMs?: number): Promise<string>;
+/**
+ * The `Anchor` src/checkpoint.ts consumes. Note what it returns: a promise the session never
+ * awaits. A failure marks the checkpoint record and stops there, because §8 is explicit that
+ * checkpoints are evidence rather than safety -- losing one costs provability, never funds.
+ */
+export declare function kaspaAnchor(cfg: AnchorConfig): Anchor;
+//# sourceMappingURL=anchor.d.ts.map