@dedot/api 0.18.8 → 1.0.0

package/client/LegacyClient.d.ts

@@ -1,9 +1,10 @@
-import { BlockHash } from '@dedot/codecs';
+import { BlockHash, type Extrinsic, Metadata } from '@dedot/codecs';
 import type { JsonRpcProvider } from '@dedot/providers';
-import { GenericSubstrateApi, RpcLegacy, VersionedGenericSubstrateApi } from '@dedot/types';
+import { Callback, GenericSubstrateApi, TxUnsub } from '@dedot/types';
+import { HexString } from '@dedot/utils';
 import type { SubstrateApi } from '../chaintypes/index.js';
 import { BaseStorageQuery } from '../storage/index.js';
-import type { ApiOptions, ISubstrateClientAt } from '../types.js';
+import type { ApiOptions, BlockExplorer, IChainSpec, ISubstrateClientAt } from '../types.js';
 import { BaseSubstrateClient } from './BaseSubstrateClient.js';
 /**
  * @name LegacyClient
@@ -43,9 +44,10 @@ import { BaseSubstrateClient } from './BaseSubstrateClient.js';
  * run().catch(console.error);
  * ```
  */
-export declare class LegacyClient<ChainApi extends VersionedGenericSubstrateApi = SubstrateApi>// prettier-end-here
- extends BaseSubstrateClient<RpcLegacy, ChainApi> {
+export declare class LegacyClient<ChainApi extends GenericSubstrateApi = SubstrateApi>// prettier-end-here
+ extends BaseSubstrateClient<ChainApi> {
     #private;
+    protected _blockExplorer?: BlockExplorer;
     /**
      * Use factory methods (`create`, `new`) to create `Dedot` instances.
      *
@@ -57,20 +59,20 @@ export declare class LegacyClient<ChainApi extends VersionedGenericSubstrateApi
      *
      * @param options
      */
-    static create<ChainApi extends VersionedGenericSubstrateApi = SubstrateApi>(options: ApiOptions | JsonRpcProvider): Promise<LegacyClient<ChainApi>>;
+    static create<ChainApi extends GenericSubstrateApi = SubstrateApi>(options: ApiOptions | JsonRpcProvider): Promise<LegacyClient<ChainApi>>;
     /**
      * Alias for __LegacyClient.create__
      *
      * @param options
      */
-    static new<ChainApi extends VersionedGenericSubstrateApi = SubstrateApi>(options: ApiOptions | JsonRpcProvider): Promise<LegacyClient<ChainApi>>;
-    protected onDisconnected: () => Promise<void>;
+    static new<ChainApi extends GenericSubstrateApi = SubstrateApi>(options: ApiOptions | JsonRpcProvider): Promise<LegacyClient<ChainApi>>;
     protected beforeDisconnect(): Promise<void>;
     /**
      * Initialize APIs before usage
      */
     protected doInitialize(): Promise<void>;
     protected cleanUp(): void;
+    protected setMetadata(metadata: Metadata): Promise<void>;
     /**
      * @description Entry-point for inspecting constants (parameter types) for all pallets (modules).
      *
@@ -79,7 +81,7 @@ export declare class LegacyClient<ChainApi extends VersionedGenericSubstrateApi
      * console.log('ss58Prefix:', ss58Prefix)
      * ```
      */
-    get consts(): ChainApi[RpcLegacy]['consts'];
+    get consts(): ChainApi['consts'];
     /**
      * @description Entry-point for executing query to on-chain storage.
      *
@@ -88,15 +90,15 @@ export declare class LegacyClient<ChainApi extends VersionedGenericSubstrateApi
      * console.log('Balance:', balance);
      * ```
      */
-    get query(): ChainApi[RpcLegacy]['query'];
+    get query(): ChainApi['query'];
     /**
      * @description Entry-point for inspecting errors from metadata
      */
-    get errors(): ChainApi[RpcLegacy]['errors'];
+    get errors(): ChainApi['errors'];
     /**
      * @description Entry-point for inspecting events from metadata
      */
-    get events(): ChainApi[RpcLegacy]['events'];
+    get events(): ChainApi['events'];
     /**
      * @description Entry-point for executing runtime api
      *
@@ -109,9 +111,9 @@ export declare class LegacyClient<ChainApi extends VersionedGenericSubstrateApi
      * const queryInfo = await api.call.transactionPaymentApi.queryInfo(tx.toU8a(), tx.length);
      * ```
      */
-    get call(): ChainApi[RpcLegacy]['call'];
-    protected callAt(hash?: BlockHash): ChainApi[RpcLegacy]['call'];
-    get view(): ChainApi[RpcLegacy]['view'];
+    get call(): ChainApi['call'];
+    protected callAt(hash?: BlockHash): ChainApi['call'];
+    get view(): ChainApi['view'];
     /**
      * @description Entry-point for executing on-chain transactions
      *
@@ -123,13 +125,16 @@ export declare class LegacyClient<ChainApi extends VersionedGenericSubstrateApi
      *    });
      * ```
      */
-    get tx(): ChainApi[RpcLegacy]['tx'];
+    get tx(): ChainApi['tx'];
+    get block(): BlockExplorer;
+    get chainSpec(): IChainSpec;
     /**
      * 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
      *
      * @param hash
      */
-    at<ChainApiAt extends GenericSubstrateApi = ChainApi[RpcLegacy]>(hash: BlockHash): Promise<ISubstrateClientAt<ChainApiAt>>;
+    at<ChainApiAt extends GenericSubstrateApi = ChainApi>(hash: BlockHash): Promise<ISubstrateClientAt<ChainApiAt>>;
     protected getStorageQuery(): BaseStorageQuery;
+    sendTx(tx: HexString | Extrinsic, callback?: Callback): TxUnsub;
 }

package/client/LegacyClient.js

@@ -1,9 +1,12 @@
 import { PortableRegistry } from '@dedot/codecs';
-import { assert } from '@dedot/utils';
+import { assert, noop } from '@dedot/utils';
 import { ConstantExecutor, ErrorExecutor, EventExecutor, RuntimeApiExecutor, StorageQueryExecutor, TxExecutor, ViewFunctionExecutor, } from '../executor/index.js';
+import { SubmittableExtrinsic } from '../extrinsic/submittable/SubmittableExtrinsic.js';
 import { newProxyChain } from '../proxychain.js';
 import { LegacyStorageQuery } from '../storage/index.js';
-import { BaseSubstrateClient } from './BaseSubstrateClient.js';
+import { BaseSubstrateClient, ensurePresence } from './BaseSubstrateClient.js';
+import { LegacyBlockExplorer } from './explorer/index.js';
+import { detectHasherFromHeader, detectHasherFromMetadata } from './utils.js';
 const KEEP_ALIVE_INTERVAL = 10_000; // in ms
 /**
  * @name LegacyClient
@@ -47,6 +50,8 @@ export class LegacyClient// prettier-end-here
  extends BaseSubstrateClient {
     #runtimeSubscriptionUnsub;
     #healthTimer;
+    #hasher;
+    _blockExplorer;
     /**
      * Use factory methods (`create`, `new`) to create `Dedot` instances.
      *
@@ -71,9 +76,6 @@ export class LegacyClient// prettier-end-here
     static async new(options) {
         return LegacyClient.create(options);
     }
-    onDisconnected = async () => {
-        await this.#unsubscribeUpdates();
-    };
     async beforeDisconnect() {
         await this.#unsubscribeUpdates();
     }
@@ -81,46 +83,91 @@ export 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 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 = 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 = detectHasherFromHeader(header, hash);
+                    }
+                }
+                catch {
+                    // Ignore errors in fallback detection
+                }
+            }
+        }
+        this._registry = new 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(noop);
         }, KEEP_ALIVE_INTERVAL);
     }
     #unsubscribeHealth() {
@@ -135,16 +182,23 @@ export 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();
@@ -221,6 +275,22 @@ export class LegacyClient// prettier-end-here
     get tx() {
         return newProxyChain({ executor: new TxExecutor(this) });
     }
+    get block() {
+        return 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
@@ -243,7 +313,7 @@ export class LegacyClient// prettier-end-here
             }
             else {
                 metadata = await this.fetchMetadata(parentHash, targetVersion);
-                registry = new PortableRegistry(metadata.latest, this.options.hasher);
+                registry = new PortableRegistry(metadata.latest, this.#hasher || this.options.hasher);
             }
         }
         const api = {
@@ -281,4 +351,10 @@ export class LegacyClient// prettier-end-here
             return header.parentHash;
         }
     }
+    sendTx(tx, callback) {
+        return SubmittableExtrinsic.fromTx(this, tx) // --
+            .send((result) => {
+            callback && callback(result);
+        });
+    }
 }

package/client/V2Client.d.ts

@@ -0,0 +1,75 @@
+import { BlockHash, type Extrinsic, Metadata } from '@dedot/codecs';
+import type { JsonRpcProvider } from '@dedot/providers';
+import { Callback, GenericSubstrateApi, TxUnsub } from '@dedot/types';
+import { HexString } from '@dedot/utils';
+import type { SubstrateApi } from '../chaintypes/index.js';
+import { Archive, ChainHead, ChainSpec, PinnedBlock } from '../json-rpc/index.js';
+import { BaseStorageQuery } from '../storage/index.js';
+import type { ApiOptions, BlockExplorer, DedotClientEvent, ISubstrateClientAt, TxBroadcaster } from '../types.js';
+import { BaseSubstrateClient } from './BaseSubstrateClient.js';
+/**
+ * @name V2Client
+ * @description New promised-based API Client for Polkadot & Substrate based on JSON-RPC V2
+ *
+ * __Unstable, use with caution.__
+ */
+export declare class V2Client<ChainApi extends GenericSubstrateApi = SubstrateApi>// prettier-end-here
+ extends BaseSubstrateClient<ChainApi, DedotClientEvent> {
+    #private;
+    protected _chainHead?: ChainHead;
+    protected _chainSpec?: ChainSpec;
+    protected _archive?: Archive;
+    protected _txBroadcaster?: TxBroadcaster;
+    protected _blockExplorer?: BlockExplorer;
+    /**
+     * Use factory methods (`create`, `new`) to create `V2Client` instances.
+     *
+     * @param options
+     */
+    constructor(options: ApiOptions | JsonRpcProvider);
+    /**
+     * Factory method to create a new V2Client instance
+     *
+     * @param options
+     */
+    static create<ChainApi extends GenericSubstrateApi = SubstrateApi>(options: ApiOptions | JsonRpcProvider): Promise<V2Client<ChainApi>>;
+    /**
+     * Alias for __V2Client.create__
+     *
+     * @param options
+     */
+    static new<ChainApi extends GenericSubstrateApi = SubstrateApi>(options: ApiOptions | JsonRpcProvider): Promise<V2Client<ChainApi>>;
+    get chainSpec(): ChainSpec;
+    get chainHead(): ChainHead;
+    get archive(): Archive | undefined;
+    get txBroadcaster(): TxBroadcaster;
+    /**
+     * Initialize APIs before usage
+     */
+    protected doInitialize(): Promise<void>;
+    protected subscribeRuntimeUpgrades(): void;
+    protected onRuntimeUpgrade: (block: PinnedBlock) => Promise<void>;
+    protected setMetadata(metadata: Metadata): Promise<void>;
+    protected beforeDisconnect(): 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['query'];
+    get view(): ChainApi['view'];
+    get call(): ChainApi['call'];
+    protected callAt(blockHash?: BlockHash): ChainApi['call'];
+    get tx(): ChainApi['tx'];
+    get block(): 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
+     */
+    at<ChainApiAt extends GenericSubstrateApi = ChainApi>(hash: BlockHash): Promise<ISubstrateClientAt<ChainApiAt>>;
+    protected getStorageQuery(): BaseStorageQuery;
+    sendTx(tx: HexString | Extrinsic, callback?: Callback): TxUnsub;
+}