Move chain::Access to routing and rename it ChainAccess

The `chain::Access` trait (and the `chain::AccessError` enum) is a
bit strange - it only really makes sense if users import it via the
`chain` module, otherwise they're left with a trait just called
`Access`. Worse, for bindings users its always just called
`Access`, in part because many downstream languages don't have a
mechanism to import a module and then refer to it.

Further, its stuck dangling in the `chain` top-level mod.rs file,
sitting in a module that doesn't use it at all (it's only used in
`routing::gossip`).

Instead, we give it its full name - `ChainAccess` (and rename the
error enum `ChainAccessError`) and put it in the a new
`routing::gossip_checking` module, next to `routing::gossip`.

Author: TheBlueMatt

fuzz/src/full_stack.rs

@@ -41,6 +41,7 @@ use lightning::ln::peer_handler::{MessageHandler,PeerManager,SocketDescriptor,Ig
 use lightning::ln::msgs::{self, DecodeError};
 use lightning::ln::script::ShutdownScript;
 use lightning::routing::gossip::{P2PGossipSync, NetworkGraph};
+use lightning::routing::gossip_checking::ChainAccess;
 use lightning::routing::router::{find_route, InFlightHtlcs, PaymentParameters, Route, RouteHop, RouteParameters, Router};
 use lightning::routing::scoring::FixedPenaltyScorer;
 use lightning::util::config::UserConfig;
@@ -183,7 +184,7 @@ impl<'a> std::hash::Hash for Peer<'a> {
 type ChannelMan<'a> = ChannelManager<
 	Arc<chainmonitor::ChainMonitor<EnforcingSigner, Arc<dyn chain::Filter>, Arc<TestBroadcaster>, Arc<FuzzEstimator>, Arc<dyn Logger>, Arc<TestPersister>>>,
 	Arc<TestBroadcaster>, Arc<KeyProvider>, Arc<KeyProvider>, Arc<KeyProvider>, Arc<FuzzEstimator>, &'a FuzzRouter, Arc<dyn Logger>>;
-type PeerMan<'a> = PeerManager<Peer<'a>, Arc<ChannelMan<'a>>, Arc<P2PGossipSync<Arc<NetworkGraph<Arc<dyn Logger>>>, Arc<dyn chain::Access>, Arc<dyn Logger>>>, IgnoringMessageHandler, Arc<dyn Logger>, IgnoringMessageHandler, Arc<KeyProvider>>;
+type PeerMan<'a> = PeerManager<Peer<'a>, Arc<ChannelMan<'a>>, Arc<P2PGossipSync<Arc<NetworkGraph<Arc<dyn Logger>>>, Arc<dyn ChainAccess>, Arc<dyn Logger>>>, IgnoringMessageHandler, Arc<dyn Logger>, IgnoringMessageHandler, Arc<KeyProvider>>;
 
 struct MoneyLossDetector<'a> {
 	manager: Arc<ChannelMan<'a>>,

fuzz/src/router.rs

@@ -11,11 +11,11 @@ use bitcoin::blockdata::script::Builder;
 use bitcoin::blockdata::transaction::TxOut;
 use bitcoin::hash_types::BlockHash;
 
-use lightning::chain;
 use lightning::chain::transaction::OutPoint;
 use lightning::ln::channelmanager::{self, ChannelDetails, ChannelCounterparty};
 use lightning::ln::msgs;
 use lightning::routing::gossip::{NetworkGraph, RoutingFees};
+use lightning::routing::gossip_checking::{ChainAccess, ChainAccessError};
 use lightning::routing::router::{find_route, PaymentParameters, RouteHint, RouteHintHop, RouteParameters};
 use lightning::routing::scoring::FixedPenaltyScorer;
 use lightning::util::config::UserConfig;
@@ -84,13 +84,13 @@ impl InputData {
 struct FuzzChainSource {
 	input: Arc<InputData>,
 }
-impl chain::Access for FuzzChainSource {
-	fn get_utxo(&self, _genesis_hash: &BlockHash, _short_channel_id: u64) -> Result<TxOut, chain::AccessError> {
+impl ChainAccess for FuzzChainSource {
+	fn get_utxo(&self, _genesis_hash: &BlockHash, _short_channel_id: u64) -> Result<TxOut, ChainAccessError> {
 		match self.input.get_slice(2) {
-			Some(&[0, _]) => Err(chain::AccessError::UnknownChain),
-			Some(&[1, _]) => Err(chain::AccessError::UnknownTx),
+			Some(&[0, _]) => Err(ChainAccessError::UnknownChain),
+			Some(&[1, _]) => Err(ChainAccessError::UnknownTx),
 			Some(&[_, x]) => Ok(TxOut { value: 0, script_pubkey: Builder::new().push_int(x as i64).into_script().to_v0_p2wsh() }),
-			None => Err(chain::AccessError::UnknownTx),
+			None => Err(ChainAccessError::UnknownTx),
 			_ => unreachable!(),
 		}
 	}

lightning-background-processor/src/lib.rs

@@ -27,6 +27,7 @@ use lightning::ln::channelmanager::ChannelManager;
 use lightning::ln::msgs::{ChannelMessageHandler, OnionMessageHandler, RoutingMessageHandler};
 use lightning::ln::peer_handler::{CustomMessageHandler, PeerManager, SocketDescriptor};
 use lightning::routing::gossip::{NetworkGraph, P2PGossipSync};
+use lightning::routing::gossip_checking::ChainAccess;
 use lightning::routing::router::Router;
 use lightning::routing::scoring::WriteableScore;
 use lightning::util::events::{Event, EventHandler, EventsProvider};
@@ -117,7 +118,7 @@ pub enum GossipSync<
 	A: Deref,
 	L: Deref,
 >
-where A::Target: chain::Access, L::Target: Logger {
+where A::Target: ChainAccess, L::Target: Logger {
 	/// Gossip sync via the lightning peer-to-peer network as defined by BOLT 7.
 	P2P(P),
 	/// Rapid gossip sync from a trusted server.
@@ -133,7 +134,7 @@ impl<
 	A: Deref,
 	L: Deref,
 > GossipSync<P, R, G, A, L>
-where A::Target: chain::Access, L::Target: Logger {
+where A::Target: ChainAccess, L::Target: Logger {
 	fn network_graph(&self) -> Option<&G> {
 		match self {
 			GossipSync::P2P(gossip_sync) => Some(gossip_sync.network_graph()),
@@ -161,7 +162,7 @@ where A::Target: chain::Access, L::Target: Logger {
 impl<P: Deref<Target = P2PGossipSync<G, A, L>>, G: Deref<Target = NetworkGraph<L>>, A: Deref, L: Deref>
 	GossipSync<P, &RapidGossipSync<G, L>, G, A, L>
 where
-	A::Target: chain::Access,
+	A::Target: ChainAccess,
 	L::Target: Logger,
 {
 	/// Initializes a new [`GossipSync::P2P`] variant.
@@ -173,10 +174,10 @@ where
 /// (C-not exported) as the bindings concretize everything and have constructors for us
 impl<'a, R: Deref<Target = RapidGossipSync<G, L>>, G: Deref<Target = NetworkGraph<L>>, L: Deref>
 	GossipSync<
-		&P2PGossipSync<G, &'a (dyn chain::Access + Send + Sync), L>,
+		&P2PGossipSync<G, &'a (dyn ChainAccess + Send + Sync), L>,
 		R,
 		G,
-		&'a (dyn chain::Access + Send + Sync),
+		&'a (dyn ChainAccess + Send + Sync),
 		L,
 	>
 where
@@ -191,10 +192,10 @@ where
 /// (C-not exported) as the bindings concretize everything and have constructors for us
 impl<'a, L: Deref>
 	GossipSync<
-		&P2PGossipSync<&'a NetworkGraph<L>, &'a (dyn chain::Access + Send + Sync), L>,
+		&P2PGossipSync<&'a NetworkGraph<L>, &'a (dyn ChainAccess + Send + Sync), L>,
 		&RapidGossipSync<&'a NetworkGraph<L>, L>,
 		&'a NetworkGraph<L>,
-		&'a (dyn chain::Access + Send + Sync),
+		&'a (dyn ChainAccess + Send + Sync),
 		L,
 	>
 where
@@ -396,7 +397,7 @@ pub async fn process_events_async<
 	sleeper: Sleeper,
 ) -> Result<(), io::Error>
 where
-	CA::Target: 'static + chain::Access,
+	CA::Target: 'static + ChainAccess,
 	CF::Target: 'static + chain::Filter,
 	CW::Target: 'static + chain::Watch<<SP::Target as SignerProvider>::Signer>,
 	T::Target: 'static + BroadcasterInterface,
@@ -522,7 +523,7 @@ impl BackgroundProcessor {
 		gossip_sync: GossipSync<PGS, RGS, G, CA, L>, peer_manager: PM, logger: L, scorer: Option<S>,
 	) -> Self
 	where
-		CA::Target: 'static + chain::Access,
+		CA::Target: 'static + ChainAccess,
 		CF::Target: 'static + chain::Filter,
 		CW::Target: 'static + chain::Watch<<SP::Target as SignerProvider>::Signer>,
 		T::Target: 'static + BroadcasterInterface,

lightning-net-tokio/src/lib.rs

@@ -33,7 +33,7 @@
 //! type FeeEstimator = dyn lightning::chain::chaininterface::FeeEstimator + Send + Sync;
 //! type Logger = dyn lightning::util::logger::Logger + Send + Sync;
 //! type NodeSigner = dyn lightning::chain::keysinterface::NodeSigner + Send + Sync;
-//! type ChainAccess = dyn lightning::chain::Access + Send + Sync;
+//! type ChainAccess = dyn lightning::routing::gossip_checking::ChainAccess + Send + Sync;
 //! type ChainFilter = dyn lightning::chain::Filter + Send + Sync;
 //! type DataPersister = dyn lightning::chain::chainmonitor::Persist<lightning::chain::keysinterface::InMemorySigner> + Send + Sync;
 //! type ChainMonitor = lightning::chain::chainmonitor::ChainMonitor<lightning::chain::keysinterface::InMemorySigner, Arc<ChainFilter>, Arc<TxBroadcaster>, Arc<FeeEstimator>, Arc<Logger>, Arc<DataPersister>>;

lightning/src/chain/mod.rs

@@ -12,7 +12,6 @@
 use bitcoin::blockdata::block::{Block, BlockHeader};
 use bitcoin::blockdata::constants::genesis_block;
 use bitcoin::blockdata::script::Script;
-use bitcoin::blockdata::transaction::TxOut;
 use bitcoin::hash_types::{BlockHash, Txid};
 use bitcoin::network::constants::Network;
 use bitcoin::secp256k1::PublicKey;
@@ -60,26 +59,6 @@ impl BestBlock {
 	pub fn height(&self) -> u32 { self.height }
 }
 
-/// An error when accessing the chain via [`Access`].
-#[derive(Clone, Debug)]
-pub enum AccessError {
-	/// The requested chain is unknown.
-	UnknownChain,
-
-	/// The requested transaction doesn't exist or hasn't confirmed.
-	UnknownTx,
-}
-
-/// The `Access` trait defines behavior for accessing chain data and state, such as blocks and
-/// UTXOs.
-pub trait Access {
-	/// Returns the transaction output of a funding transaction encoded by [`short_channel_id`].
-	/// Returns an error if `genesis_hash` is for a different chain or if such a transaction output
-	/// is unknown.
-	///
-	/// [`short_channel_id`]: https://github.com/lightning/bolts/blob/master/07-routing-gossip.md#definition-of-short_channel_id
-	fn get_utxo(&self, genesis_hash: &BlockHash, short_channel_id: u64) -> Result<TxOut, AccessError>;
-}
 
 /// The `Listen` trait is used to notify when blocks have been connected or disconnected from the
 /// chain.

lightning/src/routing/gossip.rs

@@ -19,14 +19,13 @@ use bitcoin::hashes::Hash;
 use bitcoin::blockdata::transaction::TxOut;
 use bitcoin::hash_types::BlockHash;
 
-use crate::chain;
-use crate::chain::Access;
 use crate::ln::chan_utils::make_funding_redeemscript;
 use crate::ln::features::{ChannelFeatures, NodeFeatures, InitFeatures};
 use crate::ln::msgs::{DecodeError, ErrorAction, Init, LightningError, RoutingMessageHandler, NetAddress, MAX_VALUE_MSAT};
 use crate::ln::msgs::{ChannelAnnouncement, ChannelUpdate, NodeAnnouncement, GossipTimestampFilter};
 use crate::ln::msgs::{QueryChannelRange, ReplyChannelRange, QueryShortChannelIds, ReplyShortChannelIdsEnd};
 use crate::ln::msgs;
+use crate::routing::gossip_checking::{ChainAccess, ChainAccessError};
 use crate::util::ser::{Readable, ReadableArgs, Writeable, Writer, MaybeReadable};
 use crate::util::logger::{Logger, Level};
 use crate::util::events::{MessageSendEvent, MessageSendEventsProvider};
@@ -214,7 +213,7 @@ impl_writeable_tlv_based_enum_upgradable!(NetworkUpdate,
 /// Provides interface to help with initial routing sync by
 /// serving historical announcements.
 pub struct P2PGossipSync<G: Deref<Target=NetworkGraph<L>>, C: Deref, L: Deref>
-where C::Target: chain::Access, L::Target: Logger
+where C::Target: ChainAccess, L::Target: Logger
 {
 	network_graph: G,
 	chain_access: Option<C>,
@@ -225,7 +224,7 @@ where C::Target: chain::Access, L::Target: Logger
 }
 
 impl<G: Deref<Target=NetworkGraph<L>>, C: Deref, L: Deref> P2PGossipSync<G, C, L>
-where C::Target: chain::Access, L::Target: Logger
+where C::Target: ChainAccess, L::Target: Logger
 {
 	/// Creates a new tracker of the actual state of the network of channels and nodes,
 	/// assuming an existing Network Graph.
@@ -322,7 +321,7 @@ macro_rules! secp_verify_sig {
 }
 
 impl<G: Deref<Target=NetworkGraph<L>>, C: Deref, L: Deref> RoutingMessageHandler for P2PGossipSync<G, C, L>
-where C::Target: chain::Access, L::Target: Logger
+where C::Target: ChainAccess, L::Target: Logger
 {
 	fn handle_node_announcement(&self, msg: &msgs::NodeAnnouncement) -> Result<bool, LightningError> {
 		self.network_graph.update_node_from_announcement(msg)?;
@@ -613,7 +612,7 @@ where C::Target: chain::Access, L::Target: Logger
 
 impl<G: Deref<Target=NetworkGraph<L>>, C: Deref, L: Deref> MessageSendEventsProvider for P2PGossipSync<G, C, L>
 where
-	C::Target: chain::Access,
+	C::Target: ChainAccess,
 	L::Target: Logger,
 {
 	fn get_and_clear_pending_msg_events(&self) -> Vec<MessageSendEvent> {
@@ -1316,13 +1315,13 @@ impl<L: Deref> NetworkGraph<L> where L::Target: Logger {
 	/// RoutingMessageHandler implementation to call it indirectly. This may be useful to accept
 	/// routing messages from a source using a protocol other than the lightning P2P protocol.
 	///
-	/// If a `chain::Access` object is provided via `chain_access`, it will be called to verify
+	/// If a [`ChainAccess`] object is provided via `chain_access`, it will be called to verify
 	/// the corresponding UTXO exists on chain and is correctly-formatted.
 	pub fn update_channel_from_announcement<C: Deref>(
 		&self, msg: &msgs::ChannelAnnouncement, chain_access: &Option<C>,
 	) -> Result<(), LightningError>
 	where
-		C::Target: chain::Access,
+		C::Target: ChainAccess,
 	{
 		let msg_hash = hash_to_message!(&Sha256dHash::hash(&msg.contents.encode()[..])[..]);
 		secp_verify_sig!(self.secp_ctx, &msg_hash, &msg.node_signature_1, &msg.contents.node_id_1, "channel_announcement");
@@ -1336,13 +1335,13 @@ impl<L: Deref> NetworkGraph<L> where L::Target: Logger {
 	/// signatures. Because we aren't given the associated signatures here we cannot relay the
 	/// channel announcement to any of our peers.
 	///
-	/// If a `chain::Access` object is provided via `chain_access`, it will be called to verify
+	/// If a [`ChainAccess`] object is provided via `chain_access`, it will be called to verify
 	/// the corresponding UTXO exists on chain and is correctly-formatted.
 	pub fn update_channel_from_unsigned_announcement<C: Deref>(
 		&self, msg: &msgs::UnsignedChannelAnnouncement, chain_access: &Option<C>
 	) -> Result<(), LightningError>
 	where
-		C::Target: chain::Access,
+		C::Target: ChainAccess,
 	{
 		self.update_channel_from_unsigned_announcement_intern(msg, None, chain_access)
 	}
@@ -1428,7 +1427,7 @@ impl<L: Deref> NetworkGraph<L> where L::Target: Logger {
 		&self, msg: &msgs::UnsignedChannelAnnouncement, full_msg: Option<&msgs::ChannelAnnouncement>, chain_access: &Option<C>
 	) -> Result<(), LightningError>
 	where
-		C::Target: chain::Access,
+		C::Target: ChainAccess,
 	{
 		if msg.node_id_1 == msg.node_id_2 || msg.bitcoin_key_1 == msg.bitcoin_key_2 {
 			return Err(LightningError{err: "Channel announcement node had a channel with itself".to_owned(), action: ErrorAction::IgnoreError});
@@ -1499,10 +1498,10 @@ impl<L: Deref> NetworkGraph<L> where L::Target: Logger {
 						//to the new HTLC max field in channel_update
 						Some(value)
 					},
-					Err(chain::AccessError::UnknownChain) => {
+					Err(ChainAccessError::UnknownChain) => {
 						return Err(LightningError{err: format!("Channel announced on an unknown chain ({})", msg.chain_hash.encode().to_hex()), action: ErrorAction::IgnoreError});
 					},
-					Err(chain::AccessError::UnknownTx) => {
+					Err(ChainAccessError::UnknownTx) => {
 						return Err(LightningError{err: "Channel announced without corresponding UTXO entry".to_owned(), action: ErrorAction::IgnoreError});
 					},
 				}
@@ -1932,11 +1931,11 @@ impl ReadOnlyNetworkGraph<'_> {
 
 #[cfg(test)]
 mod tests {
-	use crate::chain;
 	use crate::ln::channelmanager;
 	use crate::ln::chan_utils::make_funding_redeemscript;
 	use crate::ln::features::InitFeatures;
 	use crate::routing::gossip::{P2PGossipSync, NetworkGraph, NetworkUpdate, NodeAlias, MAX_EXCESS_BYTES_FOR_RELAY, NodeId, RoutingFees, ChannelUpdateInfo, ChannelInfo, NodeAnnouncementInfo, NodeInfo};
+	use crate::routing::gossip_checking::ChainAccessError;
 	use crate::ln::msgs::{RoutingMessageHandler, UnsignedNodeAnnouncement, NodeAnnouncement,
 		UnsignedChannelAnnouncement, ChannelAnnouncement, UnsignedChannelUpdate, ChannelUpdate,
 		ReplyChannelRange, QueryChannelRange, QueryShortChannelIds, MAX_VALUE_MSAT};
@@ -2168,7 +2167,7 @@ mod tests {
 
 		// Test if an associated transaction were not on-chain (or not confirmed).
 		let chain_source = test_utils::TestChainSource::new(Network::Testnet);
-		*chain_source.utxo_ret.lock().unwrap() = Err(chain::AccessError::UnknownTx);
+		*chain_source.utxo_ret.lock().unwrap() = Err(ChainAccessError::UnknownTx);
 		let network_graph = NetworkGraph::new(genesis_hash, &logger);
 		gossip_sync = P2PGossipSync::new(&network_graph, Some(&chain_source), &logger);
 

lightning/src/routing/gossip_checking.rs

@@ -0,0 +1,28 @@
+//! When lightning nodes gossip channel information, they resist DoS attacks by checking that each
+//! channel matches a UTXO on-chain, requireing at least some marginal on-chain transacting in
+//! order to announce a channel.
+//!
+//! This module contains traits for LDK to access these UTXOs to check gossip data is correct.
+
+use bitcoin::{BlockHash, TxOut};
+
+/// An error when accessing the chain via [`ChainAccess`].
+#[derive(Clone, Debug)]
+pub enum ChainAccessError {
+	/// The requested chain is unknown.
+	UnknownChain,
+
+	/// The requested transaction doesn't exist or hasn't confirmed.
+	UnknownTx,
+}
+
+/// The `ChainAccess` trait defines behavior for accessing chain data and state, such as blocks and
+/// UTXOs.
+pub trait ChainAccess {
+	/// Returns the transaction output of a funding transaction encoded by [`short_channel_id`].
+	/// Returns an error if `genesis_hash` is for a different chain or if such a transaction output
+	/// is unknown.
+	///
+	/// [`short_channel_id`]: https://github.com/lightning/bolts/blob/master/07-routing-gossip.md#definition-of-short_channel_id
+	fn get_utxo(&self, genesis_hash: &BlockHash, short_channel_id: u64) -> Result<TxOut, ChainAccessError>;
+}

lightning/src/routing/mod.rs

@@ -9,6 +9,7 @@
 
 //! Structs and impls for receiving messages about the network and storing the topology live here.
 
+pub mod gossip_checking;
 pub mod gossip;
 pub mod router;
 pub mod scoring;

lightning/src/util/test_utils.rs

@@ -22,6 +22,7 @@ use crate::ln::features::{ChannelFeatures, InitFeatures, NodeFeatures};
 use crate::ln::{msgs, wire};
 use crate::ln::script::ShutdownScript;
 use crate::routing::gossip::NetworkGraph;
+use crate::routing::gossip_checking::{ChainAccess, ChainAccessError};
 use crate::routing::router::{find_route, InFlightHtlcs, Route, RouteHop, RouteParameters, Router, ScorerAccountingForInFlightHtlcs};
 use crate::routing::scoring::FixedPenaltyScorer;
 use crate::util::config::UserConfig;
@@ -817,7 +818,7 @@ impl core::fmt::Debug for OnGetShutdownScriptpubkey {
 
 pub struct TestChainSource {
 	pub genesis_hash: BlockHash,
-	pub utxo_ret: Mutex<Result<TxOut, chain::AccessError>>,
+	pub utxo_ret: Mutex<Result<TxOut, ChainAccessError>>,
 	pub watched_txn: Mutex<HashSet<(Txid, Script)>>,
 	pub watched_outputs: Mutex<HashSet<(OutPoint, Script)>>,
 }
@@ -834,10 +835,10 @@ impl TestChainSource {
 	}
 }
 
-impl chain::Access for TestChainSource {
-	fn get_utxo(&self, genesis_hash: &BlockHash, _short_channel_id: u64) -> Result<TxOut, chain::AccessError> {
+impl ChainAccess for TestChainSource {
+	fn get_utxo(&self, genesis_hash: &BlockHash, _short_channel_id: u64) -> Result<TxOut, ChainAccessError> {
 		if self.genesis_hash != *genesis_hash {
-			return Err(chain::AccessError::UnknownChain);
+			return Err(ChainAccessError::UnknownChain);
 		}
 
 		self.utxo_ret.lock().unwrap().clone()