diff --git a/light-client/src/header/eth_header.rs b/light-client/src/header/eth_header.rs index 7291d3a..7d33538 100644 --- a/light-client/src/header/eth_header.rs +++ b/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: ÐHeader) -> 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: ÐHeader) -> Result { 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: ÐHeader) -> Result { let vote_attestation = self.verify_target_attestation(parent)?; diff --git a/light-client/src/header/eth_headers.rs b/light-client/src/header/eth_headers.rs index 18b7eae..67b437b 100644 --- a/light-client/src/header/eth_headers.rs +++ b/light-client/src/header/eth_headers.rs @@ -18,6 +18,15 @@ pub struct ETHHeaders { } 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, @@ -75,6 +84,10 @@ impl ETHHeaders { 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 { @@ -85,6 +98,10 @@ impl ETHHeaders { 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<(ÐHeader, ÐHeader), Error> { if self.all.len() < 3 { return Err(Error::InvalidVerifyingHeaderLength( @@ -117,6 +134,10 @@ impl ETHHeaders { )) } + /// 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( &self, epoch: u64, diff --git a/light-client/src/header/mod.rs b/light-client/src/header/mod.rs index 9c2a98a..534f949 100644 --- a/light-client/src/header/mod.rs +++ b/light-client/src/header/mod.rs @@ -93,6 +93,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: ÐHeader,