Add EIP-7805 (FOCIL) endpoints

apis/eventstream/index.yaml

@@ -39,6 +39,7 @@ get:
             - payload_attributes
             - blob_sidecar
             - data_column_sidecar
+            - inclusion_list
   responses:
     "200":
       description: Opened SSE stream.
@@ -147,7 +148,8 @@ get:
                 ignored by block builders and most other API consumers.
               value: |
                 event: payload_attributes
-                data: {"version": "capella", "data": {"proposer_index": "123", "proposal_slot": "10", "parent_block_number": "9", "parent_block_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "parent_block_hash": "0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "payload_attributes": {"timestamp": "123456", "prev_randao": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "suggested_fee_recipient": "0x0000000000000000000000000000000000000000", "withdrawals": [{"index": "5", "validator_index": "10", "address": "0x0000000000000000000000000000000000000000", "amount": "15640"}]}}}
+                data: {"version": "eip7805", "data": {"proposer_index": "123", "proposal_slot": "10", "parent_block_number": "9", "parent_block_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "parent_block_hash": "0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "payload_attributes": {"timestamp": "123456", "prev_randao": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "suggested_fee_recipient": "0x0000000000000000000000000000000000000000", "withdrawals": [{"index": "5", "validator_index": "10", "address": "0x0000000000000000000000000000000000000000", "amount": "15640"}], "parent_beacon_block_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "inclusion_list_transactions": ["0x03f88f0780843b9aca008506fc23ac00830186a09400000000000000000000000000000000000001008080c001e1a0010657f37554c781402a22917dee2f75def7ab966d7b770905398eba3c44401401a0840650aa8f74d2b07f40067dc33b715078d73422f01da17abdbd11e02bbdfda9a04b2260f6022bf53eadb337b3e59514936f7317d872defb891a708ee279bdca90"]}}}
+
             blob_sidecar:
               description: The node has received a BlobSidecar (from P2P or API) that passes all gossip validations on the blob_sidecar_{subnet_id} topic
               value: |
@@ -158,6 +160,11 @@ get:
               value: |
                 event: data_column_sidecar
                 data: {"block_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "index": "1", "slot": "1", "kzg_commitments": ["0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"]}
+            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

@@ -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: EIP-7805
+    description: "Endpoints required for EIP-7805: Fork-choice enforced Inclusion Lists (FOCIL)"
 
 paths:
 
@@ -178,6 +180,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:
@@ -204,6 +208,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"
@@ -229,6 +235,8 @@ components:
       $ref: './types/duty.yaml#/ProposerDuty'
     Altair.SyncDuty:
       $ref: './types/duty.yaml#/Altair/SyncDuty'
+    EIP7805.InclusionListDuty:
+      $ref: './types/duty.yaml#/EIP7805/InclusionListDuty'
     BeaconCommitteeSelection:
       $ref: './types/selection.yaml#/BeaconCommitteeSelection'
     SyncCommitteeSelection:
@@ -329,6 +337,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, fulu]
@@ -425,6 +435,10 @@ components:
       $ref: "./types/fulu/block_contents.yaml#/Fulu/SignedBlockContents"
     Fulu.DataColumnSidecars:
       $ref: "./types/fulu/data_column_sidecar.yaml#/Fulu/DataColumnSidecars"
+    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/duty.yaml

@@ -52,3 +52,20 @@ Altair:
         minItems: 1
         items:
           $ref: './primitive.yaml#/Uint64'
+
+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."

types/eip7805/inclusion_list.yaml

@@ -0,0 +1,24 @@
+EIP7805:
+  InclusionList:
+    type: object
+    description: "The [`InclusionList`](https://github.com/ethereum/consensus-specs/blob/v1.6.0-alpha.5/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/v1.6.0-alpha.5/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"

wordlist.txt

@@ -37,3 +37,6 @@ KZGProofs
 KZGCommitmentInclusionProof
 LMD
 fulu
+EIPs
+FOCIL
+eip7805