@pezkuwi/rpc-provider 16.5.5 → 16.5.6

package/bizinikiwi-connect/index.js

@@ -0,0 +1,319 @@
+import { EventEmitter } from 'eventemitter3';
+import { isError, isFunction, isObject, logger, noop, objectSpread } from '@pezkuwi/util';
+import { RpcCoder } from '../coder/index.js';
+import { healthChecker } from './Health.js';
+const l = logger('api-bizinikiwi-connect');
+const subscriptionUnsubscriptionMethods = new Map([
+    ['author_submitAndWatchExtrinsic', 'author_unwatchExtrinsic'],
+    ['chain_subscribeAllHeads', 'chain_unsubscribeAllHeads'],
+    ['chain_subscribeFinalizedHeads', 'chain_unsubscribeFinalizedHeads'],
+    ['chain_subscribeFinalisedHeads', 'chain_subscribeFinalisedHeads'],
+    ['chain_subscribeNewHeads', 'chain_unsubscribeNewHeads'],
+    ['chain_subscribeNewHead', 'chain_unsubscribeNewHead'],
+    ['chain_subscribeRuntimeVersion', 'chain_unsubscribeRuntimeVersion'],
+    ['subscribe_newHead', 'unsubscribe_newHead'],
+    ['state_subscribeRuntimeVersion', 'state_unsubscribeRuntimeVersion'],
+    ['state_subscribeStorage', 'state_unsubscribeStorage']
+]);
+const scClients = new WeakMap();
+export class ScProvider {
+    #Sc;
+    #coder = new RpcCoder();
+    #spec;
+    #sharedSandbox;
+    #subscriptions = new Map();
+    #resubscribeMethods = new Map();
+    #requests = new Map();
+    #wellKnownChains;
+    #eventemitter = new EventEmitter();
+    #chain = null;
+    #isChainReady = false;
+    constructor(Sc, spec, sharedSandbox) {
+        if (!isObject(Sc) || !isObject(Sc.WellKnownChain) || !isFunction(Sc.createScClient)) {
+            throw new Error('Expected an @bizinikiwi/connect interface as first parameter to ScProvider');
+        }
+        this.#Sc = Sc;
+        this.#spec = spec;
+        this.#sharedSandbox = sharedSandbox;
+        this.#wellKnownChains = new Set(Object.values(Sc.WellKnownChain));
+    }
+    get hasSubscriptions() {
+        // Indicates that subscriptions are supported
+        return !!true;
+    }
+    get isClonable() {
+        return !!false;
+    }
+    get isConnected() {
+        return !!this.#chain && this.#isChainReady;
+    }
+    clone() {
+        throw new Error('clone() is not supported.');
+    }
+    // Config details can be found in @bizinikiwi/connect repo following the link:
+    // https://github.com/pezkuwichain/bizinikiwi-connect/blob/main/packages/connect/src/connector/index.ts
+    async connect(config, checkerFactory = healthChecker) {
+        if (this.isConnected) {
+            throw new Error('Already connected!');
+        }
+        // it could happen that after emitting `disconnected` due to the fact that
+        // smoldot is syncing, the consumer tries to reconnect after a certain amount
+        // of time... In which case we want to make sure that we don't create a new
+        // chain.
+        if (this.#chain) {
+            await this.#chain;
+            return;
+        }
+        if (this.#sharedSandbox && !this.#sharedSandbox.isConnected) {
+            await this.#sharedSandbox.connect();
+        }
+        const client = this.#sharedSandbox
+            ? scClients.get(this.#sharedSandbox)
+            : this.#Sc.createScClient(config);
+        if (!client) {
+            throw new Error('Unknown ScProvider!');
+        }
+        scClients.set(this, client);
+        const hc = checkerFactory();
+        const onResponse = (res) => {
+            const hcRes = hc.responsePassThrough(res);
+            if (!hcRes) {
+                return;
+            }
+            const response = JSON.parse(hcRes);
+            let decodedResponse;
+            try {
+                decodedResponse = this.#coder.decodeResponse(response);
+            }
+            catch (e) {
+                decodedResponse = e;
+            }
+            // It's not a subscription message, but rather a standar RPC response
+            if (response.params?.subscription === undefined || !response.method) {
+                return this.#requests.get(response.id)?.(decodedResponse);
+            }
+            // We are dealing with a subscription message
+            const subscriptionId = `${response.method}::${response.params.subscription}`;
+            const callback = this.#subscriptions.get(subscriptionId)?.[0];
+            callback?.(decodedResponse);
+        };
+        const addChain = this.#sharedSandbox
+            ? (async (...args) => {
+                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                const source = this.#sharedSandbox;
+                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                return (await source.#chain).addChain(...args);
+            })
+            : this.#wellKnownChains.has(this.#spec)
+                ? client.addWellKnownChain
+                : client.addChain;
+        this.#chain = addChain(this.#spec).then((chain) => {
+            hc.setSendJsonRpc(chain.sendJsonRpc);
+            // Start async response processing loop
+            // This replaces the callback-based API from older @substrate/connect versions
+            (async () => {
+                try {
+                    for await (const res of chain.jsonRpcResponses) {
+                        onResponse(res);
+                    }
+                }
+                catch {
+                    // Chain was removed or connection closed - this is expected
+                }
+            })();
+            this.#isChainReady = false;
+            const cleanup = () => {
+                // If there are any callbacks left, we have to reject/error them.
+                // Otherwise, that would cause a memory leak.
+                const disconnectionError = new Error('Disconnected');
+                this.#requests.forEach((cb) => cb(disconnectionError));
+                this.#subscriptions.forEach(([cb]) => cb(disconnectionError));
+                this.#subscriptions.clear();
+            };
+            const staleSubscriptions = [];
+            const killStaleSubscriptions = () => {
+                if (staleSubscriptions.length === 0) {
+                    return;
+                }
+                const stale = staleSubscriptions.pop();
+                if (!stale) {
+                    throw new Error('Unable to get stale subscription');
+                }
+                const { id, unsubscribeMethod } = stale;
+                Promise
+                    .race([
+                    this.send(unsubscribeMethod, [id]).catch(noop),
+                    new Promise((resolve) => setTimeout(resolve, 500))
+                ])
+                    .then(killStaleSubscriptions)
+                    .catch(noop);
+            };
+            hc.start((health) => {
+                const isReady = !health.isSyncing && (health.peers > 0 || !health.shouldHavePeers);
+                // if it's the same as before, then nothing has changed and we are done
+                if (this.#isChainReady === isReady) {
+                    return;
+                }
+                this.#isChainReady = isReady;
+                if (!isReady) {
+                    // If we've reached this point, that means that the chain used to be "ready"
+                    // and now we are about to emit `disconnected`.
+                    //
+                    // This will cause the PezkuwiJs API think that the connection is
+                    // actually dead. In reality the smoldot chain is not dead, of course.
+                    // However, we have to cleanup all the existing callbacks because when
+                    // the smoldot chain stops syncing, then we will emit `connected` and
+                    // the PezkuwiJs API will try to re-create the previous
+                    // subscriptions and requests. Although, now is not a good moment
+                    // to be sending unsubscription messages to the smoldot chain, we
+                    // should wait until is no longer syncing to send the unsubscription
+                    // messages from the stale subscriptions of the previous connection.
+                    //
+                    // That's why -before we perform the cleanup of `this.#subscriptions`-
+                    // we keep the necessary information that we will need later on to
+                    // kill the stale subscriptions.
+                    [...this.#subscriptions.values()].forEach((s) => {
+                        staleSubscriptions.push(s[1]);
+                    });
+                    cleanup();
+                    this.#eventemitter.emit('disconnected');
+                }
+                else {
+                    killStaleSubscriptions();
+                    this.#eventemitter.emit('connected');
+                    if (this.#resubscribeMethods.size) {
+                        this.#resubscribe();
+                    }
+                }
+            });
+            return objectSpread({}, chain, {
+                remove: () => {
+                    hc.stop();
+                    chain.remove();
+                    cleanup();
+                },
+                sendJsonRpc: hc.sendJsonRpc.bind(hc)
+            });
+        });
+        try {
+            await this.#chain;
+        }
+        catch (e) {
+            this.#chain = null;
+            this.#eventemitter.emit('error', e);
+            throw e;
+        }
+    }
+    #resubscribe = () => {
+        const promises = [];
+        this.#resubscribeMethods.forEach((subDetails) => {
+            // only re-create subscriptions which are not in author (only area where
+            // transactions are created, i.e. submissions such as 'author_submitAndWatchExtrinsic'
+            // are not included (and will not be re-broadcast)
+            if (subDetails.type.startsWith('author_')) {
+                return;
+            }
+            try {
+                const promise = new Promise((resolve) => {
+                    this.subscribe(subDetails.type, subDetails.method, subDetails.params, subDetails.callback).catch((error) => console.log(error));
+                    resolve();
+                });
+                promises.push(promise);
+            }
+            catch (error) {
+                l.error(error);
+            }
+        });
+        Promise.all(promises).catch((err) => l.log(err));
+    };
+    async disconnect() {
+        if (!this.#chain) {
+            return;
+        }
+        const chain = await this.#chain;
+        this.#chain = null;
+        this.#isChainReady = false;
+        try {
+            chain.remove();
+        }
+        catch (_) { }
+        this.#eventemitter.emit('disconnected');
+    }
+    on(type, sub) {
+        // It's possible. Although, quite unlikely, that by the time that pezkuwi
+        // subscribes to the `connected` event, the Provider is already connected.
+        // In that case, we must emit to let the consumer know that we are connected.
+        if (type === 'connected' && this.isConnected) {
+            sub();
+        }
+        this.#eventemitter.on(type, sub);
+        return () => {
+            this.#eventemitter.removeListener(type, sub);
+        };
+    }
+    async send(method, params) {
+        if (!this.isConnected || !this.#chain) {
+            throw new Error('Provider is not connected');
+        }
+        const chain = await this.#chain;
+        const [id, json] = this.#coder.encodeJson(method, params);
+        const result = new Promise((resolve, reject) => {
+            this.#requests.set(id, (response) => {
+                (isError(response) ? reject : resolve)(response);
+            });
+            try {
+                chain.sendJsonRpc(json);
+            }
+            catch (e) {
+                this.#chain = null;
+                try {
+                    chain.remove();
+                }
+                catch (_) { }
+                this.#eventemitter.emit('error', e);
+            }
+        });
+        try {
+            return await result;
+        }
+        finally {
+            // let's ensure that once the Promise is resolved/rejected, then we remove
+            // remove its entry from the internal #requests
+            this.#requests.delete(id);
+        }
+    }
+    async subscribe(type, method, params, callback) {
+        if (!subscriptionUnsubscriptionMethods.has(method)) {
+            throw new Error(`Unsupported subscribe method: ${method}`);
+        }
+        const id = await this.send(method, params);
+        const subscriptionId = `${type}::${id}`;
+        const cb = (response) => {
+            if (response instanceof Error) {
+                callback(response, undefined);
+            }
+            else {
+                callback(null, response);
+            }
+        };
+        const unsubscribeMethod = subscriptionUnsubscriptionMethods.get(method);
+        if (!unsubscribeMethod) {
+            throw new Error('Invalid unsubscribe method found');
+        }
+        this.#resubscribeMethods.set(subscriptionId, { callback, method, params, type });
+        this.#subscriptions.set(subscriptionId, [cb, { id, unsubscribeMethod }]);
+        return id;
+    }
+    unsubscribe(type, method, id) {
+        if (!this.isConnected) {
+            throw new Error('Provider is not connected');
+        }
+        const subscriptionId = `${type}::${id}`;
+        if (!this.#subscriptions.has(subscriptionId)) {
+            return Promise.reject(new Error(`Unable to find active subscription=${subscriptionId}`));
+        }
+        this.#resubscribeMethods.delete(subscriptionId);
+        this.#subscriptions.delete(subscriptionId);
+        return this.send(method, [id]);
+    }
+}

package/{build/bundle.d.ts → bundle.d.ts}

@@ -1,5 +1,5 @@
 export { HttpProvider } from './http/index.js';
 export { DEFAULT_CAPACITY, LRUCache } from './lru.js';
 export { packageInfo } from './packageInfo.js';
-export { ScProvider } from './substrate-connect/index.js';
+export { ScProvider } from './bizinikiwi-connect/index.js';
 export { WsProvider } from './ws/index.js';

package/{src/bundle.ts → bundle.js}

@@ -1,8 +1,5 @@
-// Copyright 2017-2025 @polkadot/rpc-provider authors & contributors
-// SPDX-License-Identifier: Apache-2.0
-
 export { HttpProvider } from './http/index.js';
 export { DEFAULT_CAPACITY, LRUCache } from './lru.js';
 export { packageInfo } from './packageInfo.js';
-export { ScProvider } from './substrate-connect/index.js';
+export { ScProvider } from './bizinikiwi-connect/index.js';
 export { WsProvider } from './ws/index.js';

package/cjs/bizinikiwi-connect/Health.d.ts

@@ -0,0 +1,7 @@
+import type { HealthChecker } from './types.js';
+export declare function healthChecker(): HealthChecker;
+export declare class HealthCheckError extends Error {
+    #private;
+    getCause(): unknown;
+    constructor(response: unknown, message?: string);
+}

package/cjs/bizinikiwi-connect/Health.js

@@ -0,0 +1,264 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HealthCheckError = void 0;
+exports.healthChecker = healthChecker;
+const util_1 = require("@pezkuwi/util");
+/*
+ * Creates a new health checker.
+ *
+ * The role of the health checker is to report to the user the health of a smoldot chain.
+ *
+ * In order to use it, start by creating a health checker, and call `setSendJsonRpc` to set the
+ * way to send a JSON-RPC request to a chain. The health checker is disabled by default. Use
+ * `start()` in order to start the health checks. The `start()` function must be passed a callback called
+ * when an update to the health of the node is available.
+ *
+ * In order to send a JSON-RPC request to the chain, you **must** use the `sendJsonRpc` function
+ * of the health checker. The health checker rewrites the `id` of the requests it receives.
+ *
+ * When the chain send a JSON-RPC response, it must be passed to `responsePassThrough()`. This
+ * function intercepts the responses destined to the requests that have been emitted by the health
+ * checker and returns `null`. If the response doesn't concern the health checker, the response is
+ * simply returned by the function.
+ *
+ * # How it works
+ *
+ * The health checker periodically calls the `system_health` JSON-RPC call in order to determine
+ * the health of the chain.
+ *
+ * In addition to this, as long as the health check reports that `isSyncing` is `true`, the
+ * health checker also maintains a subscription to new best blocks using `chain_subscribeNewHeads`.
+ * Whenever a new block is notified, a health check is performed immediately in order to determine
+ * whether `isSyncing` has changed to `false`.
+ *
+ * Thanks to this subscription, the latency of the report of the switch from `isSyncing: true` to
+ * `isSyncing: false` is very low.
+ *
+ */
+function healthChecker() {
+    // `null` if health checker is not started.
+    let checker = null;
+    let sendJsonRpc = null;
+    return {
+        responsePassThrough: (jsonRpcResponse) => {
+            if (checker === null) {
+                return jsonRpcResponse;
+            }
+            return checker.responsePassThrough(jsonRpcResponse);
+        },
+        sendJsonRpc: (request) => {
+            if (!sendJsonRpc) {
+                throw new Error('setSendJsonRpc must be called before sending requests');
+            }
+            if (checker === null) {
+                sendJsonRpc(request);
+            }
+            else {
+                checker.sendJsonRpc(request);
+            }
+        },
+        setSendJsonRpc: (cb) => {
+            sendJsonRpc = cb;
+        },
+        start: (healthCallback) => {
+            if (checker !== null) {
+                throw new Error("Can't start the health checker multiple times in parallel");
+            }
+            else if (!sendJsonRpc) {
+                throw new Error('setSendJsonRpc must be called before starting the health checks');
+            }
+            checker = new InnerChecker(healthCallback, sendJsonRpc);
+            checker.update(true);
+        },
+        stop: () => {
+            if (checker === null) {
+                return;
+            } // Already stopped.
+            checker.destroy();
+            checker = null;
+        }
+    };
+}
+class InnerChecker {
+    #healthCallback;
+    #currentHealthCheckId = null;
+    #currentHealthTimeout = null;
+    #currentSubunsubRequestId = null;
+    #currentSubscriptionId = null;
+    #requestToSmoldot;
+    #isSyncing = false;
+    #nextRequestId = 0;
+    constructor(healthCallback, requestToSmoldot) {
+        this.#healthCallback = healthCallback;
+        this.#requestToSmoldot = (request) => requestToSmoldot((0, util_1.stringify)(request));
+    }
+    sendJsonRpc = (request) => {
+        // Replace the `id` in the request to prefix the request ID with `extern:`.
+        let parsedRequest;
+        try {
+            parsedRequest = JSON.parse(request);
+        }
+        catch {
+            return;
+        }
+        if (parsedRequest.id) {
+            const newId = 'extern:' + (0, util_1.stringify)(parsedRequest.id);
+            parsedRequest.id = newId;
+        }
+        this.#requestToSmoldot(parsedRequest);
+    };
+    responsePassThrough = (jsonRpcResponse) => {
+        let parsedResponse;
+        try {
+            parsedResponse = JSON.parse(jsonRpcResponse);
+        }
+        catch {
+            return jsonRpcResponse;
+        }
+        // Check whether response is a response to `system_health`.
+        if (parsedResponse.id && this.#currentHealthCheckId === parsedResponse.id) {
+            this.#currentHealthCheckId = null;
+            // Check whether query was successful. It is possible for queries to fail for
+            // various reasons, such as the client being overloaded.
+            if (!parsedResponse.result) {
+                this.update(false);
+                return null;
+            }
+            this.#healthCallback(parsedResponse.result);
+            this.#isSyncing = parsedResponse.result.isSyncing;
+            this.update(false);
+            return null;
+        }
+        // Check whether response is a response to the subscription or unsubscription.
+        if (parsedResponse.id &&
+            this.#currentSubunsubRequestId === parsedResponse.id) {
+            this.#currentSubunsubRequestId = null;
+            // Check whether query was successful. It is possible for queries to fail for
+            // various reasons, such as the client being overloaded.
+            if (!parsedResponse.result) {
+                this.update(false);
+                return null;
+            }
+            if (this.#currentSubscriptionId) {
+                this.#currentSubscriptionId = null;
+            }
+            else {
+                this.#currentSubscriptionId = parsedResponse.result;
+            }
+            this.update(false);
+            return null;
+        }
+        // Check whether response is a notification to a subscription.
+        if (parsedResponse.params &&
+            this.#currentSubscriptionId &&
+            parsedResponse.params.subscription === this.#currentSubscriptionId) {
+            // Note that after a successful subscription, a notification containing
+            // the current best block is always returned. Considering that a
+            // subscription is performed in response to a health check, calling
+            // `startHealthCheck()` here will lead to a second health check.
+            // It might seem redundant to perform two health checks in a quick
+            // succession, but doing so doesn't lead to any problem, and it is
+            // actually possible for the health to have changed in between as the
+            // current best block might have been updated during the subscription
+            // request.
+            this.update(true);
+            return null;
+        }
+        // Response doesn't concern us.
+        if (parsedResponse.id) {
+            const id = parsedResponse.id;
+            // Need to remove the `extern:` prefix.
+            if (!id.startsWith('extern:')) {
+                throw new Error('State inconsistency in health checker');
+            }
+            const newId = JSON.parse(id.slice('extern:'.length));
+            parsedResponse.id = newId;
+        }
+        return (0, util_1.stringify)(parsedResponse);
+    };
+    update = (startNow) => {
+        // If `startNow`, clear `#currentHealthTimeout` so that it is set below.
+        if (startNow && this.#currentHealthTimeout) {
+            clearTimeout(this.#currentHealthTimeout);
+            this.#currentHealthTimeout = null;
+        }
+        if (!this.#currentHealthTimeout) {
+            const startHealthRequest = () => {
+                this.#currentHealthTimeout = null;
+                // No matter what, don't start a health request if there is already one in progress.
+                // This is sane to do because receiving a response to a health request calls `update()`.
+                if (this.#currentHealthCheckId) {
+                    return;
+                }
+                // Actual request starting.
+                this.#currentHealthCheckId = `health-checker:${this.#nextRequestId}`;
+                this.#nextRequestId += 1;
+                this.#requestToSmoldot({
+                    id: this.#currentHealthCheckId,
+                    jsonrpc: '2.0',
+                    method: 'system_health',
+                    params: []
+                });
+            };
+            if (startNow) {
+                startHealthRequest();
+            }
+            else {
+                this.#currentHealthTimeout = setTimeout(startHealthRequest, 1000);
+            }
+        }
+        if (this.#isSyncing &&
+            !this.#currentSubscriptionId &&
+            !this.#currentSubunsubRequestId) {
+            this.startSubscription();
+        }
+        if (!this.#isSyncing &&
+            this.#currentSubscriptionId &&
+            !this.#currentSubunsubRequestId) {
+            this.endSubscription();
+        }
+    };
+    startSubscription = () => {
+        if (this.#currentSubunsubRequestId || this.#currentSubscriptionId) {
+            throw new Error('Internal error in health checker');
+        }
+        this.#currentSubunsubRequestId = `health-checker:${this.#nextRequestId}`;
+        this.#nextRequestId += 1;
+        this.#requestToSmoldot({
+            id: this.#currentSubunsubRequestId,
+            jsonrpc: '2.0',
+            method: 'chain_subscribeNewHeads',
+            params: []
+        });
+    };
+    endSubscription = () => {
+        if (this.#currentSubunsubRequestId || !this.#currentSubscriptionId) {
+            throw new Error('Internal error in health checker');
+        }
+        this.#currentSubunsubRequestId = `health-checker:${this.#nextRequestId}`;
+        this.#nextRequestId += 1;
+        this.#requestToSmoldot({
+            id: this.#currentSubunsubRequestId,
+            jsonrpc: '2.0',
+            method: 'chain_unsubscribeNewHeads',
+            params: [this.#currentSubscriptionId]
+        });
+    };
+    destroy = () => {
+        if (this.#currentHealthTimeout) {
+            clearTimeout(this.#currentHealthTimeout);
+            this.#currentHealthTimeout = null;
+        }
+    };
+}
+class HealthCheckError extends Error {
+    #cause;
+    getCause() {
+        return this.#cause;
+    }
+    constructor(response, message = 'Got error response asking for system health') {
+        super(message);
+        this.#cause = response;
+    }
+}
+exports.HealthCheckError = HealthCheckError;

package/cjs/bizinikiwi-connect/index.d.ts

@@ -0,0 +1,22 @@
+import type * as ScType from '@bizinikiwi/connect';
+import type { ProviderInterface, ProviderInterfaceCallback, ProviderInterfaceEmitCb, ProviderInterfaceEmitted } from '../types.js';
+import { healthChecker } from './Health.js';
+interface BizinikiwiConnect {
+    WellKnownChain: typeof ScType['WellKnownChain'];
+    createScClient: typeof ScType['createScClient'];
+}
+export declare class ScProvider implements ProviderInterface {
+    #private;
+    constructor(Sc: BizinikiwiConnect, spec: string | ScType.WellKnownChain, sharedSandbox?: ScProvider);
+    get hasSubscriptions(): boolean;
+    get isClonable(): boolean;
+    get isConnected(): boolean;
+    clone(): ProviderInterface;
+    connect(config?: ScType.Config, checkerFactory?: typeof healthChecker): Promise<void>;
+    disconnect(): Promise<void>;
+    on(type: ProviderInterfaceEmitted, sub: ProviderInterfaceEmitCb): () => void;
+    send<T = any>(method: string, params: unknown[]): Promise<T>;
+    subscribe(type: string, method: string, params: any[], callback: ProviderInterfaceCallback): Promise<number | string>;
+    unsubscribe(type: string, method: string, id: number | string): Promise<boolean>;
+}
+export {};