@dedot/api 0.18.8 → 1.0.0

package/cjs/client/LegacyClient.js

@@ -4,9 +4,12 @@ exports.LegacyClient = void 0;
 const codecs_1 = require("@dedot/codecs");
 const utils_1 = require("@dedot/utils");
 const index_js_1 = require("../executor/index.js");
+const SubmittableExtrinsic_js_1 = require("../extrinsic/submittable/SubmittableExtrinsic.js");
 const proxychain_js_1 = require("../proxychain.js");
 const index_js_2 = require("../storage/index.js");
 const BaseSubstrateClient_js_1 = require("./BaseSubstrateClient.js");
+const index_js_3 = require("./explorer/index.js");
+const utils_js_1 = require("./utils.js");
 const KEEP_ALIVE_INTERVAL = 10_000; // in ms
 /**
  * @name LegacyClient
@@ -50,6 +53,8 @@ class LegacyClient// prettier-end-here
  extends BaseSubstrateClient_js_1.BaseSubstrateClient {
     #runtimeSubscriptionUnsub;
     #healthTimer;
+    #hasher;
+    _blockExplorer;
     /**
      * Use factory methods (`create`, `new`) to create `Dedot` instances.
      *
@@ -74,9 +79,6 @@ class LegacyClient// prettier-end-here
     static async new(options) {
         return LegacyClient.create(options);
     }
-    onDisconnected = async () => {
-        await this.#unsubscribeUpdates();
-    };
     async beforeDisconnect() {
         await this.#unsubscribeUpdates();
     }
@@ -84,46 +86,91 @@ class LegacyClient// prettier-end-here
      * Initialize APIs before usage
      */
     async doInitialize() {
-        let [genesisHash, runtimeVersion, metadata] = await Promise.all([
-            this.rpc.chain_getBlockHash(0),
-            this.#getRuntimeVersion(),
-            (await this.shouldPreloadMetadata()) ? this.fetchMetadata() : Promise.resolve(undefined),
-        ]);
-        this._genesisHash = genesisHash;
-        this._runtimeVersion = runtimeVersion;
-        await this.setupMetadata(metadata);
-        this.#subscribeUpdates();
+        // Determine if this is the first initialization
+        const shouldInitialize = !this._genesisHash;
+        if (shouldInitialize) {
+            // First load: Run all requests in parallel for speed
+            let [genesisHash, runtimeVersion, metadata] = await Promise.all([
+                this.rpc.chain_getBlockHash(0),
+                this.#getRuntimeVersion(),
+                (await this.shouldPreloadMetadata()) ? this.fetchMetadata() : Promise.resolve(undefined),
+            ]);
+            this._genesisHash = genesisHash;
+            this._runtimeVersion = runtimeVersion;
+            await this.setupMetadata(metadata);
+            // Initialize block explorer
+            this._blockExplorer = new index_js_3.LegacyBlockExplorer(this);
+            // Subscribe to updates
+            this.#subscribeUpdates();
+        }
+        else {
+            // Reconnect: Only fetch runtime version to check for changes
+            const newRuntimeVersion = await this.#getRuntimeVersion();
+            // Only fetch metadata if spec version has changed
+            if (newRuntimeVersion.specVersion !== this._runtimeVersion?.specVersion) {
+                this._runtimeVersion = newRuntimeVersion;
+                const metadata = await this.fetchMetadata();
+                await this.setupMetadata(metadata);
+            }
+        }
     }
     cleanUp() {
         super.cleanUp();
         this.#healthTimer = undefined;
         this.#runtimeSubscriptionUnsub = undefined;
+        this._blockExplorer = undefined;
     }
     #subscribeRuntimeUpgrades() {
         if (this.#runtimeSubscriptionUnsub)
             return;
-        this.rpc
-            .state_subscribeRuntimeVersion(async (runtimeVersion) => {
+        this.#runtimeSubscriptionUnsub = this.block.best(async (block) => {
+            if (!block.runtimeUpgraded)
+                return;
+            const { hash } = block;
+            // Fetch the runtime version at this block
+            const runtimeVersion = await this.#getRuntimeVersion(hash);
+            // Check if the spec version has actually changed
             if (runtimeVersion.specVersion !== this.runtimeVersion?.specVersion) {
                 this.startRuntimeUpgrade();
-                this._runtimeVersion = this.toSubstrateRuntimeVersion(runtimeVersion);
-                const newMetadata = await this.fetchMetadata(undefined, this._runtimeVersion);
+                this._runtimeVersion = runtimeVersion;
+                const newMetadata = await this.fetchMetadata(hash, this._runtimeVersion);
                 await this.setupMetadata(newMetadata);
-                this.emit('runtimeUpgraded', this._runtimeVersion);
+                this.emit('runtimeUpgraded', this._runtimeVersion, block);
                 this.doneRuntimeUpgrade();
             }
-        })
-            .then((unsub) => {
-            this.#runtimeSubscriptionUnsub = unsub;
         });
     }
     async #getRuntimeVersion(at) {
         return this.toSubstrateRuntimeVersion(await this.rpc.state_getRuntimeVersion(at));
     }
+    async setMetadata(metadata) {
+        this._metadata = metadata;
+        // Detect hasher if not provided by user
+        // Here we assume that hasher method of a chain is less likely to be changed via runtime upgrades
+        // So for now, we only need to detect it in initial connection and reuse it later
+        if (!this.#hasher && !this.options.hasher) {
+            // Try metadata first
+            this.#hasher = (0, utils_js_1.detectHasherFromMetadata)(metadata);
+            // Fallback to block header detection
+            if (!this.#hasher) {
+                try {
+                    const hash = await this.rpc.chain_getFinalizedHead();
+                    const header = await this.rpc.chain_getHeader(hash);
+                    if (header) {
+                        this.#hasher = (0, utils_js_1.detectHasherFromHeader)(header, hash);
+                    }
+                }
+                catch {
+                    // Ignore errors in fallback detection
+                }
+            }
+        }
+        this._registry = new codecs_1.PortableRegistry(metadata.latest, this.#hasher || this.options.hasher);
+    }
     #subscribeHealth() {
         this.#unsubscribeHealth();
         this.#healthTimer = setInterval(() => {
-            this.rpc.system_health().catch(console.error);
+            this.rpc.system_health().catch(utils_1.noop);
         }, KEEP_ALIVE_INTERVAL);
     }
     #unsubscribeHealth() {
@@ -138,16 +185,23 @@ class LegacyClient// prettier-end-here
             return;
         }
         try {
-            await this.#runtimeSubscriptionUnsub();
+            this.#runtimeSubscriptionUnsub();
             this.#runtimeSubscriptionUnsub = undefined;
         }
         catch {
             // ignore
         }
     }
+    #subscribeStalingDetection() {
+        const stalingDetectionFn = this.getStalingDetectionFn();
+        if (!stalingDetectionFn)
+            return;
+        this.block.best(stalingDetectionFn);
+    }
     #subscribeUpdates() {
         this.#subscribeRuntimeUpgrades();
         this.#subscribeHealth();
+        this.#subscribeStalingDetection();
     }
     async #unsubscribeUpdates() {
         await this.#unsubscribeRuntimeUpdates();
@@ -224,6 +278,22 @@ class LegacyClient// prettier-end-here
     get tx() {
         return (0, proxychain_js_1.newProxyChain)({ executor: new index_js_1.TxExecutor(this) });
     }
+    get block() {
+        return (0, BaseSubstrateClient_js_1.ensurePresence)(this._blockExplorer);
+    }
+    get chainSpec() {
+        return {
+            chainName: () => {
+                return this.rpc.system_chain();
+            },
+            genesisHash: () => {
+                return Promise.resolve(this.genesisHash);
+            },
+            properties: () => {
+                return this.rpc.system_properties();
+            },
+        };
+    }
     /**
      * Create a new API instance at a specific block hash
      * This is useful when we want to inspect the state of the chain at a specific block hash
@@ -246,7 +316,7 @@ class LegacyClient// prettier-end-here
             }
             else {
                 metadata = await this.fetchMetadata(parentHash, targetVersion);
-                registry = new codecs_1.PortableRegistry(metadata.latest, this.options.hasher);
+                registry = new codecs_1.PortableRegistry(metadata.latest, this.#hasher || this.options.hasher);
             }
         }
         const api = {
@@ -284,5 +354,11 @@ class LegacyClient// prettier-end-here
             return header.parentHash;
         }
     }
+    sendTx(tx, callback) {
+        return SubmittableExtrinsic_js_1.SubmittableExtrinsic.fromTx(this, tx) // --
+            .send((result) => {
+            callback && callback(result);
+        });
+    }
 }
 exports.LegacyClient = LegacyClient;

package/cjs/client/V2Client.js

@@ -0,0 +1,316 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.V2Client = void 0;
+const codecs_1 = require("@dedot/codecs");
+const shape_1 = require("@dedot/shape");
+const utils_1 = require("@dedot/utils");
+const index_js_1 = require("../executor/index.js");
+const SubmittableExtrinsicV2_js_1 = require("../extrinsic/submittable/SubmittableExtrinsicV2.js");
+const index_js_2 = require("../json-rpc/index.js");
+const proxychain_js_1 = require("../proxychain.js");
+const index_js_3 = require("../storage/index.js");
+const BaseSubstrateClient_js_1 = require("./BaseSubstrateClient.js");
+const index_js_4 = require("./explorer/index.js");
+/**
+ * @name V2Client
+ * @description New promised-based API Client for Polkadot & Substrate based on JSON-RPC V2
+ *
+ * __Unstable, use with caution.__
+ */
+class V2Client// prettier-end-here
+ extends BaseSubstrateClient_js_1.BaseSubstrateClient {
+    _chainHead;
+    _chainSpec;
+    _archive;
+    _txBroadcaster;
+    _blockExplorer;
+    #hasher;
+    /**
+     * Use factory methods (`create`, `new`) to create `V2Client` instances.
+     *
+     * @param options
+     */
+    constructor(options) {
+        super('v2', options);
+    }
+    /**
+     * Factory method to create a new V2Client instance
+     *
+     * @param options
+     */
+    static async create(options) {
+        return new V2Client(options).connect();
+    }
+    /**
+     * Alias for __V2Client.create__
+     *
+     * @param options
+     */
+    static async new(options) {
+        return V2Client.create(options);
+    }
+    get chainSpec() {
+        return (0, BaseSubstrateClient_js_1.ensurePresence)(this._chainSpec);
+    }
+    get chainHead() {
+        return (0, BaseSubstrateClient_js_1.ensurePresence)(this._chainHead);
+    }
+    get archive() {
+        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.');
+        return this._txBroadcaster;
+    }
+    async #initializeTxBroadcaster(rpcMethods) {
+        const tx = new index_js_2.Transaction(this, { rpcMethods });
+        if (await tx.supported())
+            return tx;
+        const txWatch = new index_js_2.TransactionWatch(this, { rpcMethods });
+        if (await txWatch.supported())
+            return txWatch;
+    }
+    /**
+     * Initialize APIs before usage
+     */
+    async doInitialize() {
+        const shouldInitialize = !this._genesisHash;
+        if (shouldInitialize) {
+            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
+            const archive = new index_js_2.Archive(this, { rpcMethods });
+            // Set up ChainHead with Archive fallback only if Archive is supported
+            if (await archive.supported()) {
+                this._archive = archive;
+                this._chainHead.withArchive(archive);
+            }
+            this._txBroadcaster = await this.#initializeTxBroadcaster(rpcMethods);
+            this._blockExplorer = new index_js_4.V2BlockExplorer(this);
+        }
+        // Fetching node information
+        let [_, genesisHash] = await Promise.all([
+            this.chainHead.follow(true),
+            shouldInitialize ? this.chainSpec.genesisHash().catch(() => undefined) : Promise.resolve(this._genesisHash),
+        ]);
+        this._genesisHash = genesisHash || (await this.#getGenesisHashFallback());
+        const newBestRuntime = await this.chainHead.bestRuntimeVersion();
+        if (!this._runtimeVersion || newBestRuntime.specVersion !== this._runtimeVersion.specVersion) {
+            this._runtimeVersion = newBestRuntime;
+            let metadata;
+            if (await this.shouldPreloadMetadata()) {
+                metadata = await this.fetchMetadata();
+            }
+            await this.setupMetadata(metadata);
+        }
+        if (shouldInitialize) {
+            this.subscribeRuntimeUpgrades();
+            this.chainHead.on('newBlock', (...args) => this.emit('newBlock', ...args));
+            this.chainHead.on('bestBlock', (...args) => this.emit('bestBlock', ...args));
+            this.chainHead.on('finalizedBlock', (...args) => this.emit('finalizedBlock', ...args));
+            this.chainHead.on('bestChainChanged', (...args) => this.emit('bestChainChanged', ...args));
+        }
+    }
+    /**
+     * Ref: https://github.com/paritytech/polkadot-sdk/blob/bbd51ce867967f71657b901f1a956ad4f75d352e/substrate/frame/system/src/lib.rs#L909-L913
+     * @private
+     */
+    async #getGenesisHashFallback() {
+        const pallet = (0, utils_1.xxhashAsU8a)('System', 128);
+        const item = (0, utils_1.xxhashAsU8a)('BlockHash', 128);
+        const blockHeightAt0 = (0, utils_1.twox64Concat)(shape_1.u32.encode(0));
+        const key = (0, utils_1.u8aToHex)((0, utils_1.concatU8a)(pallet, item, blockHeightAt0));
+        const storageValue = await this.chainHead.storage([{ type: 'value', key }]);
+        const rawGenesisHash = storageValue.at(0)?.value;
+        (0, utils_1.assert)(rawGenesisHash, 'Genesis hash not found!');
+        // Here we assume that in most case the hash is stored as a H256
+        return codecs_1.$H256.tryDecode(rawGenesisHash);
+    }
+    subscribeRuntimeUpgrades() {
+        this.chainHead.on('bestBlock', this.onRuntimeUpgrade);
+        this.#subscribeStalingDetection();
+    }
+    onRuntimeUpgrade = async (block) => {
+        const runtimeUpgraded = block.runtime && block.runtime.specVersion !== this._runtimeVersion?.specVersion;
+        if (!runtimeUpgraded)
+            return;
+        this.startRuntimeUpgrade();
+        this._runtimeVersion = block.runtime;
+        const newMetadata = await this.fetchMetadata(undefined, this._runtimeVersion);
+        await this.setupMetadata(newMetadata);
+        const blockInfo = {
+            hash: block.hash,
+            number: block.number,
+            parent: block.parent,
+            runtimeUpgraded: block.runtimeUpgraded === true,
+        };
+        this.emit('runtimeUpgraded', this._runtimeVersion, blockInfo);
+        this.doneRuntimeUpgrade();
+    };
+    async setMetadata(metadata) {
+        this._metadata = metadata;
+        // Here we assume that hasher method of a chain is less likely to change via runtime upgrades
+        // So for now, we only need to detect it in initial connection and reuse it later
+        if (!this.#hasher && !this.options.hasher) {
+            this.#hasher = await this.chainHead.hasher();
+        }
+        this._registry = new codecs_1.PortableRegistry(metadata.latest, // --
+        this.#hasher || this.options.hasher);
+    }
+    #subscribeStalingDetection() {
+        const stalingDetectionFn = this.getStalingDetectionFn();
+        if (!stalingDetectionFn)
+            return;
+        this.chainHead.on('bestBlock', stalingDetectionFn);
+    }
+    async beforeDisconnect() {
+        await this.chainHead.unfollow();
+    }
+    cleanUp() {
+        super.cleanUp();
+        this._chainHead = undefined;
+        this._chainSpec = undefined;
+        this._archive = undefined;
+        this._txBroadcaster = undefined;
+        this._blockExplorer = undefined;
+    }
+    /**
+     * @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)({
+            executor: new index_js_1.StorageQueryExecutorV2(this, this.chainHead),
+        });
+    }
+    get view() {
+        return (0, proxychain_js_1.newProxyChain)({
+            executor: new index_js_1.ViewFunctionExecutorV2(this, this.chainHead),
+        });
+    }
+    get call() {
+        return this.callAt();
+    }
+    callAt(blockHash) {
+        return (0, proxychain_js_1.newProxyChain)({
+            executor: new index_js_1.RuntimeApiExecutorV2(this, this.chainHead, blockHash),
+        });
+    }
+    get tx() {
+        return (0, proxychain_js_1.newProxyChain)({ executor: new index_js_1.TxExecutorV2(this) });
+    }
+    get block() {
+        return (0, BaseSubstrateClient_js_1.ensurePresence)(this._blockExplorer);
+    }
+    /**
+     * Get a new API instance at a specific block hash
+     * Supports both pinned blocks (via ChainHead) and historical blocks (via Archive fallback)
+     *
+     * @param hash
+     */
+    async at(hash) {
+        const cached = this._apiAtCache.get(hash);
+        if (cached)
+            return cached;
+        let parentVersion;
+        let parentHash;
+        // Try to get block info from ChainHead first (for pinned blocks)
+        const targetBlock = this.chainHead.findBlock(hash);
+        if (targetBlock) {
+            if (hash === this.genesisHash) {
+                parentHash = hash;
+                parentVersion = targetBlock.runtime;
+            }
+            else {
+                parentHash = targetBlock.parent;
+                const parentBlock = this.chainHead.findBlock(parentHash);
+                parentVersion = parentBlock?.runtime;
+            }
+            // fallback to fetching on-chain runtime if we can't find it in the block
+            if (!parentVersion) {
+                parentVersion = this.toSubstrateRuntimeVersion(await this.callAt(parentHash).core.version());
+            }
+        }
+        else {
+            // Block not pinned, try via Archive fallback if supported
+            if (this._archive && (await this._archive.supported())) {
+                try {
+                    if (hash === this.genesisHash) {
+                        parentHash = hash;
+                    }
+                    else {
+                        const rawHeader = await this._archive.header(hash);
+                        (0, utils_1.assert)(rawHeader, `Header for block ${hash} not found`);
+                        const header = codecs_1.$Header.tryDecode(rawHeader);
+                        parentHash = header.parentHash;
+                    }
+                    // Fetch runtime version via Archive
+                    const runtimeRaw = await this._archive.call('Core_version', '0x', parentHash);
+                    (0, utils_1.assert)(runtimeRaw, 'Runtime Version Not Found');
+                    parentVersion = 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;
+        if (parentVersion && parentVersion.specVersion !== this.runtimeVersion.specVersion) {
+            const cachedMetadata = this.findMetadataInCache(parentVersion.specVersion);
+            if (cachedMetadata) {
+                metadata = cachedMetadata[0];
+                registry = cachedMetadata[1];
+            }
+            else {
+                metadata = await this.fetchMetadata(parentHash, parentVersion);
+                registry = new codecs_1.PortableRegistry(metadata.latest, this.#hasher || this.options.hasher);
+            }
+        }
+        const api = {
+            rpcVersion: 'v2',
+            atBlockHash: hash,
+            options: this.options,
+            genesisHash: this.genesisHash,
+            runtimeVersion: parentVersion,
+            metadata,
+            registry,
+            rpc: this.rpc,
+        };
+        api.consts = (0, proxychain_js_1.newProxyChain)({ executor: new index_js_1.ConstantExecutor(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) });
+        api.query = (0, proxychain_js_1.newProxyChain)({
+            executor: new index_js_1.StorageQueryExecutorV2(api, this.chainHead),
+        });
+        api.call = (0, proxychain_js_1.newProxyChain)({ executor: new index_js_1.RuntimeApiExecutorV2(api, this.chainHead) });
+        api.view = (0, proxychain_js_1.newProxyChain)({
+            executor: new index_js_1.ViewFunctionExecutorV2(api, this.chainHead),
+        });
+        // @ts-ignore Add queryMulti implementation for at-block queries
+        api.queryMulti = (queries) => {
+            return this.internalQueryMulti(queries, undefined, hash);
+        };
+        this._apiAtCache.set(hash, api);
+        return api;
+    }
+    getStorageQuery() {
+        return new index_js_3.NewStorageQuery(this);
+    }
+    sendTx(tx, callback) {
+        return SubmittableExtrinsicV2_js_1.SubmittableExtrinsicV2.fromTx(this, tx) // --
+            .send((result) => {
+            callback && callback(result);
+        });
+    }
+}
+exports.V2Client = V2Client;