@dedot/api 0.15.2 → 0.16.0

package/client/LegacyClient.js

@@ -46,7 +46,6 @@ export class LegacyClient// prettier-end-here
  extends BaseSubstrateClient {
     #runtimeSubscriptionUnsub;
     #healthTimer;
-    #apiAtCache = {};
     /**
      * Use factory methods (`create`, `new`) to create `Dedot` instances.
      *
@@ -93,7 +92,6 @@ export class LegacyClient// prettier-end-here
     }
     cleanUp() {
         super.cleanUp();
-        this.#apiAtCache = {};
         this.#healthTimer = undefined;
         this.#runtimeSubscriptionUnsub = undefined;
     }
@@ -229,8 +227,9 @@ export class LegacyClient// prettier-end-here
      * @param hash
      */
     async at(hash) {
-        if (this.#apiAtCache[hash])
-            return this.#apiAtCache[hash];
+        const cached = this._apiAtCache.get(hash);
+        if (cached)
+            return cached;
         const targetVersion = await this.#getRuntimeVersion(hash);
         let metadata = this.metadata;
         let registry = this.registry;
@@ -253,7 +252,7 @@ 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) });
-        this.#apiAtCache[hash] = api;
+        this._apiAtCache.set(hash, api);
         return api;
     }
     getStorageQuery() {

package/executor/Executor.d.ts

@@ -1,7 +1,7 @@
 import type { BlockHash, PalletDefLatest } from '@dedot/codecs';
 import type { GenericSubstrateApi } from '@dedot/types';
 import { HexString } from '@dedot/utils';
-import { ISubstrateClientAt } from '../types.js';
+import { ISubstrateClient, ISubstrateClientAt } from '../types.js';
 export interface StateCallParams {
     func: string;
     params: HexString;
@@ -13,10 +13,10 @@ export interface StateCallParams {
  */
 export declare abstract class Executor<ChainApi extends GenericSubstrateApi = GenericSubstrateApi> {
     #private;
-    readonly client: ISubstrateClientAt<ChainApi>;
-    constructor(client: ISubstrateClientAt<ChainApi>, atBlockHash?: BlockHash);
-    get atBlockHash(): `0x${string}` | undefined;
-    get registry(): import("@dedot/codecs").PortableRegistry;
+    readonly client: ISubstrateClientAt<ChainApi> | ISubstrateClient<ChainApi, any>;
+    constructor(client: ISubstrateClientAt<ChainApi> | ISubstrateClient<ChainApi, any>, atBlockHash?: BlockHash);
+    get atBlockHash(): any;
+    get registry(): import("@dedot/codecs").PortableRegistry<ChainApi>;
     get metadata(): {
         types: {
             id: number;

package/executor/Executor.js

@@ -11,6 +11,7 @@ export class Executor {
         this.#atBlockHash = atBlockHash;
     }
     get atBlockHash() {
+        // @ts-ignore
         return this.#atBlockHash || this.client.atBlockHash;
     }
     get registry() {

package/executor/StorageQueryExecutor.d.ts

@@ -1,5 +1,5 @@
 import { BlockHash, Option, StorageData, StorageKey } from '@dedot/codecs';
-import type { AsyncMethod, Callback, GenericStorageQuery, GenericSubstrateApi, RpcVersion, Unsub } from '@dedot/types';
+import type { AsyncMethod, Callback, GenericStorageQuery, GenericSubstrateApi, Unsub } from '@dedot/types';
 import { type BaseStorageQuery, QueryableStorage } from '../storage/index.js';
 import { Executor } from './Executor.js';
 /**
@@ -9,7 +9,7 @@ import { Executor } from './Executor.js';
 export declare class StorageQueryExecutor<ChainApi extends GenericSubstrateApi = GenericSubstrateApi> extends Executor<ChainApi> {
     doExecute(pallet: string, storage: string): GenericStorageQuery;
     protected exposeStorageMapMethods(entry: QueryableStorage): Record<string, AsyncMethod>;
-    protected getStorageQuery(): BaseStorageQuery<RpcVersion>;
+    protected getStorageQuery(): BaseStorageQuery;
     protected queryStorage(keys: StorageKey[], hash?: BlockHash): Promise<Record<StorageKey, Option<StorageData>>>;
     protected subscribeStorage(keys: StorageKey[], callback: Callback<Array<StorageData | undefined>>): Promise<Unsub>;
 }

package/executor/v2/RuntimeApiExecutorV2.d.ts

@@ -2,7 +2,7 @@ import type { BlockHash } from '@dedot/codecs';
 import type { GenericSubstrateApi } from '@dedot/types';
 import { HexString } from '@dedot/utils';
 import { ChainHead } from '../../json-rpc/index.js';
-import { ISubstrateClientAt } from '../../types.js';
+import { ISubstrateClient, ISubstrateClientAt } from '../../types.js';
 import { StateCallParams } from '../Executor.js';
 import { RuntimeApiExecutor } from '../RuntimeApiExecutor.js';
 /**
@@ -10,6 +10,6 @@ import { RuntimeApiExecutor } from '../RuntimeApiExecutor.js';
  */
 export declare class RuntimeApiExecutorV2<ChainApi extends GenericSubstrateApi = GenericSubstrateApi> extends RuntimeApiExecutor<ChainApi> {
     chainHead: ChainHead;
-    constructor(client: ISubstrateClientAt<ChainApi>, chainHead: ChainHead, atBlockHash?: BlockHash);
+    constructor(client: ISubstrateClientAt<ChainApi> | ISubstrateClient<ChainApi, any>, chainHead: ChainHead, atBlockHash?: BlockHash);
     protected stateCall(callParams: StateCallParams): Promise<HexString>;
 }

package/executor/v2/StorageQueryExecutorV2.d.ts

@@ -1,15 +1,15 @@
 import { BlockHash } from '@dedot/codecs';
-import type { AsyncMethod, GenericSubstrateApi, RpcVersion } from '@dedot/types';
+import type { AsyncMethod, GenericSubstrateApi } from '@dedot/types';
 import { ChainHead } from '../../json-rpc/index.js';
 import { type BaseStorageQuery, QueryableStorage } from '../../storage/index.js';
-import { ISubstrateClientAt } from '../../types.js';
+import { ISubstrateClient, ISubstrateClientAt } from '../../types.js';
 import { StorageQueryExecutor } from '../StorageQueryExecutor.js';
 /**
  * @name StorageQueryExecutorV2
  */
 export declare class StorageQueryExecutorV2<ChainApi extends GenericSubstrateApi = GenericSubstrateApi> extends StorageQueryExecutor<ChainApi> {
     chainHead: ChainHead;
-    constructor(client: ISubstrateClientAt<ChainApi>, chainHead: ChainHead, atBlockHash?: BlockHash);
+    constructor(client: ISubstrateClientAt<ChainApi> | ISubstrateClient<ChainApi, any>, chainHead: ChainHead, atBlockHash?: BlockHash);
     protected exposeStorageMapMethods(entry: QueryableStorage): Record<string, AsyncMethod>;
-    protected getStorageQuery(): BaseStorageQuery<RpcVersion>;
+    protected getStorageQuery(): BaseStorageQuery;
 }

package/executor/v2/StorageQueryExecutorV2.js

@@ -19,9 +19,7 @@ export class StorageQueryExecutorV2 extends StorageQueryExecutor {
         const entries = async (...args) => {
             const withArgs = !!args && args.length > 0;
             const key = withArgs ? entry.encodeKey(args, true) : entry.prefixKey;
-            const results = await this.chainHead.storage([
-                { type: 'descendantsValues', key },
-            ]);
+            const results = await this.chainHead.storage([{ type: 'descendantsValues', key }]);
             return results.map(({ key, value }) => [
                 entry.decodeKey(key),
                 entry.decodeValue(value),

package/executor/v2/TxExecutorV2.d.ts

@@ -6,6 +6,7 @@ import { TxExecutor } from '../TxExecutor.js';
  * @description Execute a transaction instruction, returns a submittable extrinsic
  */
 export declare class TxExecutorV2<ChainApi extends VersionedGenericSubstrateApi = VersionedGenericSubstrateApi> extends TxExecutor<ChainApi[RpcVersion]> {
-    constructor(api: DedotClient<ChainApi>);
+    readonly client: DedotClient<ChainApi>;
+    constructor(client: DedotClient<ChainApi>);
     protected createExtrinsic(call: IRuntimeTxCall): any;
 }

package/executor/v2/TxExecutorV2.js

@@ -6,9 +6,11 @@ import { TxExecutor } from '../TxExecutor.js';
  * @description Execute a transaction instruction, returns a submittable extrinsic
  */
 export class TxExecutorV2 extends TxExecutor {
-    constructor(api) {
-        assert(api.rpcVersion === 'v2', 'Only supports JSON-RPC v2');
-        super(api);
+    client;
+    constructor(client) {
+        assert(client.rpcVersion === 'v2', 'Only supports JSON-RPC v2');
+        super(client);
+        this.client = client;
     }
     createExtrinsic(call) {
         return new SubmittableExtrinsicV2(this.client, call);

package/executor/v2/ViewFunctionExecutorV2.d.ts

@@ -1,7 +1,7 @@
 import type { GenericSubstrateApi } from '@dedot/types';
 import { HexString } from '@dedot/utils';
 import { ChainHead } from '../../json-rpc/index.js';
-import { ISubstrateClientAt } from '../../types.js';
+import { ISubstrateClient, ISubstrateClientAt } from '../../types.js';
 import { StateCallParams } from '../Executor.js';
 import { ViewFunctionExecutor } from '../ViewFunctionExecutor.js';
 /**
@@ -9,6 +9,6 @@ import { ViewFunctionExecutor } from '../ViewFunctionExecutor.js';
  */
 export declare class ViewFunctionExecutorV2<ChainApi extends GenericSubstrateApi = GenericSubstrateApi> extends ViewFunctionExecutor<ChainApi> {
     chainHead: ChainHead;
-    constructor(client: ISubstrateClientAt<ChainApi>, chainHead: ChainHead);
+    constructor(client: ISubstrateClientAt<ChainApi> | ISubstrateClient<ChainApi, any>, chainHead: ChainHead);
     protected stateCall(callParams: StateCallParams): Promise<HexString>;
 }

package/extrinsic/extensions/SignedExtension.d.ts

@@ -19,17 +19,17 @@ interface SignedExtensionOptions {
     payloadOptions?: Partial<PayloadOptions>;
 }
 export declare abstract class SignedExtension<Data extends any = {}, AdditionalSigned extends any = []> implements ISignedExtension {
-    readonly client: ISubstrateClient;
+    readonly client: ISubstrateClient<any, any>;
     readonly options?: SignedExtensionOptions | undefined;
     data: Data;
     additionalSigned: AdditionalSigned;
-    constructor(client: ISubstrateClient, options?: SignedExtensionOptions | undefined);
+    constructor(client: ISubstrateClient<any, any>, options?: SignedExtensionOptions | undefined);
     init(): Promise<void>;
     fromPayload(payload: SignerPayloadJSON): Promise<void>;
     get identifier(): string;
     get $Data(): $.AnyShape;
     get $AdditionalSigned(): $.AnyShape;
-    get registry(): PortableRegistry;
+    get registry(): PortableRegistry<any>;
     get signedExtensionDef(): {
         ident: string;
         typeId: number;

package/extrinsic/submittable/BaseSubmittableExtrinsic.d.ts

@@ -9,8 +9,8 @@ interface TxHooks {
 }
 export declare abstract class BaseSubmittableExtrinsic extends Extrinsic implements ISubmittableExtrinsic {
     #private;
-    readonly client: ISubstrateClient;
-    constructor(client: ISubstrateClient, call: IRuntimeTxCall);
+    readonly client: ISubstrateClient<any>;
+    constructor(client: ISubstrateClient<any>, call: IRuntimeTxCall);
     withHooks(hooks: TxHooks): void;
     protected transformTxResult<R extends ISubmittableResult = ISubmittableResult>(result: ISubmittableResult): R;
     paymentInfo(account: AddressOrPair, options?: Partial<PayloadOptions>): Promise<TxPaymentInfo>;

package/extrinsic/submittable/SubmittableExtrinsicV2.d.ts

@@ -7,8 +7,8 @@ import { BaseSubmittableExtrinsic } from './BaseSubmittableExtrinsic.js';
  */
 export declare class SubmittableExtrinsicV2 extends BaseSubmittableExtrinsic {
     #private;
-    client: DedotClient;
-    constructor(client: DedotClient, call: IRuntimeTxCall);
+    client: DedotClient<any>;
+    constructor(client: DedotClient<any>, call: IRuntimeTxCall);
     send(): TxHash;
     send(callback: Callback): TxUnsub;
 }

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

@@ -0,0 +1,134 @@
+import { BlockHash, Option } from '@dedot/codecs';
+import { ArchiveStorageResult, PaginatedStorageQuery } from '@dedot/types/json-rpc';
+import { HexString } from '@dedot/utils';
+import { IJsonRpcClient } from '../../types.js';
+import { JsonRpcGroup, JsonRpcGroupOptions } from './JsonRpcGroup.js';
+/**
+ * @name Archive
+ * Archive JSON-RPC methods for accessing historical blockchain data.
+ * Functions with the `archive` prefix allow obtaining the state of the chain
+ * at any point in the present or in the past.
+ *
+ * JSON-RPC V2: https://paritytech.github.io/json-rpc-interface-spec/api/archive.html
+ */
+export declare class Archive extends JsonRpcGroup {
+    #private;
+    constructor(client: IJsonRpcClient, options?: Partial<JsonRpcGroupOptions>);
+    /**
+     * Retrieves the body (list of transactions) of a given block.
+     * Returns an array of strings containing the hexadecimal-encoded SCALE-codec-encoded
+     * transactions in that block. If no block with that hash is found, null.
+     *
+     * @param hash - The block hash (optional, defaults to current finalized block)
+     * @returns Array of transaction hashes or null if block not found
+     *
+     * @example
+     * ```typescript
+     * // Get transactions from current finalized block
+     * const transactions = await archive.body();
+     *
+     * // Get transactions from specific block
+     * const transactions = await archive.body('0x1234...');
+     * ```
+     */
+    body(hash?: BlockHash): Promise<Option<Array<HexString>>>;
+    /**
+     * Get the chain's genesis hash.
+     * Returns a string containing the hexadecimal-encoded hash of the genesis block of the chain.
+     * This value is cached after the first call.
+     *
+     * @returns The genesis block hash
+     */
+    genesisHash(): Promise<HexString>;
+    /**
+     * Get the block's header.
+     * Returns a string containing the hexadecimal-encoded SCALE-codec encoding header of the block.
+     *
+     * @param hash - The block hash (optional, defaults to current finalized block)
+     * @returns The encoded block header or null if block not found
+     *
+     * @example
+     * ```typescript
+     * // Get header of current finalized block
+     * const header = await archive.header();
+     *
+     * // Get header of specific block
+     * const header = await archive.header('0x1234...');
+     * ```
+     */
+    header(hash?: BlockHash): Promise<Option<HexString>>;
+    /**
+     * Get the height of the current finalized block.
+     * Returns an integer height of the current finalized block of the chain.
+     *
+     * @returns The height of the finalized block
+     */
+    finalizedHeight(): Promise<number>;
+    /**
+     * Get the hash of the current finalized block.
+     * Returns a string containing the hexadecimal-encoded hash of the current finalized block.
+     * This is a convenience method that combines finalizedHeight() and hashByHeight().
+     *
+     * @returns The hash of the current finalized block
+     */
+    finalizedHash(): Promise<HexString>;
+    /**
+     * Get the hashes of blocks from the given height.
+     * Returns an array (possibly empty) of strings containing hexadecimal-encoded hashes of block headers.
+     *
+     * Note: For heights <= finalized height, there is guaranteed to be one block.
+     * For heights > finalized height, there may be zero, one or multiple blocks depending on forks.
+     *
+     * @param height - The block height
+     * @returns Array of block hashes at the given height
+     */
+    hashByHeight(height: number): Promise<Array<HexString>>;
+    /**
+     * Call into the Runtime API at a specified block's state.
+     *
+     * @param func - The runtime API function to call
+     * @param params - The parameters for the function call (SCALE-encoded)
+     * @param hash - The block hash (optional, defaults to current finalized block)
+     * @returns The result of the runtime call
+     *
+     * @example
+     * ```typescript
+     * // Call Core_version on current finalized block
+     * const version = await archive.call('Core_version', '0x');
+     *
+     * // Call Core_version on specific block
+     * const version = await archive.call('Core_version', '0x', '0x1234...');
+     * ```
+     */
+    call(func: string, params: HexString, hash?: BlockHash): Promise<HexString>;
+    /**
+     * Returns storage entries at a specific block's state.
+     * This method collects all storage events and returns them as a single result.
+     *
+     * @param items - Array of storage queries with optional pagination
+     * @param childTrie - Optional child trie key
+     * @param hash - The block hash (optional, defaults to current finalized block)
+     * @returns Storage results array
+     *
+     * @example
+     * ```typescript
+     * // Query storage from current finalized block
+     * const results = await archive.storage([{ key: '0x1234', type: 'value' }]);
+     *
+     * // Query storage from specific block
+     * const results = await archive.storage([{ key: '0x1234', type: 'value' }], null, '0xabcd...');
+     * ```
+     */
+    storage(items: Array<PaginatedStorageQuery>, childTrie?: HexString | null, hash?: BlockHash): Promise<ArchiveStorageResult>;
+    /**
+     * Clears the internal cache used for storing archive query results.
+     * This can be useful for memory management or when you want to force fresh data retrieval.
+     *
+     * @example
+     * ```typescript
+     * // Clear all cached results
+     * archive.clearCache();
+     * ```
+     */
+    clearCache(): void;
+}

package/json-rpc/group/Archive.js

@@ -0,0 +1,228 @@
+import { DedotError, LRUCache } from '@dedot/utils';
+import { JsonRpcGroup } from './JsonRpcGroup.js';
+const ARCHIVE_CACHE_CAPACITY = 256;
+const ARCHIVE_CACHE_TTL = 60_000; // 1 minutes - archive data is immutable
+/**
+ * @name Archive
+ * Archive JSON-RPC methods for accessing historical blockchain data.
+ * Functions with the `archive` prefix allow obtaining the state of the chain
+ * at any point in the present or in the past.
+ *
+ * JSON-RPC V2: https://paritytech.github.io/json-rpc-interface-spec/api/archive.html
+ */
+export class Archive extends JsonRpcGroup {
+    #genesisHash;
+    #cache;
+    constructor(client, options) {
+        super(client, { prefix: 'archive', supportedVersions: ['unstable', 'v1'], ...options });
+        this.#cache = new LRUCache(ARCHIVE_CACHE_CAPACITY, ARCHIVE_CACHE_TTL);
+    }
+    /**
+     * Retrieves the body (list of transactions) of a given block.
+     * Returns an array of strings containing the hexadecimal-encoded SCALE-codec-encoded
+     * transactions in that block. If no block with that hash is found, null.
+     *
+     * @param hash - The block hash (optional, defaults to current finalized block)
+     * @returns Array of transaction hashes or null if block not found
+     *
+     * @example
+     * ```typescript
+     * // Get transactions from current finalized block
+     * const transactions = await archive.body();
+     *
+     * // Get transactions from specific block
+     * const transactions = await archive.body('0x1234...');
+     * ```
+     */
+    async body(hash) {
+        const blockHash = hash || (await this.finalizedHash());
+        const cacheKey = `${blockHash}::body`;
+        const cached = this.#cache.get(cacheKey);
+        if (cached !== null) {
+            return cached;
+        }
+        const result = await this.send('body', blockHash);
+        this.#cache.set(cacheKey, result);
+        return result;
+    }
+    /**
+     * Get the chain's genesis hash.
+     * Returns a string containing the hexadecimal-encoded hash of the genesis block of the chain.
+     * This value is cached after the first call.
+     *
+     * @returns The genesis block hash
+     */
+    async genesisHash() {
+        if (!this.#genesisHash) {
+            this.#genesisHash = await this.send('genesisHash');
+        }
+        return this.#genesisHash;
+    }
+    /**
+     * Get the block's header.
+     * Returns a string containing the hexadecimal-encoded SCALE-codec encoding header of the block.
+     *
+     * @param hash - The block hash (optional, defaults to current finalized block)
+     * @returns The encoded block header or null if block not found
+     *
+     * @example
+     * ```typescript
+     * // Get header of current finalized block
+     * const header = await archive.header();
+     *
+     * // Get header of specific block
+     * const header = await archive.header('0x1234...');
+     * ```
+     */
+    async header(hash) {
+        const blockHash = hash || (await this.finalizedHash());
+        const cacheKey = `${blockHash}::header`;
+        const cached = this.#cache.get(cacheKey);
+        if (cached !== null) {
+            return cached;
+        }
+        const result = await this.send('header', blockHash);
+        this.#cache.set(cacheKey, result);
+        return result;
+    }
+    /**
+     * Get the height of the current finalized block.
+     * Returns an integer height of the current finalized block of the chain.
+     *
+     * @returns The height of the finalized block
+     */
+    async finalizedHeight() {
+        return this.send('finalizedHeight');
+    }
+    /**
+     * Get the hash of the current finalized block.
+     * Returns a string containing the hexadecimal-encoded hash of the current finalized block.
+     * This is a convenience method that combines finalizedHeight() and hashByHeight().
+     *
+     * @returns The hash of the current finalized block
+     */
+    async finalizedHash() {
+        const height = await this.finalizedHeight();
+        const hashes = await this.hashByHeight(height);
+        if (hashes.length === 0) {
+            throw new Error(`No block found at finalized height ${height}`);
+        }
+        return hashes[0];
+    }
+    /**
+     * Get the hashes of blocks from the given height.
+     * Returns an array (possibly empty) of strings containing hexadecimal-encoded hashes of block headers.
+     *
+     * Note: For heights <= finalized height, there is guaranteed to be one block.
+     * For heights > finalized height, there may be zero, one or multiple blocks depending on forks.
+     *
+     * @param height - The block height
+     * @returns Array of block hashes at the given height
+     */
+    async hashByHeight(height) {
+        return this.send('hashByHeight', height);
+    }
+    /**
+     * Call into the Runtime API at a specified block's state.
+     *
+     * @param func - The runtime API function to call
+     * @param params - The parameters for the function call (SCALE-encoded)
+     * @param hash - The block hash (optional, defaults to current finalized block)
+     * @returns The result of the runtime call
+     *
+     * @example
+     * ```typescript
+     * // Call Core_version on current finalized block
+     * const version = await archive.call('Core_version', '0x');
+     *
+     * // Call Core_version on specific block
+     * const version = await archive.call('Core_version', '0x', '0x1234...');
+     * ```
+     */
+    async call(func, params, hash) {
+        const blockHash = hash || (await this.finalizedHash());
+        const cacheKey = `${blockHash}::call::${func}::${params}`;
+        const cached = this.#cache.get(cacheKey);
+        if (cached !== null) {
+            return cached;
+        }
+        const result = await this.send('call', blockHash, func, params);
+        if (!result.success) {
+            throw new DedotError(result.error);
+        }
+        this.#cache.set(cacheKey, result.value);
+        return result.value;
+    }
+    /**
+     * Returns storage entries at a specific block's state via subscription.
+     *
+     * @param items - Array of storage queries with optional pagination
+     * @param childTrie - Optional child trie key
+     * @param callback - Callback to receive storage events
+     * @param hash - The block hash (optional, defaults to current finalized block)
+     * @returns Unsubscribe function
+     */
+    async #storageSubscription(items, childTrie, callback, hash) {
+        const blockHash = hash || (await this.finalizedHash());
+        return this.send('storage', blockHash, items, childTrie, callback);
+    }
+    /**
+     * Returns storage entries at a specific block's state.
+     * This method collects all storage events and returns them as a single result.
+     *
+     * @param items - Array of storage queries with optional pagination
+     * @param childTrie - Optional child trie key
+     * @param hash - The block hash (optional, defaults to current finalized block)
+     * @returns Storage results array
+     *
+     * @example
+     * ```typescript
+     * // Query storage from current finalized block
+     * const results = await archive.storage([{ key: '0x1234', type: 'value' }]);
+     *
+     * // Query storage from specific block
+     * const results = await archive.storage([{ key: '0x1234', type: 'value' }], null, '0xabcd...');
+     * ```
+     */
+    async storage(items, childTrie, hash) {
+        return new Promise(async (resolve, reject) => {
+            const results = [];
+            const blockHash = hash || (await this.finalizedHash());
+            // Generate cache key
+            const cacheKey = `${blockHash}::storage::${JSON.stringify(items)}::${childTrie ?? null}`;
+            // Check cache
+            const cached = this.#cache.get(cacheKey);
+            if (cached !== null) {
+                return resolve(cached);
+            }
+            this.#storageSubscription(items, childTrie || null, (event) => {
+                switch (event.event) {
+                    case 'storage':
+                        results.push(event);
+                        break;
+                    case 'storageDone':
+                        // Set cache after successful completion
+                        this.#cache.set(cacheKey, results);
+                        resolve(results);
+                        break;
+                    case 'storageError':
+                        reject(new DedotError(event.error));
+                        break;
+                }
+            }, blockHash).catch(reject);
+        });
+    }
+    /**
+     * Clears the internal cache used for storing archive query results.
+     * This can be useful for memory management or when you want to force fresh data retrieval.
+     *
+     * @example
+     * ```typescript
+     * // Clear all cached results
+     * archive.clearCache();
+     * ```
+     */
+    clearCache() {
+        this.#cache.clear();
+    }
+}

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

@@ -2,6 +2,7 @@ import { BlockHash, Option } from '@dedot/codecs';
 import type { ChainHeadRuntimeVersion, OperationId, StorageQuery, StorageResult } from '@dedot/types/json-rpc';
 import { Deferred, HexString } from '@dedot/utils';
 import type { IJsonRpcClient } from '../../../types.js';
+import { Archive } from '../Archive.js';
 import { JsonRpcGroup, type JsonRpcGroupOptions } from '../JsonRpcGroup.js';
 export type OperationHandler<T = any> = {
     operationId: OperationId;
@@ -20,6 +21,15 @@ export declare const MIN_FINALIZED_QUEUE_SIZE = 10;
 export declare class ChainHead extends JsonRpcGroup<ChainHeadEvent> {
     #private;
     constructor(client: IJsonRpcClient, options?: Partial<JsonRpcGroupOptions>);
+    /**
+     * Attach an Archive instance as fallback for operations that fail due to unpinned blocks.
+     * When a ChainHeadBlockNotPinnedError occurs, the operation will automatically fallback
+     * to the Archive API to attempt to retrieve the data from historical blocks.
+     *
+     * @param archive - Archive instance to use as fallback
+     * @returns this ChainHead instance for method chaining
+     */
+    withArchive(archive: Archive): this;
     runtimeVersion(): Promise<ChainHeadRuntimeVersion>;
     bestRuntimeVersion(): Promise<ChainHeadRuntimeVersion>;
     finalizedHash(): Promise<BlockHash>;
@@ -67,4 +77,15 @@ export declare class ChainHead extends JsonRpcGroup<ChainHeadEvent> {
      * @protected
      */
     protected unpin(hashes: BlockHash | BlockHash[]): Promise<void>;
+    /**
+     * Clears the internal cache used for storing query results (both chainHead & archive instances)
+     * This can be useful for memory management or when you want to force fresh data retrieval.
+     *
+     * @example
+     * ```typescript
+     * // Clear all cached results
+     * chainHead.clearCache();
+     * ```
+     */
+    clearCache(): void;
 }