-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Define endpoints for light client sync
Introduces additional REST endpoints for light client sync, compatible with the libp2p specification defined in `ethereum/consensus-specs`: https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/p2p-interface.md Endpoints are defined to be fork-aware to allow potential optimizations such as including EL block hash into `BeaconBlockHeader` in the future. The `getLightClientUpdatesByRange` endpoint is a new kind of endpoint, as it introduces the concept of list responses. Each list item could potentially be of a different fork. Likewise, for the events stream, the fork may update between events. Both the list response and the event are additionall wrapped with a per-item `version` indicator in JSON. For SSZ, the list items are encoded as length/version/payload triples. Note that the events endpoint does not support the SSZ format. This builds on prior work from: - @dapplion at ethereum/beacon-APIs#181 The proof endpoint in that PR is out-of-scope here, but could be useful as part of the debug API as an `eth_getProof` equivalent for CL data.
- Loading branch information
1 parent
c8c38de
commit 1df34ec
Showing
8 changed files
with
324 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,54 @@ | ||
| 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. | ||
| 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. | ||
| tags: | ||
| - Beacon | ||
| parameters: | ||
| - name: block_root | ||
| in: path | ||
| required: true | ||
| $ref: '../../../beacon-node-oapi.yaml#/components/parameters/BlockRoot' | ||
| responses: | ||
| "200": | ||
| description: Success | ||
| headers: | ||
| Eth-Consensus-Version: | ||
| $ref: '../../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version' | ||
| content: | ||
| application/json: | ||
| schema: | ||
| title: GetLightClientBootstrapResponse | ||
| type: object | ||
| properties: | ||
| version: | ||
| $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion' | ||
| data: | ||
| $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientBootstrap' | ||
| application/octet-stream: | ||
| schema: | ||
| description: "SSZ serialized `LightClientBootstrap` bytes. Use Accept header to choose this response type" | ||
| "400": | ||
| description: Malformed request parameter | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" | ||
| example: | ||
| code: 400 | ||
| message: "Invalid block root value" | ||
| "404": | ||
| description: "`LightClientBootstrap` instance cannot be produced for the given block root" | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" | ||
| example: | ||
| code: 404 | ||
| message: "LC bootstrap unavailable" | ||
| "500": | ||
| $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,40 @@ | ||
| 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. | ||
| 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). | ||
| tags: | ||
| - Beacon | ||
| responses: | ||
| "200": | ||
| description: Success | ||
| headers: | ||
| Eth-Consensus-Version: | ||
| $ref: '../../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version' | ||
| content: | ||
| application/json: | ||
| schema: | ||
| title: GetLightClientFinalityUpdateResponse | ||
| type: object | ||
| properties: | ||
| version: | ||
| $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion' | ||
| data: | ||
| $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientFinalityUpdate' | ||
| application/octet-stream: | ||
| schema: | ||
| description: "SSZ serialized `LightClientFinalityUpdate` bytes. Use Accept header to choose this response type" | ||
| "404": | ||
| description: "No `LightClientFinalityUpdate` is available" | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" | ||
| example: | ||
| code: 404 | ||
| message: "LC finality update unavailable" | ||
| "500": | ||
| $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,40 @@ | ||
| 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. | ||
| 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). | ||
| tags: | ||
| - Beacon | ||
| responses: | ||
| "200": | ||
| description: Success | ||
| headers: | ||
| Eth-Consensus-Version: | ||
| $ref: '../../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version' | ||
| content: | ||
| application/json: | ||
| schema: | ||
| title: GetLightClientOptimisticUpdateResponse | ||
| type: object | ||
| properties: | ||
| version: | ||
| $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion' | ||
| data: | ||
| $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientOptimisticUpdate' | ||
| application/octet-stream: | ||
| schema: | ||
| description: "SSZ serialized `LightClientOptimisticUpdate` bytes. Use Accept header to choose this response type" | ||
| "404": | ||
| description: "No `LightClientOptimisticUpdate` is available" | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" | ||
| example: | ||
| code: 404 | ||
| message: "LC optimistic update unavailable" | ||
| "500": | ||
| $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,84 @@ | ||
| 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. | ||
| 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. | ||
| tags: | ||
| - Beacon | ||
| parameters: | ||
| - name: start_period | ||
| in: query | ||
| required: true | ||
| $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Uint64' | ||
| - name: count | ||
| in: query | ||
| required: true | ||
| $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Uint64' | ||
| responses: | ||
| "200": | ||
| description: Success | ||
| content: | ||
| application/json: | ||
| schema: | ||
| title: GetLightClientUpdatesByRangeResponse | ||
| type: array | ||
| items: | ||
| type: object | ||
| properties: | ||
| version: | ||
| $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion' | ||
| data: | ||
| $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientUpdate' | ||
| application/octet-stream: | ||
| schema: | ||
| description: | | ||
| Sequence of zero or more `response_chunk`. Each _successful_ `response_chunk` MUST contain a single `LightClientUpdate` payload: | ||
| ``` | ||
| ( | ||
| response_chunk_len: Little-endian Uint64 byte length of `response_chunk` | ||
| response_chunk: ( | ||
| context: 4 byte `ForkDigest` | ||
| payload: SSZ serialized payload bytes | ||
| ) | ||
| ) | ||
| ``` | ||
| Use Accept header to choose this response type | ||
| For each `response_chunk`, a `ForkDigest`-context based on `compute_fork_version(compute_epoch_at_slot(update.attested_header.slot))` is used to select the fork namespace of the Response type. Note that this `fork_version` may be different from the one used to verify the `update.sync_aggregate`, which is based on `update.signature_slot`. | ||
| 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` | | ||
| "400": | ||
| description: Malformed or missing request parameter | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" | ||
| examples: | ||
| InvalidSyncPeriod: | ||
| value: | ||
| code: 400 | ||
| message: "Invalid sync committee period requested" | ||
| InvalidCount: | ||
| value: | ||
| code: 400 | ||
| message: "Invalid count requested" | ||
| MissingStartPeriodValue: | ||
| value: | ||
| code: 400 | ||
| message: "Missing `start_period` value" | ||
| MissingCountValue: | ||
| value: | ||
| code: 400 | ||
| message: "Missing `count` value" | ||
|
|
||
| "500": | ||
| $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,71 @@ | ||
| Altair: | ||
| FinalityBranch: | ||
| 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" | ||
| 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" | ||
| 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" | ||
| minItems: 5 | ||
| maxItems: 5 | ||
|
|
||
| LightClientBootstrap: | ||
| type: object | ||
| properties: | ||
| header: | ||
| $ref: '../block.yaml#/BeaconBlockHeader' | ||
| current_sync_committee: | ||
| $ref: './sync_committee.yaml#/Altair/SyncCommittee' | ||
| current_sync_committee_branch: | ||
| $ref: '#/Altair/CurrentSyncCommitteeBranch' | ||
| LightClientUpdate: | ||
| type: object | ||
| properties: | ||
| attested_header: | ||
| $ref: '../block.yaml#/BeaconBlockHeader' | ||
| next_sync_committee: | ||
| $ref: './sync_committee.yaml#/Altair/SyncCommittee' | ||
| next_sync_committee_branch: | ||
| $ref: '#/Altair/NextSyncCommitteeBranch' | ||
| finalized_header: | ||
| $ref: '../block.yaml#/BeaconBlockHeader' | ||
| finality_branch: | ||
| $ref: '#/Altair/FinalityBranch' | ||
| sync_aggregate: | ||
| $ref: './sync_aggregate.yaml#/Altair/SyncAggregate' | ||
| signature_slot: | ||
| $ref: '../primitive.yaml#/Uint64' | ||
| LightClientFinalityUpdate: | ||
| type: object | ||
| properties: | ||
| attested_header: | ||
| $ref: '../block.yaml#/BeaconBlockHeader' | ||
| finalized_header: | ||
| $ref: '../block.yaml#/BeaconBlockHeader' | ||
| finality_branch: | ||
| $ref: '#/Altair/FinalityBranch' | ||
| sync_aggregate: | ||
| $ref: './sync_aggregate.yaml#/Altair/SyncAggregate' | ||
| signature_slot: | ||
| $ref: '../primitive.yaml#/Uint64' | ||
| LightClientOptimisticUpdate: | ||
| type: object | ||
| properties: | ||
| attested_header: | ||
| $ref: '../block.yaml#/BeaconBlockHeader' | ||
| sync_aggregate: | ||
| $ref: './sync_aggregate.yaml#/Altair/SyncAggregate' | ||
| signature_slot: | ||
| $ref: '../primitive.yaml#/Uint64' |