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