S1

light-client/src/header/eth_header.rs

@@ -152,6 +152,8 @@ impl ETHHeader {
         epoch_count * BLOCKS_PER_EPOCH
     }
 
+    /// Verifies that all headers in the `ETHHeader` struct have valid cascading fields.
+    ///
     /// https://github.com/bnb-chain/bsc/blob/b4773e8b5080f37e1c65c083b543f60c895abb70/consensus/parlia/parlia.go#L380
     pub fn verify_cascading_fields(&self, parent: &ETHHeader) -> Result<(), Error> {
         if self.gas_used > self.gas_limit {
@@ -189,6 +191,8 @@ impl ETHHeader {
         Ok(())
     }
 
+    /// Verifies the seal of the current `ETHHeader`.
+    ///
     /// https://github.com/bnb-chain/bsc/blob/7a19cd27b61b342d24a1584efc7fa00de4a5b4f5/consensus/parlia/parlia.go#L755
     pub fn verify_seal(
         &self,
@@ -218,6 +222,12 @@ impl ETHHeader {
         Ok(signer)
     }
 
+    /// Verifies the validator rotation for the current `ETHHeader`.
+    ///
+    /// This function checks if the validator rotation is correct by comparing the coinbase address
+    /// with the expected in-turn validator address based on the current block number and epoch.
+    /// It ensures that the difficulty corresponds to the turn-ness of the signer.
+    ///
     fn verify_validator_rotation(&self, epoch: &Epoch) -> Result<(), Error> {
         let offset = (self.number / epoch.turn_length() as u64) as usize % epoch.validators().len();
         let inturn_validator = &epoch.validators()[offset][0..VALIDATOR_BYTES_LENGTH_BEFORE_LUBAN];
@@ -239,6 +249,11 @@ impl ETHHeader {
         Ok(())
     }
 
+    /// Verifies the target attestation of the current `ETHHeader` against its parent header.
+    ///
+    /// This function checks the target vote attestation of the current header to ensure that
+    /// the target block is the direct parent of the current block.
+    ///
     pub fn verify_target_attestation(&self, parent: &ETHHeader) -> Result<VoteAttestation, Error> {
         let target_vote_attestation = self.get_vote_attestation()?;
         let target_data = &target_vote_attestation.data;
@@ -255,6 +270,8 @@ impl ETHHeader {
         Ok(target_vote_attestation)
     }
 
+    /// Verifies the vote attestation of the current `ETHHeader` against its parent header.
+    ///
     /// https://github.com/bnb-chain/bsc/blob/7a19cd27b61b342d24a1584efc7fa00de4a5b4f5/consensus/parlia/parlia.go#L416
     pub fn verify_vote_attestation(&self, parent: &ETHHeader) -> Result<VoteAttestation, Error> {
         let vote_attestation = self.verify_target_attestation(parent)?;

light-client/src/header/eth_headers.rs

@@ -19,6 +19,15 @@
 }
 
 impl ETHHeaders {
+    /// Verifies the headers in the `ETHHeaders` struct.
+    ///
+    /// This function performs several checks to ensure the validity of the headers:
+    /// 1. Ensures the header after the next or next checkpoint does not exist.
+    /// 2. Verifies the size of the headers within the specified epoch range.
+    /// 3. Ensures all headers are successfully chained.
+    /// 4. Validates the seals of all headers.
+    /// 5. Ensures the target header is finalized.
+    /// 6. Ensures the BLS signature is correct.
     pub fn verify(
         &self,
         chain_id: &ChainId,
@@ -70,6 +79,10 @@
         Ok(())
     }
 
+    /// Verifies that all headers in the `all` vector have valid cascading fields.
+    ///
+    /// This function iterates through the `all` vector of `ETHHeader` objects and ensures that each
+    /// header (except the last one) has valid cascading fields with its subsequent header.
     fn verify_cascading_fields(&self) -> Result<(), Error> {
         for (i, header) in self.all.iter().enumerate() {
             if i < self.all.len() - 1 {
@@ -80,6 +93,10 @@
         Ok(())
     }
 
+    /// Verifies that the headers are finalized.
+    ///
+    /// Only one set of three consecutive valid headers must exist.
+    /// This means that if [x, x+1, x+2] is valid then x+3 must not exist.
     fn verify_finalized(&self) -> Result<(&ETHHeader, &ETHHeader), Error> {
         if self.all.len() < 3 {
             return Err(Error::InvalidVerifyingHeaderLength(
@@ -112,6 +129,10 @@
         ))
     }
 
+    /// Verifies the size of the headers within the specified epoch range.
+    ///
+    /// This function filters the headers to include only those that are within the specified
+    /// checkpoint range and ensures that they meet the size requirements for the current and next epochs.
     fn verify_header_size<'a, 'b>(
         &'b self,
         epoch: u64,
@@ -237,7 +258,7 @@
     use crate::fixture::*;
     use crate::header::epoch::{EitherEpoch, Epoch, TrustedEpoch, UntrustedEpoch};
     use crate::header::Header;
     use crate::misc::{ChainId, Validators};
     use hex_literal::hex;
     use light_client::types::Any;
     use rstest::rstest;

light-client/src/header/mod.rs

@@ -92,6 +92,12 @@ impl Header {
     }
 }
 
+/// Verifies the vote attestation of the current `ETHHeader` against its parent header.
+///
+/// This function checks the vote attestation of the current header to ensure that
+/// the target block is the direct parent of the current block and the source block
+/// is the highest justified block.
+///
 fn verify_epoch<'a>(
     consensus_state: &ConsensusState,
     target: &ETHHeader,