@parity/product-sdk-chain-client 0.1.0

package/src/clients.ts

@@ -0,0 +1,346 @@
+import type { ChainDefinition, PolkadotClient } from "polkadot-api";
+import { createClient } from "polkadot-api";
+import { createProvider } from "./providers.js";
+import { getClientCache, clearClientCache } from "./hmr.js";
+import type { ChainEntry, ChainClientConfig, ChainClient } from "./types.js";
+
+// Cache keys are scoped by a fingerprint of the config so that two
+// `createChainClient` calls with different chain sets don't collide.
+const cacheKey = (fingerprint: string, genesis: string) => `${fingerprint}:${genesis}`;
+
+function findEntryByGenesis(genesis: string): ChainEntry | undefined {
+    for (const [key, entry] of getClientCache()) {
+        if (key.endsWith(`:${genesis}`)) return entry;
+    }
+}
+
+const clientInstances = new Map<string, Promise<ChainClient<any>>>();
+
+/** Build a stable fingerprint from sorted chain names + genesis hashes. */
+function configFingerprint(chains: Record<string, ChainDefinition>): string {
+    return Object.entries(chains)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([name, desc]) => `${name}:${desc.genesis ?? "unknown"}`)
+        .join("|");
+}
+
+/**
+ * Create a multi-chain client with user-provided descriptors and RPC endpoints.
+ *
+ * Returns fully-typed APIs for each chain plus raw `PolkadotClient` access via `.raw`.
+ * Connections use host routing (via `@parity/product-sdk-host`) when inside a container,
+ * falling back to direct WebSocket RPC.
+ *
+ * Results are cached by genesis-hash fingerprint — calling with the same descriptors
+ * returns the same instance.
+ *
+ * @example
+ * ```ts
+ * import { createChainClient } from "@parity/product-sdk-chain-client";
+ * import { paseo_asset_hub } from "./descriptors/paseo-asset-hub";
+ * import { bulletin } from "./descriptors/bulletin";
+ *
+ * const client = await createChainClient({
+ *     chains: { assetHub: paseo_asset_hub, bulletin },
+ *     rpcs: {
+ *         assetHub: ["wss://sys.ibp.network/asset-hub-paseo"],
+ *         bulletin: ["wss://paseo-bulletin-rpc.polkadot.io"],
+ *     },
+ * });
+ *
+ * // Fully typed from your descriptors
+ * const account = await client.assetHub.query.System.Account.getValue(addr);
+ * const fee = await client.bulletin.query.TransactionStorage.ByteFee.getValue();
+ *
+ * // Raw client for advanced use (e.g., InkSdk for contracts)
+ * import { createInkSdk } from "@polkadot-api/sdk-ink";
+ * const inkSdk = createInkSdk(client.raw.assetHub, { atBest: true });
+ *
+ * // Cleanup
+ * client.destroy();
+ * ```
+ */
+export async function createChainClient<const TChains extends Record<string, ChainDefinition>>(
+    config: ChainClientConfig<TChains>,
+): Promise<ChainClient<TChains>> {
+    const fingerprint = configFingerprint(config.chains);
+
+    const existing = clientInstances.get(fingerprint);
+    if (existing) return existing as Promise<ChainClient<TChains>>;
+
+    const promise = initChainClient(config, fingerprint).catch((err) => {
+        // Clean up any clients created before the failure to avoid leaking
+        // WebSocket connections that are unreachable except via destroyAll().
+        const cache = getClientCache();
+        for (const [key, entry] of cache) {
+            if (key.startsWith(`${fingerprint}:`)) {
+                try {
+                    entry.client.destroy();
+                } catch {
+                    /* already destroyed */
+                }
+                cache.delete(key);
+            }
+        }
+        clientInstances.delete(fingerprint);
+        throw err;
+    });
+    clientInstances.set(fingerprint, promise);
+    return promise;
+}
+
+/* @integration */
+async function initChainClient<const TChains extends Record<string, ChainDefinition>>(
+    config: ChainClientConfig<TChains>,
+    fingerprint: string,
+): Promise<ChainClient<TChains>> {
+    const names = Object.keys(config.chains) as (string & keyof TChains)[];
+    const clientCache = getClientCache();
+
+    // Create providers and clients in parallel
+    const entries = await Promise.all(
+        names.map(async (name) => {
+            const descriptor = config.chains[name] as ChainDefinition;
+            const genesis = descriptor.genesis;
+            if (!genesis) {
+                throw new Error(`Descriptor for chain "${name}" has no genesis hash.`);
+            }
+            const provider = await createProvider(genesis);
+            const client = createClient(provider);
+
+            // Populate HMR cache so getClient() and isConnected() work
+            const key = cacheKey(fingerprint, genesis);
+            if (!clientCache.has(key)) {
+                clientCache.set(key, {
+                    client,
+                    api: new Map(),
+                } satisfies ChainEntry);
+            }
+
+            return { name, descriptor, client, genesis };
+        }),
+    );
+
+    // Build typed APIs and raw client map
+    const apis = {} as Record<string, unknown>;
+    const raw = {} as Record<string, PolkadotClient>;
+
+    for (const { name, descriptor, client } of entries) {
+        apis[name] = client.getTypedApi(descriptor);
+        raw[name] = client;
+    }
+
+    return {
+        ...apis,
+        raw,
+        destroy() {
+            for (const { genesis } of entries) {
+                const key = cacheKey(fingerprint, genesis);
+                const entry = clientCache.get(key);
+                if (entry) {
+                    try {
+                        entry.client.destroy();
+                    } catch {
+                        /* already destroyed */
+                    }
+                    clientCache.delete(key);
+                }
+            }
+            clientInstances.delete(fingerprint);
+        },
+    } as ChainClient<TChains>;
+}
+
+/**
+ * Destroy all chain client instances and reset internal caches.
+ *
+ * Tears down every connection created by {@link createChainClient}.
+ */
+export function destroyAll(): void {
+    clearClientCache();
+    clientInstances.clear();
+}
+
+/**
+ * Get the raw `PolkadotClient` for a connected chain by its descriptor.
+ *
+ * The chain must have been initialized via {@link createChainClient} first.
+ * Alternatively, use `client.raw.<name>` on the returned {@link ChainClient}.
+ *
+ * @throws If the chain has not been connected yet.
+ */
+export function getClient(descriptor: ChainDefinition): PolkadotClient {
+    const genesis = descriptor.genesis;
+    if (!genesis) throw new Error("Descriptor has no genesis hash.");
+    const entry = findEntryByGenesis(genesis);
+    if (!entry?.client) {
+        throw new Error(
+            `Chain not connected (genesis: ${genesis}). Call createChainClient() first to establish connections.`,
+        );
+    }
+    return entry.client;
+}
+
+/**
+ * Check if a chain is currently connected.
+ *
+ * Synchronous — no side effects, no initialization.
+ */
+export function isConnected(descriptor: ChainDefinition): boolean {
+    const genesis = descriptor.genesis;
+    if (!genesis) return false;
+    return findEntryByGenesis(genesis) !== undefined;
+}
+
+if (import.meta.vitest) {
+    const { test, expect, beforeEach } = import.meta.vitest;
+
+    const fakeDescriptor = { genesis: "0xtest" } as ChainDefinition;
+    const fakeClient = {
+        destroy: () => {},
+        getTypedApi: () => ({}),
+    } as unknown as PolkadotClient;
+
+    function seedCache(genesis: string, client: PolkadotClient, fp = "test") {
+        getClientCache().set(cacheKey(fp, genesis), {
+            client,
+            api: new Map(),
+        });
+    }
+
+    beforeEach(() => {
+        clearClientCache();
+        clientInstances.clear();
+    });
+
+    // --- isConnected ---
+
+    test("isConnected returns false for unknown chain", () => {
+        expect(isConnected(fakeDescriptor)).toBe(false);
+    });
+
+    test("isConnected returns true after cache is populated", () => {
+        seedCache("0xtest", fakeClient);
+        expect(isConnected(fakeDescriptor)).toBe(true);
+    });
+
+    test("isConnected returns false for descriptor without genesis", () => {
+        expect(isConnected({} as ChainDefinition)).toBe(false);
+    });
+
+    // --- getClient ---
+
+    test("getClient returns client from cache", () => {
+        seedCache("0xtest", fakeClient);
+        expect(getClient(fakeDescriptor)).toBe(fakeClient);
+    });
+
+    test("getClient throws for unconnected chain", () => {
+        expect(() => getClient(fakeDescriptor)).toThrow(/Chain not connected/);
+    });
+
+    test("getClient throws for descriptor without genesis", () => {
+        expect(() => getClient({} as ChainDefinition)).toThrow(/no genesis hash/);
+    });
+
+    // --- destroyAll ---
+
+    test("destroyAll calls client.destroy() and clears caches", () => {
+        let destroyed = false;
+        const trackableClient = {
+            destroy: () => {
+                destroyed = true;
+            },
+            getTypedApi: () => ({}),
+        } as unknown as PolkadotClient;
+        seedCache("0xtest", trackableClient);
+        clientInstances.set("test", Promise.resolve({} as ChainClient<any>));
+        destroyAll();
+        expect(destroyed).toBe(true);
+        expect(isConnected(fakeDescriptor)).toBe(false);
+        expect(clientInstances.size).toBe(0);
+    });
+
+    // --- createChainClient ---
+
+    test("createChainClient returns same promise for identical config", async () => {
+        const fakeResult = {} as ChainClient<any>;
+        const fp = configFingerprint({ a: fakeDescriptor });
+        clientInstances.set(fp, Promise.resolve(fakeResult));
+        const result = await createChainClient({
+            chains: { a: fakeDescriptor },
+            rpcs: { a: [] },
+        });
+        expect(result).toBe(fakeResult);
+    });
+
+    test("createChainClient deduplicates concurrent calls", async () => {
+        const fakeResult = {} as ChainClient<any>;
+        const fp = configFingerprint({ x: fakeDescriptor });
+        clientInstances.set(fp, Promise.resolve(fakeResult));
+        const [a, b] = await Promise.all([
+            createChainClient({ chains: { x: fakeDescriptor }, rpcs: { x: [] } }),
+            createChainClient({ chains: { x: fakeDescriptor }, rpcs: { x: [] } }),
+        ]);
+        expect(a).toBe(b);
+    });
+
+    test("createChainClient returns different results for different configs", async () => {
+        const descA = { genesis: "0xaaa" } as ChainDefinition;
+        const descB = { genesis: "0xbbb" } as ChainDefinition;
+        const resultA = {} as ChainClient<any>;
+        const resultB = {} as ChainClient<any>;
+        clientInstances.set(configFingerprint({ a: descA }), Promise.resolve(resultA));
+        clientInstances.set(configFingerprint({ b: descB }), Promise.resolve(resultB));
+        const a = await createChainClient({ chains: { a: descA }, rpcs: { a: [] } });
+        const b = await createChainClient({ chains: { b: descB }, rpcs: { b: [] } });
+        expect(a).not.toBe(b);
+    });
+
+    // --- configFingerprint ---
+
+    test("configFingerprint is stable regardless of key order", () => {
+        const d1 = { genesis: "0x1" } as ChainDefinition;
+        const d2 = { genesis: "0x2" } as ChainDefinition;
+        expect(configFingerprint({ a: d1, b: d2 })).toBe(configFingerprint({ b: d2, a: d1 }));
+    });
+
+    // --- findEntryByGenesis ---
+
+    test("findEntryByGenesis returns undefined for missing genesis", () => {
+        expect(findEntryByGenesis("0xnonexistent")).toBeUndefined();
+    });
+
+    // --- full lifecycle ---
+
+    test("full lifecycle: seed, verify connected, destroy, verify disconnected", () => {
+        seedCache("0xtest", fakeClient);
+        expect(isConnected(fakeDescriptor)).toBe(true);
+        expect(getClient(fakeDescriptor)).toBe(fakeClient);
+        destroyAll();
+        expect(isConnected(fakeDescriptor)).toBe(false);
+        expect(() => getClient(fakeDescriptor)).toThrow(/Chain not connected/);
+    });
+
+    test("two fingerprints cached independently, destroy one leaves other intact", () => {
+        const sharedGenesis = "0xshared";
+        const clientA = { destroy: () => {} } as PolkadotClient;
+        const clientB = { destroy: () => {} } as PolkadotClient;
+        const descriptorShared = { genesis: sharedGenesis } as ChainDefinition;
+
+        seedCache(sharedGenesis, clientA, "fpA");
+        seedCache(sharedGenesis, clientB, "fpB");
+
+        expect(isConnected(descriptorShared)).toBe(true);
+
+        // Destroy only fpA's entry
+        const cache = getClientCache();
+        const keyA = cacheKey("fpA", sharedGenesis);
+        cache.get(keyA)?.client.destroy();
+        cache.delete(keyA);
+
+        // fpB's entry still alive
+        expect(isConnected(descriptorShared)).toBe(true);
+        expect(getClient(descriptorShared)).toBe(clientB);
+    });
+}

package/src/hmr.ts

@@ -0,0 +1,39 @@
+import type { ChainEntry } from "./types.js";
+
+declare global {
+    var __chainClientCache: Map<string, ChainEntry> | undefined;
+}
+
+/** Get the HMR-safe client cache, keyed by genesis hash. */
+export function getClientCache(): Map<string, ChainEntry> {
+    globalThis.__chainClientCache ??= new Map();
+    return globalThis.__chainClientCache;
+}
+
+/** Clear all entries from the client cache. Destroys active clients. */
+export function clearClientCache(): void {
+    const cache = getClientCache();
+    for (const entry of cache.values()) {
+        try {
+            entry.client.destroy();
+        } catch {
+            // client may already be destroyed
+        }
+    }
+    cache.clear();
+}
+
+if (import.meta.vitest) {
+    const { test, expect } = import.meta.vitest;
+
+    test("getClientCache returns a Map", () => {
+        const cache = getClientCache();
+        expect(cache).toBeInstanceOf(Map);
+    });
+
+    test("getClientCache returns the same instance on repeated calls", () => {
+        const a = getClientCache();
+        const b = getClientCache();
+        expect(a).toBe(b);
+    });
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+// Core BYOD API — zero descriptor overhead
+export { createChainClient, destroyAll, getClient, isConnected } from "./clients.js";
+
+// Preset environments — zero-config path with built-in descriptors
+export { getChainAPI } from "./presets.js";
+export type { Environment, PresetChains } from "./presets.js";
+
+// Types
+export type { ChainClient, ChainClientConfig, ChainEntry } from "./types.js";
+
+// Re-export from host
+export { isInsideContainer, isInsideContainerSync } from "@parity/product-sdk-host";

package/src/presets.ts

@@ -0,0 +1,221 @@
+import type { ChainDefinition } from "polkadot-api";
+import { BULLETIN_RPCS } from "@parity/product-sdk-host";
+import { createChainClient } from "./clients.js";
+import type { ChainClient } from "./types.js";
+
+// Type-only imports — erased at compile time, zero bundle cost.
+// These give us per-chain TypedApi types without importing runtime descriptor data.
+import type { polkadot_asset_hub as PolkadotAssetHubDef } from "@parity/product-sdk-descriptors/polkadot-asset-hub";
+import type { kusama_asset_hub as KusamaAssetHubDef } from "@parity/product-sdk-descriptors/kusama-asset-hub";
+import type { paseo_asset_hub as PaseoAssetHubDef } from "@parity/product-sdk-descriptors/paseo-asset-hub";
+import type { bulletin as BulletinDef } from "@parity/product-sdk-descriptors/bulletin";
+import type { individuality as IndividualityDef } from "@parity/product-sdk-descriptors/individuality";
+
+/** Known network environment with built-in descriptors and RPC endpoints. */
+export type Environment = "polkadot" | "kusama" | "paseo";
+
+/** Environments where all chains (asset hub, bulletin, individuality) are live. */
+const AVAILABLE_ENVIRONMENTS: Set<Environment> = new Set(["paseo"]);
+
+const rpcs = {
+    polkadot: {
+        assetHub: [
+            "wss://polkadot-asset-hub-rpc.polkadot.io",
+            "wss://sys.ibp.network/asset-hub-polkadot",
+        ],
+        bulletin: [...BULLETIN_RPCS.polkadot],
+        individuality: [] as string[],
+    },
+    kusama: {
+        assetHub: [
+            "wss://kusama-asset-hub-rpc.polkadot.io",
+            "wss://sys.ibp.network/asset-hub-kusama",
+        ],
+        bulletin: [...BULLETIN_RPCS.kusama],
+        individuality: [] as string[],
+    },
+    paseo: {
+        assetHub: [
+            "wss://asset-hub-paseo-rpc.n.dwellir.com",
+            "wss://sys.ibp.network/asset-hub-paseo",
+        ],
+        bulletin: [...BULLETIN_RPCS.paseo],
+        individuality: ["wss://paseo-people-next-rpc.polkadot.io"],
+    },
+} as const;
+
+/**
+ * Lazy-load descriptors for a specific environment.
+ * Only imports the chains needed — avoids bundling all 5 chains when
+ * a consumer only uses one environment.
+ */
+async function loadDescriptors(env: Environment) {
+    const assetHubImport = {
+        polkadot: () => import("@parity/product-sdk-descriptors/polkadot-asset-hub"),
+        kusama: () => import("@parity/product-sdk-descriptors/kusama-asset-hub"),
+        paseo: () => import("@parity/product-sdk-descriptors/paseo-asset-hub"),
+    }[env]();
+
+    const [ahMod, { bulletin }, { individuality }] = await Promise.all([
+        assetHubImport,
+        import("@parity/product-sdk-descriptors/bulletin"),
+        import("@parity/product-sdk-descriptors/individuality"),
+    ]);
+
+    // Extract the asset hub descriptor (the named export varies per environment)
+    const assetHub =
+        "polkadot_asset_hub" in ahMod
+            ? ahMod.polkadot_asset_hub
+            : "kusama_asset_hub" in ahMod
+              ? ahMod.kusama_asset_hub
+              : (ahMod as typeof import("@parity/product-sdk-descriptors/paseo-asset-hub"))
+                    .paseo_asset_hub;
+
+    return { assetHub, bulletin, individuality };
+}
+
+/** Maps each environment to its asset hub descriptor type. */
+type AssetHubDescriptors = {
+    polkadot: typeof PolkadotAssetHubDef;
+    kusama: typeof KusamaAssetHubDef;
+    paseo: typeof PaseoAssetHubDef;
+};
+
+/** The chain shape returned by {@link getChainAPI} for a given environment. */
+export type PresetChains<E extends Environment> = {
+    assetHub: AssetHubDescriptors[E];
+    bulletin: typeof BulletinDef;
+    individuality: typeof IndividualityDef;
+};
+
+/**
+ * Get a chain client for a known environment with built-in descriptors and RPCs.
+ *
+ * This is the **zero-config** path — no need to import descriptors or specify
+ * endpoints. For custom chains or BYOD descriptors, use
+ * {@link createChainClient} instead.
+ *
+ * Returns the same {@link ChainClient} type as `createChainClient`, with
+ * `assetHub`, `bulletin`, and `individuality` chain keys.
+ *
+ * @example
+ * ```ts
+ * import { getChainAPI } from "@parity/product-sdk-chain-client";
+ *
+ * const client = await getChainAPI("paseo");
+ *
+ * // Fully typed — no descriptor imports needed
+ * const account = await client.assetHub.query.System.Account.getValue(addr);
+ * const fee = await client.bulletin.query.TransactionStorage.ByteFee.getValue();
+ *
+ * // Raw client for advanced use (e.g., InkSdk for contracts)
+ * import { createInkSdk } from "@polkadot-api/sdk-ink";
+ * const inkSdk = createInkSdk(client.raw.assetHub, { atBest: true });
+ *
+ * client.destroy();
+ * ```
+ */
+export async function getChainAPI<E extends Environment>(
+    env: E,
+): Promise<ChainClient<PresetChains<E>>> {
+    if (!AVAILABLE_ENVIRONMENTS.has(env)) {
+        throw new Error(`Chain API for "${env}" is not yet available`);
+    }
+
+    const descriptors = await loadDescriptors(env);
+    const envRpcs = rpcs[env];
+
+    return createChainClient({
+        chains: {
+            assetHub: descriptors.assetHub,
+            bulletin: descriptors.bulletin,
+            individuality: descriptors.individuality,
+        },
+        rpcs: {
+            assetHub: [...envRpcs.assetHub],
+            bulletin: [...envRpcs.bulletin],
+            individuality: [...envRpcs.individuality],
+        },
+    }) as Promise<ChainClient<PresetChains<E>>>;
+}
+
+if (import.meta.vitest) {
+    const { test, expect, beforeEach } = import.meta.vitest;
+    const { destroyAll } = await import("./clients.js");
+
+    // Test-only genesis hashes for assertion — not used in production code.
+    const GENESIS = {
+        polkadot_asset_hub: "0x68d56f15f85d3136970ec16946040bc1752654e906147f7e43e9d539d7c3de2f",
+        kusama_asset_hub: "0x48239ef607d7928874027a43a67689209727dfb3d3dc5e5b03a39bdc2eda771a",
+        paseo_asset_hub: "0xd6eec26135305a8ad257a20d003357284c8aa03d0bdb2b357ab0a22371e11ef2",
+        bulletin: "0x744960c32e3a3df5440e1ecd4d34096f1ce2230d7016a5ada8a765d5a622b4ea",
+        individuality: "0xd01475fde5d0592989b7715ae1d2e89fdb4f8c7688c09c850d75e1d4bdb47d64",
+    } as const;
+
+    beforeEach(() => {
+        destroyAll();
+    });
+
+    // --- GENESIS constants ---
+
+    test("genesis constants are valid hex hashes", () => {
+        for (const hash of Object.values(GENESIS)) {
+            expect(hash).toMatch(/^0x[a-f0-9]{64}$/);
+        }
+    });
+
+    // --- RPC config ---
+
+    test("rpcs defined for all environments", () => {
+        for (const env of ["polkadot", "kusama", "paseo"] as const) {
+            const envRpcs = rpcs[env];
+            expect(envRpcs.assetHub.length).toBeGreaterThan(0);
+        }
+    });
+
+    test("paseo has RPCs for all chains", () => {
+        const envRpcs = rpcs.paseo;
+        expect(envRpcs.bulletin.length).toBeGreaterThan(0);
+        expect(envRpcs.individuality.length).toBeGreaterThan(0);
+    });
+
+    // --- getChainAPI ---
+
+    test("polkadot and kusama throw as not yet available", async () => {
+        await expect(getChainAPI("polkadot")).rejects.toThrow("not yet available");
+        await expect(getChainAPI("kusama")).rejects.toThrow("not yet available");
+    });
+
+    // --- loadDescriptors ---
+
+    test("loadDescriptors returns descriptors with genesis hashes for paseo", async () => {
+        const descriptors = await loadDescriptors("paseo");
+        expect(descriptors).toBeDefined();
+        expect(descriptors.assetHub).toBeDefined();
+        expect(descriptors.bulletin).toBeDefined();
+        expect(descriptors.individuality).toBeDefined();
+        expect(descriptors.assetHub.genesis).toBe(GENESIS.paseo_asset_hub);
+        expect(descriptors.bulletin.genesis).toBe(GENESIS.bulletin);
+        expect(descriptors.individuality.genesis).toBe(GENESIS.individuality);
+    });
+
+    test("loadDescriptors returns correct asset hub per environment", async () => {
+        const polkadot = await loadDescriptors("polkadot");
+        const kusama = await loadDescriptors("kusama");
+        const paseo = await loadDescriptors("paseo");
+        expect(polkadot.assetHub.genesis).toBe(GENESIS.polkadot_asset_hub);
+        expect(kusama.assetHub.genesis).toBe(GENESIS.kusama_asset_hub);
+        expect(paseo.assetHub.genesis).toBe(GENESIS.paseo_asset_hub);
+        // bulletin and individuality are the same across environments
+        expect(polkadot.bulletin.genesis).toBe(paseo.bulletin.genesis);
+        expect(polkadot.individuality.genesis).toBe(paseo.individuality.genesis);
+    });
+
+    // --- AVAILABLE_ENVIRONMENTS ---
+
+    test("only paseo is currently available", () => {
+        expect(AVAILABLE_ENVIRONMENTS.has("paseo")).toBe(true);
+        expect(AVAILABLE_ENVIRONMENTS.has("polkadot")).toBe(false);
+        expect(AVAILABLE_ENVIRONMENTS.has("kusama")).toBe(false);
+    });
+}

package/src/providers.ts

@@ -0,0 +1,57 @@
+import { getHostProvider } from "@parity/product-sdk-host";
+import type { JsonRpcProvider } from "polkadot-api/ws-provider/web";
+
+/**
+ * Create a PAPI-compatible JSON-RPC provider for a chain.
+ *
+ * Routes connections through the host provider (`@parity/product-sdk-host`).
+ * The SDK is designed to run exclusively inside a host container.
+ *
+ * @throws {Error} If the host provider is unavailable (not inside a container).
+ */
+export async function createProvider(genesisHash: string): Promise<JsonRpcProvider> {
+    const hostProvider = await getHostProvider(genesisHash as `0x${string}`);
+    if (!hostProvider) {
+        throw new Error(
+            `Host provider unavailable for chain ${genesisHash}. Ensure you are running inside a host container (Polkadot Browser / Desktop).`,
+        );
+    }
+    return hostProvider;
+}
+
+if (import.meta.vitest) {
+    const { test, expect, vi, beforeEach } = import.meta.vitest;
+
+    // Shared state between hoisted mocks and tests
+    const state = vi.hoisted(() => ({
+        fakeProvider: (() => {}) as unknown as JsonRpcProvider,
+        hostProviderCalls: [] as unknown[][],
+        hostProviderAvailable: true,
+    }));
+
+    vi.mock("@parity/product-sdk-host", async (importOriginal) => ({
+        ...(await importOriginal<typeof import("@parity/product-sdk-host")>()),
+        getHostProvider: async (...args: unknown[]) => {
+            state.hostProviderCalls.push(args);
+            if (!state.hostProviderAvailable) return null;
+            return state.fakeProvider;
+        },
+    }));
+
+    beforeEach(() => {
+        state.hostProviderCalls = [];
+        state.hostProviderAvailable = true;
+    });
+
+    test("returns host provider when available", async () => {
+        const result = await createProvider("0xabc");
+        expect(result).toBe(state.fakeProvider);
+        expect(state.hostProviderCalls.length).toBe(1);
+        expect(state.hostProviderCalls[0][0]).toBe("0xabc");
+    });
+
+    test("throws when host provider unavailable", async () => {
+        state.hostProviderAvailable = false;
+        await expect(createProvider("0xabc")).rejects.toThrow(/Host provider unavailable/);
+    });
+}