@parity/product-lab 0.0.1-placeholder → 0.1.0

package/contracts/chain/src/cases/submit.js

@@ -0,0 +1,223 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { evidenceJson, expect } from "../runner.js";
+import { HASH, hexOf, settle, pendingAfter, errorText, receiptProblems, define } from "../context.js";
+export const submitCases = [
+    define({
+        id: "submit-finalized",
+        title: "a submitted transaction resolves finalized with a receipt in a finalized block",
+        requires: ["submit", "access"],
+        async run(kit) {
+            const access = await kit.access();
+            const { tracked, hooks, diagnostics } = await kit.submit("finalized");
+            const included = await tracked.included;
+            const finalized = await tracked.finalized;
+            const head = await access.finalizedHead();
+            const evidence = { included: included.block, finalized: finalized.block, txHash: finalized.txHash, head, hooks };
+            const problems = receiptProblems(finalized);
+            expect(problems.length === 0, problems.join("; "), evidence);
+            expect(finalized.ok, "the transaction did not dispatch", { ...evidence, dispatchError: finalized.dispatchError });
+            expect(included.txHash === finalized.txHash, "the finalized receipt is not the included transaction", evidence);
+            expect(head.number >= finalized.block.number, `finalized resolved at block ${finalized.block.number} while the chain has finalized only ${head.number}`, evidence);
+            const onChain = head.number === finalized.block.number ? head.hash : hexOf(await access.storage("System", "BlockHash", [finalized.block.number], head.hash));
+            evidence.finalizedHashAtHeight = onChain;
+            expect(onChain === finalized.block.hash.toLowerCase(), "the receipt's block is not the finalized block at its height", evidence);
+            expect(hooks.beforeBroadcast === 1 && hooks.onSigned === 1, "beforeBroadcast and onSigned are not called exactly once", evidence);
+            expect(evidenceJson(diagnostics) !== undefined, "the diagnostics are not JSON-safe", evidence);
+            evidence.diagnostics = Object.keys(diagnostics);
+            return evidence;
+        },
+    }),
+    define({
+        id: "submit-cancel",
+        title: "a beforeBroadcast that throws cancels the submission: nothing is sent",
+        requires: ["submit"],
+        async run(kit) {
+            const before = kit.submitterFixture().broadcasts?.();
+            const cancel = new Error("contract kit: cancelled before broadcast");
+            const result = await settle(kit.submit("finalized", {
+                beforeBroadcast: () => {
+                    throw cancel;
+                },
+            }));
+            const after = kit.submitterFixture().broadcasts?.();
+            const evidence = { rejected: !result.ok, broadcasts: { before, after } };
+            expect(!result.ok && result.error === cancel, "submit did not reject with the beforeBroadcast error", evidence);
+            if (before !== undefined)
+                expect(after === before, "a cancelled transaction reached the chain", evidence);
+            return evidence;
+        },
+    }),
+    define({
+        id: "submit-finality-advances",
+        title: "a block finalized while the transaction is prepared does not fail it: signed once, sent once, finalized",
+        requires: ["submit", "scriptedOutcomes"],
+        async run(kit) {
+            const before = kit.submitterFixture().broadcasts?.();
+            const { tracked, hooks } = await kit.submit("finality-advances");
+            const finalized = await settle(tracked.finalized);
+            const after = kit.submitterFixture().broadcasts?.();
+            const evidence = { finalized: finalized.ok ? finalized.value.block : errorText(finalized.error), hooks, broadcasts: { before, after } };
+            expect(finalized.ok, "the transaction failed because the chain finalized a block while it was prepared", evidence);
+            const problems = receiptProblems(finalized.value);
+            expect(problems.length === 0 && finalized.value.ok, problems.join("; ") || "the transaction did not dispatch", evidence);
+            expect(hooks.beforeBroadcast === 1 && hooks.onSigned === 1, "beforeBroadcast and onSigned are not called exactly once", evidence);
+            if (before !== undefined)
+                expect(after === before + 1, "the transaction reached the chain more than once, or not at all", evidence);
+            return evidence;
+        },
+    }),
+    define({
+        id: "submit-dispatch-error",
+        title: "a failed dispatch is a finalized receipt with ok false and its dispatch error",
+        requires: ["submit", "scriptedOutcomes"],
+        async run(kit) {
+            const { tracked } = await kit.submit("dispatch-error");
+            const receipt = await tracked.finalized;
+            const problems = receiptProblems(receipt);
+            const evidence = { ok: receipt.ok, dispatchError: receipt.dispatchError };
+            expect(problems.length === 0, problems.join("; "), evidence);
+            expect(receipt.ok === false && typeof receipt.dispatchError?.type === "string", "a failed dispatch was reported as a success", evidence);
+            return evidence;
+        },
+    }),
+    define({
+        id: "submit-not-finalized",
+        title: "an included transaction whose block is never finalized never resolves finalized",
+        requires: ["submit", "scriptedOutcomes"],
+        async run(kit) {
+            const controller = new AbortController();
+            const { tracked } = await kit.submit("best-only", { signal: controller.signal });
+            const included = await tracked.included;
+            const pending = await pendingAfter(tracked.finalized, 500);
+            controller.abort(new Error("contract kit: done waiting"));
+            const after = await settle(tracked.finalized);
+            const evidence = { included: included.block, pendingAfter500ms: pending, finalizedAfterAbort: after.ok ? "resolved" : errorText(after.error) };
+            expect(pending, "finalized resolved for a block that was never finalized", evidence);
+            expect(!after.ok, "finalized resolved after the abort", evidence);
+            return evidence;
+        },
+    }),
+    define({
+        id: "submit-retracted",
+        title: "a retracted inclusion is neither a failure nor a success: finality decides, and without it the timeout rejects finalized",
+        requires: ["submit", "scriptedOutcomes"],
+        async run(kit) {
+            const { tracked } = await kit.submit("retracted", { timeoutMs: 1_500 });
+            const included = await settle(tracked.included);
+            const pending = await pendingAfter(tracked.finalized, 500);
+            const finalized = await settle(tracked.finalized);
+            const evidence = {
+                included: included.ok ? included.value.block : errorText(included.error),
+                pendingAfter500ms: pending,
+                finalized: finalized.ok ? finalized.value.block : errorText(finalized.error),
+            };
+            expect(!finalized.ok, "finalized resolved although its inclusion was retracted and no block with it was finalized", evidence);
+            expect(pending, "a retraction failed the transaction before finality could decide (it may be included again)", evidence);
+            return evidence;
+        },
+    }),
+    define({
+        id: "submit-inclusion-moves",
+        title: "an inclusion that moves to another block before finality: sent once, finalized with the receipt from the finalized block",
+        requires: ["submit", "scriptedOutcomes", "access"],
+        async run(kit) {
+            const access = await kit.access();
+            const before = kit.submitterFixture().broadcasts?.();
+            const { tracked, hooks, diagnostics } = await kit.submit("moved");
+            const included = await tracked.included;
+            const finalized = await settle(tracked.finalized);
+            const after = kit.submitterFixture().broadcasts?.();
+            const head = await access.finalizedHead();
+            const evidence = {
+                included: included.block,
+                finalized: finalized.ok ? finalized.value.block : errorText(finalized.error),
+                head,
+                hooks,
+                broadcasts: { before, after },
+            };
+            expect(finalized.ok, "the transaction failed because its inclusion moved before finality", evidence);
+            const receipt = finalized.value;
+            const problems = receiptProblems(receipt);
+            expect(problems.length === 0 && receipt.ok, problems.join("; ") || "the transaction did not dispatch", evidence);
+            expect(receipt.txHash === included.txHash, "the finalized receipt is another transaction's", evidence);
+            expect(head.number >= receipt.block.number, `finalized resolved at block ${receipt.block.number} while the chain has finalized only ${head.number}`, evidence);
+            const onChain = head.number === receipt.block.number ? head.hash : hexOf(await access.storage("System", "BlockHash", [receipt.block.number], head.hash));
+            evidence.finalizedHashAtHeight = onChain;
+            expect(onChain === receipt.block.hash.toLowerCase(), "the receipt's block is not the finalized block at its height (the first inclusion's block lost)", evidence);
+            expect(receipt.block.hash !== included.block.hash, "the fixture did not move the inclusion, so this case proves nothing", evidence);
+            expect(hooks.beforeBroadcast === 1 && hooks.onSigned === 1, "beforeBroadcast and onSigned are not called exactly once", evidence);
+            if (before !== undefined)
+                expect(after === before + 1, "the transaction reached the chain more than once, or not at all", evidence);
+            expect(evidenceJson(diagnostics) !== undefined, "the diagnostics are not JSON-safe", evidence);
+            evidence.diagnostics = Object.keys(diagnostics);
+            if (diagnostics.inclusionMoves !== undefined)
+                evidence.inclusionMoves = diagnostics.inclusionMoves;
+            return evidence;
+        },
+    }),
+    define({
+        id: "submit-stream-ends",
+        title: "a stream that ends before inclusion rejects both stages",
+        requires: ["submit", "scriptedOutcomes"],
+        async run(kit) {
+            const { tracked } = await kit.submit("stream-ends");
+            const [included, finalized] = await Promise.all([settle(tracked.included), settle(tracked.finalized)]);
+            expect(!included.ok && !finalized.ok, "a transaction whose stream ended resolved", { included: included.ok, finalized: finalized.ok });
+            return { included: errorText(!included.ok && included.error), finalized: errorText(!finalized.ok && finalized.error) };
+        },
+    }),
+    define({
+        id: "submit-abort",
+        title: "aborting rejects both stages with the abort reason",
+        requires: ["submit", "scriptedOutcomes"],
+        async run(kit) {
+            const controller = new AbortController();
+            const { tracked } = await kit.submit("pending", { signal: controller.signal });
+            const reason = new Error("contract kit: aborted");
+            controller.abort(reason);
+            const [included, finalized] = await Promise.all([settle(tracked.included), settle(tracked.finalized)]);
+            const evidence = { included: included.ok ? "resolved" : errorText(included.error), finalized: finalized.ok ? "resolved" : errorText(finalized.error) };
+            expect(!included.ok && !finalized.ok, "an aborted transaction resolved", evidence);
+            expect(included.error === reason && finalized.error === reason, "the stages rejected with something other than the abort reason", evidence);
+            return evidence;
+        },
+    }),
+    define({
+        id: "submit-timeout",
+        title: "finality that does not arrive in time rejects both stages",
+        requires: ["submit", "scriptedOutcomes"],
+        async run(kit) {
+            const started = performance.now();
+            const { tracked } = await kit.submit("pending", { timeoutMs: 200 });
+            const [included, finalized] = await Promise.all([settle(tracked.included), settle(tracked.finalized)]);
+            const ms = Math.round(performance.now() - started);
+            const evidence = { ms, included: included.ok ? "resolved" : errorText(included.error), finalized: finalized.ok ? "resolved" : errorText(finalized.error) };
+            expect(!included.ok && !finalized.ok, "a transaction past its timeout resolved", evidence);
+            expect(ms < 5_000, "the timeout was not honoured", evidence);
+            return evidence;
+        },
+    }),
+    define({
+        id: "submit-signed-facts",
+        title: "onSubmitted reports, once and before inclusion, what identifies the transaction on chain",
+        requires: ["submit", "access"],
+        async run(kit) {
+            await kit.access();
+            const { tracked, signed, signer } = await kit.submit("finalized");
+            const receipt = await tracked.finalized;
+            const facts = signed[0]?.transaction;
+            const evidence = { calls: signed.length, facts, receipt: { txHash: receipt.txHash, block: receipt.block } };
+            expect(signed.length === 1 && facts, "onSubmitted was not called exactly once", evidence);
+            expect(signed[0].beforeInclusion, "onSubmitted came after the transaction was included (a caller cut off before then cannot find it)", evidence);
+            expect(facts.txHash.toLowerCase() === receipt.txHash.toLowerCase(), "onSubmitted's txHash is not the receipt's", evidence);
+            expect(facts.signer.toLowerCase() === signer, `onSubmitted's signer is not the signer's public key (${signer})`, evidence);
+            expect(Number.isInteger(facts.signedAt?.number) && facts.signedAt.number < receipt.block.number && HASH.test(facts.signedAt.hash), "signedAt is not a block before the one it landed in", evidence);
+            if (facts.nonce !== undefined)
+                expect(Number.isInteger(facts.nonce) && facts.nonce >= 0, "the nonce is not a non-negative integer", evidence);
+            if (facts.mortality !== undefined && facts.mortality !== "immortal")
+                expect(facts.mortality.birth <= receipt.block.number && receipt.block.number < facts.mortality.death, "the transaction landed outside its own mortality", evidence);
+            return evidence;
+        },
+    }),
+];

package/contracts/chain/src/cases/validator.d.ts

@@ -0,0 +1,3 @@
+import { type ChainCase } from "../context.js";
+/** The validator cases, in run order. */
+export declare const validatorCases: readonly ChainCase[];

package/contracts/chain/src/cases/validator.js

@@ -0,0 +1,59 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { CheckFailed, evidenceJson, expect } from "../runner.js";
+import { settle, errorText, deepFreeze, define } from "../context.js";
+export const validatorCases = [
+    define({
+        id: "validator-accepts",
+        title: "the ReceiptValidator accepts the receipts it must accept",
+        requires: ["validator"],
+        async run(kit) {
+            const fixture = kit.subject.validator;
+            expect(fixture && fixture.accepts.length > 0, "declares validator but gives no receipts to accept");
+            const verdicts = [];
+            for (const receipt of fixture.accepts)
+                verdicts.push(await fixture.validator.validate(deepFreeze(structuredClone(receipt))));
+            expect(verdicts.every((verdict) => verdict.ok), "a receipt it must accept was rejected", { verdicts });
+            return { accepted: verdicts.length };
+        },
+    }),
+    define({
+        id: "validator-rejects",
+        title: "a ReceiptValidator rejection surfaces as a verdict with a reason, never a throw",
+        requires: ["validator"],
+        async run(kit) {
+            const fixture = kit.subject.validator;
+            expect(fixture && fixture.rejects.length > 0, "declares validator but gives no receipts to reject");
+            const verdicts = [];
+            for (const receipt of fixture.rejects) {
+                let verdict;
+                try {
+                    verdict = await fixture.validator.validate(deepFreeze(structuredClone(receipt)));
+                }
+                catch (error) {
+                    throw new CheckFailed(`the validator threw instead of rejecting: ${errorText(error)}`, { receipt: evidenceJson(receipt) });
+                }
+                verdicts.push(verdict);
+                expect(!verdict.ok && typeof verdict.reason === "string" && verdict.reason.trim().length > 0, "a receipt it must reject was accepted, or rejected without a reason", { verdicts });
+            }
+            return { reasons: verdicts.map((verdict) => (verdict.ok ? "" : verdict.reason)) };
+        },
+    }),
+    define({
+        id: "validator-stable",
+        title: "the verdict is the same for the inclusion and the finalized receipt, and the receipt is not mutated",
+        requires: ["validator"],
+        async run(kit) {
+            const fixture = kit.subject.validator;
+            expect(fixture, "declares validator but gives no validator fixture");
+            for (const receipt of [...fixture.accepts, ...fixture.rejects]) {
+                const frozen = deepFreeze(structuredClone(receipt));
+                const first = await settle(Promise.resolve().then(() => fixture.validator.validate(frozen)));
+                const second = await settle(Promise.resolve().then(() => fixture.validator.validate(frozen)));
+                expect(first.ok && second.ok, `the validator threw on a frozen receipt (it mutates receipts?): ${errorText(!first.ok ? first.error : !second.ok ? second.error : "")}`);
+                expect(evidenceJson(first.value) === evidenceJson(second.value), "two validations of one receipt differ", { first: first.value, second: second.value });
+            }
+            return { receipts: fixture.accepts.length + fixture.rejects.length };
+        },
+    }),
+];

package/contracts/chain/src/context.d.ts

@@ -0,0 +1,51 @@
+import type { ChainAccess, ChainHistory, SignedTransaction, KeyDerivation, Receipt, TrackedTransaction, TransactionSubmitter } from "@parity/product-lab/ports/chain";
+import { type ContractCase } from "./runner.js";
+import type { ChainKitCapability, ChainKitSubject, ScriptedOutcome } from "./subject.js";
+export declare const HASH: RegExp;
+export declare const hex: (bytes: Uint8Array) => string;
+/** A hash as the adapter decoded it: a hex string, bytes, or a binary with `asHex()`. */
+export declare function hexOf(value: unknown): string | undefined;
+export declare function settle<T>(promise: Promise<T>): Promise<{
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: unknown;
+}>;
+/** Whether `promise` is still pending after `ms`. */
+export declare function pendingAfter(promise: Promise<unknown>, ms: number): Promise<boolean>;
+export declare const errorText: (error: unknown) => string;
+export declare class ChainKitContext {
+    #private;
+    readonly subject: ChainKitSubject;
+    constructor(subject: ChainKitSubject);
+    access(): Promise<ChainAccess>;
+    submitterFixture(): NonNullable<ChainKitSubject["submitter"]>;
+    submitter(): Promise<TransactionSubmitter>;
+    history(): Promise<ChainHistory>;
+    keys(): KeyDerivation;
+    /** Submit one transaction of `outcome`, recording the hooks the submitter calls. */
+    submit(outcome: ScriptedOutcome, extra?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+        beforeBroadcast?: () => void;
+    }): Promise<{
+        tracked: TrackedTransaction;
+        hooks: {
+            beforeBroadcast: number;
+            onSigned: number;
+        };
+        diagnostics: Record<string, unknown>;
+        signed: {
+            transaction: SignedTransaction;
+            beforeInclusion: boolean;
+        }[];
+        signer: string;
+    }>;
+    teardown(): void;
+}
+/** A receipt's shape, as the port describes it. */
+export declare function receiptProblems(receipt: Receipt): string[];
+export declare function deepFreeze<T>(value: T): T;
+export type ChainCase = ContractCase<ChainKitContext, ChainKitCapability>;
+export declare const define: (testCase: ChainCase) => ChainCase;

package/contracts/chain/src/context.js

@@ -0,0 +1,125 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { evidenceJson, expect } from "./runner.js";
+export const HASH = /^0x[0-9a-f]{64}$/;
+export const hex = (bytes) => `0x${Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+export function hexOf(value) {
+    if (typeof value === "string")
+        return value.toLowerCase();
+    if (value instanceof Uint8Array)
+        return hex(value);
+    if (value && typeof value === "object" && typeof value.asHex === "function")
+        return String(value.asHex()).toLowerCase();
+    return undefined;
+}
+export async function settle(promise) {
+    try {
+        return { ok: true, value: await promise };
+    }
+    catch (error) {
+        return { ok: false, error };
+    }
+}
+export async function pendingAfter(promise, ms) {
+    let timer;
+    const marker = Symbol("pending");
+    const result = await Promise.race([promise.then(() => "settled", () => "settled"), new Promise((resolve) => (timer = setTimeout(() => resolve(marker), ms)))]);
+    clearTimeout(timer);
+    return result === marker;
+}
+export const errorText = (error) => (error instanceof Error ? error.message : String(error));
+export class ChainKitContext {
+    subject;
+    #opened = [];
+    #submitter;
+    constructor(subject) {
+        this.subject = subject;
+    }
+    async access() {
+        expect(this.subject.access, `${this.subject.name} declares access but gives no ChainAccess`);
+        const access = await this.subject.access();
+        this.#opened.push(access);
+        return access;
+    }
+    submitterFixture() {
+        expect(this.subject.submitter, `${this.subject.name} declares submit but gives no submitter`);
+        return this.subject.submitter;
+    }
+    submitter() {
+        this.#submitter ??= Promise.resolve(this.submitterFixture().create());
+        return this.#submitter;
+    }
+    async history() {
+        if (this.subject.history)
+            return this.subject.history();
+        const access = (await this.access());
+        expect(typeof access.blockAt === "function" && typeof access.extrinsicHashes === "function" && typeof access.dispatchOutcome === "function", `${this.subject.name} declares history but gives no ChainHistory (and its ChainAccess does not implement it)`);
+        return access;
+    }
+    keys() {
+        expect(this.subject.keys, `${this.subject.name} declares keys but gives no KeyDerivation`);
+        return this.subject.keys;
+    }
+    async submit(outcome, extra = {}) {
+        const submitter = await this.submitter();
+        const transaction = await this.submitterFixture().transaction(outcome);
+        const hooks = { beforeBroadcast: 0, onSigned: 0 };
+        const signed = [];
+        let includedYet = false;
+        const diagnostics = {};
+        const tracked = await submitter.submit({
+            label: `contract kit ${outcome}`,
+            call: transaction.call,
+            signer: transaction.signer,
+            signal: extra.signal ?? new AbortController().signal,
+            timeoutMs: extra.timeoutMs ?? this.subject.finalityTimeoutMs ?? 60_000,
+            diagnostics,
+            beforeBroadcast: () => {
+                hooks.beforeBroadcast++;
+                extra.beforeBroadcast?.();
+            },
+            onSigned: () => {
+                hooks.onSigned++;
+            },
+            onSubmitted: (transaction) => {
+                signed.push({ transaction: structuredClone(transaction), beforeInclusion: !includedYet });
+            },
+        });
+        void tracked.included.then(() => (includedYet = true), () => undefined);
+        return { tracked, hooks, diagnostics, signed, signer: hex(transaction.signer.publicKey) };
+    }
+    teardown() {
+        for (const access of this.#opened.splice(0))
+            access.close();
+    }
+}
+export function receiptProblems(receipt) {
+    const problems = [];
+    if (!/^0x[0-9a-f]+$/i.test(receipt.txHash))
+        problems.push(`txHash ${receipt.txHash} is not hex`);
+    if (typeof receipt.ok !== "boolean")
+        problems.push("ok is not a boolean");
+    if (!HASH.test(receipt.block?.hash ?? ""))
+        problems.push(`block hash ${receipt.block?.hash} is not a 32-byte hex hash`);
+    for (const key of ["number", "index"])
+        if (!Number.isInteger(receipt.block?.[key]) || receipt.block[key] < 0)
+            problems.push(`block.${key} is not a non-negative integer`);
+    if (!Array.isArray(receipt.events))
+        problems.push("events is not a list");
+    else
+        for (const event of receipt.events)
+            if (typeof event.type !== "string" || typeof event.value?.type !== "string")
+                problems.push(`event ${evidenceJson(event)} is not { type, value: { type } }`);
+    if (!receipt.ok && typeof receipt.dispatchError?.type !== "string")
+        problems.push("a failed dispatch carries no dispatchError");
+    return problems;
+}
+export function deepFreeze(value) {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const inner of Object.values(value))
+            deepFreeze(inner);
+    }
+    return value;
+}
+export const define = (testCase) => testCase;

package/contracts/chain/src/index.d.ts

@@ -0,0 +1,2 @@
+export { CHAIN_KIT_CAPABILITIES, ChainKitContext, DEV_VECTORS, chainCases, chainContractTests, runChainContract, type ChainKitCapability, type ChainKitOptions, type ChainKitSubject, type ScriptedOutcome, } from "./kit.js";
+export { conforms, formatReport, type CaseResult, type CaseStatus, type ContractCase, type ContractReport } from "./runner.js";

package/contracts/chain/src/index.js

@@ -0,0 +1,4 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export { CHAIN_KIT_CAPABILITIES, ChainKitContext, DEV_VECTORS, chainCases, chainContractTests, runChainContract, } from "./kit.js";
+export { conforms, formatReport } from "./runner.js";

package/contracts/chain/src/kit.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The chain contract kit (docs/architecture-refactor.md, step 10). A chain,
+ * keys or integration adapter runs it against itself from its own tests:
+ * `chainContractTests({ name, declares, access, submitter, validator, keys })`.
+ *
+ * It checks what `@parity/product-lab/ports/chain` promises: `ChainAccess` is ready
+ * (its finalized head reads back through its own storage) and closes
+ * idempotently; `TransactionSubmitter` resolves `finalized` only with a receipt
+ * in a finalized block (the block finality chose, when the inclusion moved or
+ * was retracted before it), rejects on abort, timeout or a stream that ends
+ * (never at once on a retraction: finality decides), never sends a
+ * transaction twice, surfaces a dispatch error on the receipt, and reports what identifies a
+ * transaction on chain (`onSubmitted`) before it can land; `ChainHistory`
+ * shows what a finalized block holds (the receipt's extrinsic hash, dispatch
+ * result and the signer's nonce), which "did this transaction land" rests on;
+ * a `ReceiptValidator`'s
+ * rejection surfaces as a verdict with a reason; `KeyDerivation` and its
+ * signers are deterministic for the well-known development URIs
+ * (`//Alice` is 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY) and never echo
+ * a secret.
+ *
+ * Each case names the kit capabilities it needs; one the subject does not
+ * declare is `unsupported`, never a pass. Access and submission cases against
+ * a real chain run only in live mode.
+ */
+import { type ContractReport } from "./runner.js";
+import { type ChainCase } from "./context.js";
+import type { ChainKitCapability, ChainKitOptions, ChainKitSubject } from "./subject.js";
+export { CHAIN_KIT_CAPABILITIES, DEV_VECTORS, type ChainKitCapability, type ChainKitOptions, type ChainKitSubject, type ScriptedOutcome } from "./subject.js";
+export { ChainKitContext } from "./context.js";
+/** The chain contract, in run order: one file per case family under cases/. */
+export declare const chainCases: readonly ChainCase[];
+/** Run the chain contract against a subject and report every case. */
+export declare function runChainContract(subject: ChainKitSubject, options?: ChainKitOptions): Promise<ContractReport<ChainKitCapability>>;
+/** Register the chain contract as node:test tests (one per case) in the calling test file. */
+export declare function chainContractTests(subject: ChainKitSubject, options?: Omit<ChainKitOptions, "only">): void;

package/contracts/chain/src/kit.js

@@ -0,0 +1,33 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { registerCases, runCases } from "./runner.js";
+import { ChainKitContext } from "./context.js";
+import { accessCases } from "./cases/access.js";
+import { submitCases } from "./cases/submit.js";
+import { historyCases } from "./cases/history.js";
+import { validatorCases } from "./cases/validator.js";
+import { keysCases } from "./cases/keys.js";
+export { CHAIN_KIT_CAPABILITIES, DEV_VECTORS } from "./subject.js";
+export { ChainKitContext } from "./context.js";
+export const chainCases = [...accessCases, ...submitCases, ...historyCases, ...validatorCases, ...keysCases];
+const LIVE = new Set(chainCases.filter((testCase) => testCase.requires.includes("access") || testCase.requires.includes("submit")).map((testCase) => testCase.id));
+function runOptions(subject, options) {
+    return {
+        kit: "chain",
+        subject: subject.name,
+        declared: subject.declares,
+        cases: chainCases,
+        setup: async () => new ChainKitContext(subject),
+        teardown: async (kit) => kit.teardown(),
+        skip: (testCase) => (LIVE.has(testCase.id) && subject.live && !options.live ? "live only: talks to a real chain (run with live: true)" : undefined),
+        ...(options.only ? { only: options.only } : {}),
+        ...(options.caseTimeoutMs ? { caseTimeoutMs: options.caseTimeoutMs } : {}),
+        ...(options.log ? { log: options.log } : {}),
+    };
+}
+export function runChainContract(subject, options = {}) {
+    return runCases(runOptions(subject, options));
+}
+export function chainContractTests(subject, options = {}) {
+    registerCases(`chain contract: ${subject.name}`, runOptions(subject, options));
+}

package/contracts/chain/src/runner.d.ts

@@ -0,0 +1,71 @@
+export type CaseStatus = "pass" | "fail" | "unsupported" | "skipped";
+export interface ContractCase<Context, Requirement extends string> {
+    readonly id: string;
+    readonly title: string;
+    /** Kit capabilities the subject must declare for the case to run. */
+    readonly requires: readonly Requirement[];
+    run(context: Context): Promise<Record<string, unknown>>;
+}
+export interface CaseResult<Requirement extends string = string> {
+    readonly id: string;
+    readonly title: string;
+    readonly requires: readonly Requirement[];
+    readonly status: CaseStatus;
+    /** Undeclared capabilities, for `unsupported`. */
+    readonly missing?: readonly Requirement[];
+    /** Why a case was skipped (filtered out, or live only). */
+    readonly reason?: string;
+    readonly ms: number;
+    readonly evidence: Record<string, unknown>;
+    readonly error?: string;
+}
+export interface ContractReport<Requirement extends string = string> {
+    readonly kit: string;
+    readonly subject: string;
+    readonly declared: readonly Requirement[];
+    readonly startedAt: string;
+    readonly finishedAt: string;
+    readonly results: readonly CaseResult<Requirement>[];
+    readonly summary: Record<CaseStatus, number>;
+    /** Failures outside any case (setup, teardown). */
+    readonly errors: readonly string[];
+}
+/** A failed check, with the evidence that shows it. */
+export declare class CheckFailed extends Error {
+    readonly evidence: Record<string, unknown>;
+    constructor(message: string, evidence?: Record<string, unknown>);
+}
+export declare function expect(condition: unknown, message: string, evidence?: Record<string, unknown>): asserts condition;
+/** JSON for evidence: bigints as strings, bytes as hex. */
+export declare function evidenceJson(value: unknown): string;
+export interface RunCasesOptions<Context, Requirement extends string> {
+    readonly kit: string;
+    readonly subject: string;
+    readonly declared: readonly Requirement[];
+    readonly cases: readonly ContractCase<Context, Requirement>[];
+    /** Builds the context the cases share; a throw is reported in `errors` and no case runs. */
+    setup(): Promise<Context>;
+    /** Releases what setup acquired; always runs when setup succeeded. */
+    teardown?(context: Context): Promise<void>;
+    /** A reason to skip a runnable case (for example: it starts a real chain and the run is not live). */
+    skip?(testCase: ContractCase<Context, Requirement>): string | undefined;
+    /** Run only these case ids; the rest are `skipped`. */
+    readonly only?: readonly string[];
+    /** A case still running after this long fails (default 60 s), so a broken adapter cannot hang the kit. */
+    readonly caseTimeoutMs?: number;
+    readonly log?: (line: string) => void;
+}
+export declare function missingRequirements<Requirement extends string>(declared: readonly Requirement[], testCase: {
+    readonly requires: readonly Requirement[];
+}): Requirement[];
+export declare function runCases<Context, Requirement extends string>(options: RunCasesOptions<Context, Requirement>): Promise<ContractReport<Requirement>>;
+/** True when every case that ran passed, at least one ran, and nothing failed outside them. */
+export declare function conforms(report: ContractReport): boolean;
+export declare function formatReport(report: ContractReport): string;
+/**
+ * Register a kit's cases as node:test tests: one test per case, an
+ * undeclared case as a skipped test marked `unsupported` (never a pass), a
+ * live-only case as a skipped test with its reason. The kit runs once, before
+ * the first test; each test asserts its own case's result.
+ */
+export declare function registerCases<Context, Requirement extends string>(title: string, options: Omit<RunCasesOptions<Context, Requirement>, "only">): void;