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/types/fd_types.h"
5 : #include "../../../flamenco/runtime/fd_runtime_const.h"
6 : #include "../../../flamenco/stakes/fd_vote_states.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 : /* The FD_SSMSG_EXPECTED_SLOT uses the tsorig and tspub fields
28 : of the fd_frag_meta_t struct to store the low and high 32 bits of
29 : the slot number. */
30 : static inline void
31 : fd_ssmsg_slot_to_frag( ulong slot,
32 : uint* low,
33 0 : uint* high ) {
34 0 : *low = (uint)(slot & 0xFFFFFFFFUL);
35 0 : *high = (uint)((slot >> 32UL) & 0xFFFFFFFFUL);
36 0 : }
37 :
38 : static inline void
39 : fd_ssmsg_frag_to_slot( ulong low,
40 : ulong high,
41 0 : ulong* slot ) {
42 0 : *slot = (high << 32UL) | low;
43 0 : }
44 :
45 : struct fd_snapshot_manifest_vote_account {
46 : /* The pubkey of the vote account */
47 : uchar vote_account_pubkey[ 32UL ];
48 :
49 : /* The pubkey of the node account */
50 : uchar node_account_pubkey[ 32UL ];
51 :
52 : ulong stake;
53 : ulong last_slot;
54 : long last_timestamp;
55 :
56 : /* The percent of inflation rewards earned by the validator and
57 : deposited into the validator's vote account, from 0 to 100%.
58 : The remaning percentage of inflation rewards is distributed to
59 : all delegated stake accounts by stake weight. */
60 : uchar commission;
61 :
62 : /* The epoch credits array tracks the history of how many credits the
63 : provided vote account earned in each of the past epochs. The
64 : entry at epoch_credits[0] is for the current epoch,
65 : epoch_credits[1] is for the previous epoch, and so on. In cases of
66 : booting a new chain from genesis, or for new vote accounts the
67 : epoch credits history may be short. The maximum number of entries
68 : in the epoch credits history is 64. */
69 : ulong epoch_credits_history_len;
70 : epoch_credits_t epoch_credits[ EPOCH_CREDITS_MAX ];
71 : };
72 :
73 : typedef struct fd_snapshot_manifest_vote_account fd_snapshot_manifest_vote_account_t;
74 :
75 : struct fd_snapshot_manifest_stake_delegation {
76 : /* The stake pubkey */
77 : uchar stake_pubkey[ 32UL ];
78 :
79 : /* The vote pubkey that the stake account is delegated to */
80 : uchar vote_pubkey[ 32UL ];
81 :
82 : /* The amount of stake delegated */
83 : ulong stake_delegation;
84 :
85 : /* The activation epoch of the stake delegation */
86 : ulong activation_epoch;
87 :
88 : /* The deactivation epoch of the stake delegation */
89 : ulong deactivation_epoch;
90 :
91 : /* The amount of credits observed for the stake delegation */
92 : ulong credits_observed;
93 :
94 : /* The warmup cooldown rate for the stake delegation */
95 : double warmup_cooldown_rate;
96 : };
97 :
98 : typedef struct fd_snapshot_manifest_stake_delegation fd_snapshot_manifest_stake_delegation_t;
99 :
100 : /* TODO: Consider combining this struct with
101 : fd_snapshot_manifest_vote_account. */
102 :
103 : struct fd_snapshot_manifest_vote_stakes {
104 : /* The vote pubkey */
105 : uchar vote[ 32UL ];
106 :
107 : /* The validator identity pubkey, aka node pubkey */
108 : uchar identity[ 32UL ];
109 :
110 : /* The commission account for inflation rewards (vote, before SIMD-0232) */
111 : uchar commission_inflation[ 32UL ];
112 :
113 : /* The commission account for block revenue (identity, before SIMD-0232) */
114 : uchar commission_block[ 32UL ];
115 :
116 : /* The validator BLS pubkey (used after SIMD-0326: Alpenglow) */
117 : uchar identity_bls[ 48UL ];
118 :
119 : /* The total amount of active stake for the vote account */
120 : ulong stake;
121 :
122 : /* The latest slot and timestmap that the vote account voted on in
123 : the given epoch. */
124 : ulong slot;
125 : long timestamp;
126 :
127 : /* The validator's commission rate as of the given epoch. */
128 : uchar commission;
129 :
130 : /* The epoch credits array tracks the history of how many credits the
131 : provided vote account earned in each of the past epochs. The
132 : entry at epoch_credits[0] is for the current epoch,
133 : epoch_credits[1] is for the previous epoch, and so on. In cases of
134 : booting a new chain from genesis, or for new vote accounts the
135 : epoch credits history may be short. The maximum number of entries
136 : in the epoch credits history is 64. */
137 : ulong epoch_credits_history_len;
138 : epoch_credits_t epoch_credits[ EPOCH_CREDITS_MAX ];
139 : };
140 :
141 : typedef struct fd_snapshot_manifest_vote_stakes fd_snapshot_manifest_vote_stakes_t;
142 :
143 : struct fd_snapshot_manifest_epoch_stakes {
144 : /* The total amount of active stake at the end of the given epoch.*/
145 : ulong total_stake;
146 :
147 : /* The vote accounts and their stakes for a given epoch. */
148 : ulong vote_stakes_len;
149 : fd_snapshot_manifest_vote_stakes_t vote_stakes[ FD_RUNTIME_MAX_VOTE_ACCOUNTS ];
150 : };
151 :
152 : typedef struct fd_snapshot_manifest_epoch_stakes fd_snapshot_manifest_epoch_stakes_t;
153 :
154 : struct fd_snapshot_manifest_inflation_params {
155 : /* The initial inflation percentage starting at genesis.
156 : This value is set at genesis to 8% and is not expected to change. */
157 : double initial;
158 :
159 : /* The terminal inflation percentage is the long-term steady state
160 : inflation rate after a period of disinflation. This value is set
161 : at genesis to 1.5% and is not expected to change. */
162 : double terminal;
163 :
164 : /* The rate per year at which inflation is lowered until it reaches
165 : the terminal inflation rate. This value is set to 15% at genesis
166 : and is not expected to change. */
167 : double taper;
168 :
169 : /* The percentage of total inflation allocated to the foundation.
170 : This value is set at genesis to 5% and is not expected to change. */
171 : double foundation;
172 :
173 : /* The number of years in which a portion of the total inflation is
174 : allocated to the foundation (see foundation field). This value is
175 : set to 7 years at genesis and is not expected to change. */
176 : double foundation_term;
177 : };
178 :
179 : typedef struct fd_snapshot_manifest_inflation_params fd_snapshot_manifest_inflation_params_t;
180 :
181 : struct fd_snapshot_manifest_epoch_schedule_params {
182 : /* The maximum number of slots in each epoch. */
183 : ulong slots_per_epoch;
184 :
185 : /* A number of slots before beginning of an epoch to calculate a
186 : leader schedule for that epoch. This value is set to
187 : slots_per_epoch (basically one epoch) and is unlikely to change. */
188 : ulong leader_schedule_slot_offset;
189 :
190 : /* Whether there is a warmup period where epochs are short and grow by
191 : powers of two until they reach the default epoch length of
192 : slots_per_epoch. This value is set by default to true at genesis,
193 : though it may be configured differently in development
194 : environments. */
195 : uchar warmup;
196 :
197 : /* TODO: Probably remove this? Redundant and can be calculated from
198 : the above. */
199 : ulong first_normal_epoch;
200 : ulong first_normal_slot;
201 : };
202 :
203 : typedef struct fd_snapshot_manifest_epoch_schedule_params fd_snapshot_manifest_epoch_schedule_params_t;
204 :
205 : struct fd_snapshot_manifest_fee_rate_governor {
206 : /* Transaction fees are calculated by charging a cost for each
207 : signature. There is a mechanism to dynamically adjust the cost per
208 : signature based on the cluster's transaction processing capacity.
209 : In this mechanism, the cost per signature can vary between 50% to
210 : 1000% of the target_lamports_per_signature value, which is the cost
211 : per signature when the cluster is operating at the desired
212 : transaction processing capacity defined by
213 : target_signatures_per_slot.
214 :
215 : This value is fixed at 10,000 from genesis onwards but may be
216 : changed in the future with feature flags. */
217 : ulong target_lamports_per_signature;
218 :
219 : /* The cluster transaction processing capacity is measured by
220 : signatures per slot. Solana defines the desired transaction
221 : processing capacity using the value target_signatures_per_slot.
222 :
223 : This value is fixed at 20,000 from genesis onwards but may be
224 : changed in the future with feature flags. */
225 : ulong target_signatures_per_slot;
226 :
227 : /* The minimum cost per signature is 50% of the
228 : target_lamports_per_signature value. Under the current default for
229 : target_lamports_per_signature, this value is at 5,000 lamports per
230 : signature. */
231 : ulong min_lamports_per_signature;
232 :
233 : /* The maximum cost per signature is 1000% of the
234 : target_lamports_per_signature value. Under the current default for
235 : target_lamports_per_signature, this value is at 100,000 lamports
236 : per signature.*/
237 : ulong max_lamports_per_signature;
238 :
239 : /* The percent of collected fees that are burned. This value is
240 : currently set to a fixed value of 50% from genesis onwards, but
241 : may be changed in the future with feature flags. */
242 : uchar burn_percent;
243 : };
244 :
245 : typedef struct fd_snapshot_manifest_fee_rate_governor fd_snapshot_manifest_fee_rate_governor_t;
246 :
247 : struct fd_snapshot_manifest_rent {
248 : ulong lamports_per_uint8_year;
249 : double exemption_threshold;
250 : uchar burn_percent;
251 : };
252 :
253 : typedef struct fd_snapshot_manifest_rent fd_snapshot_manifest_rent_t;
254 :
255 : struct fd_snapshot_manifest_blockhash {
256 : uchar hash[ 32UL ];
257 : ulong lamports_per_signature;
258 : ulong hash_index;
259 : ulong timestamp;
260 : };
261 :
262 : typedef struct fd_snapshot_manifest_blockhash fd_snapshot_manifest_blockhash_t;
263 :
264 : struct fd_snapshot_manifest {
265 : /* The UNIX timestamp when the genesis block was for this chain
266 : was created, in nanoseconds. */
267 : ulong creation_time_millis;
268 :
269 : /* At genesis, certain parameters can be set which control the
270 : inflation rewards going forward. This includes what the initial
271 : inflation is and how the inflation curve changes over time.
272 :
273 : Currently, these parameters can never change and are fixed from
274 : genesis onwards, although in future they may change with new
275 : feature flags. */
276 : fd_snapshot_manifest_inflation_params_t inflation_params;
277 :
278 : /* At genesis, certain parameters can be set which control the
279 : epoch schedule going forward. This includes how many slots
280 : there are per epoch, and certain development settings like if
281 : epochs start short and grow longer as the chain progreses.
282 :
283 : Currently, these parameters can never change and are fixed from
284 : genesis onwards, although in future they may change with new
285 : feature flags. */
286 : fd_snapshot_manifest_epoch_schedule_params_t epoch_schedule_params;
287 :
288 : /* At genesis, certain parameters can be set which control
289 : how transaction fees are dynamically adjusted going forward.
290 :
291 : Currently, these parameters can never change and are fixed from
292 : genesis onwards, although in future they may change with new
293 : feature flags. */
294 : fd_snapshot_manifest_fee_rate_governor_t fee_rate_governor;
295 :
296 : fd_snapshot_manifest_rent_t rent_params;
297 :
298 : /* The slot number for this snapshot */
299 : ulong slot;
300 :
301 : /* The number of blocks that have been built since genesis. This is
302 : kind of like the slot number, in that it increments by 1 for every
303 : landed block, but it does not increment for skipped slots, so the
304 : block_height will always be less than or equal to the slot. */
305 : ulong block_height;
306 :
307 : /* TODO: Document */
308 : ulong collector_fees;
309 :
310 : /* The parent slot is the slot that this block builds on top of. It
311 : is typically slot-1, but can be an arbitrary amount of slots
312 : earlier in case of forks, when the block skips over preceding
313 : slots. */
314 : ulong parent_slot;
315 :
316 : /* The bank hash of the slot represented by this snapshot. The bank
317 : hash is used by the validator to detect mismatches. All validators
318 : must agree on a bank hash for each slot or they will fork off.
319 :
320 : The bank hash is created for every slot by hashing together the
321 : parent bank hash with the accounts delta hash, the most recent
322 : Proof of History blockhash, and the number of signatures in the
323 : slot.
324 :
325 : The bank hash includes the epoch accounts hash when the epoch
326 : accounts hash is ready at slot 324000 in the current epoch. See the
327 : epoch_accounts_hash for more details regarding the epcoh accounts
328 : hash calculation . */
329 : uchar bank_hash[ 32UL ];
330 :
331 : /* The bank hash of the parent slot. */
332 : uchar parent_bank_hash[ 32UL ];
333 :
334 : /* The merkle-based hash of all account state on chain at the slot the
335 : snapshot is created. The accounts hash is calculated when producing
336 : a snapshot. */
337 : uchar accounts_hash[ 32UL ];
338 :
339 : /* The merkle-based hash of modified accounts for the slot the
340 : snapshot is created. The accounts_delta_hash is computed at
341 : the end of every slot and included into each bank hash. It is
342 : computed by hashing all modified account state together. */
343 : uchar accounts_delta_hash[ 32UL ];
344 :
345 : /* The lattice hash of all account state on chain. It is not yet used
346 : but in future will replace the accounts hash and the accounts delta
347 : hash. Those hashes are expensive to compute because they require
348 : sorting the accounts, while the lattice hash uses newer cryptography
349 : to avoid this. */
350 : int has_accounts_lthash;
351 : uchar accounts_lthash[ 2048UL ];
352 :
353 : /* The hash of all accounts at this snapshot's epoch.
354 : The epoch account hash is very expensive to calculate, so it is
355 : only calculated once per epoch during the epoch account hash
356 : calculation window, which is a range of slots in an epoch starting
357 : at slot 108000 and ending at slot 324000, where each epoch has
358 : 432000 slots.
359 :
360 : The epoch_account_hash may be empty if the snapshot was produced
361 : before the epoch account hash calculation window. */
362 : int has_epoch_account_hash;
363 : uchar epoch_account_hash[ 32UL ];
364 :
365 : ulong blockhashes_len;
366 : fd_snapshot_manifest_blockhash_t blockhashes[ 301UL ];
367 :
368 : /* The fork_id in the status cache for the root slot. */
369 : ushort txncache_fork_id;
370 :
371 : /* A list of ancestor slots. The bound comes from
372 : https://github.com/anza-xyz/agave/blob/v3.0.6/accounts-db/src/ancestors.rs#L24
373 : However in extreme conditons, the bound may be exceeded because
374 : the ancestors data structure in agave contains an unbounded excess
375 : field. If the bound is exceeded, the snapshot is considered
376 : malformed. */
377 : ulong ancestors_len;
378 : ulong ancestors[ 8192UL ];
379 :
380 : ulong hard_forks_len;
381 : ulong hard_forks[ 64UL ];
382 :
383 : /* The proof of history component "proves" the passage of time (see
384 : extended discussion in PoH tile for what that acutally means) by
385 : continually doing sha256 hashes. A certain number of hashes are
386 : required to be in each slot, to prove the leader spent some amount
387 : of time on the slot and didn't end it too early.
388 :
389 : In all clusters and environments that matter, this value is fixed
390 : at 64 and is unlikely to change, however it might be configured
391 : differently in development environments. */
392 : ulong ticks_per_slot;
393 :
394 : /* TODO: Document */
395 : ulong ns_per_slot;
396 :
397 : /* TODO: Document */
398 : double slots_per_year;
399 :
400 : /* The proof of history component typically requires every block to
401 : have 64 "ticks" in it (although this is configurable during
402 : development), but each tick is some flexible number of recursive
403 : sha256 hashes defined at genesis.
404 :
405 : The number of hashes for mainnet genesis is 12,500, meaning there
406 : will be 800,000 hashes per slot.
407 :
408 : There are various features, named like update_hashes_per_tick*
409 : which if enabled update the hashes_per_tick of the chain as-of the
410 : epoch where they are enabled. This value incorporates any changes
411 : due to such features.
412 :
413 : In development environments, sometimes hashes_per_tick will not be
414 : specified (has_hashes_per_tick will be 0). Agave refers to this as
415 : a "low power" mode, where ticks have just one hash in them. It is
416 : distinct from just setting hahes_per_tick to 1, because it also
417 : reduces the slot duration from 400ms down to 0ms (or however long
418 : it takes to produce the hash). See comments in the PoH tile for
419 : more extended discussion. */
420 : int has_hashes_per_tick;
421 : ulong hashes_per_tick;
422 :
423 : /* The sum of all account balances in lamports as of this snapshots
424 : slot. Total capitalization is used when computing inflation
425 : rewards and validating snapshots. */
426 : ulong capitalization;
427 :
428 : /* TODO: Why is this needed? */
429 : ulong tick_height;
430 : ulong max_tick_height;
431 :
432 : /* TODO: What is this? */
433 : ulong lamports_per_signature;
434 :
435 : /* TODO: Why is this needed? */
436 : ulong transaction_count;
437 :
438 : /* TODO: Why is this needed? */
439 : ulong signature_count;
440 :
441 : /* A list of this epoch's vote accounts and their state relating to
442 : rewards distribution, which includes the vote account's commission
443 : and vote credits.
444 :
445 : The validator distributes vote and stake rewards for the previous
446 : epoch in the slots immediately after the epoch boundary. These
447 : vote and stake rewards are calculated as a stake-weighted
448 : percentage of the inflation rewards for the epoch and validator
449 : uptime, which is measured by vote account vote credits. */
450 : ulong vote_accounts_len;
451 : fd_snapshot_manifest_vote_account_t vote_accounts[ FD_RUNTIME_MAX_VOTE_ACCOUNTS ];
452 :
453 : ulong stake_delegations_len;
454 : fd_snapshot_manifest_stake_delegation_t stake_delegations[ FD_RUNTIME_MAX_STAKE_ACCOUNTS ];
455 :
456 : /* Epoch stakes represent the exact amount staked to each vote
457 : account at the beginning of the previous epoch. They are
458 : primarily used to derive the leader schedule.
459 :
460 : Let's say the manifest is at epoch E.
461 :
462 : The field versioned_epoch_stakes in the manifest is a map
463 :
464 : <epoch> -> <VersionedEpochStakes>
465 :
466 : where <epoch> assumes these values:
467 :
468 : E - represents the stakes at the beginning of epoch E-1,
469 : used to compute the leader schedule at E.
470 :
471 : E+1 - represents the stakes at the beginning of epoch E,
472 : used to compute the leader schedule at E+1.
473 :
474 : The epoch stakes are stored in an array, where epoch_stakes[0]
475 : contains the data to generate the current leader schedule (i.e. E)
476 : and epoch_stakes[1] contains the data to generate the next leader
477 : schedule (i.e. E+1). */
478 : fd_snapshot_manifest_epoch_stakes_t epoch_stakes[ 2UL ];
479 : };
480 :
481 : typedef struct fd_snapshot_manifest fd_snapshot_manifest_t;
482 :
483 : #endif /* HEADER_fd_src_discof_restore_utils_fd_ssmsg_h */
|
