@parity/product-lab 0.0.1-placeholder → 0.1.0

package/adapters/environment/chopsticks/src/environment.d.ts

@@ -0,0 +1,133 @@
+import { type CapabilityPolicy } from "@parity/product-lab/domain";
+import { type Capability, type EnvironmentAccess, type EnvironmentOffer, type TopologyChain, type TopologyEndpoints } from "@parity/product-lab/domain";
+import type { RunManifestStore } from "@parity/product-lab/ports/storage";
+import type { EnvironmentVariables, CommandRunner, JsonRpcClient, PortAllocator, ProcessRunner, StopPolicy, SystemPorts } from "@parity/product-lab/ports/system";
+import { type AuthorityChange } from "./dev-authority.js";
+import { type ChopsticksChain, type ChopsticksOptions, type ResolvedChopsticksOptions } from "./options.js";
+import { type ChopsticksPlan, type PinnedBlock } from "./plan.js";
+import { type UpstreamFacts } from "./upstream.js";
+import { type ChopsticksVersionCheck, type ChopsticksVersionPlan } from "./versions.js";
+import type { VersionResolution } from "@parity/product-lab/domain/versions";
+/** What a Chopsticks environment takes from the machine (Node implementations: `@parity/product-lab/system-node`). */
+export interface ChopsticksSystem {
+    /** Owned processes: every Chopsticks process is recorded in a registry in the run directory. */
+    processes: ProcessRunner;
+    /** Bounded one-shot connection inspection. */
+    commands: CommandRunner;
+    /** Port checks before anything starts. */
+    ports: PortAllocator;
+    /** Upstream checks, readiness, the development authority and block building. */
+    rpc: JsonRpcClient;
+    /** The environment Chopsticks runs with (`CHOPSTICKS_LOG_LEVEL` sets its LOG_LEVEL, default info). */
+    environment: EnvironmentVariables;
+    /** Where the run manifest is written (`<run directory>/run-manifest.json`). */
+    runManifests: RunManifestStore;
+}
+/** The Chopsticks system from a lab's system ports; refuses a lab that supplies too few. */
+export declare function requireChopsticksSystem(deps: Partial<SystemPorts>): ChopsticksSystem;
+/** What a capability probe reports about running endpoints (env-attached's attachEnvironment has this shape). */
+export interface ProbedEndpoints {
+    chains: Partial<Record<TopologyChain, unknown>>;
+    policy: CapabilityPolicy;
+    endpoints: TopologyEndpoints;
+}
+/**
+ * Probes what running loopback endpoints serve, deciding each capability with
+ * its evidence. The caller composes it, for example `attachedProbe` from
+ * `@parity/product-lab/env-attached`.
+ */
+export type EndpointProbe = (endpoints: {
+    chains: Partial<Record<TopologyChain, string>>;
+}, rpc: JsonRpcClient) => Promise<ProbedEndpoints>;
+/** SIGINT, 10 s to exit, then SIGKILL; a process still alive 5 s later fails the stop. */
+export declare const CHOPSTICKS_STOP: StopPolicy;
+export interface ChopsticksBinary {
+    bin: string;
+    version: string;
+    /** Its package manifest (the chopsticks-core it loads is found from here). */
+    packageJson: string;
+}
+/** The Chopsticks CLI: an explicit `bin`, or `@acala-network/chopsticks` resolvable from here. */
+export declare function resolveChopsticks(bin?: string): ChopsticksBinary;
+/** Internal package reader shared by explicit and package-resolved CLI paths. */
+export declare function readChopsticksPackage(packageJson: string, bin?: string): ChopsticksBinary;
+export interface ProcessConnections {
+    pid: number;
+    /** Remote ends of established TCP connections. */
+    remote: string[];
+    listening: string[];
+    nonLoopback: string[];
+}
+/** TCP connections of a process from `lsof` (macOS and Linux). */
+export declare function processConnections(pid: number, commands: CommandRunner): Promise<ProcessConnections>;
+export interface ChopsticksChainState {
+    chain: ChopsticksChain;
+    ws: string;
+    http: string;
+    upstream: UpstreamFacts;
+    /** Fork block as served by the fork itself at readiness. */
+    forkBlock: PinnedBlock;
+    readyMs: number;
+    authority?: AuthorityChange;
+}
+export interface ChopsticksEnvironment {
+    runId: string;
+    /** Present when the run had a version resolution: each runtime against its upstream at the pinned block. */
+    versions?: {
+        plan: ChopsticksVersionPlan;
+        check: ChopsticksVersionCheck;
+    };
+    plan: ChopsticksPlan;
+    chopsticks: ChopsticksBinary;
+    chains: Partial<Record<ChopsticksChain, ChopsticksChainState>>;
+    capabilities: Record<Capability, boolean>;
+    evidence: Record<Capability, string>;
+    offer: EnvironmentOffer;
+    endpoints: TopologyEndpoints;
+    access: EnvironmentAccess;
+    connections: ProcessConnections[];
+    manifestFile: string;
+    bootMs: number;
+    logs: string[];
+    /**
+     * Why the environment stopped working: a process exited, or Chopsticks
+     * could not fetch fork-block state because the upstream pruned it. Undefined while healthy.
+     */
+    failure(): string | undefined;
+    /** Follow events the spec shim rewrote, per chain. */
+    specRewrites(): Partial<Record<ChopsticksChain, number>>;
+    newBlock(chain: ChopsticksChain, count?: number): Promise<string>;
+    /** One JSON-RPC call to the fork of `chain` (its own loopback endpoint): reads for the time control (time.ts). */
+    call(chain: ChopsticksChain, method: string, params?: readonly unknown[]): Promise<unknown>;
+    setStorage(chain: ChopsticksChain, values: unknown): Promise<void>;
+    stop(): Promise<void>;
+}
+export interface StartChopsticksOptions {
+    /** Configs, logs, the process registry and the run manifest. */
+    runDir: string;
+    system: ChopsticksSystem;
+    /** Decides capabilities from the running forks (composed by the caller, for example env-attached's attachedProbe). */
+    probe: EndpointProbe;
+    readinessTimeoutMs?: number;
+    /** Resolved fork blocks to reuse (a reset starts again from exactly these). */
+    blocks?: Partial<Record<ChopsticksChain, PinnedBlock>>;
+    /** Refuse to continue when a process connects to a non-loopback address without allowPublicUpstream (default true). */
+    enforceConnections?: boolean;
+    /** Environment id recorded in the run manifest. */
+    environment?: string;
+    /**
+     * The run's version resolution (Phase 6): runtimes read from the network pin
+     * their chain's fork block, and the upstream must hold the resolved code
+     * there, or nothing starts (versions.ts).
+     */
+    versions?: VersionResolution;
+}
+/** Consecutive failed interval builds after which block production counts as broken. */
+export declare const INTERVAL_BUILD_FAILURES = 3;
+/**
+ * Build a block every `intervalMs`, skipping a tick while the previous build runs or once `halted()` says so. A
+ * failed build is retried at the next tick; INTERVAL_BUILD_FAILURES in a row are reported once through `fail`
+ * (the environment's `failure()`), so a chain that stopped producing blocks is not silent.
+ */
+export declare function buildBlocksEvery(intervalMs: number, build: () => Promise<unknown>, fail: (reason: string) => void, halted: () => boolean): NodeJS.Timeout;
+export declare function startChopsticks(input: ChopsticksOptions | ResolvedChopsticksOptions, options: StartChopsticksOptions): Promise<ChopsticksEnvironment>;

package/adapters/environment/chopsticks/src/environment.js

@@ -0,0 +1,358 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, statSync, statfsSync, writeFileSync } from "node:fs";
+import { generalExtrinsicRefusal, generalExtrinsicSupport } from "./general-extrinsic-support.js";
+import { sqliteSupport } from "./sqlite-support.js";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { LoopbackUrl } from "@parity/product-lab/domain";
+import { environmentAccess, } from "@parity/product-lab/domain";
+import { createRunManifest } from "@parity/product-lab/domain/lab";
+import { ALICE_ACCOUNT_KEY, SUDO_KEY, authorityWrites } from "./dev-authority.js";
+import { CHOPSTICKS_VERSION, parseChopsticksOptions } from "./options.js";
+import { chopsticksPlan } from "./plan.js";
+import { startSpecProxy } from "./spec-proxy.js";
+import { topologyOfOptions } from "./topology.js";
+import { inspectUpstream, rpcCall } from "./upstream.js";
+import { checkChopsticksVersions, chopsticksVersionPlan } from "./versions.js";
+export function requireChopsticksSystem(deps) {
+    const { processes, commands, ports, rpc, environment, runManifests } = deps;
+    if (processes && commands && ports && rpc && environment && runManifests)
+        return { processes, commands, ports, rpc, environment, runManifests };
+    const missing = Object.entries({ processes, commands, ports, rpc, environment, runManifests })
+        .filter(([, value]) => value === undefined)
+        .map(([name]) => name);
+    throw new Error(`The Chopsticks environment needs the lab's system ports (${missing.join(", ")} missing): pass them as defineLab({ system })`);
+}
+export const CHOPSTICKS_STOP = { signal: "SIGINT", graceMs: 10_000, killGraceMs: 5_000 };
+class Started {
+    name;
+    id;
+    process;
+    log;
+    exitCode;
+    constructor(name, id, process, log) {
+        this.name = name;
+        this.id = id;
+        this.process = process;
+        this.log = log;
+    }
+    get pid() {
+        return this.process.pid;
+    }
+    get exited() {
+        return this.exitCode !== undefined;
+    }
+}
+export function resolveChopsticks(bin) {
+    let packageJson;
+    if (bin) {
+        if (!existsSync(bin))
+            throw new Error(`Chopsticks CLI not found at ${bin}`);
+        packageJson = join(dirname(resolve(bin)), "package.json");
+    }
+    else {
+        try {
+            let directory = dirname(createRequire(import.meta.url).resolve("@acala-network/chopsticks"));
+            for (;;) {
+                const candidate = join(directory, "package.json");
+                if (existsSync(candidate) && JSON.parse(readFileSync(candidate, "utf8")).name === "@acala-network/chopsticks") {
+                    packageJson = candidate;
+                    break;
+                }
+                if (dirname(directory) === directory)
+                    throw new Error("package manifest is missing");
+                directory = dirname(directory);
+            }
+        }
+        catch {
+            throw new Error(`Chopsticks is an optional provider and is not installed. Add @acala-network/chopsticks@${CHOPSTICKS_VERSION} to your workspace, or pass bin (the path of its chopsticks.cjs)`);
+        }
+    }
+    return readChopsticksPackage(packageJson, bin);
+}
+export function readChopsticksPackage(packageJson, bin) {
+    const manifest = JSON.parse(readFileSync(packageJson, "utf8"));
+    if (manifest.name !== "@acala-network/chopsticks")
+        throw new Error(`${packageJson} is not @acala-network/chopsticks`);
+    if (manifest.version !== CHOPSTICKS_VERSION)
+        throw new Error(`Chopsticks ${manifest.version} found; this provider is verified with ${CHOPSTICKS_VERSION} only`);
+    const entry = typeof manifest.bin === "string" ? manifest.bin : (manifest.bin?.chopsticks ?? "chopsticks.cjs");
+    const executable = bin ? resolve(bin) : join(dirname(packageJson), entry);
+    if (!existsSync(executable) || !statSync(executable).isFile())
+        throw new Error(`Chopsticks CLI not found at ${executable}`);
+    return { bin: executable, version: manifest.version, packageJson };
+}
+async function requireFreePort(ports, port, owner) {
+    if (await ports.isFree(port))
+        return;
+    const holder = await ports.holder?.(port).catch(() => undefined);
+    throw new Error(`${owner} refuses occupied port ${port}${holder ? `: held by ${holder}` : ""}`);
+}
+export async function processConnections(pid, commands) {
+    let output = "";
+    const result = await commands.run({ command: "lsof", args: ["-nP", "-a", "-p", String(pid), "-i", "TCP"], timeoutMs: 5_000 });
+    if (result.code === 0)
+        output = result.stdout;
+    else if (result.code !== 1)
+        throw new Error(`lsof failed (${result.code}): ${result.stderr.trim()}`);
+    const lines = output.trim().split("\n").slice(1).filter(Boolean);
+    const remote = lines.map((line) => /->(\S+)/.exec(line)?.[1]).filter((value) => Boolean(value));
+    const listening = lines.filter((line) => line.includes("(LISTEN)")).map((line) => line.split(/\s+/).at(-2));
+    return { pid, remote, listening, nonLoopback: remote.filter((address) => !LoopbackUrl.isLoopbackAddress(address)) };
+}
+const tail = (file, lines = 30) => {
+    try {
+        return readFileSync(file, "utf8").split("\n").slice(-lines).join("\n");
+    }
+    catch {
+        return "";
+    }
+};
+export const INTERVAL_BUILD_FAILURES = 3;
+export function buildBlocksEvery(intervalMs, build, fail, halted) {
+    let building = false;
+    let failures = 0;
+    return setInterval(() => {
+        if (halted() || building)
+            return;
+        building = true;
+        build()
+            .then(() => (failures = 0), (error) => {
+            if (++failures === INTERVAL_BUILD_FAILURES)
+                fail(`${failures} interval block builds in a row failed; the last: ${error instanceof Error ? error.message : String(error)}`);
+        })
+            .finally(() => (building = false));
+    }, intervalMs);
+}
+export async function startChopsticks(input, options) {
+    const started = performance.now();
+    const { system } = options;
+    const httpRpc = rpcCall(system.rpc);
+    const resolved = parseChopsticksOptions(input);
+    const versionPlan = options.versions ? chopsticksVersionPlan(resolved, options.versions) : undefined;
+    if (versionPlan?.refusals.length)
+        throw new Error(`Chopsticks cannot honour this version resolution:\n${versionPlan.refusals.map((item) => `- ${item}`).join("\n")}`);
+    const binary = resolveChopsticks(resolved.bin);
+    const support = generalExtrinsicSupport(binary.packageJson);
+    if (!support.ok)
+        throw new Error(generalExtrinsicRefusal(support));
+    const sqlite = sqliteSupport(binary.packageJson);
+    if (sqlite.problem)
+        throw new Error(`Chopsticks refuses to start: ${sqlite.problem}`);
+    const runId = randomUUID();
+    mkdirSync(options.runDir, { recursive: true, mode: 0o700 });
+    mkdirSync(resolved.db, { recursive: true, mode: 0o700 });
+    const disk = statfsSync(resolved.db);
+    if (disk.bavail * disk.bsize < 1024 ** 3)
+        throw new Error("Chopsticks requires at least 1 GiB free disk space for its databases");
+    const versionCheck = versionPlan ? await checkChopsticksVersions(versionPlan, resolved.endpoints, httpRpc) : undefined;
+    if (versionCheck && !versionCheck.ok)
+        throw new Error(`Chopsticks cannot fork the resolved runtimes: ${versionCheck.problems.join("; ")}`);
+    const upstreams = {};
+    for (const chain of resolved.chains) {
+        const requested = options.blocks?.[chain]?.hash ?? versionPlan?.blocks[chain]?.hash ?? (resolved.block === "latest" ? "latest" : (resolved.block[chain] ?? "latest"));
+        upstreams[chain] = await inspectUpstream(chain, resolved.endpoints[chain], requested, httpRpc);
+    }
+    const genesisHashes = Object.values(upstreams).map((facts) => facts.genesis);
+    if (new Set(genesisHashes).size !== genesisHashes.length)
+        throw new Error("Two upstreams share a genesis");
+    const blocks = Object.fromEntries(resolved.chains.map((chain) => [chain, upstreams[chain].block]));
+    const registeredTypes = Object.fromEntries(resolved.chains.map((chain) => [chain, upstreams[chain].registeredTypes]));
+    const plan = chopsticksPlan(resolved, { directory: options.runDir, bin: binary.bin, blocks, version: binary.version, registeredTypes });
+    for (const chain of plan.chains) {
+        await requireFreePort(system.ports, chain.port, `Chopsticks ${chain.chain}`);
+        if (chain.chopsticksPort !== chain.port)
+            await requireFreePort(system.ports, chain.chopsticksPort, `Chopsticks ${chain.chain} (behind the spec shim)`);
+    }
+    for (const chain of plan.chains)
+        writeFileSync(chain.configFile, JSON.stringify(chain.config, null, 2) + "\n", { mode: 0o600 });
+    const processes = [];
+    let registry;
+    const proxies = new Map();
+    const timers = [];
+    let failure;
+    let stopping = false;
+    const stop = async () => {
+        stopping = true;
+        for (const timer of timers)
+            clearInterval(timer);
+        const errors = [];
+        for (const proxy of proxies.values())
+            await proxy.close().catch((error) => errors.push(error));
+        for (const owned of [...processes].reverse())
+            await registry.stop(owned.id).catch((error) => errors.push(error));
+        if (errors.length)
+            throw new AggregateError(errors, "Some Chopsticks processes did not stop");
+        registry?.close();
+    };
+    const env = { LOG_LEVEL: system.environment.get("CHOPSTICKS_LOG_LEVEL") ?? "info" };
+    try {
+        registry = system.processes.open(options.runDir);
+        for (const [index, spec] of plan.processes.entries()) {
+            const name = `chopsticks-${spec.chains.join("+")}`;
+            const id = `chopsticks-${spec.chains.join("_")}${index ? `-${index}` : ""}`;
+            const child = await registry.start(id, { command: process.execPath, args: spec.args, env: { ...env, ...spec.env }, stop: CHOPSTICKS_STOP });
+            const owned = new Started(name, id, child, registry.logFile(id));
+            processes.push(owned);
+            void child.exited.then((code) => {
+                owned.exitCode = code;
+                if (!stopping)
+                    failure ??= `${name} exited (${code}); last log lines:\n${tail(owned.log)}`;
+            });
+        }
+        if (plan.specCompat)
+            for (const chain of plan.chains)
+                proxies.set(chain.chain, await startSpecProxy(chain.port, chain.chopsticksPort));
+        const timeoutMs = options.readinessTimeoutMs ?? 180_000;
+        const chains = {};
+        await Promise.all(plan.chains.map(async (chain) => {
+            const owner = processes[plan.processes.findIndex((spec) => spec.chains.includes(chain.chain))];
+            const deadline = Date.now() + timeoutMs;
+            let lastError;
+            while (Date.now() < deadline) {
+                if (owner.exited)
+                    throw new Error(`Chopsticks for ${chain.chain} exited before readiness:\n${tail(owner.log)}`);
+                try {
+                    const runtime = (await httpRpc(chain.http, "state_getRuntimeVersion"));
+                    const forkHash = (await httpRpc(chain.http, "chain_getBlockHash", [chain.block.number]));
+                    if (forkHash !== chain.block.hash)
+                        throw new Error(`fork serves ${forkHash} at #${chain.block.number}, expected ${chain.block.hash}`);
+                    if (runtime.specName !== upstreams[chain.chain].specName && !resolved.wasmOverride?.[chain.chain])
+                        throw new Error(`fork serves ${runtime.specName}, upstream ${upstreams[chain.chain].specName}`);
+                    chains[chain.chain] = {
+                        chain: chain.chain,
+                        ws: chain.ws,
+                        http: chain.http,
+                        upstream: upstreams[chain.chain],
+                        forkBlock: chain.block,
+                        readyMs: Math.round(performance.now() - started),
+                    };
+                    return;
+                }
+                catch (error) {
+                    lastError = error;
+                    await delay(200);
+                }
+            }
+            throw new Error(`Chopsticks ${chain.chain} readiness timed out: ${String(lastError)}`);
+        }));
+        const connections = await Promise.all(processes.map((owned) => processConnections(owned.pid, system.commands)));
+        const unexpected = connections.flatMap((item) => item.nonLoopback);
+        if (unexpected.length && !resolved.allowPublicUpstream && options.enforceConnections !== false)
+            throw new Error(`Chopsticks connected to non-loopback addresses without allowPublicUpstream: ${unexpected.join(", ")}`);
+        if (resolved.devAuthority)
+            for (const chain of Object.values(chains)) {
+                const [account, sudo] = (await Promise.all([
+                    httpRpc(chain.http, "state_getStorage", [ALICE_ACCOUNT_KEY]),
+                    httpRpc(chain.http, "state_getStorage", [SUDO_KEY]),
+                ]));
+                const { writes, change } = authorityWrites(account, sudo);
+                if (writes.length)
+                    await httpRpc(chain.http, "dev_setStorage", [writes]);
+                chain.authority = change;
+            }
+        const probed = await options.probe({ chains: Object.fromEntries(Object.values(chains).map((chain) => [chain.chain, chain.ws])) }, system.rpc);
+        let policy = probed.policy;
+        const methods = await Promise.all(Object.values(chains).map(async (chain) => (await httpRpc(chain.http, "rpc_methods")).methods));
+        const devStorage = methods.every((list) => list.includes("dev_setStorage"));
+        policy = policy.with("devAuthority", {
+            available: resolved.devAuthority && devStorage,
+            reason: !resolved.devAuthority
+                ? "devAuthority: false (no development authority provisioned)"
+                : devStorage
+                    ? `every fork serves dev_setStorage on loopback; //Alice endowed where below ${"10^15"} and set as Sudo.Key where a Sudo key exists (${Object.values(chains)
+                        .map((chain) => `${chain.chain}: free ${chain.authority?.aliceFreeAfter}, sudo ${chain.authority?.sudoSetToAlice ? "set" : chain.authority?.sudoBefore ? "already Alice" : "none"}`)
+                        .join("; ")})`
+                    : "a fork does not serve dev_setStorage",
+        });
+        if (probed.chains.bulletin && !policy.has("bulletin"))
+            policy = policy.with("bulletin", { available: false, reason: `${policy.evidence.bulletin} (Chopsticks has no bitswap)` });
+        const capabilities = policy.capabilities;
+        const evidence = policy.evidence;
+        const endpoints = probed.endpoints;
+        const offer = {
+            chains: resolved.chains,
+            services: [],
+            capabilities: policy.offered(),
+            local: true,
+        };
+        if (resolved.blocks === "interval")
+            for (const chain of plan.chains)
+                timers.push(buildBlocksEvery(resolved.intervalMs, () => httpRpc(chain.http, "dev_newBlock"), (reason) => (failure ??= `Chopsticks ${chain.chain}: ${reason}`), () => failure !== undefined));
+        const bootMs = Math.round(performance.now() - started);
+        const manifestFile = join(options.runDir, "run-manifest.json");
+        options.system.runManifests.writeTo(manifestFile, createRunManifest(topologyOfOptions(resolved), new Date().toISOString(), {
+            runId,
+            ...(options.environment ? { environment: options.environment } : {}),
+            plan,
+            extra: {
+                chopsticks: binary,
+                upstreams,
+                publicUpstreams: plan.publicUpstreams,
+                allowPublicUpstream: resolved.allowPublicUpstream,
+                connections,
+                chains,
+                capabilities,
+                evidence,
+                bootMs,
+                ...(versionPlan && versionCheck && options.versions
+                    ? { versions: { resolution: options.versions.toJSON(), runtimes: versionCheck.runtimes, notApplicable: versionPlan.notApplicable, notes: versionPlan.notes } }
+                    : {}),
+            },
+        }));
+        return {
+            runId,
+            ...(versionPlan && versionCheck ? { versions: { plan: versionPlan, check: versionCheck } } : {}),
+            plan,
+            chopsticks: binary,
+            chains,
+            capabilities,
+            evidence,
+            offer,
+            endpoints,
+            access: environmentAccess({ capabilities: policy, endpoints }),
+            connections,
+            manifestFile,
+            bootMs,
+            logs: processes.map((owned) => owned.log),
+            failure: () => {
+                if (failure)
+                    return failure;
+                for (const owned of processes) {
+                    const recent = tail(owned.log, 400);
+                    const discarded = /State already discarded for (0x[\da-f]+)/.exec(recent);
+                    if (discarded)
+                        return `the upstream pruned the fork block's state (${discarded[1]}); Chopsticks can no longer fetch uncached keys and cannot build blocks that need them. Restart from a recent block or use an archive upstream`;
+                }
+                return undefined;
+            },
+            specRewrites: () => Object.fromEntries([...proxies].map(([chain, proxy]) => [chain, proxy.rewritten()])),
+            newBlock: async (chain, count = 1) => {
+                const target = chains[chain];
+                if (!target)
+                    throw new Error(`${chain} is not forked`);
+                return (await httpRpc(target.http, "dev_newBlock", [{ count }]));
+            },
+            call: async (chain, method, params = []) => {
+                const target = chains[chain];
+                if (!target)
+                    throw new Error(`${chain} is not forked`);
+                return httpRpc(target.http, method, [...params]);
+            },
+            setStorage: async (chain, values) => {
+                const target = chains[chain];
+                if (!target)
+                    throw new Error(`${chain} is not forked`);
+                await httpRpc(target.http, "dev_setStorage", [values]);
+            },
+            stop,
+        };
+    }
+    catch (error) {
+        await stop().catch(() => undefined);
+        throw error;
+    }
+}

package/adapters/environment/chopsticks/src/extensions.d.ts

@@ -0,0 +1,27 @@
+/** Extensions polkadot-js (@polkadot/types 16.5.6, bundled by Chopsticks 1.5.2) already knows. */
+export declare const POLKADOT_JS_KNOWN_EXTENSIONS: readonly string[];
+export interface ExtensionFacts {
+    identifier: string;
+    type: number;
+    additionalSigned: number;
+    typeIsUnit: boolean;
+    additionalSignedIsUnit: boolean;
+}
+/** Signed extensions of a runtime from its SCALE metadata (hex). */
+export declare function signedExtensions(metadataHex: string): ExtensionFacts[];
+/**
+ * Chopsticks `registered-types` declaring every extension polkadot-js does not
+ * know, typed from the runtime's own metadata. Undefined when nothing is unknown.
+ */
+export declare function registeredTypesFor(specName: string, extensions: readonly ExtensionFacts[]): {
+    typesBundle: {
+        spec: {
+            [specName]: {
+                signedExtensions: Record<string, {
+                    extrinsic: Record<string, string>;
+                    payload: Record<string, string>;
+                }>;
+            };
+        };
+    };
+} | undefined;

package/adapters/environment/chopsticks/src/extensions.js

@@ -0,0 +1,60 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { decAnyMetadata, unifyMetadata } from "@polkadot-api/substrate-bindings";
+export const POLKADOT_JS_KNOWN_EXTENSIONS = [
+    "ChargeTransactionPayment",
+    "CheckBlockGasLimit",
+    "CheckEra",
+    "CheckGenesis",
+    "CheckMetadataHash",
+    "CheckMortality",
+    "CheckNonZeroSender",
+    "CheckNonce",
+    "CheckSpecVersion",
+    "CheckTxVersion",
+    "CheckVersion",
+    "CheckWeight",
+    "LockStakingStatus",
+    "SkipCheckIfFeeless",
+    "ValidateEquivocationReport",
+    "WeightReclaim",
+    "LimitParathreadCommits",
+    "OnlyStakingAndClaims",
+    "PrevalidateAttests",
+    "RestrictFunctionality",
+    "TransactionCallFilter",
+    "ValidateDoubleVoteReports",
+    "DisallowSigned",
+    "ChargeAssetTxPayment",
+];
+export function signedExtensions(metadataHex) {
+    const metadata = unifyMetadata(decAnyMetadata(metadataHex));
+    const byId = new Map(metadata.lookup.map((entry) => [entry.id, entry]));
+    const isUnit = (id) => {
+        const entry = byId.get(id);
+        return !!entry && ["tuple", "composite"].includes(entry.def.tag) && Array.isArray(entry.def.value) && entry.def.value.length === 0;
+    };
+    const lists = Object.values(metadata.extrinsic.extensionsByVersion);
+    return (lists[0] ?? []).map((item) => ({
+        identifier: item.identifier,
+        type: item.type,
+        additionalSigned: item.additionalSigned,
+        typeIsUnit: isUnit(item.type),
+        additionalSignedIsUnit: isUnit(item.additionalSigned),
+    }));
+}
+const field = (identifier, suffix = "") => `${identifier[0].toLowerCase()}${identifier.slice(1)}${suffix}`;
+export function registeredTypesFor(specName, extensions) {
+    const signed = {};
+    for (const extension of extensions) {
+        if (POLKADOT_JS_KNOWN_EXTENSIONS.includes(extension.identifier))
+            continue;
+        signed[extension.identifier] = {
+            extrinsic: extension.typeIsUnit ? {} : { [field(extension.identifier)]: `Lookup${extension.type}` },
+            payload: extension.additionalSignedIsUnit ? {} : { [field(extension.identifier, "Implicit")]: `Lookup${extension.additionalSigned}` },
+        };
+    }
+    if (!Object.keys(signed).length)
+        return undefined;
+    return { typesBundle: { spec: { [specName]: { signedExtensions: signed } } } };
+}

package/adapters/environment/chopsticks/src/general-extrinsic-support.d.ts

@@ -0,0 +1,17 @@
+export declare const GENERAL_EXTRINSIC_FIXES = "AcalaNetwork/chopsticks #1078 and #1081";
+export interface GeneralExtrinsicSupport {
+    ok: boolean;
+    /** The chopsticks-core the CLI loads, and its version. */
+    core?: {
+        root: string;
+        version: string;
+    };
+    /** What is missing, each naming its upstream fix. */
+    missing: string[];
+}
+/** Check the chopsticks-core beside `chopsticksPackageJson` (synchronous: `product-lab check` and the plan ask). */
+export declare function generalExtrinsicSupport(chopsticksPackageJson: string): GeneralExtrinsicSupport;
+/** Check the chopsticks-core package at `root`. */
+export declare function chopsticksCoreSupport(root: string): GeneralExtrinsicSupport;
+/** The refusal for a Chopsticks without both fixes: why, and the choices. */
+export declare function generalExtrinsicRefusal(support: GeneralExtrinsicSupport): string;

package/adapters/environment/chopsticks/src/general-extrinsic-support.js

@@ -0,0 +1,58 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+export const GENERAL_EXTRINSIC_FIXES = "AcalaNetwork/chopsticks #1078 and #1081";
+const GENERAL = "0x0445";
+const SIGNED = "0x0484";
+const BIG_ENDIAN_LENGTH = /createType\(\s*['"]u32['"]\s*,\s*tx\.byteLength\s*\)\.toHex\(\)/;
+function coreRoot(chopsticksPackageJson) {
+    let directory = dirname(createRequire(chopsticksPackageJson).resolve("@acala-network/chopsticks-core"));
+    for (;;) {
+        const manifest = join(directory, "package.json");
+        if (existsSync(manifest) && JSON.parse(readFileSync(manifest, "utf8")).name === "@acala-network/chopsticks-core")
+            return directory;
+        if (dirname(directory) === directory)
+            throw new Error("its package manifest is missing");
+        directory = dirname(directory);
+    }
+}
+export function generalExtrinsicSupport(chopsticksPackageJson) {
+    let root;
+    try {
+        root = coreRoot(chopsticksPackageJson);
+    }
+    catch (error) {
+        return { ok: false, missing: [`@acala-network/chopsticks-core could not be found beside ${chopsticksPackageJson}: ${error instanceof Error ? error.message : String(error)}`] };
+    }
+    return chopsticksCoreSupport(root);
+}
+export function chopsticksCoreSupport(root) {
+    const version = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version ?? "unknown";
+    const file = (path) => {
+        const full = join(root, "dist/cjs", path);
+        return existsSync(full) ? readFileSync(full, "utf8") : "";
+    };
+    const missing = [];
+    let recognises = false;
+    try {
+        const utils = createRequire(join(root, "package.json"))(join(root, "dist/cjs/utils/index.js"));
+        recognises = typeof utils.isGeneralExtrinsic === "function" && utils.isGeneralExtrinsic(GENERAL) && !utils.isGeneralExtrinsic(SIGNED);
+    }
+    catch (error) {
+        missing.push(`its utils could not be loaded to check (${error instanceof Error ? error.message : String(error)})`);
+    }
+    if (!recognises || !file("blockchain/txpool.js").includes("isGeneralExtrinsic"))
+        missing.push("its transaction pool does not recognise a general (v5) extrinsic, so a transaction a truAPI 0.23 host builds is never included (#1078)");
+    if (BIG_ENDIAN_LENGTH.test(file("rpc/substrate/payment.js")))
+        missing.push("its fee queries pass the extrinsic length big-endian, so every fee is far too high (#1081)");
+    return { ok: missing.length === 0, core: { root, version }, missing };
+}
+export function generalExtrinsicRefusal(support) {
+    return [
+        `Chopsticks refuses to start: the installed @acala-network/chopsticks-core ${support.core?.version ?? ""}${support.core ? ` (${support.core.root})` : ""} lacks ${GENERAL_EXTRINSIC_FIXES}:`,
+        ...support.missing.map((item) => `- ${item}`),
+        `Use the local dev chain (Omni Node) instead, or a Chopsticks release that includes ${GENERAL_EXTRINSIC_FIXES}.`,
+    ].join("\n");
+}