@dedot/api 0.15.2 → 0.16.0

package/chaintypes/substrate/index.d.ts

@@ -1,4 +1,5 @@
-import type { GenericSubstrateApi, RpcLegacy, RpcV2, RpcVersion } from '@dedot/types';
+import type { MultiAddress } from '@dedot/codecs';
+import type { GenericChainKnownTypes, GenericSubstrateApi, RpcLegacy, RpcV2, RpcVersion } from '@dedot/types';
 import { ChainConsts } from './consts.js';
 import { ChainErrors } from './errors.js';
 import { ChainEvents } from './events.js';
@@ -6,8 +7,26 @@ import { ChainJsonRpcApis } from './json-rpc.js';
 import { ChainStorage } from './query.js';
 import { RuntimeApis } from './runtime.js';
 import { ChainTx } from './tx.js';
+import type { FrameMetadataHashExtensionCheckMetadataHash, FrameSystemExtensionsCheckGenesis, FrameSystemExtensionsCheckMortality, FrameSystemExtensionsCheckNonZeroSender, FrameSystemExtensionsCheckNonce, FrameSystemExtensionsCheckSpecVersion, FrameSystemExtensionsCheckTxVersion, FrameSystemExtensionsCheckWeight, FrameSystemExtensionsWeightReclaim, KitchensinkRuntimeRuntimeCall, PalletAssetConversionTxPaymentChargeAssetTxPayment, SpRuntimeMultiSignature } from './types.js';
 import { ChainViewFunctions } from './view-functions.js';
 export * from './types.js';
+interface ChainKnownTypes extends GenericChainKnownTypes {
+    Address: MultiAddress;
+    Signature: SpRuntimeMultiSignature;
+    RuntimeCall: KitchensinkRuntimeRuntimeCall;
+    Extra: [
+        FrameSystemExtensionsCheckNonZeroSender,
+        FrameSystemExtensionsCheckSpecVersion,
+        FrameSystemExtensionsCheckTxVersion,
+        FrameSystemExtensionsCheckGenesis,
+        FrameSystemExtensionsCheckMortality,
+        FrameSystemExtensionsCheckNonce,
+        FrameSystemExtensionsCheckWeight,
+        PalletAssetConversionTxPaymentChargeAssetTxPayment,
+        FrameMetadataHashExtensionCheckMetadataHash,
+        FrameSystemExtensionsWeightReclaim
+    ];
+}
 export interface VersionedSubstrateApi<Rv extends RpcVersion> extends GenericSubstrateApi<Rv> {
     rpc: ChainJsonRpcApis<Rv>;
     consts: ChainConsts<Rv>;
@@ -17,6 +36,7 @@ export interface VersionedSubstrateApi<Rv extends RpcVersion> extends GenericSub
     call: RuntimeApis<Rv>;
     view: ChainViewFunctions<Rv>;
     tx: ChainTx<Rv>;
+    types: ChainKnownTypes;
 }
 /**
  * @name: SubstrateApi

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

@@ -19,8 +19,8 @@ class DedotClient// prettier-end-here
  extends BaseSubstrateClient_js_1.BaseSubstrateClient {
     _chainHead;
     _chainSpec;
+    _archive;
     _txBroadcaster;
-    #apiAtCache = {};
     /**
      * Use factory methods (`create`, `new`) to create `DedotClient` instances.
      *
@@ -51,6 +51,11 @@ class DedotClient// prettier-end-here
     get chainHead() {
         return (0, BaseSubstrateClient_js_1.ensurePresence)(this._chainHead);
     }
+    async archive() {
+        (0, utils_1.assert)(this._archive, 'Archive instance is not initialized');
+        (0, utils_1.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
         (0, utils_1.assert)(this._txBroadcaster, 'JSON-RPC method to broadcast transactions is not supported by the server/node.');
@@ -71,6 +76,12 @@ class DedotClient// prettier-end-here
         const rpcMethods = (await this.rpc.rpc_methods()).methods;
         this._chainHead = new index_js_2.ChainHead(this, { rpcMethods });
         this._chainSpec = new index_js_2.ChainSpec(this, { rpcMethods });
+        // Always initialize Archive, but only set up fallback if supported
+        this._archive = new index_js_2.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([
@@ -133,8 +144,16 @@ 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 (0, proxychain_js_1.newProxyChain)({
@@ -159,19 +178,40 @@ 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);
-        (0, utils_1.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);
+                    (0, utils_1.assert)(runtimeRaw, 'Runtime Version Not Found');
+                    targetVersion = this.toSubstrateRuntimeVersion(codecs_1.$RuntimeVersion.tryDecode(runtimeRaw));
+                }
+                catch (error) {
+                    throw new utils_1.DedotError(`Unable to fetch runtime version for block ${hash}: ${error}`);
+                }
+            }
+            else {
+                throw new utils_1.DedotError('Block is not pinned and Archive JSON-RPC is not supported by the server/node!');
+            }
         }
         let metadata = this.metadata;
         let registry = this.registry;
@@ -195,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/executor/Executor.js

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

package/cjs/executor/v2/StorageQueryExecutorV2.js

@@ -22,9 +22,7 @@ class StorageQueryExecutorV2 extends StorageQueryExecutor_js_1.StorageQueryExecu
         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/cjs/executor/v2/TxExecutorV2.js

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

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

@@ -0,0 +1,232 @@
+"use strict";
+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.
+ * 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
+ */
+class Archive extends JsonRpcGroup_js_1.JsonRpcGroup {
+    #genesisHash;
+    #cache;
+    constructor(client, options) {
+        super(client, { prefix: 'archive', supportedVersions: ['unstable', 'v1'], ...options });
+        this.#cache = new utils_1.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 utils_1.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 utils_1.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();
+    }
+}
+exports.Archive = Archive;