1 //! When fetching gossip from peers, lightning nodes need to validate that gossip against the
2 //! current UTXO set. This module defines an implementation of the LDK API required to do so
3 //! against a [`BlockSource`] which implements a few additional methods for accessing the UTXO set.
5 use crate::{AsyncBlockSourceResult, BlockData, BlockSource, BlockSourceError};
7 use bitcoin::blockdata::block::Block;
8 use bitcoin::blockdata::constants::ChainHash;
9 use bitcoin::blockdata::transaction::{TxOut, OutPoint};
10 use bitcoin::hash_types::BlockHash;
12 use lightning::sign::NodeSigner;
14 use lightning::ln::peer_handler::{CustomMessageHandler, PeerManager, SocketDescriptor};
15 use lightning::ln::msgs::{ChannelMessageHandler, OnionMessageHandler};
17 use lightning::routing::gossip::{NetworkGraph, P2PGossipSync};
18 use lightning::routing::utxo::{UtxoFuture, UtxoLookup, UtxoResult, UtxoLookupError};
20 use lightning::util::logger::Logger;
22 use std::sync::{Arc, Mutex};
23 use std::collections::VecDeque;
24 use std::future::Future;
29 /// A trait which extends [`BlockSource`] and can be queried to fetch the block at a given height
30 /// as well as whether a given output is unspent (i.e. a member of the current UTXO set).
32 /// Note that while this is implementable for a [`BlockSource`] which returns filtered block data
33 /// (i.e. [`BlockData::HeaderOnly`] for [`BlockSource::get_block`] requests), such an
34 /// implementation will reject all gossip as it is not fully able to verify the UTXOs referenced.
35 pub trait UtxoSource : BlockSource + 'static {
36 /// Fetches the block hash of the block at the given height.
38 /// This will, in turn, be passed to to [`BlockSource::get_block`] to fetch the block needed
39 /// for gossip validation.
40 fn get_block_hash_by_height<'a>(&'a self, block_height: u32) -> AsyncBlockSourceResult<'a, BlockHash>;
42 /// Returns true if the given output has *not* been spent, i.e. is a member of the current UTXO
44 fn is_output_unspent<'a>(&'a self, outpoint: OutPoint) -> AsyncBlockSourceResult<'a, bool>;
47 /// A generic trait which is able to spawn futures in the background.
49 /// If the `tokio` feature is enabled, this is implemented on `TokioSpawner` struct which
50 /// delegates to `tokio::spawn()`.
51 pub trait FutureSpawner : Send + Sync + 'static {
52 /// Spawns the given future as a background task.
54 /// This method MUST NOT block on the given future immediately.
55 fn spawn<T: Future<Output = ()> + Send + 'static>(&self, future: T);
58 #[cfg(feature = "tokio")]
59 /// A trivial [`FutureSpawner`] which delegates to `tokio::spawn`.
60 pub struct TokioSpawner;
61 #[cfg(feature = "tokio")]
62 impl FutureSpawner for TokioSpawner {
63 fn spawn<T: Future<Output = ()> + Send + 'static>(&self, future: T) {
68 /// A trivial future which joins two other futures and polls them at the same time, returning only
69 /// once both complete.
70 pub(crate) struct Joiner<
71 A: Future<Output=Result<(BlockHash, Option<u32>), BlockSourceError>> + Unpin,
72 B: Future<Output=Result<BlockHash, BlockSourceError>> + Unpin,
76 a_res: Option<(BlockHash, Option<u32>)>,
77 b_res: Option<BlockHash>,
81 A: Future<Output=Result<(BlockHash, Option<u32>), BlockSourceError>> + Unpin,
82 B: Future<Output=Result<BlockHash, BlockSourceError>> + Unpin,
84 fn new(a: A, b: B) -> Self { Self { a, b, a_res: None, b_res: None } }
88 A: Future<Output=Result<(BlockHash, Option<u32>), BlockSourceError>> + Unpin,
89 B: Future<Output=Result<BlockHash, BlockSourceError>> + Unpin,
90 > Future for Joiner<A, B> {
91 type Output = Result<((BlockHash, Option<u32>), BlockHash), BlockSourceError>;
92 fn poll(mut self: Pin<&mut Self>, ctx: &mut core::task::Context<'_>) -> Poll<Self::Output> {
93 if self.a_res.is_none() {
94 match Pin::new(&mut self.a).poll(ctx) {
97 self.a_res = Some(ok);
99 return Poll::Ready(Err(res.unwrap_err()));
105 if self.b_res.is_none() {
106 match Pin::new(&mut self.b).poll(ctx) {
107 Poll::Ready(res) => {
108 if let Ok(ok) = res {
109 self.b_res = Some(ok);
111 return Poll::Ready(Err(res.unwrap_err()));
118 if let Some(b_res) = self.b_res {
119 if let Some(a_res) = self.a_res {
120 return Poll::Ready(Ok((a_res, b_res)))
127 /// A struct which wraps a [`UtxoSource`] and a few LDK objects and implements the LDK
128 /// [`UtxoLookup`] trait.
130 /// Note that if you're using this against a Bitcoin Core REST or RPC server, you likely wish to
131 /// increase the `rpcworkqueue` setting in Bitcoin Core as LDK attempts to parallelize requests (a
132 /// value of 1024 should more than suffice), and ensure you have sufficient file descriptors
133 /// available on both Bitcoin Core and your LDK application for each request to hold its own
135 pub struct GossipVerifier<S: FutureSpawner,
136 Blocks: Deref + Send + Sync + 'static + Clone,
137 L: Deref + Send + Sync + 'static,
138 Descriptor: SocketDescriptor + Send + Sync + 'static,
139 CM: Deref + Send + Sync + 'static,
140 OM: Deref + Send + Sync + 'static,
141 CMH: Deref + Send + Sync + 'static,
142 NS: Deref + Send + Sync + 'static,
144 Blocks::Target: UtxoSource,
146 CM::Target: ChannelMessageHandler,
147 OM::Target: OnionMessageHandler,
148 CMH::Target: CustomMessageHandler,
149 NS::Target: NodeSigner,
152 peer_manager: Arc<PeerManager<Descriptor, CM, Arc<P2PGossipSync<Arc<NetworkGraph<L>>, Self, L>>, OM, L, CMH, NS>>,
153 gossiper: Arc<P2PGossipSync<Arc<NetworkGraph<L>>, Self, L>>,
155 block_cache: Arc<Mutex<VecDeque<(u32, Block)>>>,
158 const BLOCK_CACHE_SIZE: usize = 5;
160 impl<S: FutureSpawner,
161 Blocks: Deref + Send + Sync + Clone,
162 L: Deref + Send + Sync,
163 Descriptor: SocketDescriptor + Send + Sync,
164 CM: Deref + Send + Sync,
165 OM: Deref + Send + Sync,
166 CMH: Deref + Send + Sync,
167 NS: Deref + Send + Sync,
168 > GossipVerifier<S, Blocks, L, Descriptor, CM, OM, CMH, NS> where
169 Blocks::Target: UtxoSource,
171 CM::Target: ChannelMessageHandler,
172 OM::Target: OnionMessageHandler,
173 CMH::Target: CustomMessageHandler,
174 NS::Target: NodeSigner,
176 /// Constructs a new [`GossipVerifier`].
178 /// This is expected to be given to a [`P2PGossipSync`] (initially constructed with `None` for
179 /// the UTXO lookup) via [`P2PGossipSync::add_utxo_lookup`].
180 pub fn new(source: Blocks, spawn: S, gossiper: Arc<P2PGossipSync<Arc<NetworkGraph<L>>, Self, L>>, peer_manager: Arc<PeerManager<Descriptor, CM, Arc<P2PGossipSync<Arc<NetworkGraph<L>>, Self, L>>, OM, L, CMH, NS>>) -> Self {
182 source, spawn, gossiper, peer_manager,
183 block_cache: Arc::new(Mutex::new(VecDeque::with_capacity(BLOCK_CACHE_SIZE))),
187 async fn retrieve_utxo(
188 source: Blocks, block_cache: Arc<Mutex<VecDeque<(u32, Block)>>>, short_channel_id: u64
189 ) -> Result<TxOut, UtxoLookupError> {
190 let block_height = (short_channel_id >> 5 * 8) as u32; // block height is most significant three bytes
191 let transaction_index = ((short_channel_id >> 2 * 8) & 0xffffff) as u32;
192 let output_index = (short_channel_id & 0xffff) as u16;
194 let (outpoint, output);
196 'tx_found: loop { // Used as a simple goto
197 macro_rules! process_block {
198 ($block: expr) => { {
199 if transaction_index as usize >= $block.txdata.len() {
200 return Err(UtxoLookupError::UnknownTx);
202 let transaction = &$block.txdata[transaction_index as usize];
203 if output_index as usize >= transaction.output.len() {
204 return Err(UtxoLookupError::UnknownTx);
207 outpoint = OutPoint::new(transaction.txid(), output_index.into());
208 output = transaction.output[output_index as usize].clone();
212 let recent_blocks = block_cache.lock().unwrap();
213 for (height, block) in recent_blocks.iter() {
214 if *height == block_height {
215 process_block!(block);
221 let ((_, tip_height_opt), block_hash) =
222 Joiner::new(source.get_best_block(), source.get_block_hash_by_height(block_height))
224 .map_err(|_| UtxoLookupError::UnknownTx)?;
225 if let Some(tip_height) = tip_height_opt {
226 // If the block doesn't yet have five confirmations, error out.
228 // The BOLT spec requires nodes wait for six confirmations before announcing a
229 // channel, and we give them one block of headroom in case we're delayed seeing a
231 if block_height + 5 > tip_height {
232 return Err(UtxoLookupError::UnknownTx);
235 let block_data = source.get_block(&block_hash).await
236 .map_err(|_| UtxoLookupError::UnknownTx)?;
237 let block = match block_data {
238 BlockData::HeaderOnly(_) => return Err(UtxoLookupError::UnknownTx),
239 BlockData::FullBlock(block) => block,
241 process_block!(block);
243 let mut recent_blocks = block_cache.lock().unwrap();
244 let mut insert = true;
245 for (height, _) in recent_blocks.iter() {
246 if *height == block_height {
251 if recent_blocks.len() >= BLOCK_CACHE_SIZE {
252 recent_blocks.pop_front();
254 recent_blocks.push_back((block_height, block));
259 let outpoint_unspent =
260 source.is_output_unspent(outpoint).await.map_err(|_| UtxoLookupError::UnknownTx)?;
261 if outpoint_unspent {
264 Err(UtxoLookupError::UnknownTx)
269 impl<S: FutureSpawner,
270 Blocks: Deref + Send + Sync + Clone,
271 L: Deref + Send + Sync,
272 Descriptor: SocketDescriptor + Send + Sync,
273 CM: Deref + Send + Sync,
274 OM: Deref + Send + Sync,
275 CMH: Deref + Send + Sync,
276 NS: Deref + Send + Sync,
277 > Deref for GossipVerifier<S, Blocks, L, Descriptor, CM, OM, CMH, NS> where
278 Blocks::Target: UtxoSource,
280 CM::Target: ChannelMessageHandler,
281 OM::Target: OnionMessageHandler,
282 CMH::Target: CustomMessageHandler,
283 NS::Target: NodeSigner,
286 fn deref(&self) -> &Self { self }
290 impl<S: FutureSpawner,
291 Blocks: Deref + Send + Sync + Clone,
292 L: Deref + Send + Sync,
293 Descriptor: SocketDescriptor + Send + Sync,
294 CM: Deref + Send + Sync,
295 OM: Deref + Send + Sync,
296 CMH: Deref + Send + Sync,
297 NS: Deref + Send + Sync,
298 > UtxoLookup for GossipVerifier<S, Blocks, L, Descriptor, CM, OM, CMH, NS> where
299 Blocks::Target: UtxoSource,
301 CM::Target: ChannelMessageHandler,
302 OM::Target: OnionMessageHandler,
303 CMH::Target: CustomMessageHandler,
304 NS::Target: NodeSigner,
306 fn get_utxo(&self, _chain_hash: &ChainHash, short_channel_id: u64) -> UtxoResult {
307 let res = UtxoFuture::new();
308 let fut = res.clone();
309 let source = self.source.clone();
310 let gossiper = Arc::clone(&self.gossiper);
311 let block_cache = Arc::clone(&self.block_cache);
312 let pm = Arc::clone(&self.peer_manager);
313 self.spawn.spawn(async move {
314 let res = Self::retrieve_utxo(source, block_cache, short_channel_id).await;
315 fut.resolve(gossiper.network_graph(), &*gossiper, res);
318 UtxoResult::Async(res)