X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Futil%2Fconfig.rs;h=b2004df3e9cbd0c043c2b2ef184e538f267ea02a;hb=f961daef33ad1e999c83aafbf654db449e0e93e0;hp=3868d29aab49f66789c49c970a662cba19000e2e;hpb=d96a492b96df914cfd0ae389fd04fd7d8337f269;p=rust-lightning diff --git a/lightning/src/util/config.rs b/lightning/src/util/config.rs index 3868d29a..b2004df3 100644 --- a/lightning/src/util/config.rs +++ b/lightning/src/util/config.rs @@ -22,7 +22,15 @@ pub struct ChannelHandshakeConfig { /// Applied only for inbound channels (see ChannelHandshakeLimits::max_minimum_depth for the /// equivalent limit applied to outbound channels). /// + /// A lower-bound of 1 is applied, requiring all channels to have a confirmed commitment + /// transaction before operation. If you wish to accept channels with zero confirmations, see + /// [`UserConfig::manually_accept_inbound_channels`] and + /// [`ChannelManager::accept_inbound_channel_from_trusted_peer_0conf`]. + /// /// Default value: 6. + /// + /// [`ChannelManager::accept_inbound_channel`]: crate::ln::channelmanager::ChannelManager::accept_inbound_channel + /// [`ChannelManager::accept_inbound_channel_from_trusted_peer_0conf`]: crate::ln::channelmanager::ChannelManager::accept_inbound_channel_from_trusted_peer_0conf pub minimum_depth: u32, /// Set to the number of blocks we require our counterparty to wait to claim their money (ie /// the number of blocks we have to punish our counterparty if they broadcast a revoked @@ -79,21 +87,69 @@ pub struct ChannelHandshakeConfig { /// /// If this option is set, channels may be created that will not be readable by LDK versions /// prior to 0.0.106, causing [`ChannelManager`]'s read method to return a - /// [`DecodeError:InvalidValue`]. + /// [`DecodeError::InvalidValue`]. /// /// Note that setting this to true does *not* prevent us from opening channels with /// counterparties that do not support the `scid_alias` option; we will simply fall back to a /// private channel without that option. /// /// Ignored if the channel is negotiated to be announced, see - /// [`ChannelConfig::announced_channel`] and + /// [`ChannelHandshakeConfig::announced_channel`] and /// [`ChannelHandshakeLimits::force_announced_channel_preference`] for more. /// /// Default value: false. This value is likely to change to true in the future. /// /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager - /// [`DecodeError:InvalidValue`]: crate::ln::msgs::DecodeError::InvalidValue + /// [`DecodeError::InvalidValue`]: crate::ln::msgs::DecodeError::InvalidValue pub negotiate_scid_privacy: bool, + /// Set to announce the channel publicly and notify all nodes that they can route via this + /// channel. + /// + /// This should only be set to true for nodes which expect to be online reliably. + /// + /// As the node which funds a channel picks this value this will only apply for new outbound + /// channels unless [`ChannelHandshakeLimits::force_announced_channel_preference`] is set. + /// + /// Default value: false. + pub announced_channel: bool, + /// When set, we commit to an upfront shutdown_pubkey at channel open. If our counterparty + /// supports it, they will then enforce the mutual-close output to us matches what we provided + /// at intialization, preventing us from closing to an alternate pubkey. + /// + /// This is set to true by default to provide a slight increase in security, though ultimately + /// any attacker who is able to take control of a channel can just as easily send the funds via + /// lightning payments, so we never require that our counterparties support this option. + /// + /// The upfront key committed is provided from [`KeysInterface::get_shutdown_scriptpubkey`]. + /// + /// Default value: true. + /// + /// [`KeysInterface::get_shutdown_scriptpubkey`]: crate::chain::keysinterface::KeysInterface::get_shutdown_scriptpubkey + pub commit_upfront_shutdown_pubkey: bool, + + /// The Proportion of the channel value to configure as counterparty's channel reserve, + /// i.e., `their_channel_reserve_satoshis` for both outbound and inbound channels. + /// + /// `their_channel_reserve_satoshis` is the minimum balance that the other node has to maintain + /// on their side, at all times. + /// This ensures that if our counterparty broadcasts a revoked state, we can punish them by + /// claiming at least this value on chain. + /// + /// Channel reserve values greater than 30% could be considered highly unreasonable, since that + /// amount can never be used for payments. + /// Also, if our selected channel reserve for counterparty and counterparty's selected + /// channel reserve for us sum up to equal or greater than channel value, channel negotiations + /// will fail. + /// + /// Note: Versions of LDK earlier than v0.0.104 will fail to read channels with any channel reserve + /// other than the default value. + /// + /// Default value: 1% of channel value, i.e., configured as 10,000 millionths. + /// Minimum value: If the calculated proportional value is less than 1000 sats, it will be treated + /// as 1000 sats instead, which is a safe implementation-specific lower bound. + /// Maximum value: 1,000,000, any values larger than 1 Million will be treated as 1 Million (or 100%) + /// instead, although channel negotiations will fail in that case. + pub their_channel_reserve_proportional_millionths: u32 } impl Default for ChannelHandshakeConfig { @@ -104,6 +160,9 @@ impl Default for ChannelHandshakeConfig { our_htlc_minimum_msat: 1, max_inbound_htlc_value_in_flight_percent_of_channel: 10, negotiate_scid_privacy: false, + announced_channel: false, + commit_upfront_shutdown_pubkey: true, + their_channel_reserve_proportional_millionths: 10_000, } } } @@ -159,11 +218,29 @@ pub struct ChannelHandshakeLimits { /// /// Default value: 144, or roughly one day and only applies to outbound channels. pub max_minimum_depth: u32, + /// Whether we implicitly trust funding transactions generated by us for our own outbound + /// channels to not be double-spent. + /// + /// If this is set, we assume that our own funding transactions are *never* double-spent, and + /// thus we can trust them without any confirmations. This is generally a reasonable + /// assumption, given we're the only ones who could ever double-spend it (assuming we have sole + /// control of the signing keys). + /// + /// You may wish to un-set this if you allow the user to (or do in an automated fashion) + /// double-spend the funding transaction to RBF with an alternative channel open. + /// + /// This only applies if our counterparty set their confirmations-required value to 0, and we + /// always trust our own funding transaction at 1 confirmation irrespective of this value. + /// Thus, this effectively acts as a `min_minimum_depth`, with the only possible values being + /// `true` (0) and `false` (1). + /// + /// Default value: true + pub trust_own_funding_0conf: bool, /// Set to force an incoming channel to match our announced channel preference in - /// [`ChannelConfig::announced_channel`]. + /// [`ChannelHandshakeConfig::announced_channel`]. /// /// For a node which is not online reliably, this should be set to true and - /// [`ChannelConfig::announced_channel`] set to false, ensuring that no announced (aka public) + /// [`ChannelHandshakeConfig::announced_channel`] set to false, ensuring that no announced (aka public) /// channels will ever be opened. /// /// Default value: true. @@ -187,6 +264,7 @@ impl Default for ChannelHandshakeLimits { min_max_htlc_value_in_flight_msat: 0, max_channel_reserve_satoshis: ::max_value(), min_max_accepted_htlcs: 0, + trust_own_funding_0conf: true, max_minimum_depth: 144, force_announced_channel_preference: true, their_to_self_delay: MAX_LOCAL_BREAKDOWN_TIMEOUT, @@ -196,7 +274,7 @@ impl Default for ChannelHandshakeLimits { /// Options which apply on a per-channel basis and may change at runtime or based on negotiation /// with our counterparty. -#[derive(Copy, Clone, Debug)] +#[derive(Copy, Clone, Debug, PartialEq)] pub struct ChannelConfig { /// Amount (in millionths of a satoshi) charged per satoshi for payments forwarded outbound /// over the channel. @@ -238,30 +316,6 @@ pub struct ChannelConfig { /// /// [`MIN_CLTV_EXPIRY_DELTA`]: crate::ln::channelmanager::MIN_CLTV_EXPIRY_DELTA pub cltv_expiry_delta: u16, - /// Set to announce the channel publicly and notify all nodes that they can route via this - /// channel. - /// - /// This should only be set to true for nodes which expect to be online reliably. - /// - /// As the node which funds a channel picks this value this will only apply for new outbound - /// channels unless [`ChannelHandshakeLimits::force_announced_channel_preference`] is set. - /// - /// This cannot be changed after the initial channel handshake. - /// - /// Default value: false. - pub announced_channel: bool, - /// When set, we commit to an upfront shutdown_pubkey at channel open. If our counterparty - /// supports it, they will then enforce the mutual-close output to us matches what we provided - /// at intialization, preventing us from closing to an alternate pubkey. - /// - /// This is set to true by default to provide a slight increase in security, though ultimately - /// any attacker who is able to take control of a channel can just as easily send the funds via - /// lightning payments, so we never require that our counterparties support this option. - /// - /// This cannot be changed after a channel has been initialized. - /// - /// Default value: true. - pub commit_upfront_shutdown_pubkey: bool, /// Limit our total exposure to in-flight HTLCs which are burned to fees as they are too /// small to claim on-chain. /// @@ -271,6 +325,12 @@ pub struct ChannelConfig { /// to such payments may be sustantial if there are many dust HTLCs present when the /// channel is force-closed. /// + /// The dust threshold for each HTLC is based on the `dust_limit_satoshis` for each party in a + /// channel negotiated throughout the channel open process, along with the fees required to have + /// a broadcastable HTLC spending transaction. When a channel supports anchor outputs + /// (specifically the zero fee HTLC transaction variant), this threshold no longer takes into + /// account the HTLC transaction fee as it is zero. + /// /// This limit is applied for sent, forwarded, and received HTLCs and limits the total /// exposure across all three types per-channel. Setting this too low may prevent the /// sending or receipt of low-value HTLCs on high-traffic nodes, and this limit is very @@ -310,8 +370,6 @@ impl Default for ChannelConfig { forwarding_fee_proportional_millionths: 0, forwarding_fee_base_msat: 1000, cltv_expiry_delta: 6 * 12, // 6 blocks/hour * 12 hours - announced_channel: false, - commit_upfront_shutdown_pubkey: true, max_dust_htlc_exposure_msat: 5_000_000, force_close_avoidance_max_fee_satoshis: 1000, } @@ -320,32 +378,105 @@ impl Default for ChannelConfig { impl_writeable_tlv_based!(ChannelConfig, { (0, forwarding_fee_proportional_millionths, required), - (1, max_dust_htlc_exposure_msat, (default_value, 5_000_000)), - (2, cltv_expiry_delta, required), - (3, force_close_avoidance_max_fee_satoshis, (default_value, 1000)), - (4, announced_channel, required), - (6, commit_upfront_shutdown_pubkey, required), - (8, forwarding_fee_base_msat, required), + (2, forwarding_fee_base_msat, required), + (4, cltv_expiry_delta, required), + (6, max_dust_htlc_exposure_msat, required), + // ChannelConfig serialized this field with a required type of 8 prior to the introduction of + // LegacyChannelConfig. To make sure that serialization is not compatible with this one, we use + // the next required type of 10, which if seen by the old serialization will always fail. + (10, force_close_avoidance_max_fee_satoshis, required), }); +/// Legacy version of [`ChannelConfig`] that stored the static +/// [`ChannelHandshakeConfig::announced_channel`] and +/// [`ChannelHandshakeConfig::commit_upfront_shutdown_pubkey`] fields. +#[derive(Copy, Clone, Debug)] +pub(crate) struct LegacyChannelConfig { + pub(crate) options: ChannelConfig, + /// Deprecated but may still be read from. See [`ChannelHandshakeConfig::announced_channel`] to + /// set this when opening/accepting a channel. + pub(crate) announced_channel: bool, + /// Deprecated but may still be read from. See + /// [`ChannelHandshakeConfig::commit_upfront_shutdown_pubkey`] to set this when + /// opening/accepting a channel. + pub(crate) commit_upfront_shutdown_pubkey: bool, +} + +impl Default for LegacyChannelConfig { + fn default() -> Self { + Self { + options: ChannelConfig::default(), + announced_channel: false, + commit_upfront_shutdown_pubkey: true, + } + } +} + +impl ::util::ser::Writeable for LegacyChannelConfig { + fn write(&self, writer: &mut W) -> Result<(), ::io::Error> { + write_tlv_fields!(writer, { + (0, self.options.forwarding_fee_proportional_millionths, required), + (1, self.options.max_dust_htlc_exposure_msat, (default_value, 5_000_000)), + (2, self.options.cltv_expiry_delta, required), + (3, self.options.force_close_avoidance_max_fee_satoshis, (default_value, 1000)), + (4, self.announced_channel, required), + (6, self.commit_upfront_shutdown_pubkey, required), + (8, self.options.forwarding_fee_base_msat, required), + }); + Ok(()) + } +} + +impl ::util::ser::Readable for LegacyChannelConfig { + fn read(reader: &mut R) -> Result { + let mut forwarding_fee_proportional_millionths = 0; + let mut max_dust_htlc_exposure_msat = 5_000_000; + let mut cltv_expiry_delta = 0; + let mut force_close_avoidance_max_fee_satoshis = 1000; + let mut announced_channel = false; + let mut commit_upfront_shutdown_pubkey = false; + let mut forwarding_fee_base_msat = 0; + read_tlv_fields!(reader, { + (0, forwarding_fee_proportional_millionths, required), + (1, max_dust_htlc_exposure_msat, (default_value, 5_000_000u64)), + (2, cltv_expiry_delta, required), + (3, force_close_avoidance_max_fee_satoshis, (default_value, 1000u64)), + (4, announced_channel, required), + (6, commit_upfront_shutdown_pubkey, required), + (8, forwarding_fee_base_msat, required), + }); + Ok(Self { + options: ChannelConfig { + forwarding_fee_proportional_millionths, + max_dust_htlc_exposure_msat, + cltv_expiry_delta, + force_close_avoidance_max_fee_satoshis, + forwarding_fee_base_msat, + }, + announced_channel, + commit_upfront_shutdown_pubkey, + }) + } +} + /// Top-level config which holds ChannelHandshakeLimits and ChannelConfig. /// /// Default::default() provides sane defaults for most configurations /// (but currently with 0 relay fees!) #[derive(Copy, Clone, Debug)] pub struct UserConfig { - /// Channel config that we propose to our counterparty. - pub own_channel_config: ChannelHandshakeConfig, - /// Limits applied to our counterparty's proposed channel config settings. - pub peer_channel_config_limits: ChannelHandshakeLimits, + /// Channel handshake config that we propose to our counterparty. + pub channel_handshake_config: ChannelHandshakeConfig, + /// Limits applied to our counterparty's proposed channel handshake config settings. + pub channel_handshake_limits: ChannelHandshakeLimits, /// Channel config which affects behavior during channel lifetime. - pub channel_options: ChannelConfig, + pub channel_config: ChannelConfig, /// If this is set to false, we will reject any HTLCs which were to be forwarded over private /// channels. This prevents us from taking on HTLC-forwarding risk when we intend to run as a /// node which is not online reliably. /// /// For nodes which are not online reliably, you should set all channels to *not* be announced - /// (using [`ChannelConfig::announced_channel`] and + /// (using [`ChannelHandshakeConfig::announced_channel`] and /// [`ChannelHandshakeLimits::force_announced_channel_preference`]) and set this to false to /// ensure you are not exposed to any forwarding risk. /// @@ -379,9 +510,9 @@ pub struct UserConfig { impl Default for UserConfig { fn default() -> Self { UserConfig { - own_channel_config: ChannelHandshakeConfig::default(), - peer_channel_config_limits: ChannelHandshakeLimits::default(), - channel_options: ChannelConfig::default(), + channel_handshake_config: ChannelHandshakeConfig::default(), + channel_handshake_limits: ChannelHandshakeLimits::default(), + channel_config: ChannelConfig::default(), accept_forwards_to_priv_channels: false, accept_inbound_channels: true, manually_accept_inbound_channels: false,