LCOV - code coverage report
Current view: top level - flamenco/runtime/sysvar - fd_sysvar_clock.c (source / functions) Hit Total Coverage
Test: cov.lcov Lines: 0 154 0.0 %
Date: 2025-10-18 04:46:48 Functions: 0 6 0.0 %

          Line data    Source code
       1             : #include "fd_sysvar.h"
       2             : #include "fd_sysvar_clock.h"
       3             : #include "fd_sysvar_epoch_schedule.h"
       4             : #include "../fd_acc_mgr.h"
       5             : #include "../fd_system_ids.h"
       6             : 
       7             : /* Syvar Clock Possible Values:
       8             :   slot:
       9             :   [0, ULONG_MAX]
      10             : 
      11             :   epoch:
      12             :   [0, slot/432000UL]
      13             : 
      14             :   epoch_start_timestamp:
      15             :   [0, ULONG_MAX]
      16             : 
      17             :   unix_timestamp:
      18             :   This value is bounded by the slot distance from the
      19             :   epoch_start_timestamp.
      20             :   The protocol allows for a maximum drift (either fast or slow) from the
      21             :   start of the epoch's timestamp.  The expected time is called the PoH
      22             :   offset.  This offset is calculated by (epoch_start_timestamp + slots
      23             :   since epoch * slot_duration). The drift is then bounded by the
      24             :   max_allowable_drift_{slow,fast}.  The stake weighted offset can be
      25             :   150% more than the PoH offset and 25% less than the PoH offset.
      26             :   So, the bounds for the unix_timestamp can be calculated by:
      27             :   upper bound = epoch_start_timestamp + (slots since epoch * slot_duration) * 2.5
      28             :   lower bound = epoch_start_timestamp + (slots since epoch * slot_duration) * 0.75
      29             : 
      30             :   leader_schedule_epoch:
      31             :   This is the value of the epoch used for the leader schedule.  It is
      32             :   computed based on the values of the epoch schedule (first_normal_slot,
      33             :   leader_schedule_slot_offset, slots_per_epoch).  It is always equal to
      34             :   ((slot - first_normal_slot) + leader_schedule_slot_offset) / schedule->slots_per_epoch
      35             : */
      36             : 
      37             : /* https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/stake_weighted_timestamp.rs#L14 */
      38           0 : #define MAX_ALLOWABLE_DRIFT_FAST_PERCENT ( 25U )
      39             : 
      40             : /* https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/stake_weighted_timestamp.rs#L15 */
      41           0 : #define MAX_ALLOWABLE_DRIFT_SLOW_PERCENT ( 150U )
      42             : 
      43             : /* Do all intermediate calculations at nanosecond precision, to mirror
      44             :    Solana's behavior. */
      45           0 : #define NS_IN_S ((long)1e9)
      46             : 
      47             : /* https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/stake_weighted_timestamps.rs#L2110-L2117 */
      48             : static inline long
      49           0 : unix_timestamp_from_genesis( fd_bank_t * bank ) {
      50             :   /* TODO: genesis_creation_time needs to be a long in the bank. */
      51           0 :   return fd_long_sat_add(
      52           0 :       (long)fd_bank_genesis_creation_time_get( bank ),
      53           0 :       (long)( fd_uint128_sat_mul( fd_bank_slot_get( bank ), fd_bank_ns_per_slot_get( bank ) ) / NS_IN_S ) );
      54           0 : }
      55             : 
      56             : void
      57             : fd_sysvar_clock_write( fd_bank_t *               bank,
      58             :                        fd_funk_t *               funk,
      59             :                        fd_funk_txn_xid_t const * xid,
      60             :                        fd_capture_ctx_t *        capture_ctx,
      61           0 :                        fd_sol_sysvar_clock_t *   clock ) {
      62           0 :   uchar enc[ sizeof(fd_sol_sysvar_clock_t) ];
      63           0 :   fd_bincode_encode_ctx_t ctx = {
      64           0 :     .data    = enc,
      65           0 :     .dataend = enc + sizeof(fd_sol_sysvar_clock_t),
      66           0 :   };
      67           0 :   if( FD_UNLIKELY( fd_sol_sysvar_clock_encode( clock, &ctx ) ) ) {
      68           0 :     FD_LOG_ERR(( "fd_sol_sysvar_clock_encode failed" ));
      69           0 :   }
      70             : 
      71           0 :   fd_sysvar_account_update( bank, funk, xid, capture_ctx, &fd_sysvar_clock_id, enc, sizeof(fd_sol_sysvar_clock_t) );
      72           0 : }
      73             : 
      74             : 
      75             : fd_sol_sysvar_clock_t *
      76             : fd_sysvar_clock_read( fd_funk_t *               funk,
      77             :                       fd_funk_txn_xid_t const * xid,
      78           0 :                       fd_sol_sysvar_clock_t *   clock ) {
      79           0 :   fd_txn_account_t acc[1];
      80           0 :   int rc = fd_txn_account_init_from_funk_readonly( acc, &fd_sysvar_clock_id, funk, xid );
      81           0 :   if( FD_UNLIKELY( rc!=FD_ACC_MGR_SUCCESS ) ) {
      82           0 :     return NULL;
      83           0 :   }
      84             : 
      85             :   /* This check is needed as a quirk of the fuzzer. If a sysvar account
      86             :      exists in the accounts database, but doesn't have any lamports,
      87             :      this means that the account does not exist. This wouldn't happen
      88             :      in a real execution environment. */
      89           0 :   if( FD_UNLIKELY( fd_txn_account_get_lamports( acc )==0UL ) ) {
      90           0 :     return NULL;
      91           0 :   }
      92             : 
      93           0 :   return fd_bincode_decode_static(
      94           0 :       sol_sysvar_clock, clock,
      95           0 :       fd_txn_account_get_data( acc ),
      96           0 :       fd_txn_account_get_data_len( acc ),
      97           0 :       &err );
      98           0 : }
      99             : 
     100             : void
     101             : fd_sysvar_clock_init( fd_bank_t *               bank,
     102             :                       fd_funk_t *               funk,
     103             :                       fd_funk_txn_xid_t const * xid,
     104           0 :                       fd_capture_ctx_t *        capture_ctx ) {
     105           0 :   long timestamp = unix_timestamp_from_genesis( bank );
     106             : 
     107           0 :   fd_sol_sysvar_clock_t clock = {
     108           0 :     .slot                  = fd_bank_slot_get( bank ),
     109           0 :     .epoch                 = 0,
     110           0 :     .epoch_start_timestamp = timestamp,
     111           0 :     .leader_schedule_epoch = 1,
     112           0 :     .unix_timestamp        = timestamp,
     113           0 :   };
     114           0 :   fd_sysvar_clock_write( bank, funk, xid, capture_ctx, &clock );
     115           0 : }
     116             : 
     117             : struct ts_est_ele {
     118             :   long    timestamp;
     119             :   uint128 stake; /* should really be fine as ulong, but we match Agave*/
     120             : };
     121             : 
     122             : typedef struct ts_est_ele ts_est_ele_t;
     123             : 
     124             : #define SORT_NAME  sort_stake_ts
     125           0 : #define SORT_KEY_T ts_est_ele_t
     126           0 : #define SORT_BEFORE(a,b) ( (a).timestamp < (b).timestamp )
     127             : #include "../../../util/tmpl/fd_sort.c"
     128             : 
     129             : /* get_timestamp_estimate calculates a timestamp estimate.  Does not
     130             :    modify the slot context.  Walks all cached vote accounts (from the
     131             :    "bank") and calculates a unix timestamp estimate. Returns the
     132             :    timestamp estimate.  spad is used for scratch allocations (allocates
     133             :    a treap of size FD_SYSVAR_CLOCK_STAKE_WEIGHTS_MAX). Crashes the
     134             :    process with FD_LOG_ERR on failure (e.g. too many vote accounts).
     135             : 
     136             :   https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/bank.rs#L2563-L2601 */
     137             : long
     138             : get_timestamp_estimate( fd_bank_t *             bank,
     139           0 :                         fd_sol_sysvar_clock_t * clock ) {
     140           0 :   fd_epoch_schedule_t const * epoch_schedule = fd_bank_epoch_schedule_query( bank );
     141           0 :   ulong                       slot_duration  = (ulong)fd_bank_ns_per_slot_get( bank );
     142           0 :   ulong                       current_slot   = fd_bank_slot_get( bank );
     143             : 
     144           0 :   static FD_TL ts_est_ele_t ts_eles[ FD_RUNTIME_MAX_VOTE_ACCOUNTS ];
     145           0 :   ulong ts_ele_cnt = 0UL;
     146             : 
     147             :   /* https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/stake_weighted_timestamp.rs#L41 */
     148           0 :   uint128 total_stake = 0UL;
     149             : 
     150             :   /* A timestamp estimate is calculated at every slot using the most
     151             :      recent vote states of voting validators. This estimated is based on
     152             :      a stake weighted median using the stake as of the end of epoch E-2
     153             :      if we are currently in epoch E. We do not count vote accounts that
     154             :      have not voted in an epoch's worth of slots (432k). */
     155           0 :   fd_vote_states_t const * vote_states           = fd_bank_vote_states_locking_query( bank );
     156           0 :   fd_vote_states_t const * vote_states_prev_prev = fd_bank_vote_states_prev_prev_locking_query( bank );
     157             : 
     158           0 :   FD_TEST( fd_vote_states_cnt( vote_states )<=FD_RUNTIME_MAX_VOTE_ACCOUNTS );
     159             : 
     160           0 :   fd_vote_states_iter_t iter_[1];
     161           0 :   for( fd_vote_states_iter_t * iter = fd_vote_states_iter_init( iter_, vote_states );
     162           0 :        !fd_vote_states_iter_done( iter );
     163           0 :        fd_vote_states_iter_next( iter ) ) {
     164           0 :     fd_vote_state_ele_t const * vote_state = fd_vote_states_iter_ele( iter );
     165             : 
     166             :     /* https://github.com/anza-xyz/agave/blob/v3.0.0/runtime/src/bank.rs#L2445 */
     167           0 :     ulong slot_delta;
     168           0 :     int err = fd_ulong_checked_sub( current_slot, vote_state->last_vote_slot, &slot_delta );
     169           0 :     if( FD_UNLIKELY( err ) ) {
     170             :       /* Don't count vote accounts with a last vote slot that is greater
     171             :          than the current slot. */
     172           0 :       continue;
     173           0 :     }
     174             : 
     175             :     /* TODO: This should be pre-cached so we don't do map lookup here */
     176           0 :     fd_vote_state_ele_t const * vote_state_prev = fd_vote_states_query_const( vote_states_prev_prev, &vote_state->vote_account );
     177           0 :     if( FD_UNLIKELY( !vote_state_prev ) ) {
     178             :       /* Don't count vote accounts that didn't have stake at the end of
     179             :          epoch E-2. */
     180           0 :       continue;
     181           0 :     }
     182             : 
     183             :     /* Don't count vote accounts that haven't voted in the past 432k
     184             :        slots (length of an epoch).
     185             :        https://github.com/anza-xyz/agave/blob/v3.0.0/runtime/src/bank.rs#L2446-L2447 */
     186           0 :     if( FD_UNLIKELY( slot_delta>epoch_schedule->slots_per_epoch ) ) {
     187           0 :       continue;
     188           0 :     }
     189             : 
     190             :     /* Calculate the timestamp estimate by taking the last vote
     191             :        timestamp and adding the estimated time since the last vote
     192             :        (delta from last vote slot to current slot * slot duration).
     193             :        https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/stake_weighted_timestamp.rs#L44-L45 */
     194           0 :     ulong offset   = fd_ulong_sat_mul( slot_duration, slot_delta );
     195           0 :     long  estimate = vote_state->last_vote_timestamp + (long)(offset / NS_IN_S);
     196             : 
     197             :     /* For each timestamp, accumulate the stake from E-2.  If the entry
     198             :        for the timestamp doesn't exist yet, insert it.  Otherwise,
     199             :        update the existing entry.
     200             :        https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/stake_weighted_timestamp.rs#L46-L53 */
     201           0 :     ts_eles[ ts_ele_cnt ] = (ts_est_ele_t){
     202           0 :       .timestamp = estimate,
     203           0 :       .stake     = vote_state_prev->stake,
     204           0 :     };
     205           0 :     ts_ele_cnt++;
     206             : 
     207             :     /* https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/stake_weighted_timestamp.rs#L54 */
     208           0 :     total_stake += vote_state_prev->stake;
     209           0 :   }
     210           0 :   fd_bank_vote_states_end_locking_query( bank );
     211           0 :   fd_bank_vote_states_prev_prev_end_locking_query( bank );
     212             : 
     213             :   /* https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/stake_weighted_timestamp.rs#L56-L58 */
     214           0 :   if( FD_UNLIKELY( total_stake==0UL ) ) {
     215           0 :     return 0L;
     216           0 :   }
     217             : 
     218           0 :   sort_stake_ts_inplace( ts_eles, ts_ele_cnt );
     219             : 
     220             :   /* Populate estimate with the stake-weighted median timestamp.
     221             :      https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/stake_weighted_timestamp.rs#L59-L68 */
     222           0 :   uint128 stake_accumulator = 0;
     223           0 :   long    estimate          = 0L;
     224           0 :   for( ulong i=0UL; i<ts_ele_cnt; i++ ) {
     225           0 :     stake_accumulator = fd_uint128_sat_add( stake_accumulator, ts_eles[i].stake );
     226           0 :     if( stake_accumulator>(total_stake/2UL) ) {
     227           0 :       estimate = ts_eles[ i ].timestamp;
     228           0 :       break;
     229           0 :     }
     230           0 :   }
     231             : 
     232           0 :   int const fix_estimate_into_u64 = FD_FEATURE_ACTIVE_BANK( bank, warp_timestamp_again );
     233             : 
     234             :   /* Bound estimate by `max_allowable_drift` since the start of the epoch
     235             :      https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/stake_weighted_timestamp.rs#L69-L99 */
     236           0 :   ulong epoch_start_slot      = fd_epoch_slot0( epoch_schedule, clock->epoch );
     237           0 :   long  epoch_start_timestamp = clock->epoch_start_timestamp;
     238             : 
     239             :   /* https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/stake_weighted_timestamp.rs#L71-L72 */
     240           0 :   ulong poh_estimate_offset = fd_ulong_sat_mul( slot_duration, fd_ulong_sat_sub( current_slot, epoch_start_slot ) );
     241             : 
     242             :   /* https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/stake_weighted_timestamp.rs#L73-L77 */
     243           0 :   ulong estimate_offset;
     244           0 :   if( fix_estimate_into_u64 ) {
     245           0 :     estimate_offset = fd_ulong_sat_mul( NS_IN_S, fd_ulong_sat_sub( (ulong)estimate, (ulong)epoch_start_timestamp ) );
     246           0 :   } else {
     247           0 :     estimate_offset = fd_ulong_sat_mul( NS_IN_S, (ulong)fd_long_sat_sub( estimate, epoch_start_timestamp ) );
     248           0 :   }
     249             : 
     250             :   /* https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/stake_weighted_timestamp.rs#L78-L81 */
     251           0 :   ulong max_allowable_drift_fast = fd_ulong_sat_mul( poh_estimate_offset, MAX_ALLOWABLE_DRIFT_FAST_PERCENT ) / 100UL;
     252           0 :   ulong max_allowable_drift_slow = fd_ulong_sat_mul( poh_estimate_offset, MAX_ALLOWABLE_DRIFT_SLOW_PERCENT ) / 100UL;
     253             : 
     254             :   /* https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/stake_weighted_timestamp.rs#L82-L98 */
     255           0 :   if( estimate_offset>poh_estimate_offset && fd_ulong_sat_sub( estimate_offset, poh_estimate_offset )>max_allowable_drift_slow ) {
     256           0 :     estimate = fd_long_sat_add(
     257           0 :         epoch_start_timestamp,
     258           0 :         fd_long_sat_add( (long)poh_estimate_offset / NS_IN_S, (long)max_allowable_drift_slow / NS_IN_S ) );
     259           0 :   } else if( estimate_offset<poh_estimate_offset && fd_ulong_sat_sub( poh_estimate_offset, estimate_offset )>max_allowable_drift_fast ) {
     260           0 :     estimate = fd_long_sat_sub(
     261           0 :         fd_long_sat_add( epoch_start_timestamp, (long)poh_estimate_offset / NS_IN_S ),
     262           0 :         (long)max_allowable_drift_fast / NS_IN_S );
     263           0 :   }
     264             : 
     265           0 :   return estimate;
     266           0 : }
     267             : 
     268             : /* TODO: This function should be called from genesis bootup as well with
     269             :    parent_epoch = NULL
     270             :    https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/bank.rs#L2158-L2215 */
     271             : void
     272             : fd_sysvar_clock_update( fd_bank_t *               bank,
     273             :                         fd_funk_t *               funk,
     274             :                         fd_funk_txn_xid_t const * xid,
     275             :                         fd_capture_ctx_t *        capture_ctx,
     276           0 :                         ulong const *             parent_epoch ) {
     277           0 :   fd_sol_sysvar_clock_t clock_[1];
     278           0 :   fd_sol_sysvar_clock_t * clock = fd_sysvar_clock_read( funk, xid, clock_ );
     279           0 :   if( FD_UNLIKELY( !clock ) ) FD_LOG_ERR(( "fd_sysvar_clock_read failed" ));
     280             : 
     281           0 :   fd_epoch_schedule_t const * epoch_schedule = fd_bank_epoch_schedule_query( bank );
     282           0 :   ulong                       current_slot   = fd_bank_slot_get( bank );
     283           0 :   ulong                       current_epoch  = fd_slot_to_epoch( epoch_schedule, current_slot, NULL );
     284             : 
     285             :   /* https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/bank.rs#L2159 */
     286           0 :   long unix_timestamp = clock->unix_timestamp;
     287             : 
     288             :   /* https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/bank.rs#L2175 */
     289           0 :   long ancestor_timestamp = clock->unix_timestamp;
     290             : 
     291             :   /* TODO: Are we handling slot 0 correctly?
     292             :      https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/bank.rs#L2176-L2183 */
     293           0 :   long timestamp_estimate = get_timestamp_estimate( bank, clock );
     294             : 
     295             :   /* If the timestamp was successfully calculated, use it. It not keep the old one. */
     296           0 :   if( FD_LIKELY( timestamp_estimate!=0L ) ) {
     297           0 :     unix_timestamp = timestamp_estimate;
     298             : 
     299             :     /* https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/bank.rs#L2180-L2182 */
     300           0 :     if( timestamp_estimate<ancestor_timestamp ) {
     301           0 :       unix_timestamp = ancestor_timestamp;
     302           0 :     }
     303           0 :   }
     304             : 
     305             :   /* https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/bank.rs#L2191-L2197 */
     306           0 :   long epoch_start_timestamp = (parent_epoch!=NULL && *parent_epoch!=current_epoch) ?
     307           0 :       unix_timestamp :
     308           0 :       clock->epoch_start_timestamp;
     309             : 
     310             :   /* https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/bank.rs#L2198-L2201 */
     311           0 :   if( FD_UNLIKELY( current_slot==0UL ) ) {
     312           0 :     long timestamp_from_genesis = unix_timestamp_from_genesis( bank );
     313           0 :     unix_timestamp              = timestamp_from_genesis;
     314           0 :     epoch_start_timestamp       = timestamp_from_genesis;
     315           0 :   }
     316             : 
     317             :   /* https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/bank.rs#L2202-L2208 */
     318           0 :   *clock = (fd_sol_sysvar_clock_t){
     319           0 :     .slot                  = current_slot,
     320           0 :     .epoch_start_timestamp = epoch_start_timestamp,
     321           0 :     .epoch                 = current_epoch,
     322           0 :     .leader_schedule_epoch = fd_slot_to_leader_schedule_epoch( epoch_schedule, current_slot ),
     323           0 :     .unix_timestamp        = unix_timestamp,
     324           0 :   };
     325             : 
     326             :   /* https://github.com/anza-xyz/agave/blob/v2.3.7/runtime/src/bank.rs#L2209-L2214 */
     327           0 :   fd_sysvar_clock_write( bank, funk, xid, capture_ctx, clock );
     328           0 : }

Generated by: LCOV version 1.14