metered-protocol 1.0.0

package/dist/tools/kaspa.d.ts

@@ -0,0 +1,13 @@
+export type Network = 'testnet-10' | 'testnet-11' | 'mainnet';
+export declare const KEY_FILE: string;
+type Sdk = any;
+/** Loads the vendored rusty-kaspa WASM bindings. Node 21+ supplies the WebSocket global itself. */
+export declare function loadSdk(): Promise<Sdk>;
+/** The anchor key, or null if none has been generated. Never printed by anything here. */
+export declare function loadAnchorKey(): string | null;
+/** Writes a key to ~/.metered/kaspa.env. Refuses to overwrite: losing one loses its funds. */
+export declare function saveAnchorKey(privateKeyHex: string): void;
+/** The address this key pays from, which is also where a faucet should send test coins. */
+export declare function anchorAddress(privateKeyHex: string, network: Network): Promise<string>;
+export {};
+//# sourceMappingURL=kaspa.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"kaspa.d.ts","sourceRoot":"","sources":["../../tools/kaspa.ts"],"names":[],"mappings":"AAmBA,MAAM,MAAM,OAAO,GAAG,YAAY,GAAG,YAAY,GAAG,SAAS,CAAC;AAa9D,eAAO,MAAM,QAAQ,QAA2C,CAAC;AAGjE,KAAK,GAAG,GAAG,GAAG,CAAC;AAWf,mGAAmG;AACnG,wBAAsB,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,CAe5C;AAED,0FAA0F;AAC1F,wBAAgB,aAAa,IAAI,MAAM,GAAG,IAAI,CAI7C;AAED,8FAA8F;AAC9F,wBAAgB,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAUzD;AAED,2FAA2F;AAC3F,wBAAsB,aAAa,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAI5F"}

package/dist/tools/kaspa.js

@@ -0,0 +1,76 @@
+/**
+ * Loading the Kaspa SDK, and holding the key that pays for anchors.
+ *
+ * THE SDK IS NOT VENDORED HERE, deliberately. It is a 12 MB WASM blob, and this repository's whole
+ * posture is that everything it contains can be verified by CI on a clean checkout. The same
+ * arrangement already applies to `silverc` and the debugger: a heavy external artefact is found by
+ * environment variable and its absence fails with instructions rather than a stack trace. The
+ * encoder was vendored because the golden vector could not otherwise be regenerated; nothing about
+ * a checkpoint anchor has that property, because anchoring needs a live node either way.
+ *
+ * THE KEY LIVES OUTSIDE THE REPOSITORY, at ~/.metered/kaspa.env, for the reason the provider keys
+ * do: .gitignore stops a commit and does not stop a read, and anything working on this project can
+ * read anything inside it.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { pathToFileURL } from 'node:url';
+/**
+ * The rusty-kaspa WASM bindings, which are NOT vendored here: 12 MB of WASM with its own release
+ * cadence. Point METERED_KASPA_SDK at `kaspa.js` from a nodejs build, or put the same line in
+ * ~/.metered/kaspa.env beside the key -- outside the repository, like everything else that is
+ * specific to one machine.
+ *
+ * Only the chain tooling needs it. The specification, the conformance vectors and both
+ * implementations run without it.
+ */
+const SDK_ENV = 'METERED_KASPA_SDK';
+export const KEY_FILE = join(homedir(), '.metered', 'kaspa.env');
+let cached = null;
+/** Read a NAME=value line from the key file, so a machine-specific path stays out of the repository. */
+function fromKeyFile(name) {
+    if (!existsSync(KEY_FILE))
+        return undefined;
+    const match = readFileSync(KEY_FILE, 'utf8').match(new RegExp(`^${name}=(.+?)[ \\t\\r]*$`, 'm'));
+    return match?.[1];
+}
+/** Loads the vendored rusty-kaspa WASM bindings. Node 21+ supplies the WebSocket global itself. */
+export async function loadSdk() {
+    if (cached)
+        return cached;
+    const entry = process.env[SDK_ENV] ?? fromKeyFile(SDK_ENV);
+    if (!entry || !existsSync(entry)) {
+        throw new Error(`Kaspa SDK not found${entry ? ` at ${entry}` : ''}.\n\n` +
+            `Set ${SDK_ENV} to kaspa.js from a rusty-kaspa WASM nodejs build, or add\n` +
+            `${SDK_ENV}=<path> to ${KEY_FILE}.`);
+    }
+    const imported = await import(pathToFileURL(entry).href);
+    const sdk = (imported.default ?? imported);
+    sdk.initConsolePanicHook?.();
+    cached = sdk;
+    return sdk;
+}
+/** The anchor key, or null if none has been generated. Never printed by anything here. */
+export function loadAnchorKey() {
+    if (!existsSync(KEY_FILE))
+        return null;
+    const match = readFileSync(KEY_FILE, 'utf8').match(/^METERED_ANCHOR_KEY=([0-9a-fA-F]{64})\s*$/m);
+    return match ? match[1].toLowerCase() : null;
+}
+/** Writes a key to ~/.metered/kaspa.env. Refuses to overwrite: losing one loses its funds. */
+export function saveAnchorKey(privateKeyHex) {
+    if (loadAnchorKey())
+        throw new Error(`${KEY_FILE} already holds a key; refusing to overwrite it`);
+    mkdirSync(join(homedir(), '.metered'), { recursive: true });
+    writeFileSync(KEY_FILE, '# Metered -- the key that pays for checkpoint anchors. TESTNET ONLY.\n' +
+        '# Outside the repository on purpose: .gitignore stops a commit, not a read.\n' +
+        `METERED_ANCHOR_KEY=${privateKeyHex}\n`, { mode: 0o600 });
+}
+/** The address this key pays from, which is also where a faucet should send test coins. */
+export async function anchorAddress(privateKeyHex, network) {
+    const sdk = await loadSdk();
+    const priv = new sdk.PrivateKey(privateKeyHex);
+    return priv.toKeypair().toAddress(new sdk.NetworkId(network)).toString();
+}
+//# sourceMappingURL=kaspa.js.map

package/dist/tools/kaspa.js.map

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

package/dist/tools/live-deadline.d.ts

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

package/dist/tools/live-deadline.d.ts.map

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

package/dist/tools/live-deadline.js

@@ -0,0 +1,122 @@
+/**
+ * `npm run live:deadline` -- prove SPEC.md 7.3a on chain: what a provider loses by not posting.
+ *
+ * A real session runs over HTTP. Both parties count, both sign, and the provider ends up holding
+ * doubly-signed States for work it genuinely delivered. Then it does the one thing 7.3a forbids:
+ * nothing. The covenant UTXO ages past the response window with no claim pending, the buyer calls
+ * `expire`, and consensus hands the entire balance back to the buyer.
+ *
+ * THE POINT IS THAT NOTHING HERE IS AN ATTACK. The buyer does not forge, race, or exploit; it
+ * waits and then follows the rules. The provider is not cheated -- it holds perfectly good
+ * evidence of a debt, and the chain releases the money anyway, because a signed State that was
+ * never posted is a claim nobody made.
+ *
+ * This runs on testnet-10 and costs test coins. It is the demonstration behind the rule.
+ */
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { bytesToHex } from '@noble/hashes/utils';
+import { publicKeyHex } from '../src/encoding.js';
+import { serveMetered } from '../src/http/serve.js';
+import { MeteredService } from '../src/http/service.js';
+import { openSession, runBabel } from '../src/http/client.js';
+import { meterFor } from '../src/meter.js';
+import { shouldSettle } from '../src/deadline.js';
+import { loadSdk, loadAnchorKey } from './kaspa.js';
+import { compileWithState, covenantAddress } from './covenant.js';
+import { awaitUtxo, buildExpire, awaitWindow } from './live-steps.js';
+const NETWORK = 'testnet-10';
+const FUND = 50000000n;
+const FUND_FEE = 250000n;
+const CLOSE_FEE = 400000n;
+const WINDOW = 2;
+const PRICE = 3630;
+const BABEL = 10;
+const dir = mkdtempSync(join(tmpdir(), 'metered-deadline-'));
+const meter = meterFor('o200k_base');
+const deliver = (prompt, max) => new TextEncoder().encode(Array.from({ length: max }, (_, i) => `${prompt}${i}`).join(' '));
+/** What the provider's policy WOULD have told it, had it been asked. */
+const POLICY = { settleByAgeDaa: 1, settleAtUnsettledSompi: 50_000 };
+async function main() {
+    const funder = loadAnchorKey();
+    if (!funder)
+        throw new Error('no anchor key; run: npm run anchor -- address');
+    const buyerSk = bytesToHex(randomBytes(32));
+    const providerSk = bytesToHex(randomBytes(32));
+    const terms = {
+        v: 1, scheme: 'metered', network: 'kaspa:testnet-10', asset: 'KAS',
+        unit: 'llm.output_tokens.v1', meter: 'o200k_base',
+        unitPriceSompi: PRICE, babelUnits: BABEL, maxBabels: 16,
+        toleranceAbs: 1, checkpointEvery: 0, responseWindowDaa: WINDOW,
+    };
+    const service = new MeteredService({
+        terms, providerSk, providerPubkey: publicKeyHex(providerSk), meter, deliver,
+    });
+    const server = serveMetered({ service });
+    await new Promise((r) => server.listen(0, '127.0.0.1', r));
+    const base = `http://127.0.0.1:${server.address().port}`;
+    const sdk = await loadSdk();
+    const networkId = new sdk.NetworkId(NETWORK);
+    const priv = new sdk.PrivateKey(funder);
+    const from = priv.toKeypair().toAddress(networkId).toString();
+    const buyerAddr = new sdk.PrivateKey(buyerSk).toKeypair().toAddress(networkId).toString();
+    const rpc = new sdk.RpcClient({ resolver: new sdk.Resolver(), encoding: sdk.Encoding.Borsh, networkId });
+    await rpc.connect();
+    try {
+        const { offer, session } = await openSession(base, buyerSk, meter, 'kaspa:testnet-10');
+        const built = compileWithState(dir, {
+            parties: offer.partiesCommitment, sessionId: offer.sessionId, window: WINDOW, seq: -1, sompi: 0,
+        });
+        const address = await covenantAddress(built.hex, NETWORK);
+        const { entries } = await rpc.getUtxosByAddresses([from]);
+        const src = entries.reduce((a, b) => (b.amount > a.amount ? b : a));
+        const fund = sdk.createTransaction([src], [{ address, amount: FUND }, { address: from, amount: src.amount - FUND - 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, address, FUND);
+        if (!utxo)
+            throw new Error('the covenant UTXO never appeared');
+        console.log(`\n  1. FUNDED     ${Number(FUND) / 1e8} TKAS at ${address.slice(0, 30)}...`);
+        // ---- real work, really agreed.
+        let owed = 0;
+        for (let i = 0; i < 2; i += 1) {
+            const out = await runBabel(base, session, `question-${i}-`);
+            owed = out.state.cumulativeSompi;
+            console.log(`     babel ${i}: ${out.billedUnits} units, ${owed} sompi owed and DOUBLY SIGNED`);
+        }
+        const verdict = shouldSettle(POLICY, { ageDaa: WINDOW, unsettledSompi: owed });
+        console.log(`\n  2. POLICY     says settle: ${verdict.settle} -- ${verdict.why ?? 'nothing owed'}`);
+        console.log('     the provider ignores it and posts nothing. That is the whole experiment.');
+        await awaitWindow(rpc, WINDOW);
+        console.log(`\n  3. AGED       past the ${WINDOW}-DAA window with NO claim pending`);
+        const close = buildExpire(sdk, { buyerPk: offer.buyerPubkey, providerPk: offer.providerPubkey, signerSk: buyerSk,
+            redeem: built.hex, tag: built.entries.expire?.dispatch_tag ?? '' }, utxo, [{ address: buyerAddr, amount: utxo.amount - CLOSE_FEE }], WINDOW);
+        const id = (await rpc.submitTransaction({ transaction: close, allowOrphan: false })).transactionId;
+        const got = await awaitUtxo(rpc, buyerAddr, utxo.amount - CLOSE_FEE);
+        if (!got)
+            throw new Error('the close did not land');
+        console.log(`\n  4. CLOSED     the buyer took everything back   ${id}`);
+        console.log(`\n  PROVIDER OWED     ${owed} sompi, doubly signed, for work actually delivered`);
+        console.log(`  PROVIDER RECEIVED 0`);
+        console.log(`  BUYER RECEIVED    ${Number(utxo.amount - CLOSE_FEE) / 1e8} TKAS -- the entire balance`);
+        console.log('\n  Nothing here was an attack. The buyer waited, then followed the rules.');
+        console.log('  SPEC.md 7.3a is the rule that makes this the provider\'s own fault.\n');
+    }
+    finally {
+        await new Promise((r) => server.close(() => r()));
+        await rpc.disconnect().catch(() => undefined);
+    }
+}
+main().catch((err) => {
+    console.error(`\n  ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=live-deadline.js.map

package/dist/tools/live-deadline.js.map

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

package/dist/tools/live-expire.d.ts

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

package/dist/tools/live-expire.d.ts.map

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

package/dist/tools/live-expire.js

@@ -0,0 +1,127 @@
+/**
+ * `npm run live:expire` -- open a real covenant on testnet-10 and close it with `expire`.
+ *
+ * WHY EXPIRE AND NOT SETTLE. `settle` hands the funds back to the SAME covenant with updated
+ * state, and a continuation output must carry a KIP-20 CovenantBinding tying it to the authorizing
+ * input. That plumbing now exists in tools/live-settle.ts. `expire` still needs none of it: it
+ * pays plain P2PK addresses and continues nothing, and Argent lowers `emits {}` to
+ * OpAuthOutputCount == 0, which an unbound payout already satisfies. That is what made it the
+ * first covenant path to run on chain, and the first the ARGENT port ran too.
+ *
+ * WHAT IT PROVES. The whole covenant executes under real consensus: the parties commitment, the
+ * relative timelock, the signature check, and the no-claim refund branch that step 3.4 added
+ * after finding the funding UTXO would otherwise be unspendable forever.
+ *
+ * Everything happens in ONE run because the session keys live only in memory. Two earlier
+ * attempts generated keys, funded a covenant and then exited on an unrelated error, stranding the
+ * coins at an address whose keys no longer exist. Testnet, so it cost nothing but the lesson.
+ */
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { blake3 } from '@noble/hashes/blake3';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
+import { publicKeyHex } from '../src/encoding.js';
+import { loadSdk, loadAnchorKey } from './kaspa.js';
+import { compileWithState, covenantAddress } from './covenant.js';
+import { profileFromArgv } from './covenant-profile.js';
+const NETWORK = 'testnet-10';
+const FUND_SOMPI = 50000000n;
+const FUND_FEE = 250000n;
+// expire does TWO signature checks, so it needs compute budget 21, not 10 -- and mass rises with
+// the budget, so the node demands ~313,800 for a one-output close. Measured by being refused.
+const SPEND_FEE = 350000n;
+const EXPIRE_BUDGET = 21;
+const WINDOW = 2;
+/** kaspa-depin's lesson: createInputSignature returns a signature SCRIPT; strip the 0x41 push. */
+const bareSig = (s) => (s.length === 132 && s.startsWith('41') ? s.slice(2) : s);
+async function main() {
+    const funder = loadAnchorKey();
+    if (!funder)
+        throw new Error('no anchor key; run: npm run anchor -- address');
+    const dir = mkdtempSync(join(tmpdir(), 'metered-expire-'));
+    const buyerSk = bytesToHex(randomBytes(32));
+    const providerSk = bytesToHex(randomBytes(32));
+    const buyerPk = publicKeyHex(buyerSk);
+    const providerPk = publicKeyHex(providerSk);
+    const parties = bytesToHex(blake3(new Uint8Array([...hexToBytes(buyerPk), ...hexToBytes(providerPk)]), { dkLen: 32 }));
+    const sessionId = bytesToHex(randomBytes(16));
+    // `npm run live:expire -- --profile ag` closes with the ARGENT covenant instead. `expire` is
+    // the entry that needs no KIP-20 plumbing: Argent lowers `emits {}` to OpAuthOutputCount == 0,
+    // and an unbound P2PK payout already has zero authorised outputs.
+    const profile = profileFromArgv();
+    const compiled = compileWithState(dir, { parties, sessionId, window: WINDOW, seq: -1, sompi: 0 }, profile.contract);
+    const address = await covenantAddress(compiled.hex, NETWORK);
+    const tag = compiled.entries.expire?.dispatch_tag;
+    if (!tag)
+        throw new Error('the artifact has no expire entry');
+    console.log(`\n  covenant  ${compiled.hex.length / 2} bytes  [${profile.key}] ${profile.contract}`);
+    console.log(`  address   ${address}`);
+    console.log(`  closing with EXPIRE, no claim posted -- the buyer takes it all back (SPEC 7.2)`);
+    const sdk = await loadSdk();
+    const networkId = new sdk.NetworkId(NETWORK);
+    const priv = new sdk.PrivateKey(funder);
+    const funderAddr = priv.toKeypair().toAddress(networkId).toString();
+    const buyerAddr = new sdk.PrivateKey(buyerSk).toKeypair().toAddress(networkId).toString();
+    const rpc = new sdk.RpcClient({ resolver: new sdk.Resolver(), encoding: sdk.Encoding.Borsh, networkId });
+    await rpc.connect();
+    try {
+        const { entries } = await rpc.getUtxosByAddresses([funderAddr]);
+        const utxo = entries.reduce((a, b) => (b.amount > a.amount ? b : a));
+        const fundTx = sdk.createTransaction([utxo], [{ address, amount: FUND_SOMPI }, { address: funderAddr, amount: utxo.amount - FUND_SOMPI - FUND_FEE }], 0n, undefined, 0);
+        fundTx.version = 1;
+        fundTx.gas = 0n;
+        for (const i of fundTx.inputs) {
+            i.sigOpCount = 0;
+            i.computeBudget = 10;
+        }
+        fundTx.finalize();
+        const fundId = (await rpc.submitTransaction({ transaction: sdk.signTransaction(fundTx, [priv], true), allowOrphan: false })).transactionId;
+        console.log(`  funded    ${Number(FUND_SOMPI) / 1e8} TKAS   txid ${fundId}`);
+        let cov = null;
+        for (let i = 0; i < 40 && !cov; i += 1) {
+            await new Promise((r) => setTimeout(r, 1500));
+            const res = await rpc.getUtxosByAddresses([address]);
+            cov = res.entries.find((e) => e.amount === FUND_SOMPI) ?? null;
+        }
+        if (!cov)
+            throw new Error('the covenant UTXO never appeared');
+        // The window is RELATIVE (SPEC 7.3): ageDaa lowers to OpCheckSequenceVerify, which reads the
+        // spending input's sequence. The UTXO must also actually BE that old, so wait for the DAA
+        // score to advance past it.
+        const startDaa = (await rpc.getBlockDagInfo()).virtualDaaScore;
+        while ((await rpc.getBlockDagInfo()).virtualDaaScore < startDaa + BigInt(WINDOW) + 2n) {
+            await new Promise((r) => setTimeout(r, 1000));
+        }
+        console.log(`  aged      past the ${WINDOW}-DAA response window`);
+        const spend = sdk.createTransaction([cov], [{ address: buyerAddr, amount: cov.amount - SPEND_FEE }], 0n, undefined, 0);
+        spend.version = 1;
+        spend.gas = 0n;
+        spend.inputs[0].sigOpCount = 0;
+        spend.inputs[0].computeBudget = EXPIRE_BUDGET;
+        spend.inputs[0].sequence = BigInt(WINDOW);
+        const sig = bareSig(sdk.createInputSignature(spend, 0, new sdk.PrivateKey(buyerSk)));
+        const sb = new sdk.ScriptBuilder();
+        sb.addData(buyerPk);
+        sb.addData(providerPk);
+        sb.addData(sig);
+        sb.addData(tag);
+        sb.addData(compiled.hex);
+        spend.inputs[0].signatureScript = sb.toString();
+        spend.finalize();
+        const id = (await rpc.submitTransaction({ transaction: spend, allowOrphan: false })).transactionId;
+        console.log(`\n  EXPIRED   the covenant ran under real consensus and paid out`);
+        console.log(`  refund    ${Number(cov.amount - SPEND_FEE) / 1e8} TKAS -> ${buyerAddr}`);
+        console.log(`  txid      ${id}`);
+        console.log(`  explorer  https://explorer-tn10.kaspa.org/txs/${id}\n`);
+    }
+    finally {
+        await rpc.disconnect().catch(() => undefined);
+    }
+}
+main().catch((err) => {
+    console.error(`\n  ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=live-expire.js.map

package/dist/tools/live-expire.js.map

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

package/dist/tools/live-settle.d.ts

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

package/dist/tools/live-settle.d.ts.map

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

package/dist/tools/live-settle.js

@@ -0,0 +1,226 @@
+/**
+ * `npm run live:settle` -- drive a real multi-chunk session on testnet-10, including a SUPERSEDE.
+ *
+ * The single settle that ran first proved the covenant accepts a doubly-signed State. It did not
+ * prove the thing the two-phase design exists for: that a LATER State replaces a pending one and
+ * a STALE one cannot. This runs all three steps against real consensus --
+ *
+ *   1. settle seq 0                 the first claim posts
+ *   2. settle seq 0 again           refused; the guard is `seq > pendingSeq`, strictly
+ *   3. settle seq 1                 supersedes, and the state advances again
+ *   4. expire                       closes it, and the money SPLITS
+ *
+ * Step 2 is the one worth having. It is the stale-close threat -- "settle an old, lower-seq
+ * State" -- and until now it had only ever been refused by a simulator.
+ *
+ * Step 4 is the other one worth having. Every earlier expire closed a session with NO claim
+ * posted -- one output, nothing to divide. This one pays the provider exactly what it is owed and
+ * refunds the rest, which is the only branch where getting an output value wrong costs somebody.
+ *
+ * The simulator is still the pre-flight for every spend EXPECTED to succeed, and it emits the
+ * authoritative signature script. See tools/live-steps.ts for why the redeem script must be
+ * appended to it by hand.
+ */
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { blake3 } from '@noble/hashes/blake3';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
+import { publicKeyHex, signState, digestHex } from '../src/encoding.js';
+import { loadSdk, loadAnchorKey } from './kaspa.js';
+import { compileWithState, covenantAddress } from './covenant.js';
+import { preflightSigscript, awaitUtxo, withState, buildExpire, awaitWindow, x } from './live-steps.js';
+import { profileFromArgv, COVENANT_ID } from './covenant-profile.js';
+import { bindContinuation, fundAsCovenant, covenantIdOf, assertInherited } from './covenant-binding.js';
+// `npm run live:settle -- --profile ag` drives the ARGENT covenant instead.
+const PROFILE = profileFromArgv();
+const NETWORK = 'testnet-10';
+const FUND_SOMPI = 50000000n;
+const FUND_FEE = 250000n;
+const SPEND_FEE = 360000n; // measured: mass 3,429 -> 342,900 required
+const SPEND_BUDGET = 21; // two checkMsgSig calls
+const WINDOW = 2;
+const CLOSE_FEE = 400000n; // the covenant allowance in full; expire is the costliest path
+const PRICE = 3630;
+const CHUNK = 550;
+const dir = mkdtempSync(join(tmpdir(), 'metered-settle-'));
+/** Build one settle spend: pre-flight it, then hand back a signed transaction ready to submit. */
+function buildSettle(sdk, args, pending, claim, redeem, utxo, outAddress, expectPass) {
+    const state = {
+        v: 1, sessionId: args.sessionId, seq: claim.seq,
+        cumulativeUnits: claim.cumulativeUnits, cumulativeSompi: claim.cumulativeSompi,
+        prevState: claim.prevState,
+    };
+    const ctor = [x(args.parties), x(args.sessionId), WINDOW, pending.seq, pending.sompi];
+    const outValue = utxo.amount - SPEND_FEE;
+    const sigscript = preflightSigscript({
+        name: `live settle seq ${claim.seq}${expectPass ? '' : ' (stale)'}`,
+        function: 'settle',
+        constructor_args: ctor,
+        args: [
+            x(args.buyer.pk), x(args.provider.pk),
+            x(signState(state, args.buyer.sk)), x(signState(state, args.provider.sk)),
+            claim.seq, claim.cumulativeUnits, claim.cumulativeSompi, x(claim.prevState ?? '00'.repeat(32)),
+        ],
+        expect: expectPass ? 'pass' : 'fail',
+        tx: {
+            active_input_index: 0,
+            inputs: [{ utxo_value: Number(utxo.amount), constructor_args: ctor, ...(PROFILE.binds ? { covenant_id: COVENANT_ID } : {}) }],
+            outputs: [{
+                    value: Number(outValue), constructor_args: ctor,
+                    state: PROFILE.outState({
+                        parties: args.parties, sessionId: args.sessionId, window: WINDOW,
+                        seq: claim.seq, sompi: claim.cumulativeSompi,
+                    }),
+                    ...(PROFILE.binds ? { covenant_id: COVENANT_ID, authorizing_input: 0 } : {}),
+                }],
+        },
+    }, dir, expectPass, PROFILE.contract);
+    const tx = sdk.createTransaction([utxo], [{ address: outAddress, amount: outValue }], 0n, undefined, 0);
+    tx.version = 1;
+    tx.gas = 0n;
+    tx.inputs[0].sigOpCount = 0;
+    tx.inputs[0].computeBudget = SPEND_BUDGET;
+    const push = new sdk.ScriptBuilder();
+    push.addData(redeem);
+    tx.inputs[0].signatureScript = sigscript + push.toString();
+    const binding = bindContinuation(sdk, tx, utxo, PROFILE.binds);
+    tx.finalize();
+    return { tx, state, outValue, binding };
+}
+/**
+ * Fund the covenant from the anchor key and wait for its UTXO.
+ *
+ * AN ARGENT SESSION MUST BE FUNDED AS A COVENANT, not merely paid into, and this cost a rejected
+ * transaction to learn. `OpAuthOutputCount(activeInput)` asks how many outputs are authorised by
+ * the input being spent -- and an input that belongs to NO covenant authorises nothing, whatever
+ * its outputs claim. So the identity has to exist before the first settle, which means the
+ * FUNDING transaction is the genesis.
+ *
+ * The simulator passed the same spend because its test case declares `covenant_id` on the input
+ * directly; on chain there was nothing to declare it. That disagreement between simulator and
+ * consensus is the finding, and it is why the pre-flight is a floor rather than a proof.
+ *
+ * The hand-written covenant needs none of this: it constrains `outputs[0]` by convention and
+ * never asks who authorised it.
+ */
+async function payInto(sdk, rpc, priv, from, address) {
+    const { entries } = await rpc.getUtxosByAddresses([from]);
+    const source = entries.reduce((a, b) => (b.amount > a.amount ? b : a));
+    const tx = sdk.createTransaction([source], [{ address, amount: FUND_SOMPI }, { address: from, amount: source.amount - FUND_SOMPI - FUND_FEE }], 0n, undefined, 0);
+    tx.version = 1;
+    tx.gas = 0n;
+    for (const i of tx.inputs) {
+        i.sigOpCount = 0;
+        i.computeBudget = 10;
+    }
+    fundAsCovenant(tx, PROFILE.binds);
+    tx.finalize();
+    await rpc.submitTransaction({ transaction: sdk.signTransaction(tx, [priv], true), allowOrphan: false });
+    return awaitUtxo(rpc, address, FUND_SOMPI);
+}
+/**
+ * Submit a spend that MUST be rejected, and return why. A silent success here would mean the
+ * supersede guard does not hold on chain, which is the one outcome that must never pass quietly.
+ */
+async function expectRefusal(rpc, tx) {
+    try {
+        await rpc.submitTransaction({ transaction: tx, allowOrphan: false });
+    }
+    catch (err) {
+        return (err instanceof Error ? err.message : String(err)).split(':').pop()?.trim() ?? 'refused';
+    }
+    throw new Error('CONSENSUS ACCEPTED A STALE STATE -- the supersede guard does not hold on chain');
+}
+async function main() {
+    const funder = loadAnchorKey();
+    if (!funder)
+        throw new Error('no anchor key; run: npm run anchor -- address');
+    const buyer = { sk: bytesToHex(randomBytes(32)), pk: '' };
+    const provider = { sk: bytesToHex(randomBytes(32)), pk: '' };
+    buyer.pk = publicKeyHex(buyer.sk);
+    provider.pk = publicKeyHex(provider.sk);
+    const parties = bytesToHex(blake3(new Uint8Array([...hexToBytes(buyer.pk), ...hexToBytes(provider.pk)]), { dkLen: 32 }));
+    const sessionId = bytesToHex(randomBytes(16));
+    const ids = { parties, sessionId, buyer, provider };
+    const opened = compileWithState(dir, { parties, sessionId, window: WINDOW, seq: -1, sompi: 0 }, PROFILE.contract);
+    const spanEnd = opened.span.offset + opened.span.len;
+    const address = await covenantAddress(opened.hex, NETWORK);
+    console.log(`\n  covenant  ${opened.hex.length / 2} bytes  [${PROFILE.key}]  state span ${opened.span.len}`);
+    console.log(`  address   ${address}`);
+    const sdk = await loadSdk();
+    const networkId = new sdk.NetworkId(NETWORK);
+    const priv = new sdk.PrivateKey(funder);
+    const funderAddr = priv.toKeypair().toAddress(networkId).toString();
+    const rpc = new sdk.RpcClient({ resolver: new sdk.Resolver(), encoding: sdk.Encoding.Borsh, networkId });
+    await rpc.connect();
+    try {
+        const utxo0 = await payInto(sdk, rpc, priv, funderAddr, address);
+        if (!utxo0)
+            throw new Error('the covenant UTXO never appeared');
+        console.log(`  funded    ${Number(FUND_SOMPI) / 1e8} TKAS`);
+        // ---- 1. the first claim
+        const claim0 = { seq: 0, cumulativeUnits: CHUNK, cumulativeSompi: CHUNK * PRICE, prevState: null };
+        const redeem1 = withState(opened.hex, claim0.seq, claim0.cumulativeSompi, spanEnd);
+        const addr1 = await covenantAddress(redeem1, NETWORK);
+        const first = buildSettle(sdk, ids, { seq: -1, sompi: 0 }, claim0, opened.hex, utxo0, addr1, true);
+        const id0 = (await rpc.submitTransaction({ transaction: first.tx, allowOrphan: false })).transactionId;
+        const utxo1 = await awaitUtxo(rpc, addr1, first.outValue);
+        if (!utxo1)
+            throw new Error('the seq-0 continuation never appeared');
+        console.log(`\n  1. SETTLED seq 0   ${id0}`);
+        if (PROFILE.binds)
+            console.log(`     covenant  ${first.binding}  ${covenantIdOf(first.tx)}`);
+        // ---- 2. THE STALE CLOSE. Consensus must refuse this: seq 0 is not > pendingSeq 0.
+        const stale = buildSettle(sdk, ids, { seq: 0, sompi: claim0.cumulativeSompi }, claim0, redeem1, utxo1, addr1, false);
+        console.log(`  2. REFUSED seq 0 again -- ${await expectRefusal(rpc, stale.tx)}`);
+        // ---- 3. supersede with a strictly higher seq
+        const claim1 = {
+            seq: 1, cumulativeUnits: CHUNK * 2, cumulativeSompi: CHUNK * 2 * PRICE,
+            prevState: digestHex(first.state),
+        };
+        const redeem2 = withState(opened.hex, claim1.seq, claim1.cumulativeSompi, spanEnd);
+        const addr2 = await covenantAddress(redeem2, NETWORK);
+        const second = buildSettle(sdk, ids, { seq: 0, sompi: claim0.cumulativeSompi }, claim1, redeem1, utxo1, addr2, true);
+        const id1 = (await rpc.submitTransaction({ transaction: second.tx, allowOrphan: false })).transactionId;
+        const utxo2 = await awaitUtxo(rpc, addr2, second.outValue);
+        if (!utxo2)
+            throw new Error('the seq-1 continuation never appeared');
+        console.log(`  3. SETTLED seq 1   ${id1}`);
+        if (PROFILE.binds) {
+            console.log(`     covenant  ${second.binding}  ${covenantIdOf(second.tx)}`);
+            assertInherited(second.binding, second.tx, first.tx);
+        }
+        console.log(`     ${Number(second.outValue) / 1e8} TKAS at the seq-1 covenant, state advanced twice`);
+        // ---- 4. CLOSE IT. The branch where the money actually SPLITS: the provider takes the pending
+        // claim, the buyer takes the remainder. Until now expire had only ever closed a session with
+        // NO claim posted, which is the easy half -- one output, nothing to divide.
+        const buyerAddr = new sdk.PrivateKey(buyer.sk).toKeypair().toAddress(networkId).toString();
+        const providerAddr = new sdk.PrivateKey(provider.sk).toKeypair().toAddress(networkId).toString();
+        const owed = BigInt(claim1.cumulativeSompi);
+        const refund = utxo2.amount - owed - CLOSE_FEE;
+        // SPEC 7.3: the window is RELATIVE, so the UTXO must actually be that old before ageDaa passes.
+        await awaitWindow(rpc, WINDOW);
+        const closeTx = buildExpire(sdk, {
+            buyerPk: buyer.pk, providerPk: provider.pk, signerSk: provider.sk,
+            redeem: redeem2, tag: opened.entries.expire?.dispatch_tag ?? '',
+        }, utxo2, [{ address: providerAddr, amount: owed }, { address: buyerAddr, amount: refund }], WINDOW);
+        const id2 = (await rpc.submitTransaction({ transaction: closeTx, allowOrphan: false })).transactionId;
+        const paid = await awaitUtxo(rpc, providerAddr, owed);
+        const refunded = await awaitUtxo(rpc, buyerAddr, refund);
+        if (!paid || !refunded)
+            throw new Error('the split did not land -- one side was not paid');
+        console.log(`  4. CLOSED  seq 1   ${id2}`);
+        console.log(`\n  VERIFIED  provider ${Number(owed) / 1e8} TKAS, buyer ${Number(refund) / 1e8} TKAS`);
+        console.log(`            full lifecycle on chain: settle, refuse a stale one, supersede, split\n`);
+    }
+    finally {
+        await rpc.disconnect().catch(() => undefined);
+    }
+}
+main().catch((err) => {
+    console.error(`\n  ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=live-settle.js.map