Apply suggestions from code review

Co-authored-by: teor <[email protected]>

zebra-consensus/src/block/request.rs

@@ -7,12 +7,13 @@ use zebra_chain::block::Block;
 #[derive(Debug, Clone, PartialEq, Eq)]
 /// A request to the chain or block verifier
 pub enum Request {
-    /// Performs semantic validation then calls state with CommitBlock request
+    /// Performs semantic validation, then asks the state to perform contextual validation and commit the block
     Commit(Arc<Block>),
 
     #[cfg(feature = "getblocktemplate-rpcs")]
-    /// Performs semantic validation but skips checking the solution,
-    /// then calls the state with CheckBlockValid request
+    /// Performs semantic validation but skips checking proof of work,
+    /// then asks the state to perform contextual validation, excluding proof of work.
+    /// Does not commit the block to the state.
     CheckProposal(Arc<Block>),
 }
 
@@ -27,7 +28,7 @@ impl Request {
         })
     }
 
-    /// Checks if request is a proposal
+    /// Returns `true` if the request is a proposal
     pub fn is_proposal(&self) -> bool {
         match self {
             Request::Commit(_) => false,

zebra-state/src/request.rs

@@ -560,12 +560,9 @@ pub enum Request {
     CheckBestChainTipNullifiersAndAnchors(UnminedTx),
 
     #[cfg(feature = "getblocktemplate-rpcs")]
-    /// Performs contextual validation of the given block.
+    /// Performs contextual validation of the given block, but does not commit it to the state.
     ///
-    /// It is the caller's responsibility to perform semantic validation.
-    ///
-    /// Returns [`Response::ValidBlock`] with the hash of the block when successful, or an error if
-    /// the block fails contextual validation.
+    /// See `[ReadRequest::CheckBlockValidity]` for details.
     CheckBlockValidity(PreparedBlock),
 }
 
@@ -803,9 +800,10 @@ pub enum ReadRequest {
     },
 
     #[cfg(feature = "getblocktemplate-rpcs")]
-    /// Performs contextual validation of the given block.
+    /// Performs contextual validation of the given block, but does not commit it to the state.
     ///
     /// It is the caller's responsibility to perform semantic validation.
+    /// (The caller does not need to check proof of work for block proposals.)
     ///
     /// Returns [`Response::ValidBlock`] with the hash of the block when successful, or an error if
     /// the block fails contextual validation.

zebra-state/src/service.rs

@@ -1806,13 +1806,13 @@ impl Service<ReadRequest> for ReadStateService {
                         timer.finish(
                             module_path!(),
                             line!(),
-                            "ReadRequest::CheckContextualValidity",
+                            "ReadRequest::CheckBlockValidity",
                         );
 
                         Ok(ReadResponse::ValidBlock(prepared.hash))
                     })
                 })
-                .map(|join_result| join_result.expect("panic in ReadRequest::ChainInfo"))
+                .map(|join_result| join_result.expect("panic in ReadRequest::CheckBlockValidity"))
                 .boxed()
             }
         }