LCOV - code coverage report
Current view: top level - flamenco/leaders - fd_leaders.h (source / functions) Hit Total Coverage
Test: cov.lcov Lines: 21 22 95.5 %
Date: 2025-07-15 04:56:17 Functions: 6 131 4.6 %

          Line data    Source code
       1             : #ifndef HEADER_fd_src_flamenco_leaders_fd_leaders_h
       2             : #define HEADER_fd_src_flamenco_leaders_fd_leaders_h
       3             : 
       4             : /* fd_leaders provides APIs for the Solana leader schedule.
       5             :    Logic is compatible with Solana mainnet as of 2023-Jul.
       6             : 
       7             :    Every slot is assigned a leader (identified by a "node identity"
       8             :    public key).  The sequence of leaders for all slots in an epoch is
       9             :    called the "leader schedule".  The main responsibility of the leader
      10             :    is to produce a block for the slot.
      11             : 
      12             :    The leader schedule is divided into sched_cnt rotations.  Each
      13             :    rotation spans one or more slots, such that
      14             : 
      15             :      slots_per_epoch = sched_cnt * slots_per_rotation
      16             : 
      17             :    The leader can only change between rotations.  An example leader
      18             :    schedule looks as follows (where A, B, C are node identities and each
      19             :    column is a slot, with 4 slots per rotation)
      20             : 
      21             :      A  A  A  A  B  B  B  B  B  B  B  B  C  C  C  C  A  A  A  A
      22             :      ^           ^           ^           ^           ^
      23             :      rotation    rotation    rotation    rotation    rotation
      24             : 
      25             :    The mainnet epoch duration is quite long (currently 432000 slots, for
      26             :    more information see fd_sysvar_epoch_schedule.h).  To save space, we
      27             :    dedup pubkeys into a lookup table and only store an index for each
      28             :    rotation. */
      29             : 
      30             : #include "fd_leaders_base.h"
      31             : #include "../../ballet/wsample/fd_wsample.h"
      32             : 
      33          24 : #define FD_ULONG_MAX(  a, b ) (__builtin_choose_expr( __builtin_constant_p( a ) & __builtin_constant_p( b ),        \
      34          24 :                                                       ((ulong )(a))>=((ulong )(b)) ? ((ulong )(a)) : ((ulong )(b)), \
      35          24 :                                                       fd_ulong_max( (a), (b) ) ))
      36             : 
      37             : /* FD_EPOCH_LEADERS_{ALIGN,FOOTPRINT} are compile-time-friendly versions
      38             :    of the fd_epoch_leaders_{align,footprint} functions. */
      39             : 
      40           0 : #define FD_EPOCH_LEADERS_ALIGN (64UL)
      41             : #define FD_EPOCH_LEADERS_FOOTPRINT( pub_cnt, slot_cnt )                                              \
      42        6330 :   ( FD_LAYOUT_FINI( FD_LAYOUT_APPEND( FD_LAYOUT_APPEND(                                              \
      43        6330 :     FD_LAYOUT_INIT,                                                                                  \
      44        6330 :       alignof(fd_epoch_leaders_t), sizeof(fd_epoch_leaders_t)                            ),          \
      45        6330 :       alignof(uint),               (                                                                 \
      46        6330 :         (slot_cnt+FD_EPOCH_SLOTS_PER_ROTATION-1UL)/FD_EPOCH_SLOTS_PER_ROTATION*sizeof(uint)          \
      47        6330 :         )                                                                                ),          \
      48        6330 :       FD_EPOCH_LEADERS_ALIGN                                                             )  +        \
      49        6330 :       FD_ULONG_ALIGN_UP( FD_ULONG_MAX( 32UL*((pub_cnt)+1UL),                                         \
      50        6330 :                                        FD_WSAMPLE_FOOTPRINT( pub_cnt, 0 ) ), 64UL ) )
      51             : 
      52     6795975 : #define FD_EPOCH_SLOTS_PER_ROTATION (4UL)
      53             : 
      54             : /* fd_epoch_leaders_t contains the leader schedule of a Solana epoch. */
      55             : 
      56             : struct fd_epoch_leaders {
      57             :   /* This struct contains the schedule for epoch `epoch` which spans
      58             :      slots [slot0, slot0+slot_cnt). */
      59             :   ulong epoch;
      60             :   ulong slot0;
      61             :   ulong slot_cnt;
      62             : 
      63             :   /* pub is a lookup table for node public keys with length pub_cnt */
      64             :   fd_pubkey_t * pub;
      65             :   ulong         pub_cnt;
      66             : 
      67             :   /* sched contains the leader schedule in the form of indexes into
      68             :      the pub array.  For sched_cnt, refer to below. */
      69             :   uint *        sched;
      70             :   ulong         sched_cnt;
      71             : };
      72             : typedef struct fd_epoch_leaders fd_epoch_leaders_t;
      73             : 
      74             : FD_PROTOTYPES_BEGIN
      75             : 
      76             : /* fd_epoch_leaders_{align,footprint} describe the required footprint
      77             :    and alignment of the leader schedule object.  pub_cnt is the number
      78             :    of unique public keys.  slot_cnt is the number of slots in the
      79             :    epoch. */
      80             : 
      81             : FD_FN_CONST ulong
      82             : fd_epoch_leaders_align( void );
      83             : 
      84             : FD_FN_CONST ulong
      85             : fd_epoch_leaders_footprint( ulong pub_cnt,
      86             :                             ulong slot_cnt );
      87             : 
      88             : /* fd_epoch_leaders_new formats a memory region for use as a leader
      89             :    schedule object.  shmem points to the first byte of a memory region
      90             :    with matching alignment and footprint requirements.  The leader
      91             :    schedule object will contain the leader schedule for epoch `epoch`
      92             :    which spans slots [slot0, slot0+slot_cnt).  `slot0` must be the first
      93             :    slot in the epoch, but slot_cnt can be less than the length of the
      94             :    epoch to derive only the first portion of the leader schedule.
      95             :    pub_cnt is the number of unique public keys in this schedule.
      96             :    `stakes` points to the first entry of pub_cnt entries of stake
      97             :    weights sorted by tuple (stake, pubkey) in descending order.
      98             : 
      99             :    If `stakes` does not include all staked nodes, e.g. in the case of an
     100             :    attack that swamps the network with fake validators, `stakes` should
     101             :    contain the first `pub_cnt` of them in the normal sort order, and the
     102             :    sum of the remaining stake must be provided in excluded_stake,
     103             :    measured in lamports.
     104             : 
     105             :    Does NOT retain a read interest in stakes upon return.
     106             :    The caller is not joined to the object on return. */
     107             : void *
     108             : fd_epoch_leaders_new( void                    * shmem,
     109             :                       ulong                     epoch,
     110             :                       ulong                     slot0,
     111             :                       ulong                     slot_cnt,
     112             :                       ulong                     pub_cnt,
     113             :                       fd_stake_weight_t const * stakes, /* indexed [0, pub_cnt) */
     114             :                       ulong                     excluded_stake );
     115             : 
     116             : /* fd_epoch_leaders_join joins the caller to the leader schedule object.
     117             :    fd_epoch_leaders_leave undoes an existing join. */
     118             : 
     119             : fd_epoch_leaders_t *
     120             : fd_epoch_leaders_join( void * shleaders );
     121             : 
     122             : void *
     123             : fd_epoch_leaders_leave( fd_epoch_leaders_t * leaders );
     124             : 
     125             : /* fd_epoch_leaders_delete unformats a memory region and returns owner-
     126             :    ship back to the caller. */
     127             : 
     128             : void *
     129             : fd_epoch_leaders_delete( void * shleaders );
     130             : 
     131             : /* FD_INDETERMINATE_LEADER has base58 encoding
     132             :    1111111111indeterminateLeader9QSxFYNqsXA.  In hex, this pubkey ends
     133             :    with 0x0badf00d0badf00d. */
     134        6318 : #define FD_INDETERMINATE_LEADER 0x00U,0x00U,0x00U,0x00U,0x00U,0x00U,0x00U,0x00U,0x00U,0x00U,0x99U,0xf6U,0x0fU,0x96U,0x2cU,0xddU,\
     135        6318 :                                 0x38U,0x21U,0xf3U,0x0cU,0x16U,0x1dU,0xe3U,0x0aU,0x0bU,0xadU,0xf0U,0x0dU,0x0bU,0xadU,0xf0U,0x0dU
     136             : 
     137             : /* fd_epoch_leaders_get returns a pointer to the selected public key
     138             :    given a slot.  Returns NULL if slot is not in [slot0, slot0+slot_cnt)
     139             :    given the values supplied in fd_epoch_leaders_new.
     140             : 
     141             :    If a non-zero value was provided for excluded_stake in
     142             :    fd_epoch_leaders_new and a validator included in the excluded_stake
     143             :    is the leader for the requested slot, instead of returning the
     144             :    correct value (which is not known), fd_epoch_leaders_get will return
     145             :    a pointer to a pubkey with value FD_INDETERMINATE_LEADER. */
     146             : 
     147             : FD_FN_PURE static inline fd_pubkey_t const *
     148             : fd_epoch_leaders_get( fd_epoch_leaders_t const * leaders,
     149     6783819 :                       ulong                      slot ) {
     150     6783819 :   ulong slot_delta = slot - leaders->slot0;
     151     6783819 :   if( FD_UNLIKELY( slot      < leaders->slot0    ) ) return NULL;
     152     6783690 :   if( FD_UNLIKELY( slot_delta>=leaders->slot_cnt ) ) return NULL;
     153     6783345 :   return (fd_pubkey_t const *)( leaders->pub + leaders->sched[ slot_delta/FD_EPOCH_SLOTS_PER_ROTATION ] );
     154     6783690 : }
     155             : 
     156             : FD_PROTOTYPES_END
     157             : 
     158             : #endif /* HEADER_fd_src_flamenco_leaders_fd_leaders_h */

Generated by: LCOV version 1.14