@substrate/api-sidecar 20.11.0 → 20.13.0

package/build/src/util/relay/getRelayParentNumber.d.ts

@@ -0,0 +1,80 @@
+import { ApiPromise } from '@polkadot/api';
+import { BlockHash } from '@polkadot/types/interfaces';
+import BN from 'bn.js';
+/**
+ * Result of searching for a parachain block's inclusion on the relay chain.
+ */
+export interface IInclusionSearchResult {
+    /** The relay chain block number where the parachain block was included */
+    inclusionBlockNumber: number | null;
+    /** The relay parent number from setValidationData */
+    relayParentNumber: number;
+    /** Whether the inclusion was found */
+    found: boolean;
+}
+/**
+ * Extract the relay chain parent block number from a parachain block.
+ *
+ * Parachain blocks contain a `parachainSystem.setValidationData` extrinsic that
+ * includes the relay chain block number that was the parent when the parachain
+ * block was created.
+ *
+ * Note: This is the relay PARENT, not the inclusion block. For the actual
+ * inclusion block, use `getInclusionBlockNumber` or `searchForInclusionBlock`.
+ *
+ * @param api - The ApiPromise instance connected to the parachain
+ * @param blockHash - The hash of the parachain block to extract relay parent from
+ * @returns The relay chain parent block number as a BN
+ * @throws Error if the block doesn't contain setValidationData extrinsic
+ */
+export declare const getRelayParentNumber: (api: ApiPromise, blockHash: BlockHash) => Promise<BN>;
+/**
+ * Extract relay parent number as a plain number (for use with search functions).
+ *
+ * @param api - The ApiPromise instance connected to the parachain
+ * @param blockHash - The hash of the parachain block
+ * @returns The relay chain parent block number as a number
+ */
+export declare const getRelayParentNumberRaw: (api: ApiPromise, blockHash: BlockHash) => Promise<number>;
+/**
+ * Check if a block contains the setValidationData extrinsic.
+ *
+ * This can be used to determine if a block is from a parachain (has validation data)
+ * or a relay chain (does not have validation data).
+ *
+ * @param api - The ApiPromise instance
+ * @param blockHash - The hash of the block to check
+ * @returns true if the block contains setValidationData, false otherwise
+ */
+export declare const hasRelayParentData: (api: ApiPromise, blockHash: BlockHash) => Promise<boolean>;
+/**
+ * Search relay chain blocks for the inclusion of a specific parachain block.
+ *
+ * This searches relay chain blocks starting from `relayParentNumber + 1` looking
+ * for a `paraInclusion.CandidateIncluded` event that matches the given parachain
+ * block number and paraId.
+ *
+ * @param rcApi - The ApiPromise instance connected to the relay chain
+ * @param paraId - The parachain ID (e.g., 1000 for Asset Hub)
+ * @param parachainBlockNumber - The parachain block number to search for
+ * @param relayParentNumber - The relay parent number from setValidationData
+ * @param maxDepth - Maximum number of relay blocks to search (default: 10)
+ * @returns The relay chain block number where inclusion was found, or null if not found
+ */
+export declare const searchForInclusionBlock: (rcApi: ApiPromise, paraId: number, parachainBlockNumber: string, relayParentNumber: number, maxDepth?: number) => Promise<number | null>;
+/**
+ * Get the relay chain block number where a parachain block was included.
+ *
+ * This is the main function for finding the accurate relay chain block number
+ * corresponding to a parachain block. It:
+ * 1. Extracts the relayParentNumber from the parachain block's setValidationData
+ * 2. Searches relay chain blocks for the actual inclusion event
+ *
+ * @param parachainApi - The ApiPromise instance connected to the parachain
+ * @param rcApi - The ApiPromise instance connected to the relay chain
+ * @param parachainBlockHash - The hash of the parachain block
+ * @param paraId - The parachain ID (e.g., 1000 for Asset Hub)
+ * @param maxDepth - Maximum number of relay blocks to search (default: 10)
+ * @returns The inclusion search result with inclusionBlockNumber, relayParentNumber, and found status
+ */
+export declare const getInclusionBlockNumber: (parachainApi: ApiPromise, rcApi: ApiPromise, parachainBlockHash: BlockHash, paraId: number, maxDepth?: number) => Promise<IInclusionSearchResult>;

package/build/src/util/relay/getRelayParentNumber.js

@@ -0,0 +1,170 @@
+"use strict";
+// Copyright 2017-2025 Parity Technologies (UK) Ltd.
+// This file is part of Substrate API Sidecar.
+//
+// Substrate API Sidecar is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getInclusionBlockNumber = exports.searchForInclusionBlock = exports.hasRelayParentData = exports.getRelayParentNumberRaw = exports.getRelayParentNumber = void 0;
+const bn_js_1 = __importDefault(require("bn.js"));
+/** Default search depth for inclusion search */
+const DEFAULT_SEARCH_DEPTH = 10;
+/** Batch size for parallel searches */
+const BATCH_SIZE = 5;
+/**
+ * Extract the relay chain parent block number from a parachain block.
+ *
+ * Parachain blocks contain a `parachainSystem.setValidationData` extrinsic that
+ * includes the relay chain block number that was the parent when the parachain
+ * block was created.
+ *
+ * Note: This is the relay PARENT, not the inclusion block. For the actual
+ * inclusion block, use `getInclusionBlockNumber` or `searchForInclusionBlock`.
+ *
+ * @param api - The ApiPromise instance connected to the parachain
+ * @param blockHash - The hash of the parachain block to extract relay parent from
+ * @returns The relay chain parent block number as a BN
+ * @throws Error if the block doesn't contain setValidationData extrinsic
+ */
+const getRelayParentNumber = async (api, blockHash) => {
+    const [apiAt, { block }] = await Promise.all([api.at(blockHash), api.rpc.chain.getBlock(blockHash)]);
+    const setValidationData = block.extrinsics.find((ext) => {
+        return ext.method.method.toString() === 'setValidationData';
+    });
+    if (!setValidationData) {
+        throw new Error('Block does not contain setValidationData extrinsic. Cannot determine relay parent number.');
+    }
+    const callArgs = apiAt.registry.createType('Call', setValidationData.method);
+    const { relayParentNumber } = callArgs.toJSON().args.data.validationData;
+    return new bn_js_1.default(relayParentNumber);
+};
+exports.getRelayParentNumber = getRelayParentNumber;
+/**
+ * Extract relay parent number as a plain number (for use with search functions).
+ *
+ * @param api - The ApiPromise instance connected to the parachain
+ * @param blockHash - The hash of the parachain block
+ * @returns The relay chain parent block number as a number
+ */
+const getRelayParentNumberRaw = async (api, blockHash) => {
+    const [apiAt, { block }] = await Promise.all([api.at(blockHash), api.rpc.chain.getBlock(blockHash)]);
+    const setValidationData = block.extrinsics.find((ext) => {
+        return ext.method.method.toString() === 'setValidationData';
+    });
+    if (!setValidationData) {
+        throw new Error('Block does not contain setValidationData extrinsic. Cannot determine relay parent number.');
+    }
+    const callArgs = apiAt.registry.createType('Call', setValidationData.method);
+    const { relayParentNumber } = callArgs.toJSON().args.data.validationData;
+    return relayParentNumber;
+};
+exports.getRelayParentNumberRaw = getRelayParentNumberRaw;
+/**
+ * Check if a block contains the setValidationData extrinsic.
+ *
+ * This can be used to determine if a block is from a parachain (has validation data)
+ * or a relay chain (does not have validation data).
+ *
+ * @param api - The ApiPromise instance
+ * @param blockHash - The hash of the block to check
+ * @returns true if the block contains setValidationData, false otherwise
+ */
+const hasRelayParentData = async (api, blockHash) => {
+    const { block } = await api.rpc.chain.getBlock(blockHash);
+    return block.extrinsics.some((ext) => ext.method.method.toString() === 'setValidationData');
+};
+exports.hasRelayParentData = hasRelayParentData;
+/**
+ * Search relay chain blocks for the inclusion of a specific parachain block.
+ *
+ * This searches relay chain blocks starting from `relayParentNumber + 1` looking
+ * for a `paraInclusion.CandidateIncluded` event that matches the given parachain
+ * block number and paraId.
+ *
+ * @param rcApi - The ApiPromise instance connected to the relay chain
+ * @param paraId - The parachain ID (e.g., 1000 for Asset Hub)
+ * @param parachainBlockNumber - The parachain block number to search for
+ * @param relayParentNumber - The relay parent number from setValidationData
+ * @param maxDepth - Maximum number of relay blocks to search (default: 10)
+ * @returns The relay chain block number where inclusion was found, or null if not found
+ */
+const searchForInclusionBlock = async (rcApi, paraId, parachainBlockNumber, relayParentNumber, maxDepth = DEFAULT_SEARCH_DEPTH) => {
+    // Search in batches for optimal performance
+    // Most inclusions happen within 2-4 blocks of relayParentNumber
+    for (let offset = 0; offset < maxDepth; offset += BATCH_SIZE) {
+        const batchSize = Math.min(BATCH_SIZE, maxDepth - offset);
+        const searchBlocks = Array.from({ length: batchSize }, (_, i) => relayParentNumber + offset + i + 1);
+        const searchPromises = searchBlocks.map(async (blockNum) => {
+            try {
+                const relayBlockHash = await rcApi.rpc.chain.getBlockHash(blockNum);
+                const rcApiAt = await rcApi.at(relayBlockHash);
+                const events = await rcApiAt.query.system.events();
+                const foundInclusion = events.find((record) => {
+                    if (record.event.section === 'paraInclusion' && record.event.method === 'CandidateIncluded') {
+                        const eventData = record.event.data[0].toJSON();
+                        if (eventData.descriptor.paraId === paraId) {
+                            const header = rcApiAt.registry.createType('Header', record.event.data[1]);
+                            return header.number.toString() === parachainBlockNumber;
+                        }
+                    }
+                    return false;
+                });
+                return foundInclusion ? blockNum : null;
+            }
+            catch {
+                return null;
+            }
+        });
+        const results = await Promise.all(searchPromises);
+        const found = results.find((result) => result !== null);
+        if (found) {
+            return found; // Early termination when found in this batch
+        }
+    }
+    return null; // Not found within search depth
+};
+exports.searchForInclusionBlock = searchForInclusionBlock;
+/**
+ * Get the relay chain block number where a parachain block was included.
+ *
+ * This is the main function for finding the accurate relay chain block number
+ * corresponding to a parachain block. It:
+ * 1. Extracts the relayParentNumber from the parachain block's setValidationData
+ * 2. Searches relay chain blocks for the actual inclusion event
+ *
+ * @param parachainApi - The ApiPromise instance connected to the parachain
+ * @param rcApi - The ApiPromise instance connected to the relay chain
+ * @param parachainBlockHash - The hash of the parachain block
+ * @param paraId - The parachain ID (e.g., 1000 for Asset Hub)
+ * @param maxDepth - Maximum number of relay blocks to search (default: 10)
+ * @returns The inclusion search result with inclusionBlockNumber, relayParentNumber, and found status
+ */
+const getInclusionBlockNumber = async (parachainApi, rcApi, parachainBlockHash, paraId, maxDepth = DEFAULT_SEARCH_DEPTH) => {
+    // Get the parachain block header to get the block number
+    const header = await parachainApi.rpc.chain.getHeader(parachainBlockHash);
+    const parachainBlockNumber = header.number.unwrap().toString();
+    // Extract relay parent number from the parachain block
+    const relayParentNumber = await (0, exports.getRelayParentNumberRaw)(parachainApi, parachainBlockHash);
+    // Search for the actual inclusion block
+    const inclusionBlockNumber = await (0, exports.searchForInclusionBlock)(rcApi, paraId, parachainBlockNumber, relayParentNumber, maxDepth);
+    return {
+        inclusionBlockNumber,
+        relayParentNumber,
+        found: inclusionBlockNumber !== null,
+    };
+};
+exports.getInclusionBlockNumber = getInclusionBlockNumber;
+//# sourceMappingURL=getRelayParentNumber.js.map

package/build/src/util/relay/getRelayParentNumber.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getRelayParentNumber.js","sourceRoot":"","sources":["../../../../src/util/relay/getRelayParentNumber.ts"],"names":[],"mappings":"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"}

package/build/src/util/relay/getRelayParentNumber.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/build/src/util/relay/getRelayParentNumber.spec.js

@@ -0,0 +1,201 @@
+"use strict";
+// Copyright 2017-2025 Parity Technologies (UK) Ltd.
+// This file is part of Substrate API Sidecar.
+//
+// Substrate API Sidecar is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const bn_js_1 = __importDefault(require("bn.js"));
+const registries_1 = require("../../test-helpers/registries");
+const getRelayParentNumber_1 = require("./getRelayParentNumber");
+const mockBlockHash = registries_1.polkadotRegistry.createType('BlockHash', '0x7b713de604a99857f6c25eacc115a4f28d2611a23d9ddff99ab0e4f1c17a8578');
+const mockRelayParentNumber = 28500000;
+/**
+ * Create a mock extrinsic that simulates setValidationData
+ */
+const createMockSetValidationDataExtrinsic = () => ({
+    method: {
+        method: {
+            toString: () => 'setValidationData',
+        },
+    },
+});
+/**
+ * Create a mock extrinsic that is NOT setValidationData
+ */
+const createMockOtherExtrinsic = (methodName) => ({
+    method: {
+        method: {
+            toString: () => methodName,
+        },
+    },
+});
+/**
+ * Create a mock registry.createType that returns the expected structure
+ */
+const createMockCreateType = (relayParentNumber) => {
+    return (_typeName, _data) => ({
+        toJSON: () => ({
+            args: {
+                data: {
+                    validationData: {
+                        relayParentNumber,
+                    },
+                },
+            },
+        }),
+    });
+};
+describe('getRelayParentNumber', () => {
+    describe('getRelayParentNumber', () => {
+        it('should extract relay parent number from a parachain block', async () => {
+            const mockApiAt = {
+                registry: {
+                    createType: createMockCreateType(mockRelayParentNumber),
+                },
+            };
+            const mockAt = jest.fn().mockResolvedValue(mockApiAt);
+            const mockGetBlock = jest.fn().mockResolvedValue({
+                block: {
+                    extrinsics: [
+                        createMockOtherExtrinsic('timestamp'),
+                        createMockSetValidationDataExtrinsic(),
+                        createMockOtherExtrinsic('transfer'),
+                    ],
+                },
+            });
+            const mockApi = {
+                at: mockAt,
+                rpc: {
+                    chain: {
+                        getBlock: mockGetBlock,
+                    },
+                },
+            };
+            const result = await (0, getRelayParentNumber_1.getRelayParentNumber)(mockApi, mockBlockHash);
+            expect(result).toBeInstanceOf(bn_js_1.default);
+            expect(result.toNumber()).toBe(mockRelayParentNumber);
+            expect(mockAt).toHaveBeenCalledWith(mockBlockHash);
+            expect(mockGetBlock).toHaveBeenCalledWith(mockBlockHash);
+        });
+        it('should throw error when setValidationData extrinsic is not found', async () => {
+            const mockApi = {
+                at: jest.fn().mockResolvedValue({}),
+                rpc: {
+                    chain: {
+                        getBlock: jest.fn().mockResolvedValue({
+                            block: {
+                                extrinsics: [createMockOtherExtrinsic('timestamp'), createMockOtherExtrinsic('transfer')],
+                            },
+                        }),
+                    },
+                },
+            };
+            await expect((0, getRelayParentNumber_1.getRelayParentNumber)(mockApi, mockBlockHash)).rejects.toThrow('Block does not contain setValidationData extrinsic. Cannot determine relay parent number.');
+        });
+        it('should handle block with only setValidationData extrinsic', async () => {
+            const mockApiAt = {
+                registry: {
+                    createType: createMockCreateType(12345678),
+                },
+            };
+            const mockApi = {
+                at: jest.fn().mockResolvedValue(mockApiAt),
+                rpc: {
+                    chain: {
+                        getBlock: jest.fn().mockResolvedValue({
+                            block: {
+                                extrinsics: [createMockSetValidationDataExtrinsic()],
+                            },
+                        }),
+                    },
+                },
+            };
+            const result = await (0, getRelayParentNumber_1.getRelayParentNumber)(mockApi, mockBlockHash);
+            expect(result.toNumber()).toBe(12345678);
+        });
+        it('should handle large relay parent numbers', async () => {
+            const largeBlockNumber = 999999999;
+            const mockApiAt = {
+                registry: {
+                    createType: createMockCreateType(largeBlockNumber),
+                },
+            };
+            const mockApi = {
+                at: jest.fn().mockResolvedValue(mockApiAt),
+                rpc: {
+                    chain: {
+                        getBlock: jest.fn().mockResolvedValue({
+                            block: {
+                                extrinsics: [createMockSetValidationDataExtrinsic()],
+                            },
+                        }),
+                    },
+                },
+            };
+            const result = await (0, getRelayParentNumber_1.getRelayParentNumber)(mockApi, mockBlockHash);
+            expect(result.toNumber()).toBe(largeBlockNumber);
+        });
+    });
+    describe('hasRelayParentData', () => {
+        it('should return true when block contains setValidationData', async () => {
+            const mockApi = {
+                rpc: {
+                    chain: {
+                        getBlock: jest.fn().mockResolvedValue({
+                            block: {
+                                extrinsics: [createMockOtherExtrinsic('timestamp'), createMockSetValidationDataExtrinsic()],
+                            },
+                        }),
+                    },
+                },
+            };
+            const result = await (0, getRelayParentNumber_1.hasRelayParentData)(mockApi, mockBlockHash);
+            expect(result).toBe(true);
+        });
+        it('should return false when block does not contain setValidationData', async () => {
+            const mockApi = {
+                rpc: {
+                    chain: {
+                        getBlock: jest.fn().mockResolvedValue({
+                            block: {
+                                extrinsics: [createMockOtherExtrinsic('timestamp'), createMockOtherExtrinsic('transfer')],
+                            },
+                        }),
+                    },
+                },
+            };
+            const result = await (0, getRelayParentNumber_1.hasRelayParentData)(mockApi, mockBlockHash);
+            expect(result).toBe(false);
+        });
+        it('should return false for empty extrinsics array', async () => {
+            const mockApi = {
+                rpc: {
+                    chain: {
+                        getBlock: jest.fn().mockResolvedValue({
+                            block: {
+                                extrinsics: [],
+                            },
+                        }),
+                    },
+                },
+            };
+            const result = await (0, getRelayParentNumber_1.hasRelayParentData)(mockApi, mockBlockHash);
+            expect(result).toBe(false);
+        });
+    });
+});
+//# sourceMappingURL=getRelayParentNumber.spec.js.map

package/build/src/util/relay/getRelayParentNumber.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getRelayParentNumber.spec.js","sourceRoot":"","sources":["../../../../src/util/relay/getRelayParentNumber.spec.ts"],"names":[],"mappings":"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"}

package/build/src/util/vesting/vestingCalculations.d.ts

@@ -0,0 +1,87 @@
+import BN from 'bn.js';
+/**
+ * Represents a vesting schedule with the essential fields needed for calculations.
+ */
+export interface IVestingSchedule {
+    /** Total amount of tokens locked at the start of vesting */
+    locked: BN;
+    /** Number of tokens that unlock per block */
+    perBlock: BN;
+    /** Block number when vesting/unlocking begins */
+    startingBlock: BN;
+}
+/**
+ * Result of vesting calculation for a single schedule.
+ */
+export interface IVestingCalculationResult {
+    /** Amount that has vested based on time elapsed */
+    vested: BN;
+    /** Block number when vesting will be complete */
+    endBlock: BN;
+}
+/**
+ * Calculate the amount that has vested for a single vesting schedule.
+ *
+ * The calculation follows the formula used in the vesting pallet:
+ * - If currentBlock <= startingBlock: nothing is vested yet
+ * - Otherwise: vested = min(blocksPassed * perBlock, locked)
+ *
+ * Note: This is the theoretical vested amount based on time. The actual
+ * claimable amount depends on the on-chain lock state (see calculateVestedClaimable).
+ *
+ * @param currentBlock - The block number to calculate vested amount at
+ * @param schedule - The vesting schedule containing locked, perBlock, and startingBlock
+ * @returns The amount that has vested at the given block
+ */
+export declare const calculateVested: (currentBlock: BN, schedule: IVestingSchedule) => BN;
+/**
+ * Calculate the block number when a vesting schedule will be fully vested.
+ *
+ * The end block is calculated as: startingBlock + (locked / perBlock)
+ *
+ * @param schedule - The vesting schedule
+ * @returns The block number when vesting completes
+ */
+export declare const calculateEndBlock: (schedule: IVestingSchedule) => BN;
+/**
+ * Calculate the total vested amount across multiple vesting schedules.
+ *
+ * @param currentBlock - The block number to calculate vested amounts at
+ * @param schedules - Array of vesting schedules
+ * @returns The total amount that has vested across all schedules (vestedBalance)
+ */
+export declare const calculateTotalVested: (currentBlock: BN, schedules: IVestingSchedule[]) => BN;
+/**
+ * Calculate the total locked amount across multiple vesting schedules.
+ *
+ * @param schedules - Array of vesting schedules
+ * @returns The total locked amount across all schedules (vestingTotal)
+ */
+export declare const calculateVestingTotal: (schedules: IVestingSchedule[]) => BN;
+/**
+ * Calculate the actual claimable amount that can be unlocked.
+ *
+ * This follows the polkadot-js formula:
+ * vestedClaimable = vestingLocked - (vestingTotal - vestedBalance)
+ *
+ * Where:
+ * - vestingLocked: actual on-chain lock amount from balances.locks
+ * - vestingTotal: sum of all locked amounts from vesting schedules
+ * - vestedBalance: sum of all vested amounts from vesting schedules
+ *
+ * The difference accounts for previous claims that reduced the on-chain lock.
+ *
+ * @param vestingLocked - The actual on-chain vesting lock amount
+ * @param vestingTotal - Total locked across all vesting schedules
+ * @param vestedBalance - Total vested across all vesting schedules
+ * @returns The amount that can actually be claimed right now
+ */
+export declare const calculateVestedClaimable: (vestingLocked: BN, vestingTotal: BN, vestedBalance: BN) => BN;
+/**
+ * Calculate vested amounts for multiple schedules, returning per-schedule results.
+ *
+ * @param currentBlock - The block number to calculate vested amounts at
+ * @param schedules - Array of vesting schedules
+ * @returns Array of calculation results with vested amount and end block for each schedule
+ */
+export declare const calculateVestingDetails: (currentBlock: BN, schedules: IVestingSchedule[]) => IVestingCalculationResult[];