Add transaction sync crate

This crate provides utilities for syncing LDK via the transaction-based
`Confirm` interface. The initial implementation facilitates
synchronization with an Esplora backend server.

Author: tnull

Cargo.toml

@@ -3,6 +3,7 @@
 members = [
     "lightning",
     "lightning-block-sync",
+    "lightning-transaction-sync",
     "lightning-invoice",
     "lightning-net-tokio",
     "lightning-persister",

lightning-transaction-sync/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "lightning-transaction-sync"
+version = "0.0.113"
+authors = ["Elias Rohrer"]
+license = "MIT OR Apache-2.0"
+repository = "http://github.com/lightningdevkit/rust-lightning"
+description = """
+Utilities for syncing LDK via the transaction-based `Confirm` interface.
+"""
+edition = "2018"
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]
+
+[features]
+default = []
+esplora-async = ["async-interface", "esplora-client/async", "futures"]
+esplora-blocking = ["esplora-client/blocking"]
+async-interface = []
+
+[dependencies]
+lightning = { version = "0.0.113", path = "../lightning" }
+bitcoin = "0.29.0"
+bdk-macros = "0.6"
+futures = { version = "0.3", optional = true }
+esplora-client = { version = "0.3.0", default-features = false, optional = true }

lightning-transaction-sync/src/common.rs

@@ -0,0 +1,75 @@
+use lightning::chain::WatchedOutput;
+use bitcoin::{Txid, BlockHash, Transaction, BlockHeader, OutPoint};
+
+use std::collections::{HashSet, HashMap};
+
+
+// Represents the current state.
+pub(crate) struct SyncState {
+	// Transactions that were previously processed, but must not be forgotten
+	// yet since they still need to be monitored for confirmation on-chain.
+	pub watched_transactions: HashSet<Txid>,
+	// Outputs that were previously processed, but must not be forgotten yet as
+	// as we still need to monitor any spends on-chain.
+	pub watched_outputs: HashMap<OutPoint, WatchedOutput>,
+	// The tip hash observed during our last sync.
+	pub last_sync_hash: Option<BlockHash>,
+	// Indicates whether we need to resync, e.g., after encountering an error.
+	pub pending_sync: bool,
+}
+
+impl SyncState {
+	pub fn new() -> Self {
+		Self {
+			watched_transactions: HashSet::new(),
+			watched_outputs: HashMap::new(),
+			last_sync_hash: None,
+			pending_sync: false,
+		}
+	}
+}
+
+
+// A queue that is to be filled by `Filter` and drained during the next syncing round.
+pub(crate) struct FilterQueue {
+	// Transactions that were registered via the `Filter` interface and have to be processed.
+	pub transactions: HashSet<Txid>,
+	// Outputs that were registered via the `Filter` interface and have to be processed.
+	pub outputs: HashMap<OutPoint, WatchedOutput>,
+}
+
+impl FilterQueue {
+	pub fn new() -> Self {
+		Self {
+			transactions: HashSet::new(),
+			outputs: HashMap::new(),
+		}
+	}
+
+	// Processes the transaction and output queues and adds them to the given [`SyncState`].
+	//
+	// Returns `true` if new items had been registered.
+	pub fn process_queues(&mut self, sync_state: &mut SyncState) -> bool {
+		let mut pending_registrations = false;
+
+		if !self.transactions.is_empty() {
+			pending_registrations = true;
+
+			sync_state.watched_transactions.extend(self.transactions.drain());
+		}
+
+		if !self.outputs.is_empty() {
+			pending_registrations = true;
+
+			sync_state.watched_outputs.extend(self.outputs.drain());
+		}
+		pending_registrations
+	}
+}
+
+pub(crate) struct ConfirmedTx {
+	pub tx: Transaction,
+	pub block_header: BlockHeader,
+	pub block_height: u32,
+	pub pos: usize,
+}

lightning-transaction-sync/src/error.rs

@@ -0,0 +1,63 @@
+use std::fmt;
+
+#[derive(Debug)]
+/// An error that possibly needs to be handled by the user.
+pub enum TxSyncError {
+	/// A transaction sync failed and needs to be retried eventually.
+	Failed,
+}
+
+impl std::error::Error for TxSyncError {}
+
+impl fmt::Display for TxSyncError {
+	fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+		match *self {
+			Self::Failed => write!(f, "Failed to conduct transaction sync."),
+		}
+	}
+}
+
+#[derive(Debug)]
+#[cfg(any(feature = "esplora-blocking", feature = "esplora-async"))]
+pub(crate) enum InternalError {
+	/// A transaction sync failed and needs to be retried eventually.
+	Failed,
+	/// An inconsisteny was encounterd during transaction sync.
+	Inconsistency,
+}
+
+#[cfg(any(feature = "esplora-blocking", feature = "esplora-async"))]
+impl fmt::Display for InternalError {
+	fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+		match *self {
+			Self::Failed => write!(f, "Failed to conduct transaction sync."),
+			Self::Inconsistency => {
+				write!(f, "Encountered an inconsisteny during transaction sync.")
+			}
+		}
+	}
+}
+
+#[cfg(any(feature = "esplora-blocking", feature = "esplora-async"))]
+impl std::error::Error for InternalError {}
+
+#[cfg(any(feature = "esplora-blocking", feature = "esplora-async"))]
+impl From<esplora_client::Error> for TxSyncError {
+	fn from(_e: esplora_client::Error) -> Self {
+		Self::Failed
+	}
+}
+
+#[cfg(any(feature = "esplora-blocking", feature = "esplora-async"))]
+impl From<esplora_client::Error> for InternalError {
+	fn from(_e: esplora_client::Error) -> Self {
+		Self::Failed
+	}
+}
+
+#[cfg(any(feature = "esplora-blocking", feature = "esplora-async"))]
+impl From<InternalError> for TxSyncError {
+	fn from(_e: InternalError) -> Self {
+		Self::Failed
+	}
+}