polkadot-api 0.7.2 → 0.9.0

package/dist/index.d.mts

@@ -4,6 +4,8 @@ import { HexString, Binary, SS58String, Enum, BlockHeader } from '@polkadot-api/
 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 { DescriptorValues } from '@polkadot-api/codegen';
+export { DescriptorValues } from '@polkadot-api/codegen';
 import { PolkadotSigner } from '@polkadot-api/polkadot-signer';
 export { PolkadotSigner } from '@polkadot-api/polkadot-signer';
 
@@ -23,13 +25,6 @@ type TxDescriptor<Args extends {} | undefined> = {
 };
 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;
@@ -37,14 +32,10 @@ type PalletsTypedef<St extends DescriptorEntry<StorageDescriptor<any, any, any>>
     __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> & {
+    descriptors: Promise<DescriptorValues> & {
         pallets: PalletsTypedef<any, any, any, any, any>;
         apis: ApisTypedef<any>;
     };
@@ -77,11 +68,11 @@ type ErrorsFromPalletsDef<T extends PalletsTypedef<any, any, any, any, any>> = E
 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
+    Storage = "storage",
+    Tx = "tx",
+    Event = "events",
+    Error = "errors",
+    Const = "constants"
 }
 declare class Runtime {
     private _ctx;
@@ -91,7 +82,7 @@ declare class Runtime {
     /**
      * @access package  - Internal implementation detail. Do not use.
      */
-    static _create(ctx: RuntimeContext, checksums: string[], descriptors: DescriptorsValue): Runtime;
+    static _create(ctx: RuntimeContext, checksums: string[], descriptors: DescriptorValues): Runtime;
     /**
      * @access package  - Internal implementation detail. Do not use.
      */
@@ -106,10 +97,28 @@ declare class Runtime {
     _getApiChecksum(name: string, method: string): string;
 }
 type RuntimeApi = Observable<Runtime> & {
+    /**
+     * @returns Promise that resolves in the `Runtime` as soon as it's
+     *          loaded.
+     */
     latest: () => Promise<Runtime>;
 };
 interface IsCompatible {
+    /**
+     * `isCompatible` enables you to check whether or not the call you're trying
+     * to make is compatible with the descriptors you generated on dev time.
+     * In this case the function waits for `Runtime` to load, and returns
+     * asynchronously.
+     *
+     * @returns Promise that resolves with the result of the compatibility
+     *          check.
+     */
     (): Promise<boolean>;
+    /**
+     * Passing the runtime makes the function to return synchronously.
+     *
+     * @returns Result of the compatibility check.
+     */
     (runtime: Runtime): boolean;
 }
 declare const compatibilityHelper: (runtimeApi: RuntimeApi, getDescriptorChecksum: (runtime: Runtime) => string) => (getChecksum: (ctx: RuntimeContext) => string | null) => {
@@ -121,8 +130,21 @@ declare const compatibilityHelper: (runtimeApi: RuntimeApi, getDescriptorChecksu
 type CompatibilityHelper = ReturnType<typeof compatibilityHelper>;
 
 interface ConstantEntry<T> {
+    /**
+     * Constants are simple key-value structures found in the runtime metadata.
+     *
+     * @returns Promise that will resolve in the value of the constant.
+     */
     (): Promise<T>;
+    /**
+     * @param runtime  Runtime from got with `typedApi.runtime`
+     * @returns Synchronously returns value of the constant.
+     */
     (runtime: Runtime): T;
+    /**
+     * `isCompatible` enables you to check whether or not the call you're trying
+     * to make is compatible with the descriptors you generated on dev time.
+     */
     isCompatible: IsCompatible;
 }
 
@@ -150,9 +172,30 @@ type EvPull<T> = () => Promise<Array<{
 }>>;
 type EvFilter<T> = (collection: SystemEvent["event"][]) => Array<T>;
 type EvClient<T> = {
+    /**
+     * Multicast and stateful Observable watching for new events (matching the
+     * event kind chosen) in the latest known `finalized` block.
+     *
+     * @param filter  Optional filter function to only emit events complying
+     *                with the function.
+     */
     watch: EvWatch<T>;
+    /**
+     * Fetch (Promise-based) all events (matching the event kind chosen) available
+     * in the latest known `finalized` block.
+     */
     pull: EvPull<T>;
+    /**
+     * Filter a bunch of `SystemEvent` and return the decoded `payload` of every
+     * of them.
+     *
+     * @param collection  Array of `SystemEvent` to filter.
+     */
     filter: EvFilter<T>;
+    /**
+     * `isCompatible` enables you to check whether or not the call you're trying
+     * to make is compatible with the descriptors you generated on dev time.
+     */
     isCompatible: IsCompatible;
 };
 type SystemEvent = {
@@ -173,12 +216,31 @@ type CallOptions$1 = Partial<{
 }>;
 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> {
+    /**
+     * Get `Payload` (Promise-based) for the runtime call.
+     *
+     * @param args  All keys needed for that runtime call.
+     *              At the end, optionally set which block to target (latest
+     *              known finalized is the default) and an AbortSignal.
+     */
     (...args: WithCallOptions$1<Args>): Promise<Payload>;
+    /**
+     * `isCompatible` enables you to check whether or not the call you're trying
+     * to make is compatible with the descriptors you generated on dev time.
+     */
     isCompatible: IsCompatible;
 }
 
 type CallOptions = Partial<{
+    /**
+     * `at` could be a blockHash, `best`, or `finalized` (default)
+     */
     at: string;
+    /**
+     * `signal` allows you to abort an ongoing Promise. See [MDN
+     * docs](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) for
+     * more information
+     */
     signal: AbortSignal;
 }>;
 type WithCallOptions<Args extends Array<any>> = [
@@ -187,15 +249,73 @@ type WithCallOptions<Args extends Array<any>> = [
 ];
 type PossibleParents<A extends Array<any>> = A extends [...infer Left, any] ? Left | PossibleParents<Left> : [];
 type StorageEntryWithoutKeys<Payload> = {
+    /**
+     * `isCompatible` enables you to check whether or not the call you're trying
+     * to make is compatible with the descriptors you generated on dev time.
+     */
     isCompatible: IsCompatible;
+    /**
+     * Get `Payload` (Promise-based) for the storage entry.
+     *
+     * @param options  Optionally set which block to target (latest known
+     *                 finalized is the default) and an AbortSignal.
+     */
     getValue: (options?: CallOptions) => Promise<Payload>;
+    /**
+     * Watch changes in `Payload` (observable-based) for the storage entry.
+     *
+     * @param bestOrFinalized  Optionally choose which block to query and watch
+     *                         changes, `best` or `finalized` (default)
+     */
     watchValue: (bestOrFinalized?: "best" | "finalized") => Observable<Payload>;
 };
 type StorageEntryWithKeys<Args extends Array<any>, Payload> = {
+    /**
+     * `isCompatible` enables you to check whether or not the call you're trying
+     * to make is compatible with the descriptors you generated on dev time.
+     */
     isCompatible: IsCompatible;
+    /**
+     * Get `Payload` (Promise-based) for the storage entry with a specific set of
+     * `Args`.
+     *
+     * @param args  All keys needed for that storage entry.
+     *              At the end, optionally set which block to target (latest
+     *              known finalized is the default) and an AbortSignal.
+     */
     getValue: (...args: [...WithCallOptions<Args>]) => Promise<Payload>;
+    /**
+     * Watch changes in `Payload` (observable-based) for the storage entry.
+     *
+     * @param args  All keys needed for that storage entry.
+     *              At the end, optionally choose which block to query and
+     *              watch changes, `best` or `finalized` (default)
+     */
     watchValue: (...args: [...Args, bestOrFinalized?: "best" | "finalized"]) => Observable<Payload>;
+    /**
+     * Get an Array of `Payload` (Promise-based) for the storage entry with
+     * several sets of `Args`.
+     *
+     * @param keys     Array of sets of keys needed for the storage entry.
+     * @param options  Optionally set which block to target (latest known
+     *                 finalized is the default) and an AbortSignal.
+     */
     getValues: (keys: Array<[...Args]>, options?: CallOptions) => Promise<Array<Payload>>;
+    /**
+     * Get an Array of `Payload` (Promise-based) for the storage entry with a
+     * subset of `Args`.
+     *
+     * @param args  Subset of keys needed for the storage entry.
+     *              At the end, optionally set which block to target (latest
+     *              known finalized is the default) and an AbortSignal.
+     * @example
+     *
+     *   // this is a query with 3 keys
+     *   typedApi.query.Pallet.Query.getEntries({ at: "best" }) // no keys
+     *   typedApi.query.Pallet.Query.getEntries(arg1, { at: "finalized" }) // 1/3 keys
+     *   typedApi.query.Pallet.Query.getEntries(arg1, arg2, { at: "0x12345678" }) // 2/3 keys
+     *
+     */
     getEntries: (...args: WithCallOptions<PossibleParents<Args>>) => Promise<Array<{
         keyArgs: Args;
         value: NonNullable<Payload>;
@@ -225,10 +345,23 @@ type TxInBestBlocksFound = {
     found: true;
 } & TxEventsPayload;
 type TxEventsPayload = {
+    /**
+     * Verify if extrinsic was successful, i.e. check if `System.ExtrinsicSuccess`
+     * is found.
+     */
     ok: boolean;
+    /**
+     * Array of all events emitted by the tx. Ordered as they are emitted
+     * on-chain.
+     */
     events: Array<SystemEvent$1["event"]>;
+    /**
+     * Block information where the tx is found. `hash` of the block, `number` of
+     * the block, `index` of the tx in the block.
+     */
     block: {
         hash: string;
+        number: number;
         index: number;
     };
 };
@@ -237,41 +370,125 @@ type TxFinalized = {
     txHash: HexString;
 } & TxEventsPayload;
 type TxOptions<Asset> = Partial<void extends Asset ? {
+    /**
+     * Block to target the transaction against. Default: `"finalized"`
+     */
     at: HexString | "best" | "finalized";
+    /**
+     * Tip in fundamental units. Default: `0`
+     */
     tip: bigint;
+    /**
+     * Mortality of the transaction. Default: `{ mortal: true, period: 64 }`
+     */
     mortality: {
         mortal: false;
     } | {
         mortal: true;
         period: number;
     };
+    /**
+     * Custom nonce for the transaction. Default: retrieve from latest known
+     * finalized block.
+     */
     nonce: number;
 } : {
+    /**
+     * Block to target the transaction against. Default: `"finalized"`
+     */
     at: HexString | "best" | "finalized";
+    /**
+     * Tip in fundamental units. Default: `0`
+     */
     tip: bigint;
+    /**
+     * Mortality of the transaction. Default: `{ mortal: true, period: 64 }`
+     */
     mortality: {
         mortal: false;
     } | {
         mortal: true;
         period: number;
     };
+    /**
+     * Asset information to pay fees, tip, etc. By default it'll use the
+     * native token of the chain.
+     */
     asset: Asset;
+    /**
+     * Custom nonce for the transaction. Default: retrieve from latest known
+     * finalized block.
+     */
     nonce: number;
 }>;
 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 {
+    /**
+     * SCALE-encoded callData of the transaction.
+     *
+     * @returns Promise resolving in the encoded data.
+     */
     (): Promise<Binary>;
+    /**
+     * SCALE-encoded callData of the transaction.
+     *
+     * @param runtime  Runtime from got with `typedApi.runtime`
+     * @returns Synchronously returns encoded data.
+     */
     (runtime: Runtime): Binary;
 }
 type TxSignFn<Asset> = (from: PolkadotSigner, txOptions?: TxOptions<Asset>) => Promise<HexString>;
 type Transaction<Arg extends {} | undefined, Pallet extends string, Name extends string, Asset> = {
+    /**
+     * Pack the transaction, sends it to the signer, and return the signature
+     * asynchronously. If the signer fails (or the user cancels the signature)
+     * it'll throw an error.
+     *
+     * @param from       `PolkadotSigner`-compliant signer.
+     * @param txOptions  Optionally pass any number of txOptions.
+     * @returns Encoded `SignedExtrinsic` ready for broadcasting.
+     */
     sign: TxSignFn<Asset>;
+    /**
+     * Observable-based all-in-one transaction submitting. It will sign,
+     * broadcast, and track the transaction. The observable is singlecast, i.e.
+     * it will sign, broadcast, etc at every subscription. It will complete once
+     * the transaction is found in a `finalizedBlock`.
+     *
+     * @param from       `PolkadotSigner`-compliant signer.
+     * @param txOptions  Optionally pass any number of txOptions.
+     * @returns Observable to the transaction.
+     */
     signSubmitAndWatch: TxObservable<Asset>;
+    /**
+     * Pack the transaction, sends it to the signer, broadcast, and track the
+     * transaction. The promise will resolve as soon as the transaction in found
+     * in a `finalizedBlock`. If the signer fails (or the user cancels the
+     * signature), or the transaction becomes invalid it'll throw an error.
+     *
+     * @param from       `PolkadotSigner`-compliant signer.
+     * @param txOptions  Optionally pass any number of txOptions.
+     * @returns Finalized transaction information.
+     */
     signAndSubmit: TxPromise<Asset>;
+    /**
+     * SCALE-encoded callData of the transaction.
+     */
     getEncodedData: TxCall;
+    /**
+     * Estimate fees against the latest known `finalizedBlock`
+     *
+     * @param from       Public key or address from the potencial sender.
+     * @param txOptions  Optionally pass any number of txOptions.
+     * @returns Fees in fundamental units.
+     */
     getEstimatedFees: (from: Uint8Array | SS58String, txOptions?: TxOptions<Asset>) => Promise<bigint>;
+    /**
+     * PAPI way of expressing an extrinsic with arguments.
+     * It's useful to pass as a parameter to extrinsics that accept calls.
+     */
     decodedCall: Enum<{
         [P in Pallet]: Enum<{
             [N in Name]: Arg;
@@ -279,7 +496,18 @@ type Transaction<Arg extends {} | undefined, Pallet extends string, Name extends
     }>;
 };
 interface TxEntry<Arg extends {} | undefined, Pallet extends string, Name extends string, Asset> {
+    /**
+     * Synchronously create the transaction object ready to sign, submit, estimate
+     * fees, etc.
+     *
+     * @param args  All parameters required by the transaction.
+     * @returns Transaction object.
+     */
     (...args: Arg extends undefined ? [] : [data: Arg]): Transaction<Arg, Pallet, Name, Asset>;
+    /**
+     * `isCompatible` enables you to check whether or not the call you're trying
+     * to make is compatible with the descriptors you generated on dev time.
+     */
     isCompatible: IsCompatible;
 }
 
@@ -331,8 +559,8 @@ type TypedApi<D extends ChainDefinition> = {
 };
 interface PolkadotClient {
     /**
-     * Retrieve the ChainSpecData as it comes from the
-     * [JSON-RPC spec](https://paritytech.github.io/json-rpc-interface-spec/api/chainSpec.html)
+     * 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>;
     /**
@@ -417,6 +645,10 @@ interface PolkadotClient {
      *                     generated by `papi` CLI.
      */
     getTypedApi: <D extends ChainDefinition>(descriptors: D) => TypedApi<D>;
+    /**
+     * This will `unfollow` the provider, disconnect and error every subscription.
+     * After calling it nothing can be done with the client.
+     */
     destroy: () => void;
     /**
      * This API is meant as an "escape hatch" to allow access to debug endpoints
@@ -461,4 +693,4 @@ type FixedSizeArray<L extends number, T> = Array<T> & {
  */
 declare function createClient(provider: JsonRpcProvider): PolkadotClient;
 
-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$ };
+export { type ApisTypedef, type AssetDescriptor, type ChainDefinition, type ConstFromPalletsDef, type DescriptorEntry, type ErrorsFromPalletsDef, type EventPhase, type EventsFromPalletsDef, type FixedSizeArray, 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$ };