@dedot/api 1.2.0 → 1.3.0

package/cjs/client/BaseSubstrateClient.js

@@ -257,15 +257,26 @@ class BaseSubstrateClient extends index_js_2.JsonRpcClient {
         this.on('connected', this.onConnected);
         // @ts-ignore
         this.on('disconnected', this.onDisconnected);
-        return new Promise((resolve) => {
+        return new Promise((resolve, reject) => {
+            // @ts-ignore
+            const offError = this.on('error', (err) => {
+                reject(err instanceof Error ? err : new Error(String(err)));
+            });
             // @ts-ignore
             this.once('ready', () => {
+                offError();
                 resolve(this);
             });
         });
     }
     onConnected = async () => {
-        await this.initialize();
+        try {
+            await this.initialize();
+        }
+        catch (e) {
+            // @ts-ignore — surface init failure so the pending connect() promise can reject
+            this.emit('error', e);
+        }
     };
     onDisconnected = async () => { };
     async initialize() {

package/cjs/client/DedotClient.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DedotClient = void 0;
+const utils_1 = require("@dedot/utils");
 const index_js_1 = require("../json-rpc/index.js");
 const LegacyClient_js_1 = require("./LegacyClient.js");
 const V2Client_js_1 = require("./V2Client.js");
@@ -51,7 +52,12 @@ const V2Client_js_1 = require("./V2Client.js");
  */
 class DedotClient {
     #client;
-    /** The JSON-RPC version being used ('v2' or 'legacy') */
+    #pendingOptions;
+    /**
+     * The JSON-RPC version being used ('v2' or 'legacy').
+     *
+     * In auto-detect mode (no `rpcVersion` option), this is resolved during `connect()`.
+     */
     rpcVersion;
     /**
      * Creates a new DedotClient instance.
@@ -61,18 +67,14 @@ class DedotClient {
      * @param options - Client configuration options or a JsonRpcProvider instance
      */
     constructor(options) {
-        let rpcVersion = 'v2';
-        if (!(0, index_js_1.isJsonRpcProvider)(options)) {
-            if (options['rpcVersion'] === 'legacy') {
-                rpcVersion = 'legacy';
-            }
-        }
-        this.rpcVersion = rpcVersion;
-        if (this.rpcVersion === 'legacy') {
-            this.#client = new LegacyClient_js_1.LegacyClient(options);
+        const explicitVersion = (0, index_js_1.isJsonRpcProvider)(options) ? undefined : options.rpcVersion;
+        if (explicitVersion) {
+            this.rpcVersion = explicitVersion;
+            this.#client =
+                explicitVersion === 'legacy' ? new LegacyClient_js_1.LegacyClient(options) : new V2Client_js_1.V2Client(options);
         }
         else {
-            this.#client = new V2Client_js_1.V2Client(options);
+            this.#pendingOptions = options;
         }
     }
     /**
@@ -284,10 +286,34 @@ class DedotClient {
     /**
      * Establishes connection to the blockchain network.
      *
+     * When `rpcVersion` was not specified, this tries JSON-RPC v2 first and
+     * transparently falls back to legacy if the node does not support v2.
+     *
      * @returns This client instance for method chaining
      */
     async connect() {
-        await this.#client.connect();
+        if (this.#client) {
+            await this.#client.connect();
+            return this;
+        }
+        const options = this.#pendingOptions;
+        this.#pendingOptions = undefined;
+        const v2 = new V2Client_js_1.V2Client(options);
+        try {
+            await v2.connect();
+            this.#client = v2;
+            this.rpcVersion = 'v2';
+        }
+        catch (e) {
+            if (!(e instanceof utils_1.JsonRpcV2NotSupportedError))
+                throw e;
+            console.warn('JSON-RPC v2 is not supported by the connected node, falling back to legacy JSON-RPC.');
+            await v2.disconnect().catch(utils_1.noop);
+            const legacy = new LegacyClient_js_1.LegacyClient(options);
+            await legacy.connect();
+            this.#client = legacy;
+            this.rpcVersion = 'legacy';
+        }
         return this;
     }
     /**

package/cjs/client/V2Client.js

@@ -78,6 +78,10 @@ class V2Client// prettier-end-here
         const shouldInitialize = !this._genesisHash;
         if (shouldInitialize) {
             const rpcMethods = (await this.rpc.rpc_methods()).methods;
+            if (!rpcMethods.some((m) => m.startsWith('chainHead_'))) {
+                throw new utils_1.JsonRpcV2NotSupportedError('The connected node does not support JSON-RPC v2 (no chainHead_* methods). ' +
+                    'Omit `rpcVersion` to auto-detect, or pass `rpcVersion: "legacy"`.');
+            }
             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

package/client/BaseSubstrateClient.js

@@ -253,15 +253,26 @@ export class BaseSubstrateClient extends JsonRpcClient {
         this.on('connected', this.onConnected);
         // @ts-ignore
         this.on('disconnected', this.onDisconnected);
-        return new Promise((resolve) => {
+        return new Promise((resolve, reject) => {
+            // @ts-ignore
+            const offError = this.on('error', (err) => {
+                reject(err instanceof Error ? err : new Error(String(err)));
+            });
             // @ts-ignore
             this.once('ready', () => {
+                offError();
                 resolve(this);
             });
         });
     }
     onConnected = async () => {
-        await this.initialize();
+        try {
+            await this.initialize();
+        }
+        catch (e) {
+            // @ts-ignore — surface init failure so the pending connect() promise can reject
+            this.emit('error', e);
+        }
     };
     onDisconnected = async () => { };
     async initialize() {

package/client/DedotClient.d.ts

@@ -9,9 +9,14 @@ import { ApiEvent, ApiOptions, BlockExplorer, ISubstrateClient, ISubstrateClient
  */
 export type ClientOptions = ApiOptions & {
     /**
-     * The JSON-RPC version to use
-     * - 'v2' (default): Uses the new JSON-RPC v2 specification
-     * - 'legacy': Uses the legacy JSON-RPC specification for older nodes
+     * The JSON-RPC version to use.
+     *
+     * - _unset_ (default): auto-detect. Try JSON-RPC v2 first and transparently fall back
+     *   to legacy if the connected node does not expose v2 methods (no `chainHead_*`).
+     *   After `connect()` resolves, `client.rpcVersion` reflects the version that was picked.
+     * - `'v2'`: force JSON-RPC v2. Throws `JsonRpcV2NotSupportedError` during `connect()`
+     *   if the node does not support v2.
+     * - `'legacy'`: force legacy JSON-RPC.
      */
     rpcVersion?: RpcVersion;
 };
@@ -62,7 +67,11 @@ export type ClientOptions = ApiOptions & {
  */
 export declare class DedotClient<ChainApi extends GenericSubstrateApi = SubstrateApi> implements ISubstrateClient<ChainApi, ApiEvent> {
     #private;
-    /** The JSON-RPC version being used ('v2' or 'legacy') */
+    /**
+     * The JSON-RPC version being used ('v2' or 'legacy').
+     *
+     * In auto-detect mode (no `rpcVersion` option), this is resolved during `connect()`.
+     */
     rpcVersion: RpcVersion;
     /**
      * Creates a new DedotClient instance.
@@ -239,6 +248,9 @@ export declare class DedotClient<ChainApi extends GenericSubstrateApi = Substrat
     /**
      * Establishes connection to the blockchain network.
      *
+     * When `rpcVersion` was not specified, this tries JSON-RPC v2 first and
+     * transparently falls back to legacy if the node does not support v2.
+     *
      * @returns This client instance for method chaining
      */
     connect(): Promise<this>;

package/client/DedotClient.js

@@ -1,3 +1,4 @@
+import { JsonRpcV2NotSupportedError, noop } from '@dedot/utils';
 import { isJsonRpcProvider } from '../json-rpc/index.js';
 import { LegacyClient } from './LegacyClient.js';
 import { V2Client } from './V2Client.js';
@@ -48,7 +49,12 @@ import { V2Client } from './V2Client.js';
  */
 export class DedotClient {
     #client;
-    /** The JSON-RPC version being used ('v2' or 'legacy') */
+    #pendingOptions;
+    /**
+     * The JSON-RPC version being used ('v2' or 'legacy').
+     *
+     * In auto-detect mode (no `rpcVersion` option), this is resolved during `connect()`.
+     */
     rpcVersion;
     /**
      * Creates a new DedotClient instance.
@@ -58,18 +64,14 @@ export class DedotClient {
      * @param options - Client configuration options or a JsonRpcProvider instance
      */
     constructor(options) {
-        let rpcVersion = 'v2';
-        if (!isJsonRpcProvider(options)) {
-            if (options['rpcVersion'] === 'legacy') {
-                rpcVersion = 'legacy';
-            }
-        }
-        this.rpcVersion = rpcVersion;
-        if (this.rpcVersion === 'legacy') {
-            this.#client = new LegacyClient(options);
+        const explicitVersion = isJsonRpcProvider(options) ? undefined : options.rpcVersion;
+        if (explicitVersion) {
+            this.rpcVersion = explicitVersion;
+            this.#client =
+                explicitVersion === 'legacy' ? new LegacyClient(options) : new V2Client(options);
         }
         else {
-            this.#client = new V2Client(options);
+            this.#pendingOptions = options;
         }
     }
     /**
@@ -281,10 +283,34 @@ export class DedotClient {
     /**
      * Establishes connection to the blockchain network.
      *
+     * When `rpcVersion` was not specified, this tries JSON-RPC v2 first and
+     * transparently falls back to legacy if the node does not support v2.
+     *
      * @returns This client instance for method chaining
      */
     async connect() {
-        await this.#client.connect();
+        if (this.#client) {
+            await this.#client.connect();
+            return this;
+        }
+        const options = this.#pendingOptions;
+        this.#pendingOptions = undefined;
+        const v2 = new V2Client(options);
+        try {
+            await v2.connect();
+            this.#client = v2;
+            this.rpcVersion = 'v2';
+        }
+        catch (e) {
+            if (!(e instanceof JsonRpcV2NotSupportedError))
+                throw e;
+            console.warn('JSON-RPC v2 is not supported by the connected node, falling back to legacy JSON-RPC.');
+            await v2.disconnect().catch(noop);
+            const legacy = new LegacyClient(options);
+            await legacy.connect();
+            this.#client = legacy;
+            this.rpcVersion = 'legacy';
+        }
         return this;
     }
     /**

package/client/V2Client.js

@@ -1,6 +1,6 @@
 import { $H256, $Header, $RuntimeVersion, PortableRegistry, } from '@dedot/codecs';
 import { u32 } from '@dedot/shape';
-import { assert, concatU8a, DedotError, twox64Concat, u8aToHex, xxhashAsU8a } from '@dedot/utils';
+import { assert, concatU8a, DedotError, JsonRpcV2NotSupportedError, twox64Concat, u8aToHex, xxhashAsU8a, } from '@dedot/utils';
 import { ConstantExecutor, ErrorExecutor, EventExecutor, RuntimeApiExecutorV2, StorageQueryExecutorV2, TxExecutorV2, ViewFunctionExecutorV2, } from '../executor/index.js';
 import { SubmittableExtrinsicV2 } from '../extrinsic/submittable/SubmittableExtrinsicV2.js';
 import { Archive, ChainHead, ChainSpec, Transaction, TransactionWatch } from '../json-rpc/index.js';
@@ -75,6 +75,10 @@ export class V2Client// prettier-end-here
         const shouldInitialize = !this._genesisHash;
         if (shouldInitialize) {
             const rpcMethods = (await this.rpc.rpc_methods()).methods;
+            if (!rpcMethods.some((m) => m.startsWith('chainHead_'))) {
+                throw new JsonRpcV2NotSupportedError('The connected node does not support JSON-RPC v2 (no chainHead_* methods). ' +
+                    'Omit `rpcVersion` to auto-detect, or pass `rpcVersion: "legacy"`.');
+            }
             this._chainHead = new ChainHead(this, { rpcMethods });
             this._chainSpec = new ChainSpec(this, { rpcMethods });
             // Always initialize Archive, but only set up fallback if supported

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dedot/api",
-  "version": "1.2.0",
+  "version": "1.3.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": "^1.2.0",
-    "@dedot/providers": "^1.2.0",
-    "@dedot/runtime-specs": "^1.2.0",
-    "@dedot/shape": "^1.2.0",
-    "@dedot/storage": "^1.2.0",
-    "@dedot/types": "^1.2.0",
-    "@dedot/utils": "^1.2.0"
+    "@dedot/codecs": "^1.3.0",
+    "@dedot/providers": "^1.3.0",
+    "@dedot/runtime-specs": "^1.3.0",
+    "@dedot/shape": "^1.3.0",
+    "@dedot/storage": "^1.3.0",
+    "@dedot/types": "^1.3.0",
+    "@dedot/utils": "^1.3.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": "d0da366e311d33389d0fd1b9e9435c1d61da5799",
+  "gitHead": "1179ba75b371517a21eb1162881e6e4c655514a0",
   "module": "./index.js",
   "types": "./index.d.ts"
 }