@dedot/api 0.15.2 → 0.16.0

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

@@ -7,6 +7,8 @@ const JsonRpcGroup_js_1 = require("../JsonRpcGroup.js");
 const BlockUsage_js_1 = require("./BlockUsage.js");
 const error_js_1 = require("./error.js");
 exports.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 {
     #unsub;
     #subscriptionId;
@@ -23,6 +25,17 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
     #blockUsage;
     #cache;
     #operationQueue;
+    /**
+     * Archive instance used as fallback when ChainHead blocks are not pinned.
+     *
+     * When ChainHead operations fail with ChainHeadBlockNotPinnedError, the system
+     * automatically attempts the same operation using the Archive API. This provides
+     * seamless access to historical blockchain data even when blocks are no longer
+     * maintained in the ChainHead's pinned block set.
+     *
+     * @private
+     */
+    #archive;
     constructor(client, options) {
         super(client, { prefix: 'chainHead', supportedVersions: ['unstable', 'v1'], ...options });
         this.#handlers = {};
@@ -32,10 +45,22 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
         this.#followResponseQueue = new utils_1.AsyncQueue();
         this.#retryQueue = new utils_1.AsyncQueue();
         this.#blockUsage = new BlockUsage_js_1.BlockUsage();
-        this.#cache = new Map();
+        this.#cache = new utils_1.LRUCache(CHAINHEAD_CACHE_CAPACITY, CHAINHEAD_CACHE_TTL);
         // This helps us to not accidentally putting too much stress on the JSON-RPC server, especially smoldot/light-client
         this.#operationQueue = new utils_1.ThrottleQueue(this.#__unsafe__isSmoldot() ? 25 : 250);
     }
+    /**
+     * 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) {
+        this.#archive = archive;
+        return this;
+    }
     async runtimeVersion() {
         await this.#ensureFollowed();
         return this.#finalizedRuntime;
@@ -222,8 +247,9 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
                     if (!this.isPinned(hash))
                         return;
                     delete this.#pinnedBlocks[hash];
-                    // clear cache
-                    Array.from(this.#cache.keys())
+                    // Clear cache entries related to the pruned block
+                    // Filter and remove only cache entries for this specific block
+                    this.#cache.keys()
                         .filter((key) => key.startsWith(`${hash}::`))
                         .forEach((key) => this.#cache.delete(key));
                 });
@@ -344,11 +370,38 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
                 return hash;
             }
             else {
-                throw new error_js_1.ChainHeadBlockNotPinnedError(`Block hash ${hash} is not pinned`);
+                throw new error_js_1.ChainHeadBlockNotPinnedError(`Block hash ${hash} is not pinned`, hash);
             }
         }
         return (0, utils_1.ensurePresence)(this.#bestHash || this.#finalizedHash);
     }
+    /**
+     * Executes a ChainHead operation with automatic Archive fallback.
+     *
+     * This method first attempts the primary ChainHead operation. If it fails with
+     * ChainHeadBlockNotPinnedError (indicating the block is no longer pinned), and
+     * an Archive instance is available, it automatically retries the operation using
+     * the Archive API.
+     *
+     * @param operation - Primary ChainHead operation to attempt
+     * @param fallback - Archive operation to fallback to
+     * @param hash - Block hash being accessed (for logging)
+     * @returns Result from either ChainHead or Archive operation
+     * @throws Original error if not a pinning error or no Archive available
+     * @private
+     */
+    async #tryWithArchive(operation, fallback) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (error instanceof error_js_1.ChainHeadBlockNotPinnedError && this.#archive) {
+                const errorHash = error.hash;
+                return await fallback(this.#archive, errorHash);
+            }
+            throw error;
+        }
+    }
     #getOperationHandler(result) {
         const handler = this.#handlers[result.operationId];
         if (handler)
@@ -403,7 +456,7 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
         this.#followResponseQueue.clear();
         this.#retryQueue.clear();
         this.#blockUsage.clear();
-        this.#cache.clear();
+        this.clearCache();
         this.#operationQueue.cancel();
     }
     async #ensureFollowed() {
@@ -478,21 +531,32 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
     async body(at) {
         await this.#ensureFollowed();
         const shouldRetryOnPrunedBlock = !at;
-        try {
+        const operation = async () => {
             const atHash = this.#ensurePinnedHash(at);
             const cacheKey = `${atHash}::body`;
-            if (this.#cache.has(cacheKey)) {
-                return this.#cache.get(cacheKey);
+            const cached = this.#cache.get(cacheKey);
+            if (cached) {
+                return cached;
             }
-            const operation = async () => {
+            const bodyOperation = async () => {
                 await this.#ensureFollowed();
                 const hash = this.#ensurePinnedHash(atHash);
                 const resp = await this.send('body', this.#subscriptionId, hash);
                 return this.#awaitOperation(resp, hash);
             };
-            const resp = await this.#operationQueue.add(() => this.#performOperationWithRetry(operation, atHash));
+            const resp = await this.#operationQueue.add(() => this.#performOperationWithRetry(bodyOperation, atHash));
             this.#cache.set(cacheKey, resp);
             return resp;
+        };
+        const fallback = async (archive, hash) => {
+            const result = await archive.body(hash);
+            if (result === undefined) {
+                throw new error_js_1.ChainHeadOperationError(`Block ${hash} not found in Archive`);
+            }
+            return result;
+        };
+        try {
+            return await this.#tryWithArchive(operation, fallback);
         }
         catch (e) {
             if (e instanceof error_js_1.ChainHeadBlockPrunedError && shouldRetryOnPrunedBlock) {
@@ -507,21 +571,26 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
     async call(func, params = '0x', at) {
         await this.#ensureFollowed();
         const shouldRetryOnPrunedBlock = !at;
-        try {
+        const operation = async () => {
             const atHash = this.#ensurePinnedHash(at);
             const cacheKey = `${atHash}::call::${func}::${params}`;
-            if (this.#cache.has(cacheKey)) {
-                return this.#cache.get(cacheKey);
+            const cached = this.#cache.get(cacheKey);
+            if (cached) {
+                return cached;
             }
-            const operation = async () => {
+            const callOperation = async () => {
                 await this.#ensureFollowed();
                 const hash = this.#ensurePinnedHash(atHash);
                 const resp = await this.send('call', this.#subscriptionId, hash, func, params);
                 return this.#awaitOperation(resp, hash);
             };
-            const resp = await this.#operationQueue.add(() => this.#performOperationWithRetry(operation, atHash));
+            const resp = await this.#operationQueue.add(() => this.#performOperationWithRetry(callOperation, atHash));
             this.#cache.set(cacheKey, resp);
             return resp;
+        };
+        const fallback = (archive, hash) => archive.call(func, params, hash);
+        try {
+            return await this.#tryWithArchive(operation, fallback);
         }
         catch (e) {
             if (e instanceof error_js_1.ChainHeadBlockPrunedError && shouldRetryOnPrunedBlock) {
@@ -535,14 +604,19 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
      */
     async header(at) {
         await this.#ensureFollowed();
-        const hash = this.#ensurePinnedHash(at);
-        const cacheKey = `${hash}::header`;
-        if (this.#cache.has(cacheKey)) {
-            return this.#cache.get(cacheKey);
-        }
-        const resp = await this.#getHeader(hash);
-        this.#cache.set(cacheKey, resp);
-        return resp;
+        const operation = async () => {
+            const hash = this.#ensurePinnedHash(at);
+            const cacheKey = `${hash}::header`;
+            const cached = this.#cache.get(cacheKey);
+            if (cached) {
+                return cached;
+            }
+            const resp = await this.#getHeader(hash);
+            this.#cache.set(cacheKey, resp);
+            return resp;
+        };
+        const fallback = (archive, errorHash) => archive.header(errorHash);
+        return await this.#tryWithArchive(operation, fallback);
     }
     async #getHeader(at) {
         return await this.send('header', this.#subscriptionId, at);
@@ -553,35 +627,47 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
     async storage(items, childTrie, at) {
         await this.#ensureFollowed();
         const shouldRetryOnPrunedBlock = !at;
-        const hash = this.#ensurePinnedHash(at);
-        try {
-            // JSON.stringify(items) might get big, we probably should do a twox hashing in such case
-            const cacheKey = `${hash}::storage::${JSON.stringify(items)}::${childTrie ?? null}`;
-            if (this.#cache.has(cacheKey)) {
-                return this.#cache.get(cacheKey);
-            }
-            this.#blockUsage.use(hash);
-            let results = [];
-            if (this.#__unsafe__isSmoldot()) {
-                const fetchItem = async (item) => {
-                    const [batch, newDiscardedItems] = await this.#getStorage([item], childTrie ?? null, hash);
-                    if (newDiscardedItems.length > 0) {
-                        return fetchItem(item);
+        const operation = async () => {
+            const hash = this.#ensurePinnedHash(at);
+            try {
+                // JSON.stringify(items) might get big, we probably should do a twox hashing in such case
+                const cacheKey = `${hash}::storage::${JSON.stringify(items)}::${childTrie ?? null}`;
+                const cached = this.#cache.get(cacheKey);
+                if (cached) {
+                    return cached;
+                }
+                this.#blockUsage.use(hash);
+                let results = [];
+                if (this.#__unsafe__isSmoldot()) {
+                    const fetchItem = async (item) => {
+                        const [batch, newDiscardedItems] = await this.#getStorage([item], childTrie ?? null, hash);
+                        if (newDiscardedItems.length > 0) {
+                            return fetchItem(item);
+                        }
+                        return batch;
+                    };
+                    results = (await Promise.all(items.map((one) => fetchItem(one)))).flat();
+                }
+                else {
+                    let queryItems = items;
+                    while (queryItems.length > 0) {
+                        const [newBatch, newDiscardedItems] = await this.#getStorage(queryItems, childTrie ?? null, hash);
+                        results.push(...newBatch);
+                        queryItems = newDiscardedItems;
                     }
-                    return batch;
-                };
-                results = (await Promise.all(items.map((one) => fetchItem(one)))).flat();
-            }
-            else {
-                let queryItems = items;
-                while (queryItems.length > 0) {
-                    const [newBatch, newDiscardedItems] = await this.#getStorage(queryItems, childTrie ?? null, hash);
-                    results.push(...newBatch);
-                    queryItems = newDiscardedItems;
                 }
+                this.#cache.set(cacheKey, results);
+                return results;
+            }
+            finally {
+                this.#blockUsage.release(hash);
             }
-            this.#cache.set(cacheKey, results);
-            return results;
+        };
+        const fallback = (archive, hash) => {
+            return archive.storage(items, childTrie, hash);
+        };
+        try {
+            return await this.#tryWithArchive(operation, fallback);
         }
         catch (e) {
             if (e instanceof error_js_1.ChainHeadBlockPrunedError && shouldRetryOnPrunedBlock) {
@@ -589,9 +675,6 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
             }
             throw e;
         }
-        finally {
-            this.#blockUsage.release(hash);
-        }
     }
     async #getStorage(items, childTrie, at) {
         const operation = () => this.#getStorageOperation(items, childTrie, this.#ensurePinnedHash(at));
@@ -636,5 +719,19 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
         // @ts-ignore  a trick internally to check whether a provider is using smoldot connection
         return typeof this.client.provider['chain'] === 'function';
     }
+    /**
+     * 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() {
+        this.#cache.clear();
+        this.#archive?.clearCache();
+    }
 }
 exports.ChainHead = ChainHead;

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

@@ -59,6 +59,11 @@ class ChainHeadInvalidRuntimeError extends ChainHeadError {
 exports.ChainHeadInvalidRuntimeError = ChainHeadInvalidRuntimeError;
 class ChainHeadBlockNotPinnedError extends ChainHeadError {
     name = 'ChainHeadBlockNotPinnedError';
+    hash;
+    constructor(message, hash) {
+        super(message);
+        this.hash = hash;
+    }
 }
 exports.ChainHeadBlockNotPinnedError = ChainHeadBlockNotPinnedError;
 class ChainHeadBlockPrunedError extends ChainHeadError {

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

@@ -15,6 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./JsonRpcGroup.js"), exports);
+__exportStar(require("./Archive.js"), exports);
 __exportStar(require("./ChainSpec.js"), exports);
 __exportStar(require("./Transaction.js"), exports);
 __exportStar(require("./TransactionWatch.js"), exports);

package/cjs/json-rpc/subscriptionsInfo.js

@@ -17,4 +17,8 @@ exports.subscriptionsInfo = {
         'transactionWatch_unstable_unwatch',
     ],
     transactionWatch_v1_submitAndWatch: ['transactionWatch_v1_watchEvent', 'transactionWatch_v1_unwatch'],
+    archive_v1_storage: ['archive_v1_storageEvent', 'archive_v1_stopStorage'],
+    archive_v1_storageDiff: ['archive_v1_storageDiffEvent', 'archive_v1_stopStorageDiff'],
+    archive_unstable_storage: ['archive_unstable_storageEvent', 'archive_unstable_stopStorage'],
+    archive_unstable_storageDiff: ['archive_unstable_storageDiffEvent', 'archive_unstable_stopStorageDiff'],
 };

package/cjs/storage/LegacyStorageQuery.js

@@ -15,6 +15,11 @@ const BaseStorageQuery_js_1 = require("./BaseStorageQuery.js");
  * - Efficient change tracking for subscriptions
  */
 class LegacyStorageQuery extends BaseStorageQuery_js_1.BaseStorageQuery {
+    client;
+    constructor(client) {
+        super(client);
+        this.client = client;
+    }
     /**
      * Query multiple storage items in a single call using state_queryStorageAt
      *

package/cjs/storage/NewStorageQuery.js

@@ -16,6 +16,11 @@ const BaseStorageQuery_js_1 = require("./BaseStorageQuery.js");
  * - Efficient change detection for subscriptions
  */
 class NewStorageQuery extends BaseStorageQuery_js_1.BaseStorageQuery {
+    client;
+    constructor(client) {
+        super(client);
+        this.client = client;
+    }
     /**
      * Query multiple storage items in a single call using chainHead_storage
      *

package/client/BaseSubstrateClient.d.ts

@@ -2,7 +2,7 @@ import { BlockHash, Hash, Metadata, PortableRegistry, RuntimeVersion } from '@de
 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 } from '@dedot/utils';
+import { Deferred, LRUCache } from '@dedot/utils';
 import type { SubstrateApi } from '../chaintypes/index.js';
 import { JsonRpcClient } from '../json-rpc/index.js';
 import { BaseStorageQuery } from '../storage/index.js';
@@ -15,12 +15,13 @@ export declare function ensurePresence<T>(value: T): NonNullable<T>;
 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> {
     rpcVersion: RpcVersion;
     protected _options: ApiOptions;
-    protected _registry?: PortableRegistry;
+    protected _registry?: PortableRegistry<ChainApi[Rv]>;
     protected _metadata?: Metadata;
     protected _genesisHash?: Hash;
     protected _runtimeVersion?: SubstrateRuntimeVersion;
     protected _localCache?: IStorage;
     protected _runtimeUpgrading?: Deferred<void>;
+    protected _apiAtCache: LRUCache;
     protected constructor(rpcVersion: RpcVersion, options: JsonRpcClientOptions | JsonRpcProvider);
     protected normalizeOptions(options: ApiOptions | JsonRpcProvider): ApiOptions;
     protected initializeLocalCache(): Promise<void>;
@@ -37,9 +38,10 @@ export declare abstract class BaseSubstrateClient<Rv extends RpcVersion, ChainAp
     protected fetchMetadata(hash?: BlockHash, runtime?: SubstrateRuntimeVersion): Promise<Metadata>;
     protected cleanUp(): void;
     /**
-     * @description Clear local cache
+     * @description Clear local cache and API at-block cache
+     * @param keepMetadataCache Keep the metadata cache, only clear other caches.
      */
-    clearCache(): Promise<void>;
+    clearCache(keepMetadataCache?: boolean): Promise<void>;
     protected doConnect(): Promise<this>;
     protected onConnected: () => Promise<void>;
     protected onDisconnected: () => Promise<void>;
@@ -61,7 +63,7 @@ export declare abstract class BaseSubstrateClient<Rv extends RpcVersion, ChainAp
     disconnect(): Promise<void>;
     get options(): ApiOptions;
     get metadata(): Metadata;
-    get registry(): PortableRegistry;
+    get registry(): PortableRegistry<ChainApi[Rv]>;
     get genesisHash(): Hash;
     get runtimeVersion(): SubstrateRuntimeVersion;
     getRuntimeVersion(): Promise<SubstrateRuntimeVersion>;
@@ -106,5 +108,5 @@ export declare abstract class BaseSubstrateClient<Rv extends RpcVersion, ChainAp
     }, callback: Callback<{
         [K in keyof Fns]: QueryFnResult<Fns[K]>;
     }>): Promise<Unsub>;
-    protected getStorageQuery(): BaseStorageQuery<RpcVersion>;
+    protected getStorageQuery(): BaseStorageQuery;
 }

package/client/BaseSubstrateClient.js

@@ -1,12 +1,14 @@
 import { $Metadata, PortableRegistry } from '@dedot/codecs';
 import { LocalStorage } from '@dedot/storage';
-import { calcRuntimeApiHash, deferred, ensurePresence as _ensurePresence, u8aToHex } from '@dedot/utils';
+import { calcRuntimeApiHash, deferred, ensurePresence as _ensurePresence, u8aToHex, LRUCache, } from '@dedot/utils';
 import { ConstantExecutor, ErrorExecutor, EventExecutor } from '../executor/index.js';
 import { isJsonRpcProvider, JsonRpcClient } from '../json-rpc/index.js';
 import { newProxyChain } from '../proxychain.js';
 import { QueryableStorage } from '../storage/index.js';
 const SUPPORTED_METADATA_VERSIONS = [16, 15, 14];
 const MetadataApiHash = calcRuntimeApiHash('Metadata'); // 0x37e397fc7c91f5e4
+const API_AT_CACHE_CAPACITY = 64;
+const API_AT_CACHE_TTL = 300_000; // 5 minutes
 const MESSAGE = 'Make sure to call `.connect()` method first before using the API interfaces.';
 export function ensurePresence(value) {
     return _ensurePresence(value, MESSAGE);
@@ -24,10 +26,12 @@ export class BaseSubstrateClient extends JsonRpcClient {
     _runtimeVersion;
     _localCache;
     _runtimeUpgrading;
+    _apiAtCache;
     constructor(rpcVersion, options) {
         super(options);
         this.rpcVersion = rpcVersion;
         this._options = this.normalizeOptions(options);
+        this._apiAtCache = new LRUCache(API_AT_CACHE_CAPACITY, API_AT_CACHE_TTL);
     }
     /// --- Internal logics
     normalizeOptions(options) {
@@ -185,12 +189,17 @@ export class BaseSubstrateClient extends JsonRpcClient {
         this._genesisHash = undefined;
         this._runtimeVersion = undefined;
         this._localCache = undefined;
+        this._apiAtCache.clear();
     }
     /**
-     * @description Clear local cache
+     * @description Clear local cache and API at-block cache
+     * @param keepMetadataCache Keep the metadata cache, only clear other caches.
      */
-    async clearCache() {
-        await this._localCache?.clear();
+    async clearCache(keepMetadataCache = false) {
+        if (!keepMetadataCache) {
+            await this._localCache?.clear();
+        }
+        this._apiAtCache.clear();
     }
     async doConnect() {
         // @ts-ignore

package/client/DedotClient.d.ts

@@ -1,8 +1,8 @@
 import { BlockHash } from '@dedot/codecs';
 import type { JsonRpcProvider } from '@dedot/providers';
-import { GenericSubstrateApi, RpcV2, RpcVersion, VersionedGenericSubstrateApi } from '@dedot/types';
+import { GenericSubstrateApi, RpcV2, VersionedGenericSubstrateApi } from '@dedot/types';
 import type { SubstrateApi } from '../chaintypes/index.js';
-import { ChainHead, ChainSpec, PinnedBlock } from '../json-rpc/index.js';
+import { Archive, ChainHead, ChainSpec, PinnedBlock } from '../json-rpc/index.js';
 import { BaseStorageQuery } from '../storage/index.js';
 import type { ApiOptions, DedotClientEvent, ISubstrateClientAt, TxBroadcaster } from '../types.js';
 import { BaseSubstrateClient } from './BaseSubstrateClient.js';
@@ -17,6 +17,7 @@ export declare class DedotClient<ChainApi extends VersionedGenericSubstrateApi =
     #private;
     protected _chainHead?: ChainHead;
     protected _chainSpec?: ChainSpec;
+    protected _archive?: Archive;
     protected _txBroadcaster?: TxBroadcaster;
     /**
      * Use factory methods (`create`, `new`) to create `DedotClient` instances.
@@ -38,6 +39,7 @@ export declare class DedotClient<ChainApi extends VersionedGenericSubstrateApi =
     static new<ChainApi extends VersionedGenericSubstrateApi = SubstrateApi>(options: ApiOptions | JsonRpcProvider): Promise<DedotClient<ChainApi>>;
     get chainSpec(): ChainSpec;
     get chainHead(): ChainHead;
+    archive(): Promise<Archive>;
     get txBroadcaster(): TxBroadcaster;
     /**
      * Initialize APIs before usage
@@ -48,6 +50,11 @@ export declare class DedotClient<ChainApi extends VersionedGenericSubstrateApi =
     protected beforeDisconnect(): Promise<void>;
     protected onDisconnected: () => Promise<void>;
     protected cleanUp(): void;
+    /**
+     * @description Clear local cache, API at-block cache, and ChainHead cache
+     * @param keepMetadataCache Keep the metadata cache, only clear other caches.
+     */
+    clearCache(keepMetadataCache?: boolean): Promise<void>;
     get query(): ChainApi[RpcV2]['query'];
     get view(): ChainApi[RpcV2]['view'];
     get call(): ChainApi[RpcV2]['call'];
@@ -55,10 +62,10 @@ export declare class DedotClient<ChainApi extends VersionedGenericSubstrateApi =
     get tx(): ChainApi[RpcV2]['tx'];
     /**
      * Get a new API instance at a specific block hash
-     * For now, this only supports pinned block hashes from the chain head
+     * Supports both pinned blocks (via ChainHead) and historical blocks (via Archive fallback)
      *
      * @param hash
      */
     at<ChainApiAt extends GenericSubstrateApi = ChainApi[RpcV2]>(hash: BlockHash): Promise<ISubstrateClientAt<ChainApiAt>>;
-    protected getStorageQuery(): BaseStorageQuery<RpcVersion>;
+    protected getStorageQuery(): BaseStorageQuery;
 }

package/client/DedotClient.js

@@ -1,8 +1,8 @@
-import { $H256, PortableRegistry } from '@dedot/codecs';
+import { $H256, $RuntimeVersion, PortableRegistry } from '@dedot/codecs';
 import { u32 } from '@dedot/shape';
-import { assert, concatU8a, noop, twox64Concat, u8aToHex, xxhashAsU8a } from '@dedot/utils';
+import { assert, concatU8a, noop, twox64Concat, u8aToHex, xxhashAsU8a, DedotError } from '@dedot/utils';
 import { ConstantExecutor, ErrorExecutor, EventExecutor, RuntimeApiExecutorV2, StorageQueryExecutorV2, ViewFunctionExecutorV2, TxExecutorV2, } from '../executor/index.js';
-import { ChainHead, ChainSpec, Transaction, TransactionWatch } from '../json-rpc/index.js';
+import { Archive, ChainHead, ChainSpec, Transaction, TransactionWatch } from '../json-rpc/index.js';
 import { newProxyChain } from '../proxychain.js';
 import { NewStorageQuery } from '../storage/index.js';
 import { BaseSubstrateClient, ensurePresence } from './BaseSubstrateClient.js';
@@ -16,8 +16,8 @@ export class DedotClient// prettier-end-here
  extends BaseSubstrateClient {
     _chainHead;
     _chainSpec;
+    _archive;
     _txBroadcaster;
-    #apiAtCache = {};
     /**
      * Use factory methods (`create`, `new`) to create `DedotClient` instances.
      *
@@ -48,6 +48,11 @@ export class DedotClient// prettier-end-here
     get chainHead() {
         return ensurePresence(this._chainHead);
     }
+    async archive() {
+        assert(this._archive, 'Archive instance is not initialized');
+        assert(await this._archive.supported(), 'Archive JSON-RPC is not supported by the connected server');
+        return this._archive;
+    }
     get txBroadcaster() {
         this.chainHead; // Ensure chain head is initialized
         assert(this._txBroadcaster, 'JSON-RPC method to broadcast transactions is not supported by the server/node.');
@@ -68,6 +73,12 @@ export class DedotClient// prettier-end-here
         const rpcMethods = (await this.rpc.rpc_methods()).methods;
         this._chainHead = new ChainHead(this, { rpcMethods });
         this._chainSpec = new ChainSpec(this, { rpcMethods });
+        // Always initialize Archive, but only set up fallback if supported
+        this._archive = new Archive(this, { rpcMethods });
+        // Set up ChainHead with Archive fallback only if Archive is supported
+        if (await this._archive.supported()) {
+            this._chainHead.withArchive(this._archive);
+        }
         this._txBroadcaster = await this.#initializeTxBroadcaster(rpcMethods);
         // Fetching node information
         let [_, genesisHash] = await Promise.all([
@@ -130,8 +141,16 @@ export class DedotClient// prettier-end-here
         super.cleanUp();
         this._chainHead = undefined;
         this._chainSpec = undefined;
+        this._archive = undefined;
         this._txBroadcaster = undefined;
-        this.#apiAtCache = {};
+    }
+    /**
+     * @description Clear local cache, API at-block cache, and ChainHead cache
+     * @param keepMetadataCache Keep the metadata cache, only clear other caches.
+     */
+    async clearCache(keepMetadataCache = false) {
+        await super.clearCache(keepMetadataCache);
+        this._chainHead?.clearCache();
     }
     get query() {
         return newProxyChain({
@@ -156,19 +175,40 @@ export class DedotClient// prettier-end-here
     }
     /**
      * Get a new API instance at a specific block hash
-     * For now, this only supports pinned block hashes from the chain head
+     * Supports both pinned blocks (via ChainHead) and historical blocks (via Archive fallback)
      *
      * @param hash
      */
     async at(hash) {
-        if (this.#apiAtCache[hash])
-            return this.#apiAtCache[hash];
+        const cached = this._apiAtCache.get(hash);
+        if (cached)
+            return cached;
+        let targetVersion;
+        // Try to get block info from ChainHead first (for pinned blocks)
         const targetBlock = this.chainHead.findBlock(hash);
-        assert(targetBlock, 'Block is not pinned!');
-        let 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 (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());
+            }
+        }
+        else {
+            // Block not pinned, try via Archive fallback if supported
+            if (this._archive && (await this._archive.supported())) {
+                try {
+                    // Fetch runtime version via Archive
+                    const runtimeRaw = await this._archive.call('Core_version', '0x', hash);
+                    assert(runtimeRaw, 'Runtime Version Not Found');
+                    targetVersion = this.toSubstrateRuntimeVersion($RuntimeVersion.tryDecode(runtimeRaw));
+                }
+                catch (error) {
+                    throw new DedotError(`Unable to fetch runtime version for block ${hash}: ${error}`);
+                }
+            }
+            else {
+                throw new DedotError('Block is not pinned and Archive JSON-RPC is not supported by the server/node!');
+            }
         }
         let metadata = this.metadata;
         let registry = this.registry;
@@ -192,7 +232,7 @@ 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) });
-        this.#apiAtCache[hash] = api;
+        this._apiAtCache.set(hash, api);
         return api;
     }
     getStorageQuery() {

package/client/LegacyClient.d.ts

@@ -1,6 +1,6 @@
 import { BlockHash } from '@dedot/codecs';
 import type { JsonRpcProvider } from '@dedot/providers';
-import { GenericSubstrateApi, RpcLegacy, RpcVersion, VersionedGenericSubstrateApi } from '@dedot/types';
+import { GenericSubstrateApi, RpcLegacy, VersionedGenericSubstrateApi } from '@dedot/types';
 import type { SubstrateApi } from '../chaintypes/index.js';
 import { BaseStorageQuery } from '../storage/index.js';
 import type { ApiOptions, ISubstrateClientAt } from '../types.js';
@@ -131,5 +131,5 @@ export declare class LegacyClient<ChainApi extends VersionedGenericSubstrateApi
      * @param hash
      */
     at<ChainApiAt extends GenericSubstrateApi = ChainApi[RpcLegacy]>(hash: BlockHash): Promise<ISubstrateClientAt<ChainApiAt>>;
-    protected getStorageQuery(): BaseStorageQuery<RpcVersion>;
+    protected getStorageQuery(): BaseStorageQuery;
 }