@dedot/api 0.18.8 → 1.0.0

package/client/DedotClient.d.ts

@@ -1,71 +1,368 @@
-import { BlockHash } from '@dedot/codecs';
-import type { JsonRpcProvider } from '@dedot/providers';
-import { GenericSubstrateApi, RpcV2, VersionedGenericSubstrateApi } from '@dedot/types';
-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, DedotClientEvent, ISubstrateClientAt, TxBroadcaster } from '../types.js';
-import { BaseSubstrateClient } from './BaseSubstrateClient.js';
+import { type Extrinsic, Metadata, PortableRegistry } from '@dedot/codecs';
+import { ConnectionStatus, JsonRpcProvider } from '@dedot/providers';
+import { Callback, GenericStorageQuery, GenericSubstrateApi, InjectedSigner, Query, QueryFnResult, RpcVersion, TxUnsub, Unsub } from '@dedot/types';
+import { HexString } from '@dedot/utils';
+import { SubstrateApi } from '../chaintypes/index.js';
+import { ApiEvent, ApiOptions, BlockExplorer, ISubstrateClient, ISubstrateClientAt, SubstrateRuntimeVersion, IChainSpec, type EventHandlerFn } from '../types.js';
+/**
+ * Configuration options for DedotClient
+ */
+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
+     */
+    rpcVersion?: RpcVersion;
+};
 /**
  * @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.
+ *
+ * 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);
+ * });
  *
- * __Unstable, use with caution.__
+ * // 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 declare class DedotClient<ChainApi extends VersionedGenericSubstrateApi = SubstrateApi>// prettier-end-here
- extends BaseSubstrateClient<RpcV2, ChainApi, DedotClientEvent> {
+export declare class DedotClient<ChainApi extends GenericSubstrateApi = SubstrateApi> implements ISubstrateClient<ChainApi, ApiEvent> {
     #private;
-    protected _chainHead?: ChainHead;
-    protected _chainSpec?: ChainSpec;
-    protected _archive?: Archive;
-    protected _txBroadcaster?: TxBroadcaster;
+    /** The JSON-RPC version being used ('v2' or 'legacy') */
+    rpcVersion: 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: ApiOptions | JsonRpcProvider);
+    constructor(options: ClientOptions | JsonRpcProvider);
     /**
-     * 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 create<ChainApi extends VersionedGenericSubstrateApi = SubstrateApi>(options: ApiOptions | JsonRpcProvider): Promise<DedotClient<ChainApi>>;
+    static create<ChainApi extends GenericSubstrateApi = SubstrateApi>(options: ClientOptions | JsonRpcProvider): Promise<DedotClient<ChainApi>>;
     /**
-     * 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 new<ChainApi extends VersionedGenericSubstrateApi = SubstrateApi>(options: ApiOptions | JsonRpcProvider): Promise<DedotClient<ChainApi>>;
-    get chainSpec(): ChainSpec;
-    get chainHead(): ChainHead;
-    archive(): Promise<Archive>;
-    get txBroadcaster(): TxBroadcaster;
+    static new<ChainApi extends GenericSubstrateApi = SubstrateApi>(options: ClientOptions | JsonRpcProvider): Promise<DedotClient<ChainApi>>;
     /**
-     * Initialize APIs before usage
+     * 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'),
+     * });
+     * ```
      */
-    protected doInitialize(): Promise<void>;
-    protected subscribeRuntimeUpgrades(): void;
-    protected onRuntimeUpgrade: (block: PinnedBlock) => Promise<void>;
-    protected beforeDisconnect(): Promise<void>;
-    protected onDisconnected: () => Promise<void>;
-    protected cleanUp(): void;
+    static legacy<ChainApi extends GenericSubstrateApi = SubstrateApi>(options: ClientOptions | JsonRpcProvider): Promise<DedotClient<ChainApi>>;
+    /** The API configuration options */
+    get options(): ApiOptions;
+    /** Current connection status */
+    get status(): ConnectionStatus;
+    /** The underlying JSON-RPC provider */
+    get provider(): JsonRpcProvider;
+    /** Transaction builder for submitting extrinsics */
+    get tx(): ChainApi['tx'];
+    /** Raw JSON-RPC method access */
+    get rpc(): ChainApi['rpc'];
+    /** The genesis hash of the connected chain */
+    get genesisHash(): HexString;
+    /** Current runtime version information */
+    get runtimeVersion(): SubstrateRuntimeVersion;
+    /** The chain metadata */
+    get metadata(): Metadata;
+    /** Type registry for encoding/decoding chain types */
+    get registry(): PortableRegistry<ChainApi['types']>;
     /**
-     * @description Clear local cache, API at-block cache, and ChainHead cache
-     * @param keepMetadataCache Keep the metadata cache, only clear other caches.
+     * Access to pallet constants.
+     *
+     * @example
+     * ```typescript
+     * const existentialDeposit = client.consts.balances.existentialDeposit;
+     * const ss58Prefix = client.consts.system.ss58Prefix;
+     * ```
      */
-    clearCache(keepMetadataCache?: boolean): Promise<void>;
-    get query(): ChainApi[RpcV2]['query'];
-    get view(): ChainApi[RpcV2]['view'];
-    get call(): ChainApi[RpcV2]['call'];
-    protected callAt(blockHash?: BlockHash): ChainApi[RpcV2]['call'];
-    get tx(): ChainApi[RpcV2]['tx'];
+    get consts(): ChainApi['consts'];
+    /**
+     * 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);
+     * });
+     * ```
+     */
+    get query(): ChainApi['query'];
+    /**
+     * Runtime API call interface.
+     *
+     * @example
+     * ```typescript
+     * const rawMetadata = await client.call.metadata.metadataAtVersion(16);
+     * const version = await client.call.core.version();
+     * ```
+     */
+    get call(): ChainApi['call'];
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    get events(): ChainApi['events'];
+    /**
+     * 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(): ChainApi['errors'];
+    /**
+     * View functions interface (requires Metadata V16+).
+     *
+     * @example
+     * ```typescript
+     * // Call a view function
+     * const result = await client.view.voterList.scores(ALICE_ADDRESS);
+     * ```
+     */
+    get view(): ChainApi['view'];
+    /**
+     * 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(): BlockExplorer;
     /**
-     * Get a new API instance at a specific block hash
-     * Supports both pinned blocks (via ChainHead) and historical blocks (via Archive fallback)
+     * Chain specification interface for accessing chain information.
      *
-     * @param hash
+     * 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(): IChainSpec;
+    /**
+     * Establishes connection to the blockchain network.
+     *
+     * @returns This client instance for method chaining
+     */
+    connect(): Promise<this>;
+    /**
+     * Closes the connection to the blockchain network.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Subscribe to client events.
+     *
+     * @param event - The event to listen for ('ready', 'connected', 'disconnected', 'reconnecting', 'runtimeUpgraded', 'error')
+     * @param handler - Callback function to handle the event
+     * @returns Unsubscribe function
+     */
+    on<Event extends ApiEvent = ApiEvent>(event: Event, handler: EventHandlerFn<Event>): () => void;
+    /**
+     * 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 extends ApiEvent = ApiEvent>(event: Event, handler: EventHandlerFn<Event>): () => void;
+    /**
+     * 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 extends ApiEvent = ApiEvent>(event: Event, handler?: EventHandlerFn<Event>): 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<ChainApiAt extends GenericSubstrateApi = ChainApi[RpcV2]>(hash: BlockHash): Promise<ISubstrateClientAt<ChainApiAt>>;
-    protected getStorageQuery(): BaseStorageQuery;
+    at<ChainApiAt extends GenericSubstrateApi = ChainApi>(hash: `0x${string}`): Promise<ISubstrateClientAt<ChainApiAt>>;
+    /**
+     * 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(): Promise<SubstrateRuntimeVersion>;
+    /**
+     * Set or update the signer instance for signing transactions.
+     *
+     * @param signer - The signer instance (or undefined to clear)
+     */
+    setSigner(signer?: InjectedSigner | undefined): void;
+    /**
+     * Query multiple storage items in a single call or subscribe to multiple storage items.
+     *
+     * @example
+     * ```typescript
+     * // One-time query
+     * const [balance, blockNumber] = await client.queryMulti([
+     *   { fn: client.query.system.account, args: [ALICE] },
+     *   { fn: client.query.system.number, args: [] }
+     * ]);
+     *
+     * // Subscription
+     * const unsub = await client.queryMulti([
+     *   { fn: client.query.system.account, args: [ALICE] },
+     *   { fn: client.query.system.number, args: [] }
+     * ], ([balance, blockNumber]) => {
+     *   console.log('Balance:', balance, 'Block:', blockNumber);
+     * });
+     * ```
+     *
+     * @template Fns - Array of storage query functions
+     * @param queries - Array of query specifications with function and arguments
+     * @param callback - Optional callback for subscription mode
+     * @returns Query results array, or unsubscribe function if callback provided
+     */
+    queryMulti<Fns extends GenericStorageQuery[]>(queries: {
+        [K in keyof Fns]: Query<Fns[K]>;
+    }): Promise<{
+        [K in keyof Fns]: QueryFnResult<Fns[K]>;
+    }>;
+    queryMulti<Fns extends GenericStorageQuery[]>(queries: {
+        [K in keyof Fns]: Query<Fns[K]>;
+    }, callback: Callback<{
+        [K in keyof Fns]: QueryFnResult<Fns[K]>;
+    }>): Promise<Unsub>;
+    /**
+     * 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: HexString | Extrinsic, callback?: Callback): TxUnsub;
+    /**
+     * Clear internal caches.
+     *
+     * @param keepMetadataCache - If true, preserves the metadata cache (default: false)
+     */
+    clearCache(keepMetadataCache?: boolean): Promise<void>;
 }