@pezkuwi/api-derive 16.5.5

package/src/bounties/bounties.spec.ts

@@ -0,0 +1,162 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import type { ApiPromise } from '@pezkuwi/api';
+import type { SubmittableExtrinsic } from '@pezkuwi/api-base/types';
+import type { Bytes, Option, StorageKey } from '@pezkuwi/types';
+import type { Bounty, BountyIndex, Proposal, ProposalIndex } from '@pezkuwi/types/interfaces';
+import type { Codec, InterfaceTypes } from '@pezkuwi/types/types';
+import type { DeriveApi, DeriveCollectiveProposal } from '../types.js';
+
+import { firstValueFrom, of } from 'rxjs';
+
+import { BountyFactory } from '../test/bountyFactory.js';
+import { BytesFactory } from '../test/bytesFactory.js';
+import { createApiWithAugmentations } from '../test/helpers.js';
+import { ProposalFactory } from '../test/proposalFactory.js';
+import { bounties } from './index.js';
+
+const DEFAULT_PROPOSER = '5C4hrfjw9DjXZTzV3MwzrrAr9P1MJhSrvWGWqi1eSuyUpnhM';
+
+describe('bounties derive', () => {
+  let storageKey: (index: number) => StorageKey;
+  let defaultBounty: () => Bounty;
+  let emptyOption: <T extends Codec> (typeName: keyof InterfaceTypes) => Option<T>;
+  let optionOf: <T extends Codec> (value: T) => Option<T>;
+  let bountyIndex: (index: number) => BountyIndex;
+  let proposalIndex: (index: number) => ProposalIndex;
+  let bytes: (value: string) => Bytes;
+  let api: ApiPromise;
+  let createProposal: (method: SubmittableExtrinsic<'promise'>) => Proposal;
+  let defaultMockApi: DeriveApi;
+
+  beforeAll(() => {
+    api = createApiWithAugmentations();
+
+    ({ bountyIndex, defaultBounty, emptyOption, optionOf, storageKey } = new BountyFactory(api));
+    ({ bytes } = new BytesFactory(api.registry));
+    ({ createProposal, proposalIndex } = new ProposalFactory(api));
+  });
+
+  beforeEach(() => {
+    defaultMockApi = {
+      derive: {
+        council: {
+          proposals: () => of([] as DeriveCollectiveProposal[])
+        }
+      },
+      query: {
+        council: {
+          proposalCount: () => of(proposalIndex(2))
+        },
+        treasury: {
+          bounties: {
+            keys: () => of([storageKey(0), storageKey(1)]),
+            multi: () => of([optionOf(defaultBounty()), optionOf(defaultBounty())])
+          },
+          bountyCount: () => of(bountyIndex(2)),
+          bountyDescriptions: {
+            multi: () => of([
+              optionOf(bytes('make polkadot even better')),
+              optionOf(bytes('some other bounty'))
+            ])
+          }
+        }
+      },
+      tx: api.tx
+    } as unknown as DeriveApi;
+  });
+
+  it('creates storage key', function () {
+    expect(storageKey(194).args[0].eq(194)).toBe(true);
+  });
+
+  it('creates proposal', function () {
+    expect(createProposal(api.tx.balances.transferAllowDeath('5EYCAe5ijiYfyeZ2JJCGq56LmPyNRAKzpG4QkoQkkQNB5e6Z', 1))).toBeTruthy();
+  });
+
+  it('combines bounties with descriptions', async () => {
+    const mockApi = {
+      ...defaultMockApi,
+      query: {
+        ...defaultMockApi.query,
+        treasury: {
+          bounties: {
+            keys: () => of([storageKey(0), storageKey(2), storageKey(3)]),
+            multi: () => of([optionOf(defaultBounty()), emptyOption('Bounty'), optionOf(defaultBounty())])
+          },
+          bountyCount: () => of(bountyIndex(3)),
+          bountyDescriptions: {
+            multi: () => of([
+              optionOf(bytes('make polkadot even better')),
+              optionOf(bytes('this will be totally ignored')),
+              emptyOption('Bytes')
+            ])
+          }
+        }
+      }
+    } as unknown as DeriveApi;
+
+    const result = await firstValueFrom(bounties('', mockApi)());
+
+    expect(result).toHaveLength(2);
+    expect(result[0].bounty.proposer.toString()).toEqual(DEFAULT_PROPOSER);
+    expect(result[0].description).toEqual('make polkadot even better');
+    expect(result[0].index.eq(0)).toBe(true);
+    expect(result[1].bounty.proposer.toString()).toEqual(DEFAULT_PROPOSER);
+    expect(result[1].description).toEqual('');
+    expect(result[1].index.eq(3)).toBe(true);
+  });
+
+  it('returns motions', async () => {
+    const result = await firstValueFrom(bounties('', defaultMockApi)());
+
+    expect(result).toHaveLength(2);
+    expect(result[0].proposals).toHaveLength(0);
+    expect(result[1].proposals).toHaveLength(0);
+  });
+
+  it('when no council, returns bounties without motions', async () => {
+    const mockApi = {
+      ...defaultMockApi,
+      query: {
+        ...defaultMockApi.query,
+        council: null
+      }
+    } as unknown as DeriveApi;
+
+    const result = await firstValueFrom(bounties('', mockApi)());
+
+    expect(result).toHaveLength(2);
+    expect(result[0].bounty.proposer.toString()).toEqual(DEFAULT_PROPOSER);
+    expect(result[0].description).toEqual('make polkadot even better');
+    expect(result[0].index.eq(0)).toBe(true);
+    expect(result[0].proposals).toHaveLength(0);
+    expect(result[1].bounty.proposer.toString()).toEqual(DEFAULT_PROPOSER);
+    expect(result[1].description).toEqual('some other bounty');
+    expect(result[1].index.eq(1)).toBe(true);
+    expect(result[1].proposals).toHaveLength(0);
+  });
+
+  it('combines bounties with motions', async () => {
+    const mockApi = {
+      ...defaultMockApi,
+      derive: {
+        council: {
+          proposals: () => of([
+            { proposal: createProposal(api.tx.bounties.approveBounty(1)) },
+            { proposal: api.tx.treasury['approveProposal'] && createProposal(api.tx.treasury['approveProposal'](1)) }] as DeriveCollectiveProposal[])
+        }
+      }
+    } as unknown as DeriveApi;
+
+    const result = await firstValueFrom(bounties('', mockApi)());
+
+    expect(result).toHaveLength(2);
+    expect(result[0].proposals).toHaveLength(0);
+    expect(result[1].proposals).toHaveLength(1);
+    expect(result[1].proposals[0].proposal?.method).toEqual('approveBounty');
+  });
+});

package/src/bounties/bounties.ts

@@ -0,0 +1,76 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Observable } from 'rxjs';
+import type { Bytes, Option } from '@pezkuwi/types';
+import type { BountyIndex } from '@pezkuwi/types/interfaces';
+import type { PalletBountiesBounty } from '@pezkuwi/types/lookup';
+import type { DeriveApi, DeriveBounties, DeriveCollectiveProposal } from '../types.js';
+
+import { combineLatest, map, of, switchMap } from 'rxjs';
+
+import { memo } from '../util/index.js';
+import { filterBountiesProposals } from './helpers/filterBountyProposals.js';
+
+type Result = [Option<PalletBountiesBounty>[], Option<Bytes>[], BountyIndex[], DeriveCollectiveProposal[]];
+
+function parseResult ([maybeBounties, maybeDescriptions, ids, bountyProposals]: Result): DeriveBounties {
+  const bounties: DeriveBounties = [];
+
+  maybeBounties.forEach((bounty, index) => {
+    if (bounty.isSome) {
+      bounties.push({
+        bounty: bounty.unwrap(),
+        description: maybeDescriptions[index].unwrapOrDefault().toUtf8(),
+        index: ids[index],
+        proposals: bountyProposals.filter((bountyProposal) =>
+          bountyProposal.proposal && ids[index].eq(bountyProposal.proposal.args[0])
+        )
+      });
+    }
+  });
+
+  return bounties;
+}
+
+/**
+ * @name bounties
+ * @descrive Retrieves all active bounties, their descriptions, and associated proposals.
+ * @example
+ * ```javascript
+ * const bounties = await api.derive.bounties();
+ * console.log("Active bounties:", bounties);
+ * ```
+ */
+export function bounties (instanceId: string, api: DeriveApi): () => Observable<DeriveBounties> {
+  const bountyBase = api.query.bounties || api.query.treasury;
+
+  return memo(instanceId, (): Observable<DeriveBounties> =>
+    bountyBase.bounties
+      ? combineLatest([
+        bountyBase.bountyCount(),
+        api.query.council
+          ? api.query.council.proposalCount()
+          : of(0)
+      ]).pipe(
+        switchMap(() => combineLatest([
+          bountyBase.bounties.keys(),
+          api.derive.council
+            ? api.derive.council.proposals()
+            : of([])
+        ])),
+        switchMap(([keys, proposals]): Observable<Result> => {
+          const ids = keys.map(({ args: [id] }) => id);
+
+          return combineLatest([
+            bountyBase.bounties.multi(ids),
+            bountyBase.bountyDescriptions.multi(ids),
+            of(ids),
+            of(filterBountiesProposals(api, proposals))
+          ]);
+        }),
+        map(parseResult)
+      )
+      : of(parseResult([[], [], [], []]))
+  );
+}

package/src/bounties/helpers/filterBountyProposals.ts

@@ -0,0 +1,13 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { DeriveApi, DeriveCollectiveProposal } from '../../types.js';
+
+export function filterBountiesProposals (api: DeriveApi, allProposals: DeriveCollectiveProposal[]): DeriveCollectiveProposal[] {
+  const bountyTxBase = api.tx.bounties ? api.tx.bounties : api.tx.treasury;
+  const bountyProposalCalls = [bountyTxBase.approveBounty, bountyTxBase.closeBounty, bountyTxBase.proposeCurator, bountyTxBase.unassignCurator];
+
+  return allProposals.filter((proposal) => bountyProposalCalls.find((bountyCall) =>
+    proposal.proposal && bountyCall.is(proposal.proposal))
+  );
+}

package/src/bounties/index.ts

@@ -0,0 +1,4 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export * from './bounties.js';

package/src/bundle.ts

@@ -0,0 +1,140 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { DeriveCustom } from '@pezkuwi/api-base/types';
+import type { AnyFunction, AnyString } from '@pezkuwi/types/types';
+import type { ExactDerive } from './derive.js';
+import type { DeriveApi } from './types.js';
+
+import { lazyDeriveSection } from './util/index.js';
+import { derive } from './derive.js';
+
+export * from './derive.js';
+export * from './type/index.js';
+
+interface Avail {
+  instances: string[];
+  methods: string[];
+  withDetect?: boolean;
+}
+
+export { lazyDeriveSection };
+
+// Enable derive only if some of these modules are available
+const checks: Record<string, Avail> = {
+  allianceMotion: {
+    instances: ['allianceMotion'],
+    methods: []
+  },
+  bagsList: {
+    instances: ['voterBagsList', 'voterList', 'bagsList'],
+    methods: [],
+    withDetect: true
+  },
+  contracts: {
+    instances: ['contracts'],
+    methods: []
+  },
+  council: {
+    instances: ['council'],
+    methods: [],
+    withDetect: true
+  },
+  crowdloan: {
+    instances: ['crowdloan'],
+    methods: []
+  },
+  democracy: {
+    instances: ['democracy'],
+    methods: []
+  },
+  elections: {
+    instances: ['phragmenElection', 'electionsPhragmen', 'elections', 'council'],
+    methods: [],
+    withDetect: true
+  },
+  imOnline: {
+    instances: ['imOnline'],
+    methods: []
+  },
+  membership: {
+    instances: ['membership'],
+    methods: []
+  },
+  parachains: {
+    instances: ['parachains', 'registrar'],
+    methods: []
+  },
+  session: {
+    instances: ['session'],
+    methods: []
+  },
+  society: {
+    instances: ['society'],
+    methods: []
+  },
+  staking: {
+    instances: ['staking'],
+    methods: ['erasRewardPoints']
+  },
+  technicalCommittee: {
+    instances: ['technicalCommittee'],
+    methods: [],
+    withDetect: true
+  },
+  treasury: {
+    instances: ['treasury'],
+    methods: []
+  }
+};
+
+function getModuleInstances (api: DeriveApi, specName: AnyString, moduleName: string): string[] {
+  return api.registry.getModuleInstances(specName, moduleName) || [];
+}
+
+/**
+ * Returns an object that will inject `api` into all the functions inside
+ * `allSections`, and keep the object architecture of `allSections`.
+ */
+/** @internal */
+function injectFunctions (instanceId: string, api: DeriveApi, derives: DeriveCustom): ExactDerive {
+  const result: Record<string, Record<string, AnyFunction>> = {};
+  const names = Object.keys(derives);
+  const keys = Object.keys(api.query);
+  const specName = api.runtimeVersion.specName;
+
+  const filterKeys = (q: string) => keys.includes(q);
+  const filterInstances = (q: string) => getModuleInstances(api, specName, q).some(filterKeys);
+  const filterMethods = (all: string[]) => (m: string) => all.some((q) => keys.includes(q) && api.query[q][m]);
+  const getKeys = (s: string) => Object.keys(derives[s]);
+  const creator = (s: string, m: string) => derives[s][m](instanceId, api);
+  const isIncluded = (c: string) => (!checks[c] || (
+    (checks[c].instances.some(filterKeys) && (
+      !checks[c].methods.length ||
+      checks[c].methods.every(filterMethods(checks[c].instances))
+    )) ||
+    (
+      checks[c].withDetect &&
+      checks[c].instances.some(filterInstances)
+    )
+  ));
+
+  for (let i = 0, count = names.length; i < count; i++) {
+    const name = names[i];
+
+    isIncluded(name) &&
+      lazyDeriveSection(result, name, getKeys, creator);
+  }
+
+  return result as ExactDerive;
+}
+
+// FIXME The return type of this function should be {...ExactDerive, ...DeriveCustom}
+// For now we just drop the custom derive typings
+/** @internal */
+export function getAvailableDerives (instanceId: string, api: DeriveApi, custom: DeriveCustom = {}): ExactDerive {
+  return {
+    ...injectFunctions(instanceId, api, derive as DeriveCustom),
+    ...injectFunctions(instanceId, api, custom)
+  };
+}

package/src/chain/bestNumber.ts

@@ -0,0 +1,21 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { DeriveApi } from '../types.js';
+
+import { createBlockNumberDerive } from './util.js';
+
+/**
+ * @name bestNumber
+ * @descrive Retrieves the latest block number.
+ * @example
+ * ```javascript
+ * api.derive.chain.bestNumber((blockNumber) => {
+ *   console.log(`the current best block is #${blockNumber}`);
+ * });
+ * ```
+ */
+export const bestNumber = /*#__PURE__*/ createBlockNumberDerive(
+  (api: DeriveApi) =>
+    api.rpc.chain.subscribeNewHeads()
+);

package/src/chain/bestNumberFinalized.ts

@@ -0,0 +1,22 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { DeriveApi } from '../types.js';
+
+import { createBlockNumberDerive } from './util.js';
+
+/**
+ * @name bestNumberFinalized
+ * @returns A BlockNumber
+ * @description Get the latest finalized block number.
+ * @example
+ * ```javascript
+ * api.derive.chain.bestNumberFinalized((blockNumber) => {
+ *   console.log(`the current finalized block is #${blockNumber}`);
+ * });
+ * ```
+ */
+export const bestNumberFinalized = /*#__PURE__*/ createBlockNumberDerive(
+  (api: DeriveApi) =>
+    api.rpc.chain.subscribeFinalizedHeads()
+);

package/src/chain/bestNumberLag.ts

@@ -0,0 +1,33 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Observable } from 'rxjs';
+import type { BlockNumber } from '@pezkuwi/types/interfaces';
+import type { DeriveApi } from '../types.js';
+
+import { combineLatest, map } from 'rxjs';
+
+import { memo } from '../util/index.js';
+
+/**
+ * @name bestNumberLag
+ * @returns A number of blocks
+ * @description Calculates the lag between finalized head and best head
+ * @examplew
+ * ```javascript
+ * api.derive.chain.bestNumberLag((lag) => {
+ *   console.log(`finalized is ${lag} blocks behind head`);
+ * });
+ * ```
+ */
+export function bestNumberLag (instanceId: string, api: DeriveApi): () => Observable<BlockNumber> {
+  return memo(instanceId, (): Observable<BlockNumber> =>
+    combineLatest([
+      api.derive.chain.bestNumber(),
+      api.derive.chain.bestNumberFinalized()
+    ]).pipe(
+      map(([bestNumber, bestNumberFinalized]): BlockNumber =>
+        api.registry.createType('BlockNumber', bestNumber.sub(bestNumberFinalized))
+      )
+    ));
+}

package/src/chain/getBlock.ts

@@ -0,0 +1,43 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Observable } from 'rxjs';
+import type { SignedBlockExtended } from '../type/types.js';
+import type { DeriveApi } from '../types.js';
+
+import { combineLatest, map, of, switchMap } from 'rxjs';
+
+import { createSignedBlockExtended } from '../type/index.js';
+import { memo } from '../util/index.js';
+import { getAuthorDetails } from './util.js';
+
+/**
+ * @name getBlock
+ * @param {( Uint8Array | string )} hash A block hash as U8 array or string.
+ * @description Get a specific block (e.g. rpc.chain.getBlock) and extend it with the author
+ * @example
+ * ```javascript
+ * const { author, block } = await api.derive.chain.getBlock('0x123...456');
+ *
+ * console.log(`block #${block.header.number} was authored by ${author}`);
+ * ```
+ */
+export function getBlock (instanceId: string, api: DeriveApi): (hash: Uint8Array | string) => Observable<SignedBlockExtended> {
+  return memo(instanceId, (blockHash: Uint8Array | string): Observable<SignedBlockExtended> =>
+    combineLatest([
+      api.rpc.chain.getBlock(blockHash),
+      api.queryAt(blockHash)
+    ]).pipe(
+      switchMap(([signedBlock, queryAt]) =>
+        combineLatest([
+          of(signedBlock),
+          queryAt.system.events(),
+          getAuthorDetails(api, signedBlock.block.header, blockHash)
+        ])
+      ),
+      map(([signedBlock, events, [, validators, author]]) =>
+        createSignedBlockExtended(events.registry, signedBlock, events, validators, author)
+      )
+    )
+  );
+}

package/src/chain/getBlockByNumber.ts

@@ -0,0 +1,30 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Observable } from 'rxjs';
+import type { AnyNumber } from '@pezkuwi/types/types';
+import type { SignedBlockExtended } from '../type/types.js';
+import type { DeriveApi } from '../types.js';
+
+import { switchMap } from 'rxjs';
+
+import { memo } from '../util/index.js';
+
+/**
+ * @name getBlockByNumber
+ * @param {( BN | bigint | Uint8Array | number | string )} blockNumber
+ * @description Get a specific block (e.g. rpc.chain.getBlock) and extend it with the author by block number
+ * @example
+ * ```javascript
+ * const { author, block } = await api.derive.chain.getBlockByNumber(123);
+ *
+ * console.log(`block #${block.header.number} was authored by ${author}`);
+ * ```
+ */
+export function getBlockByNumber (instanceId: string, api: DeriveApi): (blockNumber: AnyNumber) => Observable<SignedBlockExtended> {
+  return memo(instanceId, (blockNumber: AnyNumber): Observable<SignedBlockExtended> =>
+    api.rpc.chain.getBlockHash(blockNumber).pipe(
+      switchMap((h) => api.derive.chain.getBlock(h))
+    )
+  );
+}

package/src/chain/getHeader.ts

@@ -0,0 +1,37 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Observable } from 'rxjs';
+import type { HeaderExtended } from '../type/types.js';
+import type { DeriveApi } from '../types.js';
+
+import { map, switchMap } from 'rxjs';
+
+import { createHeaderExtended } from '../type/index.js';
+import { memo } from '../util/index.js';
+import { getAuthorDetails } from './util.js';
+
+/**
+ * @name getHeader
+ * @param {( Uint8Array | string )} hash - A block hash as U8 array or string.
+ * @returns An array containing the block header and the block author
+ * @description Get a specific block header and extend it with the author
+ * @example
+ * ```javascript
+ * const { author, number } = await api.derive.chain.getHeader('0x123...456');
+ *
+ * console.log(`block #${number} was authored by ${author}`);
+ * ```
+ */
+export function getHeader (instanceId: string, api: DeriveApi): (blockHash: Uint8Array | string) => Observable<HeaderExtended> {
+  return memo(instanceId, (blockHash: Uint8Array | string): Observable<HeaderExtended> =>
+    api.rpc.chain.getHeader(blockHash).pipe(
+      switchMap((header) =>
+        getAuthorDetails(api, header, blockHash)
+      ),
+      map(([header, validators, author]) =>
+        createHeaderExtended((validators || header).registry, header, validators, author)
+      )
+    )
+  );
+}

package/src/chain/index.ts

@@ -0,0 +1,13 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export * from './bestNumber.js';
+export * from './bestNumberFinalized.js';
+export * from './bestNumberLag.js';
+export * from './getBlock.js';
+export * from './getBlockByNumber.js';
+export * from './getHeader.js';
+export * from './subscribeFinalizedBlocks.js';
+export * from './subscribeFinalizedHeads.js';
+export * from './subscribeNewBlocks.js';
+export * from './subscribeNewHeads.js';

package/src/chain/subscribeFinalizedBlocks.ts

@@ -0,0 +1,30 @@
+// Copyright 2017-2025 @polkadot/api-derive authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Observable } from 'rxjs';
+import type { SignedBlockExtended } from '../type/types.js';
+import type { DeriveApi } from '../types.js';
+
+import { mergeMap } from 'rxjs';
+
+import { memo } from '../util/index.js';
+
+/**
+ * @name subscribeFinalizedBlocks
+ * @description Retrieves the finalized block & events for that block
+ * @example
+ * ```javascript
+ * const unsub = await api.derive.chain.subscribeFinalizedBlocks((finalizedBlock) => {
+ *  console.log(`# Finalized block ${finalizedBlock.block.hash}`);
+ * });
+ * ```
+ */
+export function subscribeFinalizedBlocks (instanceId: string, api: DeriveApi): () => Observable<SignedBlockExtended> {
+  return memo(instanceId, (): Observable<SignedBlockExtended> =>
+    api.derive.chain.subscribeFinalizedHeads().pipe(
+      mergeMap((header) =>
+        api.derive.chain.getBlock(header.createdAtHash || header.hash)
+      )
+    )
+  );
+}