diff --git a/apis/eventstream/index.yaml b/apis/eventstream/index.yaml index 3b2fa0af..521f6580 100644 --- a/apis/eventstream/index.yaml +++ b/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: diff --git a/apis/validator/duties/inclusion_list.yaml b/apis/validator/duties/inclusion_list.yaml new file mode 100644 index 00000000..2b6038d4 --- /dev/null +++ b/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" diff --git a/apis/validator/inclusion_list.yaml b/apis/validator/inclusion_list.yaml new file mode 100644 index 00000000..da737c12 --- /dev/null +++ b/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" diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index 47ffec4a..c3cfa98f 100644 --- a/beacon-node-oapi.yaml +++ b/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: diff --git a/types/duty.yaml b/types/duty.yaml index eae60438..5104157c 100644 --- a/types/duty.yaml +++ b/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." diff --git a/types/heze/inclusion_list.yaml b/types/heze/inclusion_list.yaml new file mode 100644 index 00000000..914cdd87 --- /dev/null +++ b/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" diff --git a/wordlist.txt b/wordlist.txt index b2ab8513..b9d020d5 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -46,3 +46,6 @@ PtcDuty produceBlockV stateful RLP +EIPs +FOCIL +heze