From d7c78a7f89bd9f3a3330ef60d8a4e58959f73227 Mon Sep 17 00:00:00 2001 From: Lion - dapplion <35266934+dapplion@users.noreply.github.com> Date: Wed, 11 Feb 2026 16:45:48 -0700 Subject: [PATCH] rename --reconstruct-historic-states to --archive (#8795) Co-Authored-By: dapplion <35266934+dapplion@users.noreply.github.com> --- beacon_node/beacon_chain/src/builder.rs | 10 +++----- beacon_node/beacon_chain/src/chain_config.rs | 4 +-- .../beacon_chain/src/historical_blocks.rs | 5 +--- .../tests/attestation_verification.rs | 4 +-- .../beacon_chain/tests/blob_verification.rs | 2 +- .../beacon_chain/tests/block_verification.rs | 2 +- .../beacon_chain/tests/column_verification.rs | 2 +- .../tests/payload_invalidation.rs | 2 +- beacon_node/beacon_chain/tests/rewards.rs | 4 +-- .../beacon_chain/tests/schema_stability.rs | 2 +- beacon_node/beacon_chain/tests/store_tests.rs | 25 ++++++++----------- beacon_node/beacon_chain/tests/tests.rs | 8 +++--- beacon_node/http_api/tests/tests.rs | 2 +- beacon_node/src/cli.rs | 9 ++++--- beacon_node/src/config.rs | 4 +-- book/src/advanced_checkpoint_sync.md | 2 +- book/src/api_validator_inclusion.md | 2 +- book/src/faq.md | 12 ++++----- book/src/help_bn.md | 7 +++--- lighthouse/tests/beacon_node.rs | 19 +++++++++----- testing/ef_tests/src/cases/fork_choice.rs | 2 +- testing/node_test_rig/src/lib.rs | 2 +- 22 files changed, 67 insertions(+), 64 deletions(-) diff --git a/beacon_node/beacon_chain/src/builder.rs b/beacon_node/beacon_chain/src/builder.rs index cf6cb1598b..f673519f5f 100644 --- a/beacon_node/beacon_chain/src/builder.rs +++ b/beacon_node/beacon_chain/src/builder.rs @@ -372,8 +372,8 @@ where // Initialize anchor info before attempting to write the genesis state. // Since v4.4.0 we will set the anchor with a dummy state upper limit in order to prevent - // historic states from being retained (unless `--reconstruct-historic-states` is set). - let retain_historic_states = self.chain_config.reconstruct_historic_states; + // historic states from being retained (unless `--archive` is set). + let retain_historic_states = self.chain_config.archive; let genesis_beacon_block = genesis_block(&mut beacon_state, &self.spec)?; self.pending_io_batch.push( store @@ -529,7 +529,7 @@ where // case it will be stored in the hot DB. In this case, we need to ensure the store's anchor // is initialised prior to storing the state, as the anchor is required for working out // hdiff storage strategies. - let retain_historic_states = self.chain_config.reconstruct_historic_states; + let retain_historic_states = self.chain_config.archive; self.pending_io_batch.push( store .init_anchor_info( @@ -1125,9 +1125,7 @@ where ); // Check for states to reconstruct (in the background). - if beacon_chain.config.reconstruct_historic_states - && beacon_chain.store.get_oldest_block_slot() == 0 - { + if beacon_chain.config.archive && beacon_chain.store.get_oldest_block_slot() == 0 { beacon_chain.store_migrator.process_reconstruction(); } diff --git a/beacon_node/beacon_chain/src/chain_config.rs b/beacon_node/beacon_chain/src/chain_config.rs index ad923000e2..e9cc4f24e9 100644 --- a/beacon_node/beacon_chain/src/chain_config.rs +++ b/beacon_node/beacon_chain/src/chain_config.rs @@ -38,7 +38,7 @@ pub struct ChainConfig { /// If `None`, there is no weak subjectivity verification. pub weak_subjectivity_checkpoint: Option, /// Determine whether to reconstruct historic states, usually after a checkpoint sync. - pub reconstruct_historic_states: bool, + pub archive: bool, /// The max size of a message that can be sent over the network. pub max_network_size: usize, /// Maximum percentage of the head committee weight at which to attempt re-orging the canonical head. @@ -130,7 +130,7 @@ impl Default for ChainConfig { Self { import_max_skip_slots: None, weak_subjectivity_checkpoint: None, - reconstruct_historic_states: false, + archive: false, max_network_size: 10 * 1_048_576, // 10M re_org_head_threshold: Some(DEFAULT_RE_ORG_HEAD_THRESHOLD), re_org_parent_threshold: Some(DEFAULT_RE_ORG_PARENT_THRESHOLD), diff --git a/beacon_node/beacon_chain/src/historical_blocks.rs b/beacon_node/beacon_chain/src/historical_blocks.rs index 45ae9d7b84..3a3c3739c7 100644 --- a/beacon_node/beacon_chain/src/historical_blocks.rs +++ b/beacon_node/beacon_chain/src/historical_blocks.rs @@ -305,10 +305,7 @@ impl BeaconChain { // If backfill has completed and the chain is configured to reconstruct historic states, // send a message to the background migrator instructing it to begin reconstruction. // This can only happen if we have backfilled all the way to genesis. - if backfill_complete - && self.genesis_backfill_slot == Slot::new(0) - && self.config.reconstruct_historic_states - { + if backfill_complete && self.genesis_backfill_slot == Slot::new(0) && self.config.archive { self.store_migrator.process_reconstruction(); } diff --git a/beacon_node/beacon_chain/tests/attestation_verification.rs b/beacon_node/beacon_chain/tests/attestation_verification.rs index 208798dfdf..8aeb881aa4 100644 --- a/beacon_node/beacon_chain/tests/attestation_verification.rs +++ b/beacon_node/beacon_chain/tests/attestation_verification.rs @@ -54,7 +54,7 @@ fn get_harness(validator_count: usize) -> BeaconChainHarness> = fn get_harness(spec: ChainSpec) -> BeaconChainHarness> { let chain_config = ChainConfig { - reconstruct_historic_states: true, + archive: true, ..Default::default() }; @@ -48,7 +48,7 @@ fn get_harness(spec: ChainSpec) -> BeaconChainHarness> { fn get_electra_harness(spec: ChainSpec) -> BeaconChainHarness> { let chain_config = ChainConfig { - reconstruct_historic_states: true, + archive: true, ..Default::default() }; diff --git a/beacon_node/beacon_chain/tests/schema_stability.rs b/beacon_node/beacon_chain/tests/schema_stability.rs index 3dc009366d..8200748ae6 100644 --- a/beacon_node/beacon_chain/tests/schema_stability.rs +++ b/beacon_node/beacon_chain/tests/schema_stability.rs @@ -70,7 +70,7 @@ async fn schema_stability() { let store = get_store(&datadir, store_config, spec.clone()); let chain_config = ChainConfig { - reconstruct_historic_states: true, + archive: true, ..ChainConfig::default() }; diff --git a/beacon_node/beacon_chain/tests/store_tests.rs b/beacon_node/beacon_chain/tests/store_tests.rs index 5410f26a5d..6bea5f6013 100644 --- a/beacon_node/beacon_chain/tests/store_tests.rs +++ b/beacon_node/beacon_chain/tests/store_tests.rs @@ -100,7 +100,7 @@ fn get_harness( ) -> TestHarness { // Most tests expect to retain historic states, so we use this as the default. let chain_config = ChainConfig { - reconstruct_historic_states: true, + archive: true, ..ChainConfig::default() }; get_harness_generic( @@ -118,7 +118,7 @@ fn get_harness_import_all_data_columns( // Most tests expect to retain historic states, so we use this as the default. let chain_config = ChainConfig { ignore_ws_check: true, - reconstruct_historic_states: true, + archive: true, ..ChainConfig::default() }; get_harness_generic( @@ -2876,7 +2876,7 @@ async fn reproduction_unaligned_checkpoint_sync_pruned_payload() { slot_clock.set_slot(harness.get_current_slot().as_u64()); let chain_config = ChainConfig { - reconstruct_historic_states: true, + archive: true, ..ChainConfig::default() }; @@ -3030,9 +3030,9 @@ async fn weak_subjectivity_sync_test( slot_clock.set_slot(harness.get_current_slot().as_u64()); let chain_config = ChainConfig { - // Set reconstruct_historic_states to true from the start in the genesis case. This makes + // Set archive to true from the start in the genesis case. This makes // some of the later checks more uniform across the genesis/non-genesis cases. - reconstruct_historic_states: checkpoint_slot == 0, + archive: checkpoint_slot == 0, ..ChainConfig::default() }; @@ -3685,7 +3685,7 @@ async fn process_blocks_and_attestations_for_unaligned_checkpoint() { let temp = tempdir().unwrap(); let store = get_store(&temp); let chain_config = ChainConfig { - reconstruct_historic_states: false, + archive: false, ..ChainConfig::default() }; let harness = get_harness_generic( @@ -4110,16 +4110,13 @@ async fn revert_minority_fork_on_resume() { // version is correct. This is the easiest schema test to write without historic versions of // Lighthouse on-hand, but has the disadvantage that the min version needs to be adjusted manually // as old downgrades are deprecated. -async fn schema_downgrade_to_min_version( - store_config: StoreConfig, - reconstruct_historic_states: bool, -) { +async fn schema_downgrade_to_min_version(store_config: StoreConfig, archive: bool) { let num_blocks_produced = E::slots_per_epoch() * 4; let db_path = tempdir().unwrap(); let spec = test_spec::(); let chain_config = ChainConfig { - reconstruct_historic_states, + archive, ..ChainConfig::default() }; @@ -4174,7 +4171,7 @@ async fn schema_downgrade_to_min_version( .build(); // Check chain dump for appropriate range depending on whether this is an archive node. - let chain_dump_start_slot = if reconstruct_historic_states { + let chain_dump_start_slot = if archive { Slot::new(0) } else { store.get_split_slot() @@ -5154,7 +5151,7 @@ async fn ancestor_state_root_prior_to_split() { ..StoreConfig::default() }; let chain_config = ChainConfig { - reconstruct_historic_states: false, + archive: false, ..ChainConfig::default() }; @@ -5247,7 +5244,7 @@ async fn replay_from_split_state() { ..StoreConfig::default() }; let chain_config = ChainConfig { - reconstruct_historic_states: false, + archive: false, ..ChainConfig::default() }; diff --git a/beacon_node/beacon_chain/tests/tests.rs b/beacon_node/beacon_chain/tests/tests.rs index fb86a1a845..b052ba66f1 100644 --- a/beacon_node/beacon_chain/tests/tests.rs +++ b/beacon_node/beacon_chain/tests/tests.rs @@ -33,7 +33,7 @@ fn get_harness(validator_count: usize) -> BeaconChainHarness BeaconChainHarness> { let chain_config = ChainConfig { - reconstruct_historic_states: true, + archive: true, ..Default::default() }; let harness = BeaconChainHarness::builder(MainnetEthSpec) @@ -85,7 +85,7 @@ fn get_harness_semi_supernode( let harness = BeaconChainHarness::builder(MinimalEthSpec) .default_spec() .chain_config(ChainConfig { - reconstruct_historic_states: true, + archive: true, ..Default::default() }) .keypairs(KEYPAIRS[0..validator_count].to_vec()) @@ -950,7 +950,7 @@ async fn pseudo_finalize_test_generic( let num_blocks_produced = MinimalEthSpec::slots_per_epoch() * 5; let chain_config = ChainConfig { - reconstruct_historic_states: true, + archive: true, epochs_per_migration, ..Default::default() }; diff --git a/beacon_node/http_api/tests/tests.rs b/beacon_node/http_api/tests/tests.rs index bef9fe6acd..a49362d815 100644 --- a/beacon_node/http_api/tests/tests.rs +++ b/beacon_node/http_api/tests/tests.rs @@ -135,7 +135,7 @@ impl ApiTester { let mut harness = BeaconChainHarness::builder(MainnetEthSpec) .spec(spec.clone()) .chain_config(ChainConfig { - reconstruct_historic_states: config.retain_historic_states, + archive: config.retain_historic_states, ..ChainConfig::default() }) .deterministic_keypairs(VALIDATOR_COUNT) diff --git a/beacon_node/src/cli.rs b/beacon_node/src/cli.rs index 5c3e8058d9..61dccc9674 100644 --- a/beacon_node/src/cli.rs +++ b/beacon_node/src/cli.rs @@ -1246,9 +1246,12 @@ pub fn cli_app() -> Command { .display_order(0) ) .arg( - Arg::new("reconstruct-historic-states") - .long("reconstruct-historic-states") - .help("After a checkpoint sync, reconstruct historic states in the database. This requires syncing all the way back to genesis.") + Arg::new("archive") + .long("archive") + .alias("reconstruct-historic-states") + .help("Store all beacon states in the database. When checkpoint syncing, \ + states are reconstructed after backfill completes. This requires \ + syncing all the way back to genesis.") .action(ArgAction::SetTrue) .help_heading(FLAG_HEADER) .display_order(0) diff --git a/beacon_node/src/config.rs b/beacon_node/src/config.rs index e6091d9213..0a52bcef06 100644 --- a/beacon_node/src/config.rs +++ b/beacon_node/src/config.rs @@ -554,8 +554,8 @@ pub fn get_config( ClientGenesis::DepositContract }; - if cli_args.get_flag("reconstruct-historic-states") { - client_config.chain.reconstruct_historic_states = true; + if cli_args.get_flag("archive") { + client_config.chain.archive = true; client_config.chain.genesis_backfill = true; } diff --git a/book/src/advanced_checkpoint_sync.md b/book/src/advanced_checkpoint_sync.md index 7c30598928..0682310dcd 100644 --- a/book/src/advanced_checkpoint_sync.md +++ b/book/src/advanced_checkpoint_sync.md @@ -102,7 +102,7 @@ lack of historic states. _You do not need these states to run a staking node_, b for historical API calls (as used by block explorers and researchers). To run an archived node, you can opt-in to reconstructing all of the historic states by providing the -`--reconstruct-historic-states` flag to the beacon node at any point (before, during or after sync). +`--archive` flag to the beacon node at any point (before, during or after sync). The database keeps track of three markers to determine the availability of historic blocks and states: diff --git a/book/src/api_validator_inclusion.md b/book/src/api_validator_inclusion.md index eef563dcdb..d86483e0ea 100644 --- a/book/src/api_validator_inclusion.md +++ b/book/src/api_validator_inclusion.md @@ -8,7 +8,7 @@ These endpoints are not stable or included in the Ethereum consensus standard AP they are subject to change or removal without a change in major release version. -In order to apply these APIs, you need to have historical states information in the database of your node. This means adding the flag `--reconstruct-historic-states` in the beacon node. Once the state reconstruction process is completed, you can apply these APIs to any epoch. +In order to apply these APIs, you need to have historical states information in the database of your node. This means adding the flag `--archive` in the beacon node. Once the state reconstruction process is completed, you can apply these APIs to any epoch. ## Endpoints diff --git a/book/src/faq.md b/book/src/faq.md index c9bc53533f..5ba2c3407f 100644 --- a/book/src/faq.md +++ b/book/src/faq.md @@ -167,19 +167,19 @@ This is a known [bug](https://github.com/sigp/lighthouse/issues/3707) that will ### How can I construct only partial state history? -Lighthouse prunes finalized states by default. Nevertheless, it is quite often that users may be interested in the state history of a few epochs before finalization. To have access to these pruned states, Lighthouse typically requires a full reconstruction of states using the flag `--reconstruct-historic-states` (which will usually take a week). Partial state history can be achieved with some "tricks". Here are the general steps: +Lighthouse prunes finalized states by default. Nevertheless, it is quite often that users may be interested in the state history of a few epochs before finalization. To have access to these pruned states, Lighthouse typically requires a full reconstruction of states using the flag `--archive` (which will usually take a week). Partial state history can be achieved with some "tricks". Here are the general steps: 1. Delete the current database. You can do so with `--purge-db-force` or manually deleting the database from the data directory: `$datadir/beacon`. - 1. If you are interested in the states from the current slot and beyond, perform a checkpoint sync with the flag `--reconstruct-historic-states`, then you can skip the following and jump straight to Step 5 to check the database. + 1. If you are interested in the states from the current slot and beyond, perform a checkpoint sync with the flag `--archive`, then you can skip the following and jump straight to Step 5 to check the database. - If you are interested in the states before the current slot, identify the slot to perform a manual checkpoint sync. With the default configuration, this slot should be divisible by 221, as this is where a full state snapshot is stored. With the flag `--reconstruct-historic-states`, the state upper limit will be adjusted to the next full snapshot slot, a slot that satisfies: `slot % 2**21 == 0`. In other words, to have the state history available before the current slot, we have to checkpoint sync 221 slots before the next full snapshot slot. + If you are interested in the states before the current slot, identify the slot to perform a manual checkpoint sync. With the default configuration, this slot should be divisible by 221, as this is where a full state snapshot is stored. With the flag `--archive`, the state upper limit will be adjusted to the next full snapshot slot, a slot that satisfies: `slot % 2**21 == 0`. In other words, to have the state history available before the current slot, we have to checkpoint sync 221 slots before the next full snapshot slot. Example: Say the current mainnet is at slot `12000000`. As the next full state snapshot is at slot `12582912`, the slot that we want is slot `10485760`. You can calculate this (in Python) using `12000000 // 2**21 * 2**21`. 1. [Export](./advanced_checkpoint_sync.md#manual-checkpoint-sync) the blobs, block and state data for the slot identified in Step 2. This can be done from another beacon node that you have access to, or you could use any available public beacon API, e.g., [QuickNode](https://www.quicknode.com/docs/ethereum). - 1. Perform a [manual checkpoint sync](./advanced_checkpoint_sync.md#manual-checkpoint-sync) using the data from the previous step, and provide the flag `--reconstruct-historic-states`. + 1. Perform a [manual checkpoint sync](./advanced_checkpoint_sync.md#manual-checkpoint-sync) using the data from the previous step, and provide the flag `--archive`. 1. Check the database: @@ -193,9 +193,9 @@ Lighthouse prunes finalized states by default. Nevertheless, it is quite often t "state_upper_limit": "10485760", ``` -Lighthouse will now start to reconstruct historic states from slot `10485760`. At this point, if you do not want a full state reconstruction, you may remove the flag `--reconstruct-historic-states` (and restart). When the process is completed, you will have the state data from slot `10485760`. Going forward, Lighthouse will continue retaining all historical states newer than the snapshot. Eventually this can lead to increased disk usage, which presently can only be reduced by repeating the process starting from a more recent snapshot. +Lighthouse will now start to reconstruct historic states from slot `10485760`. At this point, if you do not want a full state reconstruction, you may remove the flag `--archive` (and restart). When the process is completed, you will have the state data from slot `10485760`. Going forward, Lighthouse will continue retaining all historical states newer than the snapshot. Eventually this can lead to increased disk usage, which presently can only be reduced by repeating the process starting from a more recent snapshot. -> Note: You may only be interested in very recent historic states. To do so, you may configure the full snapshot to be, for example, every 211 slots, see [database configuration](./advanced_database.md#hierarchical-state-diffs) for more details. This can be configured with the flag `--hierarchy-exponents 5,7,11` together with the flag `--reconstruct-historic-states`. This will affect the slot number in Step 2, while other steps remain the same. Note that this comes at the expense of a higher storage requirement. +> Note: You may only be interested in very recent historic states. To do so, you may configure the full snapshot to be, for example, every 211 slots, see [database configuration](./advanced_database.md#hierarchical-state-diffs) for more details. This can be configured with the flag `--hierarchy-exponents 5,7,11` together with the flag `--archive`. This will affect the slot number in Step 2, while other steps remain the same. Note that this comes at the expense of a higher storage requirement. > With `--hierarchy-exponents 5,7,11`, using the same example as above, the next full state snapshot is at slot `12001280`. So the slot to checkpoint sync from is: slot `11999232`. diff --git a/book/src/help_bn.md b/book/src/help_bn.md index beb74da376..cad21a3e78 100644 --- a/book/src/help_bn.md +++ b/book/src/help_bn.md @@ -439,6 +439,10 @@ Flags: intended for use by block builders, relays and developers. You should set a fee recipient on this BN and also consider adjusting the --prepare-payload-lookahead flag. + --archive + Store all beacon states in the database. When checkpoint syncing, + states are reconstructed after backfill completes. This requires + syncing all the way back to genesis. --builder-fallback-disable-checks This flag disables all checks related to chain health. This means the builder API will always be used for payload construction, regardless @@ -552,9 +556,6 @@ Flags: --purge-db-force If present, the chain database will be deleted without confirmation. Use with caution. - --reconstruct-historic-states - After a checkpoint sync, reconstruct historic states in the database. - This requires syncing all the way back to genesis. --reset-payload-statuses When present, Lighthouse will forget the payload statuses of any already-imported blocks. This can assist in the recovery from a diff --git a/lighthouse/tests/beacon_node.rs b/lighthouse/tests/beacon_node.rs index 322787736b..ded1f2b765 100644 --- a/lighthouse/tests/beacon_node.rs +++ b/lighthouse/tests/beacon_node.rs @@ -401,9 +401,9 @@ fn genesis_backfill_flag() { /// The genesis backfill flag should be enabled if historic states flag is set. #[test] -fn genesis_backfill_with_historic_flag() { +fn genesis_backfill_with_archive_flag() { CommandLineTest::new() - .flag("reconstruct-historic-states", None) + .flag("archive", None) .run_with_zero_port() .with_config(|config| assert!(config.chain.genesis_backfill)); } @@ -2030,17 +2030,24 @@ fn blob_prune_margin_epochs_on_startup_ten() { .with_config(|config| assert!(config.store.blob_prune_margin_epochs == 10)); } #[test] -fn reconstruct_historic_states_flag() { +fn archive_flag() { + CommandLineTest::new() + .flag("archive", None) + .run_with_zero_port() + .with_config(|config| assert!(config.chain.archive)); +} +#[test] +fn archive_flag_alias() { CommandLineTest::new() .flag("reconstruct-historic-states", None) .run_with_zero_port() - .with_config(|config| assert!(config.chain.reconstruct_historic_states)); + .with_config(|config| assert!(config.chain.archive)); } #[test] -fn no_reconstruct_historic_states_flag() { +fn no_archive_flag() { CommandLineTest::new() .run_with_zero_port() - .with_config(|config| assert!(!config.chain.reconstruct_historic_states)); + .with_config(|config| assert!(!config.chain.archive)); } #[test] fn epochs_per_migration_default() { diff --git a/testing/ef_tests/src/cases/fork_choice.rs b/testing/ef_tests/src/cases/fork_choice.rs index 45bed7c6cd..ca77dc8d79 100644 --- a/testing/ef_tests/src/cases/fork_choice.rs +++ b/testing/ef_tests/src/cases/fork_choice.rs @@ -448,7 +448,7 @@ impl Tester { .spec(spec.clone()) .keypairs(vec![]) .chain_config(ChainConfig { - reconstruct_historic_states: true, + archive: true, ..ChainConfig::default() }) .genesis_state_ephemeral_store(case.anchor_state.clone()) diff --git a/testing/node_test_rig/src/lib.rs b/testing/node_test_rig/src/lib.rs index e49d11ee1e..ece6001802 100644 --- a/testing/node_test_rig/src/lib.rs +++ b/testing/node_test_rig/src/lib.rs @@ -115,7 +115,7 @@ pub fn testing_client_config() -> ClientConfig { }; // Simulator tests expect historic states to be available for post-run checks. - client_config.chain.reconstruct_historic_states = true; + client_config.chain.archive = true; // Specify a constant count of beacon processor workers. Having this number // too low can cause annoying HTTP timeouts, especially on Github runners