Document new engine API methods (#1298)

* Document new engine API methods Signed-off-by: Alexandra Tran <[email protected]> * add example results Signed-off-by: Alexandra Tran <[email protected]> * minor fixes Signed-off-by: Alexandra Tran <[email protected]> * fix typo Signed-off-by: Alexandra Tran <[email protected]> * one more typo Signed-off-by: Alexandra Tran <[email protected]> * remove payloadId Signed-off-by: Alexandra Tran <[email protected]> * update exchangeCapabilities result Signed-off-by: Alexandra Tran <[email protected]> * reviewer feedback Signed-off-by: Alexandra Tran <[email protected]> --------- Signed-off-by: Alexandra Tran <[email protected]>
hyperledger · Apr 12, 2023 · a59e369 · a59e369
1 parent 873f2db
commit a59e369
Showing 1 changed file with 174 additions and 0 deletions.
diff --git a/docs/public-networks/reference/engine-api/index.md b/docs/public-networks/reference/engine-api/index.md
@@ -17,6 +17,54 @@ See the [Ethereum Engine API specification](https://github.com/ethereum/executio
 
 ## Methods
 
+### `engine_exchangeCapabilities`
+
+Exchanges a list of supported Engine API methods between the consensus client and Besu.
+
+#### Parameters
+
+`remoteCapabilities`: *array* of *strings* - Engine API method names that the consensus client supports
+
+#### Returns
+
+`localCapabilities`: *array* of *strings* - Engine API method names that Besu supports
+
+!!! example
+
+    === "curl HTTP"
+
+        ```bash
+        curl -X POST --data '{"jsonrpc":"2.0","method":"engine_exchangeCapabilities","params":[["engine_exchangeTransitionConfigurationV1","engine_forkchoiceUpdatedV1","engine_getPayloadBodiesByHash","engine_getPayloadBodiesByRangeV1","engine_getPayloadV1","engine_newPayloadV1"]],"id":67}' http://127.0.0.1:8550
+        ```
+
+    === "wscat WS"
+
+        ```bash
+        {"jsonrpc":"2.0","method":"engine_exchangeCapabilities","params":[["engine_exchangeTransitionConfigurationV1","engine_forkchoiceUpdatedV1","engine_getPayloadBodiesByHash","engine_getPayloadBodiesByRangeV1","engine_getPayloadV1","engine_newPayloadV1"]],"id":67}
+        ```
+
+    === "JSON result"
+
+        ```json
+        {
+            "jsonrpc": "2.0",
+            "id": 67,
+            "result": [
+              "engine_getPayloadV1",
+              "engine_getPayloadV2",
+              "engine_executePayloadV1",
+              "engine_newPayloadV1",
+              "engine_newPayloadV2",
+              "engine_forkchoiceUpdatedV1",
+              "engine_forkchoiceUpdatedV2",
+              "engine_exchangeTransitionConfigurationV1",
+              "engine_getPayloadBodiesByHashV1",
+              "engine_getPayloadBodiesByRangeV1"
+            ]
+          }
+        }
+        ```
+
 ### `engine_exchangeTransitionConfigurationV1`
 
 Sends the transition configuration to the consensus client to verify the configuration between both clients.
@@ -111,6 +159,132 @@ Updates the fork choice with the consensus client.
         }
         ```
 
+### `engine_getPayloadBodiesByHashV1`
+
+Returns the bodies of the execution payloads corresponding to the specified block hashes.
+
+#### Parameters
+
+`blockHashes`: **array** of **strings** - Block hashes
+
+#### Returns
+
+`engineGetPayloadBodiesResultV1`: **array** of **objects** - Execution payload body objects
+
+!!! example
+
+    === "curl HTTP"
+
+        ```bash
+        curl -X POST --data '{"jsonrpc":"2.0","method":"engine_getPayloadBodiesByHashV1","params":[["0xd5f1812548be429cbdc6376b29611fc49e06f1359758c4ceaaa3b393e2239f9c","0xfe88c94d860f01a17f961bf4bdfb6e0c6cd10d3fda5cc861e805ca1240c58553"]],"id":1}' http://127.0.0.1:8550
+        ```
+
+    === "wscat WS"
+
+        ```bash
+        {"jsonrpc":"2.0","method":"engine_getPayloadBodiesByHashV1","params":[["0xd5f1812548be429cbdc6376b29611fc49e06f1359758c4ceaaa3b393e2239f9c","0xfe88c94d860f01a17f961bf4bdfb6e0c6cd10d3fda5cc861e805ca1240c58553"]],"id":67}
+        ```
+
+    === "JSON result"
+
+        ```json
+        {
+            "jsonrpc": "2.0",
+            "id": 67,
+            "result": [{
+              "transactions": ["0xf865808506fc23ac00830124f8940101010101010101010101010101010101010101018031a02c4d88bfdc2f6dbf82c33d235c4e785e9fc23b2d0fc7b9d20fc5e9674f1f9d15a016d6d69b925cf26128683ab4a096e196fbb1142d6c6d4e8d3481b9bef1bd0f65", "0x02f86c0701843b9aca008506fc23ac00830124f89402020202020202020202020202020202020202020180c080a039409b4e5603dd8c3cf38232348661a8e99ac518396eeaa128ec9ec2a3eb8127a06b21ab956f5f138cb44fda1a9055bd08980ea4f8040d877c00dac025608d0d95", ...],
+              "withdrawals": [{
+                "index" : "0xf0",
+                "validatorIndex" : "0xf0",
+                "address" : "0x00000000000000000000000000000000000010f0",
+                "amount" : "0x1"
+              }, {
+                "index" : "0xf1",
+                "validatorIndex" : "0xf1",
+                "address" : "0x00000000000000000000000000000000000010f1",
+                "amount" : "0x1"
+              }]
+            }, {
+              "transactions": ["0xf865108506fc23ac00830124f8940101010101010101010101010101010101010101018031a0d9712a3c40ae85aea4ad1bd95a0b7cc7bd805189a9e2517403b11a00a1530f81a053b53b0267a6dcfe9f9a1652307b396b3e8a65e65707a450e60c92baefdbcfbe", "0x02f86c0711843b9aca008506fc23ac00830124f89402020202020202020202020202020202020202020180c080a071d36bc93c7ae8cc5c01501e51e5e97a51aa541d1a89c809a2af7eb40e9bc2cba071644230e21c075c1da08916aff5efe9f95a6f6a4f94dc217f6c1bb4a3240b29", ...],
+              "withdrawals": [{
+                "index" : "0xf2",
+                "validatorIndex" : "0xf2",
+                "address" : "0x00000000000000000000000000000000000010f2",
+                "amount" : "0x1"
+              }, {
+                "index" : "0xf3",
+                "validatorIndex" : "0xf3",
+                "address" : "0x00000000000000000000000000000000000010f3",
+                "amount" : "0x1"
+              }]
+            }]
+        }
+        ```
+
+### `engine_getPayloadBodiesByRangeV1`
+
+Returns the bodies of the execution payloads corresponding to the specified range of block numbers.
+
+#### Parameters
+
+* `startBlockNumber`: *string* - Number of the starting block of the range, as a hexadecimal string
+
+* `count`: *string* - Number of blocks in the range (including the starting block), as a hexadecimal string
+
+#### Returns
+
+`engineGetPayloadBodiesResultV1`: *array* of *objects* - Execution payload body objects
+
+!!! example
+
+    === "curl HTTP"
+
+        ```bash
+        curl -X POST --data '{"jsonrpc":"2.0","method":"engine_getPayloadBodiesByRangeV1","params":["0x20", "0x2"],"id":1}' http://127.0.0.1:8550
+        ```
+
+    === "wscat WS"
+
+        ```bash
+        {"jsonrpc":"2.0","method":"engine_getPayloadBodiesByRangeV1","params":["0x20", "0x2"],"id":67}
+        ```
+
+    === "JSON result"
+
+        ```json
+        {
+            "jsonrpc": "2.0",
+            "id": 67,
+            "result": [{
+              "transactions": ["0xf865808506fc23ac00830124f8940101010101010101010101010101010101010101018031a02c4d88bfdc2f6dbf82c33d235c4e785e9fc23b2d0fc7b9d20fc5e9674f1f9d15a016d6d69b925cf26128683ab4a096e196fbb1142d6c6d4e8d3481b9bef1bd0f65", "0x02f86c0701843b9aca008506fc23ac00830124f89402020202020202020202020202020202020202020180c080a039409b4e5603dd8c3cf38232348661a8e99ac518396eeaa128ec9ec2a3eb8127a06b21ab956f5f138cb44fda1a9055bd08980ea4f8040d877c00dac025608d0d95", ...],
+              "withdrawals": [{
+                "index" : "0xf0",
+                "validatorIndex" : "0xf0",
+                "address" : "0x00000000000000000000000000000000000010f0",
+                "amount" : "0x1"
+              }, {
+                "index" : "0xf1",
+                "validatorIndex" : "0xf1",
+                "address" : "0x00000000000000000000000000000000000010f1",
+                "amount" : "0x1"
+              }]
+            }, {
+              "transactions": ["0xf865108506fc23ac00830124f8940101010101010101010101010101010101010101018031a0d9712a3c40ae85aea4ad1bd95a0b7cc7bd805189a9e2517403b11a00a1530f81a053b53b0267a6dcfe9f9a1652307b396b3e8a65e65707a450e60c92baefdbcfbe", "0x02f86c0711843b9aca008506fc23ac00830124f89402020202020202020202020202020202020202020180c080a071d36bc93c7ae8cc5c01501e51e5e97a51aa541d1a89c809a2af7eb40e9bc2cba071644230e21c075c1da08916aff5efe9f95a6f6a4f94dc217f6c1bb4a3240b29", ...],
+              "withdrawals": [{
+                "index" : "0xf2",
+                "validatorIndex" : "0xf2",
+                "address" : "0x00000000000000000000000000000000000010f2",
+                "amount" : "0x1"
+              }, {
+                "index" : "0xf3",
+                "validatorIndex" : "0xf3",
+                "address" : "0x00000000000000000000000000000000000010f3",
+                "amount" : "0x1"
+              }]
+            }]
+        }
+        ```
+
 ### `engine_getPayloadV1`
 
 Prepares the payload to send to the consensus client.