@dedot/api 0.18.8 → 1.0.0

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

@@ -1,9 +1,11 @@
 import { $Header } from '@dedot/codecs';
+import { NetworkDisconnectedError } from '@dedot/providers';
 import { assert, AsyncQueue, deferred, ensurePresence, noop, ThrottleQueue, waitFor, LRUCache, } from '@dedot/utils';
+import { detectHasherFromHeader } from '../../../client/utils.js';
 import { JsonRpcGroup } from '../JsonRpcGroup.js';
 import { BlockUsage } from './BlockUsage.js';
 import { ChainHeadBlockNotPinnedError, ChainHeadBlockPrunedError, ChainHeadError, ChainHeadLimitReachedError, ChainHeadOperationError, ChainHeadOperationInaccessibleError, ChainHeadStopError, RetryStrategy, } from './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
 export class ChainHead extends JsonRpcGroup {
@@ -11,11 +13,15 @@ export class ChainHead extends 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;
@@ -60,6 +66,34 @@ export class ChainHead extends 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 = 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 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;
@@ -82,9 +116,20 @@ export class ChainHead extends 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);
     }
@@ -99,8 +144,10 @@ export class ChainHead extends JsonRpcGroup {
     /**
      * chainHead_follow
      */
-    async follow() {
-        assert(!this.#subscriptionId, 'Already followed chain head. Please unfollow first.');
+    async follow(force) {
+        if (!force) {
+            assert(!this.#subscriptionId, 'Already followed chain head. Please unfollow first.');
+        }
         return this.#doFollow();
     }
     async #doFollow() {
@@ -129,7 +176,41 @@ export class ChainHead extends 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 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) {
@@ -137,6 +218,9 @@ export class ChainHead extends 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) {
@@ -144,35 +228,37 @@ export class ChainHead extends JsonRpcGroup {
                 }
                 this.#finalizedRuntime = this.#extractRuntime(finalizedBlockRuntime);
                 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 = $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);
-                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;
@@ -185,8 +271,13 @@ export class ChainHead extends 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);
@@ -362,6 +453,100 @@ export class ChainHead extends 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 = $Header.tryDecode(await this.#getHeader(startingBlockHash));
+                return {
+                    number: header.number,
+                    parent: header.parentHash,
+                };
+            }
+        };
+        const [startingBlock, finalizedHeader] = await Promise.all([
+            fetchStartingHeader(),
+            $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 = 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: $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;
@@ -375,6 +560,23 @@ export class ChainHead extends 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)) {
@@ -460,8 +662,10 @@ export class ChainHead extends 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();
@@ -469,6 +673,7 @@ export class ChainHead extends JsonRpcGroup {
         this.#blockUsage.clear();
         this.clearCache();
         this.#operationQueue.cancel();
+        this.#hasher = undefined;
     }
     async #ensureFollowed() {
         if (this.#recovering) {

package/json-rpc/group/ChainSpec.d.ts

@@ -1,9 +1,9 @@
 import { Properties } from '@dedot/types/json-rpc';
 import { HexString } from '@dedot/utils';
-import { IJsonRpcClient } from '../../types.js';
+import { IJsonRpcClient, IChainSpec } from '../../types.js';
 import { JsonRpcGroup, JsonRpcGroupOptions } from './JsonRpcGroup.js';
-export declare class ChainSpec extends JsonRpcGroup {
-    constructor(client: IJsonRpcClient, options?: Partial<JsonRpcGroupOptions>);
+export declare class ChainSpec extends JsonRpcGroup implements IChainSpec {
+    constructor(client: IJsonRpcClient<any>, options?: Partial<JsonRpcGroupOptions>);
     chainName(): Promise<string>;
     genesisHash(): Promise<HexString>;
     properties(): Promise<Properties>;

package/json-rpc/group/Transaction.d.ts

@@ -4,7 +4,7 @@ import { HexString } from '@dedot/utils';
 import { IJsonRpcClient, TxBroadcaster } from '../../types.js';
 import { JsonRpcGroup, JsonRpcGroupOptions } from './JsonRpcGroup.js';
 export declare class Transaction extends JsonRpcGroup implements TxBroadcaster {
-    constructor(client: IJsonRpcClient, options?: Partial<JsonRpcGroupOptions>);
+    constructor(client: IJsonRpcClient<any>, options?: Partial<JsonRpcGroupOptions>);
     broadcastTx(tx: HexString): Promise<Unsub>;
     broadcast(tx: string): Promise<OperationId>;
     stop(operationId: OperationId): Promise<void>;

package/json-rpc/group/TransactionWatch.d.ts

@@ -4,7 +4,7 @@ import { HexString } from '@dedot/utils';
 import { IJsonRpcClient, TxBroadcaster } from '../../types.js';
 import { JsonRpcGroup, JsonRpcGroupOptions } from './JsonRpcGroup.js';
 export declare class TransactionWatch extends JsonRpcGroup implements TxBroadcaster {
-    constructor(client: IJsonRpcClient, options?: Partial<JsonRpcGroupOptions>);
+    constructor(client: IJsonRpcClient<any>, options?: Partial<JsonRpcGroupOptions>);
     broadcastTx(tx: HexString): Promise<Unsub>;
     submitAndWatch(tx: HexString, callback: Callback<TransactionWatchEvent>): Promise<Unsub>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dedot/api",
-  "version": "0.18.8",
+  "version": "1.0.0",
   "description": "A delightful JavaScript/TypeScript client for Polkadot & Substrate",
   "author": "Thang X. Vu <thang@dedot.dev>",
   "homepage": "https://dedot.dev",
@@ -13,13 +13,13 @@
   "type": "module",
   "sideEffects": false,
   "dependencies": {
-    "@dedot/codecs": "0.18.8",
-    "@dedot/providers": "0.18.8",
-    "@dedot/runtime-specs": "0.18.8",
-    "@dedot/shape": "0.18.8",
-    "@dedot/storage": "0.18.8",
-    "@dedot/types": "0.18.8",
-    "@dedot/utils": "0.18.8"
+    "@dedot/codecs": "1.0.0",
+    "@dedot/providers": "1.0.0",
+    "@dedot/runtime-specs": "1.0.0",
+    "@dedot/shape": "1.0.0",
+    "@dedot/storage": "1.0.0",
+    "@dedot/types": "1.0.0",
+    "@dedot/utils": "1.0.0"
   },
   "scripts": {
     "build": "tsc --project tsconfig.build.json && tsc --project tsconfig.build.cjs.json",
@@ -48,7 +48,7 @@
     "node": ">=18"
   },
   "license": "Apache-2.0",
-  "gitHead": "5f87f515d4ce4183038681dd02b20bb682a5fdce",
+  "gitHead": "7767062a2188b4ac90561c5ad3cc3f06ac608a24",
   "module": "./index.js",
   "types": "./index.d.ts"
 }

package/proxychain.d.ts

@@ -1,7 +1,6 @@
-import { GenericSubstrateApi } from '@dedot/types';
 import { Executor } from './executor/index.js';
-export interface Carrier<ChainApi extends GenericSubstrateApi> {
-    executor: Executor<ChainApi>;
+export interface Carrier {
+    executor: Executor;
     chain?: string[];
 }
 /**
@@ -11,4 +10,4 @@ export interface Carrier<ChainApi extends GenericSubstrateApi> {
  * @param currentLevel
  * @param maxLevel
  */
-export declare const newProxyChain: <ChainApi extends GenericSubstrateApi<import("@dedot/types").RpcVersion>>(carrier: Carrier<ChainApi>, currentLevel?: number, maxLevel?: number) => unknown;
+export declare const newProxyChain: (carrier: Carrier, currentLevel?: number, maxLevel?: number) => unknown;

package/storage/NewStorageQuery.d.ts

@@ -1,6 +1,6 @@
 import { BlockHash, StorageData, StorageKey } from '@dedot/codecs';
 import type { Callback, Unsub } from '@dedot/types';
-import { DedotClient } from '../client/DedotClient.js';
+import { V2Client } from '../client/V2Client.js';
 import { BaseStorageQuery } from './BaseStorageQuery.js';
 /**
  * @name NewStorageQuery
@@ -15,8 +15,8 @@ import { BaseStorageQuery } from './BaseStorageQuery.js';
  * - Efficient change detection for subscriptions
  */
 export declare class NewStorageQuery extends BaseStorageQuery {
-    protected client: DedotClient<any>;
-    constructor(client: DedotClient<any>);
+    protected client: V2Client<any>;
+    constructor(client: V2Client<any>);
     /**
      * Query multiple storage items in a single call using chainHead_storage
      *

package/storage/QueryableStorage.js

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

package/types.d.ts

@@ -1,9 +1,11 @@
-import { BlockHash, Hash, Metadata, PortableRegistry } from '@dedot/codecs';
+import { BlockHash, Extrinsic, Hash, Header, Metadata, PortableRegistry } from '@dedot/codecs';
 import type { ConnectionStatus, JsonRpcProvider, ProviderEvent } from '@dedot/providers';
 import type { AnyShape } from '@dedot/shape';
 import type { IStorage } from '@dedot/storage';
-import type { Callback, GenericStorageQuery, GenericSubstrateApi, InjectedSigner, Query, QueryFnResult, RpcVersion, RuntimeApiName, RuntimeApiSpec, Unsub } from '@dedot/types';
+import { Callback, GenericStorageQuery, GenericSubstrateApi, InjectedSigner, Query, QueryFnResult, RpcVersion, RuntimeApiName, RuntimeApiSpec, TxUnsub, Unsub } from '@dedot/types';
+import { Properties } from '@dedot/types/json-rpc';
 import type { HashFn, HexString, IEventEmitter } from '@dedot/utils';
+import type { SubstrateApi } from './chaintypes/index.js';
 import type { AnySignedExtension } from './extrinsic/index.js';
 import type { ChainHeadEvent } from './json-rpc/index.js';
 export type MetadataKey = `RAW_META/${string}`;
@@ -60,6 +62,20 @@ export interface ApiOptions extends JsonRpcClientOptions {
      * A signer instance to use for signing transactions
      */
     signer?: InjectedSigner;
+    /**
+     * Timeout in milliseconds for detecting stale WebSocket connections.
+     * When set, monitors block subscription activity and triggers reconnection
+     * to switch to a different endpoint if no blocks/events received within the timeout period.
+     *
+     * Note: This option is only supported when used with WsProvider.
+     *
+     * - Default: 30000 (30 seconds) - staling detection enabled
+     * - 0: Disabled - no staling detection
+     * - Any positive number: Custom timeout in milliseconds
+     *
+     * @default 30000
+     */
+    stalingDetectionTimeout?: number;
 }
 export type ApiEvent = ProviderEvent | 'ready' | 'runtimeUpgraded';
 export type DedotClientEvent = ApiEvent | ChainHeadEvent;
@@ -74,7 +90,7 @@ export interface SubstrateRuntimeVersion {
 /**
  * A generic interface for JSON-RPC clients
  */
-export interface IJsonRpcClient<ChainApi extends GenericSubstrateApi = GenericSubstrateApi, Events extends string = ProviderEvent> extends IEventEmitter<Events> {
+export interface IJsonRpcClient<ChainApi extends GenericSubstrateApi = SubstrateApi, Events extends string = ProviderEvent> extends IEventEmitter<Events> {
     options: JsonRpcClientOptions;
     status: ConnectionStatus;
     provider: JsonRpcProvider;
@@ -85,7 +101,7 @@ export interface IJsonRpcClient<ChainApi extends GenericSubstrateApi = GenericSu
 /**
  * @internal
  */
-export interface IGenericSubstrateClient<ChainApi extends GenericSubstrateApi = GenericSubstrateApi> {
+export interface IGenericSubstrateClient<ChainApi extends GenericSubstrateApi = SubstrateApi> {
     rpcVersion: RpcVersion;
     options: ApiOptions;
     genesisHash: Hash;
@@ -125,15 +141,37 @@ export interface IGenericSubstrateClient<ChainApi extends GenericSubstrateApi =
 /**
  * A generic interface for Substrate clients at a specific block
  */
-export interface ISubstrateClientAt<ChainApi extends GenericSubstrateApi = GenericSubstrateApi> extends IGenericSubstrateClient<ChainApi> {
+export interface ISubstrateClientAt<ChainApi extends GenericSubstrateApi = SubstrateApi> extends IGenericSubstrateClient<ChainApi> {
     atBlockHash: BlockHash;
 }
+export interface BlockInfo {
+    hash: BlockHash;
+    number: number;
+    parent: BlockHash;
+    runtimeUpgraded: boolean;
+}
+export interface BlockExplorer {
+    best(): Promise<BlockInfo>;
+    best(callback: (block: BlockInfo) => void): () => void;
+    finalized(): Promise<BlockInfo>;
+    finalized(callback: (block: BlockInfo) => void): () => void;
+    header(hash: BlockHash): Promise<Header>;
+    body(hash: BlockHash): Promise<HexString[]>;
+}
+export interface IChainSpec {
+    chainName(): Promise<string>;
+    genesisHash(): Promise<HexString>;
+    properties(): Promise<Properties>;
+}
 /**
  * A generic interface for Substrate clients
  */
-export interface ISubstrateClient<ChainApi extends GenericSubstrateApi = GenericSubstrateApi, Events extends string = ApiEvent> extends IJsonRpcClient<ChainApi, Events>, IGenericSubstrateClient<ChainApi> {
+export interface ISubstrateClient<ChainApi extends GenericSubstrateApi = SubstrateApi, // --
+Events extends string = ApiEvent> extends IJsonRpcClient<ChainApi, Events>, IGenericSubstrateClient<ChainApi> {
     options: ApiOptions;
     tx: ChainApi['tx'];
+    chainSpec: IChainSpec;
+    block: BlockExplorer;
     at<ChainApiAt extends GenericSubstrateApi = ChainApi>(hash: BlockHash): Promise<ISubstrateClientAt<ChainApiAt>>;
     /**
      * Get current version of the runtime
@@ -149,6 +187,44 @@ export interface ISubstrateClient<ChainApi extends GenericSubstrateApi = Generic
      * @param signer
      */
     setSigner(signer?: InjectedSigner): void;
+    /**
+     * Broadcasts a transaction to the network and monitors its status.
+     *
+     * This method accepts a transaction (either as a hex-encoded string or an Extrinsic instance)
+     * and submits it to the network. It returns a TxUnsub object that allows you to:
+     * - Subscribe to transaction status updates via an optional callback
+     * - Wait for specific transaction states (finalized, included in best chain block)
+     *
+     * @param tx - The signed transaction to broadcast, either as a hex-encoded string or Extrinsic instance
+     * @param callback - Optional callback function to receive transaction status updates. The callback
+     *                   receives an ISubmittableResult object containing status, events, errors, tx hash, etc...
+     *
+     * @returns A TxUnsub object that is both a Promise<Unsub> and provides utility methods:
+     *          - `.untilFinalized()` - Resolves when transaction is finalized
+     *          - `.untilBestChainBlockIncluded()` - Resolves when transaction is included in best chain block
+     *          - When awaited directly, resolves to an unsubscribe function
+     *
+     * @example
+     * // Basic usage with callback for status updates
+     * const unsub = await client.sendTx(rawTxHex, (result) => {
+     *   console.log('Transaction status:', result.status);
+     *   console.log('Transaction hash:', result.txHash);
+     *   if (result.dispatchError) {
+     *     console.error('Transaction failed:', result.dispatchError);
+     *   }
+     * });
+     *
+     * @example
+     * // Wait for transaction to be included in best chain block
+     * const result = await client.sendTx(rawTxHex, console.log).untilBestChainBlockIncluded();
+     * console.log('Transaction included in block:', result);
+     *
+     * @example
+     * // Wait for transaction finalization
+     * const result = await client.sendTx(rawTxHex).untilFinalized();
+     * console.log('Transaction finalized:', result);
+     */
+    sendTx(tx: HexString | Extrinsic, callback?: Callback): TxUnsub;
     /**
      * Query multiple storage items in a single call or subscribe to multiple storage items
      *
@@ -185,6 +261,17 @@ export interface ISubstrateClient<ChainApi extends GenericSubstrateApi = Generic
     }, callback: Callback<{
         [K in keyof Fns]: QueryFnResult<Fns[K]>;
     }>): Promise<Unsub>;
+    on<Event extends Events = Events>(event: Event, handler: EventHandlerFn<Event>): () => void;
+}
+export type EventHandlerFn<Event extends string> = EventTypes[Event];
+interface EventTypes {
+    ready: () => void;
+    connected: (connectedEndpoint: string) => void;
+    disconnected: () => void;
+    reconnecting: () => void;
+    runtimeUpgraded: (newRuntimeVersion: SubstrateRuntimeVersion, at: BlockInfo) => void;
+    error: (error?: Error) => void;
+    [event: string]: (...args: any[]) => void;
 }
 /**
  * A generic interface for broadcasting transactions
@@ -202,3 +289,4 @@ export interface TxBroadcaster {
      */
     supported(): Promise<boolean>;
 }
+export {};