Add anchor support

bindings/kotlin/ldk-node-jvm/lib/src/test/kotlin/org/lightningdevkit/ldknode/LibraryTest.kt

@@ -203,9 +203,9 @@ class LibraryTest {
  val spendableBalance2AfterOpen = node2.listBalances().spendableOnchainBalanceSats
  println("Spendable balance 1 after open: $spendableBalance1AfterOpen")
  println("Spendable balance 2 after open: $spendableBalance2AfterOpen")
- assert(spendableBalance1AfterOpen > 49000u)
- assert(spendableBalance1AfterOpen < 50000u)
- assertEquals(100000uL, spendableBalance2AfterOpen)
+ assert(spendableBalance1AfterOpen > 24000u)
+ assert(spendableBalance1AfterOpen < 25000u)
+ assertEquals(75000uL, spendableBalance2AfterOpen)
 
  val channelReadyEvent1 = node1.waitNextEvent()
  println("Got event: $channelReadyEvent1")

bindings/ldk_node.udl

@@ -15,6 +15,12 @@ dictionary Config {
 	sequence<PublicKey> trusted_peers_0conf;
 	u64 probing_liquidity_limit_multiplier;
 	LogLevel log_level;
+	AnchorChannelsConfig? anchor_channels_config;
+};
+
+dictionary AnchorChannelsConfig {
+	sequence<PublicKey> trusted_peers_no_reserve;
+	u64 per_channel_reserve_sats;
 };
 
 interface Builder {
@@ -66,6 +72,8 @@ interface Node {
 	[Throws=NodeError]
 	void close_channel([ByRef]UserChannelId user_channel_id, PublicKey counterparty_node_id);
 	[Throws=NodeError]
+	void force_close_channel([ByRef]UserChannelId user_channel_id, PublicKey counterparty_node_id);
+	[Throws=NodeError]
 	void update_channel_config([ByRef]UserChannelId user_channel_id, PublicKey counterparty_node_id, ChannelConfig channel_config);
 	[Throws=NodeError]
 	void sync_wallets();
@@ -348,6 +356,7 @@ interface PendingSweepBalance {
 dictionary BalanceDetails {
 	u64 total_onchain_balance_sats;
 	u64 spendable_onchain_balance_sats;
+	u64 total_anchor_channels_reserve_sats;
 	u64 total_lightning_balance_sats;
 	sequence<LightningBalance> lightning_balances;
 	sequence<PendingSweepBalance> pending_balances_from_channel_closures;

docker-compose-cln.yml

@@ -63,6 +63,7 @@ services:
  "--bitcoin-rpcuser=user",
  "--bitcoin-rpcpassword=pass",
  "--regtest",
+ "--experimental-anchors",
  ]
  ports:
  - "19846:19846"

src/balance.rs

@@ -15,7 +15,15 @@ pub struct BalanceDetails {
 	/// The total balance of our on-chain wallet.
 	pub total_onchain_balance_sats: u64,
 	/// The currently spendable balance of our on-chain wallet.
+	///
+	/// This includes any sufficiently confirmed funds, minus
+	/// [`total_anchor_channels_reserve_sats`].
+	///
+	/// [`total_anchor_channels_reserve_sats`]: Self::total_anchor_channels_reserve_sats
 	pub spendable_onchain_balance_sats: u64,
+	/// The share of our total balance that we retain as an emergency reserve to (hopefully) be
+	/// able to spend the Anchor outputs when one of our channels is closed.
+	pub total_anchor_channels_reserve_sats: u64,
 	/// The total balance that we would be able to claim across all our Lightning channels.
 	///
 	/// Note this excludes balances that we are unsure if we are able to claim (e.g., as we are

src/builder.rs

@@ -693,12 +693,11 @@ fn build_with_store_internal(
 	// for inbound channels.
 	let mut user_config = UserConfig::default();
 	user_config.channel_handshake_limits.force_announced_channel_preference = false;
-
-	if !config.trusted_peers_0conf.is_empty() {
- // Manually accept inbound channels if we expect 0conf channel requests, avoid
- // generating the events otherwise.
- user_config.manually_accept_inbound_channels = true;
-	}
+	user_config.manually_accept_inbound_channels = true;
+	// Note the channel_handshake_config will be overwritten in `connect_open_channel`, but we
+	// still set a default here.
+	user_config.channel_handshake_config.negotiate_anchors_zero_fee_htlc_tx =
+ config.anchor_channels_config.is_some();
 
 	if liquidity_source_config.and_then(|lsc| lsc.lsps2_service.as_ref()).is_some() {
  // Generally allow claiming underpaying HTLCs as the LSP will skim off some fee. We'll

src/config.rs

@@ -15,6 +15,7 @@ const DEFAULT_LDK_WALLET_SYNC_INTERVAL_SECS: u64 = 30;
 const DEFAULT_FEE_RATE_CACHE_UPDATE_INTERVAL_SECS: u64 = 60 * 10;
 const DEFAULT_PROBING_LIQUIDITY_LIMIT_MULTIPLIER: u64 = 3;
 const DEFAULT_LOG_LEVEL: LogLevel = LogLevel::Debug;
+const DEFAULT_ANCHOR_PER_CHANNEL_RESERVE_SATS: u64 = 25_000;
 
 // The 'stop gap' parameter used by BDK's wallet sync. This seems to configure the threshold
 // number of derivation indexes after which BDK stops looking for new scripts belonging to the wallet.
@@ -62,6 +63,9 @@ pub(crate) const WALLET_KEYS_SEED_LEN: usize = 64;
 /// | `trusted_peers_0conf` | [] |
 /// | `probing_liquidity_limit_multiplier` | 3 |
 /// | `log_level` | Debug |
+/// | `anchor_channels_config` | Some(..) |
+///
+/// See [`AnchorChannelsConfig`] for more information on its respective default values.
 ///
 /// [`Node`]: crate::Node
 pub struct Config {
@@ -104,6 +108,23 @@ pub struct Config {
 	///
 	/// Any messages below this level will be excluded from the logs.
 	pub log_level: LogLevel,
+	/// Configuration options pertaining to Anchor channels, i.e., channels for which the
+	/// `option_anchors_zero_fee_htlc_tx` channel type is negotiated.
+	///
+	/// Please refer to [`AnchorChannelsConfig`] for further information on Anchor channels.
+	///
+	/// If set to `Some`, we'll try to open new channels with Anchors enabled, i.e., new channels
+	/// will be negotiated with the `option_anchors_zero_fee_htlc_tx` channel type if supported by
+	/// the counterparty. Note that this won't prevent us from opening non-Anchor channels if the
+	/// counterparty doesn't support `option_anchors_zero_fee_htlc_tx`. If set to `None`, new
+	/// channels will be negotiated with the legacy `option_static_remotekey` channel type only.
+	///
+	/// **Note:** If set to `None` *after* some Anchor channels have already been
+	/// opened, no dedicated emergency on-chain reserve will be maintained for these channels,
+	/// which can be dangerous if only insufficient funds are available at the time of channel
+	/// closure. We *will* however still try to get the Anchor spending transactions confirmed
+	/// on-chain with the funds available.
+	pub anchor_channels_config: Option<AnchorChannelsConfig>,
 }
 
 impl Default for Config {
@@ -120,6 +141,78 @@ impl Default for Config {
  trusted_peers_0conf: Vec::new(),
  probing_liquidity_limit_multiplier: DEFAULT_PROBING_LIQUIDITY_LIMIT_MULTIPLIER,
  log_level: DEFAULT_LOG_LEVEL,
+ anchor_channels_config: Some(AnchorChannelsConfig::default()),
+ }
+	}
+}
+
+/// Configuration options pertaining to 'Anchor' channels, i.e., channels for which the
+/// `option_anchors_zero_fee_htlc_tx` channel type is negotiated.
+///
+/// Prior to the introduction of Anchor channels, the on-chain fees paying for the transactions
+/// issued on channel closure were pre-determined and locked-in at the time of the channel
+/// opening. This required to estimate what fee rate would be sufficient to still have the
+/// closing transactions be spendable on-chain (i.e., not be considered dust). This legacy
+/// design of pre-anchor channels proved inadequate in the unpredictable, often turbulent, fee
+/// markets we experience today.
+///
+/// In contrast, Anchor channels allow to determine an adequate fee rate *at the time of channel
+/// closure*, making them much more robust in the face of fee spikes. In turn, they require to
+/// maintain a reserve of on-chain funds to have the channel closure transactions confirmed
+/// on-chain, at least if the channel counterparty can't be trusted to do this for us.
+///
+/// See [BOLT 3] for more technical details on Anchor channels.
+///
+///
+/// ### Defaults
+///
+/// | Parameter | Value |
+/// |----------------------------|--------|
+/// | `trusted_peers_no_reserve` | [] |
+/// | `per_channel_reserve_sats` | 25000 |
+///
+///
+/// [BOLT 3]: https://github.com/lightning/bolts/blob/master/03-transactions.md#htlc-timeout-and-htlc-success-transactions
+#[derive(Debug, Clone)]
+pub struct AnchorChannelsConfig {
+	/// A list of peers that we trust to get the required channel closing transactions confirmed
+	/// on-chain.
+	///
+	/// Channels with these peers won't count towards the retained on-chain reserve and we won't
+	/// take any action to get the required transactions confirmed ourselves.
+	///
+	/// **Note:** Trusting the channel counterparty to take the necessary actions to get the
+	/// required Anchor spending and HTLC transactions confirmed on-chain is potentially insecure
+	/// as the channel may not be closed if they refuse to do so, potentially leaving the user
+	/// funds stuck *or* even allow the counterparty to steal any in-flight funds after the
+	/// corresponding HTLCs time out.
+	pub trusted_peers_no_reserve: Vec<PublicKey>,
+	/// The amount of satoshis per anchors-negotiated channel with an untrusted peer that we keep
+	/// as an emergency reserve in our on-chain wallet.
+	///
+	/// This allows for having the required Anchor output spending and HTLC transactions confirmed
+	/// when the channel is closed.
+	///
+	/// If the channel peer is not marked as trusted via
+	/// [`AnchorChannelsConfig::trusted_peers_no_reserve`], we will always try to spend the Anchor
+	/// outputs with *any* on-chain funds available, i.e., the total reserve value as well as any
+	/// spendable funds available in the on-chain wallet. Therefore, this per-channel multiplier is
+	/// really a emergencey reserve that we maintain at all time to reduce reduce the risk of
+	/// insufficient funds at time of a channel closure. To this end, we will refuse to open
+	/// outbound or accept inbound channels if we don't have sufficient on-chain funds availble to
+	/// cover the additional reserve requirement.
+	///
+	/// **Note:** Depending on the fee market at the time of closure, this reserve amount might or
+	/// might not suffice to successfully spend the Anchor output and have the HTLC transactions
+	/// confirmed on-chain, i.e., you may want to adjust this value accordingly.
+	pub per_channel_reserve_sats: u64,
+}
+
+impl Default for AnchorChannelsConfig {
+	fn default() -> Self {
+ Self {
+ trusted_peers_no_reserve: Vec::new(),
+ per_channel_reserve_sats: DEFAULT_ANCHOR_PER_CHANNEL_RESERVE_SATS,
  }
 	}
 }

src/event.rs

@@ -1,7 +1,8 @@
 use crate::types::{DynStore, Sweeper, Wallet};
 
 use crate::{
-	hex_utils, ChannelManager, Config, Error, NetworkGraph, PeerInfo, PeerStore, UserChannelId,
+	hex_utils, BumpTransactionEventHandler, ChannelManager, Config, Error, NetworkGraph, PeerInfo,
+	PeerStore, UserChannelId,
 };
 
 use crate::connection::ConnectionManager;
@@ -15,9 +16,10 @@ use crate::io::{
 	EVENT_QUEUE_PERSISTENCE_KEY, EVENT_QUEUE_PERSISTENCE_PRIMARY_NAMESPACE,
 	EVENT_QUEUE_PERSISTENCE_SECONDARY_NAMESPACE,
 };
-use crate::logger::{log_error, log_info, Logger};
+use crate::logger::{log_debug, log_error, log_info, Logger};
 
 use lightning::chain::chaininterface::ConfirmationTarget;
+use lightning::events::bump_transaction::BumpTransactionEvent;
 use lightning::events::{ClosureReason, PaymentPurpose};
 use lightning::events::{Event as LdkEvent, PaymentFailureReason};
 use lightning::impl_writeable_tlv_based_enum;
@@ -317,6 +319,7 @@ where
 {
 	event_queue: Arc<EventQueue<L>>,
 	wallet: Arc<Wallet>,
+	bump_tx_event_handler: Arc<BumpTransactionEventHandler>,
 	channel_manager: Arc<ChannelManager>,
 	connection_manager: Arc<ConnectionManager<L>>,
 	output_sweeper: Arc<Sweeper>,
@@ -333,15 +336,17 @@ where
 	L::Target: Logger,
 {
 	pub fn new(
- event_queue: Arc<EventQueue<L>>, wallet: Arc<Wallet>, channel_manager: Arc<ChannelManager>,
- connection_manager: Arc<ConnectionManager<L>>, output_sweeper: Arc<Sweeper>,
- network_graph: Arc<NetworkGraph>, payment_store: Arc<PaymentStore<L>>,
- peer_store: Arc<PeerStore<L>>, runtime: Arc<RwLock<Option<tokio::runtime::Runtime>>>,
- logger: L, config: Arc<Config>,
+ event_queue: Arc<EventQueue<L>>, wallet: Arc<Wallet>,
+ bump_tx_event_handler: Arc<BumpTransactionEventHandler>,
+ channel_manager: Arc<ChannelManager>, connection_manager: Arc<ConnectionManager<L>>,
+ output_sweeper: Arc<Sweeper>, network_graph: Arc<NetworkGraph>,
+ payment_store: Arc<PaymentStore<L>>, peer_store: Arc<PeerStore<L>>,
+ runtime: Arc<RwLock<Option<tokio::runtime::Runtime>>>, logger: L, config: Arc<Config>,
 	) -> Self {
  Self {
  event_queue,
  wallet,
+ bump_tx_event_handler,
  channel_manager,
  connection_manager,
  output_sweeper,
@@ -815,9 +820,67 @@ where
  temporary_channel_id,
  counterparty_node_id,
  funding_satoshis,
- channel_type: _,
+ channel_type,
  push_msat: _,
  } => {
+ let anchor_channel = channel_type.requires_anchors_zero_fee_htlc_tx();
+
+ if anchor_channel {
+ if let Some(anchor_channels_config) =
+ self.config.anchor_channels_config.as_ref()
+ {
+ let cur_anchor_reserve_sats = crate::total_anchor_channels_reserve_sats(
+ &self.channel_manager,
+ &self.config,
+ );
+ let spendable_amount_sats = self
+ .wallet
+ .get_spendable_amount_sats(cur_anchor_reserve_sats)
+ .unwrap_or(0);
+
+ let required_amount_sats = if anchor_channels_config
+ .trusted_peers_no_reserve
+ .contains(&counterparty_node_id)
+ {
+ 0
+ } else {
+ anchor_channels_config.per_channel_reserve_sats
+ };
+
+ if spendable_amount_sats < required_amount_sats {
+ log_error!(
+ self.logger,
+ "Rejecting inbound Anchor channel from peer {} due to insufficient available on-chain reserves.",
+ counterparty_node_id,
+ );
+ self.channel_manager
+ .force_close_without_broadcasting_txn(
+ &temporary_channel_id,
+ &counterparty_node_id,
+ )
+ .unwrap_or_else(|e| {
+ log_error!(self.logger, "Failed to reject channel: {:?}", e)
+ });
+ return;
+ }
+ } else {
+ log_error!(
+ self.logger,
+ "Rejecting inbound channel from peer {} due to Anchor channels being disabled.",
+ counterparty_node_id,
+ );
+ self.channel_manager
+ .force_close_without_broadcasting_txn(
+ &temporary_channel_id,
+ &counterparty_node_id,
+ )
+ .unwrap_or_else(|e| {
+ log_error!(self.logger, "Failed to reject channel: {:?}", e)
+ });
+ return;
+ }
+ }
+
  let user_channel_id: u128 = rand::thread_rng().gen::<u128>();
  let allow_0conf = self.config.trusted_peers_0conf.contains(&counterparty_node_id);
  let res = if allow_0conf {
@@ -838,8 +901,9 @@ where
  Ok(()) => {
  log_info!(
  self.logger,
- "Accepting inbound{} channel of {}sats from{} peer {}",
+ "Accepting inbound{}{} channel of {}sats from{} peer {}",
  if allow_0conf { " 0conf" } else { "" },
+ if anchor_channel { " Anchor" } else { "" },
  funding_satoshis,
  if allow_0conf { " trusted" } else { "" },
  counterparty_node_id,
@@ -848,8 +912,9 @@ where
  Err(e) => {
  log_error!(
  self.logger,
- "Error while accepting inbound{} channel from{} peer {}: {:?}",
+ "Error while accepting inbound{}{} channel from{} peer {}: {:?}",
  if allow_0conf { " 0conf" } else { "" },
+ if anchor_channel { " Anchor" } else { "" },
  counterparty_node_id,
  if allow_0conf { " trusted" } else { "" },
  e,
@@ -1018,7 +1083,6 @@ where
  },
  LdkEvent::DiscardFunding { .. } => {},
  LdkEvent::HTLCIntercepted { .. } => {},
- LdkEvent::BumpTransaction(_) => {},
  LdkEvent::InvoiceRequestFailed { payment_id } => {
  log_error!(
  self.logger,
@@ -1062,6 +1126,35 @@ where
  });
  }
  },
+ LdkEvent::BumpTransaction(bte) => {
+ let (channel_id, counterparty_node_id) = match bte {
+ BumpTransactionEvent::ChannelClose {
+ ref channel_id,
+ ref counterparty_node_id,
+ ..
+ } => (channel_id, counterparty_node_id),
+ BumpTransactionEvent::HTLCResolution {
+ ref channel_id,
+ ref counterparty_node_id,
+ ..
+ } => (channel_id, counterparty_node_id),
+ };
+
+ if let Some(anchor_channels_config) = self.config.anchor_channels_config.as_ref() {
+ if anchor_channels_config
+ .trusted_peers_no_reserve
+ .contains(counterparty_node_id)
+ {
+ log_debug!(self.logger,
+ "Ignoring BumpTransactionEvent for channel {} due to trusted counterparty {}",
+ channel_id, counterparty_node_id
+ );
+ return;
+ }
+ }
+
+ self.bump_tx_event_handler.handle_event(&bte);
+ },
  }
 	}
 }