@dedot/api 0.15.3-next.65898ecf.10 → 0.16.0

package/chaintypes/substrate/index.js

@@ -1 +1,2 @@
+// Generated by dedot cli
 export * from './types.js';

package/cjs/chaintypes/substrate/index.js

@@ -1,4 +1,5 @@
 "use strict";
+// Generated by dedot cli
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);

package/cjs/client/BaseSubstrateClient.js

@@ -10,6 +10,8 @@ const proxychain_js_1 = require("../proxychain.js");
 const index_js_3 = require("../storage/index.js");
 const SUPPORTED_METADATA_VERSIONS = [16, 15, 14];
 const MetadataApiHash = (0, utils_1.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.';
 function ensurePresence(value) {
     return (0, utils_1.ensurePresence)(value, MESSAGE);
@@ -28,10 +30,12 @@ class BaseSubstrateClient extends index_js_2.JsonRpcClient {
     _runtimeVersion;
     _localCache;
     _runtimeUpgrading;
+    _apiAtCache;
     constructor(rpcVersion, options) {
         super(options);
         this.rpcVersion = rpcVersion;
         this._options = this.normalizeOptions(options);
+        this._apiAtCache = new utils_1.LRUCache(API_AT_CACHE_CAPACITY, API_AT_CACHE_TTL);
     }
     /// --- Internal logics
     normalizeOptions(options) {
@@ -189,12 +193,17 @@ class BaseSubstrateClient extends index_js_2.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/cjs/client/DedotClient.js

@@ -21,7 +21,6 @@ class DedotClient// prettier-end-here
     _chainSpec;
     _archive;
     _txBroadcaster;
-    #apiAtCache = {};
     /**
      * Use factory methods (`create`, `new`) to create `DedotClient` instances.
      *
@@ -147,7 +146,14 @@ class DedotClient// prettier-end-here
         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 (0, proxychain_js_1.newProxyChain)({
@@ -177,8 +183,9 @@ class DedotClient// 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;
         let targetVersion;
         // Try to get block info from ChainHead first (for pinned blocks)
         const targetBlock = this.chainHead.findBlock(hash);
@@ -192,10 +199,10 @@ class DedotClient// prettier-end-here
         else {
             // Block not pinned, try via Archive fallback if supported
             if (this._archive && (await this._archive.supported())) {
-                console.warn(`Block ${hash} is not pinned, using Archive for historical access`);
                 try {
                     // Fetch runtime version via Archive
                     const runtimeRaw = await this._archive.call('Core_version', '0x', hash);
+                    (0, utils_1.assert)(runtimeRaw, 'Runtime Version Not Found');
                     targetVersion = this.toSubstrateRuntimeVersion(codecs_1.$RuntimeVersion.tryDecode(runtimeRaw));
                 }
                 catch (error) {
@@ -228,7 +235,7 @@ 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) });
-        this.#apiAtCache[hash] = api;
+        this._apiAtCache.set(hash, api);
         return api;
     }
     getStorageQuery() {

package/cjs/client/LegacyClient.js

@@ -49,7 +49,6 @@ class LegacyClient// prettier-end-here
  extends BaseSubstrateClient_js_1.BaseSubstrateClient {
     #runtimeSubscriptionUnsub;
     #healthTimer;
-    #apiAtCache = {};
     /**
      * Use factory methods (`create`, `new`) to create `Dedot` instances.
      *
@@ -96,7 +95,6 @@ class LegacyClient// prettier-end-here
     }
     cleanUp() {
         super.cleanUp();
-        this.#apiAtCache = {};
         this.#healthTimer = undefined;
         this.#runtimeSubscriptionUnsub = undefined;
     }
@@ -232,8 +230,9 @@ 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;
@@ -256,7 +255,7 @@ 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) });
-        this.#apiAtCache[hash] = api;
+        this._apiAtCache.set(hash, api);
         return api;
     }
     getStorageQuery() {

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

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Archive = void 0;
 const utils_1 = require("@dedot/utils");
 const JsonRpcGroup_js_1 = require("./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.
@@ -16,7 +18,7 @@ class Archive extends JsonRpcGroup_js_1.JsonRpcGroup {
     #cache;
     constructor(client, options) {
         super(client, { prefix: 'archive', supportedVersions: ['unstable', 'v1'], ...options });
-        this.#cache = new Map();
+        this.#cache = new utils_1.LRUCache(ARCHIVE_CACHE_CAPACITY, ARCHIVE_CACHE_TTL);
     }
     /**
      * Retrieves the body (list of transactions) of a given block.
@@ -38,8 +40,9 @@ class Archive extends JsonRpcGroup_js_1.JsonRpcGroup {
     async body(hash) {
         const blockHash = hash || (await this.finalizedHash());
         const cacheKey = `${blockHash}::body`;
-        if (this.#cache.has(cacheKey)) {
-            return this.#cache.get(cacheKey);
+        const cached = this.#cache.get(cacheKey);
+        if (cached !== null) {
+            return cached;
         }
         const result = await this.send('body', blockHash);
         this.#cache.set(cacheKey, result);
@@ -77,8 +80,9 @@ class Archive extends JsonRpcGroup_js_1.JsonRpcGroup {
     async header(hash) {
         const blockHash = hash || (await this.finalizedHash());
         const cacheKey = `${blockHash}::header`;
-        if (this.#cache.has(cacheKey)) {
-            return this.#cache.get(cacheKey);
+        const cached = this.#cache.get(cacheKey);
+        if (cached !== null) {
+            return cached;
         }
         const result = await this.send('header', blockHash);
         this.#cache.set(cacheKey, result);
@@ -141,8 +145,9 @@ class Archive extends JsonRpcGroup_js_1.JsonRpcGroup {
     async call(func, params, hash) {
         const blockHash = hash || (await this.finalizedHash());
         const cacheKey = `${blockHash}::call::${func}::${params}`;
-        if (this.#cache.has(cacheKey)) {
-            return this.#cache.get(cacheKey);
+        const cached = this.#cache.get(cacheKey);
+        if (cached !== null) {
+            return cached;
         }
         const result = await this.send('call', blockHash, func, params);
         if (!result.success) {
@@ -189,8 +194,9 @@ class Archive extends JsonRpcGroup_js_1.JsonRpcGroup {
             // Generate cache key
             const cacheKey = `${blockHash}::storage::${JSON.stringify(items)}::${childTrie ?? null}`;
             // Check cache
-            if (this.#cache.has(cacheKey)) {
-                return resolve(this.#cache.get(cacheKey));
+            const cached = this.#cache.get(cacheKey);
+            if (cached !== null) {
+                return resolve(cached);
             }
             this.#storageSubscription(items, childTrie || null, (event) => {
                 switch (event.event) {

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;
@@ -43,7 +45,7 @@ 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);
     }
@@ -245,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));
                 });
@@ -394,7 +397,6 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
         catch (error) {
             if (error instanceof error_js_1.ChainHeadBlockNotPinnedError && this.#archive) {
                 const errorHash = error.hash;
-                console.warn(`Block ${errorHash} not pinned in ChainHead, falling back to Archive`);
                 return await fallback(this.#archive, errorHash);
             }
             throw error;
@@ -454,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() {
@@ -532,8 +534,9 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
         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 bodyOperation = async () => {
                 await this.#ensureFollowed();
@@ -571,8 +574,9 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
         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 callOperation = async () => {
                 await this.#ensureFollowed();
@@ -603,8 +607,9 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
         const operation = async () => {
             const hash = this.#ensurePinnedHash(at);
             const cacheKey = `${hash}::header`;
-            if (this.#cache.has(cacheKey)) {
-                return this.#cache.get(cacheKey);
+            const cached = this.#cache.get(cacheKey);
+            if (cached) {
+                return cached;
             }
             const resp = await this.#getHeader(hash);
             this.#cache.set(cacheKey, resp);
@@ -627,8 +632,9 @@ class ChainHead extends JsonRpcGroup_js_1.JsonRpcGroup {
             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);
+                const cached = this.#cache.get(cacheKey);
+                if (cached) {
+                    return cached;
                 }
                 this.#blockUsage.use(hash);
                 let results = [];
@@ -713,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/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';
@@ -21,6 +21,7 @@ export declare abstract class BaseSubstrateClient<Rv extends RpcVersion, ChainAp
     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>;

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

@@ -50,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'];

package/client/DedotClient.js

@@ -18,7 +18,6 @@ export class DedotClient// prettier-end-here
     _chainSpec;
     _archive;
     _txBroadcaster;
-    #apiAtCache = {};
     /**
      * Use factory methods (`create`, `new`) to create `DedotClient` instances.
      *
@@ -144,7 +143,14 @@ export class DedotClient// prettier-end-here
         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({
@@ -174,8 +180,9 @@ export class DedotClient// 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;
         let targetVersion;
         // Try to get block info from ChainHead first (for pinned blocks)
         const targetBlock = this.chainHead.findBlock(hash);
@@ -189,10 +196,10 @@ export class DedotClient// prettier-end-here
         else {
             // Block not pinned, try via Archive fallback if supported
             if (this._archive && (await this._archive.supported())) {
-                console.warn(`Block ${hash} is not pinned, using Archive for historical access`);
                 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) {
@@ -225,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.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/json-rpc/group/Archive.js

@@ -1,5 +1,7 @@
-import { DedotError } from '@dedot/utils';
+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.
@@ -13,7 +15,7 @@ export class Archive extends JsonRpcGroup {
     #cache;
     constructor(client, options) {
         super(client, { prefix: 'archive', supportedVersions: ['unstable', 'v1'], ...options });
-        this.#cache = new Map();
+        this.#cache = new LRUCache(ARCHIVE_CACHE_CAPACITY, ARCHIVE_CACHE_TTL);
     }
     /**
      * Retrieves the body (list of transactions) of a given block.
@@ -35,8 +37,9 @@ export class Archive extends JsonRpcGroup {
     async body(hash) {
         const blockHash = hash || (await this.finalizedHash());
         const cacheKey = `${blockHash}::body`;
-        if (this.#cache.has(cacheKey)) {
-            return this.#cache.get(cacheKey);
+        const cached = this.#cache.get(cacheKey);
+        if (cached !== null) {
+            return cached;
         }
         const result = await this.send('body', blockHash);
         this.#cache.set(cacheKey, result);
@@ -74,8 +77,9 @@ export class Archive extends JsonRpcGroup {
     async header(hash) {
         const blockHash = hash || (await this.finalizedHash());
         const cacheKey = `${blockHash}::header`;
-        if (this.#cache.has(cacheKey)) {
-            return this.#cache.get(cacheKey);
+        const cached = this.#cache.get(cacheKey);
+        if (cached !== null) {
+            return cached;
         }
         const result = await this.send('header', blockHash);
         this.#cache.set(cacheKey, result);
@@ -138,8 +142,9 @@ export class Archive extends JsonRpcGroup {
     async call(func, params, hash) {
         const blockHash = hash || (await this.finalizedHash());
         const cacheKey = `${blockHash}::call::${func}::${params}`;
-        if (this.#cache.has(cacheKey)) {
-            return this.#cache.get(cacheKey);
+        const cached = this.#cache.get(cacheKey);
+        if (cached !== null) {
+            return cached;
         }
         const result = await this.send('call', blockHash, func, params);
         if (!result.success) {
@@ -186,8 +191,9 @@ export class Archive extends JsonRpcGroup {
             // Generate cache key
             const cacheKey = `${blockHash}::storage::${JSON.stringify(items)}::${childTrie ?? null}`;
             // Check cache
-            if (this.#cache.has(cacheKey)) {
-                return resolve(this.#cache.get(cacheKey));
+            const cached = this.#cache.get(cacheKey);
+            if (cached !== null) {
+                return resolve(cached);
             }
             this.#storageSubscription(items, childTrie || null, (event) => {
                 switch (event.event) {

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

@@ -77,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;
 }

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

@@ -1,9 +1,11 @@
 import { $Header } from '@dedot/codecs';
-import { assert, AsyncQueue, deferred, ensurePresence, noop, ThrottleQueue, waitFor, } from '@dedot/utils';
+import { assert, AsyncQueue, deferred, ensurePresence, noop, ThrottleQueue, waitFor, LRUCache, } from '@dedot/utils';
 import { JsonRpcGroup } from '../JsonRpcGroup.js';
 import { BlockUsage } from './BlockUsage.js';
 import { ChainHeadBlockNotPinnedError, ChainHeadBlockPrunedError, ChainHeadError, ChainHeadLimitReachedError, ChainHeadOperationError, ChainHeadOperationInaccessibleError, ChainHeadStopError, RetryStrategy, } from './error.js';
 export 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 {
     #unsub;
     #subscriptionId;
@@ -40,7 +42,7 @@ export class ChainHead extends JsonRpcGroup {
         this.#followResponseQueue = new AsyncQueue();
         this.#retryQueue = new AsyncQueue();
         this.#blockUsage = new BlockUsage();
-        this.#cache = new Map();
+        this.#cache = new 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 ThrottleQueue(this.#__unsafe__isSmoldot() ? 25 : 250);
     }
@@ -242,8 +244,9 @@ export class ChainHead extends 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));
                 });
@@ -391,7 +394,6 @@ export class ChainHead extends JsonRpcGroup {
         catch (error) {
             if (error instanceof ChainHeadBlockNotPinnedError && this.#archive) {
                 const errorHash = error.hash;
-                console.warn(`Block ${errorHash} not pinned in ChainHead, falling back to Archive`);
                 return await fallback(this.#archive, errorHash);
             }
             throw error;
@@ -451,7 +453,7 @@ export class ChainHead extends JsonRpcGroup {
         this.#followResponseQueue.clear();
         this.#retryQueue.clear();
         this.#blockUsage.clear();
-        this.#cache.clear();
+        this.clearCache();
         this.#operationQueue.cancel();
     }
     async #ensureFollowed() {
@@ -529,8 +531,9 @@ export class ChainHead extends JsonRpcGroup {
         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 bodyOperation = async () => {
                 await this.#ensureFollowed();
@@ -568,8 +571,9 @@ export class ChainHead extends JsonRpcGroup {
         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 callOperation = async () => {
                 await this.#ensureFollowed();
@@ -600,8 +604,9 @@ export class ChainHead extends JsonRpcGroup {
         const operation = async () => {
             const hash = this.#ensurePinnedHash(at);
             const cacheKey = `${hash}::header`;
-            if (this.#cache.has(cacheKey)) {
-                return this.#cache.get(cacheKey);
+            const cached = this.#cache.get(cacheKey);
+            if (cached) {
+                return cached;
             }
             const resp = await this.#getHeader(hash);
             this.#cache.set(cacheKey, resp);
@@ -624,8 +629,9 @@ export class ChainHead extends JsonRpcGroup {
             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);
+                const cached = this.#cache.get(cacheKey);
+                if (cached) {
+                    return cached;
                 }
                 this.#blockUsage.use(hash);
                 let results = [];
@@ -710,4 +716,18 @@ export class ChainHead extends 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();
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dedot/api",
-  "version": "0.15.3-next.65898ecf.10+65898ecf",
+  "version": "0.16.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.15.3-next.65898ecf.10+65898ecf",
-    "@dedot/providers": "0.15.3-next.65898ecf.10+65898ecf",
-    "@dedot/runtime-specs": "0.15.3-next.65898ecf.10+65898ecf",
-    "@dedot/shape": "0.15.3-next.65898ecf.10+65898ecf",
-    "@dedot/storage": "0.15.3-next.65898ecf.10+65898ecf",
-    "@dedot/types": "0.15.3-next.65898ecf.10+65898ecf",
-    "@dedot/utils": "0.15.3-next.65898ecf.10+65898ecf"
+    "@dedot/codecs": "0.16.0",
+    "@dedot/providers": "0.16.0",
+    "@dedot/runtime-specs": "0.16.0",
+    "@dedot/shape": "0.16.0",
+    "@dedot/storage": "0.16.0",
+    "@dedot/types": "0.16.0",
+    "@dedot/utils": "0.16.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": "65898ecf2226162fc6632d3f4f64ad5fe1179643",
+  "gitHead": "3e78a8eebb8977de0c5fb956154e5b09c4448f31",
   "module": "./index.js",
   "types": "./index.d.ts"
 }

package/storage/BaseStorageQuery.d.ts

@@ -1,6 +1,6 @@
-import { ISubstrateClient, ISubstrateClientAt } from '@dedot/api/types';
 import { BlockHash, StorageData, StorageKey } from '@dedot/codecs';
 import type { Callback, Unsub } from '@dedot/types';
+import { ISubstrateClient, ISubstrateClientAt } from '../types.js';
 /**
  * @name BaseStorageQuery
  * @description

package/storage/NewStorageQuery.d.ts

@@ -1,6 +1,6 @@
-import { DedotClient } from '@dedot/api/client';
 import { BlockHash, StorageData, StorageKey } from '@dedot/codecs';
 import type { Callback, Unsub } from '@dedot/types';
+import { DedotClient } from '../client/DedotClient.js';
 import { BaseStorageQuery } from './BaseStorageQuery.js';
 /**
  * @name NewStorageQuery

package/types.d.ts

@@ -1,4 +1,3 @@
-import { ChainHeadEvent } from '@dedot/api/json-rpc';
 import { BlockHash, Hash, Metadata, PortableRegistry } from '@dedot/codecs';
 import type { ConnectionStatus, JsonRpcProvider, ProviderEvent } from '@dedot/providers';
 import type { AnyShape } from '@dedot/shape';
@@ -6,6 +5,7 @@ import type { IStorage } from '@dedot/storage';
 import type { Callback, GenericStorageQuery, GenericSubstrateApi, InjectedSigner, Query, QueryFnResult, RpcVersion, RuntimeApiName, RuntimeApiSpec, Unsub } from '@dedot/types';
 import type { HashFn, HexString, IEventEmitter } from '@dedot/utils';
 import type { AnySignedExtension } from './extrinsic/index.js';
+import type { ChainHeadEvent } from './json-rpc/index.js';
 export type MetadataKey = `RAW_META/${string}`;
 export type SubscribeMethod = string;
 export type UnsubscribeMethod = string;