diff --git a/sync/optimistic.md b/sync/optimistic.md index c2f06a9be..8af450b33 100644 --- a/sync/optimistic.md +++ b/sync/optimistic.md @@ -1,5 +1,37 @@ # Optimistic Sync +## Table of contents + + + + +- [Introduction](#introduction) +- [Constants](#constants) +- [Helpers](#helpers) +- [Mechanisms](#mechanisms) + - [When to optimistically import blocks](#when-to-optimistically-import-blocks) + - [How to optimistically import blocks](#how-to-optimistically-import-blocks) + - [How to apply `latestValidHash` when payload status is `INVALID`](#how-to-apply-latestvalidhash-when-payload-status-is-invalid) + - [Execution Engine Errors](#execution-engine-errors) + - [Assumptions about Execution Engine Behaviour](#assumptions-about-execution-engine-behaviour) + - [Re-Orgs](#re-orgs) +- [Fork Choice](#fork-choice) + - [Fork Choice Poisoning](#fork-choice-poisoning) +- [Checkpoint Sync (Weak Subjectivity Sync)](#checkpoint-sync-weak-subjectivity-sync) +- [Validator assignments](#validator-assignments) + - [Block Production](#block-production) + - [Attesting](#attesting) + - [Participating in Sync Committees](#participating-in-sync-committees) +- [Ethereum Beacon APIs](#ethereum-beacon-apis) +- [Design Decision Rationale](#design-decision-rationale) + - [Why `SAFE_SLOTS_TO_IMPORT_OPTIMISTICALLY`?](#why-safe_slots_to_import_optimistically) + - [Transitioning from VALID -> INVALIDATED or INVALIDATED -> VALID](#transitioning-from-valid---invalidated-or-invalidated---valid) + - [What about Light Clients?](#what-about-light-clients) + - [What if `TERMINAL_BLOCK_HASH` is used?](#what-if-terminal_block_hash-is-used) + + + + ## Introduction In order to provide a syncing execution engine with a partial view of the head @@ -163,6 +195,23 @@ the merge block MUST be treated the same as an `INVALIDATED` block (i.e., it and all its descendants are invalidated and removed from the block tree). +### How to apply `latestValidHash` when payload status is `INVALID` + +Processing an `INVALID` payload status depends on the `latestValidHash` parameter. +The general approach is as follows: +1. Consensus engine MUST identify `invalidBlock` as per definition in the table below. +2. `invalidBlock` and all of its descendants MUST be transitioned from `NOT_VALIDATED` to `INVALIDATED`. + +| `latestValidHash` | `invalidBlock` | +|:- |:- | +| Execution block hash | The *child* of a block with `body.execution_payload.block_hash == latestValidHash` in the chain containing the block with payload in question | +| `0x00..00` (all zeroes) | The first block with `body.execution_payload != ExecutionPayload()` in the chain containing a block with payload in question | +| `null` | Block with payload in question | + +When `latestValidHash` is a meaningful execution block hash but consensus engine +cannot find a block satisfying `body.execution_payload.block_hash == latestValidHash`, +consensus engine SHOULD behave the same as if `latestValidHash` was `null`. + ### Execution Engine Errors When an execution engine returns an error or fails to respond to a payload @@ -328,7 +377,7 @@ specification since it's only possible with a faulty EE. Such a scenario requires manual intervention. -## What about Light Clients? +### What about Light Clients? An alternative to optimistic sync is to run a light client inside/alongside beacon nodes that mitigates the need for optimistic sync by providing @@ -340,7 +389,7 @@ A notable thing about optimistic sync is that it's *optional*. Should an implementation decide to go the light-client route, then they can just ignore optimistic sync all together. -## What if `TERMINAL_BLOCK_HASH` is used? +### What if `TERMINAL_BLOCK_HASH` is used? If the terminal block hash override is used (i.e., `TERMINAL_BLOCK_HASH != Hash32()`), the [`validate_merge_block`](../specs/bellatrix/fork-choice.md#validate_merge_block)