Add EIP-7805 (FOCIL) endpoints

apis/eventstream/index.yaml

@@ -38,6 +38,7 @@ get:
             - light_client_optimistic_update
             - payload_attributes
             - blob_sidecar
+            - inclusion_list
   responses:
     "200":
       description: Opened SSE stream.
@@ -152,6 +153,11 @@ get:
               value: |
                 event: blob_sidecar
                 data: {"block_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "index": "1", "slot": "1", "kzg_commitment": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505", "versioned_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"}
+            inclusion_list:
+              description: (EIP-7805) The node has received a SignedInclusionList (from P2P or API) that passes validation rules of the `inclusion_list` topic
+              value: |
+                event: inclusion_list
+                data: {"version": "eip7805", "data": {"message": {"slot": "0", "validator_index": "0", "inclusion_list_committee_root": "0x0000000000000000000000000000000000000000000000000000000000000000", "transactions": ["0x0000000000000000000000000000000000000000000000000000000000000000"]}, "signature": "0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"}}
     "400":
       description: "The topics supplied could not be parsed"
       content:

apis/validator/duties/inclusion_list.yaml

@@ -0,0 +1,71 @@
+post:
+  tags:
+    - EIP-7805
+  summary: "Get inclusion list committee duties"
+  operationId: "getInclusionListCommitteeDuties"
+  description:
+    "Requests the beacon node to provide a set of inclusion list committee duties for a particular epoch.
+
+    Duties should only need to be checked once per epoch,
+    however a chain reorganization (of > MIN_SEED_LOOKAHEAD epochs) could occur,
+    resulting in a change of duties. For full safety, you should monitor head events and confirm the
+    dependent root in this response matches:
+
+      - event.previous_duty_dependent_root when `compute_epoch_at_slot(event.slot) == epoch`
+
+      - event.current_duty_dependent_root when `compute_epoch_at_slot(event.slot) + 1 == epoch`
+
+      - event.block otherwise
+
+
+    The dependent_root value is `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 1) - 1)`
+    or the genesis block root in the case of underflow."
+  parameters:
+    - name: epoch
+      description: "Should only be allowed 1 epoch ahead"
+      in: path
+      required: true
+      schema:
+        $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Uint64"
+  requestBody:
+    description: "An array of the validator indices for which to obtain the duties."
+    required: true
+    content:
+      application/json:
+        schema:
+          title: GetInclusionListCommitteeDutiesBody
+          type: array
+          minItems: 1
+          items:
+            $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Uint64"
+  responses:
+    "200":
+      description: Success response
+      content:
+        application/json:
+          schema:
+            title: GetInclusionListCommitteeDutiesResponse
+            type: object
+            required: [dependent_root, execution_optimistic, data]
+            properties:
+              dependent_root:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/DependentRoot"
+              execution_optimistic:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
+              data:
+                type: array
+                items:
+                  $ref: "../../../beacon-node-oapi.yaml#/components/schemas/EIP7805.InclusionListDuty"
+    "400":
+      description: "Invalid epoch or index"
+      content:
+        application/json:
+          schema:
+            $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
+          example:
+            code: 400
+            message: "Invalid epoch: -2"
+    "500":
+      $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError"
+    "503":
+      $ref: "../../../beacon-node-oapi.yaml#/components/responses/CurrentlySyncing"

apis/validator/inclusion_list.yaml

@@ -0,0 +1,62 @@
+get:
+  tags:
+    - EIP-7805
+  operationId: "produceInclusionList"
+  summary: "Produce an inclusion list"
+  description: Requests the beacon node to produce an inclusion list.
+  parameters:
+    - name: slot
+      in: query
+      required: true
+      description: "The slot for which an inclusion list should be created."
+      schema:
+        $ref: ../../beacon-node-oapi.yaml#/components/schemas/Uint64
+  responses:
+    "200":
+      description: Success response
+      content:
+        application/json:
+          schema:
+            title: ProduceInclusionListResponse
+            type: object
+            required: [data]
+            properties:
+              data:
+                $ref: "../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.Transactions"
+    "400":
+      $ref: "../../beacon-node-oapi.yaml#/components/responses/InvalidRequest"
+    "500":
+      $ref: "../../beacon-node-oapi.yaml#/components/responses/InternalError"
+    "503":
+      $ref: "../../beacon-node-oapi.yaml#/components/responses/CurrentlySyncing"
+
+post:
+  tags:
+    - EIP-7805
+  operationId: "publishInclusionList"
+  summary: "Publish an inclusion list"
+  description: "Verifies given inclusion list and publishes it on appropriate gossipsub topic."
+  parameters:
+    - in: header
+      schema:
+        $ref: "../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion"
+      required: true
+      name: Eth-Consensus-Version
+      description: "The active consensus version to which the inclusion list being submitted belongs."
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          type: object
+          required: [data]
+          properties:
+            data:
+              $ref: "../../beacon-node-oapi.yaml#/components/schemas/EIP7805.SignedInclusionList"
+  responses:
+    "200":
+      description: "Successful response"
+    "400":
+      $ref: "../../beacon-node-oapi.yaml#/components/responses/InvalidRequest"
+    "500":
+      $ref: "../../beacon-node-oapi.yaml#/components/responses/InternalError"

beacon-node-oapi.yaml

@@ -64,6 +64,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: EIP-7805
+    description: "Endpoints required for EIP-7805: Fork-choice enforced Inclusion Lists (FOCIL)"
 
 paths:
 
@@ -184,6 +186,8 @@ paths:
     $ref: "./apis/validator/duties/proposer.yaml"
   /eth/v1/validator/duties/sync/{epoch}:
     $ref: "./apis/validator/duties/sync.yaml"
+  /eth/v1/validator/duties/inclusion_list/{epoch}:
+    $ref: "./apis/validator/duties/inclusion_list.yaml"
   /eth/v3/validator/blocks/{slot}:
     $ref: "./apis/validator/block.v3.yaml"
   /eth/v1/validator/attestation_data:
@@ -214,6 +218,8 @@ paths:
     $ref: "./apis/validator/register_validator.yaml"
   /eth/v1/validator/liveness/{epoch}:
     $ref: "./apis/validator/liveness.yaml"
+  /eth/v1/validator/inclusion_list:
+    $ref: "./apis/validator/inclusion_list.yaml"
 
   /eth/v1/events:
     $ref: "./apis/eventstream/index.yaml"
@@ -257,6 +263,8 @@ components:
       $ref: './types/validator.yaml#/ProposerDuty'
     Altair.SyncDuty:
       $ref: './types/validator.yaml#/Altair/SyncDuty'
+    EIP7805.InclusionListDuty:
+      $ref: './types/validator.yaml#/EIP7805/InclusionListDuty'
     SignedAggregateAndProof:
       $ref: './types/validator.yaml#/SignedAggregateAndProof'
     Attestation:
@@ -343,6 +351,8 @@ components:
       $ref: './types/bellatrix/block.yaml#/Bellatrix/BlindedBeaconBlock'
     Bellatrix.SignedBlindedBeaconBlock:
       $ref: './types/bellatrix/block.yaml#/Bellatrix/SignedBlindedBeaconBlock'
+    Bellatrix.Transactions:
+      $ref: './types/bellatrix/transactions.yaml#/Bellatrix/Transactions'
     ConsensusVersion:
       type: string
       enum: [phase0, altair, bellatrix, capella, deneb, electra]
@@ -423,6 +433,10 @@ components:
       $ref: './types/electra/light_client.yaml#/Electra/LightClientFinalityUpdate'
     Electra.LightClientOptimisticUpdate:
       $ref: './types/electra/light_client.yaml#/Electra/LightClientOptimisticUpdate'
+    EIP7805.InclusionList:
+      $ref: './types/eip7805/inclusion_list.yaml#/EIP7805/InclusionList'
+    EIP7805.SignedInclusionList:
+      $ref: './types/eip7805/inclusion_list.yaml#/EIP7805/SignedInclusionList'
     Node:
       $ref: './types/fork_choice.yaml#/Node'
     ExtraData:

types/eip7805/inclusion_list.yaml

@@ -0,0 +1,24 @@
+EIP7805:
+  InclusionList:
+    type: object
+    description: "The [`InclusionList`](https://github.com/ethereum/consensus-specs/blob/702b9e5c320d5e35bc49d45f07bfc0db7565ec88/specs/_features/eip7805/beacon-chain.md#inclusionlist) object from the CL spec."
+    required: [slot, validator_index, inclusion_list_committee_root, transactions]
+    properties:
+      slot:
+        $ref: "../primitive.yaml#/Uint64"
+      validator_index:
+        $ref: "../primitive.yaml#/Uint64"
+      inclusion_list_committee_root:
+        $ref: "../primitive.yaml#/Root"
+      transactions:
+        $ref: "../bellatrix/transactions.yaml#/Bellatrix/Transactions"
+
+  SignedInclusionList:
+    type: object
+    description: "The [`SignedInclusionList`](https://github.com/ethereum/consensus-specs/blob/702b9e5c320d5e35bc49d45f07bfc0db7565ec88/specs/_features/eip7805/beacon-chain.md#signedinclusionlist) object from the CL spec."
+    required: [message, signature]
+    properties:
+      message:
+        $ref: "#/EIP7805/InclusionList"
+      signature:
+        $ref: "../primitive.yaml#/Signature"

types/validator.yaml

@@ -111,3 +111,20 @@ SignedAggregateAndProof:
       $ref: "#/AggregateAndProof"
     signature:
       $ref: "./primitive.yaml#/Signature"
+
+EIP7805:
+ InclusionListDuty:
+  type: object
+  required: [pubkey, validator_index, slot, inclusion_list_committee_root]
+  properties:
+    pubkey:
+      $ref: "./primitive.yaml#/Pubkey"
+    validator_index:
+      $ref: "./primitive.yaml#/Uint64"
+      description: "Index of validator in validator registry."
+    slot:
+      $ref: "./primitive.yaml#/Uint64"
+      description: "The slot at which the validator must propose an inclusion list." 
+    inclusion_list_committee_root:
+      $ref: "./primitive.yaml#/Root"
+      description: "The root of inclusion list committee that the validator is part of."

wordlist.txt

@@ -36,3 +36,6 @@ KZGProof
 KZGProofs
 KZGCommitmentInclusionProof
 LMD
+EIPs
+FOCIL
+eip7805