@parity/product-lab 0.0.1-placeholder → 0.1.0

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

@@ -0,0 +1,176 @@
+import { z } from "zod";
+import { type Topology, type TopologyChain, type TopologyOptions } from "@parity/product-lab/domain";
+import type { AdapterFlag, AdapterFlagValues } from "@parity/product-lab/ports/factory";
+/** The adapter kind, recorded as `Topology.provider`. */
+export declare const CHOPSTICKS_KIND = "chopsticks";
+/** The `chopsticks` section: fork chosen chains of an upstream at pinned blocks. */
+export declare const chopsticksSection: z.ZodObject<{
+    upstream: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        bulletin: "bulletin";
+        people: "people";
+        "asset-hub": "asset-hub";
+        "web3-storage": "web3-storage";
+    }> & z.core.$partial, z.ZodURL>>;
+    block: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"latest">, z.ZodRecord<z.ZodEnum<{
+        bulletin: "bulletin";
+        people: "people";
+        "asset-hub": "asset-hub";
+        "web3-storage": "web3-storage";
+    }> & z.core.$partial, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>]>>;
+    allowPublicUpstream: z.ZodOptional<z.ZodBoolean>;
+    blocks: z.ZodOptional<z.ZodEnum<{
+        instant: "instant";
+        batch: "batch";
+        manual: "manual";
+        interval: "interval";
+    }>>;
+    db: z.ZodOptional<z.ZodString>;
+    storage: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        bulletin: "bulletin";
+        people: "people";
+        "asset-hub": "asset-hub";
+        "web3-storage": "web3-storage";
+    }> & z.core.$partial, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    devAuthority: z.ZodOptional<z.ZodBoolean>;
+    xcm: z.ZodOptional<z.ZodBoolean>;
+    specCompat: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+/** The shared topology options plus the `chopsticks` section. */
+export declare const chopsticksTopologyOptionsSchema: z.ZodObject<{
+    network: z.ZodDefault<z.ZodEnum<{
+        "paseo-next-v2": "paseo-next-v2";
+        previewnet: "previewnet";
+    }>>;
+    chains: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        bulletin: "bulletin";
+        people: "people";
+        "asset-hub": "asset-hub";
+        "web3-storage": "web3-storage";
+    }>>>;
+    relay: z.ZodOptional<z.ZodBoolean>;
+    state: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        fork: z.ZodUnion<readonly [z.ZodLiteral<"snapshot">, z.ZodLiteral<"deployed">, z.ZodObject<{
+            block: z.ZodNumber;
+        }, z.core.$strict>]>;
+    }, z.core.$strict>, z.ZodObject<{
+        genesis: z.ZodLiteral<true>;
+    }, z.core.$strict>, z.ZodObject<{
+        workspace: z.ZodString;
+    }, z.core.$strict>]>>;
+    runtimes: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        bulletin: "bulletin";
+        people: "people";
+        "asset-hub": "asset-hub";
+        "web3-storage": "web3-storage";
+    }> & z.core.$partial, z.ZodUnion<readonly [z.ZodLiteral<"locked">, z.ZodLiteral<"deployed">, z.ZodObject<{
+        wasm: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        spec: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        release: z.ZodString;
+    }, z.core.$strict>]>>>;
+    binaries: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"locked">, z.ZodObject<{
+        path: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        release: z.ZodString;
+    }, z.core.$strict>]>>>;
+    nodeArgs: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        bulletin: "bulletin";
+        people: "people";
+        "asset-hub": "asset-hub";
+        "web3-storage": "web3-storage";
+    }> & z.core.$partial, z.ZodArray<z.ZodString>>>;
+    blockTime: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodRecord<z.ZodEnum<{
+        bulletin: "bulletin";
+        people: "people";
+        "asset-hub": "asset-hub";
+        "web3-storage": "web3-storage";
+    }> & z.core.$partial, z.ZodNumber>]>>;
+    genesisEdits: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        bulletin: "bulletin";
+        people: "people";
+        "asset-hub": "asset-hub";
+        "web3-storage": "web3-storage";
+    }> & z.core.$partial, z.ZodObject<{
+        sudo: z.ZodOptional<z.ZodString>;
+        endow: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        patch: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        storage: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>>>;
+    statementStore: z.ZodOptional<z.ZodBoolean>;
+    services: z.ZodOptional<z.ZodObject<{
+        identityBackend: z.ZodOptional<z.ZodBoolean>;
+        ethRpc: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    ports: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        bulletin: "bulletin";
+        people: "people";
+        "asset-hub": "asset-hub";
+        "web3-storage": "web3-storage";
+        ethRpc: "ethRpc";
+        identityBackend: "identityBackend";
+        dashboard: "dashboard";
+    }> & z.core.$partial, z.ZodNumber>>;
+    provider: z.ZodOptional<z.ZodLiteral<"chopsticks">>;
+    chopsticks: z.ZodObject<{
+        upstream: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+            bulletin: "bulletin";
+            people: "people";
+            "asset-hub": "asset-hub";
+            "web3-storage": "web3-storage";
+        }> & z.core.$partial, z.ZodURL>>;
+        block: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"latest">, z.ZodRecord<z.ZodEnum<{
+            bulletin: "bulletin";
+            people: "people";
+            "asset-hub": "asset-hub";
+            "web3-storage": "web3-storage";
+        }> & z.core.$partial, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>]>>;
+        allowPublicUpstream: z.ZodOptional<z.ZodBoolean>;
+        blocks: z.ZodOptional<z.ZodEnum<{
+            instant: "instant";
+            batch: "batch";
+            manual: "manual";
+            interval: "interval";
+        }>>;
+        db: z.ZodOptional<z.ZodString>;
+        storage: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+            bulletin: "bulletin";
+            people: "people";
+            "asset-hub": "asset-hub";
+            "web3-storage": "web3-storage";
+        }> & z.core.$partial, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        devAuthority: z.ZodOptional<z.ZodBoolean>;
+        xcm: z.ZodOptional<z.ZodBoolean>;
+        specCompat: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ChopsticksTopologyOptions = z.input<typeof chopsticksTopologyOptionsSchema>;
+/** Resolved Chopsticks settings. */
+export interface ChopsticksSettings {
+    upstream: Partial<Record<TopologyChain, string>>;
+    block: "latest" | Partial<Record<TopologyChain, number | string>>;
+    allowPublicUpstream: boolean;
+    blocks: "instant" | "batch" | "manual" | "interval";
+    intervalMs?: number;
+    db?: string;
+    storage: Partial<Record<TopologyChain, Record<string, unknown>>>;
+    devAuthority: boolean;
+    xcm: boolean;
+    /** Spec shim on each port, Chopsticks itself on port + 1. */
+    specCompat: boolean;
+}
+/** A Chopsticks topology: the shared shape plus its settings. */
+export interface ChopsticksTopology extends Topology {
+    chopsticks: ChopsticksSettings;
+}
+export declare const CHOPSTICKS_FLAGS: readonly AdapterFlag[];
+/** `--upstream`, `--pin`, `--build-block` and `--allow-public-upstream` layered over `options`. */
+export declare function chopsticksFlagOptions(values: AdapterFlagValues, options: TopologyOptions): TopologyOptions;
+/** Resolve Chopsticks options into a topology. Throws only on malformed input; what Chopsticks cannot do is returned as issues. */
+export declare function resolveChopsticksTopology(options: ChopsticksTopologyOptions): ChopsticksTopology;
+/** The Chopsticks profile: forks of `chains` at pinned blocks (upstreams must be explicit). */
+export declare function chopsticksTopology(options: Omit<ChopsticksTopologyOptions, "relay" | "provider"> & {
+    chains: TopologyChain[];
+}): ChopsticksTopology;
+/** The options of the `chopsticks` profile layered over `options` (`env show --profile chopsticks`). */
+export declare function chopsticksProfileOptions(name: string, options: TopologyOptions): TopologyOptions;

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

@@ -0,0 +1,287 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { z } from "zod";
+import { LoopbackUrl, NETWORK_CHAINS, TopologyIssues, capabilityReasons, localEndpoints, orderedChains, topologyOffer, } from "@parity/product-lab/domain";
+import { topologyOptionsSchema, topologySchemas } from "./topology-options-schema.js";
+import { BLOCK_MODES, CHOPSTICKS_CHAINS, DEFAULT_CHOPSTICKS_PORTS } from "./constants.js";
+export const CHOPSTICKS_KIND = "chopsticks";
+const TOPOLOGY_PORTS = { ...DEFAULT_CHOPSTICKS_PORTS, "web3-storage": 14040 };
+const chopsticksBlock = z.union([
+    z.number().int().nonnegative(),
+    z.string().regex(/^0x[\da-fA-F]{64}$/, "expected a block number or a 0x-prefixed 32-byte hash"),
+]);
+export const chopsticksSection = z
+    .strictObject({
+    upstream: z.partialRecord(topologySchemas.chain, z.url()).optional(),
+    block: z.union([z.literal("latest"), z.partialRecord(topologySchemas.chain, chopsticksBlock)]).optional(),
+    allowPublicUpstream: z.boolean().optional(),
+    blocks: z.enum(BLOCK_MODES).optional(),
+    db: z.string().min(1).optional(),
+    storage: z.partialRecord(topologySchemas.chain, z.record(z.string(), z.unknown())).optional(),
+    devAuthority: z.boolean().optional(),
+    xcm: z.boolean().optional(),
+    specCompat: z.boolean().optional(),
+});
+export const chopsticksTopologyOptionsSchema = topologyOptionsSchema
+    .extend({ provider: z.literal(CHOPSTICKS_KIND).optional(), chopsticks: chopsticksSection })
+    .strict();
+export const CHOPSTICKS_FLAGS = [
+    { name: "upstream", type: "string", multiple: true, value: "<chain=ws-url>", description: "Chopsticks upstream (repeatable); loopback unless --allow-public-upstream" },
+    { name: "pin", type: "string", multiple: true, value: "<chain=block>", description: "Chopsticks fork block: a number or a 0x hash (repeatable)" },
+    { name: "build-block", type: "string", value: "<mode>", description: "Chopsticks blocks: instant | batch | manual | interval (with --block-time)" },
+    { name: "allow-public-upstream", type: "boolean", description: "let Chopsticks read state from a non-loopback upstream (recorded)" },
+];
+const list = (value) => (Array.isArray(value) ? [...value] : typeof value === "string" ? [value] : []);
+const pair = (name, value) => {
+    const index = value.indexOf("=");
+    if (index <= 0)
+        throw new Error(`--${name} expects key=value, got ${value}`);
+    return [value.slice(0, index), value.slice(index + 1)];
+};
+export function chopsticksFlagOptions(values, options) {
+    const upstreams = list(values.upstream);
+    const pins = list(values.pin);
+    const build = typeof values["build-block"] === "string" ? values["build-block"] : undefined;
+    const allow = values["allow-public-upstream"] === true;
+    if (!upstreams.length && !pins.length && !build && !allow)
+        return options;
+    const section = { ...(options.chopsticks ?? {}) };
+    for (const item of upstreams) {
+        const [chain, url] = pair("upstream", item);
+        section.upstream = { ...(section.upstream ?? {}), [chain]: url };
+    }
+    for (const item of pins) {
+        const [chain, block] = pair("pin", item);
+        const current = typeof section.block === "object" ? section.block : {};
+        section.block = { ...current, [chain]: /^\d+$/.test(block) ? Number(block) : block };
+    }
+    if (build)
+        section.blocks = build;
+    if (allow)
+        section.allowPublicUpstream = true;
+    return { ...options, chopsticks: section };
+}
+export function resolveChopsticksTopology(options) {
+    const input = chopsticksTopologyOptionsSchema.parse(options);
+    const c = input.chopsticks;
+    const network = input.network;
+    const chains = orderedChains(input.chains ?? NETWORK_CHAINS[network]);
+    const has = (id) => chains.includes(id);
+    const issues = new TopologyIssues();
+    const supported = CHOPSTICKS_CHAINS;
+    const resolvedState = input.state ?? { fork: "deployed" };
+    let block = c.block ?? "latest";
+    if (!("fork" in resolvedState) || resolvedState.fork === "snapshot")
+        issues.error("chopsticks-state", "Chopsticks forks live upstream state: use state { fork: \"deployed\" } (latest) or pin blocks with chopsticks.block; genesis, workspaces and Engine snapshots do not apply");
+    else if (typeof resolvedState.fork === "object") {
+        if (c.block !== undefined)
+            issues.error("chopsticks-fork-block-twice", "set the fork block either in state.fork.block or in chopsticks.block, not both");
+        else if (chains.length !== 1)
+            issues.error("chopsticks-fork-block-ambiguous", `one fork block cannot pin ${chains.length} chains (block numbers differ per chain); use chopsticks.block per chain`);
+        else
+            block = { [chains[0]]: resolvedState.fork.block };
+    }
+    for (const id of chains)
+        if (!supported.includes(id))
+            issues.error("chopsticks-chain", `Chopsticks ${id} is not supported (only ${CHOPSTICKS_CHAINS.join(", ")} are verified)`);
+    issues.chainsInNetwork(network, chains);
+    const upstream = {};
+    for (const id of chains) {
+        const url = c.upstream?.[id];
+        if (!url) {
+            issues.error("chopsticks-upstream-missing", `chopsticks.upstream.${id} is required: Chopsticks reads missing state from its upstream for the whole run. Point it at a local node (for example a local fork's ${id} RPC endpoint); public RPC only with allowPublicUpstream`);
+            continue;
+        }
+        if (!["ws:", "wss:"].includes(new URL(url).protocol))
+            issues.error("chopsticks-upstream-protocol", `chopsticks.upstream.${id} must be ws:// or wss:// (got ${url})`);
+        upstream[id] = url;
+    }
+    for (const id of Object.keys(c.upstream ?? {}))
+        if (!has(id))
+            issues.error("chopsticks-upstream-unused", `chopsticks.upstream.${id} names a chain that is not in this topology`);
+    if (typeof block === "object")
+        for (const id of Object.keys(block))
+            if (!has(id))
+                issues.error("chopsticks-block-unused", `chopsticks.block.${id} names a chain that is not in this topology`);
+    for (const id of Object.keys(c.storage ?? {}))
+        if (!has(id))
+            issues.error("chopsticks-storage-unused", `chopsticks.storage.${id} names a chain that is not in this topology`);
+    for (const id of Object.keys(input.runtimes ?? {}))
+        if (!has(id))
+            issues.error("chopsticks-runtime-unused", `runtimes.${id} names a chain that is not in this topology`);
+    const allowPublicUpstream = c.allowPublicUpstream ?? false;
+    for (const [id, url] of Object.entries(upstream).filter(([, url]) => !LoopbackUrl.test(url)))
+        if (allowPublicUpstream)
+            issues.note("chopsticks-public-upstream", `${id} reads fork state from ${url} for the whole run (opted in with allowPublicUpstream; recorded)`);
+        else
+            issues.error("chopsticks-public-upstream", `chopsticks.upstream.${id} (${url}) is not loopback: Chopsticks would connect to it for the whole run. Use a local node or set chopsticks.allowPublicUpstream: true`);
+    if (Object.values(upstream).some((url) => LoopbackUrl.test(url)))
+        issues.loss("chopsticks-upstream-window", "Chopsticks fetches fork-block state lazily for the whole run: a pruned upstream (local Engine forks run --state-pruning 256) serves it only while it is within 256 blocks of the fork block (measured: local Asset Hub about 9 minutes, People and Bulletin about 25; after that blocks needing uncached state fail). Older pinned blocks and long runs need an archive upstream");
+    const blocks = c.blocks ?? "instant";
+    let intervalMs;
+    if (typeof input.blockTime === "object")
+        issues.error("chopsticks-block-time", "Chopsticks takes one blockTime (milliseconds) for blocks: \"interval\", not per chain");
+    else if (input.blockTime !== undefined) {
+        if (blocks !== "interval")
+            issues.error("chopsticks-block-time", "blockTime applies to Chopsticks only with chopsticks.blocks: \"interval\"");
+        intervalMs = input.blockTime;
+    }
+    if (blocks === "interval" && intervalMs === undefined)
+        issues.error("chopsticks-interval", "chopsticks.blocks: \"interval\" needs blockTime (milliseconds)");
+    const runtimes = {};
+    for (const id of chains) {
+        const source = input.runtimes?.[id] ?? "deployed";
+        runtimes[id] = source;
+        if (source === "locked" || (typeof source === "object" && !("wasm" in source)))
+            issues.error("chopsticks-runtime", `runtimes.${id}: Chopsticks runs the upstream's runtime at the fork block ("deployed") or a { wasm } override`);
+    }
+    for (const name of Object.keys(input.binaries ?? {}))
+        issues.error("chopsticks-binaries", `binaries.${name}: Chopsticks runs no node binaries (the runtime executes in its Wasm executor)`);
+    for (const id of Object.keys(input.nodeArgs ?? {}))
+        issues.error("chopsticks-node-args", `nodeArgs.${id}: Chopsticks runs no nodes`);
+    for (const id of Object.keys(input.genesisEdits ?? {}))
+        issues.error("chopsticks-genesis-edits", `genesisEdits.${id}: a fork has no genesis; use chopsticks.storage for state overrides`);
+    if (input.services?.identityBackend)
+        issues.error("chopsticks-services", "Chopsticks starts no identity backend; attach one or use Engine");
+    if (input.services?.ethRpc)
+        issues.error("chopsticks-services", "eth-rpc against Chopsticks is not verified; use the local dev chain (Omni Node) or Engine for evm");
+    if (input.statementStore)
+        issues.error("chopsticks-statement-store", "Chopsticks serves no statement_* RPC (verified); use the local dev chain (Omni Node) or Engine for the statement store");
+    issues.statementStoreChains(input, chains);
+    for (const key of Object.keys(input.ports ?? {}))
+        if (!chains.includes(key))
+            issues.error("chopsticks-ports", `ports.${key}: Chopsticks takes one port per forked chain`);
+    const ports = {};
+    for (const id of chains)
+        ports[id] = input.ports?.[id] ?? TOPOLOGY_PORTS[id];
+    const specCompat = c.specCompat ?? true;
+    issues.portConflicts(chains.flatMap((id) => specCompat
+        ? [
+            [ports[id], id],
+            [ports[id] + 1, `${id} (Chopsticks behind the spec shim)`],
+        ]
+        : [[ports[id], id]]));
+    if (has("people"))
+        issues.loss("chopsticks-no-statement-store", "People under Chopsticks serves no statement_* RPC and its statement-store host functions are unresolved (verified); statementStore is off");
+    if (has("bulletin"))
+        issues.loss("chopsticks-no-bitswap", "Bulletin under Chopsticks stores (TransactionStorage.store succeeds) but serves no bitswap_v1_get, so stored data cannot be retrieved; the bulletin capability is off");
+    issues.loss("chopsticks-instant-finality", "every built block is final at once (no relay, no GRANDPA): finality lag, reorgs, block timing and performance are not representative");
+    issues.loss("chopsticks-mocked-consensus", "parachain validation data is mocked and dev_timeTravel stops block production on these parachains (Parachain slot must match relay-derived slot; verified): no consensus, networking or time-dependent scenarios");
+    const xcm = c.xcm ?? true;
+    if (chains.length > 1)
+        if (xcm)
+            issues.note("chopsticks-xcm", "chains are connected directly over HRMP by Chopsticks' XCM mode (no relay chain; UMP/DMP need a forked relay, not offered)");
+        else
+            issues.loss("no-xcm", "chopsticks.xcm: false leaves the forks unconnected (no teleports between them)");
+    issues.loss("no-host-routing", "hosted SPA runs need people, asset-hub, bulletin and the identity backend together (truAPI host local routing); a host with a supplied wallet can still be routed to Chopsticks People");
+    if (chains.length > 1 && xcm)
+        issues.loss("chopsticks-shared-process", "XCM mode runs every chain in one Chopsticks process: when one fork fails (for example the upstream discarded its state) every chain stops");
+    const devAuthority = c.devAuthority ?? true;
+    const capabilities = {
+        contracts: has("asset-hub"),
+        evm: false,
+        dotns: has("asset-hub"),
+        bulletin: false,
+        statementStore: false,
+        devAuthority,
+    };
+    const endpoints = localEndpoints(chains, ports);
+    const settings = {
+        upstream,
+        block,
+        allowPublicUpstream,
+        blocks,
+        ...(intervalMs !== undefined ? { intervalMs } : {}),
+        ...(c.db ? { db: c.db } : {}),
+        storage: { ...(c.storage ?? {}) },
+        devAuthority,
+        xcm,
+        specCompat,
+    };
+    const customizations = [];
+    const custom = (option, value) => customizations.push({ option, value });
+    if (typeof block === "object")
+        custom("chopsticks.block", block);
+    if (allowPublicUpstream)
+        custom("chopsticks.allowPublicUpstream", true);
+    if (blocks !== "instant")
+        custom("chopsticks.blocks", blocks);
+    if (intervalMs !== undefined)
+        custom("blockTime", intervalMs);
+    for (const [id, value] of Object.entries(settings.storage))
+        custom(`chopsticks.storage.${id}`, value);
+    if (!devAuthority)
+        custom("chopsticks.devAuthority", false);
+    if (!xcm)
+        custom("chopsticks.xcm", false);
+    if (!specCompat) {
+        custom("chopsticks.specCompat", false);
+        issues.loss("chopsticks-spec-shim-off", "without the spec shim the truAPI host cannot follow Chopsticks chains (chainHead_v1 runtime field shape; verified)");
+    }
+    for (const [id, source] of Object.entries(runtimes))
+        if (source !== "deployed")
+            custom(`runtimes.${id}`, source);
+    for (const [key, value] of Object.entries(input.ports ?? {}))
+        if (TOPOLOGY_PORTS[key] !== value)
+            custom(`ports.${key}`, value);
+    const hasBulletin = has("bulletin");
+    return {
+        kind: "product-lab-topology",
+        schemaVersion: 1,
+        profile: "chopsticks",
+        provider: CHOPSTICKS_KIND,
+        label: customizations.length ? "custom" : "standard",
+        network,
+        chains,
+        relay: false,
+        state: resolvedState,
+        runtimes,
+        binaries: {},
+        nodeArgs: {},
+        blockTime: {},
+        genesisEdits: {},
+        statementStore: false,
+        services: { identityBackend: false, ethRpc: false },
+        ports,
+        chopsticks: settings,
+        capabilities,
+        capabilityReasons: capabilityReasons(capabilities, chains, (capability) => {
+            switch (capability) {
+                case "evm":
+                    return "eth-rpc against Chopsticks is not verified";
+                case "bulletin":
+                    return hasBulletin ? "Chopsticks Bulletin serves no bitswap_v1_get (stored data cannot be retrieved)" : "needs the bulletin chain";
+                case "statementStore":
+                    return "Chopsticks serves no statement_* RPC";
+                case "devAuthority":
+                    return "chopsticks.devAuthority: false";
+                default:
+                    return undefined;
+            }
+        }),
+        offer: topologyOffer(chains, [], capabilities),
+        endpoints,
+        customizations,
+        issues: issues.list,
+        retention: { retention: "disposable", reason: "a Chopsticks fork restarts from its pinned block; blocks built in the run are discarded" },
+        presentation: {
+            relay: "no (Chopsticks forks; validation data mocked)",
+            state: `fork at ${block === "latest" ? "each upstream's best block at start (recorded)" : Object.entries(block).map(([id, value]) => `${id} ${value}`).join(", ")}`,
+            details: [
+                { label: "upstream", value: `${Object.entries(upstream).map(([id, url]) => `${id} ${url}`).join(", ") || "none"}${allowPublicUpstream ? " (public allowed)" : ""}` },
+                { label: "blocks", value: `${blocks}${intervalMs ? ` every ${intervalMs} ms` : ""}; finalized = best${xcm && chains.length > 1 ? "; XCM mode (HRMP between forks)" : ""}` },
+            ],
+            binaries: "none (Chopsticks CLI)",
+        },
+        options: structuredClone(options),
+    };
+}
+export function chopsticksTopology(options) {
+    return resolveChopsticksTopology({ ...options, relay: false });
+}
+export function chopsticksProfileOptions(name, options) {
+    if (name !== "chopsticks")
+        throw new Error(`The Chopsticks adapter has no profile ${name}`);
+    const { relay: _relay, state, chopsticks, ...rest } = options;
+    return { ...rest, ...(state ? { state } : {}), relay: false, chains: options.chains ?? ["people"], chopsticks: chopsticks ?? {} };
+}

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

@@ -0,0 +1,11 @@
+/** The Chopsticks release this provider was verified with (docs/verification/2026-09-24-env-chopsticks.md). */
+export declare const CHOPSTICKS_VERSION = "1.5.2";
+/** Chains this provider can fork. web3-storage is not verified. */
+export declare const CHOPSTICKS_CHAINS: readonly ["people", "asset-hub", "bulletin"];
+export type ChopsticksChain = (typeof CHOPSTICKS_CHAINS)[number];
+/** Default RPC ports (one WebSocket + HTTP port per chain; Chopsticks has no p2p). */
+export declare const DEFAULT_CHOPSTICKS_PORTS: Readonly<Record<ChopsticksChain, number>>;
+/** Expected runtime spec name fragment per chain, so a mislabelled upstream fails before forking. */
+export declare const SPEC_NAMES: Readonly<Record<ChopsticksChain, RegExp>>;
+export declare const BLOCK_MODES: readonly ["instant", "batch", "manual", "interval"];
+export type BlockMode = (typeof BLOCK_MODES)[number];

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

@@ -0,0 +1,15 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export const CHOPSTICKS_VERSION = "1.5.2";
+export const CHOPSTICKS_CHAINS = ["people", "asset-hub", "bulletin"];
+export const DEFAULT_CHOPSTICKS_PORTS = {
+    people: 14010,
+    "asset-hub": 14020,
+    bulletin: 14030,
+};
+export const SPEC_NAMES = {
+    people: /people/,
+    "asset-hub": /asset-hub/,
+    bulletin: /bulletin/,
+};
+export const BLOCK_MODES = ["instant", "batch", "manual", "interval"];

package/adapters/environment/chopsticks/src/dev-authority.d.ts

@@ -0,0 +1,21 @@
+export declare function systemAccountKey(publicKey: string): string;
+export declare const ALICE_ACCOUNT_KEY: string;
+/** `Sudo.Key`: twox128("Sudo") ++ twox128("Key"). */
+export declare const SUDO_KEY: string;
+/** Endow when free balance is below this (plancks). */
+export declare const MIN_AUTHORITY_FREE: bigint;
+export declare const AUTHORITY_FREE: bigint;
+export declare function accountFree(raw: string | null): bigint;
+/** The raw AccountInfo with `free` replaced; a missing account becomes a fresh one with one provider. */
+export declare function withFree(raw: string | null, free: bigint): string;
+export interface AuthorityChange {
+    aliceFreeBefore: string;
+    aliceFreeAfter: string;
+    sudoBefore: string | null;
+    sudoSetToAlice: boolean;
+}
+/** Storage writes that give //Alice funds and, where Sudo exists, the Sudo key. */
+export declare function authorityWrites(aliceAccount: string | null, sudoKey: string | null): {
+    writes: [string, string][];
+    change: AuthorityChange;
+};

package/adapters/environment/chopsticks/src/dev-authority.js

@@ -0,0 +1,66 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { Blake2128Concat, Twox128 } from "@polkadot-api/substrate-bindings";
+import { DEVELOPMENT_AUTHORITY } from "@parity/product-lab/domain";
+const ALICE_PUBLIC_KEY = DEVELOPMENT_AUTHORITY.publicKey;
+const hex = (bytes) => `0x${Buffer.from(bytes).toString("hex")}`;
+const bytes = (value) => new Uint8Array(Buffer.from(value.replace(/^0x/, ""), "hex"));
+const text = (value) => new TextEncoder().encode(value);
+export function systemAccountKey(publicKey) {
+    return hex(new Uint8Array([...Twox128(text("System")), ...Twox128(text("Account")), ...Blake2128Concat(bytes(publicKey))]));
+}
+export const ALICE_ACCOUNT_KEY = systemAccountKey(ALICE_PUBLIC_KEY);
+export const SUDO_KEY = hex(new Uint8Array([...Twox128(text("Sudo")), ...Twox128(text("Key"))]));
+export const MIN_AUTHORITY_FREE = 10n ** 15n;
+export const AUTHORITY_FREE = 10n ** 18n;
+const ACCOUNT_INFO_BYTES = 16 + 4 * 16;
+const NEW_LOGIC_FLAG = 1n << 127n;
+const readU128 = (data, offset) => {
+    let value = 0n;
+    for (let index = 15; index >= 0; index--)
+        value = (value << 8n) | BigInt(data[offset + index]);
+    return value;
+};
+const writeU128 = (data, offset, value) => {
+    for (let index = 0; index < 16; index++)
+        data[offset + index] = Number((value >> BigInt(8 * index)) & 0xffn);
+};
+export function accountFree(raw) {
+    if (!raw)
+        return 0n;
+    const data = bytes(raw);
+    if (data.length !== ACCOUNT_INFO_BYTES)
+        throw new Error(`Unexpected System.Account layout (${data.length} bytes)`);
+    return readU128(data, 16);
+}
+export function withFree(raw, free) {
+    const data = raw ? bytes(raw) : new Uint8Array(ACCOUNT_INFO_BYTES);
+    if (data.length !== ACCOUNT_INFO_BYTES)
+        throw new Error(`Unexpected System.Account layout (${data.length} bytes)`);
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    if (!raw)
+        writeU128(data, 64, NEW_LOGIC_FLAG);
+    if (view.getUint32(8, true) === 0)
+        view.setUint32(8, 1, true);
+    writeU128(data, 16, free);
+    return hex(data);
+}
+export function authorityWrites(aliceAccount, sudoKey) {
+    const writes = [];
+    const before = accountFree(aliceAccount);
+    let after = before;
+    if (before < MIN_AUTHORITY_FREE) {
+        writes.push([ALICE_ACCOUNT_KEY, withFree(aliceAccount, AUTHORITY_FREE)]);
+        after = AUTHORITY_FREE;
+    }
+    const setSudo = sudoKey !== null && sudoKey.toLowerCase() !== ALICE_PUBLIC_KEY;
+    if (setSudo)
+        writes.push([SUDO_KEY, ALICE_PUBLIC_KEY]);
+    const change = {
+        aliceFreeBefore: before.toString(),
+        aliceFreeAfter: after.toString(),
+        sudoBefore: sudoKey,
+        sudoSetToAlice: setSudo,
+    };
+    return { writes, change };
+}