polkadot-api 0.8.0 → 0.9.0

package/dist/index.d.mts

@@ -345,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;
     };
 };
@@ -357,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;
@@ -399,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;
 }
 
@@ -537,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

package/dist/index.d.ts

@@ -345,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;
     };
 };
@@ -357,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;
@@ -399,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;
 }
 
@@ -537,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

package/dist/index.js

@@ -54,8 +54,7 @@ var createConstantEntry = (palletName, name, chainHead, compatibilityHelper2) =>
   };
   const fn = (runtime) => {
     if (runtime) {
-      if (!isCompatible(runtime))
-        throw checksumError();
+      if (!isCompatible(runtime)) throw checksumError();
       return getValueWithContext(runtime._getCtx());
     }
     return (0, import_rxjs.firstValueFrom)(
@@ -105,8 +104,7 @@ function firstValueFromWithSignal(source, signal) {
         reject(new Error("Observable completed without emitting"));
       }
     });
-    if (!isDone)
-      signal?.addEventListener("abort", onAbort);
+    if (!isDone) signal?.addEventListener("abort", onAbort);
   });
 }
 
@@ -231,8 +229,7 @@ var raceMap = (mapper, concurrent) => (source$) => new import_rxjs5.Observable((
       observer.error(err);
     },
     complete() {
-      if (innerSubscriptions.length === 0)
-        observer.complete();
+      if (innerSubscriptions.length === 0) observer.complete();
       isOuterDone = true;
     }
   });
@@ -255,10 +252,8 @@ var continueWith = (mapper) => (source) => new import_rxjs6.Observable((observer
       observer.error(e);
     },
     complete() {
-      if (latestValue === NOTIN)
-        observer.complete();
-      else
-        subscription = mapper(latestValue).subscribe(observer);
+      if (latestValue === NOTIN) observer.complete();
+      else subscription = mapper(latestValue).subscribe(observer);
     }
   });
   return () => {
@@ -396,8 +391,7 @@ var compatibilityHelper = (runtimeApi, getDescriptorChecksum) => (getChecksum) =
 var import_utils4 = require("@polkadot-api/utils");
 var import_rxjs9 = require("rxjs");
 var isOptionalArg = (lastArg) => {
-  if (typeof lastArg !== "object")
-    return false;
+  if (typeof lastArg !== "object") return false;
   return Object.keys(lastArg).every(
     (k) => k === "at" && typeof lastArg.at === "string" || k === "signal" && lastArg.signal instanceof AbortSignal
   );
@@ -428,8 +422,7 @@ var createRuntimeCallEntry = (api, method, chainHead, compatibilityHelper2) => {
 var import_rxjs10 = require("rxjs");
 var import_observable_client = require("@polkadot-api/observable-client");
 var isOptionalArg2 = (lastArg) => {
-  if (typeof lastArg !== "object")
-    return false;
+  if (typeof lastArg !== "object") return false;
   return Object.keys(lastArg).every(
     (k) => k === "at" && typeof lastArg.at === "string" || k === "signal" && lastArg.signal instanceof AbortSignal
   );
@@ -469,15 +462,12 @@ var createStorageEntry = (pallet, name, chainHead, compatibilityHelper2) => {
     if (isSystemNumber) {
       result$ = chainHead.bestBlocks$.pipe(
         (0, import_rxjs10.map)((blocks) => {
-          if (at === "finalized" || !at)
-            return blocks.at(-1);
-          if (at === "best")
-            return blocks.at(0);
+          if (at === "finalized" || !at) return blocks.at(-1);
+          if (at === "best") return blocks.at(0);
           return blocks.find((block) => block.hash === at);
         }),
         (0, import_rxjs10.map)((block) => {
-          if (!block)
-            throw new import_observable_client.NotBestBlockError();
+          if (!block) throw new import_observable_client.NotBestBlockError();
           return block.number;
         }),
         (0, import_rxjs10.distinctUntilChanged)()
@@ -488,12 +478,10 @@ var createStorageEntry = (pallet, name, chainHead, compatibilityHelper2) => {
         at,
         "value",
         (ctx) => {
-          if (!isCompatible2(ctx))
-            throw checksumError();
+          if (!isCompatible2(ctx)) throw checksumError();
           const codecs = ctx.dynamicBuilder.buildStorage(pallet, name);
           const actualArgs = args.length === codecs.len ? args : args.slice(0, -1);
-          if (args !== actualArgs && !isLastArgOptional)
-            throw invalidArgs(args);
+          if (args !== actualArgs && !isLastArgOptional) throw invalidArgs(args);
           return codecs.enc(...actualArgs);
         },
         null,
@@ -515,11 +503,9 @@ var createStorageEntry = (pallet, name, chainHead, compatibilityHelper2) => {
       at,
       "descendantsValues",
       (ctx) => {
-        if (!isCompatible2(ctx))
-          throw checksumError();
+        if (!isCompatible2(ctx)) throw checksumError();
         const codecs = ctx.dynamicBuilder.buildStorage(pallet, name);
-        if (args.length > codecs.len)
-          throw invalidArgs(args);
+        if (args.length > codecs.len) throw invalidArgs(args);
         const actualArgs = args.length > 0 && isLastArgOptional ? args.slice(0, -1) : args;
         if (args.length === codecs.len && actualArgs === args)
           throw invalidArgs(args);
@@ -572,8 +558,7 @@ var systemVersionProp$ = (propName, metadata) => {
   const constant = metadata.pallets.find((x) => x.name === "System").constants.find((s) => s.name === "Version");
   const systemVersion = lookupFn(constant.type);
   const systemVersionDec = dynamicBuilder.buildDefinition(constant.type).dec;
-  if (systemVersion.type !== "struct")
-    throw new Error("not a struct");
+  if (systemVersion.type !== "struct") throw new Error("not a struct");
   const valueEnc = dynamicBuilder.buildDefinition(
     systemVersion.value[propName].id
   ).enc;
@@ -769,30 +754,27 @@ var computeState = (analized$, blocks$) => new import_rxjs21.Observable((observe
     let analyzed = analyzedBlocks.get(current);
     while (!analyzed) {
       const block = pinnedBlocks.blocks.get(current);
-      if (!block)
-        break;
+      if (!block) break;
       analyzed = analyzedBlocks.get(current = block.parent);
     }
-    if (!analyzed)
-      return;
-    const isFinalized = pinnedBlocks.blocks.get(analyzed.hash).number <= pinnedBlocks.blocks.get(pinnedBlocks.finalized).number;
+    if (!analyzed) return;
+    const analyzedNumber = pinnedBlocks.blocks.get(analyzed.hash).number;
+    const isFinalized = analyzedNumber <= pinnedBlocks.blocks.get(pinnedBlocks.finalized).number;
     const found = analyzed.found.type;
     if (found && typeof latestState === "object" && latestState.hash === analyzed.hash) {
-      if (isFinalized)
-        observer.complete();
+      if (isFinalized) observer.complete();
       return;
     }
     observer.next(
       latestState = found ? {
         hash: analyzed.hash,
+        number: analyzedNumber,
         ...analyzed.found
       } : analyzed.found.isValid
     );
     if (isFinalized) {
-      if (found)
-        observer.complete();
-      else if (!analyzed.found.isValid)
-        observer.error(new Error("Invalid"));
+      if (found) observer.complete();
+      else if (!analyzed.found.isValid) observer.error(new Error("Invalid"));
     }
   };
   const subscription = blocks$.pipe(
@@ -802,8 +784,7 @@ var computeState = (analized$, blocks$) => new import_rxjs21.Observable((observe
   ).subscribe({
     next: (pinned) => {
       pinnedBlocks = pinned;
-      if (analyzedBlocks.size === 0)
-        return;
+      if (analyzedBlocks.size === 0) return;
       computeNextState();
     },
     error(e) {
@@ -872,6 +853,7 @@ var submit$ = (chainHead, broadcastTx$, tx, at, emitSign = false) => {
         found: true,
         block: {
           index: x.index,
+          number: x.number,
           hash: x.hash
         },
         ...getTxSuccessFromSystemEvents(x.events, x.index)
@@ -890,8 +872,7 @@ var submit$ = (chainHead, broadcastTx$, tx, at, emitSign = false) => {
   );
 };
 var submit = async (chainHead, broadcastTx$, transaction, at) => (0, import_rxjs21.lastValueFrom)(submit$(chainHead, broadcastTx$, transaction, at)).then((x) => {
-  if (x.type !== "finalized")
-    throw null;
+  if (x.type !== "finalized") throw null;
   const result = { ...x };
   delete result.type;
   return result;
@@ -930,8 +911,7 @@ var createTxEntry = (pallet, name, assetChecksum, chainHead, broadcast, compatib
     const getEncodedData = (runtime) => {
       if (!runtime)
         return (0, import_rxjs22.firstValueFrom)(getCallData$(arg).pipe((0, import_rxjs22.map)((x) => x.callData)));
-      if (!isCompatible(runtime))
-        throw checksumError();
+      if (!isCompatible(runtime)) throw checksumError();
       return getCallDataWithContext(runtime._getCtx(), arg).callData;
     };
     const sign$ = (from, { ..._options }, atBlock) => getCallData$(arg, _options).pipe(
@@ -1006,11 +986,9 @@ var createTypedApi = (chainDefinition, chainHead, broadcast$) => {
   const createProxyPath = (pathCall) => {
     const cache = {};
     return createProxy((a) => {
-      if (!cache[a])
-        cache[a] = {};
+      if (!cache[a]) cache[a] = {};
       return createProxy((b) => {
-        if (!cache[a][b])
-          cache[a][b] = pathCall(a, b);
+        if (!cache[a][b]) cache[a][b] = pathCall(a, b);
         return cache[a][b];
       });
     });