From 424074da759f101763c8247732151fedbc0dc225 Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Fri, 15 Oct 2021 06:56:37 -0600 Subject: [PATCH 1/4] revamp request/response description and explictly list all errors --- src/engine/specification.md | 83 ++++++++++++++++++++++++++----------- 1 file changed, 58 insertions(+), 25 deletions(-) diff --git a/src/engine/specification.md b/src/engine/specification.md index 174c2a889..c40012bc9 100644 --- a/src/engine/specification.md +++ b/src/engine/specification.md @@ -11,13 +11,41 @@ This specification is based on [Ethereum JSON-RPC API](https://eth.wiki/json-rpc Client software **MUST** expose Engine API at a port independent from JSON-RPC API. The default port for the Engine API is 8550 for HTTP and 8551 for WebSocket. -## Error codes +## Error The list of error codes introduced by this specification can be found below. -| Code | Possible Return message | Description | +| Code | Message | Meaning | | - | - | - | -| 5 | Unknown payload | Should be used when the `payloadId` parameter of `engine_getPayload` call refers to a payload build process that is unavailable | +| -32700 | Parse error | Invalid JSON was received by the server. | +| -32600 | Invalid Request | The JSON sent is not a valid Request object. | +| -32601 | Method not found | The method does not exist / is not available. | +| -32602 | Invalid params | Invalid method parameter(s). | +| -32603 | Internal error | Internal JSON-RPC error. | +| -32000 | Server error | Generic client error while processing request. | +| -32001 | Unknown payload | Payload does not exist / is not available. | + +Each error returns a `null` `data` value, except `-32000` which returns the `data` object with a `err` member that explains the error encountered. + +For example: + +```console +$ curl https://localhost:8550 \ + -X POST \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","method":"engine_getPayload","params": ["0x1"],"id":1}' +{ + "jsonrpc": "2.0", + "id": 1, + "error": { + "code": -32000, + "message": "Server error", + "data": { + "err": "Database corrupted" + } + } +} +``` ## Structures @@ -54,15 +82,15 @@ This structure contains the attributes required to initiate a payload build proc ### engine_executePayload -#### Parameters -1. `Object` - Instance of [`ExecutionPayload`](#ExecutionPayload) +#### Request -#### Returns -`Object` - Response object: -1. `status`: `String` - the result of the payload execution: - - `VALID` - given payload is valid - - `INVALID` - given payload is invalid - - `SYNCING` - sync process is in progress +* method: `engine_executePayload` +* params: [`ExecutionPayload`](#ExecutionPayload) + +#### Response + +* result: `enum`, `"VALID" | "INVALID" | "SYNCING"` +* error: code and message set in case an exception happens during showing a message. #### Specification @@ -78,18 +106,18 @@ This structure contains the attributes required to initiate a payload build proc ### engine_forkchoiceUpdated -#### Parameters -1. `Object` - The state of the fork choice: -- `headBlockHash`: `DATA`, 32 Bytes - block hash of the head of the canonical chain -- `finalizedBlockHash`: `DATA`, 32 Bytes - block hash of the most recent finalized block -- `payloadAttributes`: `Object|None` - instance of [`PayloadAttributes`](#PayloadAttributes) or `None` +#### Request + +* method: "engine_forkchoiceUpdated" +* params: + 1. `headBlockHash`: `DATA`, 32 Bytes - block hash of the head of the canonical chain + 2. `finalizedBlockHash`: `DATA`, 32 Bytes - block hash of the most recent finalized block + 3. `payloadAttributes`: `Object|null` - instance of [`PayloadAttributes`](#PayloadAttributes) or `null` -#### Returns +#### Response -`Object|Error` - Either instance of response object or an error. Response object: -1. `status`: `String` - The result of updating the fork choice - - `SUCCESS` - The fork choice is successfully updated, and if requested, the payload build process has successfully started - - `SYNCING` - Sync process is in progress +* result: `enum`, `"SUCESS" | "SYNCING"` +* error: code and message set in case an exception happens while updating the forkchoice or preparing the payload. #### Specification @@ -108,11 +136,16 @@ This structure contains the attributes required to initiate a payload build proc ### engine_getPayload -#### Parameters -1. `payloadId`: `DATA`, 8 bytes - Identifier of the payload build process +#### Request + +* method: `engine_getPayload` +* params: + 1. `payloadId`: `DATA`, 8 bytes - Identifier of the payload build process + +#### Response -#### Returns -`Object|Error` - Either instance of [`ExecutionPayload`](#ExecutionPayload) or an error +* result: [`ExecutionPayload`](#ExecutionPayload) +* error: code and message set in case an exception happens while getting the payload. #### Specification From 56a15caf5534193eef285e60335c1846f35a48af Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Fri, 15 Oct 2021 07:01:53 -0600 Subject: [PATCH 2/4] fix typo --- src/engine/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/engine/specification.md b/src/engine/specification.md index c40012bc9..b78867199 100644 --- a/src/engine/specification.md +++ b/src/engine/specification.md @@ -11,7 +11,7 @@ This specification is based on [Ethereum JSON-RPC API](https://eth.wiki/json-rpc Client software **MUST** expose Engine API at a port independent from JSON-RPC API. The default port for the Engine API is 8550 for HTTP and 8551 for WebSocket. -## Error +## Errors The list of error codes introduced by this specification can be found below. From c8984d779413032b6ea9d4bcddaec540407fa0fe Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Fri, 15 Oct 2021 07:03:44 -0600 Subject: [PATCH 3/4] explicitly define executePayload param as the first ordered param --- src/engine/specification.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/engine/specification.md b/src/engine/specification.md index b78867199..3b682d886 100644 --- a/src/engine/specification.md +++ b/src/engine/specification.md @@ -85,7 +85,8 @@ This structure contains the attributes required to initiate a payload build proc #### Request * method: `engine_executePayload` -* params: [`ExecutionPayload`](#ExecutionPayload) +* params: + 1. [`ExecutionPayload`](#ExecutionPayload) #### Response From 58e708a3df4c38771741c72a28153a4ba87d049d Mon Sep 17 00:00:00 2001 From: lightclient <14004106+lightclient@users.noreply.github.com> Date: Sat, 16 Oct 2021 07:41:31 -0600 Subject: [PATCH 4/4] Update src/engine/specification.md Co-authored-by: Danny Ryan --- src/engine/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/engine/specification.md b/src/engine/specification.md index 3b682d886..c50724e43 100644 --- a/src/engine/specification.md +++ b/src/engine/specification.md @@ -117,7 +117,7 @@ This structure contains the attributes required to initiate a payload build proc #### Response -* result: `enum`, `"SUCESS" | "SYNCING"` +* result: `enum`, `"SUCCESS" | "SYNCING"` * error: code and message set in case an exception happens while updating the forkchoice or preparing the payload. #### Specification