document clock (#6662)

ledger/src/leader_schedule_cache.rs

@@ -43,8 +43,8 @@ impl LeaderScheduleCache {
         cache.set_root(root_bank);
 
         // Calculate the schedule for all epochs between 0 and leader_schedule_epoch(root)
-        let stakers_epoch = epoch_schedule.get_leader_schedule_epoch(root_bank.slot());
-        for epoch in 0..stakers_epoch {
+        let leader_schedule_epoch = epoch_schedule.get_leader_schedule_epoch(root_bank.slot());
+        for epoch in 0..leader_schedule_epoch {
             let first_slot_in_epoch = epoch_schedule.get_first_slot_in_epoch(epoch);
             cache.slot_leader_at(first_slot_in_epoch, Some(root_bank));
         }
@@ -254,22 +254,22 @@ mod tests {
         assert_eq!(cache.max_schedules(), MAX_SCHEDULES);
 
         // Epoch schedule for all epochs in the range:
-        // [0, stakers_epoch(bank.slot())] should
+        // [0, leader_schedule_epoch(bank.slot())] should
         // be calculated by constructor
         let epoch_schedule = bank.epoch_schedule();
-        let stakers_epoch = bank.get_leader_schedule_epoch(bank.slot());
-        for epoch in 0..=stakers_epoch {
-            let first_slot_in_stakers_epoch = epoch_schedule.get_first_slot_in_epoch(epoch);
-            let last_slot_in_stakers_epoch = epoch_schedule.get_last_slot_in_epoch(epoch);
+        let leader_schedule_epoch = bank.get_leader_schedule_epoch(bank.slot());
+        for epoch in 0..=leader_schedule_epoch {
+            let first_slot_in_leader_schedule_epoch = epoch_schedule.get_first_slot_in_epoch(epoch);
+            let last_slot_in_leader_schedule_epoch = epoch_schedule.get_last_slot_in_epoch(epoch);
             assert!(cache
-                .slot_leader_at(first_slot_in_stakers_epoch, None)
+                .slot_leader_at(first_slot_in_leader_schedule_epoch, None)
                 .is_some());
             assert!(cache
-                .slot_leader_at(last_slot_in_stakers_epoch, None)
+                .slot_leader_at(last_slot_in_leader_schedule_epoch, None)
                 .is_some());
-            if epoch == stakers_epoch {
+            if epoch == leader_schedule_epoch {
                 assert!(cache
-                    .slot_leader_at(last_slot_in_stakers_epoch + 1, None)
+                    .slot_leader_at(last_slot_in_leader_schedule_epoch + 1, None)
                     .is_none());
             }
         }
@@ -277,7 +277,7 @@ mod tests {
         // Should be a schedule for every epoch just checked
         assert_eq!(
             cache.cached_schedules.read().unwrap().0.len() as u64,
-            stakers_epoch + 1
+            leader_schedule_epoch + 1
         );
     }
 

programs/storage_program/tests/storage_processor.rs

@@ -137,7 +137,7 @@ fn test_proof_bounds() {
             slot: DEFAULT_SLOTS_PER_SEGMENT * 2,
             segment: 2,
             epoch: 0,
-            stakers_epoch: 0,
+            leader_schedule_epoch: 0,
         },
         &mut clock_account,
     );
@@ -190,7 +190,7 @@ fn test_invalid_accounts_len() {
             slot: 16,
             segment: 1,
             epoch: 0,
-            stakers_epoch: 0,
+            leader_schedule_epoch: 0,
         },
         &mut clock_account,
     );
@@ -250,7 +250,7 @@ fn test_submit_mining_ok() {
             slot: DEFAULT_SLOTS_PER_SEGMENT,
             segment: 1,
             epoch: 0,
-            stakers_epoch: 0,
+            leader_schedule_epoch: 0,
         },
         &mut clock_account,
     );

sdk/src/clock.rs

@@ -72,13 +72,23 @@ pub type Segment = u64;
 ///  some number of Slots.
 pub type Epoch = u64;
 
+/// Clock represents network time.  Members of Clock start from 0 upon
+///  network boot.  The best way to map Clock to wallclock time is to use
+///  current Slot, as Epochs vary in duration (they start short and grow
+///  as the network progresses).
+///
 #[repr(C)]
 #[derive(Serialize, Deserialize, Debug, Default, PartialEq)]
 pub struct Clock {
+    /// the current network/bank Slot
     pub slot: Slot,
+    /// the current Segment, used for archiver rounds
     pub segment: Segment,
+    /// the bank Epoch
     pub epoch: Epoch,
-    pub stakers_epoch: Epoch,
+    /// the future Epoch for which the leader schedule has
+    ///  most recently been calculated
+    pub leader_schedule_epoch: Epoch,
 }
 
 #[cfg(test)]

sdk/src/sysvar/clock.rs

@@ -1,4 +1,4 @@
-//! This account contains the clock slot, epoch, and stakers_epoch
+//! This account contains the clock slot, epoch, and leader_schedule_epoch
 //!
 pub use crate::clock::Clock;
 
@@ -40,7 +40,7 @@ pub fn new_account(
     slot: Slot,
     segment: Segment,
     epoch: Epoch,
-    stakers_epoch: Epoch,
+    leader_schedule_epoch: Epoch,
 ) -> Account {
     Account::new_data(
         lamports,
@@ -48,7 +48,7 @@ pub fn new_account(
             slot,
             segment,
             epoch,
-            stakers_epoch,
+            leader_schedule_epoch,
         },
         &sysvar::id(),
     )