@parity/product-sdk-host 0.15.0 → 0.16.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/index.ts

@@ -53,6 +53,10 @@ export type {
     RemotePermission,
 } from "./truapi.js";
 
+// Host chain discovery.
+export { getHostChainInfo } from "./chain-discovery.js";
+export type { HostChainDiscovery, HostChainIdentifier } from "./chain-discovery.js";
+
 // Result type + typed host errors (the throw→Result boundary)
 export { ok, err } from "./result.js";
 export type { Result } from "./result.js";
@@ -67,16 +71,23 @@ export {
 export type { HostErrorPayload } from "./errors.js";
 
 // Accounts — host wallet accounts, product accounts, Ring VRF, and signers.
-export { getAccountsProvider } from "./accounts.js";
+export { getAccountsProvider, findRingVrfKeyHandle } from "./accounts.js";
 export type {
     AccountsProvider,
     DerivationIndex,
     HostAccount,
     ProductAccount,
+    ProductAccountLookup,
     ContextualAlias,
     ProductProofContext,
+    RegisteredRingVrfKey,
     RingLocation,
     RingVRFProof,
+    RingVrfKeyDisclosure,
+    RingVrfKeyHandle,
+    RingVrfPublicKey,
+    VrfSignature,
+    VrfTranscriptItem,
 } from "./accounts.js";
 
 // Higher-level permission wrappers

package/src/payments.ts

@@ -97,7 +97,7 @@ function adaptPaymentManager(client: TrUApiClient): PaymentManager {
  * const payments = await getPaymentManager();
  * if (payments) {
  *   const sub = payments.subscribeBalance((b) => { ... });
- *   await payments.topUp(1_000_000n, { tag: "ProductAccount", value: { derivationIndex: { tag: "Left", value: 0 } } });
+ *   await payments.topUp(1_000_000n, { tag: "ProductAccount", value: { derivationIndex: { tag: "Index", value: 0 } } });
  *   const { id } = await payments.requestPayment(500n, "0x…");
  *   sub.unsubscribe();
  * }

package/src/testing.ts

@@ -10,17 +10,21 @@
  * makes a default `SignerManager`, `local-storage` auto-detection, and the
  * `statement-store` / `cloud-storage` host paths testable.
  *
- * Not modeled: the PAPI `chain` JSON-RPC surface behind `getHostProvider()` —
- * there's no chain-read fake, by design; the host owns RPC selection — and the
- * `chat` / `coinPayment` / `entropy` / `notifications` / `payment` /
- * `permissions` / `resourceAllocation` / `theme` domains. Touching an unmodeled
- * domain throws a descriptive error rather than failing with `undefined is not
- * a function`.
+ * Of the `chain` domain only `getChainInfo` is modeled, so host chain discovery
+ * (and `getChainAPI()` on top of it) resolves in tests; see the `chainInfo`
+ * option. Not modeled: the rest of the PAPI `chain` JSON-RPC surface behind
+ * `getHostProvider()` — there's no chain-read fake, by design; the host owns RPC
+ * selection — and the `chat` / `coinPayment` / `entropy` / `notifications` /
+ * `payment` / `permissions` / `resourceAllocation` / `theme` domains. Touching
+ * an unmodeled domain throws a descriptive error rather than failing with
+ * `undefined is not a function`.
  *
  * @packageDocumentation
  */
 import type { ObservableLike, Observer, Subscription, TrUApiClient } from "@parity/truapi";
-import { okAsync } from "neverthrow";
+import { errAsync, okAsync } from "neverthrow";
+
+import type { HostChainIdentifier } from "./chain-discovery.js";
 
 import { setTruApiClient } from "./transport.js";
 
@@ -91,10 +95,17 @@ function oneShotObservable<Item>(item: Item): ObservableLike<Item> {
  * member access throws with a pointer here, instead of the bare TypeError an
  * empty stub would give. The empty-object cast is the one concession a Proxy
  * needs; every modeled domain is checked structurally.
+ *
+ * `modeled` carries the members that _are_ implemented, for a domain where the
+ * fake covers some calls but not the whole surface.
  */
-function notModeled<D extends keyof TrUApiClient>(domain: D): PublicSurface<TrUApiClient[D]> {
-    return new Proxy({} as PublicSurface<TrUApiClient[D]>, {
-        get(_target, member) {
+function notModeled<D extends keyof TrUApiClient>(
+    domain: D,
+    modeled?: Partial<PublicSurface<TrUApiClient[D]>>,
+): PublicSurface<TrUApiClient[D]> {
+    return new Proxy((modeled ?? {}) as PublicSurface<TrUApiClient[D]>, {
+        get(target, member) {
+            if (member in target) return target[member as keyof typeof target];
             // Stay quiet for inspection probes (console.log, await-resolution).
             if (typeof member === "symbol" || member === "then") return undefined;
             throw new Error(
@@ -114,6 +125,22 @@ function preimageKey(hexValue: string): `0x${string}` {
     return `0x${(h >>> 0).toString(16).padStart(8, "0")}`;
 }
 
+/**
+ * What a fake host reports through `chain.getChainInfo`: the network id it is
+ * configured for, and a genesis hash per chain role it serves.
+ *
+ * Roles left out are answered `NotSupported`, exactly as a host that does not
+ * serve them. Use the genesis hashes the descriptors expose (e.g.
+ * `paseo_asset_hub.genesis`) if the test drives `getChainAPI()`, since the
+ * environment is derived by matching the asset hub genesis against the bundle.
+ */
+export interface FakeChainInfo {
+    /** Ecosystem the fake host claims, e.g. `"paseo"`. */
+    network: string;
+    /** Genesis hash per chain role served. */
+    chains: Partial<Record<HostChainIdentifier, `0x${string}`>>;
+}
+
 /** Options for {@link createFakeTruApiClient}. */
 export interface CreateFakeTruApiClientOptions {
     /** `account.getUserId` primary username. Default `"alice.dot"`. */
@@ -130,6 +157,12 @@ export interface CreateFakeTruApiClientOptions {
     legacyAccounts?: Array<{ publicKey: Uint8Array; name: string }>;
     /** Seed the in-memory preimage store, keyed by the `0x` preimage key. */
     preimages?: Record<string, Uint8Array>;
+    /**
+     * What `chain.getChainInfo` reports. Omit to model a host predating chain
+     * discovery: the call is refused as `Unsupported`, so `getHostChainInfo`
+     * resolves `null` and `getChainAPI` needs an explicit environment.
+     */
+    chainInfo?: FakeChainInfo;
 }
 
 /**
@@ -143,6 +176,7 @@ export function createFakeTruApiClient(options?: CreateFakeTruApiClientOptions):
     const publicKey = toHex(options?.publicKey ?? new Uint8Array(32).fill(0x11));
     const signature = toHex(options?.signature ?? new Uint8Array(64).fill(0x22));
     const chainSupported = options?.chainSupported ?? true;
+    const chainInfo = options?.chainInfo;
 
     // Real in-memory KV (hex values) so getHostLocalStorage()/createLocalKvStore() round-trip.
     const kv = new Map<string, `0x${string}`>();
@@ -193,6 +227,9 @@ export function createFakeTruApiClient(options?: CreateFakeTruApiClientOptions):
                     ringIndex: 0,
                     ringRevision: 0,
                 }),
+            registerRingVrfKey: () => okAsync(publicKey),
+            listRingVrfKeys: () => okAsync([]),
+            ringVrfSign: () => okAsync(signature),
             signVrf: () => okAsync({ preOutput: publicKey, proof: signature }),
             connectionStatusSubscribe: () => inertObservable(),
         },
@@ -226,7 +263,20 @@ export function createFakeTruApiClient(options?: CreateFakeTruApiClientOptions):
                 return okAsync(key);
             },
         },
-        chain: notModeled("chain"),
+        // Only `getChainInfo` is modeled; the rest of the domain still throws.
+        chain: notModeled("chain", {
+            getChainInfo: ({ chain }) => {
+                if (!chainInfo) return errAsync({ tag: "Unsupported" } as const);
+                const genesisHash = chainInfo.chains[chain];
+                if (!genesisHash) {
+                    return errAsync({
+                        tag: "Domain",
+                        value: { tag: "V1", value: { tag: "NotSupported" } },
+                    } as const);
+                }
+                return okAsync({ network: chainInfo.network, chain, genesisHash });
+            },
+        }),
         chat: notModeled("chat"),
         coinPayment: notModeled("coinPayment"),
         entropy: notModeled("entropy"),
@@ -317,6 +367,7 @@ if (import.meta.vitest) {
         "./container.js"
     );
     const { getAccountsProvider } = await import("./accounts.js");
+    const { getHostChainInfo } = await import("./chain-discovery.js");
     const { getPreimageManager } = await import("./truapi.js");
 
     const lookupOnce = (
@@ -360,6 +411,50 @@ if (import.meta.vitest) {
             expect(userId?.primaryUsername).toBe("carol.dot");
         });
 
+        test("signVrf round-trips through the real adapter", async () => {
+            // The fake is the only way a product can test a VRF flow: there is no
+            // dev-provider implementation and the e2e test host does not expose the
+            // call. So the fake's wire shape has to stay decodable by the adapter.
+            createFakeHost();
+            const accounts = await getAccountsProvider();
+            const signature = await accounts
+                ?.signVrf({ dotNsIdentifier: "app.dot" }, new Uint8Array([1]), [
+                    { label: new Uint8Array([2]), value: new Uint8Array([3]) },
+                ])
+                .match(
+                    (s) => s,
+                    () => null,
+                );
+            expect(signature?.preOutput).toBeInstanceOf(Uint8Array);
+            expect(signature?.proof).toBeInstanceOf(Uint8Array);
+            expect(signature?.preOutput).toHaveLength(32);
+            expect(signature?.proof).toHaveLength(64);
+        });
+
+        test("chain discovery is refused by default, so a legacy host is modeled", async () => {
+            createFakeHost();
+            // Refused, not unmodeled: a bare `getChainAPI("paseo")` in a consumer
+            // test must not warn about the fake on every call.
+            expect(await getHostChainInfo(["AssetHub"])).toBeNull();
+        });
+
+        test("chainInfo drives discovery, with unserved roles left out", async () => {
+            createFakeHost({
+                chainInfo: { network: "paseo", chains: { AssetHub: "0xaa", Bulletin: "0xbb" } },
+            });
+            expect(await getHostChainInfo(["AssetHub", "Bulletin", "People"])).toEqual({
+                network: "paseo",
+                chains: { AssetHub: "0xaa", Bulletin: "0xbb" },
+            });
+        });
+
+        test("the rest of the chain domain still reports itself unmodeled", async () => {
+            const host = createFakeHost();
+            expect(() => (host.client.chain as { chainName?: unknown }).chainName).toThrow(
+                /not modeled by the fake/,
+            );
+        });
+
         test("statement store resolves", async () => {
             createFakeHost();
             expect(await getStatementStore()).not.toBeNull();

package/src/truapi.ts

@@ -183,8 +183,9 @@ export async function createHostPreimageManager(): Promise<PreimageManager | nul
 // Resource-allocation / permission types, re-exported verbatim from
 // `@parity/truapi` (imported above for the local signatures):
 // - `AllocatableResource` — resource types requestable via `requestResourceAllocation`.
-//   Since truapi 0.6.0 its `SmartContractAllowance` variant carries the tagged
-//   `DerivationIndex` selector (`{ tag: "Left", value: number }` for a plain index).
+//   Its `SmartContractAllowance` variant carries the tagged `DerivationIndex`
+//   selector (`{ tag: "Index", value: number }` for a plain index, `{ tag:
+//   "Raw", value: HexString }` for a raw 32-byte index).
 // - `AllocationOutcome` — per-resource outcome, the string union
 //   `"Allocated" | "Rejected" | "NotAvailable"` (RFC-10).
 // - `RemotePermission` — permission the dapp asks the host to grant via `requestPermission`.

package/dist/transport-B0cdhwrp.d.ts

@@ -1,31 +0,0 @@
-import { TrUApiClient } from '@parity/truapi';
-
-/**
- * Access to the in-house TruAPI client (`@parity/truapi`) for the host package.
- *
- * Environment detection and the lazily-built, cached client come from
- * `@parity/truapi/sandbox`; this module layers the product-sdk-specific glue on
- * top — an async {@link getClient} accessor and {@link subscribeWithInterrupt},
- * which adapts a truapi stream into the host's {@link HostSubscription} shape.
- *
- * @module
- */
-
-/**
- * Test-only seam: force {@link getClient} / {@link getClientSync} to return
- * `client`, and {@link isCorrectEnvironment} to report `true`. Pass `null` to
- * restore normal detection. Exposed through `@parity/product-sdk-host/testing`,
- * not the package's main entry.
- *
- * Calling this in a production build silently reroutes every host accessor to
- * the injected client, so we warn — it almost always means a `/testing` import
- * leaked into a production path.
- */
-declare function setTruApiClient(client: TrUApiClient | null): void;
-/**
- * Host-container detection. `true` when a test client is injected, otherwise the
- * sandbox heuristic (iframe / webview marker / injected message port).
- */
-declare function isCorrectEnvironment(): boolean;
-
-export { isCorrectEnvironment as i, setTruApiClient as s };