Add EIP-7805 (FOCIL) endpoints

apis/eventstream/index.yaml

@@ -45,6 +45,7 @@ get:
             - execution_payload_bid
             - payload_attestation_message
             - fast_confirmation
+            - inclusion_list
   responses:
     "200":
       description: Opened SSE stream.
@@ -158,7 +159,7 @@ get:
                 ignored by block builders and most other API consumers.
               value: |
                 event: payload_attributes
-                data: {"version": "electra", "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"}}}
+                data: {"version": "heze", "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"]}}}
             data_column_sidecar:
               description: The node has received a DataColumnSidecar (from P2P or API) that passes all gossip validations on the data_column_sidecar_{subnet_id} topic
               value: |
@@ -194,6 +195,11 @@ get:
               value: |
                 event: fast_confirmation
                 data: {"block": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "slot": "1", "current_slot": "2"}
+            inclusion_list:
+              description: 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": "heze", "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:
+    - Heze
+  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/Heze.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:
+    - Heze
+  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:
+    - Heze
+  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/Heze.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: Heze
+    description: "Endpoints required for Heze: Fork-choice enforced Inclusion Lists (FOCIL, EIP-7805)"
 
 paths:
 
@@ -190,6 +192,8 @@ paths:
     $ref: "./apis/validator/duties/sync.yaml"
   /eth/v1/validator/duties/ptc/{epoch}:
     $ref: "./apis/validator/duties/ptc.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:
@@ -220,6 +224,8 @@ paths:
     $ref: "./apis/validator/liveness.yaml"
   /eth/v1/validator/execution_payload_bids/{slot}/{builder_index}:
     $ref: "./apis/validator/execution_payload_bid.yaml"
+  /eth/v1/validator/inclusion_list:
+    $ref: "./apis/validator/inclusion_list.yaml"
 
   /eth/v1/events:
     $ref: "./apis/eventstream/index.yaml"
@@ -247,6 +253,8 @@ components:
       $ref: './types/duty.yaml#/PtcDuty'
     Altair.SyncDuty:
       $ref: './types/duty.yaml#/Altair/SyncDuty'
+    Heze.InclusionListDuty:
+      $ref: './types/duty.yaml#/Heze/InclusionListDuty'
     BeaconCommitteeSelection:
       $ref: './types/selection.yaml#/BeaconCommitteeSelection'
     SyncCommitteeSelection:
@@ -349,9 +357,11 @@ 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, gloas]
+      enum: [phase0, altair, bellatrix, capella, deneb, electra, fulu, gloas, heze]
       example: "gloas"
     SignedValidatorRegistration:
       $ref: './types/registration.yaml#/SignedValidatorRegistration'
@@ -469,6 +479,10 @@ components:
       $ref: "./types/fulu/data_column_sidecar.yaml#/Fulu/DataColumnSidecars"
     Gloas.DataColumnSidecars:
       $ref: "./types/gloas/data_column_sidecar.yaml#/Gloas/DataColumnSidecars"
+    Heze.InclusionList:
+      $ref: './types/heze/inclusion_list.yaml#/Heze/InclusionList'
+    Heze.SignedInclusionList:
+      $ref: './types/heze/inclusion_list.yaml#/Heze/SignedInclusionList'
     Node:
       $ref: './types/fork_choice.yaml#/Node'
     ExtraData:

types/duty.yaml

@@ -65,3 +65,20 @@ PtcDuty:
     slot:
       $ref: "./primitive.yaml#/Uint64"
       description: "The slot at which the validator must perform PTC duties."
+
+Heze:
+  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/heze/inclusion_list.yaml

@@ -0,0 +1,24 @@
+Heze:
+  InclusionList:
+    type: object
+    description: "The [`InclusionList`](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.11/specs/heze/beacon-chain.md#inclusionlist) object from the CL Heze 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.7.0-alpha.11/specs/heze/beacon-chain.md#signedinclusionlist) object from the CL Heze spec."
+    required: [message, signature]
+    properties:
+      message:
+        $ref: "#/Heze/InclusionList"
+      signature:
+        $ref: "../primitive.yaml#/Signature"

wordlist.txt

@@ -46,3 +46,6 @@ PtcDuty
 produceBlockV
 stateful
 RLP
+EIPs
+FOCIL
+heze