Engine API: define Open RPC schema (#379)

* Initial Engine API schema * Move Engine API schema to ./engine/openrpc/ * Add schema for V2 * Deduplicate fcU response * Fix spellcheck * Add schema for payload bodies requests * Apply suggestions from code review Co-authored-by: lightclient <14004106+lightclient@users.noreply.github.com> * Fix broken link * Apply @lightclient's suggestions --------- Co-authored-by: lightclient <14004106+lightclient@users.noreply.github.com>
ethereum · Mar 27, 2023 · bf134c9 · bf134c9
1 parent 8121c06
commit bf134c9
Show file tree

Hide file tree

Showing 11 changed files with 518 additions and 1 deletion.
diff --git a/scripts/build.js b/scripts/build.js
@@ -30,6 +30,18 @@ methodFiles.forEach(file => {
   ];
 });
 
+methodsBase = "src/engine/openrpc/methods/";
+methodFiles = fs.readdirSync(methodsBase);
+methodFiles.forEach(file => {
+  console.log(file);
+  let raw = fs.readFileSync(methodsBase + file);
+  let parsed = yaml.load(raw);
+  methods = [
+    ...methods,
+    ...parsed,
+  ];
+});
+
 let schemas = {};
 let schemasBase = "src/schemas/"
 let schemaFiles = fs.readdirSync(schemasBase);
@@ -42,6 +54,19 @@ schemaFiles.forEach(file => {
     ...parsed,
   };
 });
+
+schemasBase = "src/engine/openrpc/schemas/"
+schemaFiles = fs.readdirSync(schemasBase);
+schemaFiles.forEach(file => {
+  console.log(file);
+  let raw = fs.readFileSync(schemasBase + file);
+  let parsed = yaml.load(raw);
+  schemas = {
+    ...schemas,
+    ...parsed,
+  };
+});
+
 const doc = {
   openrpc: "1.2.4",
   info: {

diff --git a/spellcheck.yaml b/spellcheck.yaml
@@ -26,6 +26,7 @@ matrix:
     aspell:
       lang: en
       d: en_US
+      ignore-case: true
       run-together: true
       run-together-min: 2
       run-together-limit: 256

diff --git a/src/engine/openrpc/methods/capabilities.yaml b/src/engine/openrpc/methods/capabilities.yaml
@@ -0,0 +1,18 @@
+- name: engine_exchangeCapabilities
+  summary: Exchanges list of supported Engine API methods
+  externalDocs:
+    description: Method specification
+    url: https://github.com/ethereum/execution-apis/blob/main/src/engine/common.md#engine_exchangecapabilities
+  params:
+    - name: Consensus client methods
+      required: true
+      schema:
+        type: array
+        items:
+          type: string
+  result:
+    name: Execution client methods
+    schema:
+      type: array
+      items:
+        type: string
diff --git a/src/engine/openrpc/methods/forkchoice.yaml b/src/engine/openrpc/methods/forkchoice.yaml
@@ -0,0 +1,46 @@
+- name: engine_forkchoiceUpdatedV1
+  summary: Updates the forkchoice state
+  externalDocs:
+    description: Method specification
+    url: https://github.com/ethereum/execution-apis/blob/main/src/engine/paris.md#engine_forkchoiceupdatedv1
+  params:
+    - name: Forkchoice state
+      required: true
+      schema:
+        $ref: '#/components/schemas/ForkchoiceStateV1'
+    - name: Payload attributes
+      required: false
+      schema:
+        $ref: '#/components/schemas/PayloadAttributesV1'
+  result:
+    name: Response object
+    schema:
+      $ref: '#/components/schemas/ForkchoiceUpdatedResponseV1'
+  errors:
+    - code: -38002
+      message: Invalid forkchoice state
+    - code: -38003
+      message: Invalid payload attributes
+- name: engine_forkchoiceUpdatedV2
+  summary: Updates the forkchoice state
+  externalDocs:
+    description: Method specification
+    url: https://github.com/ethereum/execution-apis/blob/main/src/engine/shanghai.md#engine_forkchoiceupdatedv2
+  params:
+    - name: Forkchoice state
+      required: true
+      schema:
+        $ref: '#/components/schemas/ForkchoiceStateV1'
+    - name: Payload attributes
+      required: false
+      schema:
+        $ref: '#/components/schemas/PayloadAttributesV2'
+  result:
+    name: Response object
+    schema:
+      $ref: '#/components/schemas/ForkchoiceUpdatedResponseV1'
+  errors:
+    - code: -38002
+      message: Invalid forkchoice state
+    - code: -38003
+      message: Invalid payload attributes
diff --git a/src/engine/openrpc/methods/payload.yaml b/src/engine/openrpc/methods/payload.yaml
@@ -0,0 +1,123 @@
+- name: engine_newPayloadV1
+  summary: Runs execution payload validation
+  externalDocs:
+    description: Method specification
+    url: https://github.com/ethereum/execution-apis/blob/main/src/engine/paris.md#engine_newpayloadv1
+  params:
+    - name: Execution payload
+      required: true
+      schema:
+        $ref: '#/components/schemas/ExecutionPayloadV1'
+  result:
+    name: Payload status
+    schema:
+      $ref: '#/components/schemas/PayloadStatusV1'
+- name: engine_newPayloadV2
+  summary: Runs execution payload validation
+  externalDocs:
+    description: Method specification
+    url: https://github.com/ethereum/execution-apis/blob/main/src/engine/shanghai.md#engine_newpayloadv2
+  params:
+    - name: Execution payload
+      required: true
+      schema:
+        oneOf:
+          - $ref: '#/components/schemas/ExecutionPayloadV1'
+          - $ref: '#/components/schemas/ExecutionPayloadV2'
+  result:
+    name: Payload status
+    schema:
+      $ref: '#/components/schemas/PayloadStatusNoInvalidBlockHash'
+  errors:
+    - code: -32602
+      message: Invalid params
+- name: engine_getPayloadV1
+  summary: Obtains execution payload from payload build process
+  externalDocs:
+    description: Method specification
+    url: https://github.com/ethereum/execution-apis/blob/main/src/engine/paris.md#engine_getpayloadv1
+  params:
+    - name: Payload id
+      required: true
+      schema:
+        $ref: '#/components/schemas/bytes8'
+  result:
+    name: Execution payload
+    schema:
+      $ref: '#/components/schemas/ExecutionPayloadV1'
+  errors:
+    - code: -38001
+      message: Unknown payload
+- name: engine_getPayloadV2
+  summary: Obtains execution payload from payload build process
+  externalDocs:
+    description: Method specification
+    url: https://github.com/ethereum/execution-apis/blob/main/src/engine/shanghai.md#engine_getpayloadv2
+  params:
+    - name: Payload id
+      required: true
+      schema:
+        $ref: '#/components/schemas/bytes8'
+  result:
+    name: Response object
+    schema:
+      type: object
+      required:
+        - executionPayload
+        - blockValue
+      properties:
+        executionPayload:
+          title: Execution payload
+          oneOf:
+            - $ref: '#/components/schemas/ExecutionPayloadV1'
+            - $ref: '#/components/schemas/ExecutionPayloadV2'
+        blockValue:
+          title: Expected fee value
+          $ref: '#/components/schemas/uint256'
+  errors:
+    - code: -38001
+      message: Unknown payload
+- name: engine_getPayloadBodiesByHashV1
+  summary: Given block hashes returns bodies of the corresponding execution payloads
+  externalDocs:
+    description: Method specification
+    url: https://github.com/ethereum/execution-apis/blob/main/src/engine/shanghai.md#engine_getpayloadbodiesbyhashv1
+  params:
+    - name: Array of block hashes
+      required: true
+      schema:
+        type: array
+        items:
+          $ref: '#/components/schemas/hash32'
+  result:
+    name: Execution payload bodies
+    schema:
+      type: array
+      items:
+        $ref: '#/components/schemas/ExecutionPayloadBodyV1'
+  errors:
+    - code: -38004
+      message: Too large request
+- name: engine_getPayloadBodiesByRangeV1
+  summary: Given a range of block numbers returns bodies of the corresponding execution payloads
+  externalDocs:
+    description: Method specification
+    url: https://github.com/ethereum/execution-apis/blob/main/src/engine/shanghai.md#engine_getpayloadbodiesbyrangev1
+  params:
+    - name: Starting block number
+      required: true
+      schema:
+        $ref: '#/components/schemas/uint64'
+    - name: Number of blocks to return
+      required: true
+      schema:
+        $ref: '#/components/schemas/uint64'
+  result:
+    name: Execution payload bodies
+    schema:
+      type: array
+      items:
+        $ref: '#/components/schemas/ExecutionPayloadBodyV1'
+  errors:
+    - code: -38004
+      message: Too large request
diff --git a/src/engine/openrpc/methods/transition_configuration.yaml b/src/engine/openrpc/methods/transition_configuration.yaml
@@ -0,0 +1,14 @@
+- name: engine_exchangeTransitionConfigurationV1
+  summary: Exchanges transition configuration
+  externalDocs:
+    description: Method specification
+    url: https://github.com/ethereum/execution-apis/blob/main/src/engine/paris.md#engine_exchangetransitionconfigurationv1
+  params:
+    - name: Consensus client configuration
+      required: true
+      schema:
+        $ref: '#/components/schemas/TransitionConfigurationV1'
+  result:
+    name: Execution client configuration
+    schema:
+      $ref: '#/components/schemas/TransitionConfigurationV1'
diff --git a/src/engine/openrpc/schemas/forkchoice.yaml b/src/engine/openrpc/schemas/forkchoice.yaml
@@ -0,0 +1,66 @@
+ForkchoiceStateV1:
+  title: Forkchoice state object V1
+  type: object
+  required:
+    - headBlockHash
+    - safeBlockHash
+    - finalizedBlockHash
+  properties:
+    headBlockHash:
+      title: Head block hash
+      $ref: '#/components/schemas/hash32'
+    safeBlockHash:
+      title: Safe block hash
+      $ref: '#/components/schemas/hash32'
+    finalizedBlockHash:
+      title: Finalized block hash
+      $ref: '#/components/schemas/hash32'
+ForkchoiceUpdatedResponseV1:
+  title: Forkchoice updated response
+  type: object
+  required:
+    - payloadStatus
+  properties:
+    payloadStatus:
+      title: Payload status
+      $ref: '#/components/schemas/RestrictedPayloadStatusV1'
+    payloadId:
+      title: Payload id
+      $ref: '#/components/schemas/bytes8'
+PayloadAttributesV1:
+  title: Payload attributes object V1
+  type: object
+  required:
+    - timestamp
+    - prevRandao
+    - suggestedFeeRecipient
+  properties:
+    timestamp:
+      title: Timestamp
+      $ref: '#/components/schemas/uint64'
+    prevRandao:
+      title: Previous randao value
+      $ref: '#/components/schemas/bytes32'
+    suggestedFeeRecipient:
+      title: Suggested fee recipient
+      $ref: '#/components/schemas/address'
+PayloadAttributesV2:
+  title: Payload attributes object V2
+  type: object
+  required:
+    - timestamp
+    - prevRandao
+    - suggestedFeeRecipient
+    - withdrawals
+  properties:
+    timestamp:
+      $ref: '#/components/schemas/PayloadAttributesV1/properties/timestamp'
+    prevRandao:
+      $ref: '#/components/schemas/PayloadAttributesV1/properties/prevRandao'
+    suggestedFeeRecipient:
+      $ref: '#/components/schemas/PayloadAttributesV1/properties/suggestedFeeRecipient'
+    withdrawals:
+      title: Withdrawals
+      type: array
+      items:
+        $ref: '#/components/schemas/WithdrawalV1'