@novasamatech/host-substrate-chain-connection 0.7.0 → 0.7.1-0

package/dist/connectionPool.d.ts

@@ -15,5 +15,13 @@ export type ChainConnection<C extends ChainConfig, T = PolkadotClient> = {
     getProvider(chain: C): JsonRpcProvider;
     status(genesisHash: string): ConnectionStatus;
     onStatusChanged(genesisHash: string, callback: (status: ConnectionStatus) => void): VoidFunction;
+    /**
+     * Drop the inner socket of every active provider that supports pausing
+     * (e.g. providers built via `createWsJsonRpcProvider`). Clients and
+     * refcounts are preserved; tracked subscriptions are re-sent on
+     * {@link resumeAll} via the replay wrapper.
+     */
+    pauseAll(): void;
+    resumeAll(): void;
 };
 export declare const createChainConnection: <C extends ChainConfig, T = PolkadotClient>({ resolve, clientOptions, createProvider, destroyDelay, }: ChainConnectionConfig<C, T>) => ChainConnection<C, T>;

package/dist/connectionPool.js

@@ -3,6 +3,7 @@ import { createClient } from 'polkadot-api';
 import { createBranchedProvider } from './branchedProvider.js';
 import { createConnectionManager } from './connectionManager.js';
 import { createRefCounter } from './refCounter.js';
+import { isPausable } from './wsProvider.js';
 export const createChainConnection = ({ resolve, clientOptions, createProvider, destroyDelay = 0, }) => {
     const connections = createConnectionManager();
     const refCounter = createRefCounter();
@@ -22,10 +23,10 @@ export const createChainConnection = ({ resolve, clientOptions, createProvider,
         const existing = existingClients.get(chain.genesisHash);
         if (existing)
             return existing;
-        const provider = createProvider(chain, status => connections.update(chain.genesisHash, status));
-        const branchedProvider = createBranchedProvider(provider);
+        const rootProvider = createProvider(chain, status => connections.update(chain.genesisHash, status));
+        const branchedProvider = createBranchedProvider(rootProvider);
         const client = createClient(branchedProvider.branch(), clientOptions?.(chain));
-        const pooled = { client, provider: branchedProvider };
+        const pooled = { client, provider: branchedProvider, rootProvider };
         existingClients.set(chain.genesisHash, pooled);
         return pooled;
     };
@@ -123,5 +124,17 @@ export const createChainConnection = ({ resolve, clientOptions, createProvider,
         onStatusChanged(genesisHash, callback) {
             return connections.onStatusChange(genesisHash, callback);
         },
+        pauseAll() {
+            for (const { rootProvider } of existingClients.values()) {
+                if (isPausable(rootProvider))
+                    rootProvider.pause();
+            }
+        },
+        resumeAll() {
+            for (const { rootProvider } of existingClients.values()) {
+                if (isPausable(rootProvider))
+                    rootProvider.resume();
+            }
+        },
     };
 };

package/dist/connectionPool.spec.js

@@ -205,4 +205,59 @@ describe('createChainConnection', () => {
             });
         });
     });
+    describe('pauseAll / resumeAll', () => {
+        const createPausableMockProvider = () => {
+            const pause = vi.fn();
+            const resume = vi.fn();
+            const provider = Object.assign(() => ({ send: vi.fn(), disconnect: vi.fn() }), {
+                pause,
+                resume,
+            });
+            return { provider, pause, resume };
+        };
+        it('calls pause on every pausable provider created so far', async () => {
+            const chainA = createPausableMockProvider();
+            const chainB = createPausableMockProvider();
+            const providerByChain = { a: chainA.provider, b: chainB.provider };
+            const connection = createChainConnection({
+                createProvider: chain => providerByChain[chain.genesisHash],
+            });
+            const { unlock: u1 } = await connection.lockApi(testChain('a'));
+            const { unlock: u2 } = await connection.lockApi(testChain('b'));
+            connection.pauseAll();
+            expect(chainA.pause).toHaveBeenCalledTimes(1);
+            expect(chainB.pause).toHaveBeenCalledTimes(1);
+            u1();
+            u2();
+        });
+        it('calls resume on every pausable provider', async () => {
+            const chainA = createPausableMockProvider();
+            const connection = createChainConnection({ createProvider: () => chainA.provider });
+            const { unlock } = await connection.lockApi(testChain('a'));
+            connection.pauseAll();
+            connection.resumeAll();
+            expect(chainA.resume).toHaveBeenCalledTimes(1);
+            unlock();
+        });
+        it('skips providers that do not expose pause/resume', async () => {
+            const { connection } = createTestConnection();
+            const { unlock } = await connection.lockApi(testChain('a'));
+            expect(() => {
+                connection.pauseAll();
+                connection.resumeAll();
+            }).not.toThrow();
+            unlock();
+        });
+        it('does not call pause on providers for chains that have been destroyed', async () => {
+            const chainA = createPausableMockProvider();
+            const connection = createChainConnection({
+                createProvider: () => chainA.provider,
+                destroyDelay: 0,
+            });
+            const { unlock } = await connection.lockApi(testChain('a'));
+            unlock();
+            connection.pauseAll();
+            expect(chainA.pause).not.toHaveBeenCalled();
+        });
+    });
 });

package/dist/nodeSubscriptionReplayMiddleware.d.ts

@@ -0,0 +1,2 @@
+import type { Middleware } from '@polkadot-api/ws-provider';
+export declare const nodeSubscriptionReplayMiddleware: Middleware;

package/dist/nodeSubscriptionReplayMiddleware.js

@@ -0,0 +1,105 @@
+import { isResponse } from '@polkadot-api/json-rpc-provider';
+const isChainMethod = (method) => method.startsWith('chain_');
+const isSubscribeMethod = (method) => {
+    if (isChainMethod(method))
+        return false;
+    const m = method.toLowerCase();
+    return m.includes('subscribe') && !m.includes('unsubscribe');
+};
+const isUnsubscribeMethod = (method) => !isChainMethod(method) && method.toLowerCase().includes('unsubscribe');
+// Middleware that replays non-chain subscriptions across reconnects (chain_*
+// subscriptions are handled by PAPI itself).
+//
+// Outgoing subscribe requests are remembered. When the inner provider hands
+// over a new connection, every such request is re-sent so the server assigns
+// fresh subscription ids. The new server ids are remapped back to the id the
+// consumer first saw, keeping inbound notifications and outbound unsubscribes
+// transparent across the drop.
+export const nodeSubscriptionReplayMiddleware = base => {
+    const subs = new Map();
+    const remap = new Map();
+    const pendingReplays = new Map();
+    let counter = 0;
+    const nextReplayId = () => `__replay_${counter++}`;
+    const findReqIdByConsumerSub = (consumerSubId) => {
+        for (const [reqId, sub] of subs)
+            if (sub.consumerSubId === consumerSubId)
+                return reqId;
+        return null;
+    };
+    const consumerToServerSubId = (consumerSubId) => {
+        for (const [server, consumer] of remap)
+            if (consumer === consumerSubId)
+                return server;
+        return consumerSubId;
+    };
+    return (onMessage, onHalt) => {
+        const handleMessage = (raw) => {
+            let msg = raw;
+            if (isResponse(msg)) {
+                const pendingConsumerSubId = pendingReplays.get(msg.id);
+                if (pendingConsumerSubId !== undefined) {
+                    pendingReplays.delete(msg.id);
+                    if ('result' in msg && msg.result !== pendingConsumerSubId)
+                        remap.set(msg.result, pendingConsumerSubId);
+                    return;
+                }
+                const sub = subs.get(msg.id);
+                if (sub) {
+                    if ('result' in msg)
+                        sub.consumerSubId = msg.result;
+                    // subscribe failed — drop so we don't keep a zombie entry across reconnects
+                    else
+                        subs.delete(msg.id);
+                }
+            }
+            else {
+                const consumerSubId = remap.get(msg.params?.subscription);
+                if (consumerSubId !== undefined)
+                    msg = { ...msg, params: { ...msg.params, subscription: consumerSubId } };
+            }
+            onMessage(msg);
+        };
+        // Server sub ids from the prior connection are dead now.
+        remap.clear();
+        pendingReplays.clear();
+        const connection = base(handleMessage, onHalt);
+        for (const { req, consumerSubId } of subs.values()) {
+            if (consumerSubId === undefined)
+                continue;
+            const id = nextReplayId();
+            pendingReplays.set(id, consumerSubId);
+            connection.send({ ...req, id });
+        }
+        return {
+            send(msg) {
+                if (msg.id != null) {
+                    if (isSubscribeMethod(msg.method)) {
+                        subs.set(msg.id, { req: msg });
+                    }
+                    else if (isUnsubscribeMethod(msg.method)) {
+                        const consumerSubId = msg.params?.[0];
+                        if (typeof consumerSubId === 'string') {
+                            const reqId = findReqIdByConsumerSub(consumerSubId);
+                            if (reqId !== null)
+                                subs.delete(reqId);
+                            const serverSubId = consumerToServerSubId(consumerSubId);
+                            if (serverSubId !== consumerSubId) {
+                                remap.delete(serverSubId);
+                                connection.send({ ...msg, params: [serverSubId, ...msg.params.slice(1)] });
+                                return;
+                            }
+                        }
+                    }
+                }
+                connection.send(msg);
+            },
+            disconnect() {
+                subs.clear();
+                remap.clear();
+                pendingReplays.clear();
+                connection.disconnect();
+            },
+        };
+    };
+};

package/dist/nodeSubscriptionReplayMiddleware.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/nodeSubscriptionReplayMiddleware.spec.js

@@ -0,0 +1,255 @@
+import { describe, expect, it, vi } from 'vitest';
+import { nodeSubscriptionReplayMiddleware } from './nodeSubscriptionReplayMiddleware.js';
+const createMockBase = () => {
+    const invocations = [];
+    const base = (onMessage, onHalt) => {
+        const send = vi.fn();
+        const disconnect = vi.fn();
+        invocations.push({ onMessage: onMessage, onHalt: onHalt, send, disconnect });
+        return { send, disconnect };
+    };
+    return {
+        base,
+        invocations,
+        get latest() {
+            const last = invocations[invocations.length - 1];
+            if (!last)
+                throw new Error('no base connection has been created yet');
+            return last;
+        },
+    };
+};
+const req = (id, method, params = []) => ({
+    jsonrpc: '2.0',
+    id,
+    method,
+    params,
+});
+const res = (id, result) => ({ jsonrpc: '2.0', id, result });
+const notify = (method, subscription, result = {}) => ({
+    jsonrpc: '2.0',
+    method,
+    params: { subscription, result },
+});
+const firstSent = (send) => {
+    const call = send.mock.calls[0];
+    if (!call)
+        throw new Error('expected send to have been called at least once');
+    return call[0];
+};
+describe('nodeSubscriptionReplayMiddleware', () => {
+    it('forwards incoming messages to onMessage unmodified', () => {
+        const mock = createMockBase();
+        const onMessage = vi.fn();
+        nodeSubscriptionReplayMiddleware(mock.base)(onMessage, vi.fn());
+        mock.latest.onMessage(res(1, '0xabc'));
+        expect(onMessage).toHaveBeenCalledWith(res(1, '0xabc'));
+    });
+    it('forwards send calls to the underlying connection', () => {
+        const mock = createMockBase();
+        const conn = nodeSubscriptionReplayMiddleware(mock.base)(vi.fn(), vi.fn());
+        conn.send(req(1, 'chain_getBlock'));
+        expect(mock.latest.send).toHaveBeenCalledWith(req(1, 'chain_getBlock'));
+    });
+    it('passes onHalt through to the base connection', () => {
+        const mock = createMockBase();
+        const onHalt = vi.fn();
+        nodeSubscriptionReplayMiddleware(mock.base)(vi.fn(), onHalt);
+        expect(mock.latest.onHalt).toBe(onHalt);
+    });
+    it('does not replay non-subscription requests on reconnect', () => {
+        const mock = createMockBase();
+        const inner = nodeSubscriptionReplayMiddleware(mock.base);
+        const conn = inner(vi.fn(), vi.fn());
+        conn.send(req(1, 'chain_getBlock'));
+        inner(vi.fn(), vi.fn());
+        expect(mock.latest.send).not.toHaveBeenCalled();
+    });
+    it('does not replay pending subscriptions (no server response yet) on reconnect', () => {
+        const mock = createMockBase();
+        const inner = nodeSubscriptionReplayMiddleware(mock.base);
+        const conn = inner(vi.fn(), vi.fn());
+        conn.send(req(1, 'statement_subscribeStatement'));
+        // intentionally no simulated response — subscription not confirmed by server
+        inner(vi.fn(), vi.fn());
+        expect(mock.latest.send).not.toHaveBeenCalled();
+    });
+    it('replays an active subscription on reconnect with a fresh internal id', () => {
+        const mock = createMockBase();
+        const inner = nodeSubscriptionReplayMiddleware(mock.base);
+        const conn = inner(vi.fn(), vi.fn());
+        conn.send(req(1, 'statement_subscribeStatement'));
+        mock.latest.onMessage(res(1, 'srv-1'));
+        inner(vi.fn(), vi.fn());
+        expect(mock.latest.send).toHaveBeenCalledTimes(1);
+        const resent = firstSent(mock.latest.send);
+        expect(resent.method).toBe('statement_subscribeStatement');
+        expect(resent.params).toEqual([]);
+        // internal replay id, distinct from the consumer's original id
+        expect(resent.id).not.toBe(1);
+        expect(typeof resent.id).toBe('string');
+    });
+    it('replays multiple active subscriptions on reconnect', () => {
+        const mock = createMockBase();
+        const inner = nodeSubscriptionReplayMiddleware(mock.base);
+        const conn = inner(vi.fn(), vi.fn());
+        conn.send(req(1, 'statement_subscribeStatement'));
+        mock.latest.onMessage(res(1, 'srv-1'));
+        conn.send(req(2, 'state_subscribeStorage', [[]]));
+        mock.latest.onMessage(res(2, 'srv-2'));
+        inner(vi.fn(), vi.fn());
+        const methods = mock.latest.send.mock.calls.map(c => c[0].method);
+        expect(methods).toHaveLength(2);
+        expect(methods).toContain('statement_subscribeStatement');
+        expect(methods).toContain('state_subscribeStorage');
+    });
+    it('suppresses the replay subscribe response from reaching onMessage', () => {
+        const mock = createMockBase();
+        const inner = nodeSubscriptionReplayMiddleware(mock.base);
+        const conn = inner(vi.fn(), vi.fn());
+        conn.send(req(1, 'statement_subscribeStatement'));
+        mock.latest.onMessage(res(1, 'srv-1'));
+        const onMessage2 = vi.fn();
+        inner(onMessage2, vi.fn());
+        const replayId = firstSent(mock.latest.send).id;
+        mock.latest.onMessage(res(replayId, 'srv-2'));
+        expect(onMessage2).not.toHaveBeenCalled();
+    });
+    it('remaps notifications from the new server sub id to the original consumer id', () => {
+        const mock = createMockBase();
+        const inner = nodeSubscriptionReplayMiddleware(mock.base);
+        const conn = inner(vi.fn(), vi.fn());
+        conn.send(req(1, 'statement_subscribeStatement'));
+        mock.latest.onMessage(res(1, 'srv-1'));
+        const onMessage2 = vi.fn();
+        inner(onMessage2, vi.fn());
+        const replayId = firstSent(mock.latest.send).id;
+        mock.latest.onMessage(res(replayId, 'srv-2'));
+        mock.latest.onMessage(notify('chain_newHead', 'srv-2', { n: 42 }));
+        expect(onMessage2).toHaveBeenCalledWith(notify('chain_newHead', 'srv-1', { n: 42 }));
+    });
+    it('forwards notifications with no remap entry unchanged', () => {
+        const mock = createMockBase();
+        const onMessage = vi.fn();
+        const conn = nodeSubscriptionReplayMiddleware(mock.base)(onMessage, vi.fn());
+        conn.send(req(1, 'statement_subscribeStatement'));
+        mock.latest.onMessage(res(1, 'srv-1'));
+        onMessage.mockClear();
+        const n = notify('chain_newHead', 'srv-1', { n: 1 });
+        mock.latest.onMessage(n);
+        expect(onMessage).toHaveBeenCalledWith(n);
+    });
+    it('does not remap when the replay response returns the same sub id', () => {
+        const mock = createMockBase();
+        const inner = nodeSubscriptionReplayMiddleware(mock.base);
+        const conn = inner(vi.fn(), vi.fn());
+        conn.send(req(1, 'statement_subscribeStatement'));
+        mock.latest.onMessage(res(1, 'srv-1'));
+        const onMessage2 = vi.fn();
+        inner(onMessage2, vi.fn());
+        const replayId = firstSent(mock.latest.send).id;
+        // server assigns the same sub id after reconnect
+        mock.latest.onMessage(res(replayId, 'srv-1'));
+        const n = notify('chain_newHead', 'srv-1', { n: 1 });
+        mock.latest.onMessage(n);
+        expect(onMessage2).toHaveBeenCalledWith(n);
+    });
+    it('translates the consumer sub id to the current server sub id on unsubscribe', () => {
+        const mock = createMockBase();
+        const inner = nodeSubscriptionReplayMiddleware(mock.base);
+        const conn = inner(vi.fn(), vi.fn());
+        conn.send(req(1, 'statement_subscribeStatement'));
+        mock.latest.onMessage(res(1, 'srv-1'));
+        const conn2 = inner(vi.fn(), vi.fn());
+        const replayId = firstSent(mock.latest.send).id;
+        mock.latest.onMessage(res(replayId, 'srv-2'));
+        mock.latest.send.mockClear();
+        conn2.send(req(2, 'statement_unsubscribeStatement', ['srv-1']));
+        expect(mock.latest.send).toHaveBeenCalledWith(req(2, 'statement_unsubscribeStatement', ['srv-2']));
+    });
+    it('forwards unsubscribe unchanged when the sub id was never remapped', () => {
+        const mock = createMockBase();
+        const conn = nodeSubscriptionReplayMiddleware(mock.base)(vi.fn(), vi.fn());
+        conn.send(req(1, 'statement_subscribeStatement'));
+        mock.latest.onMessage(res(1, 'srv-1'));
+        mock.latest.send.mockClear();
+        conn.send(req(2, 'statement_unsubscribeStatement', ['srv-1']));
+        expect(mock.latest.send).toHaveBeenCalledWith(req(2, 'statement_unsubscribeStatement', ['srv-1']));
+    });
+    it('preserves extra unsubscribe params while rewriting only the sub id', () => {
+        const mock = createMockBase();
+        const inner = nodeSubscriptionReplayMiddleware(mock.base);
+        const conn = inner(vi.fn(), vi.fn());
+        conn.send(req(1, 'some_subscribe'));
+        mock.latest.onMessage(res(1, 'srv-1'));
+        const conn2 = inner(vi.fn(), vi.fn());
+        const replayId = firstSent(mock.latest.send).id;
+        mock.latest.onMessage(res(replayId, 'srv-2'));
+        mock.latest.send.mockClear();
+        conn2.send(req(2, 'some_unsubscribe', ['srv-1', 'extra-arg']));
+        expect(mock.latest.send).toHaveBeenCalledWith(req(2, 'some_unsubscribe', ['srv-2', 'extra-arg']));
+    });
+    it('does not replay a subscription after it has been unsubscribed', () => {
+        const mock = createMockBase();
+        const inner = nodeSubscriptionReplayMiddleware(mock.base);
+        const conn = inner(vi.fn(), vi.fn());
+        conn.send(req(1, 'statement_subscribeStatement'));
+        mock.latest.onMessage(res(1, 'srv-1'));
+        conn.send(req(2, 'statement_unsubscribeStatement', ['srv-1']));
+        inner(vi.fn(), vi.fn());
+        expect(mock.latest.send).not.toHaveBeenCalled();
+    });
+    it('removes the remap entry on unsubscribe so late notifications under the old server id pass through unchanged', () => {
+        const mock = createMockBase();
+        const inner = nodeSubscriptionReplayMiddleware(mock.base);
+        const conn = inner(vi.fn(), vi.fn());
+        conn.send(req(1, 'statement_subscribeStatement'));
+        mock.latest.onMessage(res(1, 'srv-1'));
+        const onMessage2 = vi.fn();
+        const conn2 = inner(onMessage2, vi.fn());
+        const replayId = firstSent(mock.latest.send).id;
+        mock.latest.onMessage(res(replayId, 'srv-2'));
+        conn2.send(req(2, 'statement_unsubscribeStatement', ['srv-1']));
+        onMessage2.mockClear();
+        const straggler = notify('chain_newHead', 'srv-2', { n: 9 });
+        mock.latest.onMessage(straggler);
+        expect(onMessage2).toHaveBeenCalledWith(straggler);
+    });
+    it('clears all state on disconnect', () => {
+        const mock = createMockBase();
+        const inner = nodeSubscriptionReplayMiddleware(mock.base);
+        const conn = inner(vi.fn(), vi.fn());
+        conn.send(req(1, 'statement_subscribeStatement'));
+        mock.latest.onMessage(res(1, 'srv-1'));
+        conn.disconnect();
+        expect(mock.latest.disconnect).toHaveBeenCalledTimes(1);
+        // a fresh invocation after disconnect should not replay anything
+        inner(vi.fn(), vi.fn());
+        expect(mock.latest.send).not.toHaveBeenCalled();
+    });
+    it('clears remap across reconnects so stale ids from the prior connection do not leak', () => {
+        const mock = createMockBase();
+        const inner = nodeSubscriptionReplayMiddleware(mock.base);
+        const conn = inner(vi.fn(), vi.fn());
+        conn.send(req(1, 'statement_subscribeStatement'));
+        mock.latest.onMessage(res(1, 'srv-1'));
+        // first reconnect: server re-assigns srv-2 (remap gains srv-2 -> srv-1)
+        const onMessage2 = vi.fn();
+        inner(onMessage2, vi.fn());
+        const replayId2 = firstSent(mock.latest.send).id;
+        mock.latest.onMessage(res(replayId2, 'srv-2'));
+        // second reconnect: remap is cleared BEFORE replay; server assigns srv-3
+        const onMessage3 = vi.fn();
+        inner(onMessage3, vi.fn());
+        const replayId3 = firstSent(mock.latest.send).id;
+        mock.latest.onMessage(res(replayId3, 'srv-3'));
+        // notification under srv-2 from the previous connection must not remap to srv-1
+        const stale = notify('chain_newHead', 'srv-2', { n: 0 });
+        mock.latest.onMessage(stale);
+        expect(onMessage3).toHaveBeenCalledWith(stale);
+        // notification under srv-3 is remapped to the consumer's original id (srv-1)
+        onMessage3.mockClear();
+        mock.latest.onMessage(notify('chain_newHead', 'srv-3', { n: 1 }));
+        expect(onMessage3).toHaveBeenCalledWith(notify('chain_newHead', 'srv-1', { n: 1 }));
+    });
+});

package/dist/pauseController.d.ts

@@ -0,0 +1,8 @@
+import type { Middleware } from '@polkadot-api/ws-provider';
+export type PauseController = {
+    middleware: Middleware;
+    pause: () => void;
+    resume: () => void;
+    isPaused: () => boolean;
+};
+export declare const createPauseController: () => PauseController;

package/dist/pauseController.js

@@ -0,0 +1,67 @@
+// Plugs into getWsProvider's `middleware` option. Pause closes the live socket
+// and stalls auto-reconnect; resume opens a fresh socket and flushes buffered
+// sends.
+export const createPauseController = () => {
+    let paused = false;
+    let destroyed = false;
+    let base = null;
+    let onMessage = null;
+    let onHalt = null;
+    let real = null;
+    let buffer = [];
+    // a halt we fired already scheduled a middleware re-invocation — resume
+    // must defer to it rather than reusing the stale onMessage/onHalt pair
+    let reinvocationPending = false;
+    const connect = () => {
+        if (!base || !onMessage || !onHalt)
+            return;
+        real = base(onMessage, onHalt);
+        const q = buffer;
+        buffer = [];
+        for (const m of q)
+            real.send(m);
+    };
+    const middleware = b => {
+        base = b;
+        return (onMsg, onH) => {
+            reinvocationPending = false;
+            onMessage = onMsg;
+            onHalt = onH;
+            real = null;
+            if (!paused)
+                connect();
+            return {
+                send: m => (real ? real.send(m) : buffer.push(m)),
+                disconnect: () => {
+                    destroyed = true;
+                    paused = false;
+                    buffer = [];
+                    real?.disconnect();
+                    real = null;
+                },
+            };
+        };
+    };
+    const pause = () => {
+        if (paused || destroyed)
+            return;
+        paused = true;
+        if (!real || !onHalt)
+            return;
+        reinvocationPending = true;
+        const r = real;
+        real = null;
+        // withSocket.disconnect detaches listeners before close — no halt fires
+        // from there, so trigger it manually to drive getProxy's replay.
+        r.disconnect();
+        onHalt({ type: 'paused' });
+    };
+    const resume = () => {
+        if (destroyed || !paused)
+            return;
+        paused = false;
+        if (!reinvocationPending)
+            connect();
+    };
+    return { middleware, pause, resume, isPaused: () => paused };
+};

package/dist/pauseController.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/pauseController.spec.js

@@ -0,0 +1,177 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createPauseController } from './pauseController.js';
+const createMockBase = () => {
+    const invocations = [];
+    const base = (onMessage, onHalt) => {
+        const send = vi.fn();
+        const disconnect = vi.fn();
+        invocations.push({ onMessage: onMessage, onHalt: onHalt, send, disconnect });
+        return { send, disconnect };
+    };
+    return {
+        base,
+        invocations,
+        get latest() {
+            const last = invocations[invocations.length - 1];
+            if (!last)
+                throw new Error('no base connection has been created yet');
+            return last;
+        },
+    };
+};
+const req = (id, method, params = []) => ({
+    jsonrpc: '2.0',
+    id,
+    method,
+    params,
+});
+describe('createPauseController', () => {
+    it('connects on first inner invocation and forwards sends', () => {
+        const mock = createMockBase();
+        const pc = createPauseController();
+        const inner = pc.middleware(mock.base);
+        expect(mock.invocations).toHaveLength(0);
+        const conn = inner(vi.fn(), vi.fn());
+        expect(mock.invocations).toHaveLength(1);
+        expect(pc.isPaused()).toBe(false);
+        conn.send(req(1, 'foo'));
+        expect(mock.latest.send).toHaveBeenCalledWith(req(1, 'foo'));
+    });
+    it('forwards inbound messages from the base to the stored onMessage', () => {
+        const mock = createMockBase();
+        const pc = createPauseController();
+        const onMessage = vi.fn();
+        pc.middleware(mock.base)(onMessage, vi.fn());
+        const message = { jsonrpc: '2.0', id: 1, result: 'x' };
+        mock.latest.onMessage(message);
+        expect(onMessage).toHaveBeenCalledWith(message);
+    });
+    it('forwards halts from the base to the stored onHalt', () => {
+        const mock = createMockBase();
+        const pc = createPauseController();
+        const onHalt = vi.fn();
+        pc.middleware(mock.base)(vi.fn(), onHalt);
+        const haltReason = { type: 'socket-closed' };
+        mock.latest.onHalt(haltReason);
+        expect(onHalt).toHaveBeenCalledWith(haltReason);
+    });
+    it('pause disconnects the live socket and fires a paused halt', () => {
+        const mock = createMockBase();
+        const pc = createPauseController();
+        const onHalt = vi.fn();
+        pc.middleware(mock.base)(vi.fn(), onHalt);
+        pc.pause();
+        expect(pc.isPaused()).toBe(true);
+        expect(mock.latest.disconnect).toHaveBeenCalledTimes(1);
+        expect(onHalt).toHaveBeenCalledWith({ type: 'paused' });
+    });
+    it('pause is a no-op when already paused', () => {
+        const mock = createMockBase();
+        const pc = createPauseController();
+        const onHalt = vi.fn();
+        pc.middleware(mock.base)(vi.fn(), onHalt);
+        pc.pause();
+        onHalt.mockClear();
+        pc.pause();
+        expect(mock.latest.disconnect).toHaveBeenCalledTimes(1);
+        expect(onHalt).not.toHaveBeenCalled();
+    });
+    it('pause before the inner provider has been invoked does not fire a halt', () => {
+        const mock = createMockBase();
+        const pc = createPauseController();
+        pc.middleware(mock.base);
+        pc.pause();
+        expect(pc.isPaused()).toBe(true);
+        expect(mock.invocations).toHaveLength(0);
+    });
+    it('buffers sends while paused and flushes them in order after the post-halt re-invocation + resume', () => {
+        const mock = createMockBase();
+        const pc = createPauseController();
+        const inner = pc.middleware(mock.base);
+        const conn = inner(vi.fn(), vi.fn());
+        pc.pause();
+        conn.send(req(1, 'a'));
+        conn.send(req(2, 'b'));
+        // simulate the re-invocation that onHalt → getProxy would drive
+        inner(vi.fn(), vi.fn());
+        expect(mock.invocations).toHaveLength(1); // still paused — no new base connection yet
+        pc.resume();
+        expect(mock.invocations).toHaveLength(2);
+        expect(mock.latest.send).toHaveBeenNthCalledWith(1, req(1, 'a'));
+        expect(mock.latest.send).toHaveBeenNthCalledWith(2, req(2, 'b'));
+        expect(pc.isPaused()).toBe(false);
+    });
+    it('re-invocation while paused does not open a new socket', () => {
+        const mock = createMockBase();
+        const pc = createPauseController();
+        const inner = pc.middleware(mock.base);
+        inner(vi.fn(), vi.fn());
+        pc.pause();
+        inner(vi.fn(), vi.fn());
+        inner(vi.fn(), vi.fn());
+        expect(mock.invocations).toHaveLength(1);
+    });
+    it('resume without a pending re-invocation connects directly', () => {
+        const mock = createMockBase();
+        const pc = createPauseController();
+        const inner = pc.middleware(mock.base);
+        // pause before any real connection exists — no halt fires, so no re-invocation is pending
+        pc.pause();
+        inner(vi.fn(), vi.fn());
+        expect(mock.invocations).toHaveLength(0);
+        pc.resume();
+        expect(mock.invocations).toHaveLength(1);
+        expect(pc.isPaused()).toBe(false);
+    });
+    it('resume is a no-op when not paused', () => {
+        const mock = createMockBase();
+        const pc = createPauseController();
+        const inner = pc.middleware(mock.base);
+        inner(vi.fn(), vi.fn());
+        pc.resume();
+        expect(mock.invocations).toHaveLength(1);
+        expect(pc.isPaused()).toBe(false);
+    });
+    it('after a re-invocation, inbound messages from the new base reach the new onMessage', () => {
+        const mock = createMockBase();
+        const pc = createPauseController();
+        const inner = pc.middleware(mock.base);
+        const firstOnMessage = vi.fn();
+        inner(firstOnMessage, vi.fn());
+        pc.pause();
+        const secondOnMessage = vi.fn();
+        inner(secondOnMessage, vi.fn());
+        pc.resume();
+        const message = { jsonrpc: '2.0', id: 9, result: 'y' };
+        mock.latest.onMessage(message);
+        expect(secondOnMessage).toHaveBeenCalledWith(message);
+        expect(firstOnMessage).not.toHaveBeenCalled();
+    });
+    it('disconnect tears down and makes subsequent pause/resume no-ops', () => {
+        const mock = createMockBase();
+        const pc = createPauseController();
+        const inner = pc.middleware(mock.base);
+        const onHalt = vi.fn();
+        const conn = inner(vi.fn(), onHalt);
+        conn.disconnect();
+        expect(mock.latest.disconnect).toHaveBeenCalledTimes(1);
+        pc.pause();
+        expect(pc.isPaused()).toBe(false);
+        expect(onHalt).not.toHaveBeenCalled();
+        pc.resume();
+        expect(mock.invocations).toHaveLength(1);
+    });
+    it('disconnect drops buffered sends so a later reconnect does not flush stale messages', () => {
+        const mock = createMockBase();
+        const pc = createPauseController();
+        const inner = pc.middleware(mock.base);
+        const conn = inner(vi.fn(), vi.fn());
+        pc.pause();
+        conn.send(req(1, 'lost'));
+        conn.disconnect();
+        // a new controller wouldn't share buffer, but even a fresh inner call on the same
+        // controller (as might happen if getProxy retries) must not replay pre-disconnect buffer
+        inner(vi.fn(), vi.fn());
+        expect(mock.latest.send).not.toHaveBeenCalled();
+    });
+});

package/dist/subscriptionReplayProvider.js

@@ -1,6 +1,12 @@
-const isSubscribeMethod = (method) => method === 'chainHead_v1_follow' ||
-    (method.toLowerCase().includes('subscribe') && !method.toLowerCase().includes('unsubscribe'));
-const isUnsubscribeMethod = (method) => method === 'chainHead_v1_unfollow' || method.toLowerCase().includes('unsubscribe');
+import { isResponse } from '@polkadot-api/json-rpc-provider';
+const isChainMethod = (method) => method.startsWith('chain_');
+const isSubscribeMethod = (method) => {
+    if (isChainMethod(method))
+        return false;
+    const m = method.toLowerCase();
+    return m.includes('subscribe') && !m.includes('unsubscribe');
+};
+const isUnsubscribeMethod = (method) => !isChainMethod(method) && method.toLowerCase().includes('unsubscribe');
 export const withSubscriptionReplay = (provider, onReconnect) => onMessage => {
     // request id → request object (sent, awaiting server subscription ID)
     const pendingSubscriptions = new Map();
@@ -8,11 +14,7 @@ export const withSubscriptionReplay = (provider, onReconnect) => onMessage => {
     const activeSubscriptions = new Map();
     const conn = provider(message => {
         // Response with a string result means it's a subscription confirmation
-        if ('id' in message &&
-            message.id &&
-            !('method' in message) &&
-            'result' in message &&
-            typeof message.result === 'string') {
+        if (message.id && isResponse(message) && 'result' in message && typeof message.result === 'string') {
             const id = message.id;
             const pending = pendingSubscriptions.get(id);
             if (pending !== undefined) {

package/dist/subscriptionReplayProvider.spec.js

@@ -65,7 +65,7 @@ describe('withSubscriptionReplay', () => {
         const mock = createMockProvider();
         const control = createReconnectControl();
         const conn = withSubscriptionReplay(mock.provider, control.onReconnect)(vi.fn());
-        conn.send(req(1, 'chain_subscribeNewHeads'));
+        conn.send(req(1, 'statement_subscribeStatement'));
         // intentionally no simulateMessage — subscription not confirmed by server
         mock.send.mockClear();
         control.triggerReconnect();
@@ -75,7 +75,7 @@ describe('withSubscriptionReplay', () => {
         const mock = createMockProvider();
         const control = createReconnectControl();
         const conn = withSubscriptionReplay(mock.provider, control.onReconnect)(vi.fn());
-        const subscribeMsg = req(1, 'chain_subscribeNewHeads');
+        const subscribeMsg = req(1, 'statement_subscribeStatement');
         conn.send(subscribeMsg);
         mock.simulateMessage(res(1, 'sub-id-1'));
         mock.send.mockClear();
@@ -86,7 +86,7 @@ describe('withSubscriptionReplay', () => {
         const mock = createMockProvider();
         const control = createReconnectControl();
         const conn = withSubscriptionReplay(mock.provider, control.onReconnect)(vi.fn());
-        const msg1 = req(1, 'chain_subscribeNewHeads');
+        const msg1 = req(1, 'statement_subscribeStatement');
         const msg2 = req(2, 'state_subscribeStorage', [[]]);
         conn.send(msg1);
         mock.simulateMessage(res(1, 'sub-id-1'));
@@ -102,7 +102,7 @@ describe('withSubscriptionReplay', () => {
         const mock = createMockProvider();
         const control = createReconnectControl();
         const conn = withSubscriptionReplay(mock.provider, control.onReconnect)(vi.fn());
-        const subscribeMsg = req(1, 'chain_subscribeNewHeads');
+        const subscribeMsg = req(1, 'statement_subscribeStatement');
         conn.send(subscribeMsg);
         mock.simulateMessage(res(1, 'old-sub-id'));
         // First reconnect — replays and moves to pending
@@ -110,7 +110,7 @@ describe('withSubscriptionReplay', () => {
         // Server assigns new subscription ID
         mock.simulateMessage(res(1, 'new-sub-id'));
         // Unsubscribing with the old ID should have no effect (old ID is no longer tracked)
-        conn.send(req(2, 'chain_unsubscribeNewHeads', ['old-sub-id']));
+        conn.send(req(2, 'statement_unsubscribeStatement', ['old-sub-id']));
         mock.send.mockClear();
         // Second reconnect — subscription is still active (new-sub-id was not removed)
         control.triggerReconnect();
@@ -120,9 +120,9 @@ describe('withSubscriptionReplay', () => {
         const mock = createMockProvider();
         const control = createReconnectControl();
         const conn = withSubscriptionReplay(mock.provider, control.onReconnect)(vi.fn());
-        conn.send(req(1, 'chain_subscribeNewHeads'));
+        conn.send(req(1, 'statement_subscribeStatement'));
         mock.simulateMessage(res(1, 'sub-id-1'));
-        conn.send(req(2, 'chain_unsubscribeNewHeads', ['sub-id-1']));
+        conn.send(req(2, 'statement_unsubscribeStatement', ['sub-id-1']));
         mock.send.mockClear();
         control.triggerReconnect();
         expect(mock.send).not.toHaveBeenCalled();
@@ -131,7 +131,7 @@ describe('withSubscriptionReplay', () => {
         const mock = createMockProvider();
         const control = createReconnectControl();
         const conn = withSubscriptionReplay(mock.provider, control.onReconnect)(vi.fn());
-        conn.send(req(1, 'chain_subscribeNewHeads'));
+        conn.send(req(1, 'statement_subscribeStatement'));
         mock.simulateMessage(res(1, 'sub-id-1'));
         conn.disconnect();
         expect(mock.disconnect).toHaveBeenCalledTimes(1);
@@ -141,48 +141,15 @@ describe('withSubscriptionReplay', () => {
         control.triggerReconnect();
         expect(mock.send).not.toHaveBeenCalled();
     });
-    it('does not replay chainHead_v1_follow when pending (no server response yet)', () => {
-        const mock = createMockProvider();
-        const control = createReconnectControl();
-        const conn = withSubscriptionReplay(mock.provider, control.onReconnect)(vi.fn());
-        conn.send(req(1, 'chainHead_v1_follow', [true]));
-        // intentionally no simulateMessage — subscription not confirmed by server
-        mock.send.mockClear();
-        control.triggerReconnect();
-        expect(mock.send).not.toHaveBeenCalled();
-    });
-    it('replays active chainHead_v1_follow subscription on reconnect', () => {
-        const mock = createMockProvider();
-        const control = createReconnectControl();
-        const conn = withSubscriptionReplay(mock.provider, control.onReconnect)(vi.fn());
-        const followMsg = req(1, 'chainHead_v1_follow', [true]);
-        conn.send(followMsg);
-        mock.simulateMessage(res(1, 'follow-sub-id'));
-        mock.send.mockClear();
-        control.triggerReconnect();
-        expect(mock.send).toHaveBeenCalledWith(followMsg);
-    });
-    it('does not replay chainHead_v1_follow after chainHead_v1_unfollow', () => {
-        const mock = createMockProvider();
-        const control = createReconnectControl();
-        const conn = withSubscriptionReplay(mock.provider, control.onReconnect)(vi.fn());
-        conn.send(req(1, 'chainHead_v1_follow', [true]));
-        mock.simulateMessage(res(1, 'follow-sub-id'));
-        conn.send(req(2, 'chainHead_v1_unfollow', ['follow-sub-id']));
-        mock.send.mockClear();
-        control.triggerReconnect();
-        expect(mock.send).not.toHaveBeenCalled();
-    });
-    it('keeps chainHead_v1_follow active when chainHead_v1_unfollow uses wrong sub-id', () => {
+    it('should ignore chain subscriptions', () => {
         const mock = createMockProvider();
         const control = createReconnectControl();
         const conn = withSubscriptionReplay(mock.provider, control.onReconnect)(vi.fn());
-        const followMsg = req(1, 'chainHead_v1_follow', [true]);
-        conn.send(followMsg);
-        mock.simulateMessage(res(1, 'follow-sub-id'));
-        conn.send(req(2, 'chainHead_v1_unfollow', ['wrong-sub-id']));
+        const subscribeMsg = req(1, 'chain_subscribeNewHeads');
+        conn.send(subscribeMsg);
+        mock.simulateMessage(res(1, 'sub-id-1'));
         mock.send.mockClear();
         control.triggerReconnect();
-        expect(mock.send).toHaveBeenCalledWith(followMsg);
+        expect(mock.send).not.toHaveBeenCalledWith(subscribeMsg);
     });
 });

package/dist/types.d.ts

@@ -4,9 +4,10 @@ export type ChainConfig = {
 };
 export type ConnectionStatus = 'connecting' | 'connected' | 'disconnected';
 export type BranchedProvider = {
-    branch(onDisconnect?: VoidFunction): JsonRpcProvider;
+    branch(onHalt?: VoidFunction): JsonRpcProvider;
 };
 export type PooledClient = {
     client: PolkadotClient;
     provider: BranchedProvider;
+    rootProvider: JsonRpcProvider;
 };

package/dist/wsProvider.d.ts

@@ -1,6 +1,15 @@
+import type { SocketLoggerFn } from '@polkadot-api/ws-provider';
 import type { JsonRpcProvider } from 'polkadot-api';
 import type { ConnectionStatus } from './types.js';
+export type PausableJsonRpcProvider = JsonRpcProvider & {
+    pause(): void;
+    resume(): void;
+};
+export declare const isPausable: (provider: JsonRpcProvider) => provider is PausableJsonRpcProvider;
 export declare const createWsJsonRpcProvider: (options: {
     endpoints: string[];
     onStatusChanged?: (status: ConnectionStatus) => void;
-}) => JsonRpcProvider;
+    websocketClass?: typeof WebSocket;
+    heartbeatTimeout?: number;
+    logger?: SocketLoggerFn;
+}) => PausableJsonRpcProvider;

package/dist/wsProvider.js

@@ -1,6 +1,17 @@
-import { WsEvent, getWsProvider } from 'polkadot-api/ws';
+import { WsEvent, getWsProvider } from '@polkadot-api/ws-provider';
 import { noop } from './helpers.js';
+import { createPauseController } from './pauseController.js';
 import { withSubscriptionReplay } from './subscriptionReplayProvider.js';
+export const isPausable = (provider) => {
+    const maybe = provider;
+    return typeof maybe.pause === 'function' && typeof maybe.resume === 'function';
+};
+const STATUS_BY_WS_EVENT = {
+    [WsEvent.CONNECTING]: 'connecting',
+    [WsEvent.CONNECTED]: 'connected',
+    [WsEvent.ERROR]: 'disconnected',
+    [WsEvent.CLOSE]: 'disconnected',
+};
 export const createWsJsonRpcProvider = (options) => {
     let notifyReconnect = noop;
     const onReconnect = (cb) => {
@@ -9,27 +20,23 @@ export const createWsJsonRpcProvider = (options) => {
             notifyReconnect = noop;
         };
     };
-    return withSubscriptionReplay(getWsProvider(options.endpoints, {
-        heartbeatTimeout: Number.POSITIVE_INFINITY,
+    const pauseController = createPauseController();
+    const baseProvider = getWsProvider(options.endpoints, {
+        logger: options.logger,
+        heartbeatTimeout: options.heartbeatTimeout,
+        middleware: inner => pauseController.middleware(inner),
+        websocketClass: options.websocketClass,
         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;
+            const status = STATUS_BY_WS_EVENT[event.type];
+            if (status === 'connected') {
+                notifyReconnect();
             }
             options.onStatusChanged?.(status);
         },
-    }), onReconnect);
+    });
+    const replayProvider = withSubscriptionReplay(baseProvider, onReconnect);
+    return Object.assign(replayProvider, {
+        pause: () => pauseController.pause(),
+        resume: () => pauseController.resume(),
+    });
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@novasamatech/host-substrate-chain-connection",
   "type": "module",
-  "version": "0.7.0",
+  "version": "0.7.1-0",
   "description": "Chain connection pool with ref counting and provider branching for Polkadot API",
   "license": "Apache-2.0",
   "repository": {
@@ -25,7 +25,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@novasamatech/storage-adapter": "0.7.0",
+    "@novasamatech/storage-adapter": "0.7.1-0",
+    "@polkadot-api/ws-provider": "^0.9.0",
+    "@polkadot-api/json-rpc-provider": "^0.2.0",
     "@polkadot-api/json-rpc-provider-proxy": "^0.4.0",
     "nanoevents": "^9.1.0",
     "polkadot-api": ">=2"