ethereum · hwwhww · Jan 27, 2023 · Dec 6, 2022 · Dec 6, 2022 · Dec 11, 2022
diff --git a/Makefile b/Makefile
@@ -26,11 +26,11 @@ GENERATOR_VENVS = $(patsubst $(GENERATOR_DIR)/%, $(GENERATOR_DIR)/%venv, $(GENER
 MARKDOWN_FILES = $(wildcard $(SPEC_DIR)/phase0/*.md) \
                  $(wildcard $(SPEC_DIR)/altair/*.md) $(wildcard $(SPEC_DIR)/altair/**/*.md) \
                  $(wildcard $(SPEC_DIR)/bellatrix/*.md) \
-                 $(wildcard $(SPEC_DIR)/capella/*.md) \
+                 $(wildcard $(SPEC_DIR)/capella/*.md) $(wildcard $(SPEC_DIR)/capella/**/*.md) \
                  $(wildcard $(SPEC_DIR)/custody/*.md) \
                  $(wildcard $(SPEC_DIR)/das/*.md) \
                  $(wildcard $(SPEC_DIR)/sharding/*.md) \
-                 $(wildcard $(SPEC_DIR)/eip4844/*.md) \
+                 $(wildcard $(SPEC_DIR)/eip4844/*.md) $(wildcard $(SPEC_DIR)/eip4844/**/*.md) \
                  $(wildcard $(SSZ_DIR)/*.md)
 
 COV_HTML_OUT=.htmlcov

diff --git a/README.md b/README.md
@@ -24,8 +24,8 @@ Features are researched and developed in parallel, and then consolidated into se
 ### In-development Specifications
 | Code Name or Topic | Specs | Notes |
 | - | - | - |
-| Capella (tentative) | <ul><li>Core</li><ul><li>[Beacon chain changes](specs/capella/beacon-chain.md)</li><li>[Capella fork](specs/capella/fork.md)</li></ul><li>Additions</li><ul><li>[Validator additions](specs/capella/validator.md)</li><li>[P2P networking](specs/capella/p2p-interface.md)</li></ul></ul> |
-| EIP4844 (tentative) | <ul><li>Core</li><ul><li>[Beacon Chain changes](specs/eip4844/beacon-chain.md)</li><li>[EIP-4844 fork](specs/eip4844/fork.md)</li><li>[Polynomial commitments](specs/eip4844/polynomial-commitments.md)</li><li>[Fork choice changes](specs/eip4844/fork-choice.md)</li></ul><li>Additions</li><ul><li>[Honest validator guide changes](specs/eip4844/validator.md)</li><li>[P2P networking](specs/eip4844/p2p-interface.md)</li></ul></ul> |
+| Capella (tentative) | <ul><li>Core</li><ul><li>[Beacon chain changes](specs/capella/beacon-chain.md)</li><li>[Capella fork](specs/capella/fork.md)</li></ul><li>Additions</li><ul><li>[Light client sync protocol changes](specs/capella/light-client/sync-protocol.md) ([fork](specs/capella/light-client/fork.md), [full node](specs/capella/light-client/full-node.md), [networking](specs/capella/light-client/p2p-interface.md))</li></ul><ul><li>[Validator additions](specs/capella/validator.md)</li><li>[P2P networking](specs/capella/p2p-interface.md)</li></ul></ul> |
+| EIP4844 (tentative) | <ul><li>Core</li><ul><li>[Beacon Chain changes](specs/eip4844/beacon-chain.md)</li><li>[EIP-4844 fork](specs/eip4844/fork.md)</li><li>[Polynomial commitments](specs/eip4844/polynomial-commitments.md)</li><li>[Fork choice changes](specs/eip4844/fork-choice.md)</li></ul><li>Additions</li><ul><li>[Light client sync protocol changes](specs/eip4844/light-client/sync-protocol.md) ([fork](specs/eip4844/light-client/fork.md), [full node](specs/eip4844/light-client/full-node.md), [networking](specs/eip4844/light-client/p2p-interface.md))</li></ul><ul><li>[Honest validator guide changes](specs/eip4844/validator.md)</li><li>[P2P networking](specs/eip4844/p2p-interface.md)</li></ul></ul> |
 | Sharding (outdated) | <ul><li>Core</li><ul><li>[Beacon Chain changes](specs/sharding/beacon-chain.md)</li></ul><li>Additions</li><ul><li>[P2P networking](specs/sharding/p2p-interface.md)</li></ul></ul> |
 | Custody Game (outdated) | <ul><li>Core</li><ul><li>[Beacon Chain changes](specs/custody_game/beacon-chain.md)</li></ul><li>Additions</li><ul><li>[Honest validator guide changes](specs/custody_game/validator.md)</li></ul></ul> | Dependent on sharding |
 | Data Availability Sampling (outdated) | <ul><li>Core</li><ul><li>[Core types and functions](specs/das/das-core.md)</li><li>[Fork choice changes](specs/das/fork-choice.md)</li></ul><li>Additions</li><ul><li>[P2P Networking](specs/das/p2p-interface.md)</li><li>[Sampling process](specs/das/sampling.md)</li></ul></ul> | <ul><li> Dependent on sharding</li><li>[Technical explainer](https://hackmd.io/@HWeNw8hNRimMm2m2GH56Cw/B1YJPGkpD)</li></ul> |

diff --git a/setup.py b/setup.py
@@ -616,6 +616,21 @@ def imports(cls, preset_name: str):
 '''
 
 
+    @classmethod
+    def sundry_functions(cls) -> str:
+        return super().sundry_functions() + '\n\n' + '''
+def compute_merkle_proof_for_block_body(body: BeaconBlockBody,
+                                        index: GeneralizedIndex) -> Sequence[Bytes32]:
+    return build_proof(body.get_backing(), index)'''
+
+
+    @classmethod
+    def hardcoded_ssz_dep_constants(cls) -> Dict[str, str]:
+        constants = {
+            'EXECUTION_PAYLOAD_INDEX': 'GeneralizedIndex(25)',
+        }
+        return {**super().hardcoded_ssz_dep_constants(), **constants}
+
 #
 # EIP4844SpecBuilder
 #
@@ -690,6 +705,7 @@ def format_protocol(protocol_name: str, protocol_def: ProtocolDefinition) -> str
         if k in [
             "ceillog2",
             "floorlog2",
+            "compute_merkle_proof_for_block_body",
             "compute_merkle_proof_for_state",
         ]:
             del spec_object.functions[k]
@@ -982,6 +998,10 @@ def finalize_options(self):
                 """
             if self.spec_fork in (CAPELLA, EIP4844):
                 self.md_doc_paths += """
+                    specs/capella/light-client/fork.md
+                    specs/capella/light-client/full-node.md
+                    specs/capella/light-client/p2p-interface.md
+                    specs/capella/light-client/sync-protocol.md
                     specs/capella/beacon-chain.md
                     specs/capella/fork.md
                     specs/capella/fork-choice.md
@@ -990,6 +1010,10 @@ def finalize_options(self):
                 """
             if self.spec_fork == EIP4844:
                 self.md_doc_paths += """
+                    specs/eip4844/light-client/fork.md
+                    specs/eip4844/light-client/full-node.md
+                    specs/eip4844/light-client/p2p-interface.md
+                    specs/eip4844/light-client/sync-protocol.md
                     specs/eip4844/beacon-chain.md
                     specs/eip4844/fork.md
                     specs/eip4844/fork-choice.md

diff --git a/specs/capella/light-client/fork.md b/specs/capella/light-client/fork.md
@@ -0,0 +1,92 @@
+# Capella Light Client -- Fork Logic
+
+## Table of contents
+
+<!-- TOC -->
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Introduction](#introduction)
+  - [Upgrading light client data](#upgrading-light-client-data)
+  - [Upgrading the store](#upgrading-the-store)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+<!-- /TOC -->
+
+## Introduction
+
+This document describes how to upgrade existing light client objects based on the [Altair specification](../../altair/light-client/sync-protocol.md) to Capella. This is necessary when processing pre-Capella data with a post-Capella `LightClientStore`. Note that the data being exchanged over the network protocols uses the original format.
+
+### Upgrading light client data
+
+A Capella `LightClientStore` can still process earlier light client data. In order to do so, that pre-Capella data needs to be locally upgraded to Capella before processing.
+
+```python
+def upgrade_lc_header_to_capella(pre: bellatrix.LightClientHeader) -> LightClientHeader:
+    return LightClientHeader(
+        beacon=pre.beacon,
+    )
+```
+
+```python
+def upgrade_lc_bootstrap_to_capella(pre: bellatrix.LightClientBootstrap) -> LightClientBootstrap:
+    return LightClientBootstrap(
+        header=upgrade_lc_header_to_capella(pre.header),
+        current_sync_committee=pre.current_sync_committee,
+        current_sync_committee_branch=pre.current_sync_committee_branch,
+    )
+```
+
+```python
+def upgrade_lc_update_to_capella(pre: bellatrix.LightClientUpdate) -> LightClientUpdate:
+    return LightClientUpdate(
+        attested_header=upgrade_lc_header_to_capella(pre.attested_header),
+        next_sync_committee=pre.next_sync_committee,
+        next_sync_committee_branch=pre.next_sync_committee_branch,
+        finalized_header=upgrade_lc_header_to_capella(pre.finalized_header),
+        finality_branch=pre.finality_branch,
+        sync_aggregate=pre.sync_aggregate,
+        signature_slot=pre.signature_slot,
+    )
+```
+
+```python
+def upgrade_lc_finality_update_to_capella(pre: bellatrix.LightClientFinalityUpdate) -> LightClientFinalityUpdate:
+    return LightClientFinalityUpdate(
+        attested_header=upgrade_lc_header_to_capella(pre.attested_header),
+        finalized_header=upgrade_lc_header_to_capella(pre.finalized_header),
+        finality_branch=pre.finality_branch,
+        sync_aggregate=pre.sync_aggregate,
+        signature_slot=pre.signature_slot,
+    )
+```
+
+```python
+def upgrade_lc_optimistic_update_to_capella(pre: bellatrix.LightClientOptimisticUpdate) -> LightClientOptimisticUpdate:
+    return LightClientOptimisticUpdate(
+        attested_header=upgrade_lc_header_to_capella(pre.attested_header),
+        sync_aggregate=pre.sync_aggregate,
+        signature_slot=pre.signature_slot,
+    )
+```
+
+### Upgrading the store
+
+Existing `LightClientStore` objects based on Altair MUST be upgraded to Capella before Capella based light client data can be processed. The `LightClientStore` upgrade MAY be performed before `CAPELLA_FORK_EPOCH`.
+
+```python
+def upgrade_lc_store_to_capella(pre: bellatrix.LightClientStore) -> LightClientStore:
+    if pre.best_valid_update is None:
+        best_valid_update = None
+    else:
+        best_valid_update = upgrade_lc_update_to_capella(pre.best_valid_update)
+    return LightClientStore(
+        finalized_header=upgrade_lc_header_to_capella(pre.finalized_header),
+        current_sync_committee=pre.current_sync_committee,
+        next_sync_committee=pre.next_sync_committee,
+        best_valid_update=best_valid_update,
+        optimistic_header=upgrade_lc_header_to_capella(pre.optimistic_header),
+        previous_max_active_participants=pre.previous_max_active_participants,
+        current_max_active_participants=pre.current_max_active_participants,
+    )
+```
diff --git a/specs/capella/light-client/full-node.md b/specs/capella/light-client/full-node.md
@@ -0,0 +1,78 @@
+# Capella Light Client -- Full Node
+
+**Notice**: This document is a work-in-progress for researchers and implementers.
+
+## Table of contents
+
+<!-- TOC -->
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Introduction](#introduction)
+- [Helper functions](#helper-functions)
+  - [`compute_merkle_proof_for_block_body`](#compute_merkle_proof_for_block_body)
+  - [Modified `block_to_light_client_header`](#modified-block_to_light_client_header)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+<!-- /TOC -->
+
+## Introduction
+
+This upgrade adds information about the execution payload to light client data as part of the Capella upgrade.
+
+## Helper functions
+
+### `compute_merkle_proof_for_block_body`
+
+```python
+def compute_merkle_proof_for_block_body(body: BeaconBlockBody,
+                                        index: GeneralizedIndex) -> Sequence[Bytes32]:
+    ...
+```
+
+### Modified `block_to_light_client_header`
+
+```python
+def block_to_light_client_header(block: SignedBeaconBlock) -> LightClientHeader:
+    epoch = compute_epoch_at_slot(block.message.slot)
+
+    if epoch >= CAPELLA_FORK_EPOCH:
+        payload = block.message.body.execution_payload
+        execution_header = ExecutionPayloadHeader(
+            parent_hash=payload.parent_hash,
+            fee_recipient=payload.fee_recipient,
+            state_root=payload.state_root,
+            receipts_root=payload.receipts_root,
+            logs_bloom=payload.logs_bloom,
+            prev_randao=payload.prev_randao,
+            block_number=payload.block_number,
+            gas_limit=payload.gas_limit,
+            gas_used=payload.gas_used,
+            timestamp=payload.timestamp,
+            extra_data=payload.extra_data,
+            base_fee_per_gas=payload.base_fee_per_gas,
+            block_hash=payload.block_hash,
+            transactions_root=hash_tree_root(payload.transactions),
+            withdrawals_root=hash_tree_root(payload.withdrawals),
+        )
+        execution_branch = compute_merkle_proof_for_block_body(block.message.body, EXECUTION_PAYLOAD_INDEX)
+    else:
+        # Note that during fork transitions, `finalized_header` may still point to earlier forks.
+        # While Bellatrix blocks also contain an `ExecutionPayload` (minus `withdrawals_root`),
+        # it was not included in the corresponding light client data. To ensure compatibility
+        # with legacy data going through `upgrade_lc_header_to_capella`, leave out execution data.
+        execution_header = ExecutionPayloadHeader()
+        execution_branch = [Bytes32() for _ in range(floorlog2(EXECUTION_PAYLOAD_INDEX))]
+
+    return LightClientHeader(
+        beacon=BeaconBlockHeader(
+            slot=block.message.slot,
+            proposer_index=block.message.proposer_index,
+            parent_root=block.message.parent_root,
+            state_root=block.message.state_root,
+            body_root=hash_tree_root(block.message.body),
+        ),
+        execution=execution_header,
+        execution_branch=execution_branch,
+    )
+```
diff --git a/specs/capella/light-client/p2p-interface.md b/specs/capella/light-client/p2p-interface.md
@@ -0,0 +1,99 @@
+# Capella Light Client -- Networking
+
+**Notice**: This document is a work-in-progress for researchers and implementers.
+
+## Table of contents
+
+<!-- TOC -->
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Networking](#networking)
+  - [The gossip domain: gossipsub](#the-gossip-domain-gossipsub)
+    - [Topics and messages](#topics-and-messages)
+      - [Global topics](#global-topics)
+        - [`light_client_finality_update`](#light_client_finality_update)
+        - [`light_client_optimistic_update`](#light_client_optimistic_update)
+  - [The Req/Resp domain](#the-reqresp-domain)
+    - [Messages](#messages)
+      - [GetLightClientBootstrap](#getlightclientbootstrap)
+      - [LightClientUpdatesByRange](#lightclientupdatesbyrange)
+      - [GetLightClientFinalityUpdate](#getlightclientfinalityupdate)
+      - [GetLightClientOptimisticUpdate](#getlightclientoptimisticupdate)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+<!-- /TOC -->
+
+## Networking
+
+The [Altair light client networking specification](../../altair/light-client/p2p-interface.md) is extended to exchange [Capella light client data](./sync-protocol.md).
+
+### The gossip domain: gossipsub
+
+#### Topics and messages
+
+##### Global topics
+
+###### `light_client_finality_update`
+
+[0]: # (eth2spec: skip)
+
+| `fork_version`                                         | Message SSZ type                      |
+| ------------------------------------------------------ | ------------------------------------- |
+| `GENESIS_FORK_VERSION`                                 | n/a                                   |
+| `ALTAIR_FORK_VERSION` through `BELLATRIX_FORK_VERSION` | `altair.LightClientFinalityUpdate`    |
+| `CAPELLA_FORK_VERSION` and later                       | `capella.LightClientFinalityUpdate`   |
+
+###### `light_client_optimistic_update`
+
+[0]: # (eth2spec: skip)
+
+| `fork_version`                                         | Message SSZ type                      |
+| ------------------------------------------------------ | ------------------------------------- |
+| `GENESIS_FORK_VERSION`                                 | n/a                                   |
+| `ALTAIR_FORK_VERSION` through `BELLATRIX_FORK_VERSION` | `altair.LightClientOptimisticUpdate`  |
+| `CAPELLA_FORK_VERSION` and later                       | `capella.LightClientOptimisticUpdate` |
+
+### The Req/Resp domain
+
+#### Messages
+
+##### GetLightClientBootstrap
+
+[0]: # (eth2spec: skip)
+
+| `fork_version`                                         | Response SSZ type                     |
+| ------------------------------------------------------ | ------------------------------------- |
+| `GENESIS_FORK_VERSION`                                 | n/a                                   |
+| `ALTAIR_FORK_VERSION` through `BELLATRIX_FORK_VERSION` | `altair.LightClientBootstrap`         |
+| `CAPELLA_FORK_VERSION` and later                       | `capella.LightClientBootstrap`        |
+
+##### LightClientUpdatesByRange
+
+[0]: # (eth2spec: skip)
+
+| `fork_version`                                         | Response chunk SSZ type               |
+| ------------------------------------------------------ | ------------------------------------- |
+| `GENESIS_FORK_VERSION`                                 | n/a                                   |
+| `ALTAIR_FORK_VERSION` through `BELLATRIX_FORK_VERSION` | `altair.LightClientUpdate`            |
+| `CAPELLA_FORK_VERSION` and later                       | `capella.LightClientUpdate`           |
+
+##### GetLightClientFinalityUpdate
+
+[0]: # (eth2spec: skip)
+
+| `fork_version`                                         | Response SSZ type                     |
+| ------------------------------------------------------ | ------------------------------------- |
+| `GENESIS_FORK_VERSION`                                 | n/a                                   |
+| `ALTAIR_FORK_VERSION` through `BELLATRIX_FORK_VERSION` | `altair.LightClientFinalityUpdate`    |
+| `CAPELLA_FORK_VERSION` and later                       | `capella.LightClientFinalityUpdate`   |
+
+##### GetLightClientOptimisticUpdate
+
+[0]: # (eth2spec: skip)
+
+| `fork_version`                                         | Response SSZ type                     |
+| ------------------------------------------------------ | ------------------------------------- |
+| `GENESIS_FORK_VERSION`                                 | n/a                                   |
+| `ALTAIR_FORK_VERSION` through `BELLATRIX_FORK_VERSION` | `altair.LightClientOptimisticUpdate`  |
+| `CAPELLA_FORK_VERSION` and later                       | `capella.LightClientOptimisticUpdate` |