Line data    Source code

       1             : #ifndef HEADER_fd_src_flamenco_runtime_sysvar_epoch_schedule_h
       2             : #define HEADER_fd_src_flamenco_runtime_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_flamenco_base.h"
      34             : #include "../context/fd_exec_slot_ctx.h"
      35             : 
      36             : /* FD_EPOCH_LEN_MIN is a protocol constant specifying the smallest
      37             :    permitted epoch length.  This value is chosen to match
      38             :    MAX_LOCKOUT_HISTORY, which is the minimum slot count needed to reach
      39             :    finality in Tower BFT.
      40             : 
      41             :    https://github.com/solana-labs/solana/blob/88aeaa82a856fc807234e7da0b31b89f2dc0e091/sdk/program/src/epoch_schedule.rs#L21 */
      42             : 
      43      143244 : #define FD_EPOCH_LEN_MIN (32UL)
      44             : 
      45             : /* FD_EPOCH_LEN_MIN_TRAILING_ZERO stores the number of trailing zeroes of FD_EPOCH_LEN_MIN */
      46           0 : #define FD_EPOCH_LEN_MIN_TRAILING_ZERO (5UL)
      47             : 
      48             : /* FD_EPOCH_LEN_MAX is an implementation-defined epoch size limit.
      49             :    Technically, there is no epoch length limit (other than the max slot
      50             :    number ULONG_MAX).  We enforce a limit regardless to prevent overflow
      51             :    in math operations. */
      52             : 
      53             : #define FD_EPOCH_LEN_MAX (0xFFFFFFFFUL)
      54             : 
      55             : FD_PROTOTYPES_BEGIN
      56             : 
      57             : /* fd_sysvar_epoch_schedule_init initializes the epoch schedule sysvar
      58             :    account.  FIXME document what this actually does. */
      59             : 
      60             : void
      61             : fd_sysvar_epoch_schedule_init( fd_exec_slot_ctx_t * slot_ctx );
      62             : 
      63             : /* fd_sysvar_epoch_schedule_read reads the current value of the epoch
      64             :    schedule sysvar into result. */
      65             : 
      66             : fd_epoch_schedule_t *
      67             : fd_sysvar_epoch_schedule_read( fd_epoch_schedule_t * result,
      68             :                                fd_exec_slot_ctx_t const * slot_ctx );
      69             : 
      70             : /* fd_epoch_schedule_derive derives an epoch schedule config from the
      71             :    given parameters.  New epoch schedule configurations should only be
      72             :    created using this function.  Returns schedule on success.
      73             :    On failure, returns NULL and logs reason.
      74             : 
      75             :    - schedule points to the epoch schedule struct to be initialized.
      76             :    - epoch_len configures the target slot count per epoch (>0)
      77             :    - leader_schedule_slot_offset configures when to generate the leader
      78             :      schedule for an epoch, measured in number of slots before the start
      79             :      of that epoch.
      80             :    - warmup controls whether to set a warmup period  (0 if disabled,
      81             :      1 if enabled). */
      82             : 
      83             : fd_epoch_schedule_t *
      84             : fd_epoch_schedule_derive( fd_epoch_schedule_t * schedule,
      85             :                           ulong                 epoch_len,
      86             :                           ulong                 leader_schedule_slot_offset,
      87             :                           int                   warmup );
      88             : 
      89             : /* fd_epoch_slot_cnt returns the number of slots in an epoch given an
      90             :    epoch schedule config and an epoch number.  Return value > 0 */
      91             : 
      92             : FD_FN_PURE ulong
      93             : fd_epoch_slot_cnt( fd_epoch_schedule_t const * schedule,
      94             :                    ulong                       epoch );
      95             : 
      96             : /* fd_epoch_slot0 returns the absolute slot number of the first slot
      97             :    in an epoch. */
      98             : 
      99             : FD_FN_PURE ulong
     100             : fd_epoch_slot0( fd_epoch_schedule_t const * schedule,
     101             :                 ulong                       epoch );
     102             : 
     103             : /* fd_slot_to_epoch returns the epoch number of the epoch containing
     104             :    the given slot number. If out_offset_opt != NULL, on return
     105             :    *out_offset_opt contains the number of slots that precede the given
     106             :    slot in the same epoch.  U.B. if schedule->slots_per_epoch is zero. */
     107             : 
     108             : ulong
     109             : fd_slot_to_epoch( fd_epoch_schedule_t const * schedule,
     110             :                   ulong                       slot,
     111             :                   ulong *                     out_offset_opt );
     112             : 
     113             : ulong
     114             : fd_slot_to_leader_schedule_epoch( fd_epoch_schedule_t const * schedule,
     115             :                                   ulong                       slot );
     116             : 
     117             : FD_PROTOTYPES_END
     118             : 
     119             : #endif /* HEADER_fd_src_flamenco_runtime_sysvar_epoch_schedule_h */