address PR comments

Author: frisitano

apis/beacon/proofs/execution_proofs.yaml

@@ -2,16 +2,19 @@ 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"
+    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
@@ -20,20 +23,38 @@ get:
           schema:
             title: GetExecutionProofsResponse
             type: object
-            required: [data]
+            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 new_payload_request_root could not be parsed"
+      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 new_payload_request_root"
+            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

@@ -4,6 +4,7 @@ post:
   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:
@@ -13,10 +14,10 @@ post:
         schema:
           type: array
           items:
-            $ref: '../../beacon-node-oapi.yaml#/components/schemas/EIP8025.ExecutionProof'
+            $ref: '../../beacon-node-oapi.yaml#/components/schemas/EIP8025.GeneratedProof'
       application/octet-stream:
         schema:
-          description: "SSZ serialized List[ExecutionProof, MAX_EXECUTION_PROOFS_PER_PAYLOAD]"
+          description: "SSZ serialized List[GeneratedProof, MAX_EXECUTION_PROOFS_PER_PAYLOAD]"
   responses:
     "200":
       description: "Proofs received and validated successfully"

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,7 +146,7 @@ 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:
+  /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"
@@ -437,10 +439,14 @@ 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:

types/eip8025/execution_proof.yaml

@@ -1,4 +1,22 @@
 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"