@pezkuwi/api 16.5.6 → 16.5.8

package/src/types/events.ts

@@ -0,0 +1,4 @@
+// Copyright 2017-2025 @pezkuwi/api authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export * from '@pezkuwi/api-base/types/events';

package/src/types/index.ts

@@ -0,0 +1,137 @@
+// Copyright 2017-2025 @pezkuwi/api authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+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';
+
+// types
+export type { Signer, SignerResult } from '@pezkuwi/types/types';
+
+// all named
+export { ApiBase } from '../base/index.js';
+
+// all starred
+// eslint-disable-next-line import/export
+export * from '@pezkuwi/api/types/calls';
+// eslint-disable-next-line import/export
+export * from '@pezkuwi/api/types/consts';
+// eslint-disable-next-line import/export
+export * from '@pezkuwi/api/types/errors';
+// eslint-disable-next-line import/export
+export * from '@pezkuwi/api/types/events';
+// eslint-disable-next-line import/export
+export * from '@pezkuwi/api/types/storage';
+// eslint-disable-next-line import/export
+export * from '@pezkuwi/api/types/submittable';
+// eslint-disable-next-line import/export
+export * from '@pezkuwi/api-base/types';
+
+// A smaller interface of ApiRx, used in derive and in SubmittableExtrinsic
+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/src/types/storage.ts

@@ -0,0 +1,4 @@
+// Copyright 2017-2025 @pezkuwi/api-augment authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export * from '@pezkuwi/api-base/types/storage';

package/src/types/submittable.ts

@@ -0,0 +1,4 @@
+// Copyright 2017-2025 @pezkuwi/api-augment authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export * from '@pezkuwi/api-base/types/submittable';

package/src/util/augmentObject.spec.ts

@@ -0,0 +1,54 @@
+// Copyright 2017-2025 @pezkuwi/api authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { augmentObject } from './augmentObject.js';
+
+describe('augmentObject', (): void => {
+  let spy: ReturnType<typeof jest.spyOn>;
+
+  beforeEach((): void => {
+    spy = jest.spyOn(console, 'warn');
+  });
+
+  afterEach((): void => {
+    spy.mockRestore();
+  });
+
+  it('logs added/removed sections and methods', (): void => {
+    augmentObject(
+      'test',
+      { bar: { b: 1 }, foo: { d: 1, f: 1 }, new: { z: 1 } },
+      { bar: { a: 1, c: 1 }, baz: { a: 1 }, foo: { c: 1, f: 1 } }
+    );
+
+    expect(spy).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.stringMatching(/API\/AUGMENT/),
+      'api.test: Found 1 added and 1 removed modules:\n\t  added: new\n\tremoved: baz'
+    );
+    expect(spy).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.stringMatching(/API\/AUGMENT/),
+      'api.test: Found 2 added and 3 removed calls:\n\t  added: bar.b, foo.d\n\tremoved: bar.a, bar.c, foo.c'
+    );
+  });
+
+  it('copies sections to the dest', (): void => {
+    const src = { bar: { b: 1 }, foo: { a: 1 } };
+
+    expect(augmentObject('test', src, {})).toEqual(src);
+  });
+
+  it('adds fields to existing sections', (): void => {
+    const src = { bar: { b: 1 }, foo: { a: 1 } };
+    const dst = { baz: { c: 1 }, foo: { b: 2 } };
+
+    expect(augmentObject('test', src, dst)).toEqual({
+      bar: { b: 1 },
+      baz: { c: 1 },
+      foo: { a: 1, b: 2 }
+    });
+  });
+});

package/src/util/augmentObject.ts

@@ -0,0 +1,112 @@
+// Copyright 2017-2025 @pezkuwi/api authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { lazyMethods, logger, objectClear } from '@pezkuwi/util';
+
+type Sections <T> = Record<string, Methods<T>>;
+
+type Methods <T> = Record<string, T>;
+
+type StringsStrings = [string[], string[]];
+
+const l = logger('api/augment');
+
+function logLength (type: 'added' | 'removed', values: string[], and: string[] = []): string {
+  return values.length
+    ? ` ${values.length} ${type}${and.length ? ' and' : ''}`
+    : '';
+}
+
+function logValues (type: 'added' | 'removed', values: string[]): string {
+  return values.length
+    ? `\n\t${type.padStart(7)}: ${values.sort().join(', ')}`
+    : '';
+}
+
+// log details to console
+function warn (prefix: string, type: 'calls' | 'modules', [added, removed]: StringsStrings): void {
+  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: string[], b: string[]): string[] {
+  return a.filter((s) => !b.includes(s));
+}
+
+function findSectionIncludes (a: string[], b: string[]): string[] {
+  return a.filter((s) => b.includes(s));
+}
+
+function extractSections <T> (src: Sections<T>, dst: Sections<T>): StringsStrings {
+  const srcSections = Object.keys(src);
+  const dstSections = Object.keys(dst);
+
+  return [
+    findSectionExcludes(srcSections, dstSections),
+    findSectionExcludes(dstSections, srcSections)
+  ];
+}
+
+function findMethodExcludes <T> (src: Sections<T>, dst: Sections<T>): string[] {
+  const srcSections = Object.keys(src);
+  const dstSections = findSectionIncludes(Object.keys(dst), srcSections);
+  const excludes: string[] = [];
+
+  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 <T> (src: Sections<T>, dst: Sections<T>): StringsStrings {
+  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 <T> (prefix: string | null, src: Sections<T>, dst: Sections<T>, fromEmpty = false): Sections<T> {
+  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: string) => methods[m]);
+  }
+
+  return dst;
+}

package/src/util/decorate.ts

@@ -0,0 +1,43 @@
+// Copyright 2017-2025 @pezkuwi/api authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ExactDerive } from '@pezkuwi/api-derive';
+import type { AnyFunction } from '@pezkuwi/types/types';
+import type { ApiTypes, DecorateMethod, MethodResult } from '../types/index.js';
+
+import { lazyDeriveSection } from '@pezkuwi/api-derive';
+
+type AnyDeriveSection = Record<string, AnyFunction>;
+
+// Most generic typings for `api.derive.*.*`
+type AnyDerive = Record<string, AnyDeriveSection>;
+
+// Exact typings for a particular section `api.derive.section.*`
+type DeriveSection<ApiType extends ApiTypes, Section extends AnyDeriveSection> = {
+  [M in keyof Section]: MethodResult<ApiType, Section[M]>
+};
+
+// Exact typings for all sections `api.derive.*.*`
+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 function decorateDeriveSections<ApiType extends ApiTypes> (decorateMethod: DecorateMethod<ApiType>, derives: AnyDerive): AllDerives<ApiType> {
+  const getKeys = (s: string) =>
+    Object.keys(derives[s]);
+
+  const creator = (s: string, m: string) =>
+    decorateMethod(derives[s][m]) as AnyFunction;
+
+  const result: AnyDerive = {};
+  const names = Object.keys(derives);
+
+  for (let i = 0, count = names.length; i < count; i++) {
+    lazyDeriveSection(result, names[i], getKeys, creator);
+  }
+
+  return result as AllDerives<ApiType>;
+}

package/src/util/filterEvents.ts

@@ -0,0 +1,34 @@
+// Copyright 2017-2025 @pezkuwi/api authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { BlockNumber, EventRecord, ExtrinsicStatus, H256, SignedBlock } from '@pezkuwi/types/interfaces';
+
+import { isCompact } from '@pezkuwi/util';
+
+import { l } from './logging.js';
+
+export function filterEvents (txHash: H256, { block: { extrinsics, header } }: SignedBlock, allEvents: EventRecord[], status: ExtrinsicStatus): { events?: EventRecord[], txIndex?: number, blockNumber?: BlockNumber } {
+  // extrinsics to hashes
+  for (const [txIndex, x] of extrinsics.entries()) {
+    if (x.hash.eq(txHash)) {
+      return {
+        blockNumber: isCompact<BlockNumber>(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/src/util/index.ts

@@ -0,0 +1,10 @@
+// Copyright 2017-2025 @pezkuwi/api authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// all named
+export { filterEvents } from './filterEvents.js';
+export { isKeyringPair } from './isKeyringPair.js';
+export { l } from './logging.js';
+
+// all starred
+export * from './decorate.js';

package/src/util/isKeyringPair.ts

@@ -0,0 +1,11 @@
+// Copyright 2017-2025 @pezkuwi/api authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { AccountId, Address } from '@pezkuwi/types/interfaces';
+import type { IKeyringPair } from '@pezkuwi/types/types';
+
+import { isFunction } from '@pezkuwi/util';
+
+export function isKeyringPair (account: string | IKeyringPair | AccountId | Address): account is IKeyringPair {
+  return isFunction((account as IKeyringPair).sign);
+}

package/src/util/logging.ts

@@ -0,0 +1,6 @@
+// Copyright 2017-2025 @pezkuwi/api authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { logger } from '@pezkuwi/util';
+
+export const l = /*#__PURE__*/ logger('api/util');

package/src/util/validate.spec.ts

@@ -0,0 +1,72 @@
+// Copyright 2017-2025 @pezkuwi/api authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { decorateStorage, Metadata, TypeRegistry } from '@pezkuwi/types';
+import metaStatic from '@pezkuwi/types-support/metadata/static-bizinikiwi';
+
+import { extractStorageArgs } from './validate.js';
+
+describe('extractStorageArgs', (): void => {
+  const registry = new TypeRegistry();
+  const metadata = new Metadata(registry, metaStatic);
+
+  registry.setMetadata(metadata);
+
+  const storage = decorateStorage(registry, metadata.asLatest, metadata.version);
+
+  it('validates no-arg plain', (): void => {
+    expect(
+      extractStorageArgs(registry, storage['timestamp']['now'], [])
+    ).toEqual([storage['timestamp']['now'], []]);
+  });
+
+  it('validates no-arg plain (with undefined, undefined)', (): void => {
+    expect(
+      extractStorageArgs(registry, storage['timestamp']['now'], [undefined, undefined])
+    ).toEqual([storage['timestamp']['now'], []]);
+  });
+
+  it('validates no-arg plain (failing when there are args)', (): void => {
+    expect(
+      () => extractStorageArgs(registry, storage['timestamp']['now'], [123, 456])
+    ).toThrow('timestamp.now() does not take any arguments, 2 found');
+  });
+
+  it('validates map, 1 arg', (): void => {
+    expect(
+      extractStorageArgs(registry, storage['staking']['payee'], ['abc'])
+    ).toEqual([storage['staking']['payee'], ['abc']]);
+  });
+
+  it('validates map, 1 arg (failing with no args)', (): void => {
+    expect(
+      () => extractStorageArgs(registry, storage['staking']['payee'], [])
+    ).toThrow('staking.payee(AccountId32) is a map, requiring 1 arguments, 0 found');
+  });
+
+  it('validates map, 1 arg (failing with more args)', (): void => {
+    expect(
+      () => extractStorageArgs(registry, storage['staking']['payee'], ['abc', 'def'])
+    ).toThrow('staking.payee(AccountId32) is a map, requiring 1 arguments, 2 found');
+  });
+
+  it('validates doublemap, 2 args', (): void => {
+    expect(
+      extractStorageArgs(registry, storage['staking']['erasStakers'], [1, '0x1234'])
+    ).toEqual([storage['staking']['erasStakers'], [1, '0x1234']]);
+  });
+
+  it('validates doublemap, 2 args (failing with no args)', (): void => {
+    expect(
+      () => extractStorageArgs(registry, storage['staking']['erasStakers'], [])
+    ).toThrow('staking.erasStakers(u32, AccountId32) is a map, requiring 2 arguments, 0 found');
+  });
+
+  it('validates doublemap, 2 args (failing with 1 arg)', (): void => {
+    expect(
+      () => extractStorageArgs(registry, storage['staking']['erasStakers'], [123])
+    ).toThrow('staking.erasStakers(u32, AccountId32) is a map, requiring 2 arguments, 1 found');
+  });
+});

package/src/util/validate.ts

@@ -0,0 +1,36 @@
+// Copyright 2017-2025 @pezkuwi/api authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { SiLookupTypeId } from '@pezkuwi/types/interfaces';
+import type { StorageEntry } from '@pezkuwi/types/primitive/types';
+import type { Registry } from '@pezkuwi/types/types';
+
+import { isUndefined } from '@pezkuwi/util';
+
+function sig ({ lookup }: Registry, { method, section }: StorageEntry, args: SiLookupTypeId[]): string {
+  return `${section}.${method}(${args.map((a) => lookup.getTypeDef(a).type).join(', ')})`;
+}
+
+// sets up the arguments in the form of [creator, args] ready to be used in a storage
+// call. Additionally, it verifies that the correct number of arguments have been passed
+export function extractStorageArgs (registry: Registry, creator: StorageEntry, _args: unknown[]): [StorageEntry, unknown[]] {
+  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/tsconfig.build.json

@@ -0,0 +1,25 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "baseUrl": "..",
+    "outDir": "./build",
+    "rootDir": "./src"
+  },
+  "exclude": [
+    "**/checkTypes.manual.ts",
+    "**/mod.ts",
+    "**/*.spec.ts",
+    "**/test/**/*"
+  ],
+  "references": [
+    { "path": "../api-augment/tsconfig.build.json" },
+    { "path": "../api-base/tsconfig.build.json" },
+    { "path": "../api-derive/tsconfig.build.json" },
+    { "path": "../rpc-augment/tsconfig.build.json" },
+    { "path": "../rpc-core/tsconfig.build.json" },
+    { "path": "../rpc-provider/tsconfig.build.json" },
+    { "path": "../types/tsconfig.build.json" },
+    { "path": "../types-codec/tsconfig.build.json" },
+    { "path": "../types-known/tsconfig.build.json" }
+  ]
+}