Merge pull request hyperledger#133 from mkalinin/engine-api-msg-order

Engine API: refine message ordering section
siladu · Nov 29, 2021 · d7398c9 · d7398c9
2 parents 33fb5c7 + 3b90f9e
commit d7398c9
Showing 1 changed file with 17 additions and 4 deletions.
diff --git a/src/engine/specification.md b/src/engine/specification.md
@@ -9,6 +9,7 @@ This document specifies the Engine API methods that the Consensus Layer uses to
 
 - [Underlying protocol](#underlying-protocol)
 - [Versioning](#versioning)
+- [Constants](#constants)
 - [Message ordering](#message-ordering)
 - [Load-balancing and advanced configurations](#load-balancing-and-advanced-configurations)
 - [Errors](#errors)
@@ -59,13 +60,25 @@ The versioning of the Engine API is defined as follows:
   * a set of structure fields
 * The specification **MAY** reference a method or a structure without the version suffix e.g. `engine_executePayload`. These statements should be read as related to all versions of the referenced method or structure.
 
+## Constants
+
+| Name | Value |
+| - | - |
+| `MESSAGE_ORDER_RESET_ID` | `0` |
+
 ## Message ordering
 
-Consensus Layer client software **MUST** utilize JSON-RPC request IDs that are strictly
-increasing.
+Consensus Layer client software **MUST** utilize JSON-RPC request IDs that are strictly increasing.
+Request IDs assigned to `engine_forkchoiceUpdated` method calls **MUST** respect the order of
+the corresponding fork choice update events occurring in the system.
+
+Execution Layer client software **MUST NOT** process `engine_forkchoiceUpdated` method call
+if its JSON-RPC request ID is lower than the ID assigned to the previous call of this method.
 
-Execution Layer client software **MUST** execute calls strictly in the order of request IDs
-to avoid degenerate race conditions.
+Consensus Layer client software **SHOULD** use `MESSAGE_ORDER_RESET_ID` as initial value of request ID
+to reset the ID cached by Execution Layer client software.
+If the ID of a request equals to `MESSAGE_ORDER_RESET_ID`, Execution Layer client software **MUST** process this request
+disregarding the ID of the previous one and use `MESSAGE_ORDER_RESET_ID` value as the latest previous request ID, effectively resetting the request ID event ordering.
 
 ## Load-balancing and advanced configurations