Supervisor follow-up (#327)

* Document the supervisor

* Rename LightStore::latest to LightStore::highest

* Rename AtHeight::Latest to AtHeight::Highest

light-client/examples/light_client.rs

@@ -104,7 +104,7 @@ fn make_instance(
 
  light_store.insert(trusted_state, VerifiedStatus::Verified);
  } else {
- if light_store.latest(VerifiedStatus::Verified).is_none() {
+ if light_store.highest(VerifiedStatus::Verified).is_none() {
  println!("[ error ] no trusted state in database, please specify a trusted header");
  std::process::exit(1);
  }

light-client/src/components/io.rs

@@ -16,13 +16,13 @@ use crate::{
 
 pub enum AtHeight {
  At(Height),
- Latest,
+ Highest,
 }
 
 impl From<Height> for AtHeight {
  fn from(height: Height) -> Self {
  if height == 0 {
- Self::Latest
+ Self::Highest
  } else {
  Self::At(height)
  }
@@ -110,7 +110,7 @@ impl ProdIo {
  let res = block_on(
  async {
  match height {
- AtHeight::Latest => rpc_client.latest_commit().await,
+ AtHeight::Highest => rpc_client.latest_commit().await,
  AtHeight::At(height) => rpc_client.commit(height).await,
  }
  },
@@ -131,7 +131,7 @@ impl ProdIo {
  height: AtHeight,
  ) -> Result<TMValidatorSet, IoError> {
  let height = match height {
- AtHeight::Latest => bail!(IoError::InvalidHeight(
+ AtHeight::Highest => bail!(IoError::InvalidHeight(
  "given height must be greater than 0".to_string()
  )),
  AtHeight::At(height) => height,

light-client/src/components/scheduler.rs

@@ -18,7 +18,7 @@ pub trait Scheduler: Send {
  ///
  /// ## Postcondition
  /// - The resulting height must be valid according to `valid_schedule`. [LCV-SCHEDULE-POST.1]
- #[pre(light_store.latest(VerifiedStatus::Verified).is_some())]
+ #[pre(light_store.highest(VerifiedStatus::Verified).is_some())]
  #[post(valid_schedule(ret, target_height, current_height, light_store))]
  fn schedule(
  &self,
@@ -51,23 +51,23 @@ where
 ///
 /// ## Postcondition
 /// - The resulting height must be valid according to `valid_schedule`. [LCV-SCHEDULE-POST.1]
-#[pre(light_store.latest(VerifiedStatus::Verified).is_some())]
+#[pre(light_store.highest(VerifiedStatus::Verified).is_some())]
 #[post(valid_schedule(ret, target_height, current_height, light_store))]
 pub fn basic_bisecting_schedule(
  light_store: &dyn LightStore,
  current_height: Height,
  target_height: Height,
 ) -> Height {
- let latest_trusted_height = light_store
- .latest(VerifiedStatus::Verified)
+ let trusted_height = light_store
+ .highest(VerifiedStatus::Verified)
  .map(|lb| lb.height())
  .unwrap();
 
- if latest_trusted_height == current_height && latest_trusted_height < target_height {
+ if trusted_height == current_height && trusted_height < target_height {
  target_height
- } else if latest_trusted_height < current_height && latest_trusted_height < target_height {
- midpoint(latest_trusted_height, current_height)
- } else if latest_trusted_height == target_height {
+ } else if trusted_height < current_height && trusted_height < target_height {
+ midpoint(trusted_height, current_height)
+ } else if trusted_height == target_height {
  target_height
  } else {
  midpoint(current_height, target_height)
@@ -103,7 +103,7 @@ pub fn valid_schedule(
  light_store: &dyn LightStore,
 ) -> bool {
  let latest_trusted_height = light_store
- .latest(VerifiedStatus::Verified)
+ .highest(VerifiedStatus::Verified)
  .map(|lb| lb.height())
  .unwrap();
 

light-client/src/errors.rs

@@ -24,8 +24,8 @@ pub enum ErrorKind {
  #[error("no witnesses")]
  NoWitnesses,
 
- #[error("no witness left")]
- NoWitnessLeft,
+ #[error("no valid peer left")]
+ NoValidPeerLeft,
 
  #[error("fork detected peers={0:?}")]
  ForkDetected(Vec<PeerId>),

light-client/src/light_client.rs

@@ -90,11 +90,11 @@ impl LightClient {
  }
  }
 
- /// Attempt to update the light client to the latest block of the primary node.
+ /// Attempt to update the light client to the highest block of the primary node.
  ///
  /// Note: This functin delegates the actual work to `verify_to_target`.
  pub fn verify_to_highest(&mut self, state: &mut State) -> Result<LightBlock, Error> {
- let target_block = match self.io.fetch_light_block(self.peer, AtHeight::Latest) {
+ let target_block = match self.io.fetch_light_block(self.peer, AtHeight::Highest) {
  Ok(last_block) => last_block,
  Err(io_error) => bail!(ErrorKind::Io(io_error)),
  };
@@ -165,10 +165,10 @@ impl LightClient {
  let mut current_height = target_height;
 
  loop {
- // Get the latest trusted state
+ // Get the highest trusted state
  let trusted_state = state
  .light_store
- .latest(VerifiedStatus::Verified)
+ .highest(VerifiedStatus::Verified)
  .ok_or_else(|| ErrorKind::NoInitialTrustedState)?;
 
  // Check invariant [LCV-INV-TP.1]
@@ -214,7 +214,7 @@ impl LightClient {
  Verdict::NotEnoughTrust(_) => {
  // The current block cannot be trusted because of missing overlap in the validator sets.
  // Add the block to the light store with `unverified` status.
- // This will engage bisection in an attempt to raise the height of the latest
+ // This will engage bisection in an attempt to raise the height of the highest
  // trusted state until there is enough overlap.
  state
  .light_store

light-client/src/peer_list.rs

@@ -73,7 +73,7 @@ impl PeerList {
  }
  }
 
- bail!(ErrorKind::NoWitnessLeft)
+ bail!(ErrorKind::NoValidPeerLeft)
  }
 }
 

light-client/src/store.rs

@@ -54,7 +54,7 @@ pub trait LightStore: std::fmt::Debug + Send {
  /// Remove the light block with the given height and status, if any.
  fn remove(&mut self, height: Height, status: VerifiedStatus);
  /// Get the highest light block with the given status.
- fn latest(&self, status: VerifiedStatus) -> Option<LightBlock>;
+ fn highest(&self, status: VerifiedStatus) -> Option<LightBlock>;
  /// Get an iterator of all light blocks with the given status.
  fn all(&self, status: VerifiedStatus) -> Box<dyn Iterator<Item = LightBlock>>;
 }

light-client/src/store/memory.rs

@@ -62,7 +62,7 @@ impl LightStore for MemoryStore {
  self.insert(light_block, status);
  }
 
- fn latest(&self, status: VerifiedStatus) -> Option<LightBlock> {
+ fn highest(&self, status: VerifiedStatus) -> Option<LightBlock> {
  self.store
  .iter()
  .rev()

light-client/src/store/sled.rs

@@ -67,7 +67,7 @@ impl LightStore for SledStore {
  self.db(status).remove(&self.db, &height).ok();
  }
 
- fn latest(&self, status: VerifiedStatus) -> Option<LightBlock> {
+ fn highest(&self, status: VerifiedStatus) -> Option<LightBlock> {
  self.db(status).iter(&self.db).next_back()
  }