@pezkuwi/api 16.5.6 → 16.5.8

package/build/types/index.d.ts

@@ -0,0 +1,114 @@
+import type { ApiTypes, DeriveCustom, QueryableStorageMulti } from '@pezkuwi/api-base/types';
+import type { ApiInterfaceRx as ApiInterfaceBase } from '@pezkuwi/api-base/types/api';
+import type { QueryableCalls } from '@pezkuwi/api-base/types/calls';
+import type { QueryableConsts } from '@pezkuwi/api-base/types/consts';
+import type { DecoratedErrors } from '@pezkuwi/api-base/types/errors';
+import type { DecoratedEvents } from '@pezkuwi/api-base/types/events';
+import type { QueryableStorage } from '@pezkuwi/api-base/types/storage';
+import type { ProviderInterface, ProviderInterfaceEmitted } from '@pezkuwi/rpc-provider/types';
+import type { ExtDef } from '@pezkuwi/types/extrinsic/signedExtensions/types';
+import type { Call, Extrinsic, Hash, RuntimeVersionPartial } from '@pezkuwi/types/interfaces';
+import type { CallFunction, DefinitionRpc, DefinitionRpcSub, DefinitionsCall, RegisteredTypes, Registry, RegistryError, SignatureOptions, Signer } from '@pezkuwi/types/types';
+import type { BN } from '@pezkuwi/util';
+import type { HexString } from '@pezkuwi/util/types';
+import type { ApiBase } from '../base/index.js';
+import type { SubmittableExtrinsic } from '../types/submittable.js';
+import type { AllDerives } from '../util/decorate.js';
+export type { Signer, SignerResult } from '@pezkuwi/types/types';
+export { ApiBase } from '../base/index.js';
+export * from '@pezkuwi/api/types/calls';
+export * from '@pezkuwi/api/types/consts';
+export * from '@pezkuwi/api/types/errors';
+export * from '@pezkuwi/api/types/events';
+export * from '@pezkuwi/api/types/storage';
+export * from '@pezkuwi/api/types/submittable';
+export * from '@pezkuwi/api-base/types';
+export interface ApiInterfaceRx extends ApiInterfaceBase {
+    derive: AllDerives<'rxjs'>;
+}
+export interface ApiOptions extends RegisteredTypes {
+    /**
+     * @description Add custom derives to be injected
+     */
+    derives?: DeriveCustom;
+    /**
+     * @description Control the initialization of the wasm libraries. When not specified, it defaults to `true`, initializing the wasm libraries, set to `false` to not initialize wasm. (No sr25519 support)
+     */
+    initWasm?: boolean;
+    /**
+     * @description Controls the checking of storage values once they have been contructed. When not specified this defaults to `true`. Set to `false` to forgo any checking on storage results.
+     */
+    isPedantic?: boolean;
+    /**
+     * @description pre-bundles is a map of 'genesis hash and runtime spec version' as key to a metadata hex string
+     * if genesis hash and runtime spec version matches, then use metadata, else fetch it from chain
+     */
+    metadata?: Record<string, HexString>;
+    /**
+     * @description Don't display any warnings on initialization (missing RPC methods & runtime calls)
+     */
+    noInitWarn?: boolean;
+    /**
+     * @description Transport Provider from rpc-provider. If not specified, it will default to
+     * connecting to a WsProvider connecting localhost with the default port, i.e. `ws://127.0.0.1:9944`
+     */
+    provider?: ProviderInterface;
+    /**
+     * @description A type registry to use along with this instance
+     */
+    registry?: Registry;
+    /**
+     * @description User-defined RPC methods
+     */
+    rpc?: Record<string, Record<string, DefinitionRpc | DefinitionRpcSub>>;
+    /**
+     * @description Defines the size of the cache for the rpc-core. Defaults to 1024 * 10 * 10.
+     */
+    rpcCacheCapacity?: number;
+    /**
+     * @description Overrides for state_call usage (this will be removed in some future version)
+     */
+    runtime?: DefinitionsCall;
+    /**
+     * @description Any chain-specific signed extensions that are now well-known
+     */
+    signedExtensions?: ExtDef;
+    /**
+     * @description An external signer which will be used to sign extrinsic when account passed in is not KeyringPair
+     */
+    signer?: Signer;
+    /**
+     * @description The source object to use for runtime information (only used when cloning)
+     */
+    source?: ApiBase<any>;
+    /**
+     * @description Throws an error when the initial connection fails (same as isReadyOrError)
+     */
+    throwOnConnect?: boolean;
+    /**
+     * @description Throws an error when some types are unknown (useful with throwOnConnect)
+     */
+    throwOnUnknown?: boolean;
+}
+export type ApiInterfaceEvents = ProviderInterfaceEmitted | 'ready' | 'decorated';
+export interface SignerOptions extends SignatureOptions {
+    blockNumber: BN;
+    genesisHash: Hash;
+}
+export interface ApiDecoration<ApiType extends ApiTypes> {
+    call: QueryableCalls<ApiType>;
+    consts: QueryableConsts<ApiType>;
+    errors: DecoratedErrors<ApiType>;
+    events: DecoratedEvents<ApiType>;
+    query: QueryableStorage<ApiType>;
+    registry: Registry;
+    runtimeVersion: RuntimeVersionPartial;
+    rx: {
+        call: QueryableCalls<'rxjs'>;
+        query: QueryableStorage<'rxjs'>;
+    };
+    tx: (extrinsic: Call | Extrinsic | Uint8Array | string) => SubmittableExtrinsic<ApiType>;
+    findCall(callIndex: Uint8Array | string): CallFunction;
+    findError(errorIndex: Uint8Array | string): RegistryError;
+    queryMulti: QueryableStorageMulti<ApiType>;
+}

package/build/types/index.js

@@ -0,0 +1,8 @@
+export { ApiBase } from '../base/index.js';
+export * from '@pezkuwi/api/types/calls';
+export * from '@pezkuwi/api/types/consts';
+export * from '@pezkuwi/api/types/errors';
+export * from '@pezkuwi/api/types/events';
+export * from '@pezkuwi/api/types/storage';
+export * from '@pezkuwi/api/types/submittable';
+export * from '@pezkuwi/api-base/types';

package/build/types/storage.d.ts

@@ -0,0 +1 @@
+export * from '@pezkuwi/api-base/types/storage';

package/build/types/storage.js

@@ -0,0 +1 @@
+export * from '@pezkuwi/api-base/types/storage';

package/build/types/submittable.d.ts

@@ -0,0 +1 @@
+export * from '@pezkuwi/api-base/types/submittable';

package/build/types/submittable.js

@@ -0,0 +1 @@
+export * from '@pezkuwi/api-base/types/submittable';

package/build/util/augmentObject.d.ts

@@ -0,0 +1,9 @@
+type Sections<T> = Record<string, Methods<T>>;
+type Methods<T> = Record<string, T>;
+/**
+ * @description Takes a decorated api section (e.g. api.tx) and augment it with the details. It does not override what is
+ * already available, but rather just adds new missing items into the result object.
+ * @internal
+ */
+export declare function augmentObject<T>(prefix: string | null, src: Sections<T>, dst: Sections<T>, fromEmpty?: boolean): Sections<T>;
+export {};

package/build/util/augmentObject.js

@@ -0,0 +1,81 @@
+import { lazyMethods, logger, objectClear } from '@pezkuwi/util';
+const l = logger('api/augment');
+function logLength(type, values, and = []) {
+    return values.length
+        ? ` ${values.length} ${type}${and.length ? ' and' : ''}`
+        : '';
+}
+function logValues(type, values) {
+    return values.length
+        ? `\n\t${type.padStart(7)}: ${values.sort().join(', ')}`
+        : '';
+}
+function warn(prefix, type, [added, removed]) {
+    if (added.length || removed.length) {
+        l.warn(`api.${prefix}: Found${logLength('added', added, removed)}${logLength('removed', removed)} ${type}:${logValues('added', added)}${logValues('removed', removed)}`);
+    }
+}
+function findSectionExcludes(a, b) {
+    return a.filter((s) => !b.includes(s));
+}
+function findSectionIncludes(a, b) {
+    return a.filter((s) => b.includes(s));
+}
+function extractSections(src, dst) {
+    const srcSections = Object.keys(src);
+    const dstSections = Object.keys(dst);
+    return [
+        findSectionExcludes(srcSections, dstSections),
+        findSectionExcludes(dstSections, srcSections)
+    ];
+}
+function findMethodExcludes(src, dst) {
+    const srcSections = Object.keys(src);
+    const dstSections = findSectionIncludes(Object.keys(dst), srcSections);
+    const excludes = [];
+    for (let s = 0, scount = dstSections.length; s < scount; s++) {
+        const section = dstSections[s];
+        const srcMethods = Object.keys(src[section]);
+        const dstMethods = Object.keys(dst[section]);
+        for (let d = 0, mcount = dstMethods.length; d < mcount; d++) {
+            const method = dstMethods[d];
+            if (!srcMethods.includes(method)) {
+                excludes.push(`${section}.${method}`);
+            }
+        }
+    }
+    return excludes;
+}
+function extractMethods(src, dst) {
+    return [
+        findMethodExcludes(dst, src),
+        findMethodExcludes(src, dst)
+    ];
+}
+/**
+ * @description Takes a decorated api section (e.g. api.tx) and augment it with the details. It does not override what is
+ * already available, but rather just adds new missing items into the result object.
+ * @internal
+ */
+export function augmentObject(prefix, src, dst, fromEmpty = false) {
+    fromEmpty && objectClear(dst);
+    // NOTE: This part is slightly problematic since it will get the
+    // values for at least all the sections and the names of the methods
+    // (Since methods won't be decorated before lazy, this _may_ be ok)
+    if (prefix && Object.keys(dst).length) {
+        warn(prefix, 'modules', extractSections(src, dst));
+        warn(prefix, 'calls', extractMethods(src, dst));
+    }
+    const sections = Object.keys(src);
+    for (let i = 0, count = sections.length; i < count; i++) {
+        const section = sections[i];
+        const methods = src[section];
+        // We don't set here with a lazy interface, we decorate based
+        // on the top-level structure (this bypasses adding lazy onto lazy)
+        if (!dst[section]) {
+            dst[section] = {};
+        }
+        lazyMethods(dst[section], Object.keys(methods), (m) => methods[m]);
+    }
+    return dst;
+}

package/build/util/decorate.d.ts

@@ -0,0 +1,16 @@
+import type { ExactDerive } from '@pezkuwi/api-derive';
+import type { AnyFunction } from '@pezkuwi/types/types';
+import type { ApiTypes, DecorateMethod, MethodResult } from '../types/index.js';
+type AnyDeriveSection = Record<string, AnyFunction>;
+type AnyDerive = Record<string, AnyDeriveSection>;
+type DeriveSection<ApiType extends ApiTypes, Section extends AnyDeriveSection> = {
+    [M in keyof Section]: MethodResult<ApiType, Section[M]>;
+};
+export type AllDerives<ApiType extends ApiTypes> = {
+    [S in keyof ExactDerive]: DeriveSection<ApiType, ExactDerive[S]>;
+};
+/**
+ * This is a section decorator which keeps all type information.
+ */
+export declare function decorateDeriveSections<ApiType extends ApiTypes>(decorateMethod: DecorateMethod<ApiType>, derives: AnyDerive): AllDerives<ApiType>;
+export {};

package/build/util/decorate.js

@@ -0,0 +1,14 @@
+import { lazyDeriveSection } from '@pezkuwi/api-derive';
+/**
+ * This is a section decorator which keeps all type information.
+ */
+export function decorateDeriveSections(decorateMethod, derives) {
+    const getKeys = (s) => Object.keys(derives[s]);
+    const creator = (s, m) => decorateMethod(derives[s][m]);
+    const result = {};
+    const names = Object.keys(derives);
+    for (let i = 0, count = names.length; i < count; i++) {
+        lazyDeriveSection(result, names[i], getKeys, creator);
+    }
+    return result;
+}

package/build/util/filterEvents.d.ts

@@ -0,0 +1,6 @@
+import type { BlockNumber, EventRecord, ExtrinsicStatus, H256, SignedBlock } from '@pezkuwi/types/interfaces';
+export declare function filterEvents(txHash: H256, { block: { extrinsics, header } }: SignedBlock, allEvents: EventRecord[], status: ExtrinsicStatus): {
+    events?: EventRecord[];
+    txIndex?: number;
+    blockNumber?: BlockNumber;
+};

package/build/util/filterEvents.js

@@ -0,0 +1,22 @@
+import { isCompact } from '@pezkuwi/util';
+import { l } from './logging.js';
+export function filterEvents(txHash, { block: { extrinsics, header } }, allEvents, status) {
+    // extrinsics to hashes
+    for (const [txIndex, x] of extrinsics.entries()) {
+        if (x.hash.eq(txHash)) {
+            return {
+                blockNumber: isCompact(header.number) ? header.number.unwrap() : header.number,
+                events: allEvents.filter(({ phase }) => phase.isApplyExtrinsic &&
+                    phase.asApplyExtrinsic.eqn(txIndex)),
+                txIndex
+            };
+        }
+    }
+    // if we do get the block after finalized, it _should_ be there
+    // only warn on filtering with isInBlock (finalization finalizes after)
+    if (status.isInBlock) {
+        const allHashes = extrinsics.map((x) => x.hash.toHex());
+        l.warn(`block ${header.hash.toHex()}: Unable to find extrinsic ${txHash.toHex()} inside ${allHashes.join(', ')}`);
+    }
+    return {};
+}

package/build/util/index.d.ts

@@ -0,0 +1,4 @@
+export { filterEvents } from './filterEvents.js';
+export { isKeyringPair } from './isKeyringPair.js';
+export { l } from './logging.js';
+export * from './decorate.js';

package/build/util/index.js

@@ -0,0 +1,4 @@
+export { filterEvents } from './filterEvents.js';
+export { isKeyringPair } from './isKeyringPair.js';
+export { l } from './logging.js';
+export * from './decorate.js';

package/build/util/isKeyringPair.d.ts

@@ -0,0 +1,3 @@
+import type { AccountId, Address } from '@pezkuwi/types/interfaces';
+import type { IKeyringPair } from '@pezkuwi/types/types';
+export declare function isKeyringPair(account: string | IKeyringPair | AccountId | Address): account is IKeyringPair;

package/build/util/isKeyringPair.js

@@ -0,0 +1,4 @@
+import { isFunction } from '@pezkuwi/util';
+export function isKeyringPair(account) {
+    return isFunction(account.sign);
+}

package/build/util/logging.d.ts

@@ -0,0 +1 @@
+export declare const l: import("@pezkuwi/util/types").Logger;

package/build/util/logging.js

@@ -0,0 +1,2 @@
+import { logger } from '@pezkuwi/util';
+export const l = /*#__PURE__*/ logger('api/util');

package/build/util/validate.d.ts

@@ -0,0 +1,3 @@
+import type { StorageEntry } from '@pezkuwi/types/primitive/types';
+import type { Registry } from '@pezkuwi/types/types';
+export declare function extractStorageArgs(registry: Registry, creator: StorageEntry, _args: unknown[]): [StorageEntry, unknown[]];

package/build/util/validate.js

@@ -0,0 +1,23 @@
+import { isUndefined } from '@pezkuwi/util';
+function sig({ lookup }, { method, section }, args) {
+    return `${section}.${method}(${args.map((a) => lookup.getTypeDef(a).type).join(', ')})`;
+}
+export function extractStorageArgs(registry, creator, _args) {
+    const args = _args.filter((a) => !isUndefined(a));
+    if (creator.meta.type.isPlain) {
+        if (args.length !== 0) {
+            throw new Error(`${sig(registry, creator, [])} does not take any arguments, ${args.length} found`);
+        }
+    }
+    else {
+        const { hashers, key } = creator.meta.type.asMap;
+        const keys = hashers.length === 1
+            ? [key]
+            : registry.lookup.getSiType(key).def.asTuple.map((t) => t);
+        if (args.length !== keys.length) {
+            throw new Error(`${sig(registry, creator, keys)} is a map, requiring ${keys.length} arguments, ${args.length} found`);
+        }
+    }
+    // pass as tuple
+    return [creator, args];
+}

package/build-deno/README.md

@@ -0,0 +1,95 @@
+# @pezkuwi/api
+
+The Pezkuwi-JS API provides easy-to-use wrappers around JSONRPC calls that flow from an application to a node. It handles all the encoding and decoding or parameters, provides access to RPC functions and allows for the query of chain state and the submission of transactions.
+
+The API wrappers provide a standard interface for use -
+
+- A static `.create(<optional ApiOptions>)` that returns an API instance when connected, decorated and ready-to use. ApiOptions can include an optional WsProvider and optional custom type definitions `{ provider: <Optional WsProvider>, types: <Optional RegistryTypes> }`.
+- The above is just a wrapper for `new Api(<optional ApiOptions>) `, exposing the `isReady` getter
+- `api.rpc.<section>.<method>` provides access to actual RPC calls, be it for queries, submission or retrieving chain information
+  - [RPC (node interface)](https://js.pezkuwichain.app/docs/bizinikiwi/rpc)
+- `api.query.<section>.<method>` provides access to chain state queries. These are dynamically populated based on what the runtime provides
+  - [Storage chain state (runtime node interface)](https://js.pezkuwichain.app/docs/bizinikiwi/storage)
+- `api.tx.<section>.<method>` provides the ability to create a transaction, like chain state, this list is populated from a runtime query
+  - [Extrinsics (runtime node interface)](https://js.pezkuwichain.app/docs/bizinikiwi/extrinsics)
+- `api.consts.<section>.<constant>` provides access to the module constants (parameter types).
+  - [Constants (runtime node interface)](https://js.pezkuwichain.app/docs/bizinikiwi/constants)
+
+## API Selection
+
+There are two flavours of the API provided, one allowing a standard interface via JavaScript Promises and the second provides an Observable wrapper using [RxJS](https://github.com/ReactiveX/rxjs). Depending on your use-case and familiarity, you can choose either (or even both) for your application.
+
+- [[ApiPromise]] All interface calls returns Promises, including the static `.create(...)`. Additionally any subscription method uses `(value) => {}` callbacks, returning the value as the subscription is updated.
+- [[ApiRx]] All interface calls return RxJS Observables, including the static `.create(...)`. In the same fashion subscription-based methods return long-running Observables that update with the latest values.
+
+## Dynamic by default
+
+Bizinikiwi (upon which Pezkuwi is built) uses on-chain WASM runtimes, allowing for upgradability. Each runtime defining the actual chain extrinsics (submitted transactions and block intrinsics) as well as available entries in the chain state. Due to this, the API endpoints for queries and transactions are dynamically populated from the running chain.
+
+Due to this dynamic nature, this API departs from traditional APIs which only has fixed endpoints, driving use by what is available by the runtime. As a start, this generic nature has a learning curve, although the provided documentation, examples and linked documentation tries to make that experience as seamless as possible.
+
+## Installation & import
+
+Installation -
+
+```
+npm install --save @pezkuwi/api
+```
+
+Subscribing to blocks via Promise-based API -
+
+```javascript
+import { ApiPromise } from 'https://deno.land/x/pezkuwi/api/mod.ts';
+
+const api = await ApiPromise.create();
+
+api.rpc.chain.subscribeNewHeads((header) => {
+  console.log(`Chain is at #${header.number}`);
+});
+```
+
+Subscribing to blocks via RxJS-based API -
+
+```javascript
+import { ApiRx } from 'https://deno.land/x/pezkuwi/api/mod.ts';
+
+const api = await ApiRx.create().toPromise();
+
+api.rpc.chain.subscribeNewHeads().subscribe((header) => {
+  console.log(`Chain is at #${header.number}`);
+});
+```
+
+## Registering custom types
+
+Additional types used by runtime modules can be added when a new instance of the API is created. This is necessary if the runtime modules use types which are not available in the base Bizinikiwi runtime.
+
+```javascript
+import { ApiPromise } from 'https://deno.land/x/pezkuwi/api/mod.ts';
+
+const api = await ApiPromise.create({
+  types: {
+    CustomTypesExample: {
+      "id": "u32",
+      "data": "Vec<u8>",
+      "deposit": "Balance",
+      "owner": "AccountId",
+      "application_expiry": "Moment",
+      "whitelisted": "bool",
+      "challenge_id": "u32"
+    }
+  }
+});
+```
+
+## Users
+
+Some of the users of the API (let us know if you are missing from the list), include -
+
+- [Pezkuwi-JS UI](https://github.com/pezkuwichain/pezkuwi-apps) A user-interface that allows you to make transactions, query the network or participate in actions on the network such as referendums and staking
+- [KodaDot](https://github.com/vue-pezkuwi/apps) ([twitter](https://twitter.com/KodaDot)) - Vue.js web wallet, governance dashboard and aspiring performance (lightweight) alternative to original apps, mobile-first.
+- [Polkabot](https://gitlab.com/Polkabot) Polkabot is a Matrix chatbot that keeps an eye on the Pezkuwi network. You can see Polkabot in action in https://matrix.to/#/#pezkuwi-network-status:matrix.org
+- [Polkawallet.io](https://polkawallet.io) and [Polkawallet (Github)](https://github.com/polkawallet-io/polkawallet-RN/) A mobile wallet for the Pezkuwi network to manage funds and make transactions, available on both Androind and iOS
+- [PolkaStats.io](https://polkastats.io), [PolkaStats frontend GitHub repository](https://github.com/Colm3na/polkastats-v2) and [PolkaStats backend GitHub repository](https://github.com/Colm3na/polkastats-backend-v2) Pezkuwi network statistics (currently Zagros and Alexander). Shows network information and staking details from validators and intentions.
+- [Pezkuwi API Server (GitHub)](https://github.com/SimplyVC/pezkuwi_api_server) A lightweight server for querying Pezkuwi nodes from any language, built primarily as a backend for [PANIC for Pezkuwi (GitHub)](https://github.com/SimplyVC/panic_pezkuwi/), a validator monitoring and alerting tool.
+- [Identity Registrar #1 from Chevdor on Zagros, Zagros and Pezkuwi](https://www.chevdor.com/tags/registrar/)

package/build-deno/augment.ts

@@ -0,0 +1,2 @@
+
+import 'https://deno.land/x/pezkuwi/api-augment/mod.ts';