@pezkuwi/api-derive 16.5.5

package/src/tx/signingInfo.ts

@@ -0,0 +1,129 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Observable } from 'rxjs';
+import type { AugmentedConsts } from '@pezkuwi/api-base/types';
+import type { u64 } from '@pezkuwi/types';
+import type { Header, Index } from '@pezkuwi/types/interfaces';
+import type { AnyNumber, Codec, IExtrinsicEra } from '@pezkuwi/types/types';
+import type { BN } from '@pezkuwi/util';
+import type { DeriveApi } from '../types.js';
+
+import { catchError, combineLatest, map, of, switchMap } from 'rxjs';
+
+import { isNumber, isUndefined } from '@pezkuwi/util';
+
+import { unwrapBlockNumber } from '../util/index.js';
+import { FALLBACK_MAX_HASH_COUNT, FALLBACK_PERIOD, MAX_FINALITY_LAG, MORTAL_PERIOD } from './constants.js';
+
+interface Result {
+  header: Header | null;
+  mortalLength: number;
+  nonce: Index;
+}
+
+function latestNonce (api: DeriveApi, address: string): Observable<Index> {
+  return api.derive.balances.account(address).pipe(
+    map(({ accountNonce }) => accountNonce)
+  );
+}
+
+function nextNonce (api: DeriveApi, address: string): Observable<Index> {
+  if (api.call.accountNonceApi) {
+    return api.call.accountNonceApi.accountNonce(address);
+  } else {
+    return api.rpc.system?.accountNextIndex
+      ? api.rpc.system.accountNextIndex(address)
+      : latestNonce(api, address);
+  }
+}
+
+function signingHeader (api: DeriveApi): Observable<Header> {
+  return combineLatest([
+    api.rpc.chain.getHeader().pipe(
+      switchMap((header) =>
+        // check for chains at genesis (until block 1 is produced, e.g. 6s), since
+        // we do need to allow transactions at chain start (also dev/seal chains)
+        header.parentHash.isEmpty
+          ? of(header)
+          // in the case of the current block, we use the parent to minimize the
+          // impact of forks on the system, but not completely remove it
+          : api.rpc.chain.getHeader(header.parentHash).pipe(
+            catchError(() => of(header))
+          )
+      )
+    ),
+    api.rpc.chain.getFinalizedHead().pipe(
+      switchMap((hash) =>
+        api.rpc.chain.getHeader(hash).pipe(
+          catchError(() => of(null))
+        )
+      )
+    )
+  ]).pipe(
+    map(([current, finalized]) =>
+      // determine the hash to use, current when lag > max, else finalized
+      !finalized || unwrapBlockNumber(current).sub(unwrapBlockNumber(finalized)).gt(MAX_FINALITY_LAG)
+        ? current
+        : finalized
+    )
+  );
+}
+
+interface Aura {
+  slotDuration: u64 & AugmentedConsts<'rxjs'>;
+}
+
+function babeOrAuraPeriod (api: DeriveApi): BN | undefined {
+  const period = api.consts.babe?.expectedBlockTime ||
+  // this will be present ones https://github.com/paritytech/polkadot-sdk/pull/3732 is merged
+
+    // eslint-disable-next-line
+    (api.consts['aura'] as unknown as Aura)?.['slotDuration'] ||
+    api.consts.timestamp?.minimumPeriod.muln(2);
+
+  return period && period.isZero && !period.isZero() ? period : undefined;
+}
+
+/**
+ * @name signingInfo
+ * @description Retrieves signing-related information for an account, including the nonce, block header, and mortal length.
+ * @param {string} address The account address for which signing information is needed.
+ * @param { BN | bigint | Uint8Array | number | string } nonce? (Optional) The nonce to use. If `undefined`, the latest nonce is retrieved.
+ * @param { IExtrinsicEra | number } era? (Optional) The transaction era.
+ * @example
+ * ```javascript
+ * const info = await api.derive.tx.signingInfo(
+ *   "14mM9FRDDtwSYicjNxSvMfQkap8o4m9zHq7hNW4JpbSL4PPU"
+ * );
+ * console.log(info);
+ * ```
+ */
+export function signingInfo (_instanceId: string, api: DeriveApi): (address: string, nonce?: AnyNumber | Codec, era?: IExtrinsicEra | number) => Observable<Result> {
+  // no memo, we want to do this fresh on each run
+  return (address: string, nonce?: AnyNumber | Codec, era?: IExtrinsicEra | number): Observable<Result> =>
+    combineLatest([
+      // retrieve nonce if none was specified
+      isUndefined(nonce)
+        ? latestNonce(api, address)
+        : nonce === -1
+          ? nextNonce(api, address)
+          : of(api.registry.createType('Index', nonce)),
+      // if no era (create) or era > 0 (mortal), do block retrieval
+      (isUndefined(era) || (isNumber(era) && era > 0))
+        ? signingHeader(api)
+        : of(null)
+    ]).pipe(
+      map(([nonce, header]) => ({
+        header,
+        mortalLength: Math.min(
+          api.consts.system?.blockHashCount?.toNumber() || FALLBACK_MAX_HASH_COUNT,
+          MORTAL_PERIOD
+            .div(babeOrAuraPeriod(api) || FALLBACK_PERIOD)
+            .iadd(MAX_FINALITY_LAG)
+            .toNumber()
+        ),
+        nonce
+      }))
+    );
+}

package/src/type/HeaderExtended.ts

@@ -0,0 +1,33 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { AccountId, Header } from '@pezkuwi/types/interfaces';
+import type { Registry } from '@pezkuwi/types/types';
+import type { HeaderExtended } from './types.js';
+
+import { extractAuthor } from './util.js';
+
+export function createHeaderExtended (registry: Registry, header?: Header, validators?: AccountId[] | null, author?: AccountId | null): HeaderExtended {
+  // an instance of the base extrinsic for us to extend
+  const HeaderBase = registry.createClass('Header');
+
+  class Implementation extends HeaderBase implements HeaderExtended {
+    readonly #author?: AccountId | undefined;
+
+    constructor (registry: Registry, header?: Header, validators?: AccountId[] | null, author?: AccountId | null) {
+      super(registry, header);
+
+      this.#author = author || extractAuthor(this.digest, validators || []);
+      this.createdAtHash = header?.createdAtHash;
+    }
+
+    /**
+     * @description Convenience method, returns the author for the block
+     */
+    public get author (): AccountId | undefined {
+      return this.#author;
+    }
+  }
+
+  return new Implementation(registry, header, validators, author);
+}

package/src/type/SignedBlockExtended.ts

@@ -0,0 +1,75 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { AccountId, DispatchError, DispatchInfo, EventRecord, Extrinsic, SignedBlock } from '@pezkuwi/types/interfaces';
+import type { Registry } from '@pezkuwi/types/types';
+import type { SignedBlockExtended, TxWithEvent } from './types.js';
+
+import { extractAuthor } from './util.js';
+
+function mapExtrinsics (extrinsics: Extrinsic[], records: EventRecord[]): TxWithEvent[] {
+  return extrinsics.map((extrinsic, index): TxWithEvent => {
+    let dispatchError: DispatchError | undefined;
+    let dispatchInfo: DispatchInfo | undefined;
+
+    const events = records
+      .filter(({ phase }) => phase.isApplyExtrinsic && phase.asApplyExtrinsic.eq(index))
+      .map(({ event }) => {
+        if (event.section === 'system') {
+          if (event.method === 'ExtrinsicSuccess') {
+            dispatchInfo = event.data[0] as DispatchInfo;
+          } else if (event.method === 'ExtrinsicFailed') {
+            dispatchError = event.data[0] as DispatchError;
+            dispatchInfo = event.data[1] as DispatchInfo;
+          }
+        }
+
+        return event;
+      });
+
+    return { dispatchError, dispatchInfo, events, extrinsic };
+  });
+}
+
+export function createSignedBlockExtended (registry: Registry, block?: SignedBlock, events?: EventRecord[], validators?: AccountId[] | null, author?: AccountId | null): SignedBlockExtended {
+  // an instance of the base extrinsic for us to extend
+  const SignedBlockBase = registry.createClass('SignedBlock');
+
+  class Implementation extends SignedBlockBase implements SignedBlockExtended {
+    readonly #author?: AccountId | undefined;
+    readonly #events: EventRecord[];
+    readonly #extrinsics: TxWithEvent[];
+
+    constructor (registry: Registry, block?: SignedBlock, events?: EventRecord[], validators?: AccountId[] | null, author?: AccountId | null) {
+      super(registry, block);
+
+      this.#author = author || extractAuthor(this.block.header.digest, validators || []);
+      this.#events = events || ([] as EventRecord[]);
+      this.#extrinsics = mapExtrinsics(this.block.extrinsics, this.#events);
+      this.createdAtHash = block?.createdAtHash;
+    }
+
+    /**
+     * @description Convenience method, returns the author for the block
+     */
+    public get author (): AccountId | undefined {
+      return this.#author;
+    }
+
+    /**
+     * @description Convenience method, returns the events associated with the block
+     */
+    public get events (): EventRecord[] {
+      return this.#events;
+    }
+
+    /**
+     * @description Returns the extrinsics and their events, mapped
+     */
+    public get extrinsics (): TxWithEvent[] {
+      return this.#extrinsics;
+    }
+  }
+
+  return new Implementation(registry, block, events, validators, author);
+}

package/src/type/index.ts

@@ -0,0 +1,5 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export { createHeaderExtended } from './HeaderExtended.js';
+export { createSignedBlockExtended } from './SignedBlockExtended.js';

package/src/type/types.ts

@@ -0,0 +1,21 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { AccountId, DispatchError, DispatchInfo, Event, EventRecord, Extrinsic, Header, SignedBlock } from '@pezkuwi/types/interfaces';
+
+export interface HeaderExtended extends Header {
+  readonly author: AccountId | undefined;
+}
+
+export interface SignedBlockExtended extends SignedBlock {
+  readonly author: AccountId | undefined;
+  readonly events: EventRecord[];
+  readonly extrinsics: TxWithEvent[];
+}
+
+export interface TxWithEvent {
+  dispatchError?: DispatchError | undefined;
+  dispatchInfo?: DispatchInfo | undefined;
+  events: Event[];
+  extrinsic: Extrinsic;
+}

package/src/type/util.ts

@@ -0,0 +1,45 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { AccountId, Digest } from '@pezkuwi/types/interfaces';
+
+export function extractAuthor (digest: Digest, sessionValidators: AccountId[]): AccountId | undefined {
+  const [citem] = digest.logs.filter((e) => e.isConsensus);
+  const preRuntimeItems = digest.logs.filter((e) => e.isPreRuntime);
+  const [sitem] = digest.logs.filter((e) => e.isSeal);
+  let accountId: AccountId | undefined;
+
+  try {
+    // This is critical to be first for BABE (before Consensus)
+    // If not first, we end up dropping the author at session-end
+    // Iterate through ALL preRuntime logs to find a recognized engine
+    // (parachains may have multiple preRuntime logs, e.g., CMLS + aura)
+    for (const pitem of preRuntimeItems) {
+      const [engine, data] = pitem.asPreRuntime;
+
+      accountId = engine.extractAuthor(data, sessionValidators);
+
+      // Stop at first recognized engine that returns an author
+      if (accountId) {
+        return accountId;
+      }
+    }
+
+    if (!accountId && citem) {
+      const [engine, data] = citem.asConsensus;
+
+      accountId = engine.extractAuthor(data, sessionValidators);
+    }
+
+    // SEAL, still used in e.g. Kulupu for pow
+    if (!accountId && sitem) {
+      const [engine, data] = sitem.asSeal;
+
+      accountId = engine.extractAuthor(data, sessionValidators);
+    }
+  } catch {
+    // ignore
+  }
+
+  return accountId;
+}

package/src/types.ts

@@ -0,0 +1,97 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ApiInterfaceRx } from '@pezkuwi/api-base/types';
+import type { u32 } from '@pezkuwi/types';
+import type { Balance, BlockNumber, BountyIndex, Hash, Proposal, ProposalIndex, SetIndex, Votes } from '@pezkuwi/types/interfaces';
+import type { PalletBountiesBounty, PalletTreasuryProposal } from '@pezkuwi/types/lookup';
+import type { BN } from '@pezkuwi/util';
+import type { ExactDerive } from './derive.js';
+
+export * from './accounts/types.js';
+export * from './bagsList/types.js';
+export * from './balances/types.js';
+export * from './council/types.js';
+export * from './crowdloan/types.js';
+export * from './democracy/types.js';
+export * from './elections/types.js';
+export * from './parachains/types.js';
+export * from './session/types.js';
+export * from './society/types.js';
+export * from './staking/types.js';
+export * from './type/types.js';
+
+export interface DeriveApi extends ApiInterfaceRx {
+  derive: ExactDerive;
+}
+
+export interface DeriveContractFees {
+  callBaseFee: BN;
+  contractFee: BN;
+  creationFee: BN;
+  rentByteFee: BN;
+  rentDepositOffset: BN;
+  surchargeReward: BN;
+  tombstoneDeposit: BN;
+  transactionBaseFee: BN;
+  transactionByteFee: BN;
+  transferFee: BN;
+}
+
+export interface DeriveCollectiveProposal {
+  hash: Hash;
+  proposal: Proposal | null;
+  votes: Votes | null;
+}
+
+export interface DeriveFees {
+  creationFee: Balance;
+  existentialDeposit: Balance;
+  transactionBaseFee: Balance;
+  transactionByteFee: Balance;
+  transferFee: Balance;
+}
+
+export interface DeriveHeartbeatAuthor {
+  blockCount: u32;
+  hasMessage: boolean;
+  isOnline: boolean;
+}
+
+export type DeriveHeartbeats = Record<string, DeriveHeartbeatAuthor>;
+
+export interface RecentlyOffline {
+  blockNumber: BlockNumber;
+  count: BN;
+}
+
+export type DeriveRecentlyOffline = Record<string, RecentlyOffline[]>;
+
+export interface DeriveTreasuryProposal {
+  council: DeriveCollectiveProposal[];
+  id: ProposalIndex;
+  proposal: PalletTreasuryProposal;
+}
+
+export interface DeriveTreasuryProposals {
+  approvals: DeriveTreasuryProposal[];
+  proposalCount: ProposalIndex;
+  proposals: DeriveTreasuryProposal[];
+}
+
+export interface VoterPosition {
+  globalIndex: BN;
+  index: BN;
+  setIndex: SetIndex;
+}
+
+export type DeriveVoterPositions = Record<string, VoterPosition>;
+
+export interface DeriveBounty {
+  bounty: PalletBountiesBounty;
+  description: string;
+  index: BountyIndex;
+  proposals: DeriveCollectiveProposal[];
+}
+
+export type DeriveBounties = DeriveBounty[];

package/src/util/approvalFlagToBools.spec.ts

@@ -0,0 +1,37 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import type { ApprovalFlag } from '@pezkuwi/types/interfaces';
+
+import { TypeRegistry } from '@pezkuwi/types/create';
+
+import { approvalFlagsToBools } from './approvalFlagsToBools.js';
+
+describe('approvalFlagsToBools', (): void => {
+  const registry = new TypeRegistry();
+
+  it('translates and empty array to empty', (): void => {
+    expect(
+      approvalFlagsToBools([] as ApprovalFlag[])
+    ).toEqual([]);
+  });
+
+  it('translates a single input', (): void => {
+    expect(
+      approvalFlagsToBools([
+        registry.createType('ApprovalFlag', 0b1010)
+      ])
+    ).toEqual([false, true, false, true]);
+  });
+
+  it('translates multiple inputs', (): void => {
+    expect(
+      approvalFlagsToBools([
+        registry.createType('ApprovalFlag', 0b0000),
+        registry.createType('ApprovalFlag', 0b1100)
+      ])
+    ).toEqual([false, false, false, true, true]);
+  });
+});

package/src/util/approvalFlagsToBools.ts

@@ -0,0 +1,26 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Vec } from '@pezkuwi/types';
+import type { ApprovalFlag } from '@pezkuwi/types/interfaces/elections';
+
+/** @internal */
+export function approvalFlagsToBools (flags: Vec<ApprovalFlag> | ApprovalFlag[]): boolean[] {
+  const bools: boolean[] = [];
+
+  for (let i = 0, count = flags.length; i < count; i++) {
+    const str = flags[i].toString(2);
+
+    // read from lowest bit to highest
+    for (const bit of str.split('').reverse()) {
+      bools.push(!!parseInt(bit, 10));
+    }
+  }
+
+  // slice off trailing "false" values, as in substrate
+  const lastApproval = bools.lastIndexOf(true);
+
+  return lastApproval >= 0
+    ? bools.slice(0, lastApproval + 1)
+    : [];
+}

package/src/util/blockNumber.ts

@@ -0,0 +1,15 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Compact } from '@pezkuwi/types';
+import type { BlockNumber } from '@pezkuwi/types/interfaces';
+
+import { isCompact } from '@pezkuwi/util';
+
+interface CompatHeader { number: Compact<BlockNumber> | BlockNumber }
+
+export function unwrapBlockNumber (hdr: CompatHeader): BlockNumber {
+  return isCompact<BlockNumber>(hdr.number)
+    ? hdr.number.unwrap()
+    : hdr.number;
+}

package/src/util/cache.ts

@@ -0,0 +1,65 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { DeriveCache } from './types.js';
+
+import { deriveNoopCache } from './cacheImpl.js';
+
+interface CacheValue<T> {
+  v: T;
+  x: number;
+}
+
+const CACHE_EXPIRY = 7 * (24 * 60) * (60 * 1000);
+
+let deriveCache: DeriveCache;
+
+function wrapCache (keyStart: string, cache: DeriveCache): DeriveCache {
+  return {
+    del: (partial: string): void => cache.del(`${keyStart}${partial}`),
+    forEach: cache.forEach,
+    get: <T> (partial: string): T | undefined => {
+      const key = `${keyStart}${partial}`;
+      const cached = cache.get<CacheValue<T>>(key);
+
+      if (cached) {
+        cached.x = Date.now();
+        cache.set(key, cached);
+
+        return cached.v;
+      }
+
+      return undefined;
+    },
+    set: (partial: string, v: unknown): void => {
+      cache.set(`${keyStart}${partial}`, { v, x: Date.now() });
+    }
+  };
+}
+
+function clearCache (cache: DeriveCache): void {
+  // clear all expired values
+  const now = Date.now();
+  const all: string[] = [];
+
+  cache.forEach((key: string, { x }: CacheValue<any>): void => {
+    ((now - x) > CACHE_EXPIRY) && all.push(key);
+  });
+
+  // don't do delete inside loop, just in-case
+  all.forEach((key) => cache.del(key));
+}
+
+export function setDeriveCache (prefix = '', cache?: DeriveCache): void {
+  deriveCache = cache
+    ? wrapCache(`derive:${prefix}:`, cache)
+    : deriveNoopCache;
+
+  if (cache) {
+    clearCache(cache);
+  }
+}
+
+setDeriveCache();
+
+export { deriveCache };

package/src/util/cacheImpl.ts

@@ -0,0 +1,30 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { DeriveCache } from './types.js';
+
+const mapCache = new Map<string, any>();
+
+export const deriveMapCache: DeriveCache = {
+  del: (key: string): void => {
+    mapCache.delete(key);
+  },
+  forEach: (cb: (key: string, value: any) => void): void => {
+    for (const [k, v] of mapCache.entries()) {
+      cb(k, v);
+    }
+  },
+  get: <T = any> (key: string): T | undefined => {
+    return mapCache.get(key) as T;
+  },
+  set: (key: string, value: any): void => {
+    mapCache.set(key, value);
+  }
+};
+
+export const deriveNoopCache: DeriveCache = {
+  del: (): void => undefined,
+  forEach: () => undefined,
+  get: (): undefined => undefined,
+  set: (_: string, value: unknown): unknown => value
+};

package/src/util/first.ts

@@ -0,0 +1,20 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Observable } from 'rxjs';
+import type { DeriveApi } from '../types.js';
+
+import { map } from 'rxjs';
+
+import { memo } from '@pezkuwi/rpc-core';
+
+export function firstObservable <T> (obs: Observable<T[]>): Observable<T> {
+  return obs.pipe(map(([a]) => a));
+}
+
+export function firstMemo <T, A extends any[]> (fn: (api: DeriveApi, ...args: A) => Observable<T[]>): (instanceId: string, api: DeriveApi) => (...args: A) => Observable<T> {
+  return (instanceId: string, api: DeriveApi) =>
+    memo(instanceId, (...args: A) =>
+      firstObservable<T>(fn(api, ...args))
+    );
+}

package/src/util/index.ts

@@ -0,0 +1,13 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// all named
+export { drr, memo } from '@pezkuwi/rpc-core';
+
+// all starred
+export * from './approvalFlagsToBools.js';
+export * from './blockNumber.js';
+export * from './cache.js';
+export * from './cacheImpl.js';
+export * from './first.js';
+export * from './lazy.js';

package/src/util/lazy.ts

@@ -0,0 +1,16 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { lazyMethod, lazyMethods } from '@pezkuwi/util';
+
+type LazySection <T> = Record<string, T>;
+
+type LazyRecord <T> = Record<string, LazySection<T>>;
+
+export function lazyDeriveSection <T> (result: LazyRecord<T>, section: string, getKeys: (s: string) => string[], creator: (s: string, m: string) => T): void {
+  lazyMethod(result, section, () =>
+    lazyMethods({}, getKeys(section), (method: string) =>
+      creator(section, method)
+    )
+  );
+}

package/src/util/types.ts

@@ -0,0 +1,9 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export interface DeriveCache {
+  del: (key: string) => void;
+  forEach: (cb: (key: string, value: any) => void) => void;
+  get: <T = any> (key: string) => T | undefined;
+  set: (key: string, value: any) => void;
+}

package/tsconfig.build.json

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