From e63d257f0aeb3f62c79bf487520220a6d9dcef3a Mon Sep 17 00:00:00 2001
From: Andrea Simeoni <andreasimeoni84@gmail.com>
Date: Sun, 29 Jan 2023 18:26:24 +0100
Subject: [PATCH] docs: consensus engine API (#1083)

---
 crates/consensus/src/engine/mod.rs           | 19 ++++++++++++++-----
 crates/interfaces/src/consensus.rs           |  2 +-
 crates/net/downloaders/src/headers/linear.rs |  2 +-
 3 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/crates/consensus/src/engine/mod.rs b/crates/consensus/src/engine/mod.rs
index fbc1989e3..30a2e3c76 100644
--- a/crates/consensus/src/engine/mod.rs
+++ b/crates/consensus/src/engine/mod.rs
@@ -31,22 +31,31 @@ pub use error::{EngineApiError, EngineApiResult};
 /// The Engine API response sender
 pub type EngineApiSender<Ok> = oneshot::Sender<EngineApiResult<Ok>>;
 
-/// Consensus engine API trait.
+/// The Consensus Engine API is a trait that grants the Consensus layer access to data and functions
+/// in the Execution layer that are crucial for the consensus process.
 pub trait ConsensusEngine {
-    /// Retrieves payload from local cache.
+    /// Called to retrieve the latest state of the network, validate new blocks, and maintain
+    /// consistency between the Consensus and Execution layers.
     fn get_payload(&self, payload_id: H64) -> Option<ExecutionPayload>;
 
-    /// Receives a payload to validate and execute.
+    /// When the Consensus layer receives a new block via the consensus gossip protocol,
+    /// the transactions in the block are sent to the execution layer in the form of a
+    /// `ExecutionPayload`. The Execution layer executes the transactions and validates the
+    /// state in the block header, then passes validation data back to Consensus layer, that
+    /// adds the block to the head of its own blockchain and attests to it. The block is then
+    /// broadcasted over the consensus p2p network in the form of a "Beacon block".
     fn new_payload(&mut self, payload: ExecutionPayload) -> EngineApiResult<PayloadStatus>;
 
-    /// Updates the fork choice state
+    /// Called to resolve chain forks and ensure that the Execution layer is working with the latest
+    /// valid chain.
     fn fork_choice_updated(
         &self,
         fork_choice_state: ForkchoiceState,
         payload_attributes: Option<PayloadAttributes>,
     ) -> EngineApiResult<ForkchoiceUpdated>;
 
-    /// Verifies the transition configuration between execution and consensus clients.
+    /// Called to verify network configuration parameters and ensure that Consensus and Execution
+    /// layers are using the latest configuration.
     fn exchange_transition_configuration(
         &self,
         config: TransitionConfiguration,
diff --git a/crates/interfaces/src/consensus.rs b/crates/interfaces/src/consensus.rs
index effebe473..ced617341 100644
--- a/crates/interfaces/src/consensus.rs
+++ b/crates/interfaces/src/consensus.rs
@@ -45,7 +45,7 @@ pub trait Consensus: Debug + Send + Sync {
 #[allow(missing_docs)]
 #[derive(thiserror::Error, Debug, PartialEq, Eq, Clone)]
 pub enum Error {
-    #[error("Block used gas ({gas_used:?}) is greater then gas limit ({gas_limit:?}).")]
+    #[error("Block used gas ({gas_used:?}) is greater than gas limit ({gas_limit:?}).")]
     HeaderGasUsedExceedsGasLimit { gas_used: u64, gas_limit: u64 },
     #[error("Block ommer hash ({got:?}) is different then expected: ({expected:?})")]
     BodyOmmersHashDiff { got: H256, expected: H256 },
diff --git a/crates/net/downloaders/src/headers/linear.rs b/crates/net/downloaders/src/headers/linear.rs
index 909ac1fe0..4d90ca5a7 100644
--- a/crates/net/downloaders/src/headers/linear.rs
+++ b/crates/net/downloaders/src/headers/linear.rs
@@ -259,7 +259,7 @@ where
                     .iter()
                     .take_while(|last| last.number > target_block_number)
                     .count();
-                // removes all headers that are higher than then current target
+                // removes all headers that are higher than current target
                 self.queued_validated_headers.drain(..skip);
             }
         } else {