status-im
/
eth2.0-specs
mirror of https://github.com/status-im/eth2.0-specs.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity
eth2.0-specs/specs/capella/light-client/fork.md

93 lines
3.8 KiB
Markdown
Raw Normal View History

Add `ExecutionPayloadHeader` to LC data While the light client sync protocol currently provides access to the latest `BeaconBlockHeader`, obtaining the matching execution data needs workarounds such as downloading the full block. Having ready access to the EL state root simplifies use cases that need a way to cross-check `eth_getProof` responses against LC data. Access to `block_hash` unlocks scenarios where a CL light client drives an EL without `engine_newPayload`. As of Altair, only the CL beacon block root is available, but the EL block hash is needed for engine API. Other fields in the `ExecutionPayloadHeader` such as `logs_bloom` may allow light client applications to monitor blocks for local interest, e.g. for transfers affecting a certain wallet. This enables to download only the few relevant blocks instead of every single one. A new `LightClientStore` is proposed into the Capella spec that may be used to sync LC data that includes execution data. Existing pre-Capella LC data will remain as is, but can be locally upgraded before feeding it into the new `LightClientStore` so that light clients do not need to run a potentially expensive fork transition at a specific time. This enables the `LightClientStore` to be upgraded at a use case dependent timing at any time before Capella hits. Smart contract and embedded deployments benefit from reduced code size and do not need synchronization with the beacon chain clock to perform the Capella fork.
2022-12-11 23:43:07 +00:00
# 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
Use `bellatrix` in `upgrade_x_to_capella` helpers
2023-01-13 19:11:05 +00:00
def upgrade_lc_header_to_capella(pre: bellatrix.LightClientHeader) -> LightClientHeader:
Add `ExecutionPayloadHeader` to LC data While the light client sync protocol currently provides access to the latest `BeaconBlockHeader`, obtaining the matching execution data needs workarounds such as downloading the full block. Having ready access to the EL state root simplifies use cases that need a way to cross-check `eth_getProof` responses against LC data. Access to `block_hash` unlocks scenarios where a CL light client drives an EL without `engine_newPayload`. As of Altair, only the CL beacon block root is available, but the EL block hash is needed for engine API. Other fields in the `ExecutionPayloadHeader` such as `logs_bloom` may allow light client applications to monitor blocks for local interest, e.g. for transfers affecting a certain wallet. This enables to download only the few relevant blocks instead of every single one. A new `LightClientStore` is proposed into the Capella spec that may be used to sync LC data that includes execution data. Existing pre-Capella LC data will remain as is, but can be locally upgraded before feeding it into the new `LightClientStore` so that light clients do not need to run a potentially expensive fork transition at a specific time. This enables the `LightClientStore` to be upgraded at a use case dependent timing at any time before Capella hits. Smart contract and embedded deployments benefit from reduced code size and do not need synchronization with the beacon chain clock to perform the Capella fork.
2022-12-11 23:43:07 +00:00
return LightClientHeader(
Use `beacon` wrapper in `upgrade_lc_header_to_capella`
2023-01-13 13:59:34 +00:00
beacon=pre.beacon,
Add `ExecutionPayloadHeader` to LC data While the light client sync protocol currently provides access to the latest `BeaconBlockHeader`, obtaining the matching execution data needs workarounds such as downloading the full block. Having ready access to the EL state root simplifies use cases that need a way to cross-check `eth_getProof` responses against LC data. Access to `block_hash` unlocks scenarios where a CL light client drives an EL without `engine_newPayload`. As of Altair, only the CL beacon block root is available, but the EL block hash is needed for engine API. Other fields in the `ExecutionPayloadHeader` such as `logs_bloom` may allow light client applications to monitor blocks for local interest, e.g. for transfers affecting a certain wallet. This enables to download only the few relevant blocks instead of every single one. A new `LightClientStore` is proposed into the Capella spec that may be used to sync LC data that includes execution data. Existing pre-Capella LC data will remain as is, but can be locally upgraded before feeding it into the new `LightClientStore` so that light clients do not need to run a potentially expensive fork transition at a specific time. This enables the `LightClientStore` to be upgraded at a use case dependent timing at any time before Capella hits. Smart contract and embedded deployments benefit from reduced code size and do not need synchronization with the beacon chain clock to perform the Capella fork.
2022-12-11 23:43:07 +00:00
)
```
```python
Use `bellatrix` in `upgrade_x_to_capella` helpers
2023-01-13 19:11:05 +00:00
def upgrade_lc_bootstrap_to_capella(pre: bellatrix.LightClientBootstrap) -> LightClientBootstrap:
Add `ExecutionPayloadHeader` to LC data While the light client sync protocol currently provides access to the latest `BeaconBlockHeader`, obtaining the matching execution data needs workarounds such as downloading the full block. Having ready access to the EL state root simplifies use cases that need a way to cross-check `eth_getProof` responses against LC data. Access to `block_hash` unlocks scenarios where a CL light client drives an EL without `engine_newPayload`. As of Altair, only the CL beacon block root is available, but the EL block hash is needed for engine API. Other fields in the `ExecutionPayloadHeader` such as `logs_bloom` may allow light client applications to monitor blocks for local interest, e.g. for transfers affecting a certain wallet. This enables to download only the few relevant blocks instead of every single one. A new `LightClientStore` is proposed into the Capella spec that may be used to sync LC data that includes execution data. Existing pre-Capella LC data will remain as is, but can be locally upgraded before feeding it into the new `LightClientStore` so that light clients do not need to run a potentially expensive fork transition at a specific time. This enables the `LightClientStore` to be upgraded at a use case dependent timing at any time before Capella hits. Smart contract and embedded deployments benefit from reduced code size and do not need synchronization with the beacon chain clock to perform the Capella fork.
2022-12-11 23:43:07 +00:00
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
Use `bellatrix` in `upgrade_x_to_capella` helpers
2023-01-13 19:11:05 +00:00
def upgrade_lc_update_to_capella(pre: bellatrix.LightClientUpdate) -> LightClientUpdate:
Add `ExecutionPayloadHeader` to LC data While the light client sync protocol currently provides access to the latest `BeaconBlockHeader`, obtaining the matching execution data needs workarounds such as downloading the full block. Having ready access to the EL state root simplifies use cases that need a way to cross-check `eth_getProof` responses against LC data. Access to `block_hash` unlocks scenarios where a CL light client drives an EL without `engine_newPayload`. As of Altair, only the CL beacon block root is available, but the EL block hash is needed for engine API. Other fields in the `ExecutionPayloadHeader` such as `logs_bloom` may allow light client applications to monitor blocks for local interest, e.g. for transfers affecting a certain wallet. This enables to download only the few relevant blocks instead of every single one. A new `LightClientStore` is proposed into the Capella spec that may be used to sync LC data that includes execution data. Existing pre-Capella LC data will remain as is, but can be locally upgraded before feeding it into the new `LightClientStore` so that light clients do not need to run a potentially expensive fork transition at a specific time. This enables the `LightClientStore` to be upgraded at a use case dependent timing at any time before Capella hits. Smart contract and embedded deployments benefit from reduced code size and do not need synchronization with the beacon chain clock to perform the Capella fork.
2022-12-11 23:43:07 +00:00
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
Use `bellatrix` in `upgrade_x_to_capella` helpers
2023-01-13 19:11:05 +00:00
def upgrade_lc_finality_update_to_capella(pre: bellatrix.LightClientFinalityUpdate) -> LightClientFinalityUpdate:
Add `ExecutionPayloadHeader` to LC data While the light client sync protocol currently provides access to the latest `BeaconBlockHeader`, obtaining the matching execution data needs workarounds such as downloading the full block. Having ready access to the EL state root simplifies use cases that need a way to cross-check `eth_getProof` responses against LC data. Access to `block_hash` unlocks scenarios where a CL light client drives an EL without `engine_newPayload`. As of Altair, only the CL beacon block root is available, but the EL block hash is needed for engine API. Other fields in the `ExecutionPayloadHeader` such as `logs_bloom` may allow light client applications to monitor blocks for local interest, e.g. for transfers affecting a certain wallet. This enables to download only the few relevant blocks instead of every single one. A new `LightClientStore` is proposed into the Capella spec that may be used to sync LC data that includes execution data. Existing pre-Capella LC data will remain as is, but can be locally upgraded before feeding it into the new `LightClientStore` so that light clients do not need to run a potentially expensive fork transition at a specific time. This enables the `LightClientStore` to be upgraded at a use case dependent timing at any time before Capella hits. Smart contract and embedded deployments benefit from reduced code size and do not need synchronization with the beacon chain clock to perform the Capella fork.
2022-12-11 23:43:07 +00:00
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
Use `bellatrix` in `upgrade_x_to_capella` helpers
2023-01-13 19:11:05 +00:00
def upgrade_lc_optimistic_update_to_capella(pre: bellatrix.LightClientOptimisticUpdate) -> LightClientOptimisticUpdate:
Add `ExecutionPayloadHeader` to LC data While the light client sync protocol currently provides access to the latest `BeaconBlockHeader`, obtaining the matching execution data needs workarounds such as downloading the full block. Having ready access to the EL state root simplifies use cases that need a way to cross-check `eth_getProof` responses against LC data. Access to `block_hash` unlocks scenarios where a CL light client drives an EL without `engine_newPayload`. As of Altair, only the CL beacon block root is available, but the EL block hash is needed for engine API. Other fields in the `ExecutionPayloadHeader` such as `logs_bloom` may allow light client applications to monitor blocks for local interest, e.g. for transfers affecting a certain wallet. This enables to download only the few relevant blocks instead of every single one. A new `LightClientStore` is proposed into the Capella spec that may be used to sync LC data that includes execution data. Existing pre-Capella LC data will remain as is, but can be locally upgraded before feeding it into the new `LightClientStore` so that light clients do not need to run a potentially expensive fork transition at a specific time. This enables the `LightClientStore` to be upgraded at a use case dependent timing at any time before Capella hits. Smart contract and embedded deployments benefit from reduced code size and do not need synchronization with the beacon chain clock to perform the Capella fork.
2022-12-11 23:43:07 +00:00
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
Use `bellatrix` in `upgrade_x_to_capella` helpers
2023-01-13 19:11:05 +00:00
def upgrade_lc_store_to_capella(pre: bellatrix.LightClientStore) -> LightClientStore:
Add `ExecutionPayloadHeader` to LC data While the light client sync protocol currently provides access to the latest `BeaconBlockHeader`, obtaining the matching execution data needs workarounds such as downloading the full block. Having ready access to the EL state root simplifies use cases that need a way to cross-check `eth_getProof` responses against LC data. Access to `block_hash` unlocks scenarios where a CL light client drives an EL without `engine_newPayload`. As of Altair, only the CL beacon block root is available, but the EL block hash is needed for engine API. Other fields in the `ExecutionPayloadHeader` such as `logs_bloom` may allow light client applications to monitor blocks for local interest, e.g. for transfers affecting a certain wallet. This enables to download only the few relevant blocks instead of every single one. A new `LightClientStore` is proposed into the Capella spec that may be used to sync LC data that includes execution data. Existing pre-Capella LC data will remain as is, but can be locally upgraded before feeding it into the new `LightClientStore` so that light clients do not need to run a potentially expensive fork transition at a specific time. This enables the `LightClientStore` to be upgraded at a use case dependent timing at any time before Capella hits. Smart contract and embedded deployments benefit from reduced code size and do not need synchronization with the beacon chain clock to perform the Capella fork.
2022-12-11 23:43:07 +00:00
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,
)
```