@parity/product-sdk-host 0.0.0-dev.312.0

package/src/chain-discovery.ts

@@ -0,0 +1,287 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Host chain discovery. Resolves chain roles to genesis hashes against the
+ * host's configured environment instead of hard-coding them.
+ *
+ * The wire method takes one identifier per call, so the facade fires one
+ * concurrent call per requested identifier and caches the combined result
+ * for the lifetime of the connection. Consumed internally by chain-client.
+ * Products normally never call this directly.
+ *
+ * @module
+ */
+
+import type {
+    ChainIdentifier,
+    HexString,
+    TrUApiClient,
+    VersionedRemoteChainInfoError,
+    scale,
+} from "@parity/truapi";
+import { createLogger } from "@parity/product-sdk-logger";
+import { formatHostError } from "./errors.js";
+import { getClient } from "./transport.js";
+
+const log = createLogger("host");
+
+/**
+ * Chain-role identifier. A closed protocol enum, not a free-form name. The
+ * host maps each role to the concrete chain of its configured environment.
+ */
+export type HostChainIdentifier = ChainIdentifier;
+
+/** The host's configured environment plus per-identifier resolved genesis hashes. */
+export interface HostChainDiscovery {
+    /** Ecosystem the host is configured for, e.g. `"polkadot"`, `"paseo"`. */
+    network: string;
+    /** Present for every requested identifier the host serves. */
+    chains: Partial<Record<HostChainIdentifier, HexString>>;
+}
+
+/** Error channel of `chain.getChainInfo`. */
+type GetChainInfoError = scale.CallErrorValue<VersionedRemoteChainInfoError>;
+
+/**
+ * Marks a transient probe failure. These are evicted from the cache so the
+ * next call re-probes. Stable "no discovery" answers stay cached.
+ */
+const TRANSIENT_FAILURE = Symbol("transient-failure");
+
+/**
+ * Hosts that predate the wire-id reservation never answer the probe at all,
+ * so a silent host must resolve as "no discovery" instead of hanging. The
+ * answer comes from host config with no chain I/O, so a short deadline is
+ * enough. A timeout is treated as transient, never cached: a host that
+ * supports discovery but started slowly would otherwise be recorded as
+ * pre-discovery for the life of the client. The cost is that a genuinely
+ * legacy host pays the deadline again on the next call.
+ */
+const PROBE_TIMEOUT_MS = 3_000;
+
+const discoveryCache = new WeakMap<TrUApiClient, Map<string, Promise<HostChainDiscovery | null>>>();
+
+/**
+ * Resolve chain roles against the current host.
+ *
+ * Returns `null` when discovery is unavailable: outside a container, on a
+ * legacy host, or when the host serves none of the requested identifiers.
+ * Callers treat `null` as "fall back to configured constants".
+ *
+ * One concurrent `getChainInfo` call is made per identifier. Identifiers
+ * the host answers `NotSupported` for are absent from `chains`. Stable
+ * answers are cached per client and identifier set. Unexpected wire failures
+ * and probe timeouts are logged, return `null` and are not cached, so a later
+ * call re-probes.
+ */
+export async function getHostChainInfo(
+    identifiers: readonly HostChainIdentifier[],
+): Promise<HostChainDiscovery | null> {
+    const client = await getClient();
+    if (!client) return null;
+    let bySet = discoveryCache.get(client);
+    if (!bySet) {
+        bySet = new Map();
+        discoveryCache.set(client, bySet);
+    }
+    const key = [...identifiers].sort().join(",");
+    let cached = bySet.get(key);
+    if (!cached) {
+        cached = fetchChainInfo(client, identifiers).then((result) => {
+            if (result === TRANSIENT_FAILURE) {
+                // Evict so the next caller re-probes.
+                bySet.delete(key);
+                return null;
+            }
+            return result;
+        });
+        bySet.set(key, cached);
+    }
+    return cached;
+}
+
+async function fetchChainInfo(
+    client: TrUApiClient,
+    identifiers: readonly HostChainIdentifier[],
+): Promise<HostChainDiscovery | null | typeof TRANSIENT_FAILURE> {
+    try {
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        const probe = Promise.all(
+            identifiers.map((id) =>
+                client.chain.getChainInfo({ chain: id }).match(
+                    (value) => ({ id, ok: value }) as const,
+                    (error) => ({ id, err: error }) as const,
+                ),
+            ),
+        );
+        const outcomes = await Promise.race([
+            probe,
+            new Promise<"timeout">((resolve) => {
+                timer = setTimeout(() => resolve("timeout"), PROBE_TIMEOUT_MS);
+            }),
+        ]).finally(() => clearTimeout(timer));
+        if (outcomes === "timeout") {
+            log.warn("getChainInfo probe timed out, treating the host as pre-discovery for now");
+            return TRANSIENT_FAILURE;
+        }
+        let network: string | undefined;
+        const chains: Partial<Record<HostChainIdentifier, HexString>> = {};
+        for (const outcome of outcomes) {
+            if ("ok" in outcome) {
+                network = outcome.ok.network;
+                chains[outcome.id] = outcome.ok.genesisHash;
+                continue;
+            }
+            // "Unsupported" means the host predates the method entirely.
+            // "NotSupported" means this one identifier is not served.
+            if (outcome.err.tag === "Unsupported") return null;
+            if (isNotSupported(outcome.err)) continue;
+            log.warn(`getChainInfo failed: ${formatHostError(outcome.err)}`);
+            return TRANSIENT_FAILURE;
+        }
+        // Every identifier was refused, so the host never revealed its network.
+        if (network === undefined) return null;
+        return { network, chains };
+    } catch (error) {
+        log.warn(`getChainInfo failed: ${formatHostError(error)}`);
+        return TRANSIENT_FAILURE;
+    }
+}
+
+/** True when a domain error is the unit `NotSupported` variant. */
+function isNotSupported(error: GetChainInfoError): boolean {
+    return error.tag === "Domain" && error.value.value.tag === "NotSupported";
+}
+
+if (import.meta.vitest) {
+    const { test, expect, afterEach, vi } = import.meta.vitest;
+    const { setTruApiClient } = await import("./transport.js");
+    type ChainInfoResponse = import("@parity/truapi").RemoteChainInfoResponse;
+
+    type Served = Partial<Record<HostChainIdentifier, HexString>>;
+
+    const NOT_SUPPORTED: GetChainInfoError = {
+        tag: "Domain",
+        value: { tag: "V1", value: { tag: "NotSupported" } },
+    };
+
+    type FakeBehavior = { network: string; served: Served } | { err: GetChainInfoError };
+
+    /** Fake client answering from a served-chains map or a per-call behavior function. */
+    function fakeClient(
+        behavior: FakeBehavior | ((call: number) => FakeBehavior),
+        calls: { count: number; requests: HostChainIdentifier[] } = { count: 0, requests: [] },
+    ): TrUApiClient {
+        return {
+            chain: {
+                getChainInfo: (request: { chain: HostChainIdentifier }) => {
+                    const current =
+                        typeof behavior === "function" ? behavior(calls.count) : behavior;
+                    calls.count += 1;
+                    calls.requests.push(request.chain);
+                    return {
+                        match: async <A, B>(
+                            onOk: (v: ChainInfoResponse) => A,
+                            onErr: (e: GetChainInfoError) => B,
+                        ) => {
+                            if ("err" in current) return onErr(current.err);
+                            const genesisHash = current.served[request.chain];
+                            if (!genesisHash) return onErr(NOT_SUPPORTED);
+                            return onOk({
+                                network: current.network,
+                                chain: request.chain,
+                                genesisHash,
+                            });
+                        },
+                    };
+                },
+            },
+        } as unknown as TrUApiClient;
+    }
+
+    const PASEO_SERVED: Served = {
+        AssetHub: "0xaa" as HexString,
+        Bulletin: "0xbb" as HexString,
+        People: "0xcc" as HexString,
+    };
+
+    afterEach(() => {
+        setTruApiClient(null);
+        vi.restoreAllMocks();
+    });
+
+    test("resolves each requested identifier once, unserved ones absent", async () => {
+        const calls = { count: 0, requests: [] as HostChainIdentifier[] };
+        setTruApiClient(
+            fakeClient({ network: "paseo", served: { AssetHub: "0xaa" as HexString } }, calls),
+        );
+        const result = await getHostChainInfo(["AssetHub", "Bulletin", "People"]);
+        expect(result).toEqual({ network: "paseo", chains: { AssetHub: "0xaa" } });
+        expect(calls.requests).toEqual(["AssetHub", "Bulletin", "People"]);
+    });
+
+    test("returns null when discovery is unavailable and caches the answer", async () => {
+        // Outside a container.
+        expect(await getHostChainInfo(["AssetHub"])).toBeNull();
+        // Every identifier refused, so the network is never revealed.
+        const refused = { count: 0, requests: [] as HostChainIdentifier[] };
+        setTruApiClient(fakeClient({ network: "devnet", served: {} }, refused));
+        expect(await getHostChainInfo(["Bulletin"])).toBeNull();
+        expect(await getHostChainInfo(["Bulletin"])).toBeNull();
+        expect(refused.count).toBe(1);
+        // Legacy host answering Unsupported.
+        const legacy = { count: 0, requests: [] as HostChainIdentifier[] };
+        setTruApiClient(fakeClient({ err: { tag: "Unsupported" } }, legacy));
+        expect(await getHostChainInfo(["AssetHub"])).toBeNull();
+        expect(await getHostChainInfo(["AssetHub"])).toBeNull();
+        expect(legacy.count).toBe(1);
+    });
+
+    test("caches per client and identifier set, ignoring order", async () => {
+        const calls = { count: 0, requests: [] as HostChainIdentifier[] };
+        setTruApiClient(fakeClient({ network: "paseo", served: PASEO_SERVED }, calls));
+        await getHostChainInfo(["AssetHub", "Bulletin"]);
+        await getHostChainInfo(["Bulletin", "AssetHub"]);
+        expect(calls.count).toBe(2);
+        await getHostChainInfo(["People"]);
+        expect(calls.count).toBe(3);
+    });
+
+    test("a silent host times out to null and the next call re-probes", async () => {
+        vi.useFakeTimers();
+        try {
+            const calls = { count: 0 };
+            setTruApiClient({
+                chain: {
+                    getChainInfo: () => {
+                        calls.count += 1;
+                        return { match: () => new Promise(() => {}) };
+                    },
+                },
+            } as unknown as TrUApiClient);
+            const pending = getHostChainInfo(["AssetHub"]);
+            await vi.advanceTimersByTimeAsync(3_000);
+            expect(await pending).toBeNull();
+            // A host that merely started slowly must not stay classified as
+            // pre-discovery, so the timeout is never cached.
+            const retry = getHostChainInfo(["AssetHub"]);
+            await vi.advanceTimersByTimeAsync(3_000);
+            expect(await retry).toBeNull();
+            expect(calls.count).toBe(2);
+        } finally {
+            vi.useRealTimers();
+        }
+    });
+
+    test("transient wire failures return null but are not cached, the next call re-probes", async () => {
+        setTruApiClient(
+            fakeClient((call) =>
+                call === 0
+                    ? { err: { tag: "HostFailure", value: { reason: "boom" } } }
+                    : { network: "paseo", served: PASEO_SERVED },
+            ),
+        );
+        expect(await getHostChainInfo(["AssetHub"])).toBeNull();
+        expect((await getHostChainInfo(["AssetHub"]))?.network).toBe("paseo");
+    });
+}

package/src/chain-spec.ts

@@ -0,0 +1,272 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Higher-level wrapper for the host's chain-spec lookups.
+ *
+ * The host exposes three separate chain-spec calls — `chain.getSpecGenesisHash`,
+ * `chain.getSpecChainName`, and `chain.getSpecProperties` — each reachable via
+ * {@link getTruApi} and each returning a neverthrow `ResultAsync`.
+ * {@link getChainSpec} fetches all three in one call and returns a single
+ * struct so callers read whichever field they need, matching the JSON-RPC
+ * `chainSpec_v1_*` family they mirror.
+ *
+ * @module
+ */
+
+import { createLogger } from "@parity/product-sdk-logger";
+
+import type { HostError } from "./errors.js";
+import { type Result, ok } from "./result.js";
+import { getTruApi, type HexString, mapHostResult } from "./truapi.js";
+
+const log = createLogger("host:chain-spec");
+
+/**
+ * Chain SS58/token properties as reported by the host's
+ * `chainSpecProperties` call.
+ *
+ * The host returns this as a JSON string (mirroring the substrate
+ * `chainSpec_v1_properties` JSON-RPC, whose payload is an open-ended object).
+ * {@link getChainSpec} parses it into {@link ChainSpec.properties} and also
+ * surfaces the untouched JSON as {@link ChainSpec.propertiesRaw}. The well-known substrate fields are
+ * typed for convenience; the index signature keeps any chain-specific extras
+ * reachable without `any` at the call site.
+ */
+export interface ChainProperties {
+    /** Address prefix used for SS58 encoding (e.g. `0` for Polkadot). */
+    ss58Format?: number;
+    /** Decimal places of the chain's native token(s). */
+    tokenDecimals?: number | number[];
+    /** Ticker symbol(s) of the chain's native token(s). */
+    tokenSymbol?: string | string[];
+    /** Chain-specific extras passed through verbatim from the JSON payload. */
+    [key: string]: unknown;
+}
+
+/**
+ * Combined chain-spec view returned by {@link getChainSpec}.
+ */
+export interface ChainSpec {
+    /** The chain's `0x`-prefixed genesis hash, as reported by the host. */
+    genesisHash: HexString;
+    /** Human-readable chain name (e.g. `"Polkadot"`). */
+    name: string;
+    /**
+     * Parsed chain properties, or `null` if the host's JSON payload couldn't
+     * be parsed. Inspect {@link propertiesRaw} for the original string.
+     */
+    properties: ChainProperties | null;
+    /** The untouched JSON string the host returned for properties. */
+    propertiesRaw: string;
+}
+
+/**
+ * Fetch a chain's full spec (genesis hash, name, and properties) from the host
+ * in one call.
+ *
+ * Issues the three underlying `chain.getSpec*` requests concurrently, unwraps
+ * each response, and parses the properties JSON. Note the `genesisHash` in the
+ * result is the value the host echoes back from `getSpecGenesisHash` for the
+ * looked-up chain — pass the chain's known genesis hash as the lookup key.
+ *
+ * `null` (outside a container) is preserved as an `ok` value — it is an
+ * expected state, not a failure — so callers branch on `r.ok && r.value`. A
+ * real host-call failure surfaces on the `err` channel.
+ *
+ * @param genesisHash - The `0x`-prefixed genesis hash identifying the chain.
+ * @returns `ok(spec)` with the combined {@link ChainSpec}, `ok(null)` if the
+ *   host is unavailable (running outside a container), or
+ *   `err(HostCallFailedError)` if any underlying host call fails.
+ *
+ * @example
+ * ```ts
+ * import { getChainSpec } from "@parity/product-sdk-host";
+ *
+ * const r = await getChainSpec(genesisHash);
+ * if (r.ok && r.value) {
+ *   console.log(r.value.name, r.value.properties?.tokenSymbol);
+ * }
+ * ```
+ */
+export async function getChainSpec(
+    genesisHash: HexString,
+): Promise<Result<ChainSpec | null, HostError>> {
+    const truApi = await getTruApi();
+    if (!truApi) {
+        log.debug("getChainSpec: TruAPI unavailable");
+        return ok(null);
+    }
+    log.debug("getChainSpec", { genesisHash });
+
+    const [genesisHashResult, nameResult, propertiesResult] = await Promise.all([
+        mapHostResult(
+            truApi.chain.getSpecGenesisHash({ genesisHash }),
+            (response) => response.genesisHash,
+            "getChainSpec (genesisHash) failed",
+        ),
+        mapHostResult(
+            truApi.chain.getSpecChainName({ genesisHash }),
+            (response) => response.chainName,
+            "getChainSpec (chainName) failed",
+        ),
+        mapHostResult(
+            truApi.chain.getSpecProperties({ genesisHash }),
+            (response) => response.properties,
+            "getChainSpec (properties) failed",
+        ),
+    ]);
+
+    // Short-circuit on the first failing call.
+    if (!genesisHashResult.ok) return genesisHashResult;
+    if (!nameResult.ok) return nameResult;
+    if (!propertiesResult.ok) return propertiesResult;
+
+    const propertiesRaw = propertiesResult.value;
+    let properties: ChainProperties | null;
+    try {
+        properties = JSON.parse(propertiesRaw) as ChainProperties;
+    } catch (parseError) {
+        log.debug("getChainSpec: properties JSON parse failed", parseError);
+        properties = null;
+    }
+
+    return ok({
+        genesisHash: genesisHashResult.value,
+        name: nameResult.value,
+        properties,
+        propertiesRaw,
+    });
+}
+
+if (import.meta.vitest) {
+    const { test, expect, describe, vi } = import.meta.vitest;
+
+    async function withMockedTruApi<T>(
+        bridge: {
+            chain?: {
+                getSpecGenesisHash?: (req: unknown) => unknown;
+                getSpecChainName?: (req: unknown) => unknown;
+                getSpecProperties?: (req: unknown) => unknown;
+            };
+        } | null,
+        fn: (mod: typeof import("./chain-spec.js")) => Promise<T>,
+    ): Promise<T> {
+        vi.resetModules();
+        vi.doMock("./truapi.js", async (importOriginal) => {
+            const original = await importOriginal<typeof import("./truapi.js")>();
+            return {
+                ...original,
+                getTruApi: async () => bridge,
+            };
+        });
+        try {
+            const mod = await import("./chain-spec.js");
+            return await fn(mod);
+        } finally {
+            vi.doUnmock("./truapi.js");
+            vi.resetModules();
+        }
+    }
+
+    /** A resolved ResultAsync stub yielding the given response object. */
+    const okAsync = (response: unknown) => ({
+        match: async (onOk: (v: unknown) => unknown) => onOk(response),
+    });
+
+    describe("getChainSpec", () => {
+        test("returns ok(null) when TruAPI is unavailable", async () => {
+            await withMockedTruApi(null, async (mod) => {
+                expect(await mod.getChainSpec("0x00")).toEqual({ ok: true, value: null });
+            });
+        });
+
+        test("combines the three calls and parses properties JSON", async () => {
+            await withMockedTruApi(
+                {
+                    chain: {
+                        getSpecGenesisHash: vi
+                            .fn()
+                            .mockReturnValue(okAsync({ genesisHash: "0xabcd" })),
+                        getSpecChainName: vi
+                            .fn()
+                            .mockReturnValue(okAsync({ chainName: "Polkadot" })),
+                        getSpecProperties: vi.fn().mockReturnValue(
+                            okAsync({
+                                properties:
+                                    '{"ss58Format":0,"tokenDecimals":10,"tokenSymbol":"DOT"}',
+                            }),
+                        ),
+                    },
+                },
+                async (mod) => {
+                    const result = await mod.getChainSpec("0xabcd");
+                    expect(result).toEqual({
+                        ok: true,
+                        value: {
+                            genesisHash: "0xabcd",
+                            name: "Polkadot",
+                            properties: { ss58Format: 0, tokenDecimals: 10, tokenSymbol: "DOT" },
+                            propertiesRaw:
+                                '{"ss58Format":0,"tokenDecimals":10,"tokenSymbol":"DOT"}',
+                        },
+                    });
+                },
+            );
+        });
+
+        test("leaves properties null when the JSON is malformed", async () => {
+            await withMockedTruApi(
+                {
+                    chain: {
+                        getSpecGenesisHash: vi
+                            .fn()
+                            .mockReturnValue(okAsync({ genesisHash: "0xabcd" })),
+                        getSpecChainName: vi
+                            .fn()
+                            .mockReturnValue(okAsync({ chainName: "Polkadot" })),
+                        getSpecProperties: vi
+                            .fn()
+                            .mockReturnValue(okAsync({ properties: "not json" })),
+                    },
+                },
+                async (mod) => {
+                    const result = await mod.getChainSpec("0xabcd");
+                    expect(result.ok).toBe(true);
+                    if (result.ok) {
+                        expect(result.value?.properties).toBeNull();
+                        expect(result.value?.propertiesRaw).toBe("not json");
+                    }
+                },
+            );
+        });
+
+        test("returns err(HostCallFailedError) when a host call fails", async () => {
+            await withMockedTruApi(
+                {
+                    chain: {
+                        getSpecGenesisHash: vi.fn().mockReturnValue({
+                            match: async (
+                                _onOk: (v: unknown) => unknown,
+                                onErr: (e: unknown) => unknown,
+                            ) => onErr({ reason: "boom" }),
+                        }),
+                        getSpecChainName: vi
+                            .fn()
+                            .mockReturnValue(okAsync({ chainName: "Polkadot" })),
+                        getSpecProperties: vi.fn().mockReturnValue(okAsync({ properties: "{}" })),
+                    },
+                },
+                async (mod) => {
+                    const result = await mod.getChainSpec("0xabcd");
+                    expect(result.ok).toBe(false);
+                    if (!result.ok) {
+                        expect(result.error.name).toBe("HostCallFailedError");
+                        expect(result.error.message).toMatch(
+                            /getChainSpec \(genesisHash\) failed: boom/,
+                        );
+                    }
+                },
+            );
+        });
+    });
+}