eip8025

Author: frisitano

apis/beacon/proofs/execution_proofs.yaml

@@ -0,0 +1,39 @@
+get:
+  operationId: getExecutionProofs
+  summary: Get execution proofs
+  description: |
+    Retrieves execution proofs known by the node.
+  parameters:
+    - name: new_payload_request_root
+      in: query
+      required: false
+      schema:
+        $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Root'
+      description: "Filter by new payload request root"
+  tags:
+    - Beacon
+  responses:
+    "200":
+      description: Successful response
+      content:
+        application/json:
+          schema:
+            title: GetExecutionProofsResponse
+            type: object
+            required: [data]
+            properties:
+              data:
+                type: array
+                items:
+                  $ref: '../../../beacon-node-oapi.yaml#/components/schemas/EIP8025.ProverSignedExecutionProof'
+    "400":
+      description: "The new_payload_request_root could not be parsed"
+      content:
+        application/json:
+          schema:
+            $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
+          example:
+            code: 400
+            message: "Invalid new_payload_request_root"
+    "500":
+      $ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError'

apis/prover/execution_proofs.yaml

@@ -0,0 +1,30 @@
+post:
+  operationId: submitExecutionProofs
+  summary: Submit execution proofs from proof engine
+  description: |
+    Receives unsigned execution proofs from the proof engine. The beacon node
+    validates, signs, stores, and broadcasts them on the `execution_proof` gossip topic.
+  tags:
+    - Prover
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          type: array
+          items:
+            $ref: '../../beacon-node-oapi.yaml#/components/schemas/EIP8025.ExecutionProof'
+      application/octet-stream:
+        schema:
+          description: "SSZ serialized List[ExecutionProof, MAX_EXECUTION_PROOFS_PER_PAYLOAD]"
+  responses:
+    "200":
+      description: "Proofs received and validated successfully"
+    "400":
+      description: "One or more proofs failed validation or do not match pending requests"
+      content:
+        application/json:
+          schema:
+            $ref: "../../beacon-node-oapi.yaml#/components/schemas/IndexedErrorMessage"
+    "500":
+      $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError'

beacon-node-oapi.yaml

@@ -144,6 +144,10 @@ paths:
     $ref: "./apis/beacon/pool/voluntary_exits.yaml"
   /eth/v1/beacon/pool/bls_to_execution_changes:
     $ref: "./apis/beacon/pool/bls_to_execution_changes.yaml"
+  /eth/v1/beacon/proofs/execution_proofs:
+    $ref: "./apis/beacon/proofs/execution_proofs.yaml"
+  /eth/v1/prover/execution_proofs:
+    $ref: "./apis/prover/execution_proofs.yaml"
 
   /eth/v2/debug/beacon/states/{state_id}:
     $ref: './apis/debug/state.v2.yaml'
@@ -433,6 +437,12 @@ components:
       $ref: "./types/fulu/block_contents.yaml#/Fulu/SignedBlockContents"
     Fulu.DataColumnSidecars:
       $ref: "./types/fulu/data_column_sidecar.yaml#/Fulu/DataColumnSidecars"
+    EIP8025.PublicInput:
+      $ref: './types/eip8025/execution_proof.yaml#/EIP8025/PublicInput'
+    EIP8025.ExecutionProof:
+      $ref: './types/eip8025/execution_proof.yaml#/EIP8025/ExecutionProof'
+    EIP8025.ProverSignedExecutionProof:
+      $ref: './types/eip8025/execution_proof.yaml#/EIP8025/ProverSignedExecutionProof'
     Node:
       $ref: './types/fork_choice.yaml#/Node'
     ExtraData:

types/eip8025/execution_proof.yaml

@@ -0,0 +1,40 @@
+EIP8025:
+  PublicInput:
+    type: object
+    description: "Public input for execution proof verification"
+    required: [new_payload_request_root]
+    properties:
+      new_payload_request_root:
+        $ref: '../primitive.yaml#/Root'
+        description: "Root of the NewPayloadRequest being proven"
+
+  ExecutionProof:
+    type: object
+    description: "Unsigned execution proof for stateless validation"
+    required: [proof_data, proof_type, public_input]
+    properties:
+      proof_data:
+        type: string
+        format: hex
+        pattern: "^0x[a-fA-F0-9]{0,614400}$"
+        description: "Proof data, max 300KiB (307200 bytes = 614400 hex chars)"
+        example: "0x1234567890abcdef"
+      proof_type:
+        $ref: '../primitive.yaml#/Uint8'
+        description: "Type identifier for the proof system"
+      public_input:
+        $ref: '#/EIP8025/PublicInput'
+
+  ProverSignedExecutionProof:
+    type: object
+    description: "Execution proof signed by a whitelisted prover"
+    required: [message, prover_pubkey, signature]
+    properties:
+      message:
+        $ref: '#/EIP8025/ExecutionProof'
+      prover_pubkey:
+        $ref: '../primitive.yaml#/Pubkey'
+        description: "BLS public key of the prover"
+      signature:
+        $ref: '../primitive.yaml#/Signature'
+        description: "BLS signature over the execution proof"