Skip to content

Commit

Permalink
support Capella / EIP4844 LC data formats
Browse files Browse the repository at this point in the history
Implements the light client data format for Capella / EIP4844:
- ethereum/consensus-specs#3151
  • Loading branch information
etan-status committed Jan 15, 2023
1 parent 6669d98 commit ea9e9a5
Show file tree
Hide file tree
Showing 12 changed files with 239 additions and 34 deletions.
9 changes: 6 additions & 3 deletions apis/beacon/light_client/bootstrap.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@ get:
operationId: getLightClientBootstrap
summary: Get `LightClientBootstrap` structure for a requested block root
description: |
Requests the [`LightClientBootstrap`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/sync-protocol.md#lightclientbootstrap) structure corresponding to a given post-Altair beacon block root.
Requests the [`LightClientBootstrap`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.1/specs/altair/light-client/sync-protocol.md#lightclientbootstrap) structure corresponding to a given post-Altair beacon block root.
Depending on the `Accept` header it can be returned either as JSON or SSZ-serialized bytes.
Servers SHOULD provide results as defined in [`create_light_client_bootstrap`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/full-node.md#create_light_client_bootstrap). To fulfill a request, the requested block's post state needs to be known.
Servers SHOULD provide results as defined in [`create_light_client_bootstrap`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.1/specs/altair/light-client/full-node.md#create_light_client_bootstrap). To fulfill a request, the requested block's post state needs to be known.
tags:
- Beacon
parameters:
Expand All @@ -28,7 +28,10 @@ get:
version:
$ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion'
data:
$ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientBootstrap'
oneOf:
- $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientBootstrap'
- $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Capella.LightClientBootstrap'
- $ref: '../../../beacon-node-oapi.yaml#/components/schemas/EIP4844.LightClientBootstrap'
application/octet-stream:
schema:
description: "SSZ serialized `LightClientBootstrap` bytes. Use Accept header to choose this response type"
Expand Down
9 changes: 6 additions & 3 deletions apis/beacon/light_client/finality_update.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@ get:
operationId: getLightClientFinalityUpdate
summary: Get the latest known `LightClientFinalityUpdate`
description: |
Requests the latest [`LightClientFinalityUpdate`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/sync-protocol.md#lightclientfinalityupdate) known by the server.
Requests the latest [`LightClientFinalityUpdate`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.1/specs/altair/light-client/sync-protocol.md#lightclientfinalityupdate) known by the server.
Depending on the `Accept` header it can be returned either as JSON or SSZ-serialized bytes.
Servers SHOULD provide results as defined in [`create_light_client_finality_update`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/full-node.md#create_light_client_finality_update).
Servers SHOULD provide results as defined in [`create_light_client_finality_update`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.1/specs/altair/light-client/full-node.md#create_light_client_finality_update).
tags:
- Beacon
responses:
Expand All @@ -23,7 +23,10 @@ get:
version:
$ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion'
data:
$ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientFinalityUpdate'
oneOf:
- $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientFinalityUpdate'
- $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Capella.LightClientFinalityUpdate'
- $ref: '../../../beacon-node-oapi.yaml#/components/schemas/EIP4844.LightClientFinalityUpdate'
application/octet-stream:
schema:
description: "SSZ serialized `LightClientFinalityUpdate` bytes. Use Accept header to choose this response type"
Expand Down
9 changes: 6 additions & 3 deletions apis/beacon/light_client/optimistic_update.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@ get:
operationId: getLightClientOptimisticUpdate
summary: Get the latest known `LightClientOptimisticUpdate`
description: |
Requests the latest [`LightClientOptimisticUpdate`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/sync-protocol.md#lightclientoptimisticupdate) known by the server.
Requests the latest [`LightClientOptimisticUpdate`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.1/specs/altair/light-client/sync-protocol.md#lightclientoptimisticupdate) known by the server.
Depending on the `Accept` header it can be returned either as JSON or SSZ-serialized bytes.
Servers SHOULD provide results as defined in [`create_light_client_optimistic_update`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/full-node.md#create_light_client_optimistic_update).
Servers SHOULD provide results as defined in [`create_light_client_optimistic_update`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.1/specs/altair/light-client/full-node.md#create_light_client_optimistic_update).
tags:
- Beacon
responses:
Expand All @@ -23,7 +23,10 @@ get:
version:
$ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion'
data:
$ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientOptimisticUpdate'
oneOf:
- $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientOptimisticUpdate'
- $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Capella.LightClientOptimisticUpdate'
- $ref: '../../../beacon-node-oapi.yaml#/components/schemas/EIP4844.LightClientOptimisticUpdate'
application/octet-stream:
schema:
description: "SSZ serialized `LightClientOptimisticUpdate` bytes. Use Accept header to choose this response type"
Expand Down
19 changes: 12 additions & 7 deletions apis/beacon/light_client/updates.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@ get:
operationId: getLightClientUpdatesByRange
summary: Get `LightClientUpdate` instances in a requested sync committee period range
description: |
Requests the [`LightClientUpdate`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/sync-protocol.md#lightclientupdate) instances in the sync committee period range `[start_period, start_period + count)`, leading up to the current head sync committee period as selected by fork choice.
Requests the [`LightClientUpdate`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.1/specs/altair/light-client/sync-protocol.md#lightclientupdate) instances in the sync committee period range `[start_period, start_period + count)`, leading up to the current head sync committee period as selected by fork choice.
Depending on the `Accept` header they can be returned either as JSON or SSZ-serialized bytes.
Servers SHOULD provide results as defined in [`create_light_client_update`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/full-node.md#create_light_client_update). They MUST respond with at least the earliest known result within the requested range, and MUST send results in consecutive order (by period). The response MUST NOT contain more than [`min(MAX_REQUEST_LIGHT_CLIENT_UPDATES, count)`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/p2p-interface.md#configuration) results.
Servers SHOULD provide results as defined in [`create_light_client_update`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.1/specs/altair/light-client/full-node.md#create_light_client_update). They MUST respond with at least the earliest known result within the requested range, and MUST send results in consecutive order (by period). The response MUST NOT contain more than [`min(MAX_REQUEST_LIGHT_CLIENT_UPDATES, count)`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.1/specs/altair/light-client/p2p-interface.md#configuration) results.
tags:
- Beacon
parameters:
Expand Down Expand Up @@ -33,7 +33,10 @@ get:
version:
$ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion'
data:
$ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientUpdate'
oneOf:
- $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientUpdate'
- $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Capella.LightClientUpdate'
- $ref: '../../../beacon-node-oapi.yaml#/components/schemas/EIP4844.LightClientUpdate'
application/octet-stream:
schema:
description: |
Expand All @@ -53,10 +56,12 @@ get:
Per `context = compute_fork_digest(fork_version, genesis_validators_root)`:
| `fork_version` | Response chunk SSZ type |
| -------------------------------------------- | ------------------------------------ |
| `GENESIS_FORK_VERSION` | n/a |
| <nobr>`ALTAIR_FORK_VERSION` and later</nobr> | `altair.LightClientUpdate` |
| `fork_version` | Response chunk SSZ type |
| ------------------------------------------------------------------- | ------------------------------------- |
| `GENESIS_FORK_VERSION` | n/a |
| <nobr>`ALTAIR_FORK_VERSION` through `BELLATRIX_FORK_VERSION`</nobr> | `altair.LightClientUpdate` |
| `CAPELLA_FORK_VERSION` | `capella.LightClientUpdate` |
| <nobr>`EIP4844_FORK_VERSION` and later</nobr> | `eip4844.LightClientUpdate` |
"400":
description: Malformed or missing request parameter
content:
Expand Down
26 changes: 21 additions & 5 deletions beacon-node-oapi.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ tags:
description: Endpoints to query rewards and penalties for validators.
- name: Experimental
description: Endpoints that are not stable or fully implemented by each client.

paths:

/eth/v1/beacon/genesis:
Expand Down Expand Up @@ -272,6 +272,10 @@ components:
$ref: './types/http.yaml#/ErrorMessage'
IndexedErrorMessage:
$ref: './types/http.yaml#/IndexedErrorMessage'
Altair.SignedBeaconBlock:
$ref: './types/altair/block.yaml#/Altair/SignedBeaconBlock'
Altair.BeaconBlock:
$ref: './types/altair/block.yaml#/Altair/BeaconBlock'
Altair.LightClientBootstrap:
$ref: './types/altair/light_client.yaml#/Altair/LightClientBootstrap'
Altair.LightClientUpdate:
Expand All @@ -280,10 +284,6 @@ components:
$ref: './types/altair/light_client.yaml#/Altair/LightClientFinalityUpdate'
Altair.LightClientOptimisticUpdate:
$ref: './types/altair/light_client.yaml#/Altair/LightClientOptimisticUpdate'
Altair.SignedBeaconBlock:
$ref: './types/altair/block.yaml#/Altair/SignedBeaconBlock'
Altair.BeaconBlock:
$ref: './types/altair/block.yaml#/Altair/BeaconBlock'
Altair.BeaconState:
$ref: './types/altair/state.yaml#/Altair/BeaconState'
Altair.SyncCommitteeSignature:
Expand Down Expand Up @@ -325,6 +325,22 @@ components:
$ref: './types/capella/block.yaml#/Capella/BlindedBeaconBlock'
Capella.SignedBlindedBeaconBlock:
$ref: './types/capella/block.yaml#/Capella/SignedBlindedBeaconBlock'
Capella.LightClientBootstrap:
$ref: './types/capella/light_client.yaml#/Capella/LightClientBootstrap'
Capella.LightClientUpdate:
$ref: './types/capella/light_client.yaml#/Capella/LightClientUpdate'
Capella.LightClientFinalityUpdate:
$ref: './types/capella/light_client.yaml#/Capella/LightClientFinalityUpdate'
Capella.LightClientOptimisticUpdate:
$ref: './types/capella/light_client.yaml#/Capella/LightClientOptimisticUpdate'
EIP4844.LightClientBootstrap:
$ref: './types/eip4844/light_client.yaml#/EIP4844/LightClientBootstrap'
EIP4844.LightClientUpdate:
$ref: './types/eip4844/light_client.yaml#/EIP4844/LightClientUpdate'
EIP4844.LightClientFinalityUpdate:
$ref: './types/eip4844/light_client.yaml#/EIP4844/LightClientFinalityUpdate'
EIP4844.LightClientOptimisticUpdate:
$ref: './types/eip4844/light_client.yaml#/EIP4844/LightClientOptimisticUpdate'
Node:
$ref: './types/fork_choice.yaml#/Node'
ExtraData:
Expand Down
6 changes: 3 additions & 3 deletions types/altair/light_client.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -3,21 +3,21 @@ Altair:
type: array
items:
$ref: '../primitive.yaml#/Root'
description: "Merkle proof consisting of [`log2trunc(FINALIZED_ROOT_INDEX])`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/sync-protocol.md#constants) roots"
description: "Merkle proof consisting of [`log2trunc(FINALIZED_ROOT_INDEX])`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.1/specs/altair/light-client/sync-protocol.md#constants) roots"
minItems: 6
maxItems: 6
CurrentSyncCommitteeBranch:
type: array
items:
$ref: '../primitive.yaml#/Root'
description: "Merkle proof consisting of [`log2trunc(CURRENT_SYNC_COMMITTEE_INDEX])`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/sync-protocol.md#constants) roots"
description: "Merkle proof consisting of [`log2trunc(CURRENT_SYNC_COMMITTEE_INDEX])`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.1/specs/altair/light-client/sync-protocol.md#constants) roots"
minItems: 5
maxItems: 5
NextSyncCommitteeBranch:
type: array
items:
$ref: '../primitive.yaml#/Root'
description: "Merkle proof consisting of [`log2trunc(NEXT_SYNC_COMMITTEE_INDEX])`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/sync-protocol.md#constants) roots"
description: "Merkle proof consisting of [`log2trunc(NEXT_SYNC_COMMITTEE_INDEX])`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.1/specs/altair/light-client/sync-protocol.md#constants) roots"
minItems: 5
maxItems: 5

Expand Down
5 changes: 2 additions & 3 deletions types/bellatrix/transactions.yaml
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
Bellatrix:
Capella:
Transactions:
type: array
items:
allOf:
- $ref: '../primitive.yaml#/Transaction'
$ref: '../primitive.yaml#/Transaction'
maxItems: 1048576
2 changes: 1 addition & 1 deletion types/capella/execution_payload.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ Capella:
- type: object
properties:
transactions:
$ref: './transactions.yaml#/Capella/Transactions'
$ref: '../bellatrix/transactions.yaml#/Bellatrix/Transactions'
withdrawals:
$ref: './withdrawals.yaml#/Capella/Withdrawals'

Expand Down
67 changes: 67 additions & 0 deletions types/capella/light_client.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
Capella:
ExecutionBranch:
type: array
items:
$ref: '../primitive.yaml#/Root'
description: "Merkle proof consisting of [`log2trunc(EXECUTION_PAYLOAD_INDEX])`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.1/specs/capella/light-client/sync-protocol.md#constants) roots"
minItems: 4
maxItems: 4

LightClientHeader:
type: object
properties:
beacon:
$ref: '../block.yaml#/BeaconBlockHeader'
execution:
$ref: './execution_payload.yaml#/Capella/ExecutionPayloadHeader'
execution_branch:
$ref: '#/Capella/ExecutionBranch'

LightClientBootstrap:
type: object
properties:
header:
$ref: '#/Capella/LightClientHeader'
current_sync_committee:
$ref: '../altair/sync_committee.yaml#/Altair/SyncCommittee'
current_sync_committee_branch:
$ref: '../altair/light_client.yaml#/Altair/CurrentSyncCommitteeBranch'
LightClientUpdate:
type: object
properties:
attested_header:
$ref: '#/Capella/LightClientHeader'
next_sync_committee:
$ref: '../altair/sync_committee.yaml#/Altair/SyncCommittee'
next_sync_committee_branch:
$ref: '../altair/light_client.yaml#/Altair/NextSyncCommitteeBranch'
finalized_header:
$ref: '#/Capella/LightClientHeader'
finality_branch:
$ref: '../altair/light_client.yaml#/Altair/FinalityBranch'
sync_aggregate:
$ref: '../altair/sync_aggregate.yaml#/Altair/SyncAggregate'
signature_slot:
$ref: '../primitive.yaml#/Uint64'
LightClientFinalityUpdate:
type: object
properties:
attested_header:
$ref: '#/Capella/LightClientHeader'
finalized_header:
$ref: '#/Capella/LightClientHeader'
finality_branch:
$ref: '../altair/light_client.yaml#/Altair/FinalityBranch'
sync_aggregate:
$ref: '../altair/sync_aggregate.yaml#/Altair/SyncAggregate'
signature_slot:
$ref: '../primitive.yaml#/Uint64'
LightClientOptimisticUpdate:
type: object
properties:
attested_header:
$ref: '#/Capella/LightClientHeader'
sync_aggregate:
$ref: '../altair/sync_aggregate.yaml#/Altair/SyncAggregate'
signature_slot:
$ref: '../primitive.yaml#/Uint64'
6 changes: 0 additions & 6 deletions types/capella/transactions.yaml

This file was deleted.

56 changes: 56 additions & 0 deletions types/eip4844/execution_payload.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
EIP4844:
ExecutionPayloadCommon:
# An abstract object to collect the common fields between the ExecutionPayload and the ExecutionPayloadHeader objects.
type: object
description: "The [`ExecutionPayload`](https://github.com/ethereum/consensus-specs/blob/master/specs/eip4844/beacon-chain.md#executionpayload) object from the CL EIP4844 spec."
properties:
parent_hash:
$ref: '../primitive.yaml#/Root'
fee_recipient:
$ref: '../primitive.yaml#/ExecutionAddress'
state_root:
$ref: '../primitive.yaml#/Root'
receipts_root:
$ref: '../primitive.yaml#/Root'
logs_bloom:
$ref: '../primitive.yaml#/LogsBloom'
prev_randao:
$ref: '../primitive.yaml#/Bytes32'
block_number:
$ref: '../primitive.yaml#/Uint64'
gas_limit:
$ref: '../primitive.yaml#/Uint64'
gas_used:
$ref: '../primitive.yaml#/Uint64'
timestamp:
$ref: '../primitive.yaml#/Uint64'
extra_data:
$ref: '../primitive.yaml#/ExtraData'
base_fee_per_gas:
$ref: '../primitive.yaml#/Uint256'
excess_data_gas:
$ref: '../primitive.yaml#/Uint256'
block_hash:
$ref: '../primitive.yaml#/Root'


ExecutionPayload:
allOf:
- $ref: '#/EIP4844/ExecutionPayloadCommon'
- type: object
properties:
transactions:
$ref: '../bellatrix/transactions.yaml#/Bellatrix/Transactions'
withdrawals:
$ref: '../capella/withdrawals.yaml#/Capella/Withdrawals'

ExecutionPayloadHeader:
description: "The [`ExecutionPayloadHeader`](https://github.com/ethereum/consensus-specs/blob/master/specs/eip4844/beacon-chain.md#executionpayloadheader) object from the CL EIP4844 spec."
allOf:
- $ref: '#/EIP4844/ExecutionPayloadCommon'
- type: object
properties:
transactions_root:
$ref: '../primitive.yaml#/Root'
withdrawals_root:
$ref: '../primitive.yaml#/Root'
Loading

0 comments on commit ea9e9a5

Please sign in to comment.