X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Futil%2Fconfig.rs;h=2f65e958f8b60d0f0a0f72d3cd3b7ca1b009085a;hb=28c9b56113ff1ebb1b505a2c979c55c1626aa06b;hp=c591cacb3463fd6e216a24da8390bdce6ddde1f9;hpb=22398853c97966f42c709669fff3c63486d82993;p=rust-lightning diff --git a/lightning/src/util/config.rs b/lightning/src/util/config.rs index c591cacb..2f65e958 100644 --- a/lightning/src/util/config.rs +++ b/lightning/src/util/config.rs @@ -10,6 +10,7 @@ //! Various user-configurable channel limits and settings which ChannelManager //! applies for you. +use ln::channel::MAX_FUNDING_SATOSHIS_NO_WUMBO; use ln::channelmanager::{BREAKDOWN_TIMEOUT, MAX_LOCAL_BREAKDOWN_TIMEOUT}; /// Configuration we set when applicable. @@ -21,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 @@ -47,6 +56,76 @@ pub struct ChannelHandshakeConfig { /// Default value: 1. If the value is less than 1, it is ignored and set to 1, as is required /// by the protocol. pub our_htlc_minimum_msat: u64, + /// Sets the percentage of the channel value we will cap the total value of outstanding inbound + /// HTLCs to. + /// + /// This can be set to a value between 1-100, where the value corresponds to the percent of the + /// channel value in whole percentages. + /// + /// Note that: + /// * If configured to another value than the default value 10, any new channels created with + /// the non default value will cause versions of LDK prior to 0.0.104 to refuse to read the + /// `ChannelManager`. + /// + /// * This caps the total value for inbound HTLCs in-flight only, and there's currently + /// no way to configure the cap for the total value of outbound HTLCs in-flight. + /// + /// * The requirements for your node being online to ensure the safety of HTLC-encumbered funds + /// are different from the non-HTLC-encumbered funds. This makes this an important knob to + /// restrict exposure to loss due to being offline for too long. + /// See [`ChannelHandshakeConfig::our_to_self_delay`] and [`ChannelConfig::cltv_expiry_delta`] + /// for more information. + /// + /// Default value: 10. + /// Minimum value: 1, any values less than 1 will be treated as 1 instead. + /// Maximum value: 100, any values larger than 100 will be treated as 100 instead. + pub max_inbound_htlc_value_in_flight_percent_of_channel: u8, + /// If set, we attempt to negotiate the `scid_privacy` (referred to as `scid_alias` in the + /// BOLTs) option for outbound private channels. This provides better privacy by not including + /// our real on-chain channel UTXO in each invoice and requiring that our counterparty only + /// relay HTLCs to us using the channel's SCID alias. + /// + /// 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`]. + /// + /// 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 + /// [`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 + 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, } impl Default for ChannelHandshakeConfig { @@ -55,6 +134,10 @@ impl Default for ChannelHandshakeConfig { minimum_depth: 6, our_to_self_delay: BREAKDOWN_TIMEOUT, 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, } } } @@ -72,11 +155,16 @@ impl Default for ChannelHandshakeConfig { /// are applied mostly only to incoming channels that's not much of a problem. #[derive(Copy, Clone, Debug)] pub struct ChannelHandshakeLimits { - /// Minimum allowed satoshis when a channel is funded, this is supplied by the sender and so + /// Minimum allowed satoshis when a channel is funded. This is supplied by the sender and so /// only applies to inbound channels. /// /// Default value: 0. pub min_funding_satoshis: u64, + /// Maximum allowed satoshis when a channel is funded. This is supplied by the sender and so + /// only applies to inbound channels. + /// + /// Default value: 2^24 - 1. + pub max_funding_satoshis: u64, /// The remote node sets a limit on the minimum size of HTLCs we can send to them. This allows /// you to limit the maximum minimum-size they can require. /// @@ -105,11 +193,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. @@ -128,10 +234,12 @@ impl Default for ChannelHandshakeLimits { fn default() -> Self { ChannelHandshakeLimits { min_funding_satoshis: 0, + max_funding_satoshis: MAX_FUNDING_SATOSHIS_NO_WUMBO, max_htlc_minimum_msat: ::max_value(), 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, @@ -141,7 +249,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. @@ -183,30 +291,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. /// @@ -255,8 +339,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, } @@ -265,32 +347,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. /// @@ -305,16 +460,31 @@ pub struct UserConfig { /// If this is set to false, we do not accept inbound requests to open a new channel. /// Default value: true. pub accept_inbound_channels: bool, + /// If this is set to true, the user needs to manually accept inbound requests to open a new + /// channel. + /// + /// When set to true, [`Event::OpenChannelRequest`] will be triggered once a request to open a + /// new inbound channel is received through a [`msgs::OpenChannel`] message. In that case, a + /// [`msgs::AcceptChannel`] message will not be sent back to the counterparty node unless the + /// user explicitly chooses to accept the request. + /// + /// Default value: false. + /// + /// [`Event::OpenChannelRequest`]: crate::util::events::Event::OpenChannelRequest + /// [`msgs::OpenChannel`]: crate::ln::msgs::OpenChannel + /// [`msgs::AcceptChannel`]: crate::ln::msgs::AcceptChannel + pub manually_accept_inbound_channels: bool, } 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, } } }