polkadot-api 0.6.0 → 0.7.1

package/dist/index.d.mts

@@ -1,15 +1,109 @@
-import { HexString, SS58String, Enum, Binary, Descriptors, QueryFromDescriptors, TxFromDescriptors, EventsFromDescriptors, ConstFromDescriptors, BlockHeader, RuntimeDescriptor } from '@polkadot-api/substrate-bindings';
-export { AccountId, AssetDescriptor, Binary, Codec, ConstFromDescriptors, Enum, EnumVariant, ErrorsFromDescriptors, EventsFromDescriptors, FixedSizeBinary, GetEnum, HexString, PlainDescriptor, QueryFromDescriptors, ResultPayload, RuntimeDescriptor, SS58String, StorageDescriptor, TxDescriptor, TxFromDescriptors, _Enum } from '@polkadot-api/substrate-bindings';
-import { Observable } from 'rxjs';
-import { BlockInfo, SystemEvent as SystemEvent$1 } from '@polkadot-api/observable-client';
-import { ChainSpecData } from '@polkadot-api/substrate-client';
 import { JsonRpcProvider } from '@polkadot-api/json-rpc-provider';
+import { RuntimeContext, ChainHead$, BlockInfo, SystemEvent as SystemEvent$1, getObservableClient } from '@polkadot-api/observable-client';
+import { HexString, Binary, SS58String, Enum, BlockHeader } from '@polkadot-api/substrate-bindings';
+export { AccountId, Binary, Codec, Enum, EnumVariant, FixedSizeBinary, GetEnum, HexString, ResultPayload, SS58String, _Enum } from '@polkadot-api/substrate-bindings';
+import { ChainSpecData } from '@polkadot-api/substrate-client';
+import { Observable } from 'rxjs';
+import { PolkadotSigner } from '@polkadot-api/polkadot-signer';
 export { PolkadotSigner } from '@polkadot-api/polkadot-signer';
 
+type PlainDescriptor<T> = {
+    _type?: T;
+};
+type AssetDescriptor<T> = string & {
+    _type?: T;
+};
+type StorageDescriptor<Args extends Array<any>, T, Optional extends true | false> = {
+    _type: T;
+    _args: Args;
+    _optional: Optional;
+};
+type TxDescriptor<Args extends {} | undefined> = {
+    ___: Args;
+};
+type RuntimeDescriptor<Args extends Array<any>, T> = [Args, T];
+type DescriptorEntry<T> = Record<string, Record<string, T>>;
+type PalletDescriptors = Record<string, [
+    Record<string, number>,
+    Record<string, number>,
+    Record<string, number>,
+    Record<string, number>,
+    Record<string, number>
+]>;
+type PalletsTypedef<St extends DescriptorEntry<StorageDescriptor<any, any, any>>, Tx extends DescriptorEntry<TxDescriptor<any>>, Ev extends DescriptorEntry<PlainDescriptor<any>>, Err extends DescriptorEntry<PlainDescriptor<any>>, Ct extends DescriptorEntry<PlainDescriptor<any>>> = {
+    __storage: St;
+    __tx: Tx;
+    __event: Ev;
+    __error: Err;
+    __const: Ct;
+};
+type ApisDescriptors = DescriptorEntry<number>;
+type ApisTypedef<T extends DescriptorEntry<RuntimeDescriptor<any, any>>> = T;
+type DescriptorsValue = {
+    pallets: PalletDescriptors;
+    apis: ApisDescriptors;
+};
+type ChainDefinition = {
+    descriptors: Promise<DescriptorsValue> & {
+        pallets: PalletsTypedef<any, any, any, any, any>;
+        apis: ApisTypedef<any>;
+    };
+    asset: AssetDescriptor<any>;
+    checksums: Promise<string[]>;
+};
+type ExtractStorage<T extends DescriptorEntry<StorageDescriptor<any, any, any>>> = {
+    [K in keyof T]: {
+        [KK in keyof T[K]]: T[K][KK] extends StorageDescriptor<infer Key, infer Value, infer Optional> ? {
+            KeyArgs: Key;
+            Value: Value;
+            IsOptional: Optional;
+        } : unknown;
+    };
+};
+type ExtractTx<T extends DescriptorEntry<TxDescriptor<any>>> = {
+    [K in keyof T]: {
+        [KK in keyof T[K]]: T[K][KK] extends TxDescriptor<infer Args> ? Args : unknown;
+    };
+};
+type ExtractPlain<T extends DescriptorEntry<PlainDescriptor<any>>> = {
+    [K in keyof T]: {
+        [KK in keyof T[K]]: T[K][KK] extends PlainDescriptor<infer Value> ? Value : unknown;
+    };
+};
+type QueryFromPalletsDef<T extends PalletsTypedef<any, any, any, any, any>> = ExtractStorage<T["__storage"]>;
+type TxFromPalletsDef<T extends PalletsTypedef<any, any, any, any, any>> = ExtractTx<T["__tx"]>;
+type EventsFromPalletsDef<T extends PalletsTypedef<any, any, any, any, any>> = ExtractPlain<T["__event"]>;
+type ErrorsFromPalletsDef<T extends PalletsTypedef<any, any, any, any, any>> = ExtractPlain<T["__error"]>;
+type ConstFromPalletsDef<T extends PalletsTypedef<any, any, any, any, any>> = ExtractPlain<T["__const"]>;
+
+declare const enum OpType {
+    Storage = 0,
+    Tx = 1,
+    Event = 2,
+    Error = 3,
+    Const = 4
+}
 declare class Runtime {
-    protected _ctx: unknown;
-    protected _checksums: string[];
+    private _ctx;
+    private _checksums;
+    private _descriptors;
     private constructor();
+    /**
+     * @access package  - Internal implementation detail. Do not use.
+     */
+    static _create(ctx: RuntimeContext, checksums: string[], descriptors: DescriptorsValue): Runtime;
+    /**
+     * @access package  - Internal implementation detail. Do not use.
+     */
+    _getCtx(): RuntimeContext;
+    /**
+     * @access package  - Internal implementation detail. Do not use.
+     */
+    _getPalletChecksum(opType: OpType, pallet: string, name: string): string;
+    /**
+     * @access package  - Internal implementation detail. Do not use.
+     */
+    _getApiChecksum(name: string, method: string): string;
 }
 type RuntimeApi = Observable<Runtime> & {
     latest: () => Promise<Runtime>;
@@ -18,6 +112,19 @@ interface IsCompatible {
     (): Promise<boolean>;
     (runtime: Runtime): boolean;
 }
+declare const compatibilityHelper: (runtimeApi: RuntimeApi, getDescriptorChecksum: (runtime: Runtime) => string) => (getChecksum: (ctx: RuntimeContext) => string | null) => {
+    isCompatible: IsCompatible;
+    waitChecksums: () => Promise<(ctx: RuntimeContext) => boolean>;
+    withCompatibleRuntime: <T>(chainHead: ChainHead$, mapper: (x: T) => string, error: () => Error) => (source$: Observable<T>) => Observable<[T, RuntimeContext]>;
+    compatibleRuntime$: (chainHead: ChainHead$, hash: string | null, error: () => Error) => Observable<RuntimeContext>;
+};
+type CompatibilityHelper = ReturnType<typeof compatibilityHelper>;
+
+interface ConstantEntry<T> {
+    (): Promise<T>;
+    (runtime: Runtime): T;
+    isCompatible: IsCompatible;
+}
 
 type EventPhase = {
     type: "ApplyExtrinsic";
@@ -64,53 +171,60 @@ type CallOptions$1 = Partial<{
     at: string;
     signal: AbortSignal;
 }>;
-type WithCallOptions$1<Args extends Array<any>> = [
+type WithCallOptions$1<Args extends Array<any>> = Args["length"] extends 0 ? [options?: CallOptions$1] : [...args: Args, options?: CallOptions$1];
+interface RuntimeCall<Args extends Array<any>, Payload> {
+    (...args: WithCallOptions$1<Args>): Promise<Payload>;
+    isCompatible: IsCompatible;
+}
+
+type CallOptions = Partial<{
+    at: string;
+    signal: AbortSignal;
+}>;
+type WithCallOptions<Args extends Array<any>> = [
     ...args: Args,
-    options?: CallOptions$1
+    options?: CallOptions
 ];
 type PossibleParents<A extends Array<any>> = A extends [...infer Left, any] ? Left | PossibleParents<Left> : [];
 type StorageEntryWithoutKeys<Payload> = {
     isCompatible: IsCompatible;
-    getValue: (options?: CallOptions$1) => Promise<Payload>;
+    getValue: (options?: CallOptions) => Promise<Payload>;
     watchValue: (bestOrFinalized?: "best" | "finalized") => Observable<Payload>;
 };
 type StorageEntryWithKeys<Args extends Array<any>, Payload> = {
     isCompatible: IsCompatible;
-    getValue: (...args: [...WithCallOptions$1<Args>]) => Promise<Payload>;
+    getValue: (...args: [...WithCallOptions<Args>]) => Promise<Payload>;
     watchValue: (...args: [...Args, bestOrFinalized?: "best" | "finalized"]) => Observable<Payload>;
-    getValues: (keys: Array<[...Args]>, options?: CallOptions$1) => Promise<Array<Payload>>;
-    getEntries: (...args: WithCallOptions$1<PossibleParents<Args>>) => Promise<Array<{
+    getValues: (keys: Array<[...Args]>, options?: CallOptions) => Promise<Array<Payload>>;
+    getEntries: (...args: WithCallOptions<PossibleParents<Args>>) => Promise<Array<{
         keyArgs: Args;
         value: NonNullable<Payload>;
     }>>;
 };
 type StorageEntry<Args extends Array<any>, Payload> = Args extends [] ? StorageEntryWithoutKeys<Payload> : StorageEntryWithKeys<Args, Payload>;
 
-interface PolkadotSigner {
-    publicKey: Uint8Array;
-    sign: (callData: Uint8Array, signedExtensions: Record<string, {
-        identifier: string;
-        value: Uint8Array;
-        additionalSigned: Uint8Array;
-    }>, metadata: Uint8Array, atBlockNumber: number, hasher?: (data: Uint8Array) => Uint8Array) => Promise<Uint8Array>;
-}
-
-type TxBroadcastEvent = {
-    type: "broadcasted";
-} | {
-    type: "bestChainBlockIncluded";
-    block: {
-        hash: string;
-        index: number;
-    };
-} | ({
-    type: "finalized";
-} & TxFinalizedPayload);
-type TxEvent = TxBroadcastEvent | {
+type TxEvent = TxSigned | TxBroadcasted | TxBestBlocksState | TxFinalized;
+type TxBroadcastEvent = TxSigned | TxBroadcasted | TxBestBlocksState | TxFinalized;
+type TxSigned = {
     type: "signed";
-    tx: HexString;
+    txHash: HexString;
+};
+type TxBroadcasted = {
+    type: "broadcasted";
+    txHash: HexString;
+};
+type TxBestBlocksState = {
+    type: "txBestBlocksState";
+    txHash: HexString;
+} & (TxInBestBlocksNotFound | TxInBestBlocksFound);
+type TxInBestBlocksNotFound = {
+    found: false;
+    isValid: boolean;
 };
-type TxFinalizedPayload = {
+type TxInBestBlocksFound = {
+    found: true;
+} & TxEventsPayload;
+type TxEventsPayload = {
     ok: boolean;
     events: Array<SystemEvent$1["event"]>;
     block: {
@@ -118,7 +232,12 @@ type TxFinalizedPayload = {
         index: number;
     };
 };
-type HintedSignExtensions<Asset> = Partial<void extends Asset ? {
+type TxFinalized = {
+    type: "finalized";
+    txHash: HexString;
+} & TxEventsPayload;
+type TxOptions<Asset> = Partial<void extends Asset ? {
+    at: HexString | "best" | "finalized";
     tip: bigint;
     mortality: {
         mortal: false;
@@ -126,7 +245,9 @@ type HintedSignExtensions<Asset> = Partial<void extends Asset ? {
         mortal: true;
         period: number;
     };
+    nonce: number;
 } : {
+    at: HexString | "best" | "finalized";
     tip: bigint;
     mortality: {
         mortal: false;
@@ -135,20 +256,22 @@ type HintedSignExtensions<Asset> = Partial<void extends Asset ? {
         period: number;
     };
     asset: Asset;
+    nonce: number;
 }>;
-type TxFunction<Asset> = (from: PolkadotSigner, hintedSignExtensions?: HintedSignExtensions<Asset>) => Promise<TxFinalizedPayload>;
-type TxObservable<Asset> = (from: PolkadotSigner, hintedSignExtensions?: HintedSignExtensions<Asset>) => Observable<TxEvent>;
+type TxFinalizedPayload = Omit<TxFinalized, "type">;
+type TxPromise<Asset> = (from: PolkadotSigner, txOptions?: TxOptions<Asset>) => Promise<TxFinalizedPayload>;
+type TxObservable<Asset> = (from: PolkadotSigner, txOptions?: TxOptions<Asset>) => Observable<TxEvent>;
 interface TxCall {
     (): Promise<Binary>;
     (runtime: Runtime): Binary;
 }
-type TxSigned<Asset> = (from: PolkadotSigner, hintedSignExtensions?: HintedSignExtensions<Asset>) => Promise<string>;
+type TxSignFn<Asset> = (from: PolkadotSigner, txOptions?: TxOptions<Asset>) => Promise<HexString>;
 type Transaction<Arg extends {} | undefined, Pallet extends string, Name extends string, Asset> = {
-    sign: TxSigned<Asset>;
+    sign: TxSignFn<Asset>;
     signSubmitAndWatch: TxObservable<Asset>;
-    signAndSubmit: TxFunction<Asset>;
+    signAndSubmit: TxPromise<Asset>;
     getEncodedData: TxCall;
-    getEstimatedFees: (from: Uint8Array | SS58String, hintedSignExtensions?: HintedSignExtensions<Asset>) => Promise<bigint>;
+    getEstimatedFees: (from: Uint8Array | SS58String, txOptions?: TxOptions<Asset>) => Promise<bigint>;
     decodedCall: Enum<{
         [P in Pallet]: Enum<{
             [N in Name]: Arg;
@@ -160,21 +283,10 @@ interface TxEntry<Arg extends {} | undefined, Pallet extends string, Name extend
     isCompatible: IsCompatible;
 }
 
-interface ConstantEntry<T> {
-    (): Promise<T>;
-    (runtime: Runtime): T;
-    isCompatible: IsCompatible;
-}
+declare const submit$: (chainHead: ChainHead$, broadcastTx$: (tx: string) => Observable<never>, tx: HexString, at?: HexString, emitSign?: boolean) => Observable<TxEvent>;
+declare const submit: (chainHead: ChainHead$, broadcastTx$: (tx: string) => Observable<never>, transaction: HexString, at?: HexString) => Promise<TxFinalizedPayload>;
 
-type CallOptions = Partial<{
-    at: string;
-    signal: AbortSignal;
-}>;
-type WithCallOptions<Args extends Array<any>> = Args["length"] extends 0 ? [options?: CallOptions] : [...args: Args, options?: CallOptions];
-interface RuntimeCall<Args extends Array<any>, Payload> {
-    (...args: WithCallOptions<Args>): Promise<Payload>;
-    isCompatible: IsCompatible;
-}
+declare const createTxEntry: <Arg extends {} | undefined, Pallet extends string, Name extends string, Asset extends AssetDescriptor<any>>(pallet: Pallet, name: Name, assetChecksum: Asset, chainHead: ReturnType<ReturnType<typeof getObservableClient>["chainHead$"]>, broadcast: (tx: string) => Observable<never>, compatibilityHelper: CompatibilityHelper) => TxEntry<Arg, Pallet, Name, Asset["_type"]>;
 
 type StorageApi<A extends Record<string, Record<string, {
     KeyArgs: Array<any>;
@@ -209,32 +321,144 @@ type ConstApi<A extends Record<string, Record<string, any>>> = {
         [KK in keyof A[K]]: ConstantEntry<A[K][KK]>;
     };
 };
-type TypedApi<D extends Descriptors> = {
-    query: StorageApi<QueryFromDescriptors<D>>;
-    tx: TxApi<TxFromDescriptors<D>, D["asset"]["_type"]>;
-    event: EvApi<EventsFromDescriptors<D>>;
-    apis: RuntimeCallsApi<D["apis"]>;
-    constants: ConstApi<ConstFromDescriptors<D>>;
+type TypedApi<D extends ChainDefinition> = {
+    query: StorageApi<QueryFromPalletsDef<D["descriptors"]["pallets"]>>;
+    tx: TxApi<TxFromPalletsDef<D["descriptors"]["pallets"]>, D["asset"]["_type"]>;
+    event: EvApi<EventsFromPalletsDef<D["descriptors"]["pallets"]>>;
+    apis: RuntimeCallsApi<D["descriptors"]["apis"]>;
+    constants: ConstApi<ConstFromPalletsDef<D["descriptors"]["pallets"]>>;
     runtime: RuntimeApi;
 };
 interface PolkadotClient {
+    /**
+     * Retrieve the ChainSpecData as it comes from the
+     * [JSON-RPC spec](https://paritytech.github.io/json-rpc-interface-spec/api/chainSpec.html)
+     */
     getChainSpecData: () => Promise<ChainSpecData>;
+    /**
+     * Observable that emits `BlockInfo` from the latest known finalized block.
+     * It's a multicast and stateful observable, that will synchronously replay
+     * its latest known state.
+     */
     finalizedBlock$: Observable<BlockInfo>;
+    /**
+     * @returns Latest known finalized block.
+     */
     getFinalizedBlock: () => Promise<BlockInfo>;
+    /**
+     * Observable that emits an Array of `BlockInfo`, being the first element the
+     * latest known best block, and the last element the latest known finalized
+     * block. It's a multicast and stateful observable, that will synchronously
+     * replay its latest known state. This array is an immutable data structure;
+     * i.e. a new array is emitted at every event but the reference to its
+     * children are stable if the children didn't change.
+     *
+     * Note that subscribing to this observable already supersedes the need of
+     * subscribing to `finalizedBlock$`, since the last element of the array will
+     * be the latest known finalized block.
+     */
     bestBlocks$: Observable<BlockInfo[]>;
+    /**
+     * @returns Array of `BlockInfo`, being the first element the latest
+     *          known best block, and the last element the latest known
+     *          finalized block.
+     */
     getBestBlocks: () => Promise<BlockInfo[]>;
+    /**
+     * Observable to watch Block Body.
+     *
+     * @param hash  It can be a block hash, `"finalized"`, or `"best"`
+     * @returns Observable to watch a block body. There'll be just one event
+     *          with the payload and the observable will complete.
+     */
     watchBlockBody: (hash: string) => Observable<HexString[]>;
+    /**
+     * Get Block Body (Promise-based)
+     *
+     * @param hash  It can be a block hash, `"finalized"`, or `"best"`
+     * @returns Block body.
+     */
     getBlockBody: (hash: string) => Promise<HexString[]>;
+    /**
+     * Get Block Header (Promise-based)
+     *
+     * @param hash  It can be a block hash, `"finalized"` (default), or
+     *              `"best"`
+     * @returns Block hash.
+     */
     getBlockHeader: (hash?: string) => Promise<BlockHeader>;
-    submit: (transaction: HexString) => Promise<TxFinalizedPayload>;
-    submitAndWatch: (transaction: HexString) => Observable<TxBroadcastEvent>;
-    getTypedApi: <D extends Descriptors>(descriptors: D) => TypedApi<D>;
+    /**
+     * Broadcast a transaction (Promise-based)
+     *
+     * @param transaction  SCALE-encoded tx to broadcast.
+     * @param at           It can be a block hash, `"finalized"`, or `"best"`.
+     *                     That block will be used to verify the validity of
+     *                     the tx, retrieve the next nonce,
+     *                     and create the mortality taking that block into
+     *                     account.
+     */
+    submit: (transaction: HexString, at?: HexString) => Promise<TxFinalizedPayload>;
+    /**
+     * Broadcast a transaction and returns an Observable. The observable will
+     * complete as soon as the transaction is in a finalized block.
+     *
+     * @param transaction  SCALE-encoded tx to broadcast.
+     * @param at           It can be a block hash, `"finalized"`, or `"best"`.
+     *                     That block will be used to verify the validity of
+     *                     the tx, retrieve the next nonce,
+     *                     and create the mortality taking that block into
+     *                     account.
+     */
+    submitAndWatch: (transaction: HexString, at?: HexString) => Observable<TxBroadcastEvent>;
+    /**
+     * Returns an instance of a `TypedApi`
+     *
+     * @param descriptors  Pass descriptors from `@polkadot-api/descriptors`
+     *                     generated by `papi` CLI.
+     */
+    getTypedApi: <D extends ChainDefinition>(descriptors: D) => TypedApi<D>;
     destroy: () => void;
+    /**
+     * This API is meant as an "escape hatch" to allow access to debug endpoints
+     * such as `system_version`, and other useful endpoints that are not spec
+     * compliant.
+     *
+     * @example
+     *
+     *   const systemVersion = await client._request<string>("system_version", [])
+     *   const myFancyThhing = await client._request<
+     *     { value: string },
+     *     [id: number]
+     *   >("very_fancy", [1714])
+     *
+     */
+    _request: <Reply = any, Params extends Array<any> = any[]>(method: string, params: Params) => Promise<Reply>;
 }
 type FixedSizeArray<L extends number, T> = Array<T> & {
     length: L;
 };
 
+/**
+ * This is the top-level export for `polkadot-api`.
+ *
+ * @param provider  A `JsonRpcProvider` compliant with the [JSON-RPC
+ *                  spec](https://paritytech.github.io/json-rpc-interface-spec/),
+ *                  which must support the `chainHead`, `transaction` and
+ *                  `chainSpec` groups.
+ * @example
+ *
+ *   import { createClient } from "polkadot-api"
+ *   import { getSmProvider } from "polkadot-api/sm-provider"
+ *   import { chainSpec } from "polkadot-api/chains/polkadot"
+ *   import { start } from "polkadot-api/smoldot"
+ *
+ *   const smoldot = start()
+ *   const chain = await smoldot.addChain({ chainSpec })
+ *
+ *   // Connect to the polkadot relay chain.
+ *   const client = createClient(getSmProvider(chain))
+ *
+ */
 declare function createClient(provider: JsonRpcProvider): PolkadotClient;
 
-export { type EventPhase, type FixedSizeArray, type PolkadotClient, type Transaction, type TxBroadcastEvent, type TxEvent, type TxFinalizedPayload, type TypedApi, createClient };
+export { type ApisDescriptors, type ApisTypedef, type AssetDescriptor, type ChainDefinition, type ConstFromPalletsDef, type DescriptorEntry, type DescriptorsValue, type ErrorsFromPalletsDef, type EventPhase, type EventsFromPalletsDef, type FixedSizeArray, type PalletDescriptors, type PalletsTypedef, type PlainDescriptor, type PolkadotClient, type QueryFromPalletsDef, type RuntimeDescriptor, type StorageDescriptor, type Transaction, type TxBestBlocksState, type TxBroadcastEvent, type TxBroadcasted, type TxCall, type TxDescriptor, type TxEntry, type TxEvent, type TxEventsPayload, type TxFinalized, type TxFinalizedPayload, type TxFromPalletsDef, type TxInBestBlocksFound, type TxInBestBlocksNotFound, type TxObservable, type TxOptions, type TxPromise, type TxSignFn, type TxSigned, type TypedApi, createClient, createTxEntry, submit, submit$ };