Add /eth/v0/beacon/light_client/instant_update

ethereum · Nov 28, 2022 · 4ed5eba · 4ed5eba
1 parent 263f4ed
commit 4ed5eba
Show file tree

Hide file tree

Showing 4 changed files with 84 additions and 0 deletions.
diff --git a/apis/beacon/light_client/instant_update.yaml 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
@@ -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
@@ -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
@@ -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)"