solana_runtime/
commitment.rs

1use {
2    serde::{Deserialize, Serialize},
3    solana_clock::Slot,
4    solana_commitment_config::CommitmentLevel,
5    solana_vote_program::vote_state::MAX_LOCKOUT_HISTORY,
6    std::collections::HashMap,
7};
8
9pub const VOTE_THRESHOLD_SIZE: f64 = 2f64 / 3f64;
10
11pub type BlockCommitmentArray = [u64; MAX_LOCKOUT_HISTORY + 1];
12
13#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
14pub struct BlockCommitment {
15    pub commitment: BlockCommitmentArray,
16}
17
18impl BlockCommitment {
19    pub fn increase_confirmation_stake(&mut self, confirmation_count: usize, stake: u64) {
20        assert!(confirmation_count > 0 && confirmation_count <= MAX_LOCKOUT_HISTORY);
21        self.commitment[confirmation_count - 1] += stake;
22    }
23
24    pub fn get_confirmation_stake(&mut self, confirmation_count: usize) -> u64 {
25        assert!(confirmation_count > 0 && confirmation_count <= MAX_LOCKOUT_HISTORY);
26        self.commitment[confirmation_count - 1]
27    }
28
29    pub fn increase_rooted_stake(&mut self, stake: u64) {
30        self.commitment[MAX_LOCKOUT_HISTORY] += stake;
31    }
32
33    pub fn get_rooted_stake(&self) -> u64 {
34        self.commitment[MAX_LOCKOUT_HISTORY]
35    }
36
37    pub fn new(commitment: BlockCommitmentArray) -> Self {
38        Self { commitment }
39    }
40}
41
42/// A node's view of cluster commitment as per a particular bank
43#[derive(Default)]
44pub struct BlockCommitmentCache {
45    /// Map of all commitment levels of current ancestor slots, aggregated from the vote account
46    /// data in the bank
47    block_commitment: HashMap<Slot, BlockCommitment>,
48    /// Cache slot details. Cluster data is calculated from the block_commitment map, and cached in
49    /// the struct to avoid the expense of recalculating on every call.
50    commitment_slots: CommitmentSlots,
51    /// Total stake active during the bank's epoch
52    total_stake: u64,
53}
54
55impl std::fmt::Debug for BlockCommitmentCache {
56    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
57        f.debug_struct("BlockCommitmentCache")
58            .field("block_commitment", &self.block_commitment)
59            .field("total_stake", &self.total_stake)
60            .field(
61                "bank",
62                &format_args!("Bank({{current_slot: {:?}}})", self.commitment_slots.slot),
63            )
64            .field("root", &self.commitment_slots.root)
65            .finish()
66    }
67}
68
69impl BlockCommitmentCache {
70    pub fn new(
71        block_commitment: HashMap<Slot, BlockCommitment>,
72        total_stake: u64,
73        commitment_slots: CommitmentSlots,
74    ) -> Self {
75        Self {
76            block_commitment,
77            commitment_slots,
78            total_stake,
79        }
80    }
81
82    pub fn get_block_commitment(&self, slot: Slot) -> Option<&BlockCommitment> {
83        self.block_commitment.get(&slot)
84    }
85
86    pub fn total_stake(&self) -> u64 {
87        self.total_stake
88    }
89
90    pub fn slot(&self) -> Slot {
91        self.commitment_slots.slot
92    }
93
94    pub fn root(&self) -> Slot {
95        self.commitment_slots.root
96    }
97
98    pub fn highest_confirmed_slot(&self) -> Slot {
99        self.commitment_slots.highest_confirmed_slot
100    }
101
102    pub fn highest_super_majority_root(&self) -> Slot {
103        self.commitment_slots.highest_super_majority_root
104    }
105
106    pub fn commitment_slots(&self) -> CommitmentSlots {
107        self.commitment_slots
108    }
109
110    pub fn highest_gossip_confirmed_slot(&self) -> Slot {
111        // TODO: combine bank caches
112        // Currently, this information is provided by OptimisticallyConfirmedBank::bank.slot()
113        self.highest_confirmed_slot()
114    }
115
116    pub fn slot_with_commitment(&self, commitment_level: CommitmentLevel) -> Slot {
117        match commitment_level {
118            CommitmentLevel::Processed => self.slot(),
119            CommitmentLevel::Confirmed => self.highest_gossip_confirmed_slot(),
120            CommitmentLevel::Finalized => self.highest_super_majority_root(),
121        }
122    }
123
124    fn highest_slot_with_confirmation_count(&self, confirmation_count: usize) -> Slot {
125        assert!(confirmation_count > 0 && confirmation_count <= MAX_LOCKOUT_HISTORY);
126        for slot in (self.root()..self.slot()).rev() {
127            if let Some(count) = self.get_confirmation_count(slot) {
128                if count >= confirmation_count {
129                    return slot;
130                }
131            }
132        }
133        self.commitment_slots.root
134    }
135
136    pub fn calculate_highest_confirmed_slot(&self) -> Slot {
137        self.highest_slot_with_confirmation_count(1)
138    }
139
140    pub fn get_confirmation_count(&self, slot: Slot) -> Option<usize> {
141        self.get_lockout_count(slot, VOTE_THRESHOLD_SIZE)
142    }
143
144    // Returns the lowest level at which at least `minimum_stake_percentage` of the total epoch
145    // stake is locked out
146    fn get_lockout_count(&self, slot: Slot, minimum_stake_percentage: f64) -> Option<usize> {
147        self.get_block_commitment(slot).map(|block_commitment| {
148            let iterator = block_commitment.commitment.iter().enumerate().rev();
149            let mut sum = 0;
150            for (i, stake) in iterator {
151                sum += stake;
152                if (sum as f64 / self.total_stake as f64) > minimum_stake_percentage {
153                    return i + 1;
154                }
155            }
156            0
157        })
158    }
159
160    pub fn new_for_tests() -> Self {
161        let mut block_commitment: HashMap<Slot, BlockCommitment> = HashMap::new();
162        block_commitment.insert(0, BlockCommitment::default());
163        Self {
164            block_commitment,
165            total_stake: 42,
166            ..Self::default()
167        }
168    }
169
170    pub fn new_for_tests_with_slots(slot: Slot, root: Slot) -> Self {
171        let mut block_commitment: HashMap<Slot, BlockCommitment> = HashMap::new();
172        block_commitment.insert(0, BlockCommitment::default());
173        Self {
174            block_commitment,
175            total_stake: 42,
176            commitment_slots: CommitmentSlots {
177                slot,
178                root,
179                highest_confirmed_slot: root,
180                highest_super_majority_root: root,
181            },
182        }
183    }
184
185    pub fn set_highest_confirmed_slot(&mut self, slot: Slot) {
186        self.commitment_slots.highest_confirmed_slot = slot;
187    }
188
189    pub fn set_highest_super_majority_root(&mut self, root: Slot) {
190        self.commitment_slots.highest_super_majority_root = root;
191    }
192
193    pub fn initialize_slots(&mut self, slot: Slot, root: Slot) {
194        self.commitment_slots.slot = slot;
195        self.commitment_slots.root = root;
196    }
197
198    pub fn set_all_slots(&mut self, slot: Slot, root: Slot) {
199        self.commitment_slots.slot = slot;
200        self.commitment_slots.highest_confirmed_slot = slot;
201        self.commitment_slots.root = root;
202        self.commitment_slots.highest_super_majority_root = root;
203    }
204}
205
206#[derive(Default, Clone, Copy)]
207pub struct CommitmentSlots {
208    /// The slot of the bank from which all other slots were calculated.
209    pub slot: Slot,
210    /// The current node root
211    pub root: Slot,
212    /// Highest cluster-confirmed slot
213    pub highest_confirmed_slot: Slot,
214    /// Highest slot rooted by a super majority of the cluster
215    pub highest_super_majority_root: Slot,
216}
217
218impl CommitmentSlots {
219    pub fn new_from_slot(slot: Slot) -> Self {
220        Self {
221            slot,
222            ..Self::default()
223        }
224    }
225}
226
227#[cfg(test)]
228mod tests {
229    use super::*;
230
231    #[test]
232    fn test_block_commitment() {
233        let mut cache = BlockCommitment::default();
234        assert_eq!(cache.get_confirmation_stake(1), 0);
235        cache.increase_confirmation_stake(1, 10);
236        assert_eq!(cache.get_confirmation_stake(1), 10);
237        cache.increase_confirmation_stake(1, 20);
238        assert_eq!(cache.get_confirmation_stake(1), 30);
239    }
240
241    #[test]
242    fn test_get_confirmations() {
243        // Build BlockCommitmentCache with votes at depths 0 and 1 for 2 slots
244        let mut cache0 = BlockCommitment::default();
245        cache0.increase_confirmation_stake(1, 5);
246        cache0.increase_confirmation_stake(2, 40);
247
248        let mut cache1 = BlockCommitment::default();
249        cache1.increase_confirmation_stake(1, 40);
250        cache1.increase_confirmation_stake(2, 5);
251
252        let mut cache2 = BlockCommitment::default();
253        cache2.increase_confirmation_stake(1, 20);
254        cache2.increase_confirmation_stake(2, 5);
255
256        let mut block_commitment = HashMap::new();
257        block_commitment.entry(0).or_insert(cache0);
258        block_commitment.entry(1).or_insert(cache1);
259        block_commitment.entry(2).or_insert(cache2);
260        let block_commitment_cache = BlockCommitmentCache {
261            block_commitment,
262            total_stake: 50,
263            ..BlockCommitmentCache::default()
264        };
265
266        assert_eq!(block_commitment_cache.get_confirmation_count(0), Some(2));
267        assert_eq!(block_commitment_cache.get_confirmation_count(1), Some(1));
268        assert_eq!(block_commitment_cache.get_confirmation_count(2), Some(0),);
269        assert_eq!(block_commitment_cache.get_confirmation_count(3), None,);
270    }
271
272    #[test]
273    fn test_highest_confirmed_slot() {
274        let bank_slot_5 = 5;
275        let total_stake = 50;
276
277        // Build cache with confirmation_count 2 given total_stake
278        let mut cache0 = BlockCommitment::default();
279        cache0.increase_confirmation_stake(1, 5);
280        cache0.increase_confirmation_stake(2, 40);
281
282        // Build cache with confirmation_count 1 given total_stake
283        let mut cache1 = BlockCommitment::default();
284        cache1.increase_confirmation_stake(1, 40);
285        cache1.increase_confirmation_stake(2, 5);
286
287        // Build cache with confirmation_count 0 given total_stake
288        let mut cache2 = BlockCommitment::default();
289        cache2.increase_confirmation_stake(1, 20);
290        cache2.increase_confirmation_stake(2, 5);
291
292        let mut block_commitment = HashMap::new();
293        block_commitment.entry(1).or_insert_with(|| cache0.clone()); // Slot 1, conf 2
294        block_commitment.entry(2).or_insert_with(|| cache1.clone()); // Slot 2, conf 1
295        block_commitment.entry(3).or_insert_with(|| cache2.clone()); // Slot 3, conf 0
296        let commitment_slots = CommitmentSlots::new_from_slot(bank_slot_5);
297        let block_commitment_cache =
298            BlockCommitmentCache::new(block_commitment, total_stake, commitment_slots);
299
300        assert_eq!(block_commitment_cache.calculate_highest_confirmed_slot(), 2);
301
302        // Build map with multiple slots at conf 1
303        let mut block_commitment = HashMap::new();
304        block_commitment.entry(1).or_insert_with(|| cache1.clone()); // Slot 1, conf 1
305        block_commitment.entry(2).or_insert_with(|| cache1.clone()); // Slot 2, conf 1
306        block_commitment.entry(3).or_insert_with(|| cache2.clone()); // Slot 3, conf 0
307        let block_commitment_cache =
308            BlockCommitmentCache::new(block_commitment, total_stake, commitment_slots);
309
310        assert_eq!(block_commitment_cache.calculate_highest_confirmed_slot(), 2);
311
312        // Build map with slot gaps
313        let mut block_commitment = HashMap::new();
314        block_commitment.entry(1).or_insert_with(|| cache1.clone()); // Slot 1, conf 1
315        block_commitment.entry(3).or_insert(cache1); // Slot 3, conf 1
316        block_commitment.entry(5).or_insert_with(|| cache2.clone()); // Slot 5, conf 0
317        let block_commitment_cache =
318            BlockCommitmentCache::new(block_commitment, total_stake, commitment_slots);
319
320        assert_eq!(block_commitment_cache.calculate_highest_confirmed_slot(), 3);
321
322        // Build map with no conf 1 slots, but one higher
323        let mut block_commitment = HashMap::new();
324        block_commitment.entry(1).or_insert(cache0); // Slot 1, conf 2
325        block_commitment.entry(2).or_insert_with(|| cache2.clone()); // Slot 2, conf 0
326        block_commitment.entry(3).or_insert_with(|| cache2.clone()); // Slot 3, conf 0
327        let block_commitment_cache =
328            BlockCommitmentCache::new(block_commitment, total_stake, commitment_slots);
329
330        assert_eq!(block_commitment_cache.calculate_highest_confirmed_slot(), 1);
331
332        // Build map with no conf 1 or higher slots
333        let mut block_commitment = HashMap::new();
334        block_commitment.entry(1).or_insert_with(|| cache2.clone()); // Slot 1, conf 0
335        block_commitment.entry(2).or_insert_with(|| cache2.clone()); // Slot 2, conf 0
336        block_commitment.entry(3).or_insert(cache2); // Slot 3, conf 0
337        let block_commitment_cache =
338            BlockCommitmentCache::new(block_commitment, total_stake, commitment_slots);
339
340        assert_eq!(block_commitment_cache.calculate_highest_confirmed_slot(), 0);
341    }
342}
solana_runtime/commitment.rs

solana_runtime/
commitment.rs
