@dedot/api 0.17.1-next.db98ff20.1 → 0.18.1

package/cjs/client/BaseSubstrateClient.js

@@ -325,7 +325,7 @@ class BaseSubstrateClient extends index_js_2.JsonRpcClient {
     setSigner(signer) {
         this._options.signer = signer;
     }
-    async queryMulti(queries, callback) {
+    async internalQueryMulti(queries, callback, blockHash) {
         // Extract keys from queries
         const keys = queries.map((q) => q.fn.rawKey(...(q.args || [])));
         const decodeValue = (query, rawValue) => {
@@ -341,10 +341,19 @@ class BaseSubstrateClient extends index_js_2.JsonRpcClient {
             });
         }
         else {
-            const results = await this.getStorageQuery().query(keys);
+            const results = await this.getStorageQuery().query(keys, blockHash);
             return queries.map((q, i) => decodeValue(q.fn, results[keys[i]]));
         }
     }
+    async queryMulti(queries, callback) {
+        // If a callback is provided, set up a subscription
+        if (callback) {
+            return this.internalQueryMulti(queries, callback);
+        }
+        else {
+            return this.internalQueryMulti(queries);
+        }
+    }
     getStorageQuery() {
         throw new Error('Unimplemented!');
     }

package/cjs/client/DedotClient.js

@@ -186,24 +186,42 @@ class DedotClient// prettier-end-here
         const cached = this._apiAtCache.get(hash);
         if (cached)
             return cached;
-        let targetVersion;
+        let parentVersion;
+        let parentHash;
         // Try to get block info from ChainHead first (for pinned blocks)
         const targetBlock = this.chainHead.findBlock(hash);
         if (targetBlock) {
-            targetVersion = targetBlock.runtime;
-            if (!targetVersion) {
-                // fallback to fetching on-chain runtime if we can't find it in the block
-                targetVersion = this.toSubstrateRuntimeVersion(await this.callAt(hash).core.version());
+            if (hash === this.genesisHash) {
+                parentHash = hash;
+                parentVersion = targetBlock.runtime;
+            }
+            else {
+                parentHash = targetBlock.parent;
+                const parentBlock = this.chainHead.findBlock(parentHash);
+                parentVersion = parentBlock?.runtime;
+            }
+            // fallback to fetching on-chain runtime if we can't find it in the block
+            if (!parentVersion) {
+                parentVersion = this.toSubstrateRuntimeVersion(await this.callAt(parentHash).core.version());
             }
         }
         else {
             // Block not pinned, try via Archive fallback if supported
             if (this._archive && (await this._archive.supported())) {
                 try {
+                    if (hash === this.genesisHash) {
+                        parentHash = hash;
+                    }
+                    else {
+                        const rawHeader = await this._archive.header(hash);
+                        (0, utils_1.assert)(rawHeader, `Header for block ${hash} not found`);
+                        const header = codecs_1.$Header.tryDecode(rawHeader);
+                        parentHash = header.parentHash;
+                    }
                     // Fetch runtime version via Archive
-                    const runtimeRaw = await this._archive.call('Core_version', '0x', hash);
+                    const runtimeRaw = await this._archive.call('Core_version', '0x', parentHash);
                     (0, utils_1.assert)(runtimeRaw, 'Runtime Version Not Found');
-                    targetVersion = this.toSubstrateRuntimeVersion(codecs_1.$RuntimeVersion.tryDecode(runtimeRaw));
+                    parentVersion = this.toSubstrateRuntimeVersion(codecs_1.$RuntimeVersion.tryDecode(runtimeRaw));
                 }
                 catch (error) {
                     throw new utils_1.DedotError(`Unable to fetch runtime version for block ${hash}: ${error}`);
@@ -215,8 +233,8 @@ class DedotClient// prettier-end-here
         }
         let metadata = this.metadata;
         let registry = this.registry;
-        if (targetVersion && targetVersion.specVersion !== this.runtimeVersion.specVersion) {
-            metadata = await this.fetchMetadata(hash, targetVersion);
+        if (parentVersion && parentVersion.specVersion !== this.runtimeVersion.specVersion) {
+            metadata = await this.fetchMetadata(parentHash, parentVersion);
             registry = new codecs_1.PortableRegistry(metadata.latest, this.options.hasher);
         }
         const api = {
@@ -224,7 +242,7 @@ class DedotClient// prettier-end-here
             atBlockHash: hash,
             options: this.options,
             genesisHash: this.genesisHash,
-            runtimeVersion: targetVersion,
+            runtimeVersion: parentVersion,
             metadata,
             registry,
             rpc: this.rpc,
@@ -235,6 +253,10 @@ class DedotClient// prettier-end-here
         api.query = (0, proxychain_js_1.newProxyChain)({ executor: new index_js_1.StorageQueryExecutorV2(api, this.chainHead) });
         api.call = (0, proxychain_js_1.newProxyChain)({ executor: new index_js_1.RuntimeApiExecutorV2(api, this.chainHead) });
         api.view = (0, proxychain_js_1.newProxyChain)({ executor: new index_js_1.ViewFunctionExecutorV2(api, this.chainHead) });
+        // @ts-ignore Add queryMulti implementation for at-block queries
+        api.queryMulti = (queries) => {
+            return this.internalQueryMulti(queries, undefined, hash);
+        };
         this._apiAtCache.set(hash, api);
         return api;
     }

package/cjs/client/LegacyClient.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LegacyClient = void 0;
 const codecs_1 = require("@dedot/codecs");
+const utils_1 = require("@dedot/utils");
 const index_js_1 = require("../executor/index.js");
 const proxychain_js_1 = require("../proxychain.js");
 const index_js_2 = require("../storage/index.js");
@@ -233,11 +234,12 @@ class LegacyClient// prettier-end-here
         const cached = this._apiAtCache.get(hash);
         if (cached)
             return cached;
-        const targetVersion = await this.#getRuntimeVersion(hash);
+        const parentHash = await this.#findParentHash(hash);
+        const targetVersion = await this.#getRuntimeVersion(parentHash);
         let metadata = this.metadata;
         let registry = this.registry;
         if (targetVersion.specVersion !== this.runtimeVersion.specVersion) {
-            metadata = await this.fetchMetadata(hash, targetVersion);
+            metadata = await this.fetchMetadata(parentHash, targetVersion);
             registry = new codecs_1.PortableRegistry(metadata.latest, this.options.hasher);
         }
         const api = {
@@ -255,11 +257,25 @@ class LegacyClient// prettier-end-here
         api.call = (0, proxychain_js_1.newProxyChain)({ executor: new index_js_1.RuntimeApiExecutor(api) });
         api.events = (0, proxychain_js_1.newProxyChain)({ executor: new index_js_1.EventExecutor(api) });
         api.errors = (0, proxychain_js_1.newProxyChain)({ executor: new index_js_1.ErrorExecutor(api) });
+        // @ts-ignore Add queryMulti implementation for at-block queries
+        api.queryMulti = (queries) => {
+            return this.internalQueryMulti(queries, undefined, hash);
+        };
         this._apiAtCache.set(hash, api);
         return api;
     }
     getStorageQuery() {
         return new index_js_2.LegacyStorageQuery(this);
     }
+    async #findParentHash(hash) {
+        if (hash === this.genesisHash) {
+            return this.genesisHash;
+        }
+        else {
+            const header = await this.rpc.chain_getHeader(hash);
+            (0, utils_1.assert)(header, `Header for ${hash} not found`);
+            return header.parentHash;
+        }
+    }
 }
 exports.LegacyClient = LegacyClient;

package/cjs/extrinsic/submittable/SubmittableExtrinsicV2.js

@@ -22,6 +22,15 @@ class SubmittableExtrinsicV2 extends BaseSubmittableExtrinsic_js_1.BaseSubmittab
         const txHash = this.hash;
         // validate the transaction
         // https://github.com/paritytech/json-rpc-interface-spec/issues/55#issuecomment-1609011150
+        // ensure at least 2 finalized blocks, this is to make sure the api.at can find the parent hash & block to fetch runtime
+        while (true) {
+            const block = await this.client.chainHead.finalizedBlock();
+            const parentBlock = this.client.chainHead.findBlock(block.parent);
+            if (parentBlock) {
+                break;
+            }
+            await (0, utils_1.waitFor)(100);
+        }
         const finalizedHash = await this.client.chainHead.finalizedHash();
         const validateTx = async (hash) => {
             const apiAt = await api.at(hash);

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

@@ -192,10 +192,19 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
             }
             case 'finalized': {
                 const { finalizedBlockHashes, prunedBlockHashes } = result;
-                this.#finalizedHash = finalizedBlockHashes.at(-1);
-                const finalizedRuntime = this.#findRuntimeAt(this.#finalizedHash);
-                if (finalizedRuntime) {
-                    this.#finalizedRuntime = finalizedRuntime;
+                const currentFinalizedNumber = this.findBlock(this.#finalizedHash).number;
+                for (const hash of finalizedBlockHashes) {
+                    const block = this.findBlock(hash);
+                    // Skip if block not found OR blocks that are already finalized (block number <= previous finalized number)
+                    if (!block || block.number <= currentFinalizedNumber) {
+                        continue;
+                    }
+                    this.#finalizedHash = hash;
+                    const finalizedRuntime = this.#findRuntimeAt(hash);
+                    if (finalizedRuntime) {
+                        this.#finalizedRuntime = finalizedRuntime;
+                    }
+                    this.emit('finalizedBlock', block);
                 }
                 // push new finalized hashes into the queue, we'll adjust the size later if needed
                 finalizedBlockHashes.forEach((hash) => {
@@ -204,7 +213,6 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
                     this.#finalizedQueue.push(hash);
                 });
                 const currentFinalizedBlock = this.findBlock(this.#finalizedHash);
-                this.emit('finalizedBlock', currentFinalizedBlock);
                 // TODO account for operations that haven't received its operationId yet
                 Object.values(this.#handlers).forEach(({ defer, hash, operationId }) => {
                     if (prunedBlockHashes.includes(hash)) {

package/client/BaseSubstrateClient.d.ts

@@ -77,6 +77,10 @@ export declare abstract class BaseSubstrateClient<Rv extends RpcVersion, ChainAp
     get tx(): ChainApi[Rv]['tx'];
     at<ChainApiAt extends GenericSubstrateApi = ChainApi[Rv]>(hash: BlockHash): Promise<ISubstrateClientAt<ChainApiAt>>;
     setSigner(signer?: InjectedSigner): void;
+    protected internalQueryMulti(queries: {
+        fn: GenericStorageQuery;
+        args?: any[];
+    }[], callback?: Callback<any[]>, blockHash?: BlockHash): Promise<any[] | Unsub>;
     /**
      * Query multiple storage items in a single call
      *

package/client/BaseSubstrateClient.js

@@ -321,7 +321,7 @@ export class BaseSubstrateClient extends JsonRpcClient {
     setSigner(signer) {
         this._options.signer = signer;
     }
-    async queryMulti(queries, callback) {
+    async internalQueryMulti(queries, callback, blockHash) {
         // Extract keys from queries
         const keys = queries.map((q) => q.fn.rawKey(...(q.args || [])));
         const decodeValue = (query, rawValue) => {
@@ -337,10 +337,19 @@ export class BaseSubstrateClient extends JsonRpcClient {
             });
         }
         else {
-            const results = await this.getStorageQuery().query(keys);
+            const results = await this.getStorageQuery().query(keys, blockHash);
             return queries.map((q, i) => decodeValue(q.fn, results[keys[i]]));
         }
     }
+    async queryMulti(queries, callback) {
+        // If a callback is provided, set up a subscription
+        if (callback) {
+            return this.internalQueryMulti(queries, callback);
+        }
+        else {
+            return this.internalQueryMulti(queries);
+        }
+    }
     getStorageQuery() {
         throw new Error('Unimplemented!');
     }

package/client/DedotClient.js

@@ -1,7 +1,7 @@
-import { $H256, $RuntimeVersion, PortableRegistry } from '@dedot/codecs';
+import { $H256, $Header, $RuntimeVersion, PortableRegistry } from '@dedot/codecs';
 import { u32 } from '@dedot/shape';
-import { assert, concatU8a, noop, twox64Concat, u8aToHex, xxhashAsU8a, DedotError } from '@dedot/utils';
-import { ConstantExecutor, ErrorExecutor, EventExecutor, RuntimeApiExecutorV2, StorageQueryExecutorV2, ViewFunctionExecutorV2, TxExecutorV2, } from '../executor/index.js';
+import { assert, concatU8a, DedotError, noop, twox64Concat, u8aToHex, xxhashAsU8a } from '@dedot/utils';
+import { ConstantExecutor, ErrorExecutor, EventExecutor, RuntimeApiExecutorV2, StorageQueryExecutorV2, TxExecutorV2, ViewFunctionExecutorV2, } from '../executor/index.js';
 import { Archive, ChainHead, ChainSpec, Transaction, TransactionWatch } from '../json-rpc/index.js';
 import { newProxyChain } from '../proxychain.js';
 import { NewStorageQuery } from '../storage/index.js';
@@ -183,24 +183,42 @@ export class DedotClient// prettier-end-here
         const cached = this._apiAtCache.get(hash);
         if (cached)
             return cached;
-        let targetVersion;
+        let parentVersion;
+        let parentHash;
         // Try to get block info from ChainHead first (for pinned blocks)
         const targetBlock = this.chainHead.findBlock(hash);
         if (targetBlock) {
-            targetVersion = targetBlock.runtime;
-            if (!targetVersion) {
-                // fallback to fetching on-chain runtime if we can't find it in the block
-                targetVersion = this.toSubstrateRuntimeVersion(await this.callAt(hash).core.version());
+            if (hash === this.genesisHash) {
+                parentHash = hash;
+                parentVersion = targetBlock.runtime;
+            }
+            else {
+                parentHash = targetBlock.parent;
+                const parentBlock = this.chainHead.findBlock(parentHash);
+                parentVersion = parentBlock?.runtime;
+            }
+            // fallback to fetching on-chain runtime if we can't find it in the block
+            if (!parentVersion) {
+                parentVersion = this.toSubstrateRuntimeVersion(await this.callAt(parentHash).core.version());
             }
         }
         else {
             // Block not pinned, try via Archive fallback if supported
             if (this._archive && (await this._archive.supported())) {
                 try {
+                    if (hash === this.genesisHash) {
+                        parentHash = hash;
+                    }
+                    else {
+                        const rawHeader = await this._archive.header(hash);
+                        assert(rawHeader, `Header for block ${hash} not found`);
+                        const header = $Header.tryDecode(rawHeader);
+                        parentHash = header.parentHash;
+                    }
                     // Fetch runtime version via Archive
-                    const runtimeRaw = await this._archive.call('Core_version', '0x', hash);
+                    const runtimeRaw = await this._archive.call('Core_version', '0x', parentHash);
                     assert(runtimeRaw, 'Runtime Version Not Found');
-                    targetVersion = this.toSubstrateRuntimeVersion($RuntimeVersion.tryDecode(runtimeRaw));
+                    parentVersion = this.toSubstrateRuntimeVersion($RuntimeVersion.tryDecode(runtimeRaw));
                 }
                 catch (error) {
                     throw new DedotError(`Unable to fetch runtime version for block ${hash}: ${error}`);
@@ -212,8 +230,8 @@ export class DedotClient// prettier-end-here
         }
         let metadata = this.metadata;
         let registry = this.registry;
-        if (targetVersion && targetVersion.specVersion !== this.runtimeVersion.specVersion) {
-            metadata = await this.fetchMetadata(hash, targetVersion);
+        if (parentVersion && parentVersion.specVersion !== this.runtimeVersion.specVersion) {
+            metadata = await this.fetchMetadata(parentHash, parentVersion);
             registry = new PortableRegistry(metadata.latest, this.options.hasher);
         }
         const api = {
@@ -221,7 +239,7 @@ export class DedotClient// prettier-end-here
             atBlockHash: hash,
             options: this.options,
             genesisHash: this.genesisHash,
-            runtimeVersion: targetVersion,
+            runtimeVersion: parentVersion,
             metadata,
             registry,
             rpc: this.rpc,
@@ -232,6 +250,10 @@ export class DedotClient// prettier-end-here
         api.query = newProxyChain({ executor: new StorageQueryExecutorV2(api, this.chainHead) });
         api.call = newProxyChain({ executor: new RuntimeApiExecutorV2(api, this.chainHead) });
         api.view = newProxyChain({ executor: new ViewFunctionExecutorV2(api, this.chainHead) });
+        // @ts-ignore Add queryMulti implementation for at-block queries
+        api.queryMulti = (queries) => {
+            return this.internalQueryMulti(queries, undefined, hash);
+        };
         this._apiAtCache.set(hash, api);
         return api;
     }

package/client/LegacyClient.js

@@ -1,4 +1,5 @@
 import { PortableRegistry } from '@dedot/codecs';
+import { assert } from '@dedot/utils';
 import { ConstantExecutor, ErrorExecutor, EventExecutor, RuntimeApiExecutor, StorageQueryExecutor, TxExecutor, ViewFunctionExecutor, } from '../executor/index.js';
 import { newProxyChain } from '../proxychain.js';
 import { LegacyStorageQuery } from '../storage/index.js';
@@ -230,11 +231,12 @@ export class LegacyClient// prettier-end-here
         const cached = this._apiAtCache.get(hash);
         if (cached)
             return cached;
-        const targetVersion = await this.#getRuntimeVersion(hash);
+        const parentHash = await this.#findParentHash(hash);
+        const targetVersion = await this.#getRuntimeVersion(parentHash);
         let metadata = this.metadata;
         let registry = this.registry;
         if (targetVersion.specVersion !== this.runtimeVersion.specVersion) {
-            metadata = await this.fetchMetadata(hash, targetVersion);
+            metadata = await this.fetchMetadata(parentHash, targetVersion);
             registry = new PortableRegistry(metadata.latest, this.options.hasher);
         }
         const api = {
@@ -252,10 +254,24 @@ export class LegacyClient// prettier-end-here
         api.call = newProxyChain({ executor: new RuntimeApiExecutor(api) });
         api.events = newProxyChain({ executor: new EventExecutor(api) });
         api.errors = newProxyChain({ executor: new ErrorExecutor(api) });
+        // @ts-ignore Add queryMulti implementation for at-block queries
+        api.queryMulti = (queries) => {
+            return this.internalQueryMulti(queries, undefined, hash);
+        };
         this._apiAtCache.set(hash, api);
         return api;
     }
     getStorageQuery() {
         return new LegacyStorageQuery(this);
     }
+    async #findParentHash(hash) {
+        if (hash === this.genesisHash) {
+            return this.genesisHash;
+        }
+        else {
+            const header = await this.rpc.chain_getHeader(hash);
+            assert(header, `Header for ${hash} not found`);
+            return header.parentHash;
+        }
+    }
 }

package/extrinsic/submittable/SubmittableExtrinsicV2.js

@@ -1,4 +1,4 @@
-import { AsyncQueue, noop } from '@dedot/utils';
+import { AsyncQueue, noop, waitFor } from '@dedot/utils';
 import { BaseSubmittableExtrinsic } from './BaseSubmittableExtrinsic.js';
 import { SubmittableResult } from './SubmittableResult.js';
 import { InvalidTxError } from './errors.js';
@@ -19,6 +19,15 @@ export class SubmittableExtrinsicV2 extends BaseSubmittableExtrinsic {
         const txHash = this.hash;
         // validate the transaction
         // https://github.com/paritytech/json-rpc-interface-spec/issues/55#issuecomment-1609011150
+        // ensure at least 2 finalized blocks, this is to make sure the api.at can find the parent hash & block to fetch runtime
+        while (true) {
+            const block = await this.client.chainHead.finalizedBlock();
+            const parentBlock = this.client.chainHead.findBlock(block.parent);
+            if (parentBlock) {
+                break;
+            }
+            await waitFor(100);
+        }
         const finalizedHash = await this.client.chainHead.finalizedHash();
         const validateTx = async (hash) => {
             const apiAt = await api.at(hash);

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

@@ -189,10 +189,19 @@ export class ChainHead extends JsonRpcGroup {
             }
             case 'finalized': {
                 const { finalizedBlockHashes, prunedBlockHashes } = result;
-                this.#finalizedHash = finalizedBlockHashes.at(-1);
-                const finalizedRuntime = this.#findRuntimeAt(this.#finalizedHash);
-                if (finalizedRuntime) {
-                    this.#finalizedRuntime = finalizedRuntime;
+                const currentFinalizedNumber = this.findBlock(this.#finalizedHash).number;
+                for (const hash of finalizedBlockHashes) {
+                    const block = this.findBlock(hash);
+                    // Skip if block not found OR blocks that are already finalized (block number <= previous finalized number)
+                    if (!block || block.number <= currentFinalizedNumber) {
+                        continue;
+                    }
+                    this.#finalizedHash = hash;
+                    const finalizedRuntime = this.#findRuntimeAt(hash);
+                    if (finalizedRuntime) {
+                        this.#finalizedRuntime = finalizedRuntime;
+                    }
+                    this.emit('finalizedBlock', block);
                 }
                 // push new finalized hashes into the queue, we'll adjust the size later if needed
                 finalizedBlockHashes.forEach((hash) => {
@@ -201,7 +210,6 @@ export class ChainHead extends JsonRpcGroup {
                     this.#finalizedQueue.push(hash);
                 });
                 const currentFinalizedBlock = this.findBlock(this.#finalizedHash);
-                this.emit('finalizedBlock', currentFinalizedBlock);
                 // TODO account for operations that haven't received its operationId yet
                 Object.values(this.#handlers).forEach(({ defer, hash, operationId }) => {
                     if (prunedBlockHashes.includes(hash)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dedot/api",
-  "version": "0.17.1-next.db98ff20.1+db98ff20",
+  "version": "0.18.1",
   "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.17.1-next.db98ff20.1+db98ff20",
-    "@dedot/providers": "0.17.1-next.db98ff20.1+db98ff20",
-    "@dedot/runtime-specs": "0.17.1-next.db98ff20.1+db98ff20",
-    "@dedot/shape": "0.17.1-next.db98ff20.1+db98ff20",
-    "@dedot/storage": "0.17.1-next.db98ff20.1+db98ff20",
-    "@dedot/types": "0.17.1-next.db98ff20.1+db98ff20",
-    "@dedot/utils": "0.17.1-next.db98ff20.1+db98ff20"
+    "@dedot/codecs": "0.18.1",
+    "@dedot/providers": "0.18.1",
+    "@dedot/runtime-specs": "0.18.1",
+    "@dedot/shape": "0.18.1",
+    "@dedot/storage": "0.18.1",
+    "@dedot/types": "0.18.1",
+    "@dedot/utils": "0.18.1"
   },
   "scripts": {
     "build": "tsc --project tsconfig.build.json && tsc --project tsconfig.build.cjs.json",
@@ -48,7 +48,7 @@
     "node": ">=18"
   },
   "license": "Apache-2.0",
-  "gitHead": "db98ff20684d2a74b5e5402cabf43ef601d05d31",
+  "gitHead": "3ffda568232b50a3993d13c6ccac2894b0759dd7",
   "module": "./index.js",
   "types": "./index.d.ts"
 }

package/types.d.ts

@@ -99,6 +99,28 @@ export interface IGenericSubstrateClient<ChainApi extends GenericSubstrateApi =
     events: ChainApi['events'];
     errors: ChainApi['errors'];
     view: ChainApi['view'];
+    /**
+     * Query multiple storage items in a single call
+     *
+     * This method allows you to query multiple storage items in a single call with type safety
+     * for both the query functions and their results.
+     *
+     * @example
+     * // One-time query with type-safe results
+     * const [balance, blockNumber] = await client.queryMulti([
+     *   { fn: client.query.system.account, args: [ALICE] },
+     *   { fn: client.query.system.number, args: [] }
+     * ]);
+     *
+     * @template Fns Array of storage query functions
+     * @param queries - Array of query specifications, each with a function and optional arguments
+     * @returns Array of decoded values with proper types
+     */
+    queryMulti<Fns extends GenericStorageQuery[]>(queries: {
+        [K in keyof Fns]: Query<Fns[K]>;
+    }): Promise<{
+        [K in keyof Fns]: QueryFnResult<Fns[K]>;
+    }>;
 }
 /**
  * A generic interface for Substrate clients at a specific block
@@ -128,10 +150,30 @@ export interface ISubstrateClient<ChainApi extends GenericSubstrateApi = Generic
      */
     setSigner(signer?: InjectedSigner): void;
     /**
-     * Perform multiple storage queries in parallel
-     * @param queries - An array of query objects
-     * @param callback - Optional callback function to handle results
-     * @returns A promise resolving to an array of results or an Unsub function
+     * Query multiple storage items in a single call or subscribe to multiple storage items
+     *
+     * This method allows you to query multiple storage items in a single call or set up a subscription
+     * to multiple storage items. It provides type safety for both the query functions and their results.
+     *
+     * @example
+     * // One-time query with type-safe results
+     * const [balance, blockNumber] = await client.queryMulti([
+     *   { fn: client.query.system.account, args: [ALICE] },
+     *   { fn: client.query.system.number, args: [] }
+     * ]);
+     *
+     * // Subscription with callback
+     * const unsub = await client.queryMulti([
+     *   { fn: client.query.system.account, args: [ALICE] },
+     *   { fn: client.query.system.number, args: [] }
+     * ], (results) => {
+     *   console.log('Balance:', results[0], 'Block number:', results[1]);
+     * });
+     *
+     * @template Fns Array of storage query functions
+     * @param queries - Array of query specifications, each with a function and optional arguments
+     * @param callback - Optional callback for subscription-based queries
+     * @returns For one-time queries: Array of decoded values with proper types; For subscriptions: Unsubscribe function
      */
     queryMulti<Fns extends GenericStorageQuery[]>(queries: {
         [K in keyof Fns]: Query<Fns[K]>;