multiple issues fixed

apis/beacon/light_client/instant_update.yaml

@@ -5,14 +5,21 @@ get:
     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.
+    Servers providing this endpoint may obtain the best signature for each block header from multiple sources:
+    - from the block body of a child block
+    - by listening to `SyncCommitteeContribution` messages and aggregating the best aggregates for each subnet
+    - by listening to every `SyncCommitteeMessage` message and aggregating individual signatures
+
+    Note that the last option typically provides the lowest latency but also has a significant networking cost,
+    therefore it is not suggested as mandatory to implement or as enabled by default if implemented.
+    It is acceptable to only start listening on the relevant subnets once this endpoint is called and stop
+    listening if it is not called for an extended period of time. Best sync aggregates should be retained and
+    served for the 16 most recent slots. If no aggregate is available for the specified block then a 404 error
+    should be returned. If multiple aggregates are available from different sources then the one with the most
+    signers should be returned.
   tags:
     - Beacon
+    - Experimental
   parameters:
     - name: block_root
       in: path

apis/eventstream/index.yaml

@@ -86,17 +86,17 @@ get:
               description: The node's latest known `LightClientFinalityUpdate` has been updated
               value: |
                 event: light_client_finality_update
-                data: {"version":"phase0", "data": {"attested_header": {"slot":"1", "proposer_index":"1", "parent_root":"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "state_root":"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "body_root":"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"}, "finalized_header": {"slot":"1", "proposer_index":"1", "parent_root":"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "state_root":"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "body_root":"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"}, "finality_branch": ["0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"], "sync_aggregate": {"sync_committee_bits":"0x01", "sync_committee_signature":"0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"}, "signature_slot":"1"}}
+                data: {"version":"altair", "data": {"attested_header": {"slot":"1", "proposer_index":"1", "parent_root":"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "state_root":"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "body_root":"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"}, "finalized_header": {"slot":"1", "proposer_index":"1", "parent_root":"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "state_root":"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "body_root":"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"}, "finality_branch": ["0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"], "sync_aggregate": {"sync_committee_bits":"0x01", "sync_committee_signature":"0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"}, "signature_slot":"1"}}
             light_client_optimistic_update:
               description: The node's latest known `LightClientOptimisticUpdate` has been updated
               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"}}
+                data: {"version":"altair", "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"}}
+                data: {"version":"altair", "data": {"new_head": {"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:

beacon-node-oapi.yaml

@@ -54,6 +54,8 @@ tags:
       Minimal set of endpoints to enable a working validator implementation.
 
       [Checkout validator flow](./validator-flow.md) to learn how to use this api.
+  - name: Experimental
+    description: Experimental feature
 paths:
 
   /eth/v1/beacon/genesis:
@@ -100,7 +102,7 @@ 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/{block_root}:
+  /eth/v1/beacon/light_client/instant_update/{block_root}:
     $ref: "./apis/beacon/light_client/instant_update.yaml"
   /eth/v1/beacon/pool/attestations:
     $ref: "./apis/beacon/pool/attestations.yaml"

types/altair/light_client.yaml

@@ -71,6 +71,9 @@ Altair:
         $ref: '../primitive.yaml#/Uint64'
   LightClientInstantUpdate:
     type: object
+    required:
+      - best_sync_aggregate
+      - signature_slot
     properties:
       best_sync_aggregate:
         allOf:
@@ -80,7 +83,7 @@ Altair:
         allOf:
           - $ref: '../primitive.yaml#/Uint64'
           - description: "Signature slot of the best sync aggregate"
-      new_head_header:
+      new_head:
         allOf:
           - $ref: '../block.yaml#/BeaconBlockHeader'
           - description: "Latest head block header (only present if not the same as the one the sync aggregate refers to)"