massa_pos_exports/
pos_final_state.rs

1use crate::{
2    CycleInfo, CycleInfoDeserializer, CycleInfoSerializer, DeferredCreditDeserializer,
3    DeferredCreditSerializer, DeferredCredits, PoSChanges, PoSConfig, PosError, PosResult,
4    ProductionStats, SelectorController,
5};
6use bitvec::vec::BitVec;
7use massa_db_exports::{
8    DBBatch, MassaDirection, MassaIteratorMode, ShareableMassaDBController,
9    CYCLE_HISTORY_DESER_ERROR, CYCLE_HISTORY_PREFIX, CYCLE_HISTORY_SER_ERROR,
10    DEFERRED_CREDITS_DESER_ERROR, DEFERRED_CREDITS_PREFIX, DEFERRED_CREDITS_SER_ERROR, STATE_CF,
11};
12use massa_hash::{Hash, HashXof, HASH_XOF_SIZE_BYTES};
13use massa_ledger_exports::LedgerController;
14use massa_models::{
15    address::Address, amount::Amount, config::LEDGER_ENTRY_BASE_COST, prehash::PreHashMap,
16    slot::Slot,
17};
18use massa_serialization::{
19    buf_to_array_ctr, DeserializeError, Deserializer, Serializer, U64VarIntSerializer,
20};
21use nom::AsBytes;
22use std::{
23    collections::{BTreeMap, VecDeque},
24    ops::{
25        Bound::{Excluded, Included, Unbounded},
26        RangeBounds,
27    },
28    path::PathBuf,
29};
30use tracing::{debug, warn};
31
32// General cycle info idents
33const COMPLETE_IDENT: u8 = 0u8;
34const RNG_SEED_IDENT: u8 = 1u8;
35const FINAL_STATE_HASH_SNAPSHOT_IDENT: u8 = 2u8;
36const ROLL_COUNT_IDENT: u8 = 3u8;
37const PROD_STATS_IDENT: u8 = 4u8;
38
39// Production stats idents
40const PROD_STATS_FAIL_IDENT: u8 = 0u8;
41const PROD_STATS_SUCCESS_IDENT: u8 = 1u8;
42
43/// Complete key formatting macro
44#[macro_export]
45macro_rules! complete_key {
46    ($cycle_prefix:expr) => {
47        [&$cycle_prefix[..], &[COMPLETE_IDENT]].concat()
48    };
49}
50
51/// Rng seed key formatting macro
52#[macro_export]
53macro_rules! rng_seed_key {
54    ($cycle_prefix:expr) => {
55        [&$cycle_prefix[..], &[RNG_SEED_IDENT]].concat()
56    };
57}
58
59/// Final state hash snapshot key formatting macro
60#[macro_export]
61macro_rules! final_state_hash_snapshot_key {
62    ($cycle_prefix:expr) => {
63        [&$cycle_prefix[..], &[FINAL_STATE_HASH_SNAPSHOT_IDENT]].concat()
64    };
65}
66
67/// Roll count key prefix macro
68#[macro_export]
69macro_rules! roll_count_prefix {
70    ($cycle_prefix:expr) => {
71        [&$cycle_prefix[..], &[ROLL_COUNT_IDENT]].concat()
72    };
73}
74
75/// Roll count key formatting macro
76#[macro_export]
77macro_rules! roll_count_key {
78    ($cycle_prefix:expr, $addr:expr) => {
79        [
80            &$cycle_prefix[..],
81            &[ROLL_COUNT_IDENT],
82            &$addr.to_prefixed_bytes()[..],
83        ]
84        .concat()
85    };
86}
87
88/// Production stats prefix macro
89#[macro_export]
90macro_rules! prod_stats_prefix {
91    ($cycle_prefix:expr) => {
92        [&$cycle_prefix[..], &[PROD_STATS_IDENT]].concat()
93    };
94}
95
96/// Production stats fail key formatting macro
97#[macro_export]
98macro_rules! prod_stats_fail_key {
99    ($cycle_prefix:expr, $addr:expr) => {
100        [
101            &$cycle_prefix[..],
102            &[PROD_STATS_IDENT],
103            &$addr.to_prefixed_bytes()[..],
104            &[PROD_STATS_FAIL_IDENT],
105        ]
106        .concat()
107    };
108}
109
110/// Production stats success key formatting macro
111#[macro_export]
112macro_rules! prod_stats_success_key {
113    ($cycle_prefix:expr, $addr:expr) => {
114        [
115            &$cycle_prefix[..],
116            &[PROD_STATS_IDENT],
117            &$addr.to_prefixed_bytes()[..],
118            &[PROD_STATS_SUCCESS_IDENT],
119        ]
120        .concat()
121    };
122}
123
124/// Deferred credits key formatting macro
125#[macro_export]
126macro_rules! deferred_credits_key {
127    ($id:expr) => {
128        [&DEFERRED_CREDITS_PREFIX.as_bytes(), &$id[..]].concat()
129    };
130}
131
132#[derive(Clone)]
133/// Final state of PoS
134pub struct PoSFinalState {
135    /// proof-of-stake configuration
136    pub config: PoSConfig,
137    /// Access to the RocksDB database
138    pub db: ShareableMassaDBController,
139    /// contiguous cycle history, back = newest
140    pub cycle_history_cache: VecDeque<(u64, bool)>,
141    /// rng_seed cache to get rng_seed for the current cycle
142    pub rng_seed_cache: Option<(u64, BitVec<u8>)>,
143    /// selector controller
144    pub selector: Box<dyn SelectorController>,
145    /// initial rolls, used for negative cycle look back
146    pub initial_rolls: BTreeMap<Address, u64>,
147    /// initial seeds, used for negative cycle look back (cycles -2, -1 in that order)
148    pub initial_seeds: Vec<Hash>,
149    /// inner deferred credits serializer (one slot's credits)
150    pub credits_serializer: DeferredCreditSerializer,
151    /// inner deferred credits deserializer (one slot's credits)
152    pub credits_deserializer: DeferredCreditDeserializer,
153    /// cycle info serializer
154    pub cycle_info_serializer: CycleInfoSerializer,
155    /// cycle info deserializer
156    pub cycle_info_deserializer: CycleInfoDeserializer,
157}
158
159impl PoSFinalState {
160    /// Number of slots (and thus RNG seed bits) in a full cycle.
161    fn slots_per_cycle(&self) -> usize {
162        self.config
163            .periods_per_cycle
164            .saturating_mul(self.config.thread_count as u64)
165            .try_into()
166            .expect("slots_per_cycle overflow")
167    }
168
169    /// create a new `PoSFinalState`
170    pub fn new(
171        config: PoSConfig,
172        initial_seed_string: &str,
173        initial_rolls_path: &PathBuf,
174        selector: Box<dyn SelectorController>,
175        db: ShareableMassaDBController,
176    ) -> Result<Self, PosError> {
177        // load get initial rolls from file
178        let initial_rolls = serde_json::from_str::<BTreeMap<Address, u64>>(
179            &std::fs::read_to_string(initial_rolls_path).map_err(|err| {
180                PosError::RollsFileLoadingError(format!("error while deserializing: {}", err))
181            })?,
182        )
183        .map_err(|err| PosError::RollsFileLoadingError(format!("error opening file: {}", err)))?;
184
185        // Seeds used as the initial seeds for negative cycles (-2 and -1 respectively)
186        let init_seed = Hash::compute_from(initial_seed_string.as_bytes());
187        let initial_seeds = vec![Hash::compute_from(init_seed.to_bytes()), init_seed];
188
189        let cycle_info_deserializer =
190            CycleInfoDeserializer::new(config.max_rolls_length, config.max_production_stats_length);
191
192        let pos_state = Self {
193            config: config.clone(),
194            db,
195            cycle_history_cache: Default::default(),
196            rng_seed_cache: None,
197            selector,
198            initial_rolls,
199            initial_seeds,
200            credits_serializer: DeferredCreditSerializer::new(),
201            credits_deserializer: DeferredCreditDeserializer::new(config.max_credit_length),
202            cycle_info_serializer: CycleInfoSerializer::new(),
203            cycle_info_deserializer,
204        };
205
206        Ok(pos_state)
207    }
208
209    /// Try load initial deferred credits from file
210    ///
211    /// Credits that would fail at execution time (same rules as `transfer_coins` when
212    /// crediting with `from_addr = None`) are skipped:
213    /// * non-existing SC address
214    /// * non-existing user address with `amount` below the ledger entry base cost
215    pub fn load_initial_deferred_credits(
216        &mut self,
217        batch: &mut DBBatch,
218        ledger: &dyn LedgerController,
219    ) -> Result<(), PosError> {
220        let Some(initial_deferred_credits_path) = &self.config.initial_deferred_credits_path else {
221            return Ok(());
222        };
223
224        use serde::Deserialize;
225        #[derive(Deserialize)]
226        struct AddressInitialDeferredCredits {
227            slot: Slot,
228            amount: Amount,
229        }
230
231        let initial_deferred_credits =
232            serde_json::from_str::<PreHashMap<Address, Vec<AddressInitialDeferredCredits>>>(
233                &std::fs::read_to_string(initial_deferred_credits_path).map_err(|err| {
234                    PosError::DeferredCreditsFileLoadingError(format!(
235                        "error while deserializing initial deferred credits file {}: {}",
236                        initial_deferred_credits_path.display(),
237                        err
238                    ))
239                })?,
240            )
241            .map_err(|err| {
242                PosError::DeferredCreditsFileLoadingError(format!(
243                    "error loading initial deferred credits file {}: {}",
244                    initial_deferred_credits_path.display(),
245                    err
246                ))
247            })?;
248
249        for (address, deferred_credits) in initial_deferred_credits {
250            let address_is_sc = matches!(address, Address::SC(..));
251            let address_exists = ledger.entry_exists(&address);
252            for AddressInitialDeferredCredits { slot, amount } in deferred_credits {
253                if address_is_sc {
254                    warn!(
255                        "deferred credits for address {} with amount {} will not execute because it is a SC address",
256                        address, amount
257                    );
258                } else if !address_exists && amount < LEDGER_ENTRY_BASE_COST {
259                    warn!(
260                        "deferred credits for address {} with amount {} will likely not execute because the address does not exist in the ledger and the amount is below the ledger entry base cost",
261                        address, amount
262                    );
263                }
264
265                // Note that we still put the deferred credits in the database even if they are likely to fail at execution time.
266                // It's for instance possible the address is created before the execution slot of the deferred credits.
267                self.put_deferred_credits_entry(&slot, &address, &amount, batch);
268            }
269        }
270
271        Ok(())
272    }
273
274    /// After bootstrap or load from disk, recompute the caches
275    pub fn recompute_pos_state_caches(&mut self) {
276        self.cycle_history_cache = self.get_cycle_history_cycles().into();
277
278        if let Some((cycle, _)) = self.cycle_history_cache.back() {
279            self.rng_seed_cache = self
280                .get_cycle_history_rng_seed(*cycle)
281                .map(|rng_seed| (*cycle, rng_seed));
282        } else {
283            self.rng_seed_cache = None;
284        }
285    }
286
287    /// Ensures the persisted cycle history can be used for selector feeding.
288    ///
289    /// Cycles must be consecutive, as `get_cycle_index` assumes. A cycle marked
290    /// complete must have an RNG seed and a non-empty `final_state_hash_snapshot`.
291    /// Used after load/bootstrap and during DB validation so malformed history fails
292    /// fast instead of panicking later in `feed_selector`.
293    ///
294    /// The history length is deliberately not capped to `cycle_history_length`: an
295    /// interrupted multi-cycle downtime interpolation legitimately persists more cycles
296    /// until its final pruning, and the next start resumes it.
297    pub fn validate_selector_history(&self) -> PosResult<()> {
298        let cycles = self.get_cycle_history_cycles();
299        for pair in cycles.windows(2) {
300            let (prev, next) = (pair[0].0, pair[1].0);
301            if prev.checked_add(1) != Some(next) {
302                return Err(PosError::ContainerInconsistency(format!(
303                    "cycle history is not consecutive: cycle {} is followed by cycle {}",
304                    prev, next
305                )));
306            }
307        }
308        for (cycle, complete) in cycles {
309            if !complete {
310                continue;
311            }
312            if self.get_cycle_history_rng_seed(cycle).is_none() {
313                return Err(PosError::ContainerInconsistency(format!(
314                    "complete cycle {} is missing RNG seed required for selector feeding",
315                    cycle
316                )));
317            }
318            if self
319                .get_cycle_history_final_state_hash_snapshot(cycle)
320                .is_none()
321            {
322                return Err(PosError::ContainerInconsistency(format!(
323                    "complete cycle {} is missing final state hash snapshot required for selector feeding",
324                    cycle
325                )));
326            }
327        }
328        Ok(())
329    }
330
331    /// Reset the state of the PoS final state
332    ///
333    /// USED ONLY FOR BOOTSTRAP
334    pub fn reset(&mut self) {
335        let mut db = self.db.write();
336        db.delete_prefix(CYCLE_HISTORY_PREFIX, STATE_CF, None);
337        db.delete_prefix(DEFERRED_CREDITS_PREFIX, STATE_CF, None);
338        self.cycle_history_cache = Default::default();
339        self.rng_seed_cache = None;
340    }
341
342    /// Create the initial cycle based off the initial rolls.
343    ///
344    /// This should be called only if bootstrap did not happen.
345    pub fn create_initial_cycle(&mut self, batch: &mut DBBatch) {
346        let mut rng_seed = BitVec::with_capacity(self.slots_per_cycle());
347        rng_seed.extend(vec![false; self.config.thread_count as usize]);
348
349        self.put_new_cycle_info(
350            &CycleInfo::new(
351                0,
352                false,
353                self.initial_rolls.clone(),
354                rng_seed,
355                PreHashMap::default(),
356            ),
357            batch,
358        );
359    }
360
361    /// Create a cycle based off of another cycle_info.
362    ///
363    /// Used for downtime interpolation, when restarting from a snapshot.
364    /// Roll counts are always carried over from `last_cycle_info`.
365    ///
366    /// `rng_seed` and `production_stats` are kept only when continuing the same
367    /// incomplete cycle (`last_cycle_info.cycle` matches the target cycle and
368    /// `first_slot` is not the first slot of that cycle). Otherwise the seed
369    /// starts fresh and `production_stats` are empty, so interpolated future
370    /// cycles do not inherit stale production results from the snapshot.
371    ///
372    /// In all cases, `rng_seed` is then extended with `false` bits for every
373    /// interpolated slot in `[first_slot, last_slot]`.
374    pub fn create_new_cycle_from_last(
375        &mut self,
376        last_cycle_info: &CycleInfo,
377        first_slot: Slot,
378        last_slot: Slot,
379        batch: &mut DBBatch,
380    ) -> Result<(), PosError> {
381        let cycle = last_slot.get_cycle(self.config.periods_per_cycle);
382
383        // Keep seed/stats only when filling the gap in the same incomplete cycle.
384        // Require both same cycle id and a non-first first_slot (defense in depth:
385        // callers may reuse a snapshot CycleInfo across several target cycles).
386        let continuing_same_cycle = last_cycle_info.cycle == cycle
387            && !first_slot.is_first_of_cycle(self.config.periods_per_cycle);
388
389        let (mut rng_seed, production_stats) = if continuing_same_cycle {
390            (
391                last_cycle_info.rng_seed.clone(),
392                last_cycle_info.production_stats.clone(),
393            )
394        } else {
395            (
396                BitVec::with_capacity(self.slots_per_cycle()),
397                PreHashMap::default(),
398            )
399        };
400
401        let num_slots = match last_slot.slots_since(&first_slot, self.config.thread_count) {
402            Ok(slots_since) => slots_since.saturating_add(1),
403            // if first_slot is greater than last_slot, we have nothing to do
404            Err(_) => return Ok(()),
405        };
406
407        let slots_per_cycle = self.slots_per_cycle();
408        // Existing seed (e.g. genesis thread_count padding) may already cover some of
409        // the interpolated range. Cap so we never exceed a full cycle.
410        if rng_seed.len() > slots_per_cycle {
411            return Err(PosError::ContainerInconsistency(format!(
412                "RNG seed for cycle {} exceeds slots_per_cycle: {} > {}",
413                cycle,
414                rng_seed.len(),
415                slots_per_cycle
416            )));
417        }
418        // Pad downtime slots; not the same as leaving the seed empty.
419        let to_add = (num_slots as usize).min(slots_per_cycle.saturating_sub(rng_seed.len()));
420        rng_seed.extend(vec![false; to_add]);
421
422        let complete =
423            last_slot.is_last_of_cycle(self.config.periods_per_cycle, self.config.thread_count);
424        if rng_seed.len() > slots_per_cycle || (complete && rng_seed.len() != slots_per_cycle) {
425            return Err(PosError::ContainerInconsistency(format!(
426                "invalid RNG seed length {} for cycle {} (slots_per_cycle {}, complete={})",
427                rng_seed.len(),
428                cycle,
429                slots_per_cycle,
430                complete
431            )));
432        }
433
434        self.put_new_cycle_info(
435            &CycleInfo::new(
436                cycle,
437                complete,
438                last_cycle_info.roll_counts.clone(),
439                rng_seed,
440                production_stats,
441            ),
442            batch,
443        );
444
445        Ok(())
446    }
447
448    /// Deletes a given cycle from RocksDB
449    pub fn delete_cycle_info(&mut self, cycle: u64, batch: &mut DBBatch) {
450        let db = self.db.read();
451
452        let prefix = self.cycle_history_cycle_prefix(cycle);
453
454        for (serialized_key, _) in db.prefix_iterator_cf(STATE_CF, &prefix) {
455            if !serialized_key.starts_with(prefix.as_bytes()) {
456                break;
457            }
458            db.delete_key(batch, serialized_key.to_vec());
459        }
460    }
461
462    /// Sends the current draw inputs (initial or bootstrapped) to the selector.
463    /// Waits for the initial draws to be performed.
464    pub fn compute_initial_draws(&mut self) -> PosResult<()> {
465        // Reject incomplete selector inputs before recomputing draws from history.
466        self.validate_selector_history()?;
467
468        // if cycle_history starts at a cycle that is strictly higher than 0, do not feed cycles 0, 1 to selector
469        let history_starts_late = self
470            .cycle_history_cache
471            .front()
472            .map(|c_info| c_info.0 > 0)
473            .unwrap_or(false);
474
475        let mut max_cycle = None;
476
477        // feed cycles 0, 1 to selector if necessary
478        if !history_starts_late {
479            for draw_cycle in 0u64..=1 {
480                self.feed_selector(draw_cycle)?;
481                max_cycle = Some(draw_cycle);
482            }
483        }
484
485        // feed cycles available from history
486        for (idx, hist_item) in self.cycle_history_cache.iter().enumerate() {
487            if !hist_item.1 {
488                break;
489            }
490            if history_starts_late && idx == 0 {
491                // If the history starts late, the first RNG seed cannot be used to draw
492                // because the roll distribution which should be provided by the previous element is absent.
493                continue;
494            }
495            let draw_cycle = hist_item.0.checked_add(2).ok_or_else(|| {
496                PosError::OverflowError("cycle overflow in give_selector_controller".into())
497            })?;
498            self.feed_selector(draw_cycle)?;
499            max_cycle = Some(draw_cycle);
500        }
501
502        // wait for all fed cycles to be drawn
503        if let Some(wait_cycle) = max_cycle {
504            self.selector.as_mut().wait_for_draws(wait_cycle)?;
505        }
506        Ok(())
507    }
508
509    /// Technical specification of `apply_changes_to_batch`:
510    ///
511    /// set `self.last_final_slot` = C
512    /// if cycle C is absent from `self.cycle_history_cache`:
513    ///     `push` a new empty `CycleInfo` on disk and reflect in `self.cycle_history_cache` and set its cycle = C
514    ///     `pop_front` from `cycle_history_cache` until front() represents cycle C-4 or later (not C-3 because we might need older endorsement draws on the limit between 2 cycles)
515    ///     delete the removed cycles from disk
516    /// for the cycle C entry in the db:
517    ///     extend `seed_bits` with `changes.seed_bits`
518    ///     extend `roll_counts` with `changes.roll_changes`
519    ///         delete all entries from `roll_counts` for which the roll count is zero
520    ///     add each element of `changes.production_stats` to the cycle's `production_stats`
521    /// for each `changes.deferred_credits` targeting cycle Ct:
522    ///     overwrite `self.deferred_credits` entries of cycle Ct in `cycle_history` with the ones from change
523    ///         remove entries for which Amount = 0
524    /// if slot S was the last of cycle C:
525    ///     set complete=true for cycle C in the history
526    ///     compute the seed hash and notifies the `PoSDrawer` for cycle `C+3`
527    ///
528    pub fn apply_changes_to_batch(
529        &mut self,
530        changes: PoSChanges,
531        slot: Slot,
532        feed_selector: bool,
533        batch: &mut DBBatch,
534    ) -> PosResult<()> {
535        let slots_per_cycle = self.slots_per_cycle();
536
537        // compute the current cycle from the given slot
538        let cycle = slot.get_cycle(self.config.periods_per_cycle);
539
540        // if cycle C is absent from self.cycle_history:
541        // push a new empty CycleInfo at the back of self.cycle_history and set its cycle = C
542        // pop_front from cycle_history until front() represents cycle C-4 or later
543        // (not C-3 because we might need older endorsement draws on the limit between 2 cycles)
544        if let Some(info) = self.cycle_history_cache.back() {
545            if cycle == info.0 && !info.1 {
546                // extend the last incomplete cycle
547            } else if info.0.checked_add(1) == Some(cycle) && info.1 {
548                // the previous cycle is complete, push a new incomplete/empty one to extend
549                // By now `_finalize` should already have written its final_state_hash_snapshot.
550                // Catch a missing snapshot here (first slot of the new cycle) instead of waiting
551                // until feed_selector needs it as a lookback (~1 cycle later).
552                if self
553                    .get_cycle_history_final_state_hash_snapshot(info.0)
554                    .is_none()
555                {
556                    return Err(PosError::ContainerInconsistency(format!(
557                        "complete cycle {} is missing final state hash snapshot before starting cycle {}",
558                        info.0, cycle
559                    )));
560                }
561
562                let roll_counts = self.get_all_roll_counts(info.0);
563                self.put_new_cycle_info(
564                    &CycleInfo::new(
565                        cycle,
566                        false,
567                        roll_counts,
568                        BitVec::with_capacity(slots_per_cycle),
569                        PreHashMap::default(),
570                    ),
571                    batch,
572                );
573                while self.cycle_history_cache.len() > self.config.cycle_history_length {
574                    if let Some((old_cycle, _)) = self.cycle_history_cache.pop_front() {
575                        self.delete_cycle_info(old_cycle, batch);
576                    }
577                }
578            } else {
579                return Err(PosError::OverflowError(
580                    "invalid cycle sequence in PoS final state".into(),
581                ));
582            }
583        } else {
584            return Err(PosError::ContainerInconsistency(
585                "PoS history should never be empty here".into(),
586            ));
587        }
588
589        let complete: bool =
590            slot.is_last_of_cycle(self.config.periods_per_cycle, self.config.thread_count);
591
592        // OPTIM: we could avoid reading the previous seed bits with a cache or with an update function
593        // Validate selector inputs before marking the cycle complete so a malformed seed cannot
594        // leave `complete=true` in the in-memory cache when we return an error.
595        let mut rng_seed = self.get_cycle_history_rng_seed(cycle).ok_or_else(|| {
596            PosError::ContainerInconsistency(format!("missing RNG seed for cycle {}", cycle))
597        })?;
598        // Reject already-corrupt or overflowing seed state before mutating caches/batch.
599        if rng_seed.len() > slots_per_cycle {
600            return Err(PosError::ContainerInconsistency(format!(
601                "RNG seed for cycle {} exceeds slots_per_cycle: {} > {}",
602                cycle,
603                rng_seed.len(),
604                slots_per_cycle
605            )));
606        }
607        rng_seed.extend(changes.seed_bits);
608        if rng_seed.len() > slots_per_cycle || (complete && rng_seed.len() != slots_per_cycle) {
609            return Err(PosError::ContainerInconsistency(format!(
610                "cycle {} RNG seed length {} invalid (slots_per_cycle {}, complete={})",
611                cycle,
612                rng_seed.len(),
613                slots_per_cycle,
614                complete
615            )));
616        }
617
618        self.put_cycle_history_complete(cycle, complete, batch);
619        self.put_cycle_history_rng_seed(cycle, rng_seed, batch);
620
621        // extend roll counts
622        for (addr, roll_count) in changes.roll_changes {
623            self.put_cycle_history_address_entry(cycle, &addr, Some(&roll_count), None, batch);
624        }
625
626        // extend production stats
627        for (addr, stats) in changes.production_stats {
628            if let Some(prev_production_stats) = self.get_production_stats_for_address(cycle, &addr)
629            {
630                let mut new_production_stats = prev_production_stats;
631                new_production_stats.extend(&stats);
632                self.put_cycle_history_address_entry(
633                    cycle,
634                    &addr,
635                    None,
636                    Some(&new_production_stats),
637                    batch,
638                );
639            } else {
640                self.put_cycle_history_address_entry(cycle, &addr, None, Some(&stats), batch);
641            }
642        }
643
644        // extend deferred_credits with changes.deferred_credits and remove zeros
645        for (slot, credits) in changes.deferred_credits.credits.iter() {
646            for (address, amount) in credits.iter() {
647                self.put_deferred_credits_entry(slot, address, amount, batch);
648            }
649        }
650
651        // feed the cycle if it is complete
652        // notify the PoSDrawer about the newly ready draw data
653        // to draw cycle + 2, we use the rng data from cycle - 1 and the seed from cycle
654        debug!(
655            "After slot {} PoS cycle list is {:?}",
656            slot, self.cycle_history_cache
657        );
658        if complete && feed_selector {
659            self.feed_selector(cycle.checked_add(2).ok_or_else(|| {
660                PosError::OverflowError("cycle overflow when feeding selector".into())
661            })?)
662        } else {
663            Ok(())
664        }
665    }
666
667    /// Feeds the selector targeting a given draw cycle
668    pub fn feed_selector(&self, draw_cycle: u64) -> PosResult<()> {
669        // get roll lookback
670
671        let (lookback_rolls, lookback_state_hash) = match draw_cycle.checked_sub(3) {
672            // looking back in history
673            Some(c) => {
674                let index = self
675                    .get_cycle_index(c)
676                    .ok_or(PosError::CycleUnavailable(c))?;
677                let cycle_info = &self.cycle_history_cache[index];
678                if !cycle_info.1 {
679                    return Err(PosError::CycleUnfinished(c));
680                }
681                // take the final_state_hash_snapshot at cycle - 3
682                // it will later be combined with rng_seed from cycle - 2 to determine the selection seed
683                // do this here to avoid a potential attacker manipulating the selections
684                let state_hash = self
685                    .get_cycle_history_final_state_hash_snapshot(cycle_info.0)
686                    .ok_or_else(|| {
687                        PosError::ContainerInconsistency(format!(
688                            "complete cycle {} is missing final state hash snapshot required for selector feeding",
689                            c
690                        ))
691                    })?;
692                (self.get_all_roll_counts(cycle_info.0), Some(state_hash))
693            }
694            // looking back to negative cycles
695            None => (self.initial_rolls.clone(), None),
696        };
697
698        // get seed lookback
699        let lookback_seed = match draw_cycle.checked_sub(2) {
700            // looking back in history
701            Some(c) => {
702                let index = self
703                    .get_cycle_index(c)
704                    .ok_or(PosError::CycleUnavailable(c))?;
705                let cycle_info = &self.cycle_history_cache[index];
706                if !cycle_info.1 {
707                    return Err(PosError::CycleUnfinished(c));
708                }
709                let u64_ser = U64VarIntSerializer::new();
710                let mut seed = Vec::new();
711                u64_ser.serialize(&c, &mut seed).unwrap();
712                let rng_seed = self
713                    .get_cycle_history_rng_seed(cycle_info.0)
714                    .ok_or_else(|| {
715                        PosError::ContainerInconsistency(format!(
716                            "complete cycle {} is missing RNG seed required for selector feeding",
717                            c
718                        ))
719                    })?;
720                seed.extend(rng_seed.into_vec());
721                if let Some(lookback_state_hash) = lookback_state_hash {
722                    seed.extend(lookback_state_hash.to_bytes());
723                }
724                Hash::compute_from(&seed)
725            }
726            // looking back to negative cycles
727            None => self.initial_seeds[draw_cycle as usize],
728        };
729
730        // feed selector
731        self.selector
732            .as_ref()
733            .feed_cycle(draw_cycle, lookback_rolls, lookback_seed)
734    }
735
736    /// Feeds the selector targeting a given draw cycle
737    pub fn feed_cycle_state_hash(
738        &self,
739        cycle: u64,
740        final_state_hash: HashXof<HASH_XOF_SIZE_BYTES>,
741    ) {
742        if self.get_cycle_index(cycle).is_some() {
743            let mut batch = DBBatch::new();
744            self.put_cycle_history_final_state_hash_snapshot(
745                cycle,
746                Some(final_state_hash),
747                &mut batch,
748            );
749
750            self.db.write().write_batch(batch, Default::default(), None);
751        } else {
752            panic!("cycle {} should be contained here", cycle);
753        }
754    }
755}
756
757// RocksDB getters
758impl PoSFinalState {
759    /// Retrieves the amount of rolls a given address has at the latest cycle
760    pub fn get_rolls_for(&self, addr: &Address) -> u64 {
761        self.cycle_history_cache
762            .back()
763            .and_then(|info| {
764                let cycle = info.0;
765                let db = self.db.read();
766
767                let key = roll_count_key!(self.cycle_history_cycle_prefix(cycle), addr);
768
769                if let Some(serialized_value) =
770                    db.get_cf(STATE_CF, key).expect(CYCLE_HISTORY_DESER_ERROR)
771                {
772                    let (_, amount) = self
773                        .cycle_info_deserializer
774                        .rolls_deser
775                        .u64_deserializer
776                        .deserialize::<DeserializeError>(&serialized_value)
777                        .expect(CYCLE_HISTORY_DESER_ERROR);
778
779                    Some(amount)
780                } else {
781                    None
782                }
783            })
784            .unwrap_or_default()
785    }
786
787    /// Retrieves the amount of rolls a given address has at a given cycle - 3
788    /// if cycle - 3 does not exist, values from initial rolls are returned
789    pub fn get_address_active_rolls(&self, addr: &Address, cycle: u64) -> Option<u64> {
790        match cycle.checked_sub(3) {
791            Some(lookback_cycle) => {
792                let key = roll_count_key!(self.cycle_history_cycle_prefix(lookback_cycle), addr);
793                let db = self.db.read();
794                if let Some(serialized_value) =
795                    db.get_cf(STATE_CF, key).expect(CYCLE_HISTORY_DESER_ERROR)
796                {
797                    let (_, amount) = self
798                        .cycle_info_deserializer
799                        .rolls_deser
800                        .u64_deserializer
801                        .deserialize::<DeserializeError>(&serialized_value)
802                        .expect(CYCLE_HISTORY_DESER_ERROR);
803
804                    Some(amount)
805                } else {
806                    None
807                }
808            }
809            None => self.initial_rolls.get(addr).cloned(),
810        }
811    }
812
813    /// Gets all active rolls for a given cycle - 3, use self.initial_rolls if cycle - 3 does not exist
814    pub fn get_all_active_rolls(&self, cycle: u64) -> BTreeMap<Address, u64> {
815        match cycle.checked_sub(3) {
816            Some(lookback_cycle) => {
817                // get rolls
818                self.get_all_roll_counts(lookback_cycle)
819            }
820            None => self.initial_rolls.clone(),
821        }
822    }
823
824    /// Retrieves every deferred credit in a slot range
825    /// Warning: this can be quite slow if there is tons of Deferred credits (e.g. just after genesis) to fetch
826    ///          so there is an option to filter by an address to improve the speed (cf json rpc api get_addresses)
827    pub fn get_deferred_credits_range<R>(
828        &self,
829        range: R,
830        addr_filter: Option<&Address>,
831    ) -> DeferredCredits
832    where
833        R: RangeBounds<Slot>,
834    {
835        let db = self.db.read();
836
837        let mut deferred_credits = DeferredCredits::new();
838
839        let mut start_key_buffer = Vec::new();
840        start_key_buffer.extend_from_slice(DEFERRED_CREDITS_PREFIX.as_bytes());
841
842        match range.start_bound() {
843            Included(slot) => {
844                start_key_buffer.extend_from_slice(&slot.to_bytes_key());
845            }
846            Excluded(slot) => {
847                start_key_buffer.extend_from_slice(
848                    &slot
849                        .get_next_slot(self.config.thread_count)
850                        .expect(DEFERRED_CREDITS_SER_ERROR)
851                        .to_bytes_key(),
852                );
853            }
854            Unbounded => {}
855        };
856
857        let iterator_cf = db
858            .iterator_cf(
859                STATE_CF,
860                MassaIteratorMode::From(&start_key_buffer, MassaDirection::Forward),
861            )
862            .take_while(|(k, _)| k.starts_with(DEFERRED_CREDITS_PREFIX.as_bytes()));
863
864        for (serialized_key, serialized_value) in iterator_cf {
865            // deserialize the slot
866            let rest_key = &serialized_key[DEFERRED_CREDITS_PREFIX.len()..];
867            let (rest_key, slot) = buf_to_array_ctr(rest_key, Slot::from_bytes_key)
868                .expect(DEFERRED_CREDITS_DESER_ERROR);
869
870            if !range.contains(&slot) {
871                break;
872            }
873
874            let (_, address) = self
875                .credits_deserializer
876                .address_deserializer
877                .deserialize::<DeserializeError>(rest_key)
878                .expect(DEFERRED_CREDITS_DESER_ERROR);
879
880            if let Some(addr_filter_value) = &addr_filter {
881                if &&address != addr_filter_value {
882                    continue;
883                }
884            }
885
886            let (_, amount) = self
887                .credits_deserializer
888                .amount_deserializer
889                .deserialize::<DeserializeError>(&serialized_value)
890                .expect(DEFERRED_CREDITS_DESER_ERROR);
891
892            deferred_credits.insert(slot, address, amount);
893        }
894
895        deferred_credits
896    }
897
898    /// Gets the index of a cycle in history
899    pub fn get_cycle_index(&self, cycle: u64) -> Option<usize> {
900        let first_cycle = match self.cycle_history_cache.front() {
901            Some(c) => c.0,
902            None => return None, // history empty
903        };
904        if cycle < first_cycle {
905            return None; // in the past
906        }
907        let index: usize = match (cycle - first_cycle).try_into() {
908            Ok(v) => v,
909            Err(_) => return None, // usize overflow
910        };
911        if index >= self.cycle_history_cache.len() {
912            return None; // in the future
913        }
914        Some(index)
915    }
916
917    /// Get all the roll counts for a given cycle
918    pub fn get_all_roll_counts(&self, cycle: u64) -> BTreeMap<Address, u64> {
919        let db = self.db.read();
920
921        if self.get_cycle_index(cycle).is_none() {
922            panic!("Cycle {} not in history", cycle)
923        }
924
925        let mut roll_counts: BTreeMap<Address, u64> = BTreeMap::new();
926        let prefix = roll_count_prefix!(self.cycle_history_cycle_prefix(cycle));
927        for (serialized_key, serialized_value) in db.prefix_iterator_cf(STATE_CF, &prefix) {
928            if !serialized_key.starts_with(prefix.as_bytes()) {
929                break;
930            }
931
932            // deserialize the cycle
933            let rest_key = &serialized_key[CYCLE_HISTORY_PREFIX.len()..];
934            let (rest_key, _cycle) = buf_to_array_ctr(rest_key, |v| u64::from_be_bytes(*v))
935                .expect(CYCLE_HISTORY_DESER_ERROR);
936
937            let (_, address) = self
938                .cycle_info_deserializer
939                .rolls_deser
940                .address_deserializer
941                .deserialize::<DeserializeError>(&rest_key[1..])
942                .expect(CYCLE_HISTORY_DESER_ERROR);
943
944            let (_, amount) = self
945                .cycle_info_deserializer
946                .rolls_deser
947                .u64_deserializer
948                .deserialize::<DeserializeError>(&serialized_value)
949                .expect(CYCLE_HISTORY_DESER_ERROR);
950
951            roll_counts.insert(address, amount);
952        }
953
954        roll_counts
955    }
956
957    /// Retrieves the productions statistics for all addresses on a given cycle
958    pub fn get_all_production_stats(
959        &self,
960        cycle: u64,
961    ) -> Option<PreHashMap<Address, ProductionStats>> {
962        self.get_cycle_index(cycle)
963            .map(|idx| self.get_all_production_stats_private(self.cycle_history_cache[idx].0))
964    }
965
966    /// Retrieves the productions statistics for all addresses on a given cycle
967    fn get_all_production_stats_private(&self, cycle: u64) -> PreHashMap<Address, ProductionStats> {
968        let db = self.db.read();
969
970        let mut production_stats: PreHashMap<Address, ProductionStats> = PreHashMap::default();
971        let mut cur_production_stat = ProductionStats::default();
972        let mut cur_address = None;
973
974        let prefix = prod_stats_prefix!(self.cycle_history_cycle_prefix(cycle));
975        for (serialized_key, serialized_value) in db.prefix_iterator_cf(STATE_CF, &prefix) {
976            if !serialized_key.starts_with(prefix.as_bytes()) {
977                break;
978            }
979
980            // deserialize the cycle
981            let rest_key = &serialized_key[CYCLE_HISTORY_PREFIX.len()..];
982            let (rest_key, _cycle) = buf_to_array_ctr(rest_key, |v| u64::from_be_bytes(*v))
983                .expect(CYCLE_HISTORY_DESER_ERROR);
984
985            let (rest_key, address) = self
986                .cycle_info_deserializer
987                .production_stats_deser
988                .address_deserializer
989                .deserialize::<DeserializeError>(&rest_key[1..])
990                .expect(CYCLE_HISTORY_DESER_ERROR);
991
992            if cur_address != Some(address) {
993                cur_address = Some(address);
994                cur_production_stat = ProductionStats::default();
995            }
996
997            let (_, value) = self
998                .cycle_info_deserializer
999                .production_stats_deser
1000                .u64_deserializer
1001                .deserialize::<DeserializeError>(&serialized_value)
1002                .expect(CYCLE_HISTORY_DESER_ERROR);
1003
1004            if rest_key.len() == 1 && rest_key[0] == PROD_STATS_FAIL_IDENT {
1005                cur_production_stat.block_failure_count = value;
1006            } else if rest_key.len() == 1 && rest_key[0] == PROD_STATS_SUCCESS_IDENT {
1007                cur_production_stat.block_success_count = value;
1008            } else {
1009                panic!("{}", CYCLE_HISTORY_DESER_ERROR);
1010            }
1011
1012            production_stats.insert(address, cur_production_stat);
1013        }
1014
1015        production_stats
1016    }
1017
1018    /// Getter for the rng_seed of a given cycle, prioritizing the cache and querying the database as fallback.
1019    fn get_cycle_history_rng_seed(&self, cycle: u64) -> Option<BitVec<u8>> {
1020        if let Some((cached_cycle, rng_seed)) = &self.rng_seed_cache {
1021            if *cached_cycle == cycle {
1022                return Some(rng_seed.clone());
1023            }
1024        }
1025
1026        let serialized_rng_seed = self
1027            .db
1028            .read()
1029            .get_cf(
1030                STATE_CF,
1031                rng_seed_key!(self.cycle_history_cycle_prefix(cycle)),
1032            )
1033            .expect(CYCLE_HISTORY_DESER_ERROR);
1034        let serialized_rng_seed = serialized_rng_seed?;
1035
1036        let (_, rng_seed) = self
1037            .cycle_info_deserializer
1038            .bitvec_deser
1039            .deserialize::<DeserializeError>(&serialized_rng_seed)
1040            .expect(CYCLE_HISTORY_DESER_ERROR);
1041
1042        Some(rng_seed)
1043    }
1044
1045    /// Getter for the final_state_hash_snapshot of a given cycle.
1046    ///
1047    /// Returns `None` if the RocksDB key is absent or if the stored value is `None`.
1048    fn get_cycle_history_final_state_hash_snapshot(
1049        &self,
1050        cycle: u64,
1051    ) -> Option<HashXof<HASH_XOF_SIZE_BYTES>> {
1052        let db = self.db.read();
1053
1054        let serialized_state_hash = db
1055            .get_cf(
1056                STATE_CF,
1057                final_state_hash_snapshot_key!(self.cycle_history_cycle_prefix(cycle)),
1058            )
1059            .expect(CYCLE_HISTORY_DESER_ERROR)?;
1060        let (_, state_hash) = self
1061            .cycle_info_deserializer
1062            .opt_hash_deser
1063            .deserialize::<DeserializeError>(&serialized_state_hash)
1064            .expect(CYCLE_HISTORY_DESER_ERROR);
1065        state_hash
1066    }
1067
1068    /// Used to recompute the cycle cache from the disk.
1069    ///
1070    fn get_cycle_history_cycles(&self) -> Vec<(u64, bool)> {
1071        let mut found_cycles: Vec<u64> = Vec::new();
1072
1073        {
1074            let db = self.db.read();
1075
1076            while let Some((serialized_key, _)) = match found_cycles.last() {
1077                // u64::MAX is the last possible cycle: stop instead of reading it again forever
1078                Some(prev_cycle) => prev_cycle.checked_add(1).and_then(|next_cycle| {
1079                    db.iterator_cf(
1080                        STATE_CF,
1081                        MassaIteratorMode::From(
1082                            &self.cycle_history_cycle_prefix(next_cycle),
1083                            MassaDirection::Forward,
1084                        ),
1085                    )
1086                    .next()
1087                }),
1088                None => db
1089                    .iterator_cf(
1090                        STATE_CF,
1091                        MassaIteratorMode::From(
1092                            CYCLE_HISTORY_PREFIX.as_bytes(),
1093                            MassaDirection::Forward,
1094                        ),
1095                    )
1096                    .next(),
1097            } {
1098                if !serialized_key.starts_with(CYCLE_HISTORY_PREFIX.as_bytes()) {
1099                    break;
1100                }
1101
1102                // deserialize the cycle
1103                let rest_key = &serialized_key[CYCLE_HISTORY_PREFIX.len()..];
1104                let (_rest_key, cycle) = buf_to_array_ctr(rest_key, |v| u64::from_be_bytes(*v))
1105                    .expect(CYCLE_HISTORY_DESER_ERROR);
1106
1107                found_cycles.push(cycle);
1108            }
1109        }
1110
1111        found_cycles
1112            .into_iter()
1113            .map(|cycle| (cycle, self.is_cycle_complete(cycle).unwrap_or(false)))
1114            .collect()
1115    }
1116
1117    /// Queries a given cycle info in the database
1118    pub fn get_cycle_info(&self, cycle: u64) -> Option<CycleInfo> {
1119        // TODO improve performance by not taking a lock and re-searching the key at every element
1120
1121        let complete = self.is_cycle_complete(cycle)?;
1122        let rng_seed = self.get_cycle_history_rng_seed(cycle)?;
1123        let final_state_hash_snapshot = self.get_cycle_history_final_state_hash_snapshot(cycle);
1124
1125        let roll_counts = self.get_all_roll_counts(cycle);
1126
1127        let production_stats = self.get_all_production_stats(cycle).unwrap_or_default();
1128
1129        let mut cycle_info =
1130            CycleInfo::new(cycle, complete, roll_counts, rng_seed, production_stats);
1131        cycle_info.final_state_hash_snapshot = final_state_hash_snapshot;
1132        Some(cycle_info)
1133    }
1134
1135    /// Gets the deferred credits for a given address that will be credited at a given slot
1136    pub fn get_address_credits_for_slot(&self, addr: &Address, slot: &Slot) -> Option<Amount> {
1137        let db = self.db.read();
1138
1139        let mut serialized_key = Vec::new();
1140        serialized_key.extend_from_slice(&slot.to_bytes_key());
1141        self.credits_serializer
1142            .address_ser
1143            .serialize(addr, &mut serialized_key)
1144            .expect(DEFERRED_CREDITS_SER_ERROR);
1145
1146        match db.get_cf(STATE_CF, deferred_credits_key!(serialized_key)) {
1147            Ok(Some(serialized_amount)) => {
1148                let (_, amount) = self
1149                    .credits_deserializer
1150                    .amount_deserializer
1151                    .deserialize::<DeserializeError>(&serialized_amount)
1152                    .expect(DEFERRED_CREDITS_DESER_ERROR);
1153                Some(amount)
1154            }
1155            _ => None,
1156        }
1157    }
1158
1159    /// Gets the production stats for a given address
1160    pub fn get_production_stats_for_address(
1161        &self,
1162        cycle: u64,
1163        address: &Address,
1164    ) -> Option<ProductionStats> {
1165        let db = self.db.read();
1166
1167        let prefix = self.cycle_history_cycle_prefix(cycle);
1168
1169        let query = vec![
1170            (STATE_CF, prod_stats_fail_key!(prefix, *address)),
1171            (STATE_CF, prod_stats_success_key!(prefix, *address)),
1172        ];
1173
1174        let results = db.multi_get_cf(query);
1175
1176        match (results.first(), results.get(1)) {
1177            (Some(Ok(Some(serialized_fail))), Some(Ok(Some(serialized_success)))) => {
1178                let (_, fail) = self
1179                    .cycle_info_deserializer
1180                    .production_stats_deser
1181                    .u64_deserializer
1182                    .deserialize::<DeserializeError>(serialized_fail)
1183                    .expect(CYCLE_HISTORY_DESER_ERROR);
1184                let (_, success) = self
1185                    .cycle_info_deserializer
1186                    .production_stats_deser
1187                    .u64_deserializer
1188                    .deserialize::<DeserializeError>(serialized_success)
1189                    .expect(CYCLE_HISTORY_DESER_ERROR);
1190
1191                Some(ProductionStats {
1192                    block_success_count: success,
1193                    block_failure_count: fail,
1194                })
1195            }
1196            _ => None,
1197        }
1198    }
1199
1200    /// Check if a cycle is complete (all slots finalized)
1201    pub fn is_cycle_complete(&self, cycle: u64) -> Option<bool> {
1202        let key = complete_key!(self.cycle_history_cycle_prefix(cycle));
1203        let res = self.db.read().get_cf(STATE_CF, key);
1204        match res {
1205            Ok(Some(complete_value)) => Some(complete_value.first() == Some(&1)),
1206            Ok(None) => None,
1207            Err(err) => {
1208                panic!(
1209                    "Error while checking if cycle {} is complete: {}",
1210                    cycle, err
1211                );
1212            }
1213        }
1214    }
1215}
1216
1217// RocksDB setters
1218impl PoSFinalState {
1219    /// Helper function to put a new CycleInfo to RocksDB, and update the cycle_history cache
1220    pub fn put_new_cycle_info(&mut self, cycle_info: &CycleInfo, batch: &mut DBBatch) {
1221        self.put_cycle_history_complete(cycle_info.cycle, cycle_info.complete, batch);
1222        self.put_cycle_history_rng_seed(cycle_info.cycle, cycle_info.rng_seed.clone(), batch);
1223        self.put_cycle_history_final_state_hash_snapshot(
1224            cycle_info.cycle,
1225            cycle_info.final_state_hash_snapshot,
1226            batch,
1227        );
1228        for (address, roll) in cycle_info.roll_counts.iter() {
1229            self.put_cycle_history_address_entry(
1230                cycle_info.cycle,
1231                address,
1232                Some(roll),
1233                None,
1234                batch,
1235            );
1236        }
1237        for (address, prod_stats) in cycle_info.production_stats.iter() {
1238            self.put_cycle_history_address_entry(
1239                cycle_info.cycle,
1240                address,
1241                None,
1242                Some(prod_stats),
1243                batch,
1244            );
1245        }
1246        self.cycle_history_cache
1247            .push_back((cycle_info.cycle, cycle_info.complete));
1248    }
1249
1250    /// Helper function to put a the complete flag for a given cycle
1251    fn put_cycle_history_complete(&mut self, cycle: u64, value: bool, batch: &mut DBBatch) {
1252        let db = self.db.read();
1253
1254        let prefix = self.cycle_history_cycle_prefix(cycle);
1255
1256        let serialized_value = if value { &[1] } else { &[0] };
1257
1258        db.put_or_update_entry_value(batch, complete_key!(prefix), serialized_value);
1259
1260        if let Some(index) = self.get_cycle_index(cycle) {
1261            self.cycle_history_cache[index].1 = value;
1262        }
1263    }
1264
1265    /// Helper function to put a the final_state_hash_snapshot for a given cycle
1266    fn put_cycle_history_final_state_hash_snapshot(
1267        &self,
1268        cycle: u64,
1269        value: Option<HashXof<HASH_XOF_SIZE_BYTES>>,
1270        batch: &mut DBBatch,
1271    ) {
1272        let db = self.db.read();
1273
1274        let prefix = self.cycle_history_cycle_prefix(cycle);
1275
1276        let mut serialized_value = Vec::new();
1277        self.cycle_info_serializer
1278            .opt_hash_ser
1279            .serialize(&value, &mut serialized_value)
1280            .expect(CYCLE_HISTORY_SER_ERROR);
1281
1282        db.put_or_update_entry_value(
1283            batch,
1284            final_state_hash_snapshot_key!(prefix),
1285            &serialized_value,
1286        );
1287    }
1288
1289    /// Helper function to put a the rng_seed for a given cycle
1290    fn put_cycle_history_rng_seed(&mut self, cycle: u64, value: BitVec<u8>, batch: &mut DBBatch) {
1291        let db = self.db.read();
1292
1293        let prefix = self.cycle_history_cycle_prefix(cycle);
1294
1295        let mut serialized_value = Vec::new();
1296        self.cycle_info_serializer
1297            .bitvec_ser
1298            .serialize(&value, &mut serialized_value)
1299            .expect(CYCLE_HISTORY_SER_ERROR);
1300
1301        self.rng_seed_cache = Some((cycle, value.clone()));
1302
1303        db.put_or_update_entry_value(batch, rng_seed_key!(prefix), &serialized_value);
1304    }
1305
1306    /// Internal function to put an entry for a given address in the cycle history
1307    fn put_cycle_history_address_entry(
1308        &self,
1309        cycle: u64,
1310        address: &Address,
1311        roll_count: Option<&u64>,
1312        production_stats: Option<&ProductionStats>,
1313        batch: &mut DBBatch,
1314    ) {
1315        let db = self.db.read();
1316
1317        let prefix = self.cycle_history_cycle_prefix(cycle);
1318
1319        // Roll count
1320        if let Some(0) = roll_count {
1321            db.delete_key(batch, roll_count_key!(prefix, address));
1322        } else if let Some(roll_count) = roll_count {
1323            let mut serialized_roll_count = Vec::new();
1324            self.cycle_info_serializer
1325                .u64_ser
1326                .serialize(roll_count, &mut serialized_roll_count)
1327                .expect(CYCLE_HISTORY_SER_ERROR);
1328            db.put_or_update_entry_value(
1329                batch,
1330                roll_count_key!(prefix, address),
1331                &serialized_roll_count,
1332            );
1333        }
1334
1335        // Production stats
1336        if let Some(production_stats) = production_stats {
1337            let mut serialized_prod_stats_fail = Vec::new();
1338            self.cycle_info_serializer
1339                .u64_ser
1340                .serialize(
1341                    &production_stats.block_failure_count,
1342                    &mut serialized_prod_stats_fail,
1343                )
1344                .expect(CYCLE_HISTORY_SER_ERROR);
1345            db.put_or_update_entry_value(
1346                batch,
1347                prod_stats_fail_key!(prefix, address),
1348                &serialized_prod_stats_fail,
1349            );
1350
1351            // Production stats success
1352            let mut serialized_prod_stats_success = Vec::new();
1353            self.cycle_info_serializer
1354                .u64_ser
1355                .serialize(
1356                    &production_stats.block_success_count,
1357                    &mut serialized_prod_stats_success,
1358                )
1359                .expect(CYCLE_HISTORY_SER_ERROR);
1360            db.put_or_update_entry_value(
1361                batch,
1362                prod_stats_success_key!(prefix, address),
1363                &serialized_prod_stats_success,
1364            );
1365        }
1366    }
1367
1368    /// Internal function to put an entry
1369    pub fn put_deferred_credits_entry(
1370        &self,
1371        slot: &Slot,
1372        address: &Address,
1373        amount: &Amount,
1374        batch: &mut DBBatch,
1375    ) {
1376        let db = self.db.read();
1377
1378        let mut serialized_key = Vec::new();
1379        serialized_key.extend_from_slice(&slot.to_bytes_key());
1380        self.credits_serializer
1381            .address_ser
1382            .serialize(address, &mut serialized_key)
1383            .expect(DEFERRED_CREDITS_SER_ERROR);
1384
1385        if amount.is_zero() {
1386            db.delete_key(batch, deferred_credits_key!(serialized_key));
1387        } else {
1388            let mut serialized_amount = Vec::new();
1389            self.credits_serializer
1390                .amount_ser
1391                .serialize(amount, &mut serialized_amount)
1392                .expect(DEFERRED_CREDITS_SER_ERROR);
1393
1394            db.put_or_update_entry_value(
1395                batch,
1396                deferred_credits_key!(serialized_key),
1397                &serialized_amount,
1398            );
1399        }
1400    }
1401}
1402
1403/// Helpers for key and value management
1404impl PoSFinalState {
1405    /// Helper function to construct the key prefix associated with a given cycle
1406    fn cycle_history_cycle_prefix(&self, cycle: u64) -> Vec<u8> {
1407        let mut serialized_key = Vec::new();
1408        serialized_key.extend_from_slice(CYCLE_HISTORY_PREFIX.as_bytes());
1409        serialized_key.extend_from_slice(&cycle.to_be_bytes());
1410        serialized_key
1411    }
1412
1413    /// Deserializes the key and value, useful after bootstrap
1414    pub fn is_cycle_history_key_value_valid(
1415        &self,
1416        serialized_key: &[u8],
1417        serialized_value: &[u8],
1418    ) -> bool {
1419        if !serialized_key.starts_with(CYCLE_HISTORY_PREFIX.as_bytes()) {
1420            return false;
1421        }
1422
1423        // deserialize the cycle
1424        let rest_key = &serialized_key[CYCLE_HISTORY_PREFIX.len()..];
1425        let Some((rest_key, cycle)) = buf_to_array_ctr(rest_key, |v| u64::from_be_bytes(*v)) else {
1426            return false;
1427        };
1428
1429        if rest_key.is_empty() {
1430            return false;
1431        }
1432
1433        let slots_per_cycle = self.slots_per_cycle();
1434
1435        match rest_key[0] {
1436            COMPLETE_IDENT => {
1437                if rest_key.len() != 1 {
1438                    return false;
1439                }
1440                if serialized_value.len() != 1 {
1441                    return false;
1442                }
1443                if serialized_value[0] > 1 {
1444                    return false;
1445                }
1446                // A completed cycle must have an RNG seed of exactly slots_per_cycle bits.
1447                if serialized_value[0] == 1 {
1448                    let prefix = self.cycle_history_cycle_prefix(cycle);
1449                    let Ok(Some(serialized_rng_seed)) =
1450                        self.db.read().get_cf(STATE_CF, rng_seed_key!(prefix))
1451                    else {
1452                        return false;
1453                    };
1454                    let Ok((rest, rng_seed)) =
1455                        self.cycle_info_deserializer
1456                            .bitvec_deser
1457                            .deserialize::<DeserializeError>(&serialized_rng_seed)
1458                    else {
1459                        return false;
1460                    };
1461                    if !rest.is_empty() || rng_seed.len() != slots_per_cycle {
1462                        return false;
1463                    }
1464                }
1465            }
1466            RNG_SEED_IDENT => {
1467                if rest_key.len() != 1 {
1468                    return false;
1469                }
1470                let Ok((rest_key, rng_seed)) = self
1471                    .cycle_info_deserializer
1472                    .bitvec_deser
1473                    .deserialize::<DeserializeError>(serialized_value)
1474                else {
1475                    return false;
1476                };
1477                if !rest_key.is_empty() {
1478                    return false;
1479                }
1480                // Seed length must never exceed a full cycle; exact length for complete
1481                // cycles is enforced when validating the COMPLETE flag above.
1482                if rng_seed.len() > slots_per_cycle {
1483                    return false;
1484                }
1485            }
1486            FINAL_STATE_HASH_SNAPSHOT_IDENT => {
1487                if rest_key.len() != 1 {
1488                    return false;
1489                }
1490                let Ok((rest_key, _final_state_hash)) = self
1491                    .cycle_info_deserializer
1492                    .opt_hash_deser
1493                    .deserialize::<DeserializeError>(serialized_value)
1494                else {
1495                    return false;
1496                };
1497                if !rest_key.is_empty() {
1498                    return false;
1499                }
1500            }
1501            ROLL_COUNT_IDENT => {
1502                let Ok((rest_key, _addr)): std::result::Result<
1503                    (&[u8], Address),
1504                    nom::Err<massa_serialization::DeserializeError<'_>>,
1505                > = self
1506                    .cycle_info_deserializer
1507                    .rolls_deser
1508                    .address_deserializer
1509                    .deserialize::<DeserializeError>(&rest_key[1..])
1510                else {
1511                    return false;
1512                };
1513                if !rest_key.is_empty() {
1514                    return false;
1515                }
1516                let Ok((rest_key, _addr)) = self
1517                    .cycle_info_deserializer
1518                    .rolls_deser
1519                    .u64_deserializer
1520                    .deserialize::<DeserializeError>(serialized_value)
1521                else {
1522                    return false;
1523                };
1524                if !rest_key.is_empty() {
1525                    return false;
1526                }
1527            }
1528            PROD_STATS_IDENT => {
1529                let Ok((rest_key, _addr)): std::result::Result<
1530                    (&[u8], Address),
1531                    nom::Err<massa_serialization::DeserializeError<'_>>,
1532                > = self
1533                    .cycle_info_deserializer
1534                    .rolls_deser
1535                    .address_deserializer
1536                    .deserialize::<DeserializeError>(&rest_key[1..])
1537                else {
1538                    return false;
1539                };
1540                if rest_key.len() != 1 {
1541                    return false;
1542                }
1543
1544                match rest_key[0] {
1545                    PROD_STATS_FAIL_IDENT => {
1546                        let Ok((rest_key, _fail)) = self
1547                            .cycle_info_deserializer
1548                            .production_stats_deser
1549                            .u64_deserializer
1550                            .deserialize::<DeserializeError>(serialized_value)
1551                        else {
1552                            return false;
1553                        };
1554                        if !rest_key.is_empty() {
1555                            return false;
1556                        }
1557                    }
1558                    PROD_STATS_SUCCESS_IDENT => {
1559                        let Ok((rest_key, _success)) = self
1560                            .cycle_info_deserializer
1561                            .production_stats_deser
1562                            .u64_deserializer
1563                            .deserialize::<DeserializeError>(serialized_value)
1564                        else {
1565                            return false;
1566                        };
1567                        if !rest_key.is_empty() {
1568                            return false;
1569                        }
1570                    }
1571                    _ => {
1572                        return false;
1573                    }
1574                }
1575            }
1576            _ => {
1577                return false;
1578            }
1579        }
1580
1581        true
1582    }
1583
1584    /// Deserializes the key and value, useful after bootstrap
1585    pub fn is_deferred_credits_key_value_valid(
1586        &self,
1587        serialized_key: &[u8],
1588        serialized_value: &[u8],
1589    ) -> bool {
1590        if !serialized_key.starts_with(DEFERRED_CREDITS_PREFIX.as_bytes()) {
1591            return false;
1592        }
1593
1594        // deserialize the slot
1595        let rest_key = &serialized_key[DEFERRED_CREDITS_PREFIX.len()..];
1596        let Some((rest_key, _slot)) = buf_to_array_ctr(rest_key, Slot::from_bytes_key) else {
1597            return false;
1598        };
1599
1600        let Ok((rest_key, _addr)): std::result::Result<
1601            (&[u8], Address),
1602            nom::Err<massa_serialization::DeserializeError<'_>>,
1603        > = self
1604            .credits_deserializer
1605            .address_deserializer
1606            .deserialize::<DeserializeError>(rest_key)
1607        else {
1608            return false;
1609        };
1610        if !rest_key.is_empty() {
1611            return false;
1612        }
1613
1614        let Ok((rest_key, _amount)) = self
1615            .credits_deserializer
1616            .amount_deserializer
1617            .deserialize::<DeserializeError>(serialized_value)
1618        else {
1619            return false;
1620        };
1621        if !rest_key.is_empty() {
1622            return false;
1623        }
1624
1625        true
1626    }
1627}
1628
1629/// Helpers for testing
1630#[cfg(feature = "test-exports")]
1631impl PoSFinalState {
1632    /// Queries all the deferred credits in the database
1633    pub fn get_deferred_credits(&self) -> DeferredCredits {
1634        let db = self.db.read();
1635
1636        let mut deferred_credits = DeferredCredits::new();
1637
1638        for (serialized_key, serialized_value) in
1639            db.prefix_iterator_cf(STATE_CF, DEFERRED_CREDITS_PREFIX.as_bytes())
1640        {
1641            if !serialized_key.starts_with(DEFERRED_CREDITS_PREFIX.as_bytes()) {
1642                break;
1643            }
1644
1645            // deserialize the slot
1646            let rest_key = &serialized_key[DEFERRED_CREDITS_PREFIX.len()..];
1647            let (rest_key, slot) = buf_to_array_ctr(rest_key, Slot::from_bytes_key)
1648                .expect(DEFERRED_CREDITS_DESER_ERROR);
1649
1650            let (_, address) = self
1651                .credits_deserializer
1652                .address_deserializer
1653                .deserialize::<DeserializeError>(rest_key)
1654                .expect(DEFERRED_CREDITS_DESER_ERROR);
1655
1656            let (_, amount) = self
1657                .credits_deserializer
1658                .amount_deserializer
1659                .deserialize::<DeserializeError>(&serialized_value)
1660                .expect(DEFERRED_CREDITS_DESER_ERROR);
1661
1662            deferred_credits.insert(slot, address, amount);
1663        }
1664        deferred_credits
1665    }
1666}
1667
1668#[cfg(test)]
1669mod tests {
1670    use super::*;
1671
1672    use std::collections::HashMap;
1673    use std::str::FromStr;
1674    use std::sync::Arc;
1675
1676    use assert_matches::assert_matches;
1677    use bitvec::prelude::*;
1678    use parking_lot::RwLock;
1679    use tempfile::TempDir;
1680
1681    use crate::MockSelectorController;
1682
1683    use massa_db_exports::{MassaDBConfig, MassaDBController};
1684    use massa_db_worker::MassaDB;
1685    use massa_models::config::constants::{
1686        MAX_DEFERRED_CREDITS_LENGTH, MAX_PRODUCTION_STATS_LENGTH, MAX_ROLLS_COUNT_LENGTH,
1687        POS_SAVED_CYCLES,
1688    };
1689    use massa_signature::KeyPair;
1690
1691    // This test checks that the initial deferred credits are loaded correctly
1692    #[test]
1693    fn test_initial_deferred_credits_loading() {
1694        let initial_deferred_credits_file = tempfile::NamedTempFile::new()
1695            .expect("could not create temporary initial deferred credits file");
1696        // write down some deferred credits
1697        let deferred_credits_file_contents = "{
1698            \"AU12pAcVUzsgUBJHaYSAtDKVTYnUT9NorBDjoDovMfAFTLFa16MNa\": [
1699                {
1700                    \"slot\": {\"period\": 3, \"thread\": 0},
1701                    \"amount\": \"5.01\"
1702                },
1703                {
1704                    \"slot\": {\"period\": 4, \"thread\": 1},
1705                    \"amount\": \"6.0\"
1706                },
1707                {
1708                    \"slot\": {\"period\": 255, \"thread\": 0},
1709                    \"amount\": \"5.01\"
1710                },
1711                {
1712                    \"slot\": {\"period\": 256, \"thread\": 0},
1713                    \"amount\": \"6.0\"
1714                }
1715            ],
1716            \"AU1wN8rn4SkwYSTDF3dHFY4U28KtsqKL1NnEjDZhHnHEy6cEQm53\": [
1717                {
1718                    \"slot\": {\"period\": 3, \"thread\": 0},
1719                    \"amount\": \"2.01\"
1720                }
1721            ]
1722        }";
1723        std::fs::write(
1724            initial_deferred_credits_file.path(),
1725            deferred_credits_file_contents.as_bytes(),
1726        )
1727        .expect("failed writing initial deferred credits file");
1728        let pos_config = PoSConfig {
1729            periods_per_cycle: 2,
1730            thread_count: 2,
1731            cycle_history_length: POS_SAVED_CYCLES,
1732            max_rolls_length: MAX_ROLLS_COUNT_LENGTH,
1733            max_production_stats_length: MAX_PRODUCTION_STATS_LENGTH,
1734            max_credit_length: MAX_DEFERRED_CREDITS_LENGTH,
1735            initial_deferred_credits_path: Some(initial_deferred_credits_file.path().to_path_buf()),
1736        };
1737        // initialize the database and pos_state
1738        let tempdir = tempfile::TempDir::new().expect("cannot create temp directory");
1739        let db_config = MassaDBConfig {
1740            path: tempdir.path().to_path_buf(),
1741            max_history_length: 10,
1742            max_final_state_elements_size: 100_000,
1743            max_versioning_elements_size: 100_000,
1744            thread_count: 2,
1745            max_ledger_backups: 10,
1746            enable_metrics: false,
1747        };
1748        let db = Arc::new(RwLock::new(
1749            Box::new(MassaDB::new(db_config)) as Box<dyn MassaDBController + 'static>
1750        ));
1751        let selector_controller = Box::new(MockSelectorController::new());
1752        let init_seed = Hash::compute_from(b"");
1753        let initial_seeds = vec![Hash::compute_from(init_seed.to_bytes()), init_seed];
1754        let cycle_info_deserializer = CycleInfoDeserializer::new(
1755            pos_config.max_rolls_length,
1756            pos_config.max_production_stats_length,
1757        );
1758        let mut pos_state = PoSFinalState {
1759            config: pos_config.clone(),
1760            db: db.clone(),
1761            cycle_history_cache: Default::default(),
1762            rng_seed_cache: None,
1763            selector: selector_controller,
1764            initial_rolls: Default::default(),
1765            initial_seeds,
1766            credits_serializer: DeferredCreditSerializer::new(),
1767            credits_deserializer: DeferredCreditDeserializer::new(pos_config.max_credit_length),
1768            cycle_info_serializer: CycleInfoSerializer::new(),
1769            cycle_info_deserializer,
1770        };
1771        let mut batch = DBBatch::new();
1772        // load initial deferred credits
1773        let mut ledger = massa_ledger_exports::MockLedgerController::new();
1774        ledger.expect_entry_exists().returning(|_| false);
1775        pos_state
1776            .load_initial_deferred_credits(&mut batch, &ledger)
1777            .expect("error while loading initial deferred credits");
1778        db.write().write_batch(batch, DBBatch::new(), None);
1779        let deferred_credits = pos_state.get_deferred_credits().credits;
1780        let addr1 =
1781            Address::from_str("AU12pAcVUzsgUBJHaYSAtDKVTYnUT9NorBDjoDovMfAFTLFa16MNa").unwrap();
1782        let a_a1_s3 = Amount::from_str("5.01").unwrap();
1783        let addr2 =
1784            Address::from_str("AU1wN8rn4SkwYSTDF3dHFY4U28KtsqKL1NnEjDZhHnHEy6cEQm53").unwrap();
1785        let a_a2_s3 = Amount::from_str("2.01").unwrap();
1786        let expected_credits = vec![
1787            (
1788                Slot::new(3, 0),
1789                vec![(addr1, a_a1_s3), (addr2, a_a2_s3)]
1790                    .into_iter()
1791                    .collect(),
1792            ),
1793            (
1794                Slot::new(4, 1),
1795                vec![(addr1, Amount::from_str("6.0").unwrap())]
1796                    .into_iter()
1797                    .collect(),
1798            ),
1799            (
1800                Slot::new(255, 0),
1801                vec![(addr1, Amount::from_str("5.01").unwrap())]
1802                    .into_iter()
1803                    .collect(),
1804            ),
1805            (
1806                Slot::new(256, 0),
1807                vec![(addr1, Amount::from_str("6.0").unwrap())]
1808                    .into_iter()
1809                    .collect(),
1810            ),
1811        ]
1812        .into_iter()
1813        .collect();
1814        assert_eq!(
1815            deferred_credits, expected_credits,
1816            "deferred credits not loaded correctly"
1817        );
1818        let credits_range_1 =
1819            pos_state.get_deferred_credits_range(Slot::new(4, 0)..Slot::new(4, 1), None);
1820        assert!(credits_range_1.is_empty());
1821        let credits_range_2 =
1822            pos_state.get_deferred_credits_range(Slot::new(2, 0)..Slot::new(3, 1), None);
1823        let expected_credits_range_2 = vec![(
1824            Slot::new(3, 0),
1825            vec![(addr1, a_a1_s3), (addr2, a_a2_s3)]
1826                .into_iter()
1827                .collect(),
1828        )]
1829        .into_iter()
1830        .collect();
1831        assert_eq!(credits_range_2.credits, expected_credits_range_2);
1832        let credits_range_3 =
1833            pos_state.get_deferred_credits_range(Slot::new(7, 0)..Slot::new(9, 5), None);
1834        assert!(credits_range_3.is_empty());
1835        let credits_range_4 =
1836            pos_state.get_deferred_credits_range(Slot::new(7, 0)..Slot::new(255, 1), None);
1837
1838        let a_a1_s255 = Amount::from_str("5.01").unwrap();
1839        let expected_credits_range_4 = vec![(
1840            Slot::new(255, 0),
1841            vec![(addr1, a_a1_s255)].into_iter().collect(),
1842        )]
1843        .into_iter()
1844        .collect();
1845        assert_eq!(credits_range_4.credits, expected_credits_range_4);
1846    }
1847
1848    // This test checks that the initial rolls are loaded correctly
1849    #[test]
1850    fn test_initial_rolls_loading() {
1851        let initial_deferred_credits_file =
1852            tempfile::NamedTempFile::new().expect("could not create temporary initial rolls file");
1853        let initial_rolls_file_0 =
1854            tempfile::NamedTempFile::new().expect("could not create temporary initial rolls file");
1855
1856        // write down some rolls info
1857        let rolls_file_contents_0 = "{}";
1858        std::fs::write(
1859            initial_rolls_file_0.path(),
1860            rolls_file_contents_0.as_bytes(),
1861        )
1862        .expect("failed writing initial rolls file 0");
1863        // write down some deferred credits
1864        let deferred_credits_file_contents = "{}";
1865        std::fs::write(
1866            initial_deferred_credits_file.path(),
1867            deferred_credits_file_contents.as_bytes(),
1868        )
1869        .expect("failed writing initial deferred credits file");
1870
1871        // initialize the database
1872        let tempdir = tempfile::TempDir::new().expect("cannot create temp directory");
1873        let db_config = MassaDBConfig {
1874            path: tempdir.path().to_path_buf(),
1875            max_history_length: 10,
1876            max_final_state_elements_size: 100,
1877            max_versioning_elements_size: 100,
1878            thread_count: 2,
1879            max_ledger_backups: 10,
1880            enable_metrics: false,
1881        };
1882        let db = Arc::new(RwLock::new(
1883            Box::new(MassaDB::new(db_config)) as Box<dyn MassaDBController + 'static>
1884        ));
1885        let selector_controller = Box::new(MockSelectorController::new());
1886
1887        let pos_config = PoSConfig {
1888            periods_per_cycle: 2,
1889            thread_count: 2,
1890            cycle_history_length: POS_SAVED_CYCLES,
1891            max_rolls_length: MAX_ROLLS_COUNT_LENGTH,
1892            max_production_stats_length: MAX_PRODUCTION_STATS_LENGTH,
1893            max_credit_length: MAX_DEFERRED_CREDITS_LENGTH,
1894            initial_deferred_credits_path: Some(initial_deferred_credits_file.path().to_path_buf()),
1895        };
1896
1897        let init_seed = "";
1898        let pos_state_0 = PoSFinalState::new(
1899            pos_config.clone(),
1900            init_seed,
1901            &initial_rolls_file_0.path().to_path_buf(),
1902            selector_controller,
1903            db.clone(),
1904        );
1905
1906        // Check ok with empty roll file
1907        assert!(pos_state_0.is_ok());
1908
1909        // Init a invalid roll file (invalid content)
1910        let initial_rolls_file_1 =
1911            tempfile::NamedTempFile::new().expect("could not create temporary initial rolls file");
1912        let data_1 = HashMap::from([("foo", "bar")]);
1913        let rolls_file_contents_1 = serde_json::to_string(&data_1).unwrap();
1914        // println!("rolls_file_contents_1: {}", rolls_file_contents_1);
1915        std::fs::write(
1916            initial_rolls_file_1.path(),
1917            rolls_file_contents_1.as_bytes(),
1918        )
1919        .expect("failed writing initial rolls file 1");
1920        let selector_controller = Box::new(MockSelectorController::new());
1921
1922        let pos_state_1 = PoSFinalState::new(
1923            pos_config.clone(),
1924            init_seed,
1925            &initial_rolls_file_1.path().to_path_buf(),
1926            selector_controller,
1927            db.clone(),
1928        );
1929
1930        // Check ko
1931        assert!(pos_state_1.is_err());
1932
1933        // Now check with valid data
1934
1935        let addr1_ = "AU12pAcVUzsgUBJHaYSAtDKVTYnUT9NorBDjoDovMfAFTLFa16MNa";
1936        let addr1 = Address::from_str(addr1_).unwrap();
1937        let roll1: u64 = 5;
1938        let addr2_ = "AU1wN8rn4SkwYSTDF3dHFY4U28KtsqKL1NnEjDZhHnHEy6cEQm53";
1939        let addr2 = Address::from_str(addr2_).unwrap();
1940        let roll2: u64 = 65529;
1941
1942        let initial_rolls_file_2 =
1943            tempfile::NamedTempFile::new().expect("could not create temporary initial rolls file");
1944        let data_2 = HashMap::from([(addr1_, roll1), (addr2_, roll2)]);
1945        let rolls_file_contents_2 = serde_json::to_string(&data_2).unwrap();
1946        std::fs::write(
1947            initial_rolls_file_2.path(),
1948            rolls_file_contents_2.as_bytes(),
1949        )
1950        .expect("failed writing initial rolls file 2");
1951        let selector_controller = Box::new(MockSelectorController::new());
1952
1953        let mut pos_state_2 = PoSFinalState::new(
1954            pos_config,
1955            init_seed,
1956            &initial_rolls_file_2.path().to_path_buf(),
1957            selector_controller,
1958            db.clone(),
1959        )
1960        .unwrap();
1961
1962        assert_eq!(pos_state_2.initial_rolls.get(&addr1), Some(&roll1));
1963        assert_eq!(pos_state_2.initial_rolls.get(&addr2), Some(&roll2));
1964        // Note: get_address_active_rolls (if not cycle -3) uses initial_rolls
1965        assert_eq!(pos_state_2.get_address_active_rolls(&addr1, 0), Some(roll1));
1966        // Note: get_all_active_rolls (if not cycle -3) uses initial_rolls
1967        assert_eq!(
1968            pos_state_2.get_all_active_rolls(0).get(&addr1),
1969            Some(&roll1)
1970        );
1971        assert_eq!(
1972            pos_state_2.get_all_active_rolls(0).get(&addr2),
1973            Some(&roll2)
1974        );
1975
1976        // Simulate some cycle with address 1 + decrease rolls and address 2 + increase rolls
1977        let roll_counts_c0 = BTreeMap::from([(addr1, roll1), (addr2, roll2)]);
1978        let roll_a1_c1 = roll1.checked_sub(1).unwrap();
1979        let roll_counts_c1 =
1980            BTreeMap::from([(addr1, roll_a1_c1), (addr2, roll2.checked_add(1).unwrap())]);
1981        let roll_counts_c2 = BTreeMap::from([
1982            (addr1, roll1.checked_sub(2).unwrap()),
1983            (addr2, roll2.checked_add(2).unwrap()),
1984        ]);
1985        let roll_a1_c3 = roll1.checked_sub(3).unwrap();
1986        let roll_a2_c3 = roll2.checked_add(3).unwrap();
1987        let roll_counts_c3 = BTreeMap::from([(addr1, roll_a1_c3), (addr2, roll_a2_c3)]);
1988        let roll_a1_c4 = roll1.checked_sub(4).unwrap();
1989        let roll_a2_c4 = roll2.checked_add(4).unwrap();
1990        let roll_counts_c4 = BTreeMap::from([(addr1, roll_a1_c4), (addr2, roll_a2_c4)]);
1991        let cycle_info_0 = CycleInfo::new(
1992            0,
1993            Default::default(),
1994            roll_counts_c0,
1995            Default::default(),
1996            Default::default(),
1997        );
1998        let cycle_info_1 = CycleInfo {
1999            cycle: 1,
2000            roll_counts: roll_counts_c1.clone(),
2001            ..cycle_info_0.clone()
2002        };
2003        let cycle_info_2 = CycleInfo {
2004            cycle: 2,
2005            roll_counts: roll_counts_c2,
2006            ..cycle_info_0.clone()
2007        };
2008        let cycle_info_3 = CycleInfo {
2009            cycle: 3,
2010            roll_counts: roll_counts_c3,
2011            ..cycle_info_0.clone()
2012        };
2013        let cycle_info_4 = CycleInfo {
2014            cycle: 4,
2015            roll_counts: roll_counts_c4,
2016            ..cycle_info_0.clone()
2017        };
2018
2019        let mut batch = DBBatch::new();
2020        pos_state_2.put_new_cycle_info(&cycle_info_0, &mut batch);
2021        pos_state_2.put_new_cycle_info(&cycle_info_1, &mut batch);
2022        pos_state_2.put_new_cycle_info(&cycle_info_2, &mut batch);
2023        pos_state_2.put_new_cycle_info(&cycle_info_3, &mut batch);
2024        pos_state_2.put_new_cycle_info(&cycle_info_4, &mut batch);
2025        pos_state_2
2026            .db
2027            .write()
2028            .write_batch(batch, DBBatch::new(), None);
2029
2030        assert_eq!(
2031            pos_state_2.get_address_active_rolls(&addr1, 4),
2032            Some(roll_a1_c1)
2033        );
2034        assert_eq!(
2035            pos_state_2.get_address_active_rolls(&addr1, 4 + 3 + 1),
2036            None
2037        );
2038        assert_eq!(pos_state_2.get_address_active_rolls(&addr1, 19), None);
2039
2040        let rolls_1 = pos_state_2.get_rolls_for(&addr1);
2041        assert_eq!(rolls_1, roll_a1_c4);
2042        let rolls_2 = pos_state_2.get_rolls_for(&addr2);
2043        assert_eq!(rolls_2, roll_a2_c4);
2044
2045        // Will fetch at cycle - 3
2046        let active_rolls = pos_state_2.get_all_active_rolls(4);
2047        assert_eq!(active_rolls, roll_counts_c1);
2048    }
2049
2050    // This test checks that the recompute_pos_cache function recovers every cycle and does return correctly.
2051    // The test example is chosen to have the cycles overlap a power of 2, to check that the order of cycles in the DB
2052    // (lexicographical over bytes) is the same as the order of cycles in the cache (numerical).
2053    // If this is not handled properly, the node hangs as explained here: https://github.com/massalabs/massa/issues/4101
2054    #[test]
2055    fn test_pos_cache_recomputation() {
2056        let pos_config = PoSConfig {
2057            periods_per_cycle: 2,
2058            thread_count: 2,
2059            cycle_history_length: POS_SAVED_CYCLES,
2060            max_rolls_length: MAX_ROLLS_COUNT_LENGTH,
2061            max_production_stats_length: MAX_PRODUCTION_STATS_LENGTH,
2062            max_credit_length: MAX_DEFERRED_CREDITS_LENGTH,
2063            initial_deferred_credits_path: None,
2064        };
2065
2066        // initialize the database and pos_state
2067        let tempdir = TempDir::new().expect("cannot create temp directory");
2068        let db_config = MassaDBConfig {
2069            path: tempdir.path().to_path_buf(),
2070            max_history_length: 10,
2071            max_final_state_elements_size: 100_000,
2072            max_versioning_elements_size: 100_000,
2073            thread_count: 2,
2074            max_ledger_backups: 10,
2075            enable_metrics: false,
2076        };
2077        let db = Arc::new(RwLock::new(
2078            Box::new(MassaDB::new(db_config)) as Box<dyn MassaDBController + 'static>
2079        ));
2080        let selector_controller = Box::new(MockSelectorController::new());
2081        let init_seed = Hash::compute_from(b"");
2082        let initial_seeds = vec![Hash::compute_from(init_seed.to_bytes()), init_seed];
2083
2084        let cycle_info_deserializer = CycleInfoDeserializer::new(
2085            pos_config.max_rolls_length,
2086            pos_config.max_production_stats_length,
2087        );
2088
2089        let mut pos_state = PoSFinalState {
2090            config: pos_config.clone(),
2091            db: db.clone(),
2092            cycle_history_cache: Default::default(),
2093            rng_seed_cache: None,
2094            selector: selector_controller,
2095            initial_rolls: Default::default(),
2096            initial_seeds,
2097            credits_serializer: DeferredCreditSerializer::new(),
2098            credits_deserializer: DeferredCreditDeserializer::new(pos_config.max_credit_length),
2099            cycle_info_serializer: CycleInfoSerializer::new(),
2100            cycle_info_deserializer,
2101        };
2102
2103        // Populate the disk with some cycle infos
2104        let mut cycle_infos = Vec::new();
2105        for cycle in 509..516 {
2106            cycle_infos.push(CycleInfo::new(
2107                cycle,
2108                Default::default(),
2109                Default::default(),
2110                Default::default(),
2111                Default::default(),
2112            ));
2113        }
2114
2115        let mut batch = DBBatch::new();
2116        pos_state.put_new_cycle_info(&cycle_infos[0], &mut batch);
2117        pos_state.put_new_cycle_info(&cycle_infos[1], &mut batch);
2118        pos_state.put_new_cycle_info(&cycle_infos[2], &mut batch);
2119        pos_state.put_new_cycle_info(&cycle_infos[3], &mut batch);
2120        pos_state.put_new_cycle_info(&cycle_infos[4], &mut batch);
2121        pos_state.put_new_cycle_info(&cycle_infos[5], &mut batch);
2122        pos_state.put_new_cycle_info(&cycle_infos[6], &mut batch);
2123
2124        pos_state
2125            .db
2126            .write()
2127            .write_batch(batch, DBBatch::new(), None);
2128
2129        // Recompute the cache, and assert we do not miss any data
2130        // We .clear() the cache explicitly, even though we do not need to, to make sure the recomputation works
2131        pos_state.cycle_history_cache.clear();
2132        pos_state.recompute_pos_state_caches();
2133
2134        // Assert that the cache contains the expected cycles
2135        assert_eq!(
2136            pos_state.cycle_history_cache.len(),
2137            cycle_infos.len(),
2138            "Cycle history len does not match"
2139        );
2140
2141        for ((cycle_from_history, _), cycle) in
2142            pos_state.cycle_history_cache.iter().zip(cycle_infos.iter())
2143        {
2144            assert_eq!(
2145                *cycle_from_history, cycle.cycle,
2146                "Cycle number does not match"
2147            );
2148        }
2149    }
2150
2151    // This test aims to check that the basic workflow of apply changes to the PoS state works.
2152    #[test]
2153    fn test_pos_final_state_hash_computation() {
2154        let pos_config = PoSConfig {
2155            // slots_per_cycle = 4*2 = 8 so the seed bits accumulated below stay within bounds
2156            periods_per_cycle: 4,
2157            thread_count: 2,
2158            cycle_history_length: POS_SAVED_CYCLES,
2159            max_rolls_length: MAX_ROLLS_COUNT_LENGTH,
2160            max_production_stats_length: MAX_PRODUCTION_STATS_LENGTH,
2161            max_credit_length: MAX_DEFERRED_CREDITS_LENGTH,
2162            initial_deferred_credits_path: None,
2163        };
2164
2165        // initialize the database and pos_state
2166        let tempdir = TempDir::new().expect("cannot create temp directory");
2167        let db_config = MassaDBConfig {
2168            path: tempdir.path().to_path_buf(),
2169            max_history_length: 10,
2170            max_final_state_elements_size: 100_000,
2171            max_versioning_elements_size: 100_000,
2172            thread_count: 2,
2173            max_ledger_backups: 10,
2174            enable_metrics: false,
2175        };
2176        let db = Arc::new(RwLock::new(
2177            Box::new(MassaDB::new(db_config)) as Box<dyn MassaDBController + 'static>
2178        ));
2179        let selector_controller = Box::new(MockSelectorController::new());
2180        let init_seed = Hash::compute_from(b"");
2181        let initial_seeds = vec![Hash::compute_from(init_seed.to_bytes()), init_seed];
2182
2183        let cycle_info_deserializer = CycleInfoDeserializer::new(
2184            pos_config.max_rolls_length,
2185            pos_config.max_production_stats_length,
2186        );
2187
2188        let mut pos_state = PoSFinalState {
2189            config: pos_config.clone(),
2190            db: db.clone(),
2191            cycle_history_cache: Default::default(),
2192            rng_seed_cache: None,
2193            selector: selector_controller,
2194            initial_rolls: Default::default(),
2195            initial_seeds,
2196            credits_serializer: DeferredCreditSerializer::new(),
2197            credits_deserializer: DeferredCreditDeserializer::new(pos_config.max_credit_length),
2198            cycle_info_serializer: CycleInfoSerializer::new(),
2199            cycle_info_deserializer,
2200        };
2201
2202        pos_state.recompute_pos_state_caches();
2203
2204        let mut batch = DBBatch::new();
2205        pos_state.create_initial_cycle(&mut batch);
2206        db.write()
2207            .write_batch(batch, Default::default(), Some(Slot::new(0, 0)));
2208
2209        // add changes
2210        let addr = Address::from_public_key(&KeyPair::generate(0).unwrap().get_public_key());
2211        let mut roll_changes = PreHashMap::default();
2212        roll_changes.insert(addr, 10);
2213        let mut production_stats = PreHashMap::default();
2214        production_stats.insert(
2215            addr,
2216            ProductionStats {
2217                block_success_count: 4,
2218                block_failure_count: 0,
2219            },
2220        );
2221        let changes = PoSChanges {
2222            seed_bits: bitvec![u8, Lsb0; 0, 1],
2223            roll_changes: roll_changes.clone(),
2224            production_stats: production_stats.clone(),
2225            deferred_credits: DeferredCredits::new(),
2226        };
2227
2228        let mut batch = DBBatch::new();
2229        pos_state
2230            .apply_changes_to_batch(changes, Slot::new(0, 0), false, &mut batch)
2231            .unwrap();
2232        db.write()
2233            .write_batch(batch, Default::default(), Some(Slot::new(0, 0)));
2234
2235        // update changes once
2236        roll_changes.clear();
2237        roll_changes.insert(addr, 20);
2238        production_stats.clear();
2239        production_stats.insert(
2240            addr,
2241            ProductionStats {
2242                block_success_count: 4,
2243                block_failure_count: 6,
2244            },
2245        );
2246        let changes = PoSChanges {
2247            seed_bits: bitvec![u8, Lsb0; 1, 0],
2248            roll_changes: roll_changes.clone(),
2249            production_stats: production_stats.clone(),
2250            deferred_credits: DeferredCredits::new(),
2251        };
2252
2253        let mut batch = DBBatch::new();
2254        pos_state
2255            .apply_changes_to_batch(changes, Slot::new(0, 1), false, &mut batch)
2256            .unwrap();
2257        db.write()
2258            .write_batch(batch, Default::default(), Some(Slot::new(0, 1)));
2259
2260        // update changes twice
2261        roll_changes.clear();
2262        roll_changes.insert(addr, 0);
2263        production_stats.clear();
2264        production_stats.insert(
2265            addr,
2266            ProductionStats {
2267                block_success_count: 4,
2268                block_failure_count: 12,
2269            },
2270        );
2271
2272        let changes = PoSChanges {
2273            seed_bits: bitvec![u8, Lsb0; 0, 1],
2274            roll_changes,
2275            production_stats,
2276            deferred_credits: DeferredCredits::new(),
2277        };
2278
2279        let mut batch = DBBatch::new();
2280        pos_state
2281            .apply_changes_to_batch(changes, Slot::new(1, 0), false, &mut batch)
2282            .unwrap();
2283        db.write()
2284            .write_batch(batch, Default::default(), Some(Slot::new(1, 0)));
2285
2286        let cycles = pos_state.get_cycle_history_cycles();
2287        assert_eq!(cycles.len(), 1, "wrong number of cycles");
2288        assert_eq!(cycles[0].0, 0, "cycle should be the 1st one");
2289        assert!(!cycles[0].1, "cycle should not be complete yet");
2290
2291        let cycle_info_a = pos_state.get_cycle_info(0).unwrap();
2292
2293        let mut prod_stats = HashMap::default();
2294        prod_stats.insert(
2295            addr,
2296            ProductionStats {
2297                block_success_count: 12,
2298                block_failure_count: 18,
2299            },
2300        );
2301
2302        let cycle_info_b = CycleInfo::new(
2303            0,
2304            false,
2305            BTreeMap::default(),
2306            bitvec![u8, Lsb0; 0, 0, 0, 1, 1, 0, 0, 1],
2307            prod_stats,
2308        );
2309
2310        assert_eq!(cycle_info_a, cycle_info_b, "cycle_info mismatch");
2311    }
2312
2313    #[test]
2314    fn test_feed_selector() {
2315        let initial_deferred_credits_file =
2316            tempfile::NamedTempFile::new().expect("could not create temporary initial rolls file");
2317
2318        let initial_rolls_file_0 =
2319            tempfile::NamedTempFile::new().expect("could not create temporary initial rolls file");
2320
2321        // write down some rolls info
2322        let rolls_file_contents_0 = "{}";
2323        std::fs::write(
2324            initial_rolls_file_0.path(),
2325            rolls_file_contents_0.as_bytes(),
2326        )
2327        .expect("failed writing initial rolls file 0");
2328
2329        // write down some deferred credits
2330        let deferred_credits_file_contents = "{}";
2331        std::fs::write(
2332            initial_deferred_credits_file.path(),
2333            deferred_credits_file_contents.as_bytes(),
2334        )
2335        .expect("failed writing initial deferred credits file");
2336
2337        // initialize the database
2338        let tempdir = tempfile::TempDir::new().expect("cannot create temp directory");
2339        let db_config = MassaDBConfig {
2340            path: tempdir.path().to_path_buf(),
2341            max_history_length: 10,
2342            max_final_state_elements_size: 100,
2343            max_versioning_elements_size: 100,
2344            thread_count: 2,
2345            max_ledger_backups: 10,
2346            enable_metrics: false,
2347        };
2348        let db = Arc::new(RwLock::new(
2349            Box::new(MassaDB::new(db_config)) as Box<dyn MassaDBController + 'static>
2350        ));
2351        let selector_controller = Box::new(MockSelectorController::new());
2352
2353        let pos_config = PoSConfig {
2354            periods_per_cycle: 2,
2355            thread_count: 2,
2356            cycle_history_length: POS_SAVED_CYCLES,
2357            max_rolls_length: MAX_ROLLS_COUNT_LENGTH,
2358            max_production_stats_length: MAX_PRODUCTION_STATS_LENGTH,
2359            max_credit_length: MAX_DEFERRED_CREDITS_LENGTH,
2360            initial_deferred_credits_path: Some(initial_deferred_credits_file.path().to_path_buf()),
2361        };
2362
2363        let init_seed = "";
2364        let mut pos_state_0 = PoSFinalState::new(
2365            pos_config,
2366            init_seed,
2367            &initial_rolls_file_0.path().to_path_buf(),
2368            selector_controller,
2369            db.clone(),
2370        )
2371        .unwrap();
2372
2373        let cycle_info_0 = CycleInfo::new(
2374            0,
2375            true,
2376            Default::default(),
2377            Default::default(),
2378            Default::default(),
2379        );
2380        let cycle_info_1 = CycleInfo {
2381            cycle: 1,
2382            ..cycle_info_0.clone()
2383        };
2384        let cycle_info_2 = CycleInfo {
2385            cycle: 2,
2386            ..cycle_info_0.clone()
2387        };
2388        let cycle_info_3 = CycleInfo {
2389            cycle: 3,
2390            ..cycle_info_0.clone()
2391        };
2392        let cycle_info_4 = CycleInfo {
2393            cycle: 4,
2394            complete: false,
2395            ..cycle_info_0.clone()
2396        };
2397
2398        let mut batch = DBBatch::new();
2399        pos_state_0.put_new_cycle_info(&cycle_info_0, &mut batch);
2400        pos_state_0.put_new_cycle_info(&cycle_info_1, &mut batch);
2401        pos_state_0.put_new_cycle_info(&cycle_info_2, &mut batch);
2402        pos_state_0.put_new_cycle_info(&cycle_info_3, &mut batch);
2403        pos_state_0.put_new_cycle_info(&cycle_info_4, &mut batch);
2404        pos_state_0
2405            .db
2406            .write()
2407            .write_batch(batch, DBBatch::new(), None);
2408
2409        // Test feed selector with unfinished cycle
2410        assert_matches!(
2411            pos_state_0.feed_selector(4 + 3),
2412            Err(PosError::CycleUnfinished(4))
2413        );
2414
2415        // F100: complete cycles without a final state hash snapshot must error, not panic
2416        assert_matches!(
2417            pos_state_0.feed_selector(4),
2418            Err(PosError::ContainerInconsistency(_))
2419        );
2420        assert_matches!(
2421            pos_state_0.validate_selector_history(),
2422            Err(PosError::ContainerInconsistency(_))
2423        );
2424    }
2425
2426    #[test]
2427    fn test_feed_selector_2() {
2428        let initial_deferred_credits_file =
2429            tempfile::NamedTempFile::new().expect("could not create temporary initial rolls file");
2430
2431        let initial_rolls_file_0 =
2432            tempfile::NamedTempFile::new().expect("could not create temporary initial rolls file");
2433
2434        // write down some rolls info
2435        let rolls_file_contents_0 = "{}";
2436        std::fs::write(
2437            initial_rolls_file_0.path(),
2438            rolls_file_contents_0.as_bytes(),
2439        )
2440        .expect("failed writing initial rolls file 0");
2441
2442        // write down some deferred credits
2443        let deferred_credits_file_contents = "{}";
2444        std::fs::write(
2445            initial_deferred_credits_file.path(),
2446            deferred_credits_file_contents.as_bytes(),
2447        )
2448        .expect("failed writing initial deferred credits file");
2449
2450        // initialize the database
2451        let tempdir = tempfile::TempDir::new().expect("cannot create temp directory");
2452        let db_config = MassaDBConfig {
2453            path: tempdir.path().to_path_buf(),
2454            max_history_length: 10,
2455            thread_count: 2,
2456            max_final_state_elements_size: 100,
2457            max_versioning_elements_size: 100,
2458            max_ledger_backups: 10,
2459            enable_metrics: false,
2460        };
2461        let db = Arc::new(RwLock::new(
2462            Box::new(MassaDB::new(db_config)) as Box<dyn MassaDBController + 'static>
2463        ));
2464        let mut selector_controller = Box::new(MockSelectorController::new());
2465        selector_controller
2466            .expect_feed_cycle()
2467            .times(1)
2468            .returning(|_, _, _| Ok(()));
2469
2470        let pos_config = PoSConfig {
2471            periods_per_cycle: 2,
2472            thread_count: 2,
2473            cycle_history_length: POS_SAVED_CYCLES,
2474            max_rolls_length: MAX_ROLLS_COUNT_LENGTH,
2475            max_production_stats_length: MAX_PRODUCTION_STATS_LENGTH,
2476            max_credit_length: MAX_DEFERRED_CREDITS_LENGTH,
2477            initial_deferred_credits_path: Some(initial_deferred_credits_file.path().to_path_buf()),
2478        };
2479
2480        let init_seed = "";
2481        let mut pos_state_0 = PoSFinalState::new(
2482            pos_config,
2483            init_seed,
2484            &initial_rolls_file_0.path().to_path_buf(),
2485            selector_controller,
2486            db.clone(),
2487        )
2488        .unwrap();
2489
2490        let cycle_info_0 = CycleInfo::new(
2491            0,
2492            true,
2493            Default::default(),
2494            Default::default(),
2495            Default::default(),
2496        );
2497        let cycle_info_1 = CycleInfo {
2498            cycle: 1,
2499            ..cycle_info_0.clone()
2500        };
2501        let cycle_info_2 = CycleInfo {
2502            cycle: 2,
2503            ..cycle_info_0.clone()
2504        };
2505        let cycle_info_3 = CycleInfo {
2506            cycle: 3,
2507            ..cycle_info_0.clone()
2508        };
2509        let cycle_info_4 = CycleInfo {
2510            cycle: 4,
2511            complete: false,
2512            ..cycle_info_0.clone()
2513        };
2514
2515        let mut batch = DBBatch::new();
2516        pos_state_0.put_new_cycle_info(&cycle_info_0, &mut batch);
2517        pos_state_0.put_new_cycle_info(&cycle_info_1, &mut batch);
2518        pos_state_0.put_new_cycle_info(&cycle_info_2, &mut batch);
2519        pos_state_0.put_new_cycle_info(&cycle_info_3, &mut batch);
2520        pos_state_0.put_new_cycle_info(&cycle_info_4, &mut batch);
2521        pos_state_0
2522            .db
2523            .write()
2524            .write_batch(batch, DBBatch::new(), None);
2525
2526        // Note: by using cycle 2, feed_selector will use initial_rolls & initial_seeds
2527        let _ = pos_state_0.feed_selector(2);
2528    }
2529
2530    /// Oversized RNG seeds must be rejected by DB key/value validation (bootstrap/DoS hardening).
2531    #[test]
2532    fn test_rng_seed_validation_rejects_oversized_seed() {
2533        let pos_config = PoSConfig {
2534            periods_per_cycle: 2,
2535            thread_count: 2, // slots_per_cycle = 4
2536            cycle_history_length: POS_SAVED_CYCLES,
2537            max_rolls_length: MAX_ROLLS_COUNT_LENGTH,
2538            max_production_stats_length: MAX_PRODUCTION_STATS_LENGTH,
2539            max_credit_length: MAX_DEFERRED_CREDITS_LENGTH,
2540            initial_deferred_credits_path: None,
2541        };
2542
2543        let tempdir = TempDir::new().expect("cannot create temp directory");
2544        let db_config = MassaDBConfig {
2545            path: tempdir.path().to_path_buf(),
2546            max_history_length: 10,
2547            max_final_state_elements_size: 100_000,
2548            max_versioning_elements_size: 100_000,
2549            thread_count: 2,
2550            max_ledger_backups: 10,
2551            enable_metrics: false,
2552        };
2553        let db = Arc::new(RwLock::new(
2554            Box::new(MassaDB::new(db_config)) as Box<dyn MassaDBController + 'static>
2555        ));
2556        let selector_controller = Box::new(MockSelectorController::new());
2557        let init_seed = Hash::compute_from(b"");
2558        let initial_seeds = vec![Hash::compute_from(init_seed.to_bytes()), init_seed];
2559
2560        let cycle_info_deserializer = CycleInfoDeserializer::new(
2561            pos_config.max_rolls_length,
2562            pos_config.max_production_stats_length,
2563        );
2564
2565        let mut pos_state = PoSFinalState {
2566            config: pos_config.clone(),
2567            db: db.clone(),
2568            cycle_history_cache: Default::default(),
2569            rng_seed_cache: None,
2570            selector: selector_controller,
2571            initial_rolls: Default::default(),
2572            initial_seeds,
2573            credits_serializer: DeferredCreditSerializer::new(),
2574            credits_deserializer: DeferredCreditDeserializer::new(pos_config.max_credit_length),
2575            cycle_info_serializer: CycleInfoSerializer::new(),
2576            cycle_info_deserializer,
2577        };
2578
2579        let oversized = bitvec![u8, Lsb0; 0, 1, 0, 1, 0]; // 5 > 4
2580        let cycle_info = CycleInfo::new(
2581            0,
2582            false,
2583            BTreeMap::default(),
2584            oversized.clone(),
2585            PreHashMap::default(),
2586        );
2587        let mut batch = DBBatch::new();
2588        pos_state.put_new_cycle_info(&cycle_info, &mut batch);
2589        db.write().write_batch(batch, DBBatch::new(), None);
2590
2591        let prefix = pos_state.cycle_history_cycle_prefix(0);
2592        let key = rng_seed_key!(prefix);
2593        let mut serialized_value = Vec::new();
2594        pos_state
2595            .cycle_info_serializer
2596            .bitvec_ser
2597            .serialize(&oversized, &mut serialized_value)
2598            .unwrap();
2599
2600        assert!(
2601            !pos_state.is_cycle_history_key_value_valid(&key, &serialized_value),
2602            "oversized RNG seed must be rejected"
2603        );
2604
2605        // Completing a cycle with a short seed must also be rejected
2606        let short_seed = bitvec![u8, Lsb0; 0, 1];
2607        let mut batch = DBBatch::new();
2608        pos_state.put_cycle_history_rng_seed(0, short_seed, &mut batch);
2609        pos_state.put_cycle_history_complete(0, true, &mut batch);
2610        db.write().write_batch(batch, DBBatch::new(), None);
2611
2612        let complete_key = complete_key!(prefix);
2613        assert!(
2614            !pos_state.is_cycle_history_key_value_valid(&complete_key, &[1]),
2615            "complete cycle with wrong RNG seed length must be rejected"
2616        );
2617    }
2618
2619    /// A cycle history entry for cycle `u64::MAX` (corrupt DB or bad bootstrap peer)
2620    /// must not make the cycle scan loop forever.
2621    #[test]
2622    fn test_get_cycle_history_cycles_stops_at_max_cycle() {
2623        let pos_config = PoSConfig {
2624            periods_per_cycle: 2,
2625            thread_count: 2,
2626            cycle_history_length: POS_SAVED_CYCLES,
2627            max_rolls_length: MAX_ROLLS_COUNT_LENGTH,
2628            max_production_stats_length: MAX_PRODUCTION_STATS_LENGTH,
2629            max_credit_length: MAX_DEFERRED_CREDITS_LENGTH,
2630            initial_deferred_credits_path: None,
2631        };
2632
2633        let tempdir = TempDir::new().expect("cannot create temp directory");
2634        let db_config = MassaDBConfig {
2635            path: tempdir.path().to_path_buf(),
2636            max_history_length: 10,
2637            max_final_state_elements_size: 100_000,
2638            max_versioning_elements_size: 100_000,
2639            thread_count: 2,
2640            max_ledger_backups: 10,
2641            enable_metrics: false,
2642        };
2643        let db = Arc::new(RwLock::new(
2644            Box::new(MassaDB::new(db_config)) as Box<dyn MassaDBController + 'static>
2645        ));
2646        let init_seed = Hash::compute_from(b"");
2647        let initial_seeds = vec![Hash::compute_from(init_seed.to_bytes()), init_seed];
2648
2649        let cycle_info_deserializer = CycleInfoDeserializer::new(
2650            pos_config.max_rolls_length,
2651            pos_config.max_production_stats_length,
2652        );
2653
2654        let mut pos_state = PoSFinalState {
2655            config: pos_config.clone(),
2656            db: db.clone(),
2657            cycle_history_cache: Default::default(),
2658            rng_seed_cache: None,
2659            selector: Box::new(MockSelectorController::new()),
2660            initial_rolls: Default::default(),
2661            initial_seeds,
2662            credits_serializer: DeferredCreditSerializer::new(),
2663            credits_deserializer: DeferredCreditDeserializer::new(pos_config.max_credit_length),
2664            cycle_info_serializer: CycleInfoSerializer::new(),
2665            cycle_info_deserializer,
2666        };
2667
2668        let mut batch = DBBatch::new();
2669        pos_state.put_cycle_history_complete(0, false, &mut batch);
2670        pos_state.put_cycle_history_complete(u64::MAX, true, &mut batch);
2671        db.write().write_batch(batch, DBBatch::new(), None);
2672
2673        // before the fix, this call never returned
2674        assert_eq!(
2675            pos_state.get_cycle_history_cycles(),
2676            vec![(0, false), (u64::MAX, true)]
2677        );
2678
2679        // the gap between 0 and u64::MAX is rejected by the history validation
2680        assert_matches!(
2681            pos_state.validate_selector_history(),
2682            Err(PosError::ContainerInconsistency(_))
2683        );
2684    }
2685
2686    /// A cycle history with a gap (corrupt DB or bad bootstrap peer) is rejected,
2687    /// since `get_cycle_index` assumes consecutive cycles.
2688    #[test]
2689    fn test_validate_selector_history_rejects_non_consecutive_cycles() {
2690        let pos_config = PoSConfig {
2691            periods_per_cycle: 2,
2692            thread_count: 2,
2693            cycle_history_length: POS_SAVED_CYCLES,
2694            max_rolls_length: MAX_ROLLS_COUNT_LENGTH,
2695            max_production_stats_length: MAX_PRODUCTION_STATS_LENGTH,
2696            max_credit_length: MAX_DEFERRED_CREDITS_LENGTH,
2697            initial_deferred_credits_path: None,
2698        };
2699
2700        let tempdir = TempDir::new().expect("cannot create temp directory");
2701        let db_config = MassaDBConfig {
2702            path: tempdir.path().to_path_buf(),
2703            max_history_length: 10,
2704            max_final_state_elements_size: 100_000,
2705            max_versioning_elements_size: 100_000,
2706            thread_count: 2,
2707            max_ledger_backups: 10,
2708            enable_metrics: false,
2709        };
2710        let db = Arc::new(RwLock::new(
2711            Box::new(MassaDB::new(db_config)) as Box<dyn MassaDBController + 'static>
2712        ));
2713        let init_seed = Hash::compute_from(b"");
2714        let initial_seeds = vec![Hash::compute_from(init_seed.to_bytes()), init_seed];
2715
2716        let cycle_info_deserializer = CycleInfoDeserializer::new(
2717            pos_config.max_rolls_length,
2718            pos_config.max_production_stats_length,
2719        );
2720
2721        let mut pos_state = PoSFinalState {
2722            config: pos_config.clone(),
2723            db: db.clone(),
2724            cycle_history_cache: Default::default(),
2725            rng_seed_cache: None,
2726            selector: Box::new(MockSelectorController::new()),
2727            initial_rolls: Default::default(),
2728            initial_seeds,
2729            credits_serializer: DeferredCreditSerializer::new(),
2730            credits_deserializer: DeferredCreditDeserializer::new(pos_config.max_credit_length),
2731            cycle_info_serializer: CycleInfoSerializer::new(),
2732            cycle_info_deserializer,
2733        };
2734
2735        // incomplete cycles, so only the consecutiveness check applies
2736        let mut batch = DBBatch::new();
2737        pos_state.put_cycle_history_complete(3, false, &mut batch);
2738        pos_state.put_cycle_history_complete(4, false, &mut batch);
2739        db.write().write_batch(batch, DBBatch::new(), None);
2740        assert_matches!(pos_state.validate_selector_history(), Ok(()));
2741
2742        // cycle 5 is missing
2743        let mut batch = DBBatch::new();
2744        pos_state.put_cycle_history_complete(6, false, &mut batch);
2745        db.write().write_batch(batch, DBBatch::new(), None);
2746        assert_matches!(
2747            pos_state.validate_selector_history(),
2748            Err(PosError::ContainerInconsistency(_))
2749        );
2750    }
2751
2752    /// Cycle completion with a wrong seed length returns an error instead of panicking.
2753    #[test]
2754    fn test_apply_changes_returns_error_on_seed_length_mismatch() {
2755        let pos_config = PoSConfig {
2756            periods_per_cycle: 2,
2757            thread_count: 2, // slots_per_cycle = 4
2758            cycle_history_length: POS_SAVED_CYCLES,
2759            max_rolls_length: MAX_ROLLS_COUNT_LENGTH,
2760            max_production_stats_length: MAX_PRODUCTION_STATS_LENGTH,
2761            max_credit_length: MAX_DEFERRED_CREDITS_LENGTH,
2762            initial_deferred_credits_path: None,
2763        };
2764
2765        let tempdir = TempDir::new().expect("cannot create temp directory");
2766        let db_config = MassaDBConfig {
2767            path: tempdir.path().to_path_buf(),
2768            max_history_length: 10,
2769            max_final_state_elements_size: 100_000,
2770            max_versioning_elements_size: 100_000,
2771            thread_count: 2,
2772            max_ledger_backups: 10,
2773            enable_metrics: false,
2774        };
2775        let db = Arc::new(RwLock::new(
2776            Box::new(MassaDB::new(db_config)) as Box<dyn MassaDBController + 'static>
2777        ));
2778        let selector_controller = Box::new(MockSelectorController::new());
2779        let init_seed = Hash::compute_from(b"");
2780        let initial_seeds = vec![Hash::compute_from(init_seed.to_bytes()), init_seed];
2781
2782        let cycle_info_deserializer = CycleInfoDeserializer::new(
2783            pos_config.max_rolls_length,
2784            pos_config.max_production_stats_length,
2785        );
2786
2787        let mut pos_state = PoSFinalState {
2788            config: pos_config.clone(),
2789            db: db.clone(),
2790            cycle_history_cache: Default::default(),
2791            rng_seed_cache: None,
2792            selector: selector_controller,
2793            initial_rolls: Default::default(),
2794            initial_seeds,
2795            credits_serializer: DeferredCreditSerializer::new(),
2796            credits_deserializer: DeferredCreditDeserializer::new(pos_config.max_credit_length),
2797            cycle_info_serializer: CycleInfoSerializer::new(),
2798            cycle_info_deserializer,
2799        };
2800
2801        // Incomplete cycle with a short seed; completing it with one more bit yields length 3 ≠ 4.
2802        let mut batch = DBBatch::new();
2803        pos_state.put_new_cycle_info(
2804            &CycleInfo::new(
2805                0,
2806                false,
2807                BTreeMap::default(),
2808                bitvec![u8, Lsb0; 0, 1],
2809                PreHashMap::default(),
2810            ),
2811            &mut batch,
2812        );
2813        db.write()
2814            .write_batch(batch, Default::default(), Some(Slot::new(1, 0)));
2815        pos_state.recompute_pos_state_caches();
2816
2817        // Last slot of cycle 0 with periods_per_cycle=2, thread_count=2 is (1, 1).
2818        let changes = PoSChanges {
2819            seed_bits: bitvec![u8, Lsb0; 1],
2820            roll_changes: PreHashMap::default(),
2821            production_stats: PreHashMap::default(),
2822            deferred_credits: DeferredCredits::new(),
2823        };
2824        let mut batch = DBBatch::new();
2825        let err = pos_state
2826            .apply_changes_to_batch(changes, Slot::new(1, 1), false, &mut batch)
2827            .expect_err("seed length mismatch on cycle completion must be an error");
2828        assert_matches!(err, PosError::ContainerInconsistency(_));
2829    }
2830
2831    /// Completing a cycle during downtime interpolation must cap seed bits at slots_per_cycle
2832    /// when the existing seed already includes genesis padding.
2833    #[test]
2834    fn test_create_new_cycle_from_last_caps_seed_on_complete() {
2835        let pos_config = PoSConfig {
2836            periods_per_cycle: 2,
2837            thread_count: 2, // slots_per_cycle = 4
2838            cycle_history_length: POS_SAVED_CYCLES,
2839            max_rolls_length: MAX_ROLLS_COUNT_LENGTH,
2840            max_production_stats_length: MAX_PRODUCTION_STATS_LENGTH,
2841            max_credit_length: MAX_DEFERRED_CREDITS_LENGTH,
2842            initial_deferred_credits_path: None,
2843        };
2844
2845        let tempdir = TempDir::new().expect("cannot create temp directory");
2846        let db_config = MassaDBConfig {
2847            path: tempdir.path().to_path_buf(),
2848            max_history_length: 10,
2849            max_final_state_elements_size: 100_000,
2850            max_versioning_elements_size: 100_000,
2851            thread_count: 2,
2852            max_ledger_backups: 10,
2853            enable_metrics: false,
2854        };
2855        let db = Arc::new(RwLock::new(
2856            Box::new(MassaDB::new(db_config)) as Box<dyn MassaDBController + 'static>
2857        ));
2858        let selector_controller = Box::new(MockSelectorController::new());
2859        let init_seed = Hash::compute_from(b"");
2860        let initial_seeds = vec![Hash::compute_from(init_seed.to_bytes()), init_seed];
2861
2862        let cycle_info_deserializer = CycleInfoDeserializer::new(
2863            pos_config.max_rolls_length,
2864            pos_config.max_production_stats_length,
2865        );
2866
2867        let mut pos_state = PoSFinalState {
2868            config: pos_config.clone(),
2869            db: db.clone(),
2870            cycle_history_cache: Default::default(),
2871            rng_seed_cache: None,
2872            selector: selector_controller,
2873            initial_rolls: Default::default(),
2874            initial_seeds,
2875            credits_serializer: DeferredCreditSerializer::new(),
2876            credits_deserializer: DeferredCreditDeserializer::new(pos_config.max_credit_length),
2877            cycle_info_serializer: CycleInfoSerializer::new(),
2878            cycle_info_deserializer,
2879        };
2880
2881        // Same pattern as create_initial_cycle: thread_count padding bits already present.
2882        let last_cycle = CycleInfo::new(
2883            0,
2884            false,
2885            BTreeMap::default(),
2886            bitvec![u8, Lsb0; 0, 0],
2887            PreHashMap::default(),
2888        );
2889        let mut batch = DBBatch::new();
2890        pos_state
2891            .create_new_cycle_from_last(
2892                &last_cycle,
2893                Slot::new(0, 1),
2894                Slot::new(1, 1), // last slot of cycle 0
2895                &mut batch,
2896            )
2897            .expect("interpolation should cap seed length instead of overflowing");
2898        db.write()
2899            .write_batch(batch, Default::default(), Some(Slot::new(1, 1)));
2900
2901        let cycle_info = pos_state.get_cycle_info(0).expect("cycle 0 should exist");
2902        assert!(cycle_info.complete);
2903        assert_eq!(cycle_info.rng_seed.len(), 4);
2904    }
2905
2906    #[test]
2907    fn test_create_new_cycle_from_last_production_stats() {
2908        let pos_config = PoSConfig {
2909            periods_per_cycle: 2,
2910            thread_count: 2, // slots_per_cycle = 4
2911            cycle_history_length: POS_SAVED_CYCLES,
2912            max_rolls_length: MAX_ROLLS_COUNT_LENGTH,
2913            max_production_stats_length: MAX_PRODUCTION_STATS_LENGTH,
2914            max_credit_length: MAX_DEFERRED_CREDITS_LENGTH,
2915            initial_deferred_credits_path: None,
2916        };
2917
2918        let tempdir = TempDir::new().expect("cannot create temp directory");
2919        let db_config = MassaDBConfig {
2920            path: tempdir.path().to_path_buf(),
2921            max_history_length: 10,
2922            max_final_state_elements_size: 100_000,
2923            max_versioning_elements_size: 100_000,
2924            thread_count: 2,
2925            max_ledger_backups: 10,
2926            enable_metrics: false,
2927        };
2928        let db = Arc::new(RwLock::new(
2929            Box::new(MassaDB::new(db_config)) as Box<dyn MassaDBController + 'static>
2930        ));
2931        let selector_controller = Box::new(MockSelectorController::new());
2932        let init_seed = Hash::compute_from(b"");
2933        let initial_seeds = vec![Hash::compute_from(init_seed.to_bytes()), init_seed];
2934
2935        let cycle_info_deserializer = CycleInfoDeserializer::new(
2936            pos_config.max_rolls_length,
2937            pos_config.max_production_stats_length,
2938        );
2939
2940        let mut pos_state = PoSFinalState {
2941            config: pos_config.clone(),
2942            db: db.clone(),
2943            cycle_history_cache: Default::default(),
2944            rng_seed_cache: None,
2945            selector: selector_controller,
2946            initial_rolls: Default::default(),
2947            initial_seeds,
2948            credits_serializer: DeferredCreditSerializer::new(),
2949            credits_deserializer: DeferredCreditDeserializer::new(pos_config.max_credit_length),
2950            cycle_info_serializer: CycleInfoSerializer::new(),
2951            cycle_info_deserializer,
2952        };
2953
2954        // Snapshot cycle 0 with non-empty production stats and a partial seed.
2955        let stats_addr =
2956            Address::from_str("AU12pAcVUzsgUBJHaYSAtDKVTYnUT9NorBDjoDovMfAFTLFa16MNa").unwrap();
2957        let mut snapshot_stats = PreHashMap::default();
2958        snapshot_stats.insert(
2959            stats_addr,
2960            ProductionStats {
2961                block_success_count: 3,
2962                block_failure_count: 1,
2963            },
2964        );
2965        let snapshot = CycleInfo::new(
2966            0,
2967            false,
2968            BTreeMap::default(),
2969            bitvec![u8, Lsb0; 0, 0],
2970            snapshot_stats,
2971        );
2972
2973        // Filling the gap in the SAME incomplete cycle keeps the production stats.
2974        let mut batch = DBBatch::new();
2975        pos_state
2976            .create_new_cycle_from_last(
2977                &snapshot,
2978                Slot::new(0, 1), // internal slot of cycle 0 (not first)
2979                Slot::new(0, 1),
2980                &mut batch,
2981            )
2982            .expect("same-cycle interpolation should succeed");
2983        db.write()
2984            .write_batch(batch, Default::default(), Some(Slot::new(0, 1)));
2985
2986        let cycle_0 = pos_state.get_cycle_info(0).expect("cycle 0 should exist");
2987        let kept = cycle_0
2988            .production_stats
2989            .get(&stats_addr)
2990            .expect("continuing the same incomplete cycle must keep production stats");
2991        assert_eq!(kept.block_success_count, 3);
2992        assert_eq!(kept.block_failure_count, 1);
2993
2994        // F65: interpolating a new cycle must NOT inherit the snapshot's production stats.
2995        let mut batch = DBBatch::new();
2996        pos_state
2997            .create_new_cycle_from_last(
2998                &snapshot,
2999                Slot::new(2, 0), // first slot of cycle 1
3000                Slot::new(3, 1), // last slot of cycle 1
3001                &mut batch,
3002            )
3003            .expect("new cycle interpolation should succeed");
3004        db.write()
3005            .write_batch(batch, Default::default(), Some(Slot::new(3, 1)));
3006
3007        let cycle_1 = pos_state.get_cycle_info(1).expect("cycle 1 should exist");
3008        assert!(
3009            cycle_1.production_stats.is_empty(),
3010            "interpolated new cycle must have empty production stats, got {:?}",
3011            cycle_1.production_stats
3012        );
3013    }
3014}