From a15951cd783c2ea5d5b9bf70cd2f1a90702e603c Mon Sep 17 00:00:00 2001 From: Justin Traglia Date: Mon, 11 May 2026 13:37:22 -0500 Subject: [PATCH] Move safe-block into specs directory --- .gitignore | 1 + Makefile | 3 --- fork_choice/.pages | 7 ------ fork_choice/safe-block.md | 41 ----------------------------------- specs/bellatrix/safe-block.md | 32 +++++++++++++++++++++++++++ specs/gloas/safe-block.md | 41 +++++++++++++++++++++++++++++++++++ 6 files changed, 74 insertions(+), 51 deletions(-) delete mode 100644 fork_choice/.pages delete mode 100644 fork_choice/safe-block.md create mode 100644 specs/bellatrix/safe-block.md create mode 100644 specs/gloas/safe-block.md diff --git a/.gitignore b/.gitignore index cb0b920aa29..89ca3fe7437 100644 --- a/.gitignore +++ b/.gitignore @@ -13,6 +13,7 @@ dist/ .pytest_cache .mypy_cache +.ruff_cache # Dynamically built from Markdown spec tests/core/pyspec/eth_consensus_specs/phase0/ diff --git a/Makefile b/Makefile index ce704c71fed..ccd0e5a286d 100644 --- a/Makefile +++ b/Makefile @@ -243,7 +243,6 @@ test: _pyspec ############################################################################### DOCS_DIR = ./docs -FORK_CHOICE_DIR = ./fork_choice SPEC_DIR = ./specs SSZ_DIR = ./ssz SYNC_DIR = ./sync @@ -251,10 +250,8 @@ SYNC_DIR = ./sync # Copy files to the docs directory. _copy_docs: @cp -r $(SPEC_DIR) $(DOCS_DIR) - @rm -rf $(DOCS_DIR)/specs/_deprecated @cp -r $(SYNC_DIR) $(DOCS_DIR) @cp -r $(SSZ_DIR) $(DOCS_DIR) - @cp -r $(FORK_CHOICE_DIR) $(DOCS_DIR) @cp $(CURDIR)/README.md $(DOCS_DIR)/README.md # Start a local documentation server. diff --git a/fork_choice/.pages b/fork_choice/.pages deleted file mode 100644 index a5e6ccc9046..00000000000 --- a/fork_choice/.pages +++ /dev/null @@ -1,7 +0,0 @@ -nav: - - ... - - Fork Choice -- Core: - - phase0: specs/phase0/fork-choice - - bellatrix: specs/bellatrix/fork-choice - - capella: specs/capella/fork-choice - - deneb: specs/deneb/fork-choice diff --git a/fork_choice/safe-block.md b/fork_choice/safe-block.md deleted file mode 100644 index 00f75e92ce4..00000000000 --- a/fork_choice/safe-block.md +++ /dev/null @@ -1,41 +0,0 @@ -# Fork Choice -- Safe Block - - - -- [Introduction](#introduction) -- [`get_safe_execution_block_hash`](#get_safe_execution_block_hash) - - - -## Introduction - -Under honest majority and certain network synchronicity assumptions there exists -a block that is safe from re-orgs. Normally this block is pretty close to the -head of canonical chain which makes it valuable to expose a safe block to users. - -This section describes an algorithm to find a safe block. - -## `get_safe_execution_block_hash` - -*Note*: `retrieve_fast_confirmed_root()` is an implementation dependent function -that retrieves the most recent `confirmed_root` determined by the -[Fast Confirmation](../specs/phase0/fast-confirmation.md) algorithm. - -```python -def get_safe_execution_block_hash(store: Store) -> Hash32: - safe_block_root = retrieve_fast_confirmed_root() - safe_block = store.blocks[safe_block_root] - - if compute_epoch_at_slot(safe_block.slot) >= GLOAS_FORK_EPOCH: - safe_block_bid = safe_block.body.signed_execution_payload_bid.message - return safe_block_bid.parent_block_hash - if compute_epoch_at_slot(safe_block.slot) >= BELLATRIX_FORK_EPOCH: - return safe_block.body.execution_payload.block_hash - else: - # Return Hash32() if no safe block is yet available - return Hash32() -``` - -*Note*: This helper uses beacon block container extended in -[Bellatrix](../specs/bellatrix/beacon-chain.md) and -[Gloas](../specs/gloas/beacon-chain.md). diff --git a/specs/bellatrix/safe-block.md b/specs/bellatrix/safe-block.md new file mode 100644 index 00000000000..2dd2d6bfb30 --- /dev/null +++ b/specs/bellatrix/safe-block.md @@ -0,0 +1,32 @@ +# Bellatrix -- Safe Block + + + +- [Introduction](#introduction) +- [Helpers](#helpers) + - [New `get_safe_execution_block_hash`](#new-get_safe_execution_block_hash) + + + +## Introduction + +This document describes an algorithm to find a safe block. Under honest majority +and certain network synchronicity assumptions there exists a block that is safe +from re-orgs. Normally this block is pretty close to the head of canonical chain +which makes it valuable to expose a safe block to users. + +## Helpers + +### New `get_safe_execution_block_hash` + +```python +def get_safe_execution_block_hash(fcr_store: FastConfirmationStore) -> Hash32: + safe_block_root = fcr_store.confirmed_root + safe_block = fcr_store.store.blocks[safe_block_root] + + if compute_epoch_at_slot(safe_block.slot) >= BELLATRIX_FORK_EPOCH: + return safe_block.body.execution_payload.block_hash + else: + # No safe block is available yet + return Hash32() +``` diff --git a/specs/gloas/safe-block.md b/specs/gloas/safe-block.md new file mode 100644 index 00000000000..f830bf8851b --- /dev/null +++ b/specs/gloas/safe-block.md @@ -0,0 +1,41 @@ +# Gloas -- Safe Block + + + +- [Introduction](#introduction) +- [Helpers](#helpers) + - [Modified `get_safe_execution_block_hash`](#modified-get_safe_execution_block_hash) + + + +## Introduction + +This document is an extension of +[Bellatrix -- Safe Block](../bellatrix/safe-block.md). All behaviors and +definitions defined in this document, and documents it extends, carry over +unless explicitly noted or overridden. + +This document describes an algorithm to find a safe block. Under honest majority +and certain network synchronicity assumptions there exists a block that is safe +from re-orgs. Normally this block is pretty close to the head of canonical chain +which makes it valuable to expose a safe block to users. + +## Helpers + +### Modified `get_safe_execution_block_hash` + +```python +def get_safe_execution_block_hash(fcr_store: FastConfirmationStore) -> Hash32: + safe_block_root = fcr_store.confirmed_root + safe_block = fcr_store.store.blocks[safe_block_root] + + # [Modified in Gloas] + if compute_epoch_at_slot(safe_block.slot) >= GLOAS_FORK_EPOCH: + safe_block_bid = safe_block.body.signed_execution_payload_bid.message + return safe_block_bid.parent_block_hash + elif compute_epoch_at_slot(safe_block.slot) >= BELLATRIX_FORK_EPOCH: + return safe_block.body.execution_payload.block_hash + else: + # No safe block is available yet + return Hash32() +```