@novasamatech/host-substrate-chain-connection 0.6.11 → 0.6.13

package/README.md

@@ -25,33 +25,32 @@ import {
 import { dot } from '@polkadot-api/descriptors';
 
 const polkadot: ChainConfig = {
-  chainId: '0x91b171bb158e2d3848fa23a9f1c25182fb8e20313b2c1eb49219da7a70ce90c3',
-  nodes: [{ url: 'wss://rpc.polkadot.io' }],
+  genesisHash: '0x91b171bb158e2d3848fa23a9f1c25182fb8e20313b2c1eb49219da7a70ce90c3',
+  nodes: ['wss://rpc.polkadot.io'],
 };
 
 const chains = createChainConnection({
   createProvider: (chain, onStatusChanged) =>
     createWsJsonRpcProvider({
-      endpoints: chain.nodes.map((n) => n.url),
+      endpoints: chain.nodes,
       onStatusChanged,
     }),
 });
 
-// One-shot query - connection is acquired and released automatically
-const account = await chains.requestApi(polkadot, async (client) => {
-  const api = client.getTypedApi(dot);
-  return api.query.System.Account.getValue('5GrwvaEF...');
-});
+// Acquire a connection, run a query, then release
+const { api: client, unlock } = await chains.lockApi(polkadot);
+const api = client.getTypedApi(dot);
+const account = await api.query.System.Account.getValue('5GrwvaEF...');
+unlock();
 ```
 
 ## Table of contents
 
 - [API](#api)
   - [`createChainConnection`](#createchainconnectionconfig)
-  - [`requestApi`](#requestapichain-callback)
   - [`lockApi`](#lockapichain)
   - [`getProvider`](#getproviderchain)
-  - [`status` / `onStatusChanged`](#statuschainid--onstatuschangedchainid-callback)
+  - [`status` / `onStatusChanged`](#statusgenesishash--onstatuschangedgenesishash-callback)
   - [`createWsJsonRpcProvider`](#createwsjsonrpcprovideroptions)
   - [`createMetadataCache`](#createmetadatacacheoptions)
 - [Recipes](#recipes)
@@ -82,38 +81,18 @@ function createChainConnection<C extends ChainConfig, T = PolkadotClient>(
 | `createProvider` | `(chain: C, onStatusChanged: (status: ConnectionStatus) => void) => JsonRpcProvider` | Factory for the underlying JSON-RPC transport. Called once per chain. Use `onStatusChanged` to feed connection status back into the pool. |
 | `clientOptions` | `(chain: C) => ClientOptions` | Optional. Returns [polkadot-api client options](https://papi.how/) - typically metadata cache hooks (`getMetadata` / `setMetadata`). |
 | `resolve` | `(chain: C, client: PolkadotClient) => Promise<T>` | Optional. Transforms the raw `PolkadotClient` into your app's API type. The result is cached per chain. If omitted, `T` defaults to `PolkadotClient`. |
+| `destroyDelay` | `number` | Optional. Milliseconds to wait before destroying a connection after the last caller releases. Defaults to `0` (destroy immediately). Useful to avoid reconnect churn when callers release and re-acquire in quick succession. |
 
 **`ChainConfig`** - minimum shape your chain objects must satisfy:
 
 ```ts
 type ChainConfig = {
-  chainId: string;
-  nodes: ReadonlyArray<{ url: string }>;
+  genesisHash: string;
+  nodes: string[];
 };
 ```
 
-Returns a [`ChainConnection<C, T>`](#requestapichain-callback) with the methods below.
-
----
-
-### `requestApi(chain, callback)`
-
-Acquires a connection, runs the callback, and releases automatically when it settles. Best for one-shot queries.
-
-**Signature:**
-
-```ts
-requestApi<Return>(chain: C, callback: (api: T) => Return): Promise<Awaited<Return>>
-```
-
-**Example:**
-
-```ts
-const account = await chains.requestApi(polkadot, async (client) => {
-  const api = client.getTypedApi(dot);
-  return api.query.System.Account.getValue('5GrwvaEF...');
-});
-```
+Returns a [`ChainConnection<C, T>`](#lockapichain) with the methods below.
 
 ---
 
@@ -124,7 +103,7 @@ Acquires a connection and holds it until `unlock()` is called. Use for subscript
 **Signature:**
 
 ```ts
-lockApi(chain: C): Promise<{ api: T; unlock: VoidFunction }>
+function lockApi(chain: C): Promise<{ api: T; unlock: VoidFunction }>
 ```
 
 **Example:**
@@ -157,7 +136,7 @@ Useful for passing a provider to an iframe, webview, or any library that expects
 **Signature:**
 
 ```ts
-getProvider(chain: C): JsonRpcProvider
+function getProvider(chain: C): JsonRpcProvider
 ```
 
 **Example:**
@@ -169,25 +148,25 @@ const provider = chains.getProvider(polkadot);
 
 ---
 
-### `status(chainId)` / `onStatusChanged(chainId, callback)`
+### `status(genesisHash)` / `onStatusChanged(genesisHash, callback)`
 
-Read or subscribe to connection status. Both take a `chainId` string (the genesis hash). Returns `'disconnected'` for chains that have never been connected.
+Read or subscribe to connection status. Both take a `genesisHash` string. Returns `'disconnected'` for chains that have never been connected.
 
 **Signature:**
 
 ```ts
-status(chainId: string): ConnectionStatus
+function status(genesisHash: string): ConnectionStatus
 // ConnectionStatus = 'connecting' | 'connected' | 'disconnected'
 
-onStatusChanged(chainId: string, callback: (status: ConnectionStatus) => void): VoidFunction
+function onStatusChanged(genesisHash: string, callback: (status: ConnectionStatus) => void): VoidFunction
 ```
 
 **Example:**
 
 ```ts
-const currentStatus = chains.status(polkadot.chainId);
+const currentStatus = chains.status(polkadot.genesisHash);
 
-const unsubscribe = chains.onStatusChanged(polkadot.chainId, (status) => {
+const unsubscribe = chains.onStatusChanged(polkadot.genesisHash, (status) => {
   console.info('Polkadot:', status);
 });
 
@@ -199,7 +178,7 @@ unsubscribe();
 
 ### `createWsJsonRpcProvider(options)`
 
-WebSocket provider factory. Wraps polkadot-api's `getWsProvider` with `polkadot-sdk-compat` and translates WebSocket events to `ConnectionStatus`. Active JSON-RPC subscriptions are automatically replayed after a reconnect — consumers using `getProvider` don't need to handle reconnects manually.
+WebSocket provider factory. Wraps polkadot-api's `getWsProvider` and translates WebSocket events to `ConnectionStatus`. Active JSON-RPC subscriptions are automatically replayed after a reconnect — consumers using `getProvider` don't need to handle reconnects manually.
 
 **Signature:**
 
@@ -231,7 +210,7 @@ Caches chain metadata in memory, with optional persistence via a `StorageAdapter
 function createMetadataCache(options?: { storage?: StorageAdapter }): MetadataCache;
 
 type MetadataCache = {
-  forChain(chainId: string): ClientOptions;
+  forChain(genesisHash: string): ClientOptions;
 };
 ```
 
@@ -268,22 +247,25 @@ type ResolvedApi = {
 };
 
 const chains = createChainConnection<ChainConfig, ResolvedApi>({
-  createProvider: (chain, onStatusChanged) =>
-    createWsJsonRpcProvider({
-      endpoints: chain.nodes.map((n) => n.url),
+  createProvider(chain, onStatusChanged) {
+    return createWsJsonRpcProvider({
+      endpoints: chain.nodes,
       onStatusChanged,
-    }),
+    });
+  },
 
-  resolve: async (_chain, client) => ({
-    api: client.getTypedApi(dot),
-    client,
-  }),
+  async resolve (_chain, client) {
+    return {
+      api: client.getTypedApi(dot),
+      client,
+    };
+  },
 });
 
-// Now requestApi and lockApi return ResolvedApi instead of PolkadotClient
-const account = await chains.requestApi(polkadot, async ({ api }) => {
-  return api.query.System.Account.getValue('5GrwvaEF...');
-});
+// Now lockApi returns ResolvedApi instead of PolkadotClient
+const { api: resolved, unlock } = await chains.lockApi(polkadot);
+const account = await resolved.api.query.System.Account.getValue('5GrwvaEF...');
+unlock();
 ```
 
 ---
@@ -300,10 +282,10 @@ const metadataCache = createMetadataCache({
 const chains = createChainConnection({
   createProvider: (chain, onStatusChanged) =>
     createWsJsonRpcProvider({
-      endpoints: chain.nodes.map((n) => n.url),
+      endpoints: chain.nodes,
       onStatusChanged,
     }),
-  clientOptions: (chain) => metadataCache.forChain(chain.chainId),
+  clientOptions: (chain) => metadataCache.forChain(chain.genesisHash),
 });
 ```
 
@@ -334,7 +316,7 @@ const lightClientChainSpecs: Record<string, () => Promise<{ chainSpec: string }>
 let smoldot: SmoldotClient | null = null;
 
 const createLightClientProvider = (chain: MyChain): JsonRpcProvider => {
-  const getChainSpec = lightClientChainSpecs[chain.chainId];
+  const getChainSpec = lightClientChainSpecs[chain.genesisHash];
   if (!getChainSpec) {
     throw new Error(`Light client for chain "${chain.name}" is not supported`);
   }
@@ -351,14 +333,14 @@ const createLightClientProvider = (chain: MyChain): JsonRpcProvider => {
 
 const chains = createChainConnection<MyChain>({
   createProvider: (chain, onStatusChanged) => {
-    if (chain.lightClient && chain.chainId in lightClientChainSpecs) {
+    if (chain.lightClient && chain.genesisHash in lightClientChainSpecs) {
       // Light clients report connected immediately - Smoldot handles syncing internally.
       onStatusChanged('connected');
       return createLightClientProvider(chain);
     }
 
     return createWsJsonRpcProvider({
-      endpoints: chain.nodes.map((n) => n.url),
+      endpoints: chain.nodes,
       onStatusChanged,
     });
   },
@@ -382,8 +364,8 @@ import { dot, ksm, type DotDescriptor, type KsmDescriptor } from '@polkadot-api/
 import { type ChainDefinition, type CompatibilityToken, type TypedApi, getTypedCodecs } from 'polkadot-api';
 
 const descriptorMap: Record<string, ChainDefinition> = {
-  [polkadot.chainId]: dot,
-  [kusama.chainId]: ksm,
+  [polkadot.genesisHash]: dot,
+  [kusama.genesisHash]: ksm,
 };
 
 type ResolvedApi = {
@@ -396,12 +378,12 @@ type ResolvedApi = {
 const chains = createChainConnection<MyChain, ResolvedApi>({
   createProvider: (chain, onStatusChanged) =>
     createWsJsonRpcProvider({
-      endpoints: chain.nodes.map((n) => n.url),
+      endpoints: chain.nodes,
       onStatusChanged,
     }),
 
   resolve: async (chain, client) => {
-    const descriptor = descriptorMap[chain.chainId];
+    const descriptor = descriptorMap[chain.genesisHash];
     const api = client.getTypedApi(descriptor);
 
     // Pre-resolve once - these require async metadata fetches
@@ -454,7 +436,7 @@ graph LR
   end
 
   subgraph Host App
-    HA["requestApi() / lockApi()"]
+    HA["lockApi()"]
     Container
   end
 
@@ -473,7 +455,7 @@ graph LR
 
 Products embedded in iframes or webviews don't connect to RPC nodes directly. They send `remote_chain_*` requests to the **Container**, which obtains a provider from the **Connection Pool** via `getProvider(chain)`.
 
-The host app's own code uses the same pool through `requestApi` and `lockApi`. Everyone shares the same underlying connections - one per chain. The pool opens a connection on first use and closes it when the last consumer releases.
+The host app's own code uses the same pool through `lockApi` and `getProvider`. Everyone shares the same underlying connections - one per chain. The pool opens a connection on first use and closes it when the last consumer releases.
 
 ## Full example
 
@@ -515,7 +497,7 @@ type Chain = ChainConfig & {
 // ---------------------------------------------------------------------------
 // 2. Descriptor resolution
 //
-//    Maps specName → default descriptor, with chainId overrides for
+//    Maps specName → default descriptor, with genesisHash overrides for
 //    parachains that share a specName with their relay chain.
 // ---------------------------------------------------------------------------
 
@@ -539,7 +521,7 @@ const specNameDefaults: Record<string, Descriptor> = {
 };
 
 const getDescriptor = (chain: Chain): Descriptor => {
-  return parachainOverrides[chain.chainId]
+  return parachainOverrides[chain.genesisHash]
     ?? specNameDefaults[chain.specName]
     ?? { type: 'dot', def: dot };
 };
@@ -558,8 +540,8 @@ const lightClientChainSpecs: Record<string, () => Promise<{ chainSpec: string }>
 
 let smoldot: SmoldotClient | null = null;
 
-const createLightClientProvider = (chainId: string): JsonRpcProvider => {
-  const getChainSpec = lightClientChainSpecs[chainId]!;
+const createLightClientProvider = (genesisHash: string): JsonRpcProvider => {
+  const getChainSpec = lightClientChainSpecs[genesisHash]!;
 
   const smoldotChain = getChainSpec().then(({ chainSpec }) => {
     if (!smoldot) {
@@ -600,18 +582,18 @@ type TypedClient = {
 
 const chains = createChainConnection<Chain, TypedClient>({
   createProvider: (chain, onStatusChanged) => {
-    if (chain.chainId in lightClientChainSpecs) {
+    if (chain.genesisHash in lightClientChainSpecs) {
       onStatusChanged('connected');
-      return createLightClientProvider(chain.chainId);
+      return createLightClientProvider(chain.genesisHash);
     }
 
     return createWsJsonRpcProvider({
-      endpoints: chain.nodes.map((n) => n.url),
+      endpoints: chain.nodes,
       onStatusChanged,
     });
   },
 
-  clientOptions: (chain) => metadataCache.forChain(chain.chainId),
+  clientOptions: (chain) => metadataCache.forChain(chain.genesisHash),
 
   resolve: async (chain, client) => {
     const { type, def } = getDescriptor(chain);
@@ -631,16 +613,16 @@ const chains = createChainConnection<Chain, TypedClient>({
 // ---------------------------------------------------------------------------
 
 const polkadot: Chain = {
-  chainId: '0x91b171bb158e2d3848fa23a9f1c25182fb8e20313b2c1eb49219da7a70ce90c3',
+  genesisHash: '0x91b171bb158e2d3848fa23a9f1c25182fb8e20313b2c1eb49219da7a70ce90c3',
   specName: 'polkadot',
   name: 'Polkadot',
-  nodes: [{ url: 'wss://rpc.polkadot.io' }, { url: 'wss://polkadot-rpc.dwellir.com' }],
+  nodes: ['wss://rpc.polkadot.io', 'wss://polkadot-rpc.dwellir.com'],
 };
 
 // One-shot query
-const account = await chains.requestApi(polkadot, async ({ api }) => {
-  return api.query.System.Account.getValue('5GrwvaEF...');
-});
+const { api: queried, unlock: unlockQuery } = await chains.lockApi(polkadot);
+const account = await queried.api.query.System.Account.getValue('5GrwvaEF...');
+unlockQuery();
 
 // Long-lived subscription
 const { api: resolved, unlock } = await chains.lockApi(polkadot);
@@ -654,7 +636,7 @@ sub.unsubscribe();
 unlock();
 
 // Connection status
-const unsubscribe = chains.onStatusChanged(polkadot.chainId, (status) => {
+const unsubscribe = chains.onStatusChanged(polkadot.genesisHash, (status) => {
   console.info(`${polkadot.name}:`, status);
 });
 

package/dist/branchedProvider.d.ts

@@ -1,3 +1,7 @@
 import type { JsonRpcProvider } from '@polkadot-api/json-rpc-provider';
 import type { BranchedProvider } from './types.js';
-export declare const createBranchedProvider: (provider: JsonRpcProvider) => BranchedProvider;
+type Params = {
+    enhanceBranch?(branch: JsonRpcProvider): JsonRpcProvider;
+};
+export declare const createBranchedProvider: (provider: JsonRpcProvider, params?: Params) => BranchedProvider;
+export {};

package/dist/branchedProvider.js

@@ -1,12 +1,14 @@
 import { createNanoEvents } from 'nanoevents';
+import { id } from './helpers.js';
 import { createRefCounter } from './refCounter.js';
-export const createBranchedProvider = (provider) => {
+export const createBranchedProvider = (provider, params) => {
+    const enhancer = params?.enhanceBranch ?? id;
     const messages = createNanoEvents();
     const refs = createRefCounter();
     let connection = null;
     return {
         branch(onDisconnect) {
-            return onMessage => {
+            return enhancer(onMessage => {
                 if (!connection) {
                     connection = provider(message => messages.emit('incoming', message));
                 }
@@ -25,7 +27,7 @@ export const createBranchedProvider = (provider) => {
                         unsub();
                     },
                 };
-            };
+            });
         },
     };
 };

package/dist/branchedProvider.spec.js

@@ -99,4 +99,12 @@ describe('createBranchedProvider', () => {
         conn.send('{"method":"test"}');
         expect(mock.send).toHaveBeenCalledWith('{"method":"test"}');
     });
+    it('calls enhanceBranch for each new branch independently', () => {
+        const mock = createMockProvider();
+        const enhance = vi.fn((p) => p);
+        const branched = createBranchedProvider(mock.provider, { enhanceBranch: enhance });
+        branched.branch()(vi.fn());
+        branched.branch()(vi.fn());
+        expect(enhance).toHaveBeenCalledTimes(2);
+    });
 });

package/dist/connectionPool.d.ts

@@ -3,18 +3,18 @@ import type { PolkadotClient } from 'polkadot-api';
 import { createClient } from 'polkadot-api';
 import type { ChainConfig, ConnectionStatus } from './types.js';
 export type ChainConnectionConfig<C extends ChainConfig, T = PolkadotClient> = {
-    createProvider: (chain: C, onStatusChanged: (status: ConnectionStatus) => void) => JsonRpcProvider;
-    clientOptions?: (chain: C) => Parameters<typeof createClient>[1];
-    resolve?: (chain: C, client: PolkadotClient) => Promise<T>;
+    createProvider(chain: C, onStatusChanged: (status: ConnectionStatus) => void): JsonRpcProvider;
+    clientOptions?(chain: C): Parameters<typeof createClient>[1];
+    resolve?(chain: C, client: PolkadotClient): Promise<T>;
+    destroyDelay?: number;
 };
 export type ChainConnection<C extends ChainConfig, T = PolkadotClient> = {
     lockApi(chain: C): Promise<{
         api: T;
         unlock: VoidFunction;
     }>;
-    requestApi<Return>(chain: C, callback: (api: T) => Return): Promise<Awaited<Return>>;
     getProvider(chain: C): JsonRpcProvider;
-    status(chainId: string): ConnectionStatus;
-    onStatusChanged(chainId: string, callback: (status: ConnectionStatus) => void): VoidFunction;
+    status(genesisHash: string): ConnectionStatus;
+    onStatusChanged(genesisHash: string, callback: (status: ConnectionStatus) => void): VoidFunction;
 };
-export declare const createChainConnection: <C extends ChainConfig, T = PolkadotClient>(config: ChainConnectionConfig<C, T>) => ChainConnection<C, T>;
+export declare const createChainConnection: <C extends ChainConfig, T = PolkadotClient>({ resolve, clientOptions, createProvider, destroyDelay, }: ChainConnectionConfig<C, T>) => ChainConnection<C, T>;

package/dist/connectionPool.js

@@ -3,73 +3,93 @@ import { createClient } from 'polkadot-api';
 import { createBranchedProvider } from './branchedProvider.js';
 import { createConnectionManager } from './connectionManager.js';
 import { createRefCounter } from './refCounter.js';
-export const createChainConnection = (config) => {
+export const createChainConnection = ({ resolve, clientOptions, createProvider, destroyDelay = 0, }) => {
     const connections = createConnectionManager();
     const refCounter = createRefCounter();
     const existingClients = new Map();
     // Resolve cache (when config.resolve is provided)
     const resolvedApis = new Map();
     const pendingResolutions = new Map();
+    const destructionTimers = new Map();
+    const cancelDestructionTimer = (genesisHash) => {
+        const timer = destructionTimers.get(genesisHash);
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            destructionTimers.delete(genesisHash);
+        }
+    };
     const getOrCreateClient = (chain) => {
-        const existing = existingClients.get(chain.chainId);
+        const existing = existingClients.get(chain.genesisHash);
         if (existing)
             return existing;
-        const provider = config.createProvider(chain, status => connections.update(chain.chainId, status));
+        const provider = createProvider(chain, status => connections.update(chain.genesisHash, status));
         const branchedProvider = createBranchedProvider(provider);
-        const client = createClient(branchedProvider.branch(), config.clientOptions?.(chain));
+        const client = createClient(branchedProvider.branch(), clientOptions?.(chain));
         const pooled = { client, provider: branchedProvider };
-        existingClients.set(chain.chainId, pooled);
+        existingClients.set(chain.genesisHash, pooled);
         return pooled;
     };
-    const destroyClient = (chainId) => {
-        const pooled = existingClients.get(chainId);
+    const destroyClient = (genesisHash) => {
+        cancelDestructionTimer(genesisHash);
+        const pooled = existingClients.get(genesisHash);
         if (pooled) {
-            existingClients.delete(chainId);
-            connections.update(chainId, 'disconnected');
+            existingClients.delete(genesisHash);
+            connections.update(genesisHash, 'disconnected');
             pooled.client.destroy();
         }
-        resolvedApis.delete(chainId);
-        pendingResolutions.delete(chainId);
+        resolvedApis.delete(genesisHash);
+        pendingResolutions.delete(genesisHash);
     };
     const rawAcquire = async (chain) => {
         try {
-            refCounter.increment(chain.chainId);
+            if (destroyDelay > 0)
+                cancelDestructionTimer(chain.genesisHash);
+            refCounter.increment(chain.genesisHash);
             const pooled = getOrCreateClient(chain);
-            await pooled.client.getBestBlocks();
             return {
                 pooled,
                 unlock() {
-                    refCounter.decrement(chain.chainId);
+                    if (refCounter.decrement(chain.genesisHash) === 0) {
+                        if (destroyDelay === 0) {
+                            destroyClient(chain.genesisHash);
+                        }
+                        else {
+                            const timer = setTimeout(() => {
+                                destroyClient(chain.genesisHash);
+                            }, destroyDelay);
+                            destructionTimers.set(chain.genesisHash, timer);
+                        }
+                    }
                 },
             };
         }
         catch (error) {
-            if (refCounter.decrement(chain.chainId) === 0) {
-                destroyClient(chain.chainId);
+            if (refCounter.decrement(chain.genesisHash) === 0) {
+                destroyClient(chain.genesisHash);
             }
             throw error;
         }
     };
     const resolveApi = async (chain, polkadotClient) => {
-        if (!config.resolve)
+        if (!resolve)
             return polkadotClient;
-        const existing = resolvedApis.get(chain.chainId);
+        const existing = resolvedApis.get(chain.genesisHash);
         if (existing && existing.polkadotClient === polkadotClient)
             return existing.resolved;
-        const pending = pendingResolutions.get(chain.chainId);
+        const pending = pendingResolutions.get(chain.genesisHash);
         if (pending && pending.polkadotClient === polkadotClient)
             return pending.promise;
         const promise = (async () => {
             // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guarded by early return above
-            const resolved = await config.resolve(chain, polkadotClient);
-            resolvedApis.set(chain.chainId, { resolved, polkadotClient });
+            const resolved = await resolve(chain, polkadotClient);
+            resolvedApis.set(chain.genesisHash, { resolved, polkadotClient });
             return resolved;
         })();
-        pendingResolutions.set(chain.chainId, { promise, polkadotClient });
-        promise.finally(() => pendingResolutions.delete(chain.chainId));
+        pendingResolutions.set(chain.genesisHash, { promise, polkadotClient });
+        promise.finally(() => pendingResolutions.delete(chain.genesisHash));
         return promise;
     };
-    const connection = {
+    return {
         async lockApi(chain) {
             const { pooled, unlock } = await rawAcquire(chain);
             try {
@@ -78,32 +98,22 @@ export const createChainConnection = (config) => {
             }
             catch (error) {
                 unlock();
-                resolvedApis.delete(chain.chainId);
-                pendingResolutions.delete(chain.chainId);
+                resolvedApis.delete(chain.genesisHash);
+                pendingResolutions.delete(chain.genesisHash);
                 throw error;
             }
         },
-        requestApi: (async (chain, callback) => {
-            const { api, unlock } = await connection.lockApi(chain);
-            try {
-                return await callback(api);
-            }
-            finally {
-                unlock();
-            }
-        }),
         getProvider(chain) {
             return getSyncProvider(async () => {
                 const { pooled, unlock } = await rawAcquire(chain);
                 return pooled.provider.branch(unlock);
             });
         },
-        status(chainId) {
-            return connections.getConnectionStatus(chainId);
+        status(genesisHash) {
+            return connections.getConnectionStatus(genesisHash);
         },
-        onStatusChanged(chainId, callback) {
-            return connections.onStatusChange(chainId, callback);
+        onStatusChanged(genesisHash, callback) {
+            return connections.onStatusChange(genesisHash, callback);
         },
     };
-    return connection;
 };

package/dist/connectionPool.spec.js

@@ -1,12 +1,9 @@
-import { describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { createChainConnection } from './connectionPool.js';
 vi.mock('polkadot-api', () => ({
     createClient: vi.fn((_provider, _options) => createMockClient()),
 }));
-const createMockClient = () => ({
-    getBestBlocks: vi.fn().mockResolvedValue([]),
-    destroy: vi.fn(),
-});
+const createMockClient = () => ({ destroy: vi.fn() });
 const createMockProvider = () => {
     const send = vi.fn();
     const disconnect = vi.fn();
@@ -17,7 +14,7 @@ const createMockProvider = () => {
     };
     return { provider, send, disconnect, simulateMessage: (msg) => onMessage?.(msg) };
 };
-const testChain = (id) => ({ chainId: id, nodes: [{ url: 'wss://test' }] });
+const testChain = (id) => ({ genesisHash: id, nodes: ['wss://test'] });
 const createTestConnection = (overrides) => {
     const mockProvider = createMockProvider();
     const connection = createChainConnection({
@@ -52,12 +49,6 @@ describe('createChainConnection', () => {
             u1();
             u2();
         });
-        it('calls getBestBlocks to verify connectivity', async () => {
-            const { connection } = createTestConnection();
-            const { api, unlock } = await connection.lockApi(testChain('a'));
-            expect(api.getBestBlocks).toHaveBeenCalled();
-            unlock();
-        });
     });
     describe('lockApi — with resolve', () => {
         it('calls resolve with chain and polkadotClient', async () => {
@@ -90,24 +81,6 @@ describe('createChainConnection', () => {
         });
     });
     describe('lockApi — error handling', () => {
-        it('throws when getBestBlocks rejects', async () => {
-            vi.mocked(await import('polkadot-api')).createClient.mockReturnValueOnce({
-                getBestBlocks: vi.fn().mockRejectedValue(new Error('connection failed')),
-                destroy: vi.fn(),
-            });
-            const { connection } = createTestConnection();
-            await expect(connection.lockApi(testChain('a'))).rejects.toThrow('connection failed');
-        });
-        it('destroys client on error when ref count reaches 0', async () => {
-            const destroyFn = vi.fn();
-            vi.mocked(await import('polkadot-api')).createClient.mockReturnValueOnce({
-                getBestBlocks: vi.fn().mockRejectedValue(new Error('fail')),
-                destroy: destroyFn,
-            });
-            const { connection } = createTestConnection();
-            await expect(connection.lockApi(testChain('a'))).rejects.toThrow();
-            expect(destroyFn).toHaveBeenCalled();
-        });
         it('throws when resolve rejects and calls unlock', async () => {
             const resolve = vi.fn().mockRejectedValue(new Error('resolve failed'));
             const { connection } = createTestConnection({ resolve });
@@ -127,32 +100,6 @@ describe('createChainConnection', () => {
             unlock();
         });
     });
-    describe('requestApi', () => {
-        it('calls callback with api and returns result', async () => {
-            const { connection } = createTestConnection();
-            const result = await connection.requestApi(testChain('a'), api => {
-                expect(api).toBeDefined();
-                return 42;
-            });
-            expect(result).toBe(42);
-        });
-        it('unlocks after callback completes', async () => {
-            const { connection } = createTestConnection();
-            await connection.requestApi(testChain('a'), () => 'done');
-            // Subsequent request should work without issue
-            const result = await connection.requestApi(testChain('a'), () => 'again');
-            expect(result).toBe('again');
-        });
-        it('unlocks when callback throws', async () => {
-            const { connection } = createTestConnection();
-            await expect(connection.requestApi(testChain('a'), () => {
-                throw new Error('callback error');
-            })).rejects.toThrow('callback error');
-            // Should still work after error
-            const result = await connection.requestApi(testChain('a'), () => 'ok');
-            expect(result).toBe('ok');
-        });
-    });
     describe('status / onStatusChanged', () => {
         it('returns disconnected for unknown chain', () => {
             const { connection } = createTestConnection();
@@ -189,4 +136,70 @@ describe('createChainConnection', () => {
             expect(callback).not.toHaveBeenCalled();
         });
     });
+    describe('lockApi — connection lifecycle', () => {
+        it('destroys client synchronously when last lock is released (no destroyDelay)', async () => {
+            const destroyFn = vi.fn();
+            vi.mocked(await import('polkadot-api')).createClient.mockReturnValueOnce({
+                getBestBlocks: vi.fn().mockResolvedValue([]),
+                destroy: destroyFn,
+            });
+            const { connection } = createTestConnection();
+            const { unlock } = await connection.lockApi(testChain('a'));
+            unlock();
+            expect(destroyFn).toHaveBeenCalledOnce();
+        });
+        it('does not destroy while any lock is still held', async () => {
+            const destroyFn = vi.fn();
+            vi.mocked(await import('polkadot-api')).createClient.mockReturnValueOnce({
+                getBestBlocks: vi.fn().mockResolvedValue([]),
+                destroy: destroyFn,
+            });
+            const { connection } = createTestConnection();
+            const chain = testChain('a');
+            const { unlock: u1 } = await connection.lockApi(chain);
+            const { unlock: u2 } = await connection.lockApi(chain);
+            u1();
+            expect(destroyFn).not.toHaveBeenCalled();
+            u2();
+            expect(destroyFn).toHaveBeenCalledOnce();
+        });
+        describe('with destroyDelay', () => {
+            beforeEach(() => {
+                vi.useFakeTimers();
+            });
+            afterEach(() => {
+                vi.useRealTimers();
+            });
+            it('defers destruction by destroyDelay ms', async () => {
+                const destroyFn = vi.fn();
+                vi.mocked(await import('polkadot-api')).createClient.mockReturnValueOnce({
+                    getBestBlocks: vi.fn().mockResolvedValue([]),
+                    destroy: destroyFn,
+                });
+                const { connection } = createTestConnection({ destroyDelay: 1000 });
+                const { unlock } = await connection.lockApi(testChain('a'));
+                unlock();
+                expect(destroyFn).not.toHaveBeenCalled();
+                vi.advanceTimersByTime(1000);
+                expect(destroyFn).toHaveBeenCalledOnce();
+            });
+            it('cancels destruction timer when connection is re-acquired before delay elapses', async () => {
+                const destroyFn = vi.fn();
+                vi.mocked(await import('polkadot-api')).createClient.mockReturnValueOnce({
+                    getBestBlocks: vi.fn().mockResolvedValue([]),
+                    destroy: destroyFn,
+                });
+                const { connection } = createTestConnection({ destroyDelay: 1000 });
+                const chain = testChain('a');
+                const { api: api1, unlock: u1 } = await connection.lockApi(chain);
+                u1();
+                // Re-acquire before timer fires — same client must be returned, no destruction
+                const { api: api2, unlock: u2 } = await connection.lockApi(chain);
+                vi.advanceTimersByTime(1000);
+                expect(destroyFn).not.toHaveBeenCalled();
+                expect(api1).toBe(api2);
+                u2();
+            });
+        });
+    });
 });

package/dist/helpers.d.ts

@@ -0,0 +1,2 @@
+export declare function id<T>(x: T): T;
+export declare function noop(): void;

package/dist/helpers.js

@@ -0,0 +1,6 @@
+export function id(x) {
+    return x;
+}
+export function noop() {
+    // empty
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { type ChainConnection, type ChainConnectionConfig, createChainConnection } from './connectionPool.js';
 export { type MetadataCache, createMetadataCache } from './metadataCache.js';
 export { withSubscriptionReplay } from './subscriptionReplayProvider.js';
-export { createWsJsonRpcProvider } from './providers.js';
+export { createWsJsonRpcProvider } from './wsProvider.js';
 export { type ChainConfig, type ConnectionStatus } from './types.js';

package/dist/index.js

@@ -1,5 +1,5 @@
 export { createChainConnection } from './connectionPool.js';
 export { createMetadataCache } from './metadataCache.js';
 export { withSubscriptionReplay } from './subscriptionReplayProvider.js';
-export { createWsJsonRpcProvider } from './providers.js';
+export { createWsJsonRpcProvider } from './wsProvider.js';
 export {} from './types.js';

package/dist/types.d.ts

@@ -1,10 +1,8 @@
 import type { JsonRpcProvider } from '@polkadot-api/json-rpc-provider';
 import type { PolkadotClient } from 'polkadot-api';
 export type ChainConfig = {
-    chainId: string;
-    nodes: ReadonlyArray<{
-        url: string;
-    }>;
+    genesisHash: string;
+    nodes: string[];
 };
 export type ConnectionStatus = 'connecting' | 'connected' | 'disconnected';
 export type BranchedProvider = {

package/dist/wsProvider.d.ts

@@ -0,0 +1,6 @@
+import type { JsonRpcProvider } from '@polkadot-api/json-rpc-provider';
+import type { ConnectionStatus } from './types.js';
+export declare const createWsJsonRpcProvider: (options: {
+    endpoints: string[];
+    onStatusChanged?: (status: ConnectionStatus) => void;
+}) => JsonRpcProvider;

package/dist/wsProvider.js

@@ -0,0 +1,35 @@
+import { WsEvent, getWsProvider } from '@polkadot-api/ws-provider';
+import { noop } from './helpers.js';
+import { withSubscriptionReplay } from './subscriptionReplayProvider.js';
+export const createWsJsonRpcProvider = (options) => {
+    let notifyReconnect = noop;
+    const onReconnect = (cb) => {
+        notifyReconnect = cb;
+        return () => {
+            notifyReconnect = noop;
+        };
+    };
+    return withSubscriptionReplay(getWsProvider(options.endpoints, {
+        heartbeatTimeout: Number.POSITIVE_INFINITY,
+        onStatusChanged: event => {
+            let status;
+            switch (event.type) {
+                case WsEvent.CONNECTING:
+                    status = 'connecting';
+                    break;
+                case WsEvent.CONNECTED:
+                    notifyReconnect();
+                    status = 'connected';
+                    break;
+                case WsEvent.ERROR:
+                case WsEvent.CLOSE:
+                    status = 'disconnected';
+                    break;
+                default:
+                    status = 'disconnected';
+                    break;
+            }
+            options.onStatusChanged?.(status);
+        },
+    }), onReconnect);
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@novasamatech/host-substrate-chain-connection",
   "type": "module",
-  "version": "0.6.11",
+  "version": "0.6.13",
   "description": "Chain connection pool with ref counting and provider branching for Polkadot API",
   "license": "Apache-2.0",
   "repository": {
@@ -25,9 +25,10 @@
     "README.md"
   ],
   "dependencies": {
-    "@novasamatech/storage-adapter": "0.6.11",
+    "@novasamatech/storage-adapter": "0.6.13",
     "@polkadot-api/json-rpc-provider": "^0.0.4",
     "@polkadot-api/json-rpc-provider-proxy": "^0.2.8",
+    "@polkadot-api/ws-provider": "^0.7.5",
     "nanoevents": "^9.1.0",
     "polkadot-api": "^1.23.3"
   },