chore(node): Add comments about header validation (#308)

Signed-off-by: Yiannis Marangos <[email protected]>
Co-authored-by: Maciej Zwoliński <[email protected]>

node/src/p2p.rs

@@ -392,12 +392,14 @@ impl P2p {
 
     /// Request the headers following the one given with the `header-ex` protocol.
     ///
-    /// First header from the requested range will be verified against the provided one, then each subsequent is verified against the previous one.
+    /// First header from the requested range will be verified against the provided one,
+    /// then each subsequent is verified against the previous one.
     pub async fn get_verified_headers_range(
         &self,
         from: &ExtendedHeader,
         amount: u64,
     ) -> Result<Vec<ExtendedHeader>> {
+        // User can give us a bad header, so validate it.
         from.validate().map_err(|_| HeaderExError::InvalidRequest)?;
 
         let height = from.height().value() + 1;
@@ -407,6 +409,10 @@ impl P2p {
         let mut session = HeaderSession::new(range, self.cmd_tx.clone());
         let headers = session.run().await?;
 
+        // `.validate()` is called on each header separately by `HeaderExClientHandler`.
+        //
+        // The last step is to verify that all headers are from the same chain
+        // and indeed connected with the next one.
         from.verify_adjacent_range(&headers)
             .map_err(|_| HeaderExError::InvalidResponse)?;
 

node/src/p2p/header_ex/client.rs

@@ -256,7 +256,7 @@ async fn decode_and_verify_responses(
         for response in responses {
             // Unmarshal and validate. Propagate error only if nothing
             // was decoded before.
-            let header = match response.to_extended_header() {
+            let header = match response.to_validated_extented_header() {
                 Ok(header) => header,
                 Err(e) if headers.is_empty() => return Err(e),
                 Err(_) => break 'outer,

node/src/p2p/header_ex/utils.rs

@@ -51,13 +51,13 @@ impl HeaderRequestExt for HeaderRequest {
 }
 
 pub(super) trait HeaderResponseExt {
-    fn to_extended_header(&self) -> Result<ExtendedHeader, HeaderExError>;
+    fn to_validated_extented_header(&self) -> Result<ExtendedHeader, HeaderExError>;
     fn not_found() -> HeaderResponse;
     fn invalid() -> HeaderResponse;
 }
 
 impl HeaderResponseExt for HeaderResponse {
-    fn to_extended_header(&self) -> Result<ExtendedHeader, HeaderExError> {
+    fn to_validated_extented_header(&self) -> Result<ExtendedHeader, HeaderExError> {
         match self.status_code() {
             StatusCode::Invalid => Err(HeaderExError::InvalidResponse),
             StatusCode::NotFound => Err(HeaderExError::HeaderNotFound),