gemachain_program/
epoch_schedule.rs

1//! configuration for epochs, slots
2
3/// 1 Epoch = 400 * 8192 ms ~= 55 minutes
4pub use crate::clock::{Epoch, Slot, DEFAULT_SLOTS_PER_EPOCH};
5
6/// The number of slots before an epoch starts to calculate the leader schedule.
7///  Default is an entire epoch, i.e. leader schedule for epoch X is calculated at
8///  the beginning of epoch X - 1.
9pub const DEFAULT_LEADER_SCHEDULE_SLOT_OFFSET: u64 = DEFAULT_SLOTS_PER_EPOCH;
10
11/// The maximum number of slots before an epoch starts to calculate the leader schedule.
12///  Default is an entire epoch, i.e. leader schedule for epoch X is calculated at
13///  the beginning of epoch X - 1.
14pub const MAX_LEADER_SCHEDULE_EPOCH_OFFSET: u64 = 3;
15
16/// based on MAX_LOCKOUT_HISTORY from vote_program
17pub const MINIMUM_SLOTS_PER_EPOCH: u64 = 32;
18
19#[repr(C)]
20#[derive(Debug, Clone, Copy, PartialEq, Deserialize, Serialize, AbiExample)]
21#[serde(rename_all = "camelCase")]
22pub struct EpochSchedule {
23    /// The maximum number of slots in each epoch.
24    pub slots_per_epoch: u64,
25
26    /// A number of slots before beginning of an epoch to calculate
27    ///  a leader schedule for that epoch
28    pub leader_schedule_slot_offset: u64,
29
30    /// whether epochs start short and grow
31    pub warmup: bool,
32
33    /// basically: log2(slots_per_epoch) - log2(MINIMUM_SLOTS_PER_EPOCH)
34    pub first_normal_epoch: Epoch,
35
36    /// basically: MINIMUM_SLOTS_PER_EPOCH * (2.pow(first_normal_epoch) - 1)
37    pub first_normal_slot: Slot,
38}
39
40impl Default for EpochSchedule {
41    fn default() -> Self {
42        Self::custom(
43            DEFAULT_SLOTS_PER_EPOCH,
44            DEFAULT_LEADER_SCHEDULE_SLOT_OFFSET,
45            true,
46        )
47    }
48}
49
50impl EpochSchedule {
51    pub fn new(slots_per_epoch: u64) -> Self {
52        Self::custom(slots_per_epoch, slots_per_epoch, true)
53    }
54    pub fn without_warmup() -> Self {
55        Self::custom(
56            DEFAULT_SLOTS_PER_EPOCH,
57            DEFAULT_LEADER_SCHEDULE_SLOT_OFFSET,
58            false,
59        )
60    }
61    pub fn custom(slots_per_epoch: u64, leader_schedule_slot_offset: u64, warmup: bool) -> Self {
62        assert!(slots_per_epoch >= MINIMUM_SLOTS_PER_EPOCH as u64);
63        let (first_normal_epoch, first_normal_slot) = if warmup {
64            let next_power_of_two = slots_per_epoch.next_power_of_two();
65            let log2_slots_per_epoch = next_power_of_two
66                .trailing_zeros()
67                .saturating_sub(MINIMUM_SLOTS_PER_EPOCH.trailing_zeros());
68
69            (
70                u64::from(log2_slots_per_epoch),
71                next_power_of_two.saturating_sub(MINIMUM_SLOTS_PER_EPOCH),
72            )
73        } else {
74            (0, 0)
75        };
76        EpochSchedule {
77            slots_per_epoch,
78            leader_schedule_slot_offset,
79            warmup,
80            first_normal_epoch,
81            first_normal_slot,
82        }
83    }
84
85    /// get the length of the given epoch (in slots)
86    pub fn get_slots_in_epoch(&self, epoch: Epoch) -> u64 {
87        if epoch < self.first_normal_epoch {
88            2u64.saturating_pow(
89                (epoch as u32).saturating_add(MINIMUM_SLOTS_PER_EPOCH.trailing_zeros() as u32),
90            )
91        } else {
92            self.slots_per_epoch
93        }
94    }
95
96    /// get the epoch for which the given slot should save off
97    ///  information about stakers
98    pub fn get_leader_schedule_epoch(&self, slot: Slot) -> Epoch {
99        if slot < self.first_normal_slot {
100            // until we get to normal slots, behave as if leader_schedule_slot_offset == slots_per_epoch
101            self.get_epoch_and_slot_index(slot).0.saturating_add(1)
102        } else {
103            let new_slots_since_first_normal_slot = slot.saturating_sub(self.first_normal_slot);
104            let new_first_normal_leader_schedule_slot =
105                new_slots_since_first_normal_slot.saturating_add(self.leader_schedule_slot_offset);
106            let new_epochs_since_first_normal_leader_schedule =
107                new_first_normal_leader_schedule_slot
108                    .checked_div(self.slots_per_epoch)
109                    .unwrap_or(0);
110            self.first_normal_epoch
111                .saturating_add(new_epochs_since_first_normal_leader_schedule)
112        }
113    }
114
115    /// get epoch for the given slot
116    pub fn get_epoch(&self, slot: Slot) -> Epoch {
117        self.get_epoch_and_slot_index(slot).0
118    }
119
120    /// get epoch and offset into the epoch for the given slot
121    pub fn get_epoch_and_slot_index(&self, slot: Slot) -> (Epoch, u64) {
122        if slot < self.first_normal_slot {
123            let epoch = slot
124                .saturating_add(MINIMUM_SLOTS_PER_EPOCH)
125                .saturating_add(1)
126                .next_power_of_two()
127                .trailing_zeros()
128                .saturating_sub(MINIMUM_SLOTS_PER_EPOCH.trailing_zeros())
129                .saturating_sub(1);
130
131            let epoch_len =
132                2u64.saturating_pow(epoch.saturating_add(MINIMUM_SLOTS_PER_EPOCH.trailing_zeros()));
133
134            (
135                u64::from(epoch),
136                slot.saturating_sub(epoch_len.saturating_sub(MINIMUM_SLOTS_PER_EPOCH)),
137            )
138        } else {
139            let normal_slot_index = slot.saturating_sub(self.first_normal_slot);
140            let normal_epoch_index = normal_slot_index
141                .checked_div(self.slots_per_epoch)
142                .unwrap_or(0);
143            let epoch = self.first_normal_epoch.saturating_add(normal_epoch_index);
144            let slot_index = normal_slot_index
145                .checked_rem(self.slots_per_epoch)
146                .unwrap_or(0);
147            (epoch, slot_index)
148        }
149    }
150
151    pub fn get_first_slot_in_epoch(&self, epoch: Epoch) -> Slot {
152        if epoch <= self.first_normal_epoch {
153            2u64.saturating_pow(epoch as u32)
154                .saturating_sub(1)
155                .saturating_mul(MINIMUM_SLOTS_PER_EPOCH)
156        } else {
157            epoch
158                .saturating_sub(self.first_normal_epoch)
159                .saturating_mul(self.slots_per_epoch)
160                .saturating_add(self.first_normal_slot)
161        }
162    }
163
164    pub fn get_last_slot_in_epoch(&self, epoch: Epoch) -> Slot {
165        self.get_first_slot_in_epoch(epoch)
166            .saturating_add(self.get_slots_in_epoch(epoch))
167            .saturating_sub(1)
168    }
169}
170
171#[cfg(test)]
172mod tests {
173    use super::*;
174
175    #[test]
176    fn test_epoch_schedule() {
177        // one week of slots at 8 ticks/slot, 10 ticks/sec is
178        // (1 * 7 * 24 * 4500u64).next_power_of_two();
179
180        // test values between MINIMUM_SLOT_LEN and MINIMUM_SLOT_LEN * 16, should cover a good mix
181        for slots_per_epoch in MINIMUM_SLOTS_PER_EPOCH..=MINIMUM_SLOTS_PER_EPOCH * 16 {
182            let epoch_schedule = EpochSchedule::custom(slots_per_epoch, slots_per_epoch / 2, true);
183
184            assert_eq!(epoch_schedule.get_first_slot_in_epoch(0), 0);
185            assert_eq!(
186                epoch_schedule.get_last_slot_in_epoch(0),
187                MINIMUM_SLOTS_PER_EPOCH - 1
188            );
189
190            let mut last_leader_schedule = 0;
191            let mut last_epoch = 0;
192            let mut last_slots_in_epoch = MINIMUM_SLOTS_PER_EPOCH;
193            for slot in 0..(2 * slots_per_epoch) {
194                // verify that leader_schedule_epoch is continuous over the warmup
195                // and into the first normal epoch
196
197                let leader_schedule = epoch_schedule.get_leader_schedule_epoch(slot);
198                if leader_schedule != last_leader_schedule {
199                    assert_eq!(leader_schedule, last_leader_schedule + 1);
200                    last_leader_schedule = leader_schedule;
201                }
202
203                let (epoch, offset) = epoch_schedule.get_epoch_and_slot_index(slot);
204
205                //  verify that epoch increases continuously
206                if epoch != last_epoch {
207                    assert_eq!(epoch, last_epoch + 1);
208                    last_epoch = epoch;
209                    assert_eq!(epoch_schedule.get_first_slot_in_epoch(epoch), slot);
210                    assert_eq!(epoch_schedule.get_last_slot_in_epoch(epoch - 1), slot - 1);
211
212                    // verify that slots in an epoch double continuously
213                    //   until they reach slots_per_epoch
214
215                    let slots_in_epoch = epoch_schedule.get_slots_in_epoch(epoch);
216                    if slots_in_epoch != last_slots_in_epoch && slots_in_epoch != slots_per_epoch {
217                        assert_eq!(slots_in_epoch, last_slots_in_epoch * 2);
218                    }
219                    last_slots_in_epoch = slots_in_epoch;
220                }
221                // verify that the slot offset is less than slots_in_epoch
222                assert!(offset < last_slots_in_epoch);
223            }
224
225            // assert that these changed  ;)
226            assert!(last_leader_schedule != 0); // t
227            assert!(last_epoch != 0);
228            // assert that we got to "normal" mode
229            assert!(last_slots_in_epoch == slots_per_epoch);
230        }
231    }
232}
gemachain_program/epoch_schedule.rs

gemachain_program/
epoch_schedule.rs
