EIP-8025

apis/beacon/proofs/execution_proofs.yaml

@@ -0,0 +1,60 @@
+get:
+  operationId: getExecutionProofs
+  summary: Get execution proofs
+  description: |
+    Retrieves execution proofs for a given block id.
+    Depending on `Accept` header it can be returned either as JSON or as bytes serialized by SSZ.
+
+    Proofs are returned as an ordered list of `ProverSignedExecutionProof` objects.
+
+    Proofs are only available for recent blocks within the proof retention period.
+  tags:
+    - Beacon
+  parameters:
+    - name: block_id
+      in: path
+      required: true
+      $ref: "../../../beacon-node-oapi.yaml#/components/parameters/BlockId"
+  responses:
+    "200":
+      description: Successful response
+      content:
+        application/json:
+          schema:
+            title: GetExecutionProofsResponse
+            type: object
+            required: [execution_optimistic, finalized, data]
+            properties:
+              execution_optimistic:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
+              finalized:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized"
+              data:
+                type: array
+                items:
+                  $ref: '../../../beacon-node-oapi.yaml#/components/schemas/EIP8025.ProverSignedExecutionProof'
+        application/octet-stream:
+          schema:
+            description: "SSZ serialized `List[ProverSignedExecutionProof, MAX_EXECUTION_PROOFS_PER_PAYLOAD]` bytes. Use Accept header to choose this response type"
+    "400":
+      description: "The block ID supplied could not be parsed"
+      content:
+        application/json:
+          schema:
+            $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
+          example:
+            code: 400
+            message: "Invalid block ID: current"
+    "404":
+      description: "Block not found"
+      content:
+        application/json:
+          schema:
+            $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
+          example:
+            code: 404
+            message: "Block not found"
+    "406":
+      $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable"
+    "500":
+      $ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError'

apis/prover/execution_proofs.yaml

@@ -0,0 +1,31 @@
+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.
+    Each proof includes the `proof_gen_id` to link it to the original proof generation request.
+  tags:
+    - Prover
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          type: array
+          items:
+            $ref: '../../beacon-node-oapi.yaml#/components/schemas/EIP8025.GeneratedProof'
+      application/octet-stream:
+        schema:
+          description: "SSZ serialized List[GeneratedProof, 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

@@ -62,6 +62,8 @@ tags:
       [Checkout validator flow](./validator-flow.md) to learn how to use this api.
   - name: Rewards
     description: Endpoints to query rewards and penalties for validators.
+  - name: Prover
+    description: Endpoints for execution proof generation and submission.
 
 paths:
 
@@ -144,6 +146,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/{block_id}:
+    $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 +439,16 @@ components:
       $ref: "./types/fulu/block_contents.yaml#/Fulu/SignedBlockContents"
     Fulu.DataColumnSidecars:
       $ref: "./types/fulu/data_column_sidecar.yaml#/Fulu/DataColumnSidecars"
+    EIP8025.ProofGenId:
+      $ref: './types/eip8025/execution_proof.yaml#/EIP8025/ProofGenId'
+    EIP8025.PublicInput:
+      $ref: './types/eip8025/execution_proof.yaml#/EIP8025/PublicInput'
+    EIP8025.ExecutionProof:
+      $ref: './types/eip8025/execution_proof.yaml#/EIP8025/ExecutionProof'
+    EIP8025.GeneratedProof:
+      $ref: './types/eip8025/execution_proof.yaml#/EIP8025/GeneratedProof'
+    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,58 @@
+EIP8025:
+  ProofGenId:
+    type: string
+    format: hex
+    pattern: "^0x[a-fA-F0-9]{16}$"
+    description: "8-byte identifier for tracking proof generation requests"
+    example: "0x0102030405060708"
+
+  GeneratedProof:
+    type: object
+    description: "Generated execution proof with associated proof generation ID"
+    required: [proof_gen_id, execution_proof]
+    properties:
+      proof_gen_id:
+        $ref: '#/EIP8025/ProofGenId'
+        description: "ID linking this proof to the original request"
+      execution_proof:
+        $ref: '#/EIP8025/ExecutionProof'
+
+  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"