Line data    Source code

       1             : #ifndef HEADER_fd_src_discof_restore_utils_fd_ssmsg_h
       2             : #define HEADER_fd_src_discof_restore_utils_fd_ssmsg_h
       3             : 
       4             : #include "../../../flamenco/runtime/fd_runtime_const.h"
       5             : #include "../../../flamenco/runtime/fd_blockhashes.h"
       6             : #include "../../../flamenco/runtime/program/vote/fd_validator_location.h"
       7             : 
       8           0 : #define FD_SSMSG_MANIFEST_FULL        (0) /* A snapshot manifest message from the full snapshot */
       9           0 : #define FD_SSMSG_MANIFEST_INCREMENTAL (1) /* A snapshot manifest message from the incremental snapshot */
      10           0 : #define FD_SSMSG_DONE                 (2) /* Indicates the snapshot is fully loaded and tiles are shutting down */
      11           0 : #define FD_SSMSG_EXPECTED_SLOT        (3) /* Expected rooted slot from incremental snapshot */
      12             : 
      13             : FD_FN_CONST static inline ulong
      14           0 : fd_ssmsg_sig( ulong message ) {
      15           0 :   return (message & 0x3UL);
      16           0 : }
      17             : 
      18           0 : FD_FN_CONST static inline ulong fd_ssmsg_sig_message( ulong sig ) { return (sig & 0x3UL); }
      19             : struct epoch_credits {
      20             :   ulong epoch;
      21             :   ulong credits;
      22             :   ulong prev_credits;
      23             : };
      24             : 
      25             : typedef struct epoch_credits epoch_credits_t;
      26             : 
      27             : /* fd_epoch_credits_is_alpenglow_marker returns 1 if ec is the
      28             :    tower->Alpenglow migration sentinel, 0 otherwise. */
      29             : 
      30             : FD_FN_PURE static inline int
      31           0 : fd_epoch_credits_is_alpenglow_marker( epoch_credits_t const * ec ) {
      32           0 :   return ec->epoch==ULONG_MAX && ec->credits==ULONG_MAX && ec->prev_credits==ULONG_MAX;
      33           0 : }
      34             : 
      35             : /* The FD_SSMSG_EXPECTED_SLOT uses the tsorig and tspub fields
      36             :    of the fd_frag_meta_t struct to store the low and high 32 bits of
      37             :    the slot number. */
      38             : static inline void
      39             : fd_ssmsg_slot_to_frag( ulong slot,
      40             :                        uint* low,
      41           0 :                        uint* high ) {
      42           0 :    *low = (uint)(slot & 0xFFFFFFFFUL);
      43           0 :    *high = (uint)((slot >> 32UL) & 0xFFFFFFFFUL);
      44           0 : }
      45             : 
      46             : static inline void
      47             : fd_ssmsg_frag_to_slot( ulong low,
      48             :                        ulong high,
      49           0 :                        ulong* slot ) {
      50           0 :    *slot = (high << 32UL) | low;
      51           0 : }
      52             : 
      53             : struct fd_snapshot_manifest_vote_stakes {
      54             :   /* The vote pubkey */
      55             :   uchar vote[ 32UL ];
      56             : 
      57             :   /* The validator identity pubkey, aka node pubkey */
      58             :   uchar identity[ 32UL ];
      59             : 
      60             :   /* The commission account for inflation rewards (vote, before SIMD-0232) */
      61             :   uchar commission_inflation[ 32UL ];
      62             : 
      63             :   /* The commission account for block revenue (identity, before SIMD-0232) */
      64             :   uchar commission_block[ 32UL ];
      65             : 
      66             :   /* Whether this vote account has a BLS pubkey set */
      67             :   uchar has_identity_bls;
      68             : 
      69             :   /* The validator BLS pubkey (used after SIMD-0326: Alpenglow) */
      70             :   uchar identity_bls[ 48UL ];
      71             : 
      72             :   /* The validator's declared location (SIMD-0674) */
      73             :   fd_validator_location_t location;
      74             : 
      75             :   /* The total amount of active stake for the vote account */
      76             :   ulong stake;
      77             : 
      78             :   /* The latest slot and timestamp that the vote account voted on in
      79             :      the given epoch. */
      80             :   ulong slot;
      81             :   long  timestamp;
      82             : 
      83             :   /* The validator's commission rate as of the given epoch. */
      84             :   ushort commission;
      85             : 
      86             :   /* The validator's block revenue commission (basis points) */
      87             :   ushort commission_block_bps;
      88             : 
      89             :   /* The validator's pending delegator rewards as of the given epoch */
      90             :   ulong  pending_delegator_rewards;
      91             : 
      92             :   /* The epoch credits array tracks the history of how many credits the
      93             :      provided vote account earned in each recorded epoch.  Entries are
      94             :      ordered by strictly increasing epoch: epoch_credits[0] is the
      95             :      oldest and epoch_credits[epoch_credits_history_len-1] is the
      96             :      newest.  Epochs with no recorded credits can be absent.  When
      97             :      booting a new chain from genesis, or for new vote accounts, the
      98             :      epoch credits history may be short.  The maximum number of entries
      99             :      in the epoch credits history is 64.
     100             : 
     101             :      Note one entry may be the Alpenglow migration marker (all three
     102             :      fields ULONG_MAX, see fd_epoch_credits_is_alpenglow_marker). */
     103             :   ulong           epoch_credits_history_len;
     104             :   epoch_credits_t epoch_credits[ FD_EPOCH_CREDITS_MAX ];
     105             : };
     106             : 
     107             : typedef struct fd_snapshot_manifest_vote_stakes fd_snapshot_manifest_vote_stakes_t;
     108             : 
     109             : struct fd_snapshot_manifest_epoch_stakes {
     110             :    /* The epoch for which these vote accounts and stakes are valid for */
     111             :   ulong                              epoch;
     112             :   /* The total amount of active stake at the end of the given epoch.*/
     113             :   ulong                              total_stake;
     114             : 
     115             :   /* The vote accounts and their stakes for a given epoch.
     116             :      FIXME: Snapshot manifest has to support a much larger bound. */
     117             :   ulong                              vote_stakes_len;
     118             :   fd_snapshot_manifest_vote_stakes_t vote_stakes[ FD_RUNTIME_MAX_VAT_VOTE_ACCOUNTS ];
     119             : };
     120             : 
     121             : typedef struct fd_snapshot_manifest_epoch_stakes fd_snapshot_manifest_epoch_stakes_t;
     122             : 
     123             : struct fd_snapshot_manifest_inflation_params {
     124             :   /* The initial inflation percentage starting at genesis. */
     125             :   double initial;
     126             : 
     127             :   /* The terminal inflation percentage is the long-term steady state
     128             :      inflation rate after a period of disinflation.  This value is set
     129             :      at genesis to 1.5% and is not expected to change. */
     130             :   double terminal;
     131             : 
     132             :   /* The rate per year at which inflation is lowered until it reaches
     133             :      the terminal inflation rate.  This value is set to 15% at genesis
     134             :      and only changes at the boundary when double_disinflation_rate
     135             :      activates. */
     136             :   double taper;
     137             : 
     138             :   /* The percentage of total inflation allocated to the foundation.
     139             :      This value is set at genesis to 5% and is not expected to change. */
     140             :   double foundation;
     141             : 
     142             :   /* The number of years in which a portion of the total inflation is
     143             :      allocated to the foundation (see foundation field).  This value is
     144             :      set to 7 years at genesis and is not expected to change. */
     145             :   double foundation_term;
     146             : };
     147             : 
     148             : typedef struct fd_snapshot_manifest_inflation_params fd_snapshot_manifest_inflation_params_t;
     149             : 
     150             : struct fd_snapshot_manifest_epoch_schedule_params {
     151             :   /* The maximum number of slots in each epoch. */
     152             :   ulong slots_per_epoch;
     153             : 
     154             :   /* A number of slots before beginning of an epoch to calculate a
     155             :      leader schedule for that epoch.  This value is set to
     156             :      slots_per_epoch (basically one epoch) and is unlikely to change. */
     157             :   ulong leader_schedule_slot_offset;
     158             : 
     159             :   /* Whether there is a warmup period where epochs are short and grow by
     160             :      powers of two until they reach the default epoch length of
     161             :      slots_per_epoch.  This value is set by default to true at genesis,
     162             :      though it may be configured differently in development
     163             :      environments. */
     164             :   uchar warmup;
     165             : 
     166             :   /* TODO: Probably remove this? Redundant and can be calculated from
     167             :      the above. */
     168             :   ulong first_normal_epoch;
     169             :   ulong first_normal_slot;
     170             : };
     171             : 
     172             : typedef struct fd_snapshot_manifest_epoch_schedule_params fd_snapshot_manifest_epoch_schedule_params_t;
     173             : 
     174             : struct fd_snapshot_manifest_fee_rate_governor {
     175             :   /* Transaction fees are calculated by charging a cost for each
     176             :      signature.  There is a mechanism to dynamically adjust the cost per
     177             :      signature based on the cluster's transaction processing capacity.
     178             :      In this mechanism, the cost per signature can vary between 50% to
     179             :      1000% of the target_lamports_per_signature value, which is the cost
     180             :      per signature when the cluster is operating at the desired
     181             :      transaction processing capacity defined by
     182             :      target_signatures_per_slot.
     183             : 
     184             :      This value is fixed at 10,000 from genesis onwards but may be
     185             :      changed in the future with feature flags. */
     186             :   ulong target_lamports_per_signature;
     187             : 
     188             :   /* The cluster transaction processing capacity is measured by
     189             :      signatures per slot.  Solana defines the desired transaction
     190             :      processing capacity using the value target_signatures_per_slot.
     191             : 
     192             :      This value is fixed at 20,000 from genesis onwards but may be
     193             :      changed in the future with feature flags. */
     194             :   ulong target_signatures_per_slot;
     195             : 
     196             :   /* The minimum cost per signature is 50% of the
     197             :      target_lamports_per_signature value.  Under the current default for
     198             :      target_lamports_per_signature, this value is at 5,000 lamports per
     199             :      signature. */
     200             :   ulong min_lamports_per_signature;
     201             : 
     202             :   /* The maximum cost per signature is 1000% of the
     203             :      target_lamports_per_signature value.  Under the current default for
     204             :      target_lamports_per_signature, this value is at 100,000 lamports
     205             :      per signature.*/
     206             :   ulong max_lamports_per_signature;
     207             : 
     208             :   /* The percent of collected fees that are burned.  This value is
     209             :      currently set to a fixed value of 50% from genesis onwards, but
     210             :      may be changed in the future with feature flags. */
     211             :   uchar burn_percent;
     212             : };
     213             : 
     214             : typedef struct fd_snapshot_manifest_fee_rate_governor fd_snapshot_manifest_fee_rate_governor_t;
     215             : 
     216             : struct fd_snapshot_manifest_rent {
     217             :   ulong lamports_per_uint8_year;
     218             :   double exemption_threshold;
     219             :   uchar burn_percent;
     220             : };
     221             : 
     222             : typedef struct fd_snapshot_manifest_rent fd_snapshot_manifest_rent_t;
     223             : 
     224             : struct fd_snapshot_manifest_blockhash {
     225             :    uchar hash[ 32UL ];
     226             :    ulong lamports_per_signature;
     227             :    ulong hash_index;
     228             :    ulong timestamp;
     229             : };
     230             : 
     231             : typedef struct fd_snapshot_manifest_blockhash fd_snapshot_manifest_blockhash_t;
     232             : 
     233             : struct fd_snapshot_manifest {
     234             :   /* The UNIX timestamp when the genesis block was for this chain
     235             :      was created, in seconds.
     236             :      https://github.com/anza-xyz/agave/blob/v4.0.0-beta.1/runtime/src/bank.rs#L2108-L2114 */
     237             :   ulong creation_time_seconds;
     238             : 
     239             :   /* At genesis, certain parameters can be set which control the
     240             :      inflation rewards going forward.  This includes what the initial
     241             :      inflation is and how the inflation curve changes over time.
     242             : 
     243             :      These parameters may change with feature gate activations, for
     244             :      example double_disinflation_rate. */
     245             :   fd_snapshot_manifest_inflation_params_t inflation_params;
     246             : 
     247             :   /* At genesis, certain parameters can be set which control the
     248             :      epoch schedule going forward.  This includes how many slots
     249             :      there are per epoch, and certain development settings like if
     250             :      epochs start short and grow longer as the chain progresses.
     251             : 
     252             :      Currently, these parameters can never change and are fixed from
     253             :      genesis onwards, although in future they may change with new
     254             :      feature flags. */
     255             :   fd_snapshot_manifest_epoch_schedule_params_t epoch_schedule_params;
     256             : 
     257             :   /* At genesis, certain parameters can be set which control
     258             :      how transaction fees are dynamically adjusted going forward.
     259             : 
     260             :      Currently, these parameters can never change and are fixed from
     261             :      genesis onwards, although in future they may change with new
     262             :      feature flags. */
     263             :   fd_snapshot_manifest_fee_rate_governor_t fee_rate_governor;
     264             : 
     265             :   fd_snapshot_manifest_rent_t rent_params;
     266             : 
     267             :   /* The slot number for this snapshot (this slot was fully replayed and
     268             :      then the snapshot was taken) */
     269             :   ulong slot;
     270             : 
     271             :   /* The number of blocks that have been built since genesis.  This is
     272             :      kind of like the slot number, in that it increments by 1 for every
     273             :      landed block, but it does not increment for skipped slots, so the
     274             :      block_height will always be less than or equal to the slot. */
     275             :   ulong block_height;
     276             : 
     277             :   /* Leader node identity of the snapshot slot */
     278             :   uchar leader_id[ 32UL ];
     279             : 
     280             :   /* TODO: Document */
     281             :   ulong collector_fees;
     282             : 
     283             :   /* The parent slot is the slot that this block builds on top of.  It
     284             :      is typically slot-1, but can be an arbitrary amount of slots
     285             :      earlier in case of forks, when the block skips over preceding
     286             :      slots. */
     287             :   ulong parent_slot;
     288             : 
     289             :   /* The bank hash of the slot represented by this snapshot.  The bank
     290             :      hash is used by the validator to detect mismatches.  All validators
     291             :      must agree on a bank hash for each slot or they will fork off. */
     292             :   uchar bank_hash[ 32UL ];
     293             : 
     294             :   /* The bank hash of the parent slot. */
     295             :   uchar parent_bank_hash[ 32UL ];
     296             : 
     297             :   /* The merkle-based hash of all account state on chain at the slot the
     298             :      snapshot is created.  The accounts hash is calculated when producing
     299             :      a snapshot. */
     300             :   uchar accounts_hash[ 32UL ];
     301             : 
     302             :   /* The legacy Merkle-based hash of modified accounts in the snapshot
     303             :      slot. */
     304             :   uchar accounts_delta_hash[ 32UL ];
     305             : 
     306             :   /* The lattice hash of all account state on chain. */
     307             :   int   has_accounts_lthash;
     308             :   uchar accounts_lthash[ 2048UL ];
     309             : 
     310             :   /* The hash of all accounts at this snapshot's epoch.
     311             :      The epoch account hash is very expensive to calculate, so it is
     312             :      only calculated once per epoch during the epoch account hash
     313             :      calculation window, which is a range of slots in an epoch starting
     314             :      at slot 108000 and ending at slot 324000, where each epoch has
     315             :      432000 slots.
     316             : 
     317             :      The epoch_account_hash may be empty if the snapshot was produced
     318             :      before the epoch account hash calculation window. */
     319             :   int   has_epoch_account_hash;
     320             :   uchar epoch_account_hash[ 32UL ];
     321             : 
     322             :   /* The merkle root of the snapshot slot's block.
     323             :      Only present in snapshots generated by Agave >=4.1. */
     324             :   int   has_block_id;
     325             :   uchar block_id[ 32UL ];
     326             : 
     327             :   ulong blockhashes_len;
     328             :   fd_snapshot_manifest_blockhash_t blockhashes[ FD_BLOCKHASHES_MAX ];
     329             : 
     330             :   ushort accdb_fork_id; /* The fork_id in the account database for the root slot. */
     331             :   ushort txncache_fork_id; /* The fork_id in the status cache for the root slot. */
     332             : 
     333             :   /* A list of ancestor slots has been deprecated.  Agave's bank now
     334             :      creates an ancestor set with a single entry (the current slot):
     335             :      https://github.com/anza-xyz/agave/blob/v4.0.0-beta.1/runtime/src/bank.rs#L1846 */
     336             : 
     337             :   /* A hard fork is a deliberate deviation from the canonical blockchain
     338             :      progression.  This contains the list of slots which have
     339             :      historically undergone a hard fork.  The typical case for these is
     340             :      a feature is deactivated and the cluster is restarted. */
     341             :   ulong          hard_fork_cnt;
     342             :   fd_hard_fork_t hard_forks[ FD_HARD_FORKS_MAX ];
     343             : 
     344             :   /* The proof of history component "proves" the passage of time (see
     345             :      extended discussion in PoH tile for what that actually means) by
     346             :      continually doing sha256 hashes.  A certain number of hashes are
     347             :      required to be in each slot, to prove the leader spent some amount
     348             :      of time on the slot and didn't end it too early.
     349             : 
     350             :      In all clusters and environments that matter, this value is fixed
     351             :      at 64 and is unlikely to change, however it might be configured
     352             :      differently in development environments. */
     353             :   ulong ticks_per_slot;
     354             : 
     355             :   /* TODO: Document */
     356             :   ulong ns_per_slot;
     357             : 
     358             :   /* TODO: Document */
     359             :   double slots_per_year;
     360             : 
     361             :   /* The proof of history component typically requires every block to
     362             :      have 64 "ticks" in it (although this is configurable during
     363             :      development), but each tick is some flexible number of recursive
     364             :      sha256 hashes defined at genesis.
     365             : 
     366             :      The number of hashes for mainnet genesis is 12,500, meaning there
     367             :      will be 800,000 hashes per slot.
     368             : 
     369             :      There are various features, named like update_hashes_per_tick*
     370             :      which if enabled update the hashes_per_tick of the chain as-of the
     371             :      epoch where they are enabled.  This value incorporates any changes
     372             :      due to such features.
     373             : 
     374             :      In development environments, sometimes hashes_per_tick will not be
     375             :      specified (has_hashes_per_tick will be 0).  Agave refers to this as
     376             :      a "low power" mode, where ticks have just one hash in them.  It is
     377             :      distinct from just setting hahes_per_tick to 1, because it also
     378             :      reduces the slot duration from 400ms down to 0ms (or however long
     379             :      it takes to produce the hash).  See comments in the PoH tile for
     380             :      more extended discussion. */
     381             :   int   has_hashes_per_tick;
     382             :   ulong hashes_per_tick;
     383             : 
     384             :   /* The sum of all account balances in lamports as of this snapshots
     385             :      slot.  Total capitalization is used when computing inflation
     386             :      rewards and validating snapshots. */
     387             :   ulong capitalization;
     388             : 
     389             :   /* TODO: Why is this needed? */
     390             :   ulong tick_height;
     391             :   ulong max_tick_height;
     392             : 
     393             :   /* TODO: What is this? */
     394             :   ulong lamports_per_signature;
     395             : 
     396             :   /* TODO: Why is this needed? */
     397             :   ulong transaction_count;
     398             : 
     399             :   /* TODO: Why is this needed? */
     400             :   ulong signature_count;
     401             : 
     402             :   /* Epoch stakes represent the exact amount staked to each vote
     403             :      account at the beginning of a previous epoch.  They are primarily
     404             :      used to derive the leader schedule.
     405             : 
     406             :      Let's say the manifest is at epoch E.
     407             : 
     408             :      The field versioned_epoch_stakes in the manifest is a map
     409             : 
     410             :        <epoch> -> <VersionedEpochStakes>
     411             : 
     412             :      where <epoch> assumes these values:
     413             : 
     414             :        E-3 - represents the stakes at the beginning of epoch E-4.
     415             :        E-2 - represents the stakes at the beginning of epoch E-3.
     416             :              Agave retains MAX_LEADER_SCHEDULE_STAKES (5) entries and
     417             :              a block footer may carry a finalization cert from any
     418             :              epoch it retains, so these are loaded as well.
     419             : 
     420             :        E-1 - represents the stakes at the beginning of epoch E-2,
     421             :              used to compute the leader schedule at E-1.  Also used
     422             :              by delay_commission_updates (SIMD-0249) to determine
     423             :              the commission rate for partitioned epoch rewards
     424             :              recalculation at boot.
     425             : 
     426             :        E   - represents the stakes at the beginning of epoch E-1,
     427             :              used to compute the leader schedule at E.
     428             : 
     429             :        E+1 - represents the stakes at the beginning of epoch E,
     430             :              used to compute the leader schedule at E+1.
     431             : 
     432             :      The epoch stakes are stored in an array indexed from
     433             :      epoch_stakes_base = max( E-3, 0 ):
     434             :        epoch_stakes[0] = epoch E-3
     435             :        epoch_stakes[1] = epoch E-2
     436             :        epoch_stakes[2] = epoch E-1
     437             :        epoch_stakes[3] = epoch E
     438             :        epoch_stakes[4] = epoch E+1
     439             :      Entries the snapshot does not carry keep epoch ULONG_MAX. */
     440             :   fd_snapshot_manifest_epoch_stakes_t epoch_stakes[ FD_RUNTIME_MANIFEST_EPOCH_STAKES_LEN ];
     441             : };
     442             : 
     443             : typedef struct fd_snapshot_manifest fd_snapshot_manifest_t;
     444             : 
     445             : #endif /* HEADER_fd_src_discof_restore_utils_fd_ssmsg_h */