@substrate/api-sidecar
Version:
REST service that makes it easy to interact with blockchain nodes built using Substrate's FRAME framework.
90 lines (89 loc) • 4.32 kB
TypeScript
import { BlockHash } from '@polkadot/types/interfaces';
import { IPalletStakingProgress } from 'src/types/responses';
import { AbstractService } from '../AbstractService';
interface IStakingProgressOptions {
isRcCall?: boolean;
}
export declare class PalletsStakingProgressService extends AbstractService {
/**
* Fetch and derive generalized staking information at a given block.
*
* @param hash `BlockHash` to make call at
*/
derivePalletStakingProgress(hash: BlockHash, options?: IStakingProgressOptions): Promise<IPalletStakingProgress>;
/**
* Derive session and era progress for Asset Hub using time-based BABE calculations
*
* This method calculates session and era progress for Asset Hub by deriving all values
* from scratch using time-based BABE formulas. This approach is necessary because:
*
* 1. **Historical Support**: Asset Hub cannot access historical BABE pallet constants
* from the relay chain, so we need to calculate everything from time
* 2. **Time-Based Nature**: BABE slots and epochs are purely time-based and can be
* calculated deterministically without chain state
* 3. **Relay Chain Dependency**: Asset Hub needs to query the relay chain for
* skipped epochs, but can calculate slots/epochs locally
*
* **Calculations:**
* - **Current Slot**: `timestamp / slot_duration` (6 seconds for all networks)
* - **Epoch Index**: `(current_slot - genesis_slot) / epoch_duration`
* - **Session Index**: Derived from epoch index using SkippedEpochs mapping
* - **Session Progress**: `current_slot - epoch_start_slot`
* - **Era Progress**: `(current_session - era_start_session) * session_length + session_progress`
*
* **Data Sources:**
* - **Time-based**: Current timestamp, hardcoded BABE parameters
* - **Chain state**: Active era, bonded eras, session index, skipped epochs
*
* @param historicApi - Asset Hub API for staking queries
* @param RCApi - Relay chain API for BABE queries (session index, skipped epochs)
* @returns Session and era progress information
*/
private deriveSessionAndEraProgressAssetHub;
/**
* Derive information on the progress of the current session and era.
*
* @param api ApiPromise with ensured metadata
* @param hash `BlockHash` to make call at
*/
private deriveSessionAndEraProgress;
/**
* Get electionLookAhead as a const if available. Otherwise derive
* `electionLookAhead` based on the `specName` & `epochDuration`.
* N.B. Values are hardcoded based on `specName`s polkadot, kusama, and westend.
* There are no guarantees that this will return the expected values for
* other `specName`s.
*
* @param api ApiPromise with ensured metadata
* @param hash `BlockHash` to make call at
*/
private deriveElectionLookAhead;
/**
* Calculate session index from epoch index using SkippedEpochs mapping
*
* In BABE consensus, epochs advance based on time and can be "skipped" if the chain
* is offline, but sessions (which represent authority set changes) must happen
* sequentially and cannot be skipped.
*
* When epochs are skipped, BABE stores the mapping in `SkippedEpochs` to track
* the permanent offset between epoch and session indices.
*
* **Example:**
* - Normal: Epoch 10 → Session 10, Epoch 11 → Session 11
* - Chain offline during epochs 12-15
* - After downtime: Epoch 16 → Session 12 (sessions 13-16 were "lost")
* - `SkippedEpochs` stores: [(16, 12)] indicating epoch 16 maps to session 12
* - Future epochs: Epoch 17 → Session 13, Epoch 18 → Session 14, etc.
*
* **Algorithm:**
* 1. Find the closest skipped epoch ≤ current epoch
* 2. Calculate permanent offset: `skipped_epoch - skipped_session`
* 3. Apply offset: `session_index = current_epoch - permanent_offset`
*
* @param epochIndex - Current epoch index (time-based)
* @param skippedEpochs - BABE SkippedEpochs storage: Vec<(u64, u32)> mapping epoch to session
* @returns Current session index that accounts for skipped epochs
*/
private calculateSessionIndexFromSkippedEpochs;
}
export {};