@dedot/api 0.18.6 → 1.0.0-next.a0f8d41e.25

package/types.d.ts

@@ -1,9 +1,11 @@
-import { BlockHash, Hash, Metadata, PortableRegistry } from '@dedot/codecs';
+import { BlockHash, Extrinsic, Hash, Header, Metadata, PortableRegistry } from '@dedot/codecs';
 import type { ConnectionStatus, JsonRpcProvider, ProviderEvent } from '@dedot/providers';
 import type { AnyShape } from '@dedot/shape';
 import type { IStorage } from '@dedot/storage';
-import type { Callback, GenericStorageQuery, GenericSubstrateApi, InjectedSigner, Query, QueryFnResult, RpcVersion, RuntimeApiName, RuntimeApiSpec, Unsub } from '@dedot/types';
+import { Callback, GenericStorageQuery, GenericSubstrateApi, InjectedSigner, Query, QueryFnResult, RpcVersion, RuntimeApiName, RuntimeApiSpec, TxUnsub, Unsub } from '@dedot/types';
+import { Properties } from '@dedot/types/json-rpc';
 import type { HashFn, HexString, IEventEmitter } from '@dedot/utils';
+import type { SubstrateApi } from './chaintypes/index.js';
 import type { AnySignedExtension } from './extrinsic/index.js';
 import type { ChainHeadEvent } from './json-rpc/index.js';
 export type MetadataKey = `RAW_META/${string}`;
@@ -60,6 +62,20 @@ export interface ApiOptions extends JsonRpcClientOptions {
      * A signer instance to use for signing transactions
      */
     signer?: InjectedSigner;
+    /**
+     * Timeout in milliseconds for detecting stale WebSocket connections.
+     * When set, monitors block subscription activity and triggers reconnection
+     * to switch to a different endpoint if no blocks/events received within the timeout period.
+     *
+     * Note: This option is only supported when used with WsProvider.
+     *
+     * - Default: 30000 (30 seconds) - staling detection enabled
+     * - 0: Disabled - no staling detection
+     * - Any positive number: Custom timeout in milliseconds
+     *
+     * @default 30000
+     */
+    stalingDetectionTimeout?: number;
 }
 export type ApiEvent = ProviderEvent | 'ready' | 'runtimeUpgraded';
 export type DedotClientEvent = ApiEvent | ChainHeadEvent;
@@ -74,7 +90,7 @@ export interface SubstrateRuntimeVersion {
 /**
  * A generic interface for JSON-RPC clients
  */
-export interface IJsonRpcClient<ChainApi extends GenericSubstrateApi = GenericSubstrateApi, Events extends string = ProviderEvent> extends IEventEmitter<Events> {
+export interface IJsonRpcClient<ChainApi extends GenericSubstrateApi = SubstrateApi, Events extends string = ProviderEvent> extends IEventEmitter<Events> {
     options: JsonRpcClientOptions;
     status: ConnectionStatus;
     provider: JsonRpcProvider;
@@ -85,7 +101,7 @@ export interface IJsonRpcClient<ChainApi extends GenericSubstrateApi = GenericSu
 /**
  * @internal
  */
-export interface IGenericSubstrateClient<ChainApi extends GenericSubstrateApi = GenericSubstrateApi> {
+export interface IGenericSubstrateClient<ChainApi extends GenericSubstrateApi = SubstrateApi> {
     rpcVersion: RpcVersion;
     options: ApiOptions;
     genesisHash: Hash;
@@ -125,15 +141,37 @@ export interface IGenericSubstrateClient<ChainApi extends GenericSubstrateApi =
 /**
  * A generic interface for Substrate clients at a specific block
  */
-export interface ISubstrateClientAt<ChainApi extends GenericSubstrateApi = GenericSubstrateApi> extends IGenericSubstrateClient<ChainApi> {
+export interface ISubstrateClientAt<ChainApi extends GenericSubstrateApi = SubstrateApi> extends IGenericSubstrateClient<ChainApi> {
     atBlockHash: BlockHash;
 }
+export interface BlockInfo {
+    hash: BlockHash;
+    number: number;
+    parent: BlockHash;
+    runtimeUpgraded: boolean;
+}
+export interface BlockExplorer {
+    best(): Promise<BlockInfo>;
+    best(callback: (block: BlockInfo) => void): () => void;
+    finalized(): Promise<BlockInfo>;
+    finalized(callback: (block: BlockInfo) => void): () => void;
+    header(hash: BlockHash): Promise<Header>;
+    body(hash: BlockHash): Promise<HexString[]>;
+}
+export interface IChainSpec {
+    chainName(): Promise<string>;
+    genesisHash(): Promise<HexString>;
+    properties(): Promise<Properties>;
+}
 /**
  * A generic interface for Substrate clients
  */
-export interface ISubstrateClient<ChainApi extends GenericSubstrateApi = GenericSubstrateApi, Events extends string = ApiEvent> extends IJsonRpcClient<ChainApi, Events>, IGenericSubstrateClient<ChainApi> {
+export interface ISubstrateClient<ChainApi extends GenericSubstrateApi = SubstrateApi, // --
+Events extends string = ApiEvent> extends IJsonRpcClient<ChainApi, Events>, IGenericSubstrateClient<ChainApi> {
     options: ApiOptions;
     tx: ChainApi['tx'];
+    chainSpec: IChainSpec;
+    block: BlockExplorer;
     at<ChainApiAt extends GenericSubstrateApi = ChainApi>(hash: BlockHash): Promise<ISubstrateClientAt<ChainApiAt>>;
     /**
      * Get current version of the runtime
@@ -149,6 +187,44 @@ export interface ISubstrateClient<ChainApi extends GenericSubstrateApi = Generic
      * @param signer
      */
     setSigner(signer?: InjectedSigner): void;
+    /**
+     * Broadcasts a transaction to the network and monitors its status.
+     *
+     * This method accepts a transaction (either as a hex-encoded string or an Extrinsic instance)
+     * and submits it to the network. It returns a TxUnsub object that allows you to:
+     * - Subscribe to transaction status updates via an optional callback
+     * - Wait for specific transaction states (finalized, included in best chain block)
+     *
+     * @param tx - The signed transaction to broadcast, either as a hex-encoded string or Extrinsic instance
+     * @param callback - Optional callback function to receive transaction status updates. The callback
+     *                   receives an ISubmittableResult object containing status, events, errors, tx hash, etc...
+     *
+     * @returns A TxUnsub object that is both a Promise<Unsub> and provides utility methods:
+     *          - `.untilFinalized()` - Resolves when transaction is finalized
+     *          - `.untilBestChainBlockIncluded()` - Resolves when transaction is included in best chain block
+     *          - When awaited directly, resolves to an unsubscribe function
+     *
+     * @example
+     * // Basic usage with callback for status updates
+     * const unsub = await client.sendTx(rawTxHex, (result) => {
+     *   console.log('Transaction status:', result.status);
+     *   console.log('Transaction hash:', result.txHash);
+     *   if (result.dispatchError) {
+     *     console.error('Transaction failed:', result.dispatchError);
+     *   }
+     * });
+     *
+     * @example
+     * // Wait for transaction to be included in best chain block
+     * const result = await client.sendTx(rawTxHex, console.log).untilBestChainBlockIncluded();
+     * console.log('Transaction included in block:', result);
+     *
+     * @example
+     * // Wait for transaction finalization
+     * const result = await client.sendTx(rawTxHex).untilFinalized();
+     * console.log('Transaction finalized:', result);
+     */
+    sendTx(tx: HexString | Extrinsic, callback?: Callback): TxUnsub;
     /**
      * Query multiple storage items in a single call or subscribe to multiple storage items
      *
@@ -185,6 +261,17 @@ export interface ISubstrateClient<ChainApi extends GenericSubstrateApi = Generic
     }, callback: Callback<{
         [K in keyof Fns]: QueryFnResult<Fns[K]>;
     }>): Promise<Unsub>;
+    on<Event extends Events = Events>(event: Event, handler: EventHandlerFn<Event>): () => void;
+}
+export type EventHandlerFn<Event extends string> = EventTypes[Event];
+interface EventTypes {
+    ready: () => void;
+    connected: (connectedEndpoint: string) => void;
+    disconnected: () => void;
+    reconnecting: () => void;
+    runtimeUpgraded: (newRuntimeVersion: SubstrateRuntimeVersion, at: BlockInfo) => void;
+    error: (error?: Error) => void;
+    [event: string]: (...args: any[]) => void;
 }
 /**
  * A generic interface for broadcasting transactions
@@ -202,3 +289,4 @@ export interface TxBroadcaster {
      */
     supported(): Promise<boolean>;
 }
+export {};