From f4fc9b52161baa816ec9d3de6e1ebfd55762c332 Mon Sep 17 00:00:00 2001
From: Dan Cline <6798349+Rjected@users.noreply.github.com>
Date: Wed, 5 Apr 2023 16:35:33 -0400
Subject: [PATCH] chore: add docs for PayloadStatusEnum (#2132)

---
 crates/rpc/rpc-types/src/eth/engine/payload.rs | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/crates/rpc/rpc-types/src/eth/engine/payload.rs b/crates/rpc/rpc-types/src/eth/engine/payload.rs
index 7d5e80889e..2844e874dc 100644
--- a/crates/rpc/rpc-types/src/eth/engine/payload.rs
+++ b/crates/rpc/rpc-types/src/eth/engine/payload.rs
@@ -226,12 +226,26 @@ impl PayloadStatus {
 #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(tag = "status", rename_all = "SCREAMING_SNAKE_CASE")]
 pub enum PayloadStatusEnum {
+    /// VALID is returned by the engine API in the following calls:
+    ///   - newPayloadV1:       if the payload was already known or was just validated and executed
+    ///   - forkchoiceUpdateV1: if the chain accepted the reorg (might ignore if it's stale)
     Valid,
+
+    /// INVALID is returned by the engine API in the following calls:
+    ///   - newPayloadV1:       if the payload failed to execute on top of the local chain
+    ///   - forkchoiceUpdateV1: if the new head is unknown, pre-merge, or reorg to it fails
     Invalid {
         #[serde(rename = "validationError")]
         validation_error: String,
     },
+
+    /// SYNCING is returned by the engine API in the following calls:
+    ///   - newPayloadV1:       if the payload was accepted on top of an active sync
+    ///   - forkchoiceUpdateV1: if the new head was seen before, but not part of the chain
     Syncing,
+
+    /// ACCEPTED is returned by the engine API in the following calls:
+    ///   - newPayloadV1: if the payload was accepted, but not processed (side chain)
     Accepted,
     InvalidBlockHash {
         #[serde(rename = "validationError")]