diff --git a/apis/beacon/light_client/instant_update.yaml b/apis/beacon/light_client/instant_update.yaml new file mode 100644 index 00000000..1953b19a --- /dev/null +++ b/apis/beacon/light_client/instant_update.yaml @@ -0,0 +1,59 @@ +get: + operationId: getLightClientInstantUpdate + summary: Get a `LightClientInstantUpdate` for the given (recent) block header + description: | + Requests the best [`LightClientInstantUpdate`](../../../types/altair/light_client.yaml#/Altair/LightClientInstantUpdate) known by the server for the given block header. + Depending on the `Accept` header it can be returned either as JSON or SSZ-serialized bytes. + + Servers providing this endpoint SHOULD always listen to the sync committee signature gossip and collect individual signatures. On request the best BLS + signature is aggregated and returned for the specified (recent) block header. When a new block appears, the previously known best sync aggregate for its + parent is compared against the sync aggregate found in the new block and replaced if the canonical one is better. Best sync aggregates are retained and + served for the 16 most recent slots. + Note that since always listening to the signature gossip costs some resources, it is acceptable to only start listening once this endpoint is called + and stop listening if it is not called for an extended period of time. + 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: GetLightClientInstantUpdateResponse + type: object + properties: + version: + $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion' + data: + $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientInstantUpdate' + application/octet-stream: + schema: + description: "SSZ serialized `LightClientInstantUpdate` bytes. Use Accept header to choose this response type" + "404": + description: "No `LightClientInstantUpdate` is available for given block root" + content: + application/json: + schema: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + example: + code: 404 + message: "LC instant update unavailable" + "406": + description: Unacceptable media type + content: + application/json: + schema: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + example: + code: 406 + message: "Accepted media type not supported" + "500": + $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/eventstream/index.yaml b/apis/eventstream/index.yaml index db694bd3..0969e9fc 100644 --- a/apis/eventstream/index.yaml +++ b/apis/eventstream/index.yaml @@ -32,6 +32,7 @@ get: - contribution_and_proof - light_client_finality_update - light_client_optimistic_update + - light_client_instant_update responses: "200": description: Opened SSE stream. @@ -91,6 +92,11 @@ get: value: | event: light_client_optimistic_update data: {"version":"phase0", "data": {"attested_header": {"slot":"1", "proposer_index":"1", "parent_root":"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "state_root":"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "body_root":"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"}, "sync_aggregate": {"sync_committee_bits":"0x01", "sync_committee_signature":"0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"}, "signature_slot":"1"}} + light_client_instant_update: + description: A new `LightClientInstantUpdate` has been generated (the node's current head and/or the best sync aggregate for the previously known head has been updated) + value: | + event: light_client_instant_update + data: {"version":"phase0", "data": {"new_head_header": {"slot":"1", "proposer_index":"1", "parent_root":"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "state_root":"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "body_root":"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"}, "best_sync_aggregate": {"sync_committee_bits":"0x01", "sync_committee_signature":"0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"}, "signature_slot":"1"}} "400": description: "The topics supplied could not be parsed" content: diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index fa1e6a22..1693d3ec 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -100,6 +100,8 @@ paths: $ref: "./apis/beacon/light_client/finality_update.yaml" /eth/v1/beacon/light_client/optimistic_update: $ref: "./apis/beacon/light_client/optimistic_update.yaml" + /eth/v0/beacon/light_client/instant_update: + $ref: "./apis/beacon/light_client/instant_update.yaml" /eth/v1/beacon/pool/attestations: $ref: "./apis/beacon/pool/attestations.yaml" /eth/v1/beacon/pool/attester_slashings: @@ -265,6 +267,8 @@ components: $ref: './types/altair/light_client.yaml#/Altair/LightClientFinalityUpdate' Altair.LightClientOptimisticUpdate: $ref: './types/altair/light_client.yaml#/Altair/LightClientOptimisticUpdate' + Altair.LightClientInstantUpdate: + $ref: './types/altair/light_client.yaml#/Altair/LightClientInstantUpdate' Altair.SignedBeaconBlock: $ref: './types/altair/block.yaml#/Altair/SignedBeaconBlock' Altair.BeaconBlock: diff --git a/types/altair/light_client.yaml b/types/altair/light_client.yaml index 4586a92d..417fbd6f 100644 --- a/types/altair/light_client.yaml +++ b/types/altair/light_client.yaml @@ -69,3 +69,18 @@ Altair: $ref: './sync_aggregate.yaml#/Altair/SyncAggregate' signature_slot: $ref: '../primitive.yaml#/Uint64' + LightClientInstantUpdate: + type: object + properties: + best_sync_aggregate: + allOf: + - $ref: './sync_aggregate.yaml#/Altair/SyncAggregate' + - description: "Best available sync aggregate for requested header" + signature_slot: + allOf: + - $ref: '../primitive.yaml#/Uint64' + - description: "Signature slot of the best sync aggregate" + new_head_header: + allOf: + - $ref: '../block.yaml#/BeaconBlockHeader' + - description: "Latest head block header (only present if not the same as the one the sync aggregate refers to)"