Line data    Source code

       1             : #ifndef HEADER_fd_src_flamenco_runtime_sysvar_fd_sysvar_epoch_schedule_h
       2             : #define HEADER_fd_src_flamenco_runtime_sysvar_fd_sysvar_epoch_schedule_h
       3             : 
       4             : /* fd_sysvar_epoch_schedule provides methods for epoch numbers, a native
       5             :    concept of the Solana runtime.
       6             : 
       7             :    Every Solana slot is assigned an epoch number (ulong), starting with
       8             :    epoch 0.  The epoch number either stays constant or increments by one
       9             :    between two slots.
      10             : 
      11             :    The length of an epoch is the count of consecutive slots that have
      12             :    the same epoch number.  The series of epochs consists of two parts:
      13             :    The warmup period (which may span zero epochs), and the constant
      14             :    period (which is infinite).
      15             : 
      16             :    In the warmup period, the length of an epoch starts small and
      17             :    exponentially increases.  The length of each epoch in the warmup
      18             :    period is 2^x where x is (epoch_number - min_exp).  min_exp is
      19             :    ceil(log2(FD_EPOCH_LEN_MIN)).
      20             : 
      21             :    In the constant period, the length of each epoch stays the same.
      22             :    Note that the Solana protocol may introduce a breaking change in the
      23             :    future that changes the epoch length.  The code does not yet account
      24             :    for that.
      25             : 
      26             :    The epoch schedule is used to derive the epoch number of each slot.
      27             :    It does this by specifying at which slots the epoch number increments
      28             :    (epoch boundary).
      29             : 
      30             :    The epoch schedule sysvar contains epoch scheduling constants used to
      31             :    make various epoch-related calculations. */
      32             : 
      33             : #include "../fd_bank.h"
      34             : 
      35             : /* FD_EPOCH_LEN_MIN is a protocol constant specifying the smallest
      36             :    permitted epoch length.  This value is chosen to match
      37             :    MAX_LOCKOUT_HISTORY, which is the minimum slot count needed to reach
      38             :    finality in Tower BFT.
      39             : 
      40             :    https://github.com/solana-labs/solana/blob/88aeaa82a856fc807234e7da0b31b89f2dc0e091/sdk/program/src/epoch_schedule.rs#L21 */
      41             : 
      42      117102 : #define FD_EPOCH_LEN_MIN (32UL)
      43             : 
      44             : /* FD_EPOCH_LEN_MIN_TRAILING_ZERO stores the number of trailing zeroes of FD_EPOCH_LEN_MIN */
      45           0 : #define FD_EPOCH_LEN_MIN_TRAILING_ZERO (5UL)
      46             : 
      47             : /* FD_EPOCH_LEN_MAX is an implementation-defined epoch size limit.
      48             :    Technically, there is no epoch length limit (other than the max slot
      49             :    number ULONG_MAX).  We enforce a limit regardless to prevent overflow
      50             :    in math operations. */
      51             : 
      52             : #define FD_EPOCH_LEN_MAX (0xFFFFFFFFUL)
      53             : 
      54             : FD_PROTOTYPES_BEGIN
      55             : 
      56             : /* fd_epoch_schedule_derive populates an epoch schedule from a
      57             :    user-provided epoch length and leader-schedule slot offset.  Returns
      58             :    schedule on success, NULL if epoch_len is outside [FD_EPOCH_LEN_MIN,
      59             :    FD_EPOCH_LEN_MAX] (logs a warning). */
      60             : 
      61             : fd_epoch_schedule_t *
      62             : fd_epoch_schedule_derive( fd_epoch_schedule_t * schedule,
      63             :                           ulong                 epoch_len,
      64             :                           ulong                 leader_schedule_slot_offset,
      65             :                           int                   warmup );
      66             : 
      67             : /* fd_sysvar_epoch_schedule_init initializes the epoch schedule sysvar
      68             :    account.  FIXME document what this actually does. */
      69             : 
      70             : void
      71             : fd_sysvar_epoch_schedule_init( fd_bank_t *        bank,
      72             :                                fd_accdb_t *       accdb,
      73             :                                fd_capture_ctx_t * capture_ctx );
      74             : 
      75             : /* fd_sysvar_epoch_schedule_write writes the current value of the epoch
      76             :    schedule sysvar to the accounts database. */
      77             : 
      78             : void
      79             : fd_sysvar_epoch_schedule_write( fd_bank_t *                 bank,
      80             :                                 fd_accdb_t *                accdb,
      81             :                                 fd_capture_ctx_t *          capture_ctx,
      82             :                                 fd_epoch_schedule_t const * epoch_schedule );
      83             : 
      84             : /* fd_epoch_slot_cnt returns the number of slots in an epoch given an
      85             :    epoch schedule config and an epoch number.  Return value > 0 */
      86             : 
      87             : FD_FN_PURE ulong
      88             : fd_epoch_slot_cnt( fd_epoch_schedule_t const * schedule,
      89             :                    ulong                       epoch );
      90             : 
      91             : /* fd_epoch_slot0 returns the absolute slot number of the first slot
      92             :    in an epoch. */
      93             : 
      94             : FD_FN_PURE ulong
      95             : fd_epoch_slot0( fd_epoch_schedule_t const * schedule,
      96             :                 ulong                       epoch );
      97             : 
      98             : /* fd_slot_to_epoch returns the epoch number of the epoch containing
      99             :    the given slot number. If out_offset_opt != NULL, on return
     100             :    *out_offset_opt contains the number of slots that precede the given
     101             :    slot in the same epoch.  U.B. if schedule->slots_per_epoch is zero. */
     102             : 
     103             : ulong
     104             : fd_slot_to_epoch( fd_epoch_schedule_t const * schedule,
     105             :                   ulong                       slot,
     106             :                   ulong *                     out_offset_opt );
     107             : 
     108             : ulong
     109             : fd_slot_to_leader_schedule_epoch( fd_epoch_schedule_t const * schedule,
     110             :                                   ulong                       slot );
     111             : 
     112             : FD_PROTOTYPES_END
     113             : 
     114             : #endif /* HEADER_fd_src_flamenco_runtime_sysvar_fd_sysvar_epoch_schedule_h */