@dedot/api 0.18.8 → 1.0.0

package/client/DedotClient.js

@@ -1,270 +1,402 @@
-import { $H256, $Header, $RuntimeVersion, PortableRegistry } from '@dedot/codecs';
-import { u32 } from '@dedot/shape';
-import { assert, concatU8a, DedotError, noop, twox64Concat, u8aToHex, xxhashAsU8a } from '@dedot/utils';
-import { ConstantExecutor, ErrorExecutor, EventExecutor, RuntimeApiExecutorV2, StorageQueryExecutorV2, TxExecutorV2, ViewFunctionExecutorV2, } from '../executor/index.js';
-import { Archive, ChainHead, ChainSpec, Transaction, TransactionWatch } from '../json-rpc/index.js';
-import { newProxyChain } from '../proxychain.js';
-import { NewStorageQuery } from '../storage/index.js';
-import { BaseSubstrateClient, ensurePresence } from './BaseSubstrateClient.js';
+import { isJsonRpcProvider } from '../json-rpc/index.js';
+import { LegacyClient } from './LegacyClient.js';
+import { V2Client } from './V2Client.js';
 /**
  * @name DedotClient
- * @description New promised-based API Client for Polkadot & Substrate based on JSON-RPC V2
+ * @description The main entry point for interacting with PolkadotSDK-based blockchains.
  *
- * __Unstable, use with caution.__
+ * DedotClient is a facade that provides a unified API for both JSON-RPC v2 (default) and legacy
+ * JSON-RPC versions.
+ *
+ * @example
+ * ```typescript
+ * import { DedotClient, WsProvider } from 'dedot';
+ * import type { PolkadotApi } from '@dedot/chaintypes/polkadot';
+ *
+ * // Create and connect to a Polkadot node
+ * const provider = new WsProvider('wss://rpc.polkadot.io');
+ * const client = await DedotClient.new<PolkadotApi>(provider);
+ *
+ * // Get the current best block
+ * const bestBlock = await client.block.best();
+ * console.log('Best block:', bestBlock.number, bestBlock.hash);
+ *
+ * // Subscribe to finalized blocks
+ * const unsub = client.block.finalized((block) => {
+ *   console.log('Finalized:', block.number);
+ * });
+ *
+ * // Query on-chain storage
+ * const balance = await client.query.system.account('14...');
+ * console.log('Balance:', balance);
+ *
+ * // Subscribe to runtime upgrades
+ * const unsub = client.on('runtimeUpgraded', (version, block) => {
+ *   console.log('Runtime upgraded to:', version.specVersion, 'at block:', block.number);
+ * });
+ *
+ * // Sending transactions
+ * await client.tx.balances.transferKeepAlive('15...', 1000000000000n)
+ *             .signAndSend(signer)
+ *             .untilFinalized();
+ *
+ * // Disconnect when done
+ * await client.disconnect();
+ * ```
+ *
+ * @template ChainApi - Chain-specific API type for type-safe interactions (defaults to SubstrateApi)
  */
-export class DedotClient// prettier-end-here
- extends BaseSubstrateClient {
-    _chainHead;
-    _chainSpec;
-    _archive;
-    _txBroadcaster;
+export class DedotClient {
+    #client;
+    /** The JSON-RPC version being used ('v2' or 'legacy') */
+    rpcVersion;
     /**
-     * Use factory methods (`create`, `new`) to create `DedotClient` instances.
+     * Creates a new DedotClient instance.
+     *
+     * Use factory methods (`create`, `new`, `legacy`) for automatic connection.
      *
-     * @param options
+     * @param options - Client configuration options or a JsonRpcProvider instance
      */
     constructor(options) {
-        super('v2', 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);
+        }
+        else {
+            this.#client = new V2Client(options);
+        }
     }
     /**
-     * Factory method to create a new DedotClient instance
+     * Factory method to create and connect a new DedotClient instance.
      *
-     * @param options
+     * @param options - Client configuration options or a JsonRpcProvider instance
+     * @returns A connected DedotClient instance
+     *
+     * @example
+     * ```typescript
+     * const client = await DedotClient.create<PolkadotApi>({
+     *   provider: new WsProvider('wss://rpc.polkadot.io'),
+     * });
+     * ```
      */
     static async create(options) {
         return new DedotClient(options).connect();
     }
     /**
-     * Alias for __DedotClient.create__
+     * Alias for `DedotClient.create`
      *
-     * @param options
+     * @param options - Client configuration options or a JsonRpcProvider instance
+     * @returns A connected DedotClient instance
      */
     static async new(options) {
         return DedotClient.create(options);
     }
-    get chainSpec() {
-        return ensurePresence(this._chainSpec);
+    /**
+     * Factory method to create a DedotClient using legacy JSON-RPC.
+     *
+     * This is a convenience method that automatically sets `rpcVersion: 'legacy'`.
+     *
+     * @param options - Client configuration options or a JsonRpcProvider instance
+     * @returns A connected DedotClient instance using legacy JSON-RPC
+     *
+     * @example
+     * ```typescript
+     * const client = await DedotClient.legacy<PolkadotApi>({
+     *   provider: new WsProvider('wss://rpc.polkadot.io'),
+     * });
+     * ```
+     */
+    static async legacy(options) {
+        return DedotClient.create(isJsonRpcProvider(options) // --
+            ? { provider: options, rpcVersion: 'legacy' }
+            : { ...options, rpcVersion: 'legacy' });
+    }
+    /** The API configuration options */
+    get options() {
+        return this.#client.options;
+    }
+    /** Current connection status */
+    get status() {
+        return this.#client.status;
+    }
+    /** The underlying JSON-RPC provider */
+    get provider() {
+        return this.#client.provider;
+    }
+    /** Transaction builder for submitting extrinsics */
+    get tx() {
+        return this.#client.tx;
+    }
+    /** Raw JSON-RPC method access */
+    get rpc() {
+        return this.#client.rpc;
+    }
+    /** The genesis hash of the connected chain */
+    get genesisHash() {
+        return this.#client.genesisHash;
     }
-    get chainHead() {
-        return ensurePresence(this._chainHead);
+    /** Current runtime version information */
+    get runtimeVersion() {
+        return this.#client.runtimeVersion;
     }
-    async archive() {
-        assert(this._archive, 'Archive instance is not initialized');
-        assert(await this._archive.supported(), 'Archive JSON-RPC is not supported by the connected server');
-        return this._archive;
+    /** The chain metadata */
+    get metadata() {
+        return this.#client.metadata;
     }
-    get txBroadcaster() {
-        this.chainHead; // Ensure chain head is initialized
-        assert(this._txBroadcaster, 'JSON-RPC method to broadcast transactions is not supported by the server/node.');
-        return this._txBroadcaster;
+    /** Type registry for encoding/decoding chain types */
+    get registry() {
+        return this.#client.registry;
     }
-    async #initializeTxBroadcaster(rpcMethods) {
-        const tx = new Transaction(this, { rpcMethods });
-        if (await tx.supported())
-            return tx;
-        const txWatch = new TransactionWatch(this, { rpcMethods });
-        if (await txWatch.supported())
-            return txWatch;
+    /**
+     * Access to pallet constants.
+     *
+     * @example
+     * ```typescript
+     * const existentialDeposit = client.consts.balances.existentialDeposit;
+     * const ss58Prefix = client.consts.system.ss58Prefix;
+     * ```
+     */
+    get consts() {
+        return this.#client.consts;
     }
     /**
-     * Initialize APIs before usage
+     * Storage query interface for reading on-chain state.
+     *
+     * @example
+     * ```typescript
+     * // One-time query
+     * const account = await client.query.system.account(address);
+     *
+     * // Subscribe to storage changes
+     * const unsub = await client.query.system.number((blockNumber) => {
+     *   console.log('Current block:', blockNumber);
+     * });
+     * ```
      */
-    async doInitialize() {
-        const rpcMethods = (await this.rpc.rpc_methods()).methods;
-        this._chainHead = new ChainHead(this, { rpcMethods });
-        this._chainSpec = new ChainSpec(this, { rpcMethods });
-        // Always initialize Archive, but only set up fallback if supported
-        this._archive = new 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([
-            this.chainHead.follow(),
-            this.chainSpec.genesisHash().catch(() => undefined),
-        ]);
-        this._genesisHash = genesisHash || (await this.#getGenesisHashFallback());
-        this._runtimeVersion = await this.chainHead.bestRuntimeVersion();
-        let metadata;
-        if (await this.shouldPreloadMetadata()) {
-            metadata = await this.fetchMetadata();
-        }
-        await this.setupMetadata(metadata);
-        this.subscribeRuntimeUpgrades();
-        // relegate events
-        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));
+    get query() {
+        return this.#client.query;
     }
     /**
-     * Ref: https://github.com/paritytech/polkadot-sdk/blob/bbd51ce867967f71657b901f1a956ad4f75d352e/substrate/frame/system/src/lib.rs#L909-L913
-     * @private
+     * Runtime API call interface.
+     *
+     * @example
+     * ```typescript
+     * const rawMetadata = await client.call.metadata.metadataAtVersion(16);
+     * const version = await client.call.core.version();
+     * ```
      */
-    async #getGenesisHashFallback() {
-        const pallet = xxhashAsU8a('System', 128);
-        const item = xxhashAsU8a('BlockHash', 128);
-        const blockHeightAt0 = twox64Concat(u32.encode(0));
-        const key = u8aToHex(concatU8a(pallet, item, blockHeightAt0));
-        const storageValue = await this.chainHead.storage([{ type: 'value', key }]);
-        const rawGenesisHash = storageValue.at(0)?.value;
-        assert(rawGenesisHash, 'Genesis hash not found!');
-        // Here we assume that in most case the hash is stored as a H256
-        return $H256.tryDecode(rawGenesisHash);
-    }
-    subscribeRuntimeUpgrades() {
-        this.chainHead.on('bestBlock', this.onRuntimeUpgrade);
-    }
-    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);
-        this.emit('runtimeUpgraded', this._runtimeVersion);
-        this.doneRuntimeUpgrade();
-    };
-    async beforeDisconnect() {
-        await this.chainHead.unfollow();
-    }
-    onDisconnected = async () => {
-        try {
-            this.chainHead.unfollow().catch(noop);
-        }
-        catch { }
-    };
-    cleanUp() {
-        super.cleanUp();
-        this._chainHead = undefined;
-        this._chainSpec = undefined;
-        this._archive = undefined;
-        this._txBroadcaster = undefined;
+    get call() {
+        return this.#client.call;
     }
     /**
-     * @description Clear local cache, API at-block cache, and ChainHead cache
-     * @param keepMetadataCache Keep the metadata cache, only clear other caches.
+     * Event type definitions and utilities.
+     *
+     * @example
+     * ```typescript
+     * // Check if an event matches a specific type
+     * if (client.events.balances.Transfer.is(event)) {
+     *   console.log('Transfer event:', event.data);
+     * }
+     * ```
      */
-    async clearCache(keepMetadataCache = false) {
-        await super.clearCache(keepMetadataCache);
-        this._chainHead?.clearCache();
+    get events() {
+        return this.#client.events;
     }
-    get query() {
-        return newProxyChain({
-            executor: new StorageQueryExecutorV2(this, this.chainHead),
-        });
+    /**
+     * Error type definitions and utilities.
+     *
+     * @example
+     * ```typescript
+     * // Check if an error matches a specific type
+     * if (client.errors.balances.InsufficientBalance.is(dispatchError)) {
+     *   console.log('Insufficient balance error');
+     * }
+     * ```
+     */
+    get errors() {
+        return this.#client.errors;
     }
+    /**
+     * View functions interface (requires Metadata V16+).
+     *
+     * @example
+     * ```typescript
+     * // Call a view function
+     * const result = await client.view.voterList.scores(ALICE_ADDRESS);
+     * ```
+     */
     get view() {
-        return newProxyChain({
-            executor: new ViewFunctionExecutorV2(this, this.chainHead),
-        });
+        return this.#client.view;
     }
-    get call() {
-        return this.callAt();
+    /**
+     * Block explorer interface for accessing block data.
+     *
+     * Provides methods to get/subscribe to best and finalized blocks,
+     * as well as retrieve block headers and bodies.
+     *
+     * @example
+     * ```typescript
+     * // Get the current best block
+     * const bestBlock = await client.block.best();
+     * console.log('Best block:', bestBlock.number, bestBlock.hash);
+     *
+     * // Subscribe to finalized blocks
+     * const unsub = client.block.finalized((block) => {
+     *   console.log('Finalized block:', block.number);
+     * });
+     *
+     * // Get block header and body
+     * const header = await client.block.header(blockHash);
+     * const body = await client.block.body(blockHash);
+     * ```
+     */
+    get block() {
+        return this.#client.block;
     }
-    callAt(blockHash) {
-        return newProxyChain({
-            executor: new RuntimeApiExecutorV2(this, this.chainHead, blockHash),
-        });
+    /**
+     * Chain specification interface for accessing chain information.
+     *
+     * Provides methods to get chain name, genesis hash, and chain properties.
+     *
+     * @example
+     * ```typescript
+     * const chainName = await client.chainSpec.chainName();
+     * const genesisHash = await client.chainSpec.genesisHash();
+     * const properties = await client.chainSpec.properties();
+     *
+     * console.log(`Connected to ${chainName}`);
+     * console.log('Token symbol:', properties.tokenSymbol);
+     * console.log('Token decimals:', properties.tokenDecimals);
+     * ```
+     */
+    get chainSpec() {
+        return this.#client.chainSpec;
     }
-    get tx() {
-        return newProxyChain({ executor: new TxExecutorV2(this) });
+    /**
+     * Establishes connection to the blockchain network.
+     *
+     * @returns This client instance for method chaining
+     */
+    async connect() {
+        await this.#client.connect();
+        return this;
     }
     /**
-     * Get a new API instance at a specific block hash
-     * Supports both pinned blocks (via ChainHead) and historical blocks (via Archive fallback)
+     * Closes the connection to the blockchain network.
+     */
+    async disconnect() {
+        await this.#client.disconnect();
+    }
+    /**
+     * Subscribe to client events.
      *
-     * @param hash
+     * @param event - The event to listen for ('ready', 'connected', 'disconnected', 'reconnecting', 'runtimeUpgraded', 'error')
+     * @param handler - Callback function to handle the event
+     * @returns Unsubscribe function
      */
-    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);
-                        assert(rawHeader, `Header for block ${hash} not found`);
-                        const header = $Header.tryDecode(rawHeader);
-                        parentHash = header.parentHash;
-                    }
-                    // Fetch runtime version via Archive
-                    const runtimeRaw = await this._archive.call('Core_version', '0x', parentHash);
-                    assert(runtimeRaw, 'Runtime Version Not Found');
-                    parentVersion = this.toSubstrateRuntimeVersion($RuntimeVersion.tryDecode(runtimeRaw));
-                }
-                catch (error) {
-                    throw new DedotError(`Unable to fetch runtime version for block ${hash}: ${error}`);
-                }
-            }
-            else {
-                throw new 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 PortableRegistry(metadata.latest, this.options.hasher);
-            }
-        }
-        const api = {
-            rpcVersion: 'v2',
-            atBlockHash: hash,
-            options: this.options,
-            genesisHash: this.genesisHash,
-            runtimeVersion: parentVersion,
-            metadata,
-            registry,
-            rpc: this.rpc,
-        };
-        api.consts = newProxyChain({ executor: new ConstantExecutor(api) });
-        api.events = newProxyChain({ executor: new EventExecutor(api) });
-        api.errors = newProxyChain({ executor: new ErrorExecutor(api) });
-        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) });
-        // @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 NewStorageQuery(this);
+    on(event, handler) {
+        return this.#client.on(event, handler);
+    }
+    /**
+     * Subscribe to a client event once.
+     *
+     * @param event - The event to listen for
+     * @param handler - Callback function to handle the event
+     * @returns Unsubscribe function
+     */
+    once(event, handler) {
+        return this.#client.once(event, handler);
+    }
+    /**
+     * Unsubscribe from client events.
+     *
+     * @param event - The event to unsubscribe from
+     * @param handler - The handler function to remove (optional, removes all handlers if not provided)
+     * @returns This client instance for method chaining
+     */
+    off(event, handler) {
+        this.#client.off(event, handler);
+        return this;
+    }
+    /**
+     * Get a client instance at a specific block hash.
+     *
+     * This allows querying historical state at a specific block.
+     *
+     * @template ChainApiAt - Chain API type for the historical state (defaults to ChainApi)
+     * @param hash - The block hash to query at
+     * @returns A client instance for querying state at the specified block
+     *
+     * @example
+     * ```typescript
+     * const clientAtBlock = await client.at('0x1234...');
+     * const historicalBalance = await clientAtBlock.query.system.account('14...');
+     * ```
+     */
+    at(hash) {
+        return this.#client.at(hash);
+    }
+    /**
+     * Get the current runtime version with metadata sync.
+     *
+     * Unlike the `runtimeVersion` getter, this method ensures the corresponding
+     * metadata for the runtime version is downloaded and set up. Useful for
+     * preparing for runtime upgrades.
+     *
+     * @returns The current runtime version
+     */
+    getRuntimeVersion() {
+        return this.#client.getRuntimeVersion();
+    }
+    /**
+     * Set or update the signer instance for signing transactions.
+     *
+     * @param signer - The signer instance (or undefined to clear)
+     */
+    setSigner(signer) {
+        this.#client.setSigner(signer);
+    }
+    queryMulti(queries, // --
+    callback) {
+        // @ts-ignore
+        return this.#client.queryMulti(queries, callback);
+    }
+    /**
+     * Broadcast a transaction to the network and track its status.
+     *
+     * @param tx - The transaction (hex string or Extrinsic instance)
+     * @param callback - Optional callback for transaction status updates
+     * @returns TxUnsub object with utility methods (`.untilFinalized()`, `.untilBestChainBlockIncluded()`)
+     *
+     * @example
+     * ```typescript
+     * // Wait for finalization
+     * const result = await client.sendTx(txHex).untilFinalized();
+     *
+     * // With status callback to track progress
+     * const unsub = await client.sendTx(txHex, (result) => {
+     *   console.log('Status:', result.status);
+     *   if (result.dispatchError) {
+     *     console.error('Transaction failed:', result.dispatchError);
+     *   }
+     * });
+     * ```
+     */
+    sendTx(tx, callback) {
+        return this.#client.sendTx(tx, callback);
+    }
+    /**
+     * Clear internal caches.
+     *
+     * @param keepMetadataCache - If true, preserves the metadata cache (default: false)
+     */
+    async clearCache(keepMetadataCache = false) {
+        await this.#client.clearCache(keepMetadataCache);
     }
 }