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-01 05:00:49 Functions: 6 133 4.5 %

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

Generated by: LCOV version 1.14