From bfb3953231993d413c86bc7a130e3443b4cf061f Mon Sep 17 00:00:00 2001
From: Dan Cline <6798349+Rjected@users.noreply.github.com>
Date: Wed, 3 Jan 2024 06:27:15 -0500
Subject: [PATCH] chore: improve forkchoiceUpdated doc comments (#5925)

---
 crates/rpc/rpc-api/src/engine.rs | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/crates/rpc/rpc-api/src/engine.rs b/crates/rpc/rpc-api/src/engine.rs
index ee04b2ee8..94563267c 100644
--- a/crates/rpc/rpc-api/src/engine.rs
+++ b/crates/rpc/rpc-api/src/engine.rs
@@ -35,7 +35,7 @@ pub trait EngineApi {
 
     /// See also <https://github.com/ethereum/execution-apis/blob/6709c2a795b707202e93c4f2867fa0bf2640a84f/src/engine/paris.md#engine_forkchoiceupdatedv1>
     ///
-    /// Caution: This should not accept the `withdrawals` field
+    /// Caution: This should not accept the `withdrawals` field in the payload attributes.
     #[method(name = "forkchoiceUpdatedV1")]
     async fn fork_choice_updated_v1(
         &self,
@@ -43,7 +43,15 @@ pub trait EngineApi {
         payload_attributes: Option<PayloadAttributes>,
     ) -> RpcResult<ForkchoiceUpdated>;
 
+    /// Post Shanghai forkchoice update handler
+    ///
+    /// This is the same as `forkchoiceUpdatedV1`, but expects an additional `withdrawals` field in
+    /// the [PayloadAttributes], if payload attributes are provided.
+    ///
     /// See also <https://github.com/ethereum/execution-apis/blob/6709c2a795b707202e93c4f2867fa0bf2640a84f/src/engine/shanghai.md#engine_forkchoiceupdatedv2>
+    ///
+    /// Caution: This should not accept the `parentBeaconBlockRoot` field in the payload
+    /// attributes.
     #[method(name = "forkchoiceUpdatedV2")]
     async fn fork_choice_updated_v2(
         &self,
@@ -51,7 +59,11 @@ pub trait EngineApi {
         payload_attributes: Option<PayloadAttributes>,
     ) -> RpcResult<ForkchoiceUpdated>;
 
-    /// Same as `forkchoiceUpdatedV2` but supports additional [PayloadAttributes] field.
+    /// Post Cancun forkchoice update handler
+    ///
+    /// This is the same as `forkchoiceUpdatedV2`, but expects an additional
+    /// `parentBeaconBlockRoot` field in the the [PayloadAttributes], if payload attributes are
+    /// provided.
     ///
     /// See also <https://github.com/ethereum/execution-apis/blob/main/src/engine/cancun.md#engine_forkchoiceupdatedv3>
     #[method(name = "forkchoiceUpdatedV3")]