@parity/product-lab 0.0.1-placeholder → 0.1.0

package/adapters/environment/attached/src/live-network.js

@@ -0,0 +1,96 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { HostNetworkRoutes, LoopbackUrl, RpcSelection } from "@parity/product-lab/domain";
+import { attachEnvironment } from "./index.js";
+export const LIVE_CHAINS = ["people", "asset-hub", "bulletin"];
+export const LIVE_RPC = { chains: ["relay", ...LIVE_CHAINS], role: "endpoint" };
+const describe = (runtime) => `${runtime.specName} ${runtime.specVersion}`;
+export function compareLiveRuntimes(live, reference) {
+    return Object.entries(live).map(([chain, runtime]) => {
+        const expected = reference?.runtimes[chain];
+        return {
+            chain,
+            live: describe(runtime),
+            ...(expected ? { reference: describe(expected), same: expected.specName === runtime.specName && expected.specVersion === runtime.specVersion } : {}),
+        };
+    });
+}
+export function liveRuntimesLine(rows, reference) {
+    if (!reference)
+        return `Live runtimes: ${rows.map((row) => `${row.chain} ${row.live}`).join(", ")} (no reference to compare with)`;
+    const differ = rows.filter((row) => row.same === false);
+    const shown = rows.map((row) => (row.reference === undefined ? `${row.chain} ${row.live} (not in the reference)` : row.same ? `${row.chain} ${row.live}` : `${row.chain} ${row.live}, ${reference.label} has ${row.reference}`));
+    return `${differ.length ? `Live runtimes differ from the ${reference.label} on ${differ.map((row) => row.chain).join(", ")}` : `Live runtimes match the ${reference.label}`}: ${shown.join("; ")}`;
+}
+export function liveNetworkEnvironment(options) {
+    const access = options.access ?? "read-only";
+    const marker = {
+        reason: options.reason,
+        network: options.network,
+        access,
+        ...(access === "read-write" && options.finalityTimeoutMs !== undefined ? { finalityTimeoutMs: options.finalityTimeoutMs } : {}),
+        ...(options.newIdentities ? { newIdentities: options.newIdentities } : {}),
+    };
+    return {
+        label: options.label,
+        description: options.description ??
+            (access === "read-write"
+                ? `The live ${options.network} network: scenarios write with the lab's existing accounts, and what they write stays; nothing resets`
+                : `The live ${options.network} network, read only: heads and finality, runtimes compared; the lab writes nothing`),
+        offer: { chains: [...LIVE_CHAINS], local: false, public: marker },
+        rpc: LIVE_RPC,
+        async start({ system, rpc: chosen }) {
+            const rpc = system?.rpc;
+            if (!rpc)
+                throw new Error(`${options.label} reads the live chains over the lab's JSON-RPC client (the start context's system ports); load the lab through the composition root`);
+            const defaults = Object.fromEntries(Object.entries(options.endpoints()).filter(([chain]) => LIVE_RPC.chains.includes(chain)));
+            const selection = (chosen ?? RpcSelection.empty).with("default", defaults);
+            const endpoints = Object.fromEntries(Object.entries(selection.urls()).map(([chain, url]) => [chain, url.replace(/^http(s?):\/\//, "ws$1://")]));
+            if (!endpoints.people)
+                throw new Error(`${options.label} names no People endpoint`);
+            const loopback = Object.entries(endpoints).filter(([, url]) => LoopbackUrl.test(url));
+            if (loopback.length)
+                throw new Error(`${options.label} is a live public network, but ${loopback.map(([chain, url]) => `${chain} ${url}`).join(", ")} ${loopback.length === 1 ? "is" : "are"} on this machine. Nothing was attached.`);
+            const chains = Object.fromEntries(LIVE_CHAINS.filter((chain) => endpoints[chain]).map((chain) => [chain, endpoints[chain]]));
+            const attached = await attachEnvironment({ chains }, { rpc });
+            const live = {};
+            if (endpoints.relay) {
+                const relay = await rpc.request(endpoints.relay, "state_getRuntimeVersion", [], { timeoutMs: 10_000 }).catch((error) => {
+                    throw new Error(`The relay endpoint ${endpoints.relay} did not answer, so nothing was attached: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+                });
+                live.relay = { specName: relay.specName, specVersion: relay.specVersion };
+            }
+            for (const [chain, info] of Object.entries(attached.chains))
+                live[chain] = { specName: info.specName, specVersion: info.specVersion };
+            const reference = options.reference?.();
+            const rows = compareLiveRuntimes(live, reference);
+            const services = options.services?.() ?? {};
+            const routes = HostNetworkRoutes.from({
+                network: options.network,
+                namespace: HostNetworkRoutes.namespaceOf(options.network),
+                chains: Object.fromEntries(Object.entries(attached.chains).map(([chain, info]) => [chain, { ws: info.ws, genesis: info.genesis }])),
+                ...(services.identityBackend ? { services: { "identity-backend": services.identityBackend } } : {}),
+                publicRoutes: { reason: options.reason },
+            });
+            return {
+                offer: { ...attached.offer, local: false, public: marker },
+                endpoints: { ...Object.fromEntries(Object.entries(attached.chains).map(([chain, info]) => [chain, info.ws])), ...(endpoints.relay ? { relay: endpoints.relay } : {}) },
+                routes,
+                provenance: {
+                    provider: "live",
+                    network: options.network,
+                    public: marker,
+                    chains: Object.fromEntries(Object.entries(attached.chains).map(([chain, info]) => [chain, { ws: info.ws, genesis: info.genesis, runtime: describe(info) }])),
+                    runtimes: { ...(reference ? { reference: reference.label } : {}), rows },
+                    evidence: attached.evidence,
+                },
+                rpc: selection.view(),
+                notices: [liveRuntimesLine(rows, reference)],
+                retention: { retention: "persistent", reason: `${options.network} is a live public network: the lab owns none of its state and resets nothing` },
+                snapshotsUnsupported: `${options.network} is a live public network: its state cannot be saved or restored`,
+                timeUnsupported: `${options.network} is a live public network: its chains advance on their own`,
+                close: async () => { },
+            };
+        },
+    };
+}

package/adapters/environment/attached/src/versions.d.ts

@@ -0,0 +1,29 @@
+import type { JsonRpcClient } from "@parity/product-lab/ports/system";
+import { type NotApplicableComponent, type RuntimeComparison, type VersionResolution } from "@parity/product-lab/domain/versions";
+import type { AttachedEnvironment } from "./index.js";
+export interface AttachedVersionRow extends RuntimeComparison {
+    id: string;
+    endpoint: string;
+    /** The finalized block the comparison read. */
+    at?: {
+        number: number;
+        hash: string;
+    };
+}
+export interface AttachedVersionCheck {
+    ok: boolean;
+    runtimes: AttachedVersionRow[];
+    notApplicable: NotApplicableComponent[];
+    /** Why the attachment must be refused (empty when `ok`). */
+    problems: string[];
+}
+/**
+ * Compare `resolution` with the attached chains. `network` is the network the
+ * attached chains belong to (for a fork of paseo-next-v2, `paseo-next-v2`).
+ */
+export declare function checkAttachedVersions(attached: AttachedEnvironment, resolution: VersionResolution, options: {
+    rpc: JsonRpcClient;
+    network: string;
+}): Promise<AttachedVersionCheck>;
+/** The attachment refused, naming every difference (for an environment's `start`). */
+export declare function assertAttachedVersions(check: AttachedVersionCheck): void;

package/adapters/environment/attached/src/versions.js

@@ -0,0 +1,51 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { ResolvedRuntime } from "@parity/product-lab/domain/versions";
+const CODE_KEY = "0x3a636f6465";
+export async function checkAttachedVersions(attached, resolution, options) {
+    const call = (url, method, params) => options.rpc.request(url, method, params, { timeoutMs: 10_000 });
+    const runtimes = [];
+    const notApplicable = [];
+    const problems = [];
+    for (const entry of resolution.components()) {
+        const id = entry.id.toString();
+        if (entry.id.kind !== "runtime") {
+            notApplicable.push({ id, reason: `a ${entry.id.kind}: an attached environment runs what is already running and installs nothing` });
+            continue;
+        }
+        const runtime = ResolvedRuntime.of(entry);
+        const chain = attached.chains[runtime.chain];
+        if (!chain) {
+            notApplicable.push({ id, reason: `the attached environment does not serve ${runtime.chain}` });
+            continue;
+        }
+        if (runtime.network !== undefined && runtime.network !== options.network) {
+            problems.push(`${id} was read from ${runtime.network}; the attached chains belong to ${options.network}`);
+            continue;
+        }
+        try {
+            const hash = (await call(chain.http, "chain_getFinalizedHead", []));
+            const [header, codeHash, version] = (await Promise.all([
+                call(chain.http, "chain_getHeader", [hash]),
+                call(chain.http, "state_getStorageHash", [CODE_KEY, hash]),
+                call(chain.http, "state_getRuntimeVersion", [hash]),
+            ]));
+            const comparison = runtime.compare({ codeHash: String(codeHash), specName: version.specName, specVersion: version.specVersion, genesis: chain.genesis });
+            const rowProblems = [...comparison.problems];
+            if (comparison.genesis.same === false)
+                rowProblems.push(`the attached ${runtime.chain} (${chain.ws}) is another chain: genesis ${comparison.genesis.actual}, the resolution's ${comparison.genesis.expected}`);
+            runtimes.push({ ...comparison, id, endpoint: chain.ws, at: { number: Number.parseInt(header.number, 16), hash }, ok: rowProblems.length === 0, problems: rowProblems });
+            problems.push(...rowProblems.map((problem) => `${runtime.chain} (${chain.ws}): ${problem}`));
+        }
+        catch (error) {
+            const problem = `the attached ${runtime.chain} (${chain.ws}) could not be read: ${error instanceof Error ? error.message : String(error)}`;
+            runtimes.push({ chain: runtime.chain, id, endpoint: chain.ws, ok: false, codeHash: { actual: "", matches: false }, spec: {}, genesis: {}, problems: [problem] });
+            problems.push(problem);
+        }
+    }
+    return { ok: problems.length === 0, runtimes, notApplicable, problems };
+}
+export function assertAttachedVersions(check) {
+    if (!check.ok)
+        throw new Error(`The attached network does not run the resolved runtimes, so it was not attached: ${check.problems.join("; ")}`);
+}

package/adapters/environment/chopsticks/README.md

@@ -0,0 +1,200 @@
+# @product-lab/env-chopsticks
+
+Optional environment provider: [Chopsticks](https://github.com/AcalaNetwork/chopsticks)
+(`@acala-network/chopsticks` 1.5.2) forks of chosen chains at pinned blocks. Engine
+(real nodes) stays the default and relay-less omni-node the fast genesis lane;
+Chopsticks adds what neither can do today: fork a chain subset, at a pinned
+block, in seconds, with a small database, and with a replaced runtime
+(`wasmOverride`) for upgrade tests.
+
+```ts
+import { chopsticks, localEngineUpstream } from "@product-lab/env-chopsticks";
+import { attachedProbe } from "@product-lab/env-attached";
+
+const upstream = localEngineUpstream(); // an owned Engine fork on its default ports: ws://127.0.0.1:10010/10020/10030
+const system = nodeSystem(); // the Node system adapters (@product-lab/system-node), built by the caller
+defineLab({
+  environments: {
+    pinned: chopsticks(
+      {
+        chains: ["people", "asset-hub"],
+        endpoints: { people: upstream.people, "asset-hub": upstream["asset-hub"] },
+        block: { people: 651203 },          // or "latest" (resolved hash recorded)
+        db: ".product-lab/environments/chopsticks",
+        ports: { people: 15510, "asset-hub": 15520 },
+      },
+      { probe: attachedProbe, system },
+    ),
+  },
+  // …
+});
+```
+
+The same run as a topology entry, resolved and started by this package's adapter factory. The
+composition root constructs the factory with `probe: attachedProbe` and passes its Node system
+ports (`composition/src/adapter-catalogue.ts`); a lab only selects the adapter and its settings:
+
+```ts
+defineLab({
+  environments: {
+    pinned: chopsticksTopology({ chains: ["people"], chopsticks: { upstream: { people: "ws://127.0.0.1:10010" }, block: { people: 651203 } } }),
+  },
+  environmentAdapters: { chopsticks: { db: ".product-lab/environments/chopsticks" /* , bin: ".../chopsticks.cjs" */ } },
+  // …
+});
+```
+
+Without the composition root (tests, a consumer's own wiring) the lab registers
+`new ChopsticksEnvironmentFactory({ probe: attachedProbe, db })` in `environmentFactories` and gives
+the system ports as `defineLab({ system })`.
+
+Composition (refactor step 7): what a running fork offers is decided by a capability probe the
+caller supplies (`probe`, an `EndpointProbe`; the composition root passes env-attached's `attachedProbe`), so this
+adapter imports no other adapter. The system ports (the composition root's, or `defineLab({ system })`) come through
+`create(topology, deps)` (or `chopsticks(options, { probe, system })`): `processes` (every
+Chopsticks process recorded in a registry in the run directory, id
+`chopsticks-<chains joined by _>[-<n>]`, stopped with `CHOPSTICKS_STOP`: SIGINT, 10 s, then
+SIGKILL, 5 s), `commands` (bounded `lsof` connection inspection), `ports` (every port checked before anything starts), `rpc` (upstream checks,
+readiness, the development authority, block building), `environment` (`CHOPSTICKS_LOG_LEVEL`) and
+`runManifests` (the run manifest, `<run directory>/run-manifest.json`, built by the domain's redacting
+`createRunManifest` with an adapter-owned timestamp and written with `writeTo`). A start without them is refused and names what is
+missing (`requireChopsticksSystem`). The adapter's own process spawning, port probe, JSON-RPC
+client and run-manifest writer are deleted.
+
+The same selection is available as `product-lab env show --profile chopsticks --upstream people=ws://… --pin people=651203`.
+`examples/notes` (`chopsticks`) runs its E2E and lab window this way.
+
+Each launch plan removes inherited `PORT` and, as a precaution, `PORTS` and `PORT_LAST` before
+starting the CLI. Single-chain commands also pass `--port` explicitly (the port behind the spec
+shim when enabled). Chopsticks applies `PORT` after both config and command-line options, so
+passing `--port` alone does not isolate a fork from its parent. XCM takes each chain's port from
+its own config; removing the variables also keeps its child environment isolated.
+The regression in `tools/verify/tests/chopsticks-inherited-port.test.ts` reaches the real launch
+call and checks the overrides it receives. It also runs the installed CLI's parsing through the
+Node runner with and without the shim: single-chain cases check the selected port and absence
+of all three variables, and XCM cases check its configured ports and absence of those variables.
+Only the CLI's server-start boundary is replaced, so no chain or listener starts.
+
+## Deny by default
+
+Chopsticks reads every storage key it has not cached from its upstream, for the
+whole run. Upstreams are therefore required and must be loopback; a public RPC
+needs `allowPublicUpstream: true` and is recorded in the run manifest. After
+readiness the provider lists the TCP connections of every Chopsticks process
+(`lsof`) and refuses to continue if one leaves loopback without that opt-in.
+The connection listing has a 5 s command timeout and surfaces other `lsof` failures.
+
+A pruned upstream only serves the fork block's state while it is within its
+pruning window (local Engine forks run `--state-pruning 256`: about 9 minutes
+for Asset Hub, 25 for People and Bulletin). `failure()` reports it once
+Chopsticks logs that the upstream discarded the state. The provider refuses an already-pruned block at
+start; a longer run, or an older pinned block, needs an archive upstream.
+
+## What it offers (verified live; see the verification record)
+
+| | Result |
+| --- | --- |
+| Blocks | `instant` (block per transaction), `batch`, `manual` (`dev_newBlock`), `interval` (provider timer; a failed build is retried at the next tick, and three failures in a row are reported through `failure()`, `buildBlocksEvery`). Finalized head = best head immediately |
+| truAPI host | notes E2E passed on a People fork (supplied wallet); a second product SPA (its develop branch) showed an existing identity's card on three forks |
+| polkadot-api | `chainHead_v1` finalized subscription and `transaction_v1` transfers watched to finality, on People and Asset Hub |
+| XCM | several chains run in Chopsticks' XCM mode: HRMP between the forks (Asset Hub → People teleport verified) |
+| `contracts`, `dotns` | Asset Hub runtime APIs and forked DotNS state (re-probed at start) |
+| `devAuthority` | `dev_setStorage`; `//Alice` endowed and made `Sudo.Key` where missing |
+| Time (backlog 16) | `RunningEnvironment.time` (`chopsticksTime`, `src/time.ts`): `advanceBlocks` builds blocks on request with `dev_newBlock` (calls of at most 25 blocks, inside the JSON-RPC timeout); `advanceClock` builds the blocks whose stamps cover the time asked for, since the fork stamps each block one slot after its parent (12 s on People; 2 minutes took 10 blocks in 5.6 s). Refused: a build that adds no block, a clock that does not move with a block. `tests/time.test.ts` |
+| Not offered | statement store (no `statement_*`), Bulletin retrieval (no `bitswap_v1_get`), eth-rpc, identity backend, `dev_timeTravel` (stops block production on these parachains; time moves by building blocks instead) |
+
+Three workarounds are applied automatically:
+- `allow-unresolved-imports`: the People runtime imports statement-store host
+  functions Chopsticks lacks.
+- Generated `registered-types` for the custom signed extensions polkadot-js
+  does not know. Without them, Chopsticks rejects every signed Asset Hub
+  transaction.
+- A JSON-RPC spec shim on each chain's port, with Chopsticks on port + 1
+  (`specCompat`, default on). It rewrites the runtime field of
+  `chainHead_v1_follow` events into the spec's `{ type: "valid", spec }`.
+  Without it, the truAPI host cannot follow a Chopsticks chain. A forwarded
+  HTTP request is bounded (`startSpecProxy(port, target, { requestTimeoutMs })`,
+  default 120 000 ms): an upstream that does not answer in time gets the caller
+  a JSON-RPC 502 naming the cause (`tests/spec-proxy.test.ts`).
+
+Chopsticks is an optional peer dependency: install `@acala-network/chopsticks@1.5.2`
+in the consuming workspace, or pass `bin` (the path of its `chopsticks.cjs`).
+This repository installs that pinned CLI as this adapter's development dependency.
+`resolveChopsticks` locates its package manifest from the package entry because
+the CLI's wildcard export does not expose `package.json` directly. Notes starts
+a local relay-less People upstream when its Chopsticks environment is selected;
+it needs no separately running full fork.
+
+Inside this repository Bun installs `@acala-network/chopsticks-core` 1.5.2 with a patch:
+the published pool throws on a V5 general extrinsic,
+the kind a truAPI 0.23.0 host builds for People, so such a transaction is never included, and its fee queries
+overprice every extrinsic. The patch is the port of AcalaNetwork/chopsticks #1078 and #1081, both merged upstream on
+6 October 2026 and not yet in a release (npm `latest` is 1.5.2, checked 27 October 2026).
+
+**In a product.** `@parity/product-lab` does not ship this patch: npm never applies a dependency's
+`patchedDependencies`. A product that installs `@acala-network/chopsticks@1.5.2` (the optional peer) gets the
+unpatched core, and the Chopsticks environment refuses to start. It refuses before it starts a process or writes a
+file, with the message below, naming #1078 and #1081. A transaction can never look submitted on a Chopsticks that
+would drop it. Use the local dev chain or a copy of Paseo until a Chopsticks release carries both fixes. Chopsticks is
+not part of 0.1.0. Measured in a clean npm
+consumer of the release pack on 27 October 2026, with the lab's patched core as the control.
+
+A Chopsticks without both fixes is refused before anything starts (`src/general-extrinsic-support.ts`): the factory's
+`problems()` says so, so `product-lab check` reports the environment as unable to start and a suite plan skips it, and
+`start` throws the same message. The message names what is missing and the two ways on: a relay-less environment, or a
+Chopsticks release that includes #1078 and #1081.
+
+The check reads what the installed `@acala-network/chopsticks-core` (the one the CLI loads) does and contains, not its
+version, so a later release carrying both fixes passes without a change here:
+- #1078: its `isGeneralExtrinsic` tells a general (v5) extrinsic from a signed (v4) one by the preamble byte, and its
+  transaction pool uses it;
+- #1081: its fee queries no longer pass the length as `createType('u32', length).toHex()` (big-endian).
+
+A version check would refuse such a release until this package learned its number, and would pass a patched 1.5.2
+only by trusting the install. Tests: `tests/general-extrinsic-support.test.ts` (the installed core passes; a temporary
+copy with the patch reversed is refused, and one with only #1081 reversed names only that).
+
+Chopsticks keeps each chain's database in SQLite (`--db`, through `@acala-network/chopsticks-db` and typeorm), and
+sqlite3 works only with its native build, which its install script makes. Since backlog 227 (8 October 2026) the lab
+follows the installed tree as Chopsticks loads it (chopsticks-db, typeorm, sqlite3) and refuses a sqlite3 without
+`build/Release/node_sqlite3.node` before anything starts, in `problems()` and at the start: "sqlite3 has no native build
+(…), so Chopsticks cannot open its database; run bun run setup (in product-lab's checkout), or npm rebuild sqlite3 (in a
+product)" (`src/sqlite-support.ts`: `sqliteSupport`, `SQLITE_NATIVE_BUILD`, `SQLITE_FIX`). Before, Chopsticks exited
+before readiness with typeorm's `DriverPackageNotInstalledError`. Tests: `tests/sqlite-support.test.ts` (a fake tree
+without the build refused, with it planted passing; the installed sqlite3 has its build).
+
+Live scripts (in `tools/verify/live/chopsticks/` since step 7, wired to the Node system
+adapters and `attachedProbe`): `run-environment.ts` (boot, probes, measurements),
+`upstream-window.ts` (pruned upstream window), `wasm-override.ts`
+(runtime override and `set_code`), `provider-lifecycle.ts` (start, reset,
+close).
+
+## Version resolutions (Phase 6)
+
+With `EnvironmentStartContext.versions` (or `startChopsticks(..., { versions })`), `src/versions.ts`:
+`chopsticksVersionPlan(options, resolution)` pins each chain whose runtime was read from the network
+(`deployed`, or a lock entry made from one) to the resolved block, and refuses a conflicting
+`chopsticks.block`, a `wasmOverride` for that chain, a released or git runtime (Chopsticks forks
+what the upstream ran; unsupported) and a resolved binary. `checkChopsticksVersions` then reads each
+pinned block from its upstream before any inspection or process: the upstream must have the
+resolution's genesis (a fork keeps its upstream's), know the block at that number, and hold the
+resolved `:code` hash there; otherwise nothing starts. A reset restarts from the same pinned blocks
+with the same checks. The run manifest's `extra.versions` and the provenance record each runtime's
+comparison.
+
+## Package
+
+| | |
+| --- | --- |
+| Nx project | `env-chopsticks` |
+| Tags | `scope:provider`, `type:adapter` |
+| Exports | `src/index.ts`: `chopsticks`, `ChopsticksEnvironmentFactory`, `chopsticksTopology`, `resolveChopsticksTopology`, options (`parseChopsticksOptions`, `chopsticksOptionsSchema`, `chopsticksTopologyOptionsSchema`, `CHOPSTICKS_FLAGS`, `localEngineUpstream`, `CHOPSTICKS_VERSION`), `chopsticksPlan`, `startChopsticks`, `ChopsticksSystem`, `requireChopsticksSystem`, `CHOPSTICKS_STOP`, `EndpointProbe`, `ProbedEndpoints`, the spec shim (`startSpecProxy`), dev-authority and signed-extension helpers, `chopsticksVersionPlan`, `checkChopsticksVersions` (Phase 6), `generalExtrinsicSupport`, `chopsticksCoreSupport`, `generalExtrinsicRefusal` (the #1078/#1081 check), `chopsticksTime`, `chainMoment`, `decodeMoment`, `TIMESTAMP_NOW_KEY` (backlog 16) |
+| Implements | `TopologyAdapterFactory` (`ChopsticksEnvironmentFactory`, `@product-lab/ports/environment`) and a `TopologyEnvironment` (`chopsticks()`, also `@product-lab/ports/environment`, re-exported by `@product-lab/core`); takes `ProcessRunner`, `CommandRunner`, `PortAllocator`, `JsonRpcClient` and `EnvironmentVariables` from `@product-lab/ports/system` and `RunManifestStore` from `@product-lab/ports/storage` |
+| Depends on | `@product-lab/domain` (topology vocabulary and functions, `DEVELOPMENT_AUTHORITY`, `@product-lab/domain/versions`), `@product-lab/ports`, `ws`, `zod` (its own copy of the shared topology options schema, `src/topology-options-schema.ts`, kept the same by the environment contract kit's `malformed-throws` case); peer `@acala-network/chopsticks` 1.5.2 (optional for consumers, installed for repository development). No other adapter (env-attached's two imports removed in step 7) |
+| Used by | the composition root (`composition/src/adapter-catalogue.ts`), `examples/notes` (`chopsticks`), `tools/verify` (live scripts, `env show`) |
+
+Contract kit: `tests/contract.test.ts` runs the [environment contract kit](../../../contracts/environment/README.md), declaring `topology`, `profiles`, `flags` and `endpointOptions`. The `lifecycle` and `reset` cases start real forks through the Node system ports and `attachedProbe`: since step 7 they run from `tools/verify/tests/environment-contract-live.test.ts`, only with `PRODUCT_LAB_KIT_LIVE=1` and `PRODUCT_LAB_KIT_CHOPSTICKS_UPSTREAM` (not run by the gates).
+
+Tests: `bunx nx run env-chopsticks:test` (no Chopsticks process, no chain; `tests/system-fakes.ts` has a probe that must not be reached).
+
+The factory reports missing or wrong-version Chopsticks packages, and a chopsticks-core without the general-extrinsic fixes, through `problems()` before a switch is offered. This only checks the local CLI/package; it does not claim the upstream is reachable or the chain is ready.

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

@@ -0,0 +1,140 @@
+import type { Topology, TopologyOptions } from "@parity/product-lab/domain";
+import type { TopologyEnvironment } from "@parity/product-lab/ports/environment";
+import type { TopologyAdapterFactory, TopologyProfile } from "@parity/product-lab/ports/environment";
+import type { AdapterFlagValues } from "@parity/product-lab/ports/factory";
+import type { SystemPorts } from "@parity/product-lab/ports/system";
+import { type ChopsticksEnvironmentSettings } from "./provider.js";
+export declare class ChopsticksEnvironmentFactory implements TopologyAdapterFactory<TopologyEnvironment, Partial<SystemPorts>> {
+    private readonly settings;
+    readonly kind = "chopsticks";
+    readonly label = "Chopsticks forks of chosen chains at pinned blocks";
+    readonly section = "chopsticks";
+    readonly options: import("zod").ZodObject<{
+        network: import("zod").ZodDefault<import("zod").ZodEnum<{
+            "paseo-next-v2": "paseo-next-v2";
+            previewnet: "previewnet";
+        }>>;
+        chains: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodEnum<{
+            bulletin: "bulletin";
+            people: "people";
+            "asset-hub": "asset-hub";
+            "web3-storage": "web3-storage";
+        }>>>;
+        relay: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        state: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodObject<{
+            fork: import("zod").ZodUnion<readonly [import("zod").ZodLiteral<"snapshot">, import("zod").ZodLiteral<"deployed">, import("zod").ZodObject<{
+                block: import("zod").ZodNumber;
+            }, import("zod/v4/core").$strict>]>;
+        }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
+            genesis: import("zod").ZodLiteral<true>;
+        }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
+            workspace: import("zod").ZodString;
+        }, import("zod/v4/core").$strict>]>>;
+        runtimes: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodEnum<{
+            bulletin: "bulletin";
+            people: "people";
+            "asset-hub": "asset-hub";
+            "web3-storage": "web3-storage";
+        }> & import("zod/v4/core").$partial, import("zod").ZodUnion<readonly [import("zod").ZodLiteral<"locked">, import("zod").ZodLiteral<"deployed">, import("zod").ZodObject<{
+            wasm: import("zod").ZodString;
+        }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
+            spec: import("zod").ZodString;
+        }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
+            release: import("zod").ZodString;
+        }, import("zod/v4/core").$strict>]>>>;
+        binaries: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnion<readonly [import("zod").ZodLiteral<"locked">, import("zod").ZodObject<{
+            path: import("zod").ZodString;
+        }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
+            release: import("zod").ZodString;
+        }, import("zod/v4/core").$strict>]>>>;
+        nodeArgs: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodEnum<{
+            bulletin: "bulletin";
+            people: "people";
+            "asset-hub": "asset-hub";
+            "web3-storage": "web3-storage";
+        }> & import("zod/v4/core").$partial, import("zod").ZodArray<import("zod").ZodString>>>;
+        blockTime: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodRecord<import("zod").ZodEnum<{
+            bulletin: "bulletin";
+            people: "people";
+            "asset-hub": "asset-hub";
+            "web3-storage": "web3-storage";
+        }> & import("zod/v4/core").$partial, import("zod").ZodNumber>]>>;
+        genesisEdits: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodEnum<{
+            bulletin: "bulletin";
+            people: "people";
+            "asset-hub": "asset-hub";
+            "web3-storage": "web3-storage";
+        }> & import("zod/v4/core").$partial, import("zod").ZodObject<{
+            sudo: import("zod").ZodOptional<import("zod").ZodString>;
+            endow: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>>;
+            patch: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>;
+            storage: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>>;
+        }, import("zod/v4/core").$strict>>>;
+        statementStore: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        services: import("zod").ZodOptional<import("zod").ZodObject<{
+            identityBackend: import("zod").ZodOptional<import("zod").ZodBoolean>;
+            ethRpc: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        }, import("zod/v4/core").$strict>>;
+        ports: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodEnum<{
+            bulletin: "bulletin";
+            people: "people";
+            "asset-hub": "asset-hub";
+            "web3-storage": "web3-storage";
+            ethRpc: "ethRpc";
+            identityBackend: "identityBackend";
+            dashboard: "dashboard";
+        }> & import("zod/v4/core").$partial, import("zod").ZodNumber>>;
+        provider: import("zod").ZodOptional<import("zod").ZodLiteral<"chopsticks">>;
+        chopsticks: import("zod").ZodObject<{
+            upstream: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodEnum<{
+                bulletin: "bulletin";
+                people: "people";
+                "asset-hub": "asset-hub";
+                "web3-storage": "web3-storage";
+            }> & import("zod/v4/core").$partial, import("zod").ZodURL>>;
+            block: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodLiteral<"latest">, import("zod").ZodRecord<import("zod").ZodEnum<{
+                bulletin: "bulletin";
+                people: "people";
+                "asset-hub": "asset-hub";
+                "web3-storage": "web3-storage";
+            }> & import("zod/v4/core").$partial, import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodString]>>]>>;
+            allowPublicUpstream: import("zod").ZodOptional<import("zod").ZodBoolean>;
+            blocks: import("zod").ZodOptional<import("zod").ZodEnum<{
+                instant: "instant";
+                batch: "batch";
+                manual: "manual";
+                interval: "interval";
+            }>>;
+            db: import("zod").ZodOptional<import("zod").ZodString>;
+            storage: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodEnum<{
+                bulletin: "bulletin";
+                people: "people";
+                "asset-hub": "asset-hub";
+                "web3-storage": "web3-storage";
+            }> & import("zod/v4/core").$partial, import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>>;
+            devAuthority: import("zod").ZodOptional<import("zod").ZodBoolean>;
+            xcm: import("zod").ZodOptional<import("zod").ZodBoolean>;
+            specCompat: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        }, import("zod/v4/core").$strict>;
+    }, import("zod/v4/core").$strict>;
+    readonly flags: readonly import("@parity/product-lab/ports").AdapterFlag[];
+    readonly profiles: readonly TopologyProfile[];
+    constructor(settings: ChopsticksEnvironmentSettings);
+    /** Only options carrying its `chopsticks` section (or naming it as provider) are Chopsticks topologies. */
+    accepts(_options: TopologyOptions): boolean;
+    profile(name: string, options: TopologyOptions): TopologyOptions;
+    withFlags(values: AdapterFlagValues, options: TopologyOptions): TopologyOptions;
+    resolve(options: TopologyOptions): Topology;
+    /** What stops a Chopsticks environment before it starts: no CLI, one without the general-extrinsic fixes, or no sqlite3 build. */
+    problems(): readonly string[];
+    describe(topology: Topology): {
+        label: string;
+        description: string;
+    };
+    /**
+     * The environment serving `topology`. Its start refuses what the topology's
+     * rules refuse (one rule set) and needs the lab's `processes`, `ports`, `rpc`
+     * and `environment` (`defineLab({ system })`).
+     */
+    create(topology: Topology, deps: Partial<SystemPorts>): TopologyEnvironment;
+}

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

@@ -0,0 +1,55 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { CHOPSTICKS_FLAGS, CHOPSTICKS_KIND, chopsticksFlagOptions, chopsticksProfileOptions, chopsticksTopologyOptionsSchema, resolveChopsticksTopology, } from "./chopsticks-topology.js";
+import { chopsticks, describeChopsticks } from "./provider.js";
+import { resolveChopsticks } from "./environment.js";
+import { generalExtrinsicRefusal, generalExtrinsicSupport } from "./general-extrinsic-support.js";
+import { sqliteSupport } from "./sqlite-support.js";
+import { chopsticksOptionsFromTopology } from "./topology.js";
+export class ChopsticksEnvironmentFactory {
+    settings;
+    kind = CHOPSTICKS_KIND;
+    label = "Chopsticks forks of chosen chains at pinned blocks";
+    section = "chopsticks";
+    options = chopsticksTopologyOptionsSchema;
+    flags = CHOPSTICKS_FLAGS;
+    profiles = [
+        { name: "chopsticks", description: "Chopsticks forks of --chains (default people) from explicit --upstream endpoints at pinned blocks" },
+    ];
+    constructor(settings) {
+        this.settings = settings;
+    }
+    accepts(_options) {
+        return false;
+    }
+    profile(name, options) {
+        return chopsticksProfileOptions(name, options);
+    }
+    withFlags(values, options) {
+        return chopsticksFlagOptions(values, options);
+    }
+    resolve(options) {
+        return resolveChopsticksTopology(options);
+    }
+    problems() {
+        let binary;
+        try {
+            binary = resolveChopsticks(this.settings.bin);
+        }
+        catch (error) {
+            return [error instanceof Error ? error.message : String(error)];
+        }
+        const support = generalExtrinsicSupport(binary.packageJson);
+        const sqlite = sqliteSupport(binary.packageJson);
+        return [...(support.ok ? [] : [generalExtrinsicRefusal(support)]), ...(sqlite.problem ? [sqlite.problem] : [])];
+    }
+    describe(topology) {
+        return describeChopsticks(topology);
+    }
+    create(topology, deps) {
+        const t = topology;
+        const db = this.settings.db ?? t.chopsticks.db ?? ".product-lab/chopsticks";
+        const options = chopsticksOptionsFromTopology(t, { db, ...(this.settings.bin ? { bin: this.settings.bin } : {}) });
+        return { ...chopsticks(options, { probe: this.settings.probe, system: deps }), topology: t };
+    }
+}