metered-protocol 1.0.0

package/dist/tools/session-chain.js

@@ -0,0 +1,113 @@
+/**
+ * The three chain operations a metered session needs, as functions rather than as a script.
+ *
+ * FUND, SETTLE, CLOSE. Until now this sequence existed only inside `tools/demo.ts`, wound through
+ * its console output -- which meant that anything else wanting to settle a session had to copy it.
+ * The second program to want that was the first real product built on this protocol, and copying
+ * would have produced two versions of the one sequence that moves money.
+ *
+ * SPEC.md 7. `settle` posts a doubly-signed claim and pays no one; the response window then
+ * restarts. `expire` pays out after the window: the claim to the provider, the remainder to the
+ * buyer, everything to the buyer if no claim was ever posted. The two-phase shape is not an
+ * implementation detail -- it is what makes the claim superseding a later one work as a guard
+ * rather than as a branch.
+ *
+ * WHAT THIS STILL NEEDS: `silverc`, because the redeem script embeds the session's own identity as
+ * constructor constants and so must be compiled per session. That is the official released
+ * compiler and an ordinary dependency. It no longer needs the patched cli-debugger -- see
+ * tools/sigscript.ts, which was the difference between one machine being able to settle and
+ * anybody being able to.
+ */
+import { compileWithState, covenantAddress } from './covenant.js';
+import { awaitUtxo, withState, buildExpire, awaitWindow, closeOutputs, x } from './live-steps.js';
+import { signatureScript, settleArgs } from './sigscript.js';
+/** Fees are compiled into the covenant's allowance, so they are constants rather than estimates. */
+export const SETTLE_FEE = 360000n;
+export const CLOSE_FEE = 400000n;
+export const FUND_FEE = 250000n;
+/**
+ * Compile this session's covenant and derive the address that holds its funds.
+ *
+ * The constructor constants come from the Offer the provider actually issued, so the address is
+ * derived from the agreement rather than the agreement being fitted to an address. A covenant
+ * compiled for a different session has a different address and cannot be spent by this one.
+ */
+export async function openCovenant(dir, offer, window, network) {
+    const built = compileWithState(dir, {
+        parties: offer.partiesCommitment, sessionId: offer.sessionId, window, seq: -1, sompi: 0,
+    });
+    const address = await covenantAddress(built.hex, network);
+    return { ...built, address, window };
+}
+/** Pay into the covenant from an ordinary wallet, and wait for the UTXO to appear. */
+export async function fundCovenant(rpc, sdk, opened, funderSk, amount, network) {
+    const priv = new sdk.PrivateKey(funderSk);
+    const from = priv.toKeypair().toAddress(new sdk.NetworkId(network)).toString();
+    const { entries } = await rpc.getUtxosByAddresses([from]);
+    if (entries.length === 0)
+        throw new Error(`nothing to spend at ${from}`);
+    const src = entries.reduce((a, b) => (b.amount > a.amount ? b : a));
+    if (src.amount < amount + FUND_FEE)
+        throw new Error(`largest UTXO at ${from} cannot cover ${amount}`);
+    const fund = sdk.createTransaction([src], [{ address: opened.address, amount }, { address: from, amount: src.amount - amount - FUND_FEE }], 0n, undefined, 0);
+    fund.version = 1;
+    fund.gas = 0n;
+    for (const i of fund.inputs) {
+        i.sigOpCount = 0;
+        i.computeBudget = 10;
+    }
+    fund.finalize();
+    await rpc.submitTransaction({ transaction: sdk.signTransaction(fund, [priv], true), allowOrphan: false });
+    const utxo = await awaitUtxo(rpc, opened.address, amount);
+    if (!utxo)
+        throw new Error('the covenant UTXO never appeared');
+    return utxo;
+}
+/**
+ * Post the doubly-signed final State to the covenant.
+ *
+ * `settle` PAYS NO ONE. The single output hands the balance straight back to the same covenant,
+ * now carrying `(seq, cumulativeSompi)` as its state, and the response window restarts. A later
+ * State with a strictly higher seq supersedes this one by the same route.
+ */
+export async function settleClaim(rpc, sdk, opened, utxo, state, parties, network) {
+    const tag = opened.entries.settle?.dispatch_tag;
+    if (!tag)
+        throw new Error('the compiled covenant has no `settle` entry');
+    const redeem = withState(opened.hex, state.seq, state.cumulativeSompi);
+    const address = await covenantAddress(redeem, network);
+    const amount = utxo.amount - SETTLE_FEE;
+    const spend = sdk.createTransaction([utxo], [{ address, amount }], 0n, undefined, 0);
+    spend.version = 1;
+    spend.gas = 0n;
+    spend.inputs[0].sigOpCount = 0;
+    // Sized to the COSTLIEST entry, not this one: `expire` does two signature checks. Finding E.
+    spend.inputs[0].computeBudget = 21;
+    spend.inputs[0].signatureScript = signatureScript(sdk, settleArgs(state, parties.buyerPubkey, parties.providerPubkey, parties.buyerSig, parties.providerSig), tag, opened.hex);
+    spend.finalize();
+    const txid = (await rpc.submitTransaction({ transaction: spend, allowOrphan: false })).transactionId;
+    const posted = await awaitUtxo(rpc, address, amount);
+    if (!posted)
+        throw new Error('the claim never posted');
+    return { txid, posted, redeem, address };
+}
+/**
+ * Wait out the response window and pay everyone.
+ *
+ * The output SHAPE is computed rather than assumed. The covenant accepts exactly three and refuses
+ * everything else, and guessing gets "script ran, but verification failed" -- which says nothing
+ * about which rule was broken. Below the KIP-9 floor a payout cannot be its own output at all, so
+ * it folds into the other party's.
+ */
+export async function closeCovenant(rpc, sdk, opened, claim, who, owedSompi) {
+    await awaitWindow(rpc, opened.window);
+    const outputs = closeOutputs(claim.posted.amount, BigInt(owedSompi), CLOSE_FEE, who.buyerAddress, who.providerAddress);
+    const close = buildExpire(sdk, {
+        buyerPk: who.buyerPubkey, providerPk: who.providerPubkey, signerSk: who.signerSk,
+        redeem: claim.redeem, tag: opened.entries.expire?.dispatch_tag ?? '',
+    }, claim.posted, outputs, opened.window);
+    const txid = (await rpc.submitTransaction({ transaction: close, allowOrphan: false })).transactionId;
+    return { txid, outputs };
+}
+export { x };
+//# sourceMappingURL=session-chain.js.map

package/dist/tools/session-chain.js.map

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

package/dist/tools/sighash.d.ts

@@ -0,0 +1,9 @@
+export declare const DEBUGGER: string;
+/**
+ * Run one test case and return the sighash the VM computed for the active input. The case is
+ * expected to FAIL at the signature check -- that is fine and expected, we only want the hash.
+ */
+export declare function sighashFor(contractPath: string, testCase: unknown): string;
+/** BIP340 over the sighash, plus the type byte -- the 65 bytes a Kaspa `sig` parameter wants. */
+export declare function signSighash(sighashHex: string, privateKeyHex: string): string;
+//# sourceMappingURL=sighash.d.ts.map

package/dist/tools/sighash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sighash.d.ts","sourceRoot":"","sources":["../../tools/sighash.ts"],"names":[],"mappings":"AAgCA,eAAO,MAAM,QAAQ,QAE4G,CAAC;AAElI;;;GAGG;AACH,wBAAgB,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,CAyB1E;AAED,iGAAiG;AACjG,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAM7E"}

package/dist/tools/sighash.js

@@ -0,0 +1,68 @@
+/**
+ * The signing harness for covenant entries that use `checkSig`.
+ *
+ * `checkMsgSig` verifies a signature over supplied data, so `settle` can be signed offline -- the
+ * message is just the settlement digest. `checkSig` verifies a signature over the SPENDING
+ * TRANSACTION, and the sighash depends on the whole transaction the simulator builds: outpoints,
+ * amounts, script pubkeys, sequences, sigop counts. There is no way to compute it from outside
+ * without reimplementing Kaspa's consensus hashing and matching the simulator byte for byte.
+ *
+ * So we ask it. `SILVERSCRIPT_PRINT_SIGHASH=1` makes the debugger print the sighash it computed,
+ * we sign that, and write the signature back into the test case. Two passes, no reimplementation.
+ *
+ * WHY THIS IS NOT CIRCULAR. Kaspa's sighash covers the UTXO's script pubkey, not the spending
+ * input's signature script -- the signature is not an input to the hash that the signature signs.
+ * So a placeholder signature in pass one yields exactly the sighash that the real signature in
+ * pass two must cover. If that ever stops being true, every expire test breaks loudly rather than
+ * silently, because the VM verifies for real.
+ *
+ * THE DEBUGGER IS PATCHED LOCALLY to print it, in the v1.0.0 worktree under ~/.metered/. That
+ * patch is four lines behind an environment variable and is NOT upstream; a fresh checkout will
+ * not have it. `npm run contracts:gen` says so if the sighash never appears.
+ */
+import { spawnSync } from 'node:child_process';
+import { writeFileSync, mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { schnorr } from '@noble/curves/secp256k1';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
+/** Kaspa's SIG_HASH_ALL. A `sig` is 64 schnorr bytes plus this one type byte -- 65 in total. */
+const SIG_HASH_ALL = 0x01;
+export const DEBUGGER = process.env.SILVERSCRIPT_DEBUGGER ??
+    join(process.env.USERPROFILE ?? process.env.HOME ?? '', '.metered', 'silverscript-v1', 'target', 'release', 'cli-debugger.exe');
+/**
+ * Run one test case and return the sighash the VM computed for the active input. The case is
+ * expected to FAIL at the signature check -- that is fine and expected, we only want the hash.
+ */
+export function sighashFor(contractPath, testCase) {
+    const dir = mkdtempSync(join(tmpdir(), 'metered-sighash-'));
+    const file = join(dir, 'one.tests.json');
+    const name = testCase.name;
+    writeFileSync(file, JSON.stringify({ tests: [testCase] }));
+    // `--run`, not `--run-all`: run-all re-spawns itself per case and swallows the child's stderr
+    // when the case passes, which is exactly when we still need the hash.
+    const run = spawnSync(DEBUGGER, [contractPath, '--run', '--test-file', file, '--test-name', name], {
+        encoding: 'utf8',
+        env: { ...process.env, SILVERSCRIPT_PRINT_SIGHASH: '1' },
+    });
+    const out = `${run.stdout ?? ''}${run.stderr ?? ''}`;
+    const found = out.match(/SIGHASH ([0-9a-f]{64})/);
+    if (!found) {
+        throw new Error('the debugger printed no sighash.\n\n' +
+            `  tried: ${DEBUGGER}\n\n` +
+            'That binary must be built from the v1.0.0 worktree WITH the local sighash patch\n' +
+            '(four lines in debugger/cli/src/main.rs, behind SILVERSCRIPT_PRINT_SIGHASH).\n' +
+            'A stock silverscript checkout will not print it. See tools/sighash.ts.\n\n' +
+            `${out.split('\n').slice(-6).join('\n')}`);
+    }
+    return found[1];
+}
+/** BIP340 over the sighash, plus the type byte -- the 65 bytes a Kaspa `sig` parameter wants. */
+export function signSighash(sighashHex, privateKeyHex) {
+    const raw = schnorr.sign(hexToBytes(sighashHex), hexToBytes(privateKeyHex));
+    const withType = new Uint8Array(65);
+    withType.set(raw, 0);
+    withType[64] = SIG_HASH_ALL;
+    return bytesToHex(withType);
+}
+//# sourceMappingURL=sighash.js.map

package/dist/tools/sighash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sighash.js","sourceRoot":"","sources":["../../tools/sighash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAE7D,gGAAgG;AAChG,MAAM,YAAY,GAAG,IAAI,CAAC;AAE1B,MAAM,CAAC,MAAM,QAAQ,GACnB,OAAO,CAAC,GAAG,CAAC,qBAAqB;IACjC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,EAAE,UAAU,EAAE,iBAAiB,EAAE,QAAQ,EAAE,SAAS,EAAE,kBAAkB,CAAC,CAAC;AAElI;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,YAAoB,EAAE,QAAiB;IAChE,MAAM,GAAG,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC;IACzC,MAAM,IAAI,GAAI,QAA6B,CAAC,IAAI,CAAC;IACjD,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;IAE3D,8FAA8F;IAC9F,sEAAsE;IACtE,MAAM,GAAG,GAAG,SAAS,CAAC,QAAQ,EAAE,CAAC,YAAY,EAAE,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE;QACjG,QAAQ,EAAE,MAAM;QAChB,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,0BAA0B,EAAE,GAAG,EAAE;KACzD,CAAC,CAAC;IACH,MAAM,GAAG,GAAG,GAAG,GAAG,CAAC,MAAM,IAAI,EAAE,GAAG,GAAG,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;IACrD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAClD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,sCAAsC;YACpC,YAAY,QAAQ,MAAM;YAC1B,mFAAmF;YACnF,gFAAgF;YAChF,4EAA4E;YAC5E,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC5C,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC,CAAC,CAAW,CAAC;AAC5B,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,WAAW,CAAC,UAAkB,EAAE,aAAqB;IACnE,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC;IAC5E,MAAM,QAAQ,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC;IACpC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACrB,QAAQ,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC;IAC5B,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC;AAC9B,CAAC"}

package/dist/tools/sigscript-check.d.ts

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

package/dist/tools/sigscript-check.d.ts.map

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

package/dist/tools/sigscript-check.js

@@ -0,0 +1,113 @@
+/**
+ * `npx tsx tools/sigscript-check.ts` -- prove the signature script can be built without the simulator.
+ *
+ * tools/sigscript.ts claims it knows how a SilverScript signature script is laid out. This is
+ * where that claim is tested rather than believed: every case below is built BOTH ways -- once by
+ * the patched cli-debugger that every live spend has used until now, and once in TypeScript from
+ * nothing but the compiled artifact -- and the two byte strings must be identical.
+ *
+ * If they are, settlement stops requiring a patched debugger and starts requiring only the Kaspa
+ * SDK, which is the difference between a protocol one machine can settle and a protocol anyone
+ * can. If they are not, the description in sigscript.ts is wrong and belongs nowhere near money.
+ */
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { partiesCommitment, publicKeyHex, signState } from '../src/encoding.js';
+import { compileWithState } from './covenant.js';
+import { preflightSigscript, withState, x } from './live-steps.js';
+import { signatureScript, actionScript, encodeNumber, settleArgs } from './sigscript.js';
+import { loadSdk } from './kaspa.js';
+const dir = mkdtempSync(join(tmpdir(), 'metered-sigscript-'));
+const BUYER_SK = '11'.repeat(32);
+const PROVIDER_SK = '22'.repeat(32);
+const SESSION = 'a1'.repeat(16);
+const PARTIES = partiesCommitment(publicKeyHex(BUYER_SK), publicKeyHex(PROVIDER_SK));
+const WINDOW = 2;
+/** Deliberately spread across the number encoding's awkward places, not three happy cases. */
+const CASES = [
+    { name: 'seq 0, the first claim', seq: 0, units: 550, sompi: 1996500, prevState: null },
+    { name: 'a mid-session claim', seq: 3, units: 2199, sompi: 7982370, prevState: 'b2'.repeat(32) },
+    { name: 'values that fill the sign bit', seq: 1, units: 128, sompi: 32768, prevState: 'cd'.repeat(32) },
+    { name: 'a large sompi total', seq: 7, units: 1000000, sompi: 47600000, prevState: 'ef'.repeat(32) },
+];
+function argsFor(c) {
+    const state = {
+        v: 1, sessionId: SESSION, seq: c.seq, cumulativeUnits: c.units,
+        cumulativeSompi: c.sompi, prevState: c.prevState,
+    };
+    return settleArgs(state, publicKeyHex(BUYER_SK), publicKeyHex(PROVIDER_SK), signState(state, BUYER_SK), signState(state, PROVIDER_SK));
+}
+function numberVectors() {
+    // The encoding these scripts hang on, checked against Kaspa script's own rules before anything
+    // larger is compared. Zero is the empty push; 0x80 needs a byte added so the sign bit is free.
+    const vectors = [
+        [0, ''], [1, '01'], [127, '7f'], [128, '8000'], [255, 'ff00'], [256, '0001'],
+        [-1, '81'], [-127, 'ff'], [-128, '8080'], [32768, '008000'], [1996500, 'd4761e'],
+    ];
+    for (const [n, want] of vectors) {
+        const got = Buffer.from(encodeNumber(n)).toString('hex');
+        if (got !== want)
+            throw new Error(`encodeNumber(${n}) = ${got}, expected ${want}`);
+    }
+    console.log(`  number encoding    ${vectors.length} vectors agree`);
+}
+async function main() {
+    numberVectors();
+    const sdk = await loadSdk();
+    let checked = 0;
+    for (const c of CASES) {
+        const ctor = [x(PARTIES), x(SESSION), WINDOW, -1, 0];
+        const built = compileWithState(dir, {
+            parties: PARTIES, sessionId: SESSION, window: WINDOW, seq: -1, sompi: 0,
+        });
+        const tag = built.entries.settle?.dispatch_tag;
+        if (!tag)
+            throw new Error('the compiled covenant has no `settle` entry');
+        const args = argsFor(c);
+        const outRedeem = withState(built.hex, c.seq, c.sompi);
+        // THE REFERENCE: the patched debugger, which is what every live spend has used.
+        const fromDebugger = preflightSigscript({
+            name: `sigscript ${c.name}`,
+            function: 'settle',
+            constructor_args: ctor,
+            args,
+            expect: 'pass',
+            tx: {
+                active_input_index: 0,
+                inputs: [{ utxo_value: 50_000_000, constructor_args: ctor }],
+                outputs: [{
+                        value: 49_640_000, constructor_args: ctor,
+                        state: { pendingSeq: c.seq, pendingSompi: c.sompi },
+                    }],
+            },
+        }, dir);
+        // THE CANDIDATE: built here, from the compiled artifact and nothing else. Compared as the
+        // WHOLE script -- action half plus redeem -- because that is what gets broadcast; comparing
+        // only the half this file constructs would leave the join untested.
+        const redeem = new sdk.ScriptBuilder();
+        redeem.addData(built.hex);
+        const reference = fromDebugger + redeem.toString();
+        const mine = signatureScript(sdk, args, tag, built.hex);
+        if (actionScript(sdk, args, tag) !== fromDebugger) {
+            console.log(`
+  ACTION HALF MISMATCH on "${c.name}"`);
+            process.exit(1);
+        }
+        if (mine !== reference) {
+            console.log(`\n  MISMATCH on "${c.name}"`);
+            console.log(`    debugger  ${reference.slice(0, 120)}...  (${reference.length / 2} bytes)`);
+            console.log(`    built     ${mine.slice(0, 120)}...  (${mine.length / 2} bytes)`);
+            process.exit(1);
+        }
+        console.log(`  ${c.name.padEnd(30)} ${mine.length / 2} bytes, identical`);
+        checked += 1;
+        void outRedeem;
+    }
+    console.log(`\n  ${checked} signature scripts built without the simulator, byte for byte.\n`);
+}
+main().catch((err) => {
+    console.error(`\n  ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=sigscript-check.js.map

package/dist/tools/sigscript-check.js.map

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

package/dist/tools/sigscript.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Build a covenant signature script WITHOUT the simulator.
+ *
+ * THIS FILE EXISTS BECAUSE SETTLEMENT WAS UNDEPLOYABLE. Every live spend this project has ever
+ * made obtained its signature script by running the SilverScript cli-debugger and reading the
+ * bytes it printed -- behind an environment variable added by a LOCAL, un-upstreamed patch. That
+ * worked, and it meant a metered session could be settled on exactly one machine in the world.
+ * A protocol whose enforcement half needs a patched debugger is not adoptable, however carefully
+ * the rest of it is specified.
+ *
+ * A SilverScript signature script is not mysterious, which is what makes this fixable. It is:
+ *
+ *     <arg_0> <arg_1> ... <arg_n> <dispatch_tag> <redeem_script>
+ *
+ * -- the entry's arguments pushed in DECLARATION order, then the tag that selects the entry, then
+ * the redeem script itself. The debugger's `combine_action_and_redeem` does the same thing; it was
+ * simply the only thing doing it.
+ *
+ * The order was established by comparison, not by reading: the first attempt pushed the arguments
+ * reversed, on the reasoning that the first one should end up on top of the stack. It produced a
+ * script of exactly the right length and entirely the wrong bytes, which is a good argument for
+ * checking against the reference rather than against one's own reasoning.
+ *
+ * Nothing here is trusted on the strength of that description. tools/sigscript-check.ts builds
+ * every case both ways and compares the bytes, and the two must agree exactly.
+ */
+import type { Any } from './live-steps.js';
+/** A covenant argument: a hex blob (`0x...`) or a whole number. */
+export type Arg = string | number;
+export declare class UnencodableArg extends Error {
+}
+/**
+ * SilverScript numbers are minimally-encoded, little-endian, sign-and-magnitude -- Kaspa script's
+ * own number encoding, not two's complement. Zero is the EMPTY push, which is why it cannot be
+ * written as a single 0x00 byte.
+ */
+export declare function encodeNumber(n: number): Uint8Array;
+/**
+ * The ACTION half: arguments then dispatch tag, with no redeem script appended.
+ *
+ * Kept separate from the redeem half because the caller appends that itself -- the redeem bytes
+ * must physically be present in the input's own signature script, since `validateOutputState`
+ * rebuilds the continuation out of them.
+ */
+export declare function actionScript(sdk: Any, args: Arg[], dispatchTag: string): string;
+/**
+ * The arguments the covenant's `settle` entry takes, in the order it declares them.
+ *
+ * ONE DEFINITION, because the order is load-bearing and there were three copies of it -- the test
+ * generator, the demo and the cross-check each built this list by hand. Three lists that must
+ * agree and are maintained separately are three chances to find out on chain.
+ */
+export declare function settleArgs(state: {
+    seq: number;
+    cumulativeUnits: number;
+    cumulativeSompi: number;
+    prevState: string | null;
+}, buyerPubkey: string, providerPubkey: string, buyerSig: string, providerSig: string): Arg[];
+/** The whole signature script: the action half, then the redeem script it runs against. */
+export declare function signatureScript(sdk: Any, args: Arg[], dispatchTag: string, redeemHex: string): string;
+//# sourceMappingURL=sigscript.d.ts.map

package/dist/tools/sigscript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sigscript.d.ts","sourceRoot":"","sources":["../../tools/sigscript.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAE3C,mEAAmE;AACnE,MAAM,MAAM,GAAG,GAAG,MAAM,GAAG,MAAM,CAAC;AAElC,qBAAa,cAAe,SAAQ,KAAK;CAAG;AAE5C;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU,CAiBlD;AAWD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAK/E;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAClG,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GACjF,GAAG,EAAE,CAMP;AAED,2FAA2F;AAC3F,wBAAgB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAIrG"}

package/dist/tools/sigscript.js

@@ -0,0 +1,70 @@
+export class UnencodableArg extends Error {
+}
+/**
+ * SilverScript numbers are minimally-encoded, little-endian, sign-and-magnitude -- Kaspa script's
+ * own number encoding, not two's complement. Zero is the EMPTY push, which is why it cannot be
+ * written as a single 0x00 byte.
+ */
+export function encodeNumber(n) {
+    if (!Number.isSafeInteger(n))
+        throw new UnencodableArg(`${n} is not a whole number`);
+    if (n === 0)
+        return new Uint8Array(0);
+    const negative = n < 0;
+    let value = Math.abs(n);
+    const out = [];
+    while (value > 0) {
+        out.push(value & 0xff);
+        value = Math.floor(value / 256);
+    }
+    // The top bit doubles as the sign, so a value that already fills it needs one more byte to
+    // carry the sign without changing the magnitude.
+    const top = out[out.length - 1];
+    if (top & 0x80)
+        out.push(negative ? 0x80 : 0x00);
+    else if (negative)
+        out[out.length - 1] = top | 0x80;
+    return Uint8Array.from(out);
+}
+const hexToBytes = (hex) => {
+    const clean = hex.startsWith('0x') ? hex.slice(2) : hex;
+    if (clean.length % 2 !== 0 || /[^0-9a-fA-F]/.test(clean))
+        throw new UnencodableArg(`not hex: ${hex}`);
+    return Uint8Array.from(clean.match(/../g)?.map((b) => parseInt(b, 16)) ?? []);
+};
+const asBytes = (arg) => (typeof arg === 'number' ? encodeNumber(arg) : hexToBytes(arg));
+/**
+ * The ACTION half: arguments then dispatch tag, with no redeem script appended.
+ *
+ * Kept separate from the redeem half because the caller appends that itself -- the redeem bytes
+ * must physically be present in the input's own signature script, since `validateOutputState`
+ * rebuilds the continuation out of them.
+ */
+export function actionScript(sdk, args, dispatchTag) {
+    const builder = new sdk.ScriptBuilder();
+    for (const arg of args)
+        builder.addData(asBytes(arg));
+    builder.addData(hexToBytes(dispatchTag));
+    return builder.toString();
+}
+/**
+ * The arguments the covenant's `settle` entry takes, in the order it declares them.
+ *
+ * ONE DEFINITION, because the order is load-bearing and there were three copies of it -- the test
+ * generator, the demo and the cross-check each built this list by hand. Three lists that must
+ * agree and are maintained separately are three chances to find out on chain.
+ */
+export function settleArgs(state, buyerPubkey, providerPubkey, buyerSig, providerSig) {
+    return [
+        `0x${buyerPubkey}`, `0x${providerPubkey}`, `0x${buyerSig}`, `0x${providerSig}`,
+        state.seq, state.cumulativeUnits, state.cumulativeSompi,
+        `0x${state.prevState ?? '00'.repeat(32)}`,
+    ];
+}
+/** The whole signature script: the action half, then the redeem script it runs against. */
+export function signatureScript(sdk, args, dispatchTag, redeemHex) {
+    const redeem = new sdk.ScriptBuilder();
+    redeem.addData(hexToBytes(redeemHex));
+    return actionScript(sdk, args, dispatchTag) + redeem.toString();
+}
+//# sourceMappingURL=sigscript.js.map

package/dist/tools/sigscript.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sigscript.js","sourceRoot":"","sources":["../../tools/sigscript.ts"],"names":[],"mappings":"AA+BA,MAAM,OAAO,cAAe,SAAQ,KAAK;CAAG;AAE5C;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,CAAS;IACpC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC;QAAE,MAAM,IAAI,cAAc,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC;IACrF,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;IAEtC,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,IAAI,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACxB,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,OAAO,KAAK,GAAG,CAAC,EAAE,CAAC;QACjB,GAAG,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;QACvB,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC;IAClC,CAAC;IACD,2FAA2F;IAC3F,iDAAiD;IACjD,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAW,CAAC;IAC1C,IAAI,GAAG,GAAG,IAAI;QAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;SAC5C,IAAI,QAAQ;QAAE,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,GAAG,GAAG,IAAI,CAAC;IACpD,OAAO,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,GAAW,EAAc,EAAE;IAC7C,MAAM,KAAK,GAAG,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IACxD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,cAAc,CAAC,YAAY,GAAG,EAAE,CAAC,CAAC;IACtG,OAAO,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AAChF,CAAC,CAAC;AAEF,MAAM,OAAO,GAAG,CAAC,GAAQ,EAAc,EAAE,CACvC,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,GAAQ,EAAE,IAAW,EAAE,WAAmB;IACrE,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,aAAa,EAAE,CAAC;IACxC,KAAK,MAAM,GAAG,IAAI,IAAI;QAAE,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IACtD,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC;IACzC,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;AAC5B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CACxB,KAAkG,EAClG,WAAmB,EAAE,cAAsB,EAAE,QAAgB,EAAE,WAAmB;IAElF,OAAO;QACL,KAAK,WAAW,EAAE,EAAE,KAAK,cAAc,EAAE,EAAE,KAAK,QAAQ,EAAE,EAAE,KAAK,WAAW,EAAE;QAC9E,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,eAAe,EAAE,KAAK,CAAC,eAAe;QACvD,KAAK,KAAK,CAAC,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE;KAC1C,CAAC;AACJ,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,eAAe,CAAC,GAAQ,EAAE,IAAW,EAAE,WAAmB,EAAE,SAAiB;IAC3F,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,aAAa,EAAE,CAAC;IACvC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;IACtC,OAAO,YAAY,CAAC,GAAG,EAAE,IAAI,EAAE,WAAW,CAAC,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;AAClE,CAAC"}

package/dist/tools/state-layout.d.ts

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

package/dist/tools/state-layout.d.ts.map

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

package/dist/tools/state-layout.js

@@ -0,0 +1,57 @@
+/**
+ * Where does contract state actually live in the bytecode?
+ *
+ * `settle` hands the funds back to the SAME covenant with `(pendingSeq, pendingSompi)` updated,
+ * so a real spend has to derive the OUTPUT address -- which means knowing exactly which bytes
+ * change and how they are encoded. The artifact reports a `state_span`, but a span is a claim.
+ * This compiles the contract twice with different state and diffs the result, which is the same
+ * measure-do-not-reason discipline every parameter in SPEC.md 0.1 came from.
+ */
+import { execFileSync } from 'node:child_process';
+import { writeFileSync, readFileSync, mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { SILVERC, compileWithState } from './covenant.js';
+import { profileFromArgv } from './covenant-profile.js';
+import { withState } from './live-steps.js';
+// `npm run state-layout -- --profile ag` measures the Argent port instead. Its span is larger
+// because Argent has no per-instance immutable parameter: parties, session_id and window are
+// state there, so a continuation re-emits all five fields rather than two.
+const PROFILE = profileFromArgv();
+const dir = mkdtempSync(join(tmpdir(), 'metered-layout-'));
+function bytecodeFor(seq, sompi) {
+    const out = compileWithState(dir, { parties: '11'.repeat(32), sessionId: '22'.repeat(16), window: 10, seq, sompi }, PROFILE.contract);
+    return out;
+}
+const a = bytecodeFor(-1, 0);
+const b = bytecodeFor(7, 123456);
+console.log(`profile      ${PROFILE.key}  ${PROFILE.contract}`);
+console.log(`silverc      ${SILVERC}`);
+console.log(`length       ${a.hex.length / 2} vs ${b.hex.length / 2} bytes`);
+console.log(`state_span   offset ${a.span.offset}, len ${a.span.len}`);
+console.log('\ndiffering bytes:');
+for (let i = 0; i < Math.min(a.hex.length, b.hex.length); i += 2) {
+    const x = a.hex.slice(i, i + 2);
+    const y = b.hex.slice(i, i + 2);
+    if (x !== y)
+        console.log(`  byte ${String(i / 2).padStart(4)}   ${x} -> ${y}`);
+}
+console.log(`\nspan bytes A  ${a.hex.slice(a.span.offset * 2, (a.span.offset + a.span.len) * 2)}`);
+console.log(`span bytes B  ${b.hex.slice(b.span.offset * 2, (b.span.offset + b.span.len) * 2)}`);
+console.log(`\nhead A        ${a.hex.slice(0, 48)}`);
+console.log(`head B        ${b.hex.slice(0, 48)}`);
+// THE SPAN IS A CLAIM THE COMPILER MAKES. This is the check that it is true: splice B's state
+// into A by hand and demand the result equal a real compile of B, byte for byte. If the layout
+// were anything but "the mutable pair sits at the END of the span", it fails here rather than on
+// chain, where the symptom is a session nobody can spend.
+const spliced = withState(a.hex, 7, 123456, a.span.offset + a.span.len);
+console.log(`\nsplice check  ${spliced === b.hex ? 'IDENTICAL to a real compile' : 'DIFFERS from a real compile'}`);
+if (spliced !== b.hex) {
+    console.log(`  spliced     ${spliced}`);
+    console.log(`  compiled    ${b.hex}`);
+    process.exit(1);
+}
+void execFileSync;
+void writeFileSync;
+void readFileSync;
+//# sourceMappingURL=state-layout.js.map

package/dist/tools/state-layout.js.map

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

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "metered-protocol",
+  "version": "1.0.0",
+  "description": "A chunked, two-sided payment scheme for metered work, settled on Kaspa.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./chain": {
+      "types": "./dist/tools/chain.d.ts",
+      "import": "./dist/tools/chain.js"
+    }
+  },
+  "types": "./dist/src/index.d.ts",
+  "files": [
+    "dist",
+    "contracts",
+    "spec/SPEC.md",
+    "spec/CONFORMANCE.md",
+    "spec/conformance-vectors.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "prepublishOnly": "npm run build && npm test",
+    "test": "node --import tsx --test \"src/**/*.test.ts\"",
+    "conformance": "tsx tools/conformance.ts",
+    "conformance:py": "python impl-py/conformance.py",
+    "vectors": "tsx spec/vectors.ts > spec/worked-example.txt",
+    "contracts": "tsx tools/contracts.ts",
+    "contracts:ag": "tsx tools/contracts.ts --profile ag",
+    "state-layout": "tsx tools/state-layout.ts",
+    "dust-map": "tsx tools/dust-map.ts",
+    "fee-check": "tsx tools/fee-check.ts",
+    "anchor": "tsx tools/anchor-cli.ts",
+    "demo": "tsx tools/demo.ts",
+    "live:settle": "tsx tools/live-settle.ts",
+    "live:expire": "tsx tools/live-expire.ts",
+    "live:deadline": "tsx tools/live-deadline.ts",
+    "sigscript": "tsx tools/sigscript-check.ts"
+  },
+  "dependencies": {
+    "@noble/curves": "^1.9.7",
+    "@noble/hashes": "^1.8.0",
+    "gpt-tokenizer": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}