Merge pull request #4576 from TheBlueMatt/2026-04-block-locator-rename

Rename `BestBlock` to `BlockLocator`

Author: tnull

fuzz/src/chanmon_consistency.rs

@@ -44,7 +44,7 @@ use lightning::chain::chaininterface::{
 use lightning::chain::channelmonitor::{ChannelMonitor, MonitorEvent};
 use lightning::chain::transaction::OutPoint;
 use lightning::chain::{
-	chainmonitor, channelmonitor, BestBlock, ChannelMonitorUpdateStatus, Confirm, Watch,
+	chainmonitor, channelmonitor, BlockLocator, ChannelMonitorUpdateStatus, Confirm, Watch,
 };
 use lightning::events;
 use lightning::ln::channel::{
@@ -332,7 +332,7 @@ impl chain::Watch<TestChannelSigner> for TestChainMonitor {
 			.map(|(_, data)| data)
 			.unwrap_or(&map_entry.persisted_monitor);
 		let deserialized_monitor =
-			<(BestBlock, channelmonitor::ChannelMonitor<TestChannelSigner>)>::read(
+			<(BlockLocator, channelmonitor::ChannelMonitor<TestChannelSigner>)>::read(
 				&mut &latest_monitor_data[..],
 				(&*self.keys, &*self.keys),
 			)
@@ -958,7 +958,7 @@ pub fn do_test<Out: Output + MaybeSend + MaybeSync>(data: &[u8], out: Out) {
 			}
 			let network = Network::Bitcoin;
 			let best_block_timestamp = genesis_block(network).header.time;
-			let params = ChainParameters { network, best_block: BestBlock::from_network(network) };
+			let params = ChainParameters { network, best_block: BlockLocator::from_network(network) };
 			(
 				ChannelManager::new(
 					$fee_estimator.clone(),
@@ -1039,7 +1039,7 @@ pub fn do_test<Out: Output + MaybeSend + MaybeSync>(data: &[u8], out: Out) {
 			// Use a different value of `use_old_mons` if we have another monitor (only for node B)
 			// by shifting `use_old_mons` one in base-3.
 			use_old_mons /= 3;
-			let mon = <(BestBlock, ChannelMonitor<TestChannelSigner>)>::read(
+			let mon = <(BlockLocator, ChannelMonitor<TestChannelSigner>)>::read(
 				&mut &serialized_mon[..],
 				(&**keys, &**keys),
 			)
@@ -1074,7 +1074,7 @@ pub fn do_test<Out: Output + MaybeSend + MaybeSync>(data: &[u8], out: Out) {
 		};
 
 		let manager =
-			<(BestBlock, ChanMan)>::read(&mut &ser[..], read_args).expect("Failed to read manager");
+			<(BlockLocator, ChanMan)>::read(&mut &ser[..], read_args).expect("Failed to read manager");
 		let res = (manager.1, chain_monitor.clone());
 		for (channel_id, mon) in monitors.drain() {
 			assert_eq!(

fuzz/src/chanmon_deser.rs

@@ -1,7 +1,7 @@
 // This file is auto-generated by gen_target.sh based on msg_target_template.txt
 // To modify it, modify msg_target_template.txt and run gen_target.sh instead.
 
-use lightning::chain::{channelmonitor, BestBlock};
+use lightning::chain::{channelmonitor, BlockLocator};
 use lightning::util::ser::{ReadableArgs, Writeable, Writer};
 use lightning::util::test_channel_signer::TestChannelSigner;
 use lightning::util::test_utils::OnlyReadsKeysInterface;
@@ -21,14 +21,14 @@ impl Writer for VecWriter {
 #[inline]
 pub fn do_test<Out: test_logger::Output>(data: &[u8], _out: Out) {
 	if let Ok((latest_block_hash, monitor)) =
-		<(BestBlock, channelmonitor::ChannelMonitor<TestChannelSigner>)>::read(
+		<(BlockLocator, channelmonitor::ChannelMonitor<TestChannelSigner>)>::read(
 			&mut Cursor::new(data),
 			(&OnlyReadsKeysInterface {}, &OnlyReadsKeysInterface {}),
 		) {
 		let mut w = VecWriter(Vec::new());
 		monitor.write(&mut w).unwrap();
 		let deserialized_copy =
-			<(BestBlock, channelmonitor::ChannelMonitor<TestChannelSigner>)>::read(
+			<(BlockLocator, channelmonitor::ChannelMonitor<TestChannelSigner>)>::read(
 				&mut Cursor::new(&w.0),
 				(&OnlyReadsKeysInterface {}, &OnlyReadsKeysInterface {}),
 			)

fuzz/src/full_stack.rs

@@ -39,7 +39,7 @@ use lightning::chain::chaininterface::{
 };
 use lightning::chain::chainmonitor;
 use lightning::chain::transaction::OutPoint;
-use lightning::chain::{BestBlock, ChannelMonitorUpdateStatus, Confirm, Listen};
+use lightning::chain::{BlockLocator, ChannelMonitorUpdateStatus, Confirm, Listen};
 use lightning::events::Event;
 use lightning::ln::channel_state::ChannelDetails;
 use lightning::ln::channelmanager::{ChainParameters, ChannelManager, InterceptId, PaymentId};
@@ -354,7 +354,7 @@ impl<'a> MoneyLossDetector<'a> {
 				self.header_hashes[self.height - 1].0,
 				self.header_hashes[self.height].1,
 			);
-			let best_block = BestBlock::new(header.prev_blockhash, self.height as u32 - 1);
+			let best_block = BlockLocator::new(header.prev_blockhash, self.height as u32 - 1);
 			self.manager.blocks_disconnected(best_block);
 			self.monitor.blocks_disconnected(best_block);
 			self.height -= 1;
@@ -606,7 +606,7 @@ pub fn do_test(mut data: &[u8], logger: &Arc<dyn Logger + MaybeSend + MaybeSync>
 
 	let network = Network::Bitcoin;
 	let best_block_timestamp = genesis_block(network).header.time;
-	let params = ChainParameters { network, best_block: BestBlock::from_network(network) };
+	let params = ChainParameters { network, best_block: BlockLocator::from_network(network) };
 	let channelmanager = Arc::new(ChannelManager::new(
 		fee_est.clone(),
 		monitor.clone(),

fuzz/src/lsps_message.rs

@@ -6,7 +6,7 @@ use bitcoin::secp256k1::{PublicKey, Secp256k1, SecretKey};
 use bitcoin::Network;
 
 use lightning::chain::Filter;
-use lightning::chain::{chainmonitor, BestBlock};
+use lightning::chain::{chainmonitor, BlockLocator};
 use lightning::ln::channelmanager::{ChainParameters, ChannelManager};
 use lightning::ln::peer_handler::CustomMessageHandler;
 use lightning::ln::wire::CustomMessageReader;
@@ -61,7 +61,7 @@ pub fn do_test(data: &[u8]) {
 		keys_manager.get_peer_storage_key(),
 		false,
 	));
-	let best_block = BestBlock::from_network(network);
+	let best_block = BlockLocator::from_network(network);
 	let params = ChainParameters { network, best_block };
 	let manager = Arc::new(ChannelManager::new(
 		Arc::clone(&fee_estimator),

lightning-background-processor/src/lib.rs

@@ -1937,7 +1937,7 @@ mod tests {
 	use lightning::chain::chainmonitor;
 	use lightning::chain::channelmonitor::ANTI_REORG_DELAY;
 	use lightning::chain::transaction::OutPoint;
-	use lightning::chain::{BestBlock, Confirm};
+	use lightning::chain::{BlockLocator, Confirm};
 	use lightning::events::{Event, PathFailure, ReplayEvent};
 	use lightning::ln::channelmanager;
 	use lightning::ln::channelmanager::{
@@ -2121,7 +2121,7 @@ mod tests {
 		tx_broadcaster: Arc<test_utils::TestBroadcaster>,
 		network_graph: Arc<NetworkGraph<Arc<test_utils::TestLogger>>>,
 		logger: Arc<test_utils::TestLogger>,
-		best_block: BestBlock,
+		best_block: BlockLocator,
 		scorer: Arc<LockingWrapper<TestScorer>>,
 		sweeper: Arc<
 			OutputSweeperSync<
@@ -2484,7 +2484,7 @@ mod tests {
 				keys_manager.get_peer_storage_key(),
 				true,
 			));
-			let best_block = BestBlock::from_network(network);
+			let best_block = BlockLocator::from_network(network);
 			let params = ChainParameters { network, best_block };
 			let mut config = UserConfig::default();
 			config.channel_handshake_config.negotiate_anchors_zero_fee_htlc_tx = false;
@@ -2726,7 +2726,7 @@ mod tests {
 			let height = node.best_block.height + 1;
 			let header = create_dummy_header(prev_blockhash, height);
 			let txdata = vec![(0, tx)];
-			node.best_block = BestBlock::new(header.block_hash(), height);
+			node.best_block = BlockLocator::new(header.block_hash(), height);
 			match i {
 				1 => {
 					node.node.transactions_confirmed(&header, &txdata, height);
@@ -2753,7 +2753,7 @@ mod tests {
 			let prev_blockhash = node.best_block.block_hash;
 			let height = node.best_block.height + 1;
 			let header = create_dummy_header(prev_blockhash, height);
-			node.best_block = BestBlock::new(header.block_hash(), height);
+			node.best_block = BlockLocator::new(header.block_hash(), height);
 			if i == num_blocks {
 				// We need the TestBroadcaster to know about the new height so that it doesn't think
 				// we're violating the time lock requirements of transactions broadcasted at that

lightning-block-sync/src/init.rs

@@ -9,7 +9,7 @@ use bitcoin::block::Header;
 use bitcoin::network::Network;
 
 use lightning::chain;
-use lightning::chain::BestBlock;
+use lightning::chain::BlockLocator;
 
 use std::ops::Deref;
 
@@ -46,7 +46,7 @@ where
 /// use bitcoin::network::Network;
 ///
 /// use lightning::chain;
-/// use lightning::chain::{BestBlock, Watch};
+/// use lightning::chain::{BlockLocator, Watch};
 /// use lightning::chain::chainmonitor;
 /// use lightning::chain::chainmonitor::ChainMonitor;
 /// use lightning::chain::channelmonitor::ChannelMonitor;
@@ -93,7 +93,7 @@ where
 /// ) {
 /// 	// Read a serialized channel monitor paired with the best block when it was persisted.
 /// 	let serialized_monitor = "...";
-/// 	let (monitor_best_block, mut monitor) = <(BestBlock, ChannelMonitor<SP::EcdsaSigner>)>::read(
+/// 	let (monitor_best_block, mut monitor) = <(BlockLocator, ChannelMonitor<SP::EcdsaSigner>)>::read(
 /// 		&mut Cursor::new(&serialized_monitor), (entropy_source, signer_provider)).unwrap();
 ///
 /// 	// Read the channel manager paired with the best block when it was persisted.
@@ -112,7 +112,7 @@ where
 /// 			config,
 /// 			vec![&mut monitor],
 /// 		);
-/// 		<(BestBlock, ChannelManager<&ChainMonitor<SP::EcdsaSigner, &C, &T, &F, &L, &P, &ES>, &T, &ES, &NS, &SP, &F, &R, &MR, &L>)>::read(
+/// 		<(BlockLocator, ChannelManager<&ChainMonitor<SP::EcdsaSigner, &C, &T, &F, &L, &P, &ES>, &T, &ES, &NS, &SP, &F, &R, &MR, &L>)>::read(
 /// 			&mut Cursor::new(&serialized_manager), read_args).unwrap()
 /// 	};
 ///
@@ -140,7 +140,7 @@ where
 /// [`ChannelManager`]: lightning::ln::channelmanager::ChannelManager
 /// [`ChannelMonitor`]: lightning::chain::channelmonitor::ChannelMonitor
 pub async fn synchronize_listeners<B: Deref + Sized + Send + Sync, L: chain::Listen + ?Sized>(
-	block_source: B, network: Network, mut chain_listeners: Vec<(BestBlock, &L)>,
+	block_source: B, network: Network, mut chain_listeners: Vec<(BlockLocator, &L)>,
 ) -> BlockSourceResult<(HeaderCache, ValidatedBlockHeader)>
 where
 	B::Target: BlockSource,
@@ -242,7 +242,7 @@ impl<'a, L: chain::Listen + ?Sized> chain::Listen for DynamicChainListener<'a, L
 		unreachable!()
 	}
 
-	fn blocks_disconnected(&self, fork_point: BestBlock) {
+	fn blocks_disconnected(&self, fork_point: BlockLocator) {
 		self.0.blocks_disconnected(fork_point)
 	}
 }
@@ -266,9 +266,9 @@ mod tests {
 		let listener_3 = MockChainListener::new().expect_block_connected(*chain.at_height(4));
 
 		let listeners = vec![
-			(chain.best_block_at_height(1), &listener_1 as &dyn chain::Listen),
-			(chain.best_block_at_height(2), &listener_2 as &dyn chain::Listen),
-			(chain.best_block_at_height(3), &listener_3 as &dyn chain::Listen),
+			(chain.block_locator_at_height(1), &listener_1 as &dyn chain::Listen),
+			(chain.block_locator_at_height(2), &listener_2 as &dyn chain::Listen),
+			(chain.block_locator_at_height(3), &listener_3 as &dyn chain::Listen),
 		];
 		match synchronize_listeners(&chain, Network::Bitcoin, listeners).await {
 			Ok((cache, header)) => {

lightning-block-sync/src/lib.rs

@@ -54,7 +54,7 @@ use bitcoin::hash_types::BlockHash;
 use bitcoin::pow::Work;
 
 use lightning::chain;
-use lightning::chain::BestBlock;
+use lightning::chain::BlockLocator;
 
 use std::future::Future;
 use std::ops::Deref;
@@ -372,7 +372,7 @@ impl<'a, L: chain::Listen + ?Sized> ChainNotifier<'a, L> {
 	/// Updates the header cache as it goes, tracking headers needed to find the diff to reuse for
 	/// other objects that might need similar headers.
 	async fn find_difference_from_best_block<P: Poll>(
-		&mut self, current_header: ValidatedBlockHeader, prev_best_block: BestBlock,
+		&mut self, current_header: ValidatedBlockHeader, prev_best_block: BlockLocator,
 		chain_poller: &mut P,
 	) -> BlockSourceResult<ChainDifference> {
 		// Try to resolve the header for the previous best block. First try the block_hash,
@@ -393,7 +393,9 @@ impl<'a, L: chain::Listen + ?Sized> ChainNotifier<'a, L> {
 				break;
 			}
 			let height = prev_best_block.height.checked_sub(height_diff).ok_or(
-				BlockSourceError::persistent("BestBlock had more previous_blocks than its height"),
+				BlockSourceError::persistent(
+					"BlockLocator had more previous_blocks than its height",
+				),
 			)?;
 			if let Ok(header) = chain_poller.get_header(block_hash, Some(height)).await {
 				found_header = Some(header);
@@ -402,7 +404,7 @@ impl<'a, L: chain::Listen + ?Sized> ChainNotifier<'a, L> {
 			}
 		}
 		let found_header = found_header.ok_or_else(|| {
-			BlockSourceError::persistent("could not resolve any block from BestBlock")
+			BlockSourceError::persistent("could not resolve any block from BlockLocator")
 		})?;
 
 		self.find_difference_from_header(current_header, &found_header, chain_poller).await
@@ -456,7 +458,7 @@ impl<'a, L: chain::Listen + ?Sized> ChainNotifier<'a, L> {
 	/// Notifies the chain listeners of disconnected blocks.
 	fn disconnect_blocks(&mut self, fork_point: ValidatedBlockHeader) {
 		self.header_cache.blocks_disconnected(&fork_point);
-		let best_block = BestBlock::new(fork_point.block_hash, fork_point.height);
+		let best_block = BlockLocator::new(fork_point.block_hash, fork_point.height);
 		self.chain_listener.blocks_disconnected(best_block);
 	}
 

lightning-block-sync/src/poll.rs

@@ -4,7 +4,7 @@ use crate::{BlockData, BlockHeaderData, BlockSource, BlockSourceError, BlockSour
 
 use bitcoin::hash_types::BlockHash;
 use bitcoin::network::Network;
-use lightning::chain::BestBlock;
+use lightning::chain::BlockLocator;
 
 use std::future::Future;
 use std::ops::Deref;
@@ -160,7 +160,7 @@ impl ValidatedBlockHeader {
 		Ok(())
 	}
 
-	/// Returns the [`BestBlock`] corresponding to this validated block header, which can be passed
+	/// Returns the [`BlockLocator`] corresponding to this validated block header, which can be passed
 	/// into [`ChannelManager::new`] as part of its [`ChainParameters`]. Useful for ensuring that
 	/// the [`SpvClient`] and [`ChannelManager`] are initialized to the same block during a fresh
 	/// start.
@@ -169,8 +169,8 @@ impl ValidatedBlockHeader {
 	/// [`ChainParameters`]: lightning::ln::channelmanager::ChainParameters
 	/// [`ChannelManager`]: lightning::ln::channelmanager::ChannelManager
 	/// [`ChannelManager::new`]: lightning::ln::channelmanager::ChannelManager::new
-	pub fn to_best_block(&self) -> BestBlock {
-		BestBlock::new(self.block_hash, self.inner.height)
+	pub fn to_block_locator(&self) -> BlockLocator {
+		BlockLocator::new(self.block_hash, self.inner.height)
 	}
 }
 

lightning-block-sync/src/test_utils.rs

@@ -12,7 +12,7 @@ use bitcoin::transaction;
 use bitcoin::Transaction;
 
 use lightning::chain;
-use lightning::chain::BestBlock;
+use lightning::chain::BlockLocator;
 
 use std::cell::RefCell;
 use std::collections::VecDeque;
@@ -104,12 +104,12 @@ impl Blockchain {
 		block_header.validate(block_hash).unwrap()
 	}
 
-	pub fn best_block_at_height(&self, height: usize) -> BestBlock {
+	pub fn block_locator_at_height(&self, height: usize) -> BlockLocator {
 		let mut previous_blocks = [None; 12];
 		for (i, height) in (0..height).rev().take(12).enumerate() {
 			previous_blocks[i] = Some(self.blocks[height].block_hash());
 		}
-		BestBlock {
+		BlockLocator {
 			height: height as u32,
 			block_hash: self.blocks[height].block_hash(),
 			previous_blocks,
@@ -135,9 +135,9 @@ impl Blockchain {
 		self.at_height(self.blocks.len() - 1)
 	}
 
-	pub fn best_block(&self) -> BestBlock {
+	pub fn best_block(&self) -> BlockLocator {
 		assert!(!self.blocks.is_empty());
-		self.best_block_at_height(self.blocks.len() - 1)
+		self.block_locator_at_height(self.blocks.len() - 1)
 	}
 
 	pub fn disconnect_tip(&mut self) -> Option<Block> {
@@ -223,7 +223,7 @@ impl chain::Listen for NullChainListener {
 		&self, _header: &Header, _txdata: &chain::transaction::TransactionData, _height: u32,
 	) {
 	}
-	fn blocks_disconnected(&self, _fork_point: BestBlock) {}
+	fn blocks_disconnected(&self, _fork_point: BlockLocator) {}
 }
 
 pub struct MockChainListener {
@@ -284,7 +284,7 @@ impl chain::Listen for MockChainListener {
 		}
 	}
 
-	fn blocks_disconnected(&self, fork_point: BestBlock) {
+	fn blocks_disconnected(&self, fork_point: BlockLocator) {
 		match self.expected_blocks_disconnected.borrow_mut().pop_front() {
 			None => {
 				panic!(

lightning/src/chain/chainmonitor.rs

@@ -37,7 +37,7 @@ use crate::chain::channelmonitor::{
 	WithChannelMonitor,
 };
 use crate::chain::transaction::{OutPoint, TransactionData};
-use crate::chain::{BestBlock, ChannelMonitorUpdateStatus, WatchedOutput};
+use crate::chain::{BlockLocator, ChannelMonitorUpdateStatus, WatchedOutput};
 use crate::events::{self, Event, EventHandler, ReplayEvent};
 use crate::ln::channel_state::ChannelDetails;
 #[cfg(peer_storage)]
@@ -1473,7 +1473,7 @@ where
 		self.event_notifier.notify();
 	}
 
-	fn blocks_disconnected(&self, fork_point: BestBlock) {
+	fn blocks_disconnected(&self, fork_point: BlockLocator) {
 		let monitor_states = self.monitors.read().unwrap();
 		log_debug!(
 			self.logger,