@dedot/api 0.18.8 → 1.0.0

package/cjs/json-rpc/group/ChainHead/ChainHead.js

@@ -2,11 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChainHead = void 0;
 const codecs_1 = require("@dedot/codecs");
+const providers_1 = require("@dedot/providers");
 const utils_1 = require("@dedot/utils");
+const utils_js_1 = require("../../../client/utils.js");
 const JsonRpcGroup_js_1 = require("../JsonRpcGroup.js");
 const BlockUsage_js_1 = require("./BlockUsage.js");
 const error_js_1 = require("./error.js");
-const MIN_FINALIZED_QUEUE_SIZE = 16; // finalized queue size
+const MIN_FINALIZED_QUEUE_SIZE = 10; // finalized queue size
 const CHAINHEAD_CACHE_CAPACITY = 256;
 const CHAINHEAD_CACHE_TTL = 30_000; // 30 seconds
 class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
@@ -14,11 +16,15 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
     #subscriptionId;
     #handlers;
     #pendingOperations;
+    #pendingRequests = new Map();
+    #requestIdCounter = 0;
     #finalizedQueue;
     #pinnedBlocks;
     #bestHash;
+    #lastBestBlockNumber; // Track last emitted best block number for gap detection
     #finalizedHash; // best finalized hash
     #finalizedRuntime;
+    #hasher; // detected hasher from block header
     #followResponseQueue;
     #retryQueue;
     #recovering;
@@ -63,6 +69,34 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
         this.#archive = archive;
         return this;
     }
+    /**
+     * Override send() to track pending requests for retry on network disconnection
+     */
+    async send(method, ...params) {
+        const requestId = `req_${++this.#requestIdCounter}`;
+        const defer = (0, utils_1.deferred)();
+        this.#pendingRequests.set(requestId, {
+            method,
+            params,
+            defer,
+        });
+        try {
+            const result = await super.send(method, ...params);
+            this.#pendingRequests.delete(requestId);
+            defer.resolve(result);
+            return result;
+        }
+        catch (error) {
+            if (error instanceof providers_1.NetworkDisconnectedError) {
+                // Keep in pending for retry on re-follow - don't delete
+                // Return the deferred promise that will be resolved on retry
+                return defer.promise;
+            }
+            // Other errors: clean up and throw
+            this.#pendingRequests.delete(requestId);
+            throw error;
+        }
+    }
     async runtimeVersion() {
         await this.#ensureFollowed();
         return this.#finalizedRuntime;
@@ -85,9 +119,20 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
     async finalizedBlock() {
         return this.findBlock(await this.finalizedHash());
     }
+    /**
+     * Returns the detected hasher for the chain
+     * Returns undefined if detection failed (client should use default)
+     */
+    async hasher() {
+        await this.#ensureFollowed();
+        return this.#hasher;
+    }
     findBlock(hash) {
         return this.#pinnedBlocks[hash];
     }
+    #findBlocksByNumber(blockNumber) {
+        return Object.values(this.#pinnedBlocks).filter((block) => block.number === blockNumber);
+    }
     isPinned(hash) {
         return !!this.findBlock(hash);
     }
@@ -102,8 +147,10 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
     /**
      * chainHead_follow
      */
-    async follow() {
-        (0, utils_1.assert)(!this.#subscriptionId, 'Already followed chain head. Please unfollow first.');
+    async follow(force) {
+        if (!force) {
+            (0, utils_1.assert)(!this.#subscriptionId, 'Already followed chain head. Please unfollow first.');
+        }
         return this.#doFollow();
     }
     async #doFollow() {
@@ -132,7 +179,41 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
         catch (e) {
             defer.reject(e);
         }
-        return defer.promise;
+        // Wait for follow to complete, then retry pending requests
+        await defer.promise;
+        // Retry pending requests if any (from previous disconnection)
+        if (this.#pendingRequests.size > 0) {
+            this.#retryPendingRequests();
+        }
+    }
+    /**
+     * Retry pending requests that were queued during network disconnection
+     */
+    #retryPendingRequests() {
+        const pending = Array.from(this.#pendingRequests.entries());
+        for (const [requestId, request] of pending) {
+            const { method, params, defer } = request;
+            // Update subscription ID with the new one (first param for all ChainHead RPC methods)
+            const updatedParams = [...params];
+            if (updatedParams.length > 0) {
+                updatedParams[0] = this.#subscriptionId;
+            }
+            // Retry the request with new subscriptionId
+            super
+                .send(method, ...updatedParams)
+                .then((result) => {
+                defer.resolve(result);
+                this.#pendingRequests.delete(requestId);
+            })
+                .catch((error) => {
+                if (!(error instanceof providers_1.NetworkDisconnectedError)) {
+                    // Real error, reject and clean up
+                    defer.reject(error);
+                    this.#pendingRequests.delete(requestId);
+                }
+                // If NetworkDisconnectedError again, keep in pending for next retry
+            });
+        }
     }
     #onFollowEvent = async (result, subscription) => {
         switch (result.event) {
@@ -140,6 +221,9 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
                 const { finalizedBlockHashes = [], finalizedBlockHash, finalizedBlockRuntime } = result;
                 if (finalizedBlockHash)
                     finalizedBlockHashes.push(finalizedBlockHash);
+                const lastFinalizedHash = this.#finalizedHash;
+                const prevPinnedBlocks = this.#pinnedBlocks;
+                // Initialize subscription state
                 this.#subscriptionId = subscription.subscriptionId;
                 this.#finalizedQueue = finalizedBlockHashes;
                 if (finalizedBlockHashes.length > MIN_FINALIZED_QUEUE_SIZE) {
@@ -147,35 +231,37 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
                 }
                 this.#finalizedRuntime = this.#extractRuntime(finalizedBlockRuntime);
                 (0, utils_1.assert)(this.#finalizedRuntime, 'Invalid finalized runtime');
-                this.#bestHash = this.#finalizedHash = finalizedBlockHashes.at(-1);
-                this.#pinnedBlocks = finalizedBlockHashes.reduce((o, hash, idx, arr) => {
-                    o[hash] = { hash, parent: arr[idx - 1], number: idx };
-                    // assign finalized runtime to the current finalized block
-                    if (idx === finalizedBlockHashes.length - 1) {
-                        o[hash]['runtime'] = this.#finalizedRuntime;
-                    }
-                    return o;
-                }, {});
-                const header = codecs_1.$Header.tryDecode(await this.#getHeader(finalizedBlockHashes[0]));
-                Object.values(this.#pinnedBlocks).forEach((b, idx) => {
-                    b.number += header.number;
-                    if (idx === 0) {
-                        b.parent = header.parentHash;
-                    }
-                });
+                // Build initial pinned blocks
+                this.#finalizedHash = finalizedBlockHashes.at(-1);
+                if (!this.#bestHash) {
+                    this.#bestHash = this.#finalizedHash;
+                }
+                this.#pinnedBlocks = this.#buildInitialPinnedBlocks(finalizedBlockHashes, this.#finalizedRuntime);
+                await this.#updateBlockNumbersAndParents(finalizedBlockHashes, prevPinnedBlocks);
+                // Handle first initialization or reconnection
+                if (!lastFinalizedHash) {
+                    this.emit('finalizedBlock', await this.finalizedBlock());
+                }
+                else {
+                    await this.#handleMissingBlocks(finalizedBlockHashes, lastFinalizedHash, prevPinnedBlocks);
+                }
                 break;
             }
             case 'newBlock': {
                 const { blockHash: hash, parentBlockHash: parent, newRuntime } = result;
                 const runtime = this.#extractRuntime(newRuntime);
                 const parentBlock = this.findBlock(parent);
-                (0, utils_1.assert)(parentBlock, `Parent block not found for new block ${hash}`);
+                if (!parentBlock) {
+                    console.warn(`Parent block not found for new block ${hash}`);
+                    return;
+                }
                 this.#pinnedBlocks[hash] = {
                     hash,
                     parent,
                     // if the runtime is not provided, we'll find it from the parent block
                     runtime: runtime || this.#findRuntimeAt(parent),
                     number: parentBlock.number + 1,
+                    runtimeUpgraded: !!runtime,
                 };
                 this.emit('newBlock', this.#pinnedBlocks[hash]);
                 break;
@@ -188,8 +274,13 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
                     return;
                 if (currentBestBlock.hash === newBestBlock.hash)
                     return;
+                // Detect and fill gaps before updating best hash
+                if (this.#lastBestBlockNumber !== undefined) {
+                    this.#fillBestBlockGaps(this.#lastBestBlockNumber, newBestBlock.number);
+                }
                 const bestChainChanged = !this.#onTheSameChain(currentBestBlock, newBestBlock);
                 this.#bestHash = bestBlockHash;
+                this.#lastBestBlockNumber = newBestBlock.number; // Update tracking
                 this.emit('bestBlock', newBestBlock, bestChainChanged);
                 if (bestChainChanged)
                     this.emit('bestChainChanged', newBestBlock);
@@ -365,6 +456,100 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
             return;
         return this.#findRuntimeAt(block.parent);
     }
+    #hasRuntimeUpgrade(header) {
+        return header.digest.logs.some((log) => log.type === 'RuntimeEnvironmentUpdated');
+    }
+    #buildInitialPinnedBlocks(finalizedBlockHashes, runtime) {
+        return finalizedBlockHashes.reduce((o, hash, idx, arr) => {
+            o[hash] = { hash, parent: arr[idx - 1], number: idx };
+            // assign finalized runtime to the current finalized block
+            if (idx === finalizedBlockHashes.length - 1) {
+                o[hash]['runtime'] = runtime;
+            }
+            return o;
+        }, {});
+    }
+    async #fetchInitializationHeaders(finalizedBlockHashes, prevPinnedBlocks) {
+        const fetchStartingHeader = async () => {
+            const startingBlockHash = finalizedBlockHashes[0];
+            const existing = prevPinnedBlocks[startingBlockHash];
+            if (existing) {
+                return {
+                    number: existing.number,
+                    parent: existing.parent,
+                };
+            }
+            else {
+                const header = codecs_1.$Header.tryDecode(await this.#getHeader(startingBlockHash));
+                return {
+                    number: header.number,
+                    parent: header.parentHash,
+                };
+            }
+        };
+        const [startingBlock, finalizedHeader] = await Promise.all([
+            fetchStartingHeader(),
+            codecs_1.$Header.tryDecode(await this.#getHeader(this.#finalizedHash)),
+        ]);
+        return { startingHeader: startingBlock, finalizedHeader };
+    }
+    async #updateBlockNumbersAndParents(finalizedBlockHashes, prevPinnedBlocks) {
+        // Fetch headers and update block metadata
+        const { startingHeader, finalizedHeader } = await this.#fetchInitializationHeaders(finalizedBlockHashes, prevPinnedBlocks);
+        // Detect hasher using the finalized header we just fetched
+        this.#hasher = (0, utils_js_1.detectHasherFromHeader)(finalizedHeader, this.#finalizedHash);
+        Object.values(this.#pinnedBlocks).forEach((b, idx) => {
+            b.number += startingHeader.number;
+            if (idx === 0) {
+                b.parent = startingHeader.parent;
+            }
+        });
+        this.#pinnedBlocks[this.#finalizedHash].runtimeUpgraded = this.#hasRuntimeUpgrade(finalizedHeader);
+    }
+    async #fetchAndApplyRuntimeUpgrades(missingHashes, prevPinnedBlocks) {
+        const blocksNeedingHeaders = [];
+        for (const hash of missingHashes) {
+            const prevBlock = prevPinnedBlocks[hash];
+            const currentBlock = this.#pinnedBlocks[hash];
+            if (prevBlock?.runtimeUpgraded !== undefined) {
+                // Reuse existing runtime info from prevPinnedBlocks
+                currentBlock.runtimeUpgraded = prevBlock.runtimeUpgraded;
+            }
+            else {
+                // Need to fetch header for this block
+                blocksNeedingHeaders.push(hash);
+            }
+        }
+        if (blocksNeedingHeaders.length === 0)
+            return;
+        const headers = await Promise.all(blocksNeedingHeaders.map(async (hash) => ({
+            hash,
+            header: codecs_1.$Header.tryDecode(await this.#getHeader(hash)),
+        })));
+        // Set runtimeUpgraded flag based on digest check
+        for (const { hash, header } of headers) {
+            const block = this.#pinnedBlocks[hash];
+            if (block) {
+                block.runtimeUpgraded = this.#hasRuntimeUpgrade(header);
+            }
+        }
+    }
+    async #handleMissingBlocks(finalizedBlockHashes, lastFinalizedHash, prevPinnedBlocks) {
+        const lastFinalizedIndex = finalizedBlockHashes.indexOf(lastFinalizedHash);
+        if (lastFinalizedIndex !== -1 && lastFinalizedIndex < finalizedBlockHashes.length - 1) {
+            // Get missing block hashes that occurred during disconnection
+            const missingHashes = finalizedBlockHashes.slice(lastFinalizedIndex + 1);
+            // Identify blocks needing header fetch vs those with cached runtime info
+            await this.#fetchAndApplyRuntimeUpgrades(missingHashes, prevPinnedBlocks);
+            // Emit all missing finalized blocks with proper runtime info
+            for (const hash of missingHashes) {
+                const block = this.#pinnedBlocks[hash];
+                if (block) {
+                    this.emit('finalizedBlock', block);
+                }
+            }
+        }
+    }
     #onTheSameChain(b1, b2) {
         if (!b1 || !b2)
             return false;
@@ -378,6 +563,23 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
             return this.#onTheSameChain(this.findBlock(b1.parent), b2);
         }
     }
+    /**
+     * Detect and emit missing best blocks from pinned blocks
+     * Called when bestBlockChanged event detects a gap
+     */
+    #fillBestBlockGaps(lastNumber, currentNumber) {
+        // No gap if current is next sequential block
+        if (currentNumber <= lastNumber + 1) {
+            return;
+        }
+        // Emit missing blocks from pinned blocks
+        for (let num = lastNumber + 1; num < currentNumber; num++) {
+            const blocks = this.#findBlocksByNumber(num);
+            for (let idx = 0; idx < blocks.length; idx++) {
+                this.emit('bestBlock', blocks[idx], idx >= 1);
+            }
+        }
+    }
     #ensurePinnedHash(hash) {
         if (hash) {
             if (this.isPinned(hash)) {
@@ -463,8 +665,10 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
         this.#unsub = undefined;
         this.#handlers = {};
         this.#pendingOperations = {};
+        this.#pendingRequests.clear();
         this.#pinnedBlocks = {};
         this.#bestHash = undefined;
+        this.#lastBestBlockNumber = undefined;
         this.#finalizedHash = undefined;
         this.#finalizedRuntime = undefined;
         this.#followResponseQueue.clear();
@@ -472,6 +676,7 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
         this.#blockUsage.clear();
         this.clearCache();
         this.#operationQueue.cancel();
+        this.#hasher = undefined;
     }
     async #ensureFollowed() {
         if (this.#recovering) {

package/cjs/storage/QueryableStorage.js

@@ -68,6 +68,7 @@ class QueryableStorage {
                 const keyId = keyTypeIds[index];
                 const hasher = utils_1.HASHERS[hashers[index]];
                 const $keyCodec = this.registry.findCodec(keyId);
+                $keyCodec.assert?.(input);
                 return hasher($keyCodec.tryEncode(input));
             });
             return (0, utils_2.u8aToHex)((0, utils_2.concatU8a)(this.prefixKeyAsU8a, ...keyParts));

package/client/BaseSubstrateClient.d.ts

@@ -1,21 +1,22 @@
-import { BlockHash, Hash, Metadata, PortableRegistry, RuntimeVersion } from '@dedot/codecs';
-import type { JsonRpcProvider } from '@dedot/providers';
+import { BlockHash, Extrinsic, Hash, Metadata, PortableRegistry, RuntimeVersion } from '@dedot/codecs';
+import { type JsonRpcProvider } from '@dedot/providers';
 import { type IStorage } from '@dedot/storage';
-import { Callback, GenericStorageQuery, GenericSubstrateApi, InjectedSigner, Query, QueryFnResult, RpcVersion, Unsub, VersionedGenericSubstrateApi } from '@dedot/types';
-import { Deferred, LRUCache } from '@dedot/utils';
+import { Callback, GenericStorageQuery, GenericSubstrateApi, InjectedSigner, Query, QueryFnResult, RpcVersion, TxUnsub, Unsub } from '@dedot/types';
+import { Deferred, HexString, LRUCache } from '@dedot/utils';
 import type { SubstrateApi } from '../chaintypes/index.js';
 import { JsonRpcClient } from '../json-rpc/index.js';
 import { BaseStorageQuery } from '../storage/index.js';
-import type { ApiEvent, ApiOptions, ISubstrateClient, ISubstrateClientAt, JsonRpcClientOptions, MetadataKey, SubstrateRuntimeVersion } from '../types.js';
+import type { ApiEvent, ApiOptions, BlockExplorer, EventHandlerFn, IChainSpec, ISubstrateClient, ISubstrateClientAt, JsonRpcClientOptions, MetadataKey, SubstrateRuntimeVersion } from '../types.js';
 export declare function ensurePresence<T>(value: T): NonNullable<T>;
 /**
  * @name BaseSubstrateClient
  * @description Base & shared abstraction for Substrate API Clients
  */
-export declare abstract class BaseSubstrateClient<Rv extends RpcVersion, ChainApi extends VersionedGenericSubstrateApi = SubstrateApi, Events extends string = ApiEvent> extends JsonRpcClient<ChainApi, Events> implements ISubstrateClient<ChainApi[Rv], Events> {
+export declare abstract class BaseSubstrateClient<ChainApi extends GenericSubstrateApi = SubstrateApi, Events extends string = ApiEvent> extends JsonRpcClient<ChainApi, Events> implements ISubstrateClient<ChainApi, Events> {
+    #private;
     rpcVersion: RpcVersion;
     protected _options: ApiOptions;
-    protected _registry?: PortableRegistry<ChainApi[Rv]['types']>;
+    protected _registry?: PortableRegistry<ChainApi['types']>;
     protected _metadata?: Metadata;
     protected _genesisHash?: Hash;
     protected _runtimeVersion?: SubstrateRuntimeVersion;
@@ -30,7 +31,7 @@ export declare abstract class BaseSubstrateClient<Rv extends RpcVersion, ChainAp
      * Safely set metadata to cache with fallback cleanup if storage limit is exceeded
      */
     protected safeSetMetadataToCache(key: string, value: string): Promise<void>;
-    protected setMetadata(metadata: Metadata): void;
+    protected setMetadata(metadata: Metadata): Promise<void>;
     protected getMetadataKey(runtime?: SubstrateRuntimeVersion): MetadataKey;
     get currentMetadataKey(): string;
     protected shouldPreloadMetadata(): Promise<boolean>;
@@ -42,6 +43,17 @@ export declare abstract class BaseSubstrateClient<Rv extends RpcVersion, ChainAp
      */
     protected findMetadataInCache(specVersion: number): [Metadata, PortableRegistry] | undefined;
     protected fetchMetadata(hash?: BlockHash, runtime?: SubstrateRuntimeVersion): Promise<Metadata>;
+    /**
+     * Set up staling detection with timeout reset logic.
+     * Returns a callback function that should be called on each activity (block/event).
+     *
+     * @returns A function to call on each activity to reset the timeout
+     */
+    protected getStalingDetectionFn(): (() => void) | undefined;
+    /**
+     * Clean up staling detection timer
+     */
+    protected cleanupStalingDetection(): void;
     protected cleanUp(): void;
     /**
      * @description Clear local cache and API at-block cache
@@ -69,19 +81,20 @@ export declare abstract class BaseSubstrateClient<Rv extends RpcVersion, ChainAp
     disconnect(): Promise<void>;
     get options(): ApiOptions;
     get metadata(): Metadata;
-    get registry(): PortableRegistry<ChainApi[Rv]['types']>;
+    get registry(): PortableRegistry<ChainApi['types']>;
     get genesisHash(): Hash;
     get runtimeVersion(): SubstrateRuntimeVersion;
     getRuntimeVersion(): Promise<SubstrateRuntimeVersion>;
-    get consts(): ChainApi[Rv]['consts'];
-    get errors(): ChainApi[Rv]['errors'];
-    get events(): ChainApi[Rv]['events'];
-    get query(): ChainApi[Rv]['query'];
-    get view(): ChainApi[Rv]['view'];
-    get call(): ChainApi[Rv]['call'];
-    protected callAt(hash?: BlockHash): ChainApi[Rv]['call'];
-    get tx(): ChainApi[Rv]['tx'];
-    at<ChainApiAt extends GenericSubstrateApi = ChainApi[Rv]>(hash: BlockHash): Promise<ISubstrateClientAt<ChainApiAt>>;
+    get block(): BlockExplorer;
+    get consts(): ChainApi['consts'];
+    get errors(): ChainApi['errors'];
+    get events(): ChainApi['events'];
+    get query(): ChainApi['query'];
+    get view(): ChainApi['view'];
+    get call(): ChainApi['call'];
+    protected callAt(hash?: BlockHash): ChainApi['call'];
+    get tx(): ChainApi['tx'];
+    at<ChainApiAt extends GenericSubstrateApi = ChainApi>(hash: BlockHash): Promise<ISubstrateClientAt<ChainApiAt>>;
     setSigner(signer?: InjectedSigner): void;
     protected internalQueryMulti(queries: {
         fn: GenericStorageQuery;
@@ -119,4 +132,7 @@ export declare abstract class BaseSubstrateClient<Rv extends RpcVersion, ChainAp
         [K in keyof Fns]: QueryFnResult<Fns[K]>;
     }>): Promise<Unsub>;
     protected getStorageQuery(): BaseStorageQuery;
+    sendTx(tx: HexString | Extrinsic, callback?: Callback): TxUnsub;
+    get chainSpec(): IChainSpec;
+    on<Event extends Events = Events>(event: Event, handler: EventHandlerFn<Event>): () => void;
 }

package/client/BaseSubstrateClient.js

@@ -1,6 +1,7 @@
-import { $Metadata, PortableRegistry } from '@dedot/codecs';
+import { $Metadata, PortableRegistry, } from '@dedot/codecs';
+import { WsProvider } from '@dedot/providers';
 import { LocalStorage } from '@dedot/storage';
-import { calcRuntimeApiHash, deferred, ensurePresence as _ensurePresence, u8aToHex, LRUCache, } from '@dedot/utils';
+import { calcRuntimeApiHash, deferred, ensurePresence as _ensurePresence, LRUCache, noop, u8aToHex, } from '@dedot/utils';
 import { ConstantExecutor, ErrorExecutor, EventExecutor } from '../executor/index.js';
 import { isJsonRpcProvider, JsonRpcClient } from '../json-rpc/index.js';
 import { newProxyChain } from '../proxychain.js';
@@ -27,6 +28,7 @@ export class BaseSubstrateClient extends JsonRpcClient {
     _localCache;
     _runtimeUpgrading;
     _apiAtCache;
+    #stalingWatchdogTimer;
     constructor(rpcVersion, options) {
         super(options);
         this.rpcVersion = rpcVersion;
@@ -94,7 +96,7 @@ export class BaseSubstrateClient extends JsonRpcClient {
         if (!metadata) {
             throw new Error('Cannot load metadata');
         }
-        this.setMetadata(metadata);
+        await this.setMetadata(metadata);
     }
     /**
      * Safely set metadata to cache with fallback cleanup if storage limit is exceeded
@@ -126,7 +128,7 @@ export class BaseSubstrateClient extends JsonRpcClient {
             }
         }
     }
-    setMetadata(metadata) {
+    async setMetadata(metadata) {
         this._metadata = metadata;
         this._registry = new PortableRegistry(metadata.latest, this.options.hasher);
     }
@@ -199,6 +201,34 @@ export class BaseSubstrateClient extends JsonRpcClient {
             return await this.rpc.state_getMetadata();
         }
     }
+    /**
+     * Set up staling detection with timeout reset logic.
+     * Returns a callback function that should be called on each activity (block/event).
+     *
+     * @returns A function to call on each activity to reset the timeout
+     */
+    getStalingDetectionFn() {
+        const timeout = this._options.stalingDetectionTimeout ?? 30_000; // default to 30 seconds
+        if (timeout === 0 || !(this.provider instanceof WsProvider)) {
+            return;
+        }
+        return () => {
+            this.cleanupStalingDetection();
+            this.#stalingWatchdogTimer = setTimeout(() => {
+                console.warn(`No new blocks received for over ${timeout}ms, triggering reconnection with endpoint switch...`);
+                this.provider.disconnect(true).catch(noop);
+            }, timeout);
+        };
+    }
+    /**
+     * Clean up staling detection timer
+     */
+    cleanupStalingDetection() {
+        if (this.#stalingWatchdogTimer) {
+            clearTimeout(this.#stalingWatchdogTimer);
+            this.#stalingWatchdogTimer = undefined;
+        }
+    }
     cleanUp() {
         this._registry = undefined;
         this._metadata = undefined;
@@ -206,6 +236,7 @@ export class BaseSubstrateClient extends JsonRpcClient {
         this._runtimeVersion = undefined;
         this._localCache = undefined;
         this._apiAtCache.clear();
+        this.cleanupStalingDetection();
     }
     /**
      * @description Clear local cache and API at-block cache
@@ -306,6 +337,9 @@ export class BaseSubstrateClient extends JsonRpcClient {
         await this.ensureRuntimeUpgraded();
         return this.runtimeVersion;
     }
+    get block() {
+        throw new Error('Unimplemented!');
+    }
     get consts() {
         return newProxyChain({ executor: new ConstantExecutor(this) });
     }
@@ -369,4 +403,13 @@ export class BaseSubstrateClient extends JsonRpcClient {
     getStorageQuery() {
         throw new Error('Unimplemented!');
     }
+    sendTx(tx, callback) {
+        throw new Error('Unimplemented!');
+    }
+    get chainSpec() {
+        throw new Error('Unimplemented!');
+    }
+    on(event, handler) {
+        return super.on(event, handler);
+    }
 }