X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning-c-bindings%2Fsrc%2Flightning%2Futil%2Fconfig.rs;h=df0220e37a7c971f8e38687f23fa0b943c61b320;hb=68c220f7ee4fa0b6b4a300f56cd30b9b02ebfbdf;hp=63def438b9558bf52c754d844c98985bd4b9c245;hpb=6658ad877ed253301df2c729b1c6a2a859515777;p=ldk-c-bindings diff --git a/lightning-c-bindings/src/lightning/util/config.rs b/lightning-c-bindings/src/lightning/util/config.rs index 63def43..df0220e 100644 --- a/lightning-c-bindings/src/lightning/util/config.rs +++ b/lightning-c-bindings/src/lightning/util/config.rs @@ -340,21 +340,27 @@ pub extern "C" fn ChannelHandshakeLimits_get_max_minimum_depth(this_ptr: &Channe pub extern "C" fn ChannelHandshakeLimits_set_max_minimum_depth(this_ptr: &mut ChannelHandshakeLimits, mut val: u32) { unsafe { &mut *this_ptr.inner }.max_minimum_depth = val; } -/// Set to force the incoming channel to match our announced channel preference in -/// ChannelConfig. +/// Set to force an incoming channel to match our announced channel preference in +/// [`ChannelConfig::announced_channel`]. /// -/// Default value: true, to make the default that no announced channels are possible (which is -/// appropriate for any nodes which are not online very reliably). +/// 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) +/// channels will ever be opened. +/// +/// Default value: true. #[no_mangle] pub extern "C" fn ChannelHandshakeLimits_get_force_announced_channel_preference(this_ptr: &ChannelHandshakeLimits) -> bool { let mut inner_val = &mut unsafe { &mut *this_ptr.inner }.force_announced_channel_preference; *inner_val } -/// Set to force the incoming channel to match our announced channel preference in -/// ChannelConfig. +/// Set to force an incoming channel to match our announced channel preference in +/// [`ChannelConfig::announced_channel`]. /// -/// Default value: true, to make the default that no announced channels are possible (which is -/// appropriate for any nodes which are not online very reliably). +/// 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) +/// channels will ever be opened. +/// +/// Default value: true. #[no_mangle] pub extern "C" fn ChannelHandshakeLimits_set_force_announced_channel_preference(this_ptr: &mut ChannelHandshakeLimits, mut val: bool) { unsafe { &mut *this_ptr.inner }.force_announced_channel_preference = val; @@ -468,24 +474,59 @@ impl ChannelConfig { ret } } -/// Amount (in millionths of a satoshi) the channel will charge per transferred satoshi. +/// Amount (in millionths of a satoshi) charged per satoshi for payments forwarded outbound +/// over the channel. /// This may be allowed to change at runtime in a later update, however doing so must result in /// update messages sent to notify all nodes of our updated relay fee. /// /// Default value: 0. #[no_mangle] -pub extern "C" fn ChannelConfig_get_fee_proportional_millionths(this_ptr: &ChannelConfig) -> u32 { - let mut inner_val = &mut unsafe { &mut *this_ptr.inner }.fee_proportional_millionths; +pub extern "C" fn ChannelConfig_get_forwarding_fee_proportional_millionths(this_ptr: &ChannelConfig) -> u32 { + let mut inner_val = &mut unsafe { &mut *this_ptr.inner }.forwarding_fee_proportional_millionths; *inner_val } -/// Amount (in millionths of a satoshi) the channel will charge per transferred satoshi. +/// Amount (in millionths of a satoshi) charged per satoshi for payments forwarded outbound +/// over the channel. /// This may be allowed to change at runtime in a later update, however doing so must result in /// update messages sent to notify all nodes of our updated relay fee. /// /// Default value: 0. #[no_mangle] -pub extern "C" fn ChannelConfig_set_fee_proportional_millionths(this_ptr: &mut ChannelConfig, mut val: u32) { - unsafe { &mut *this_ptr.inner }.fee_proportional_millionths = val; +pub extern "C" fn ChannelConfig_set_forwarding_fee_proportional_millionths(this_ptr: &mut ChannelConfig, mut val: u32) { + unsafe { &mut *this_ptr.inner }.forwarding_fee_proportional_millionths = val; +} +/// Amount (in milli-satoshi) charged for payments forwarded outbound over the channel, in +/// excess of [`forwarding_fee_proportional_millionths`]. +/// This may be allowed to change at runtime in a later update, however doing so must result in +/// update messages sent to notify all nodes of our updated relay fee. +/// +/// The default value of a single satoshi roughly matches the market rate on many routing nodes +/// as of July 2021. Adjusting it upwards or downwards may change whether nodes route through +/// this node. +/// +/// Default value: 1000. +/// +/// [`forwarding_fee_proportional_millionths`]: ChannelConfig::forwarding_fee_proportional_millionths +#[no_mangle] +pub extern "C" fn ChannelConfig_get_forwarding_fee_base_msat(this_ptr: &ChannelConfig) -> u32 { + let mut inner_val = &mut unsafe { &mut *this_ptr.inner }.forwarding_fee_base_msat; + *inner_val +} +/// Amount (in milli-satoshi) charged for payments forwarded outbound over the channel, in +/// excess of [`forwarding_fee_proportional_millionths`]. +/// This may be allowed to change at runtime in a later update, however doing so must result in +/// update messages sent to notify all nodes of our updated relay fee. +/// +/// The default value of a single satoshi roughly matches the market rate on many routing nodes +/// as of July 2021. Adjusting it upwards or downwards may change whether nodes route through +/// this node. +/// +/// Default value: 1000. +/// +/// [`forwarding_fee_proportional_millionths`]: ChannelConfig::forwarding_fee_proportional_millionths +#[no_mangle] +pub extern "C" fn ChannelConfig_set_forwarding_fee_base_msat(this_ptr: &mut ChannelConfig, mut val: u32) { + unsafe { &mut *this_ptr.inner }.forwarding_fee_base_msat = val; } /// The difference in the CLTV value between incoming HTLCs and an outbound HTLC forwarded over /// the channel this config applies to. @@ -540,7 +581,7 @@ pub extern "C" fn ChannelConfig_set_cltv_expiry_delta(this_ptr: &mut ChannelConf /// 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_preferences is set. +/// channels unless [`ChannelHandshakeLimits::force_announced_channel_preference`] is set. /// /// This cannot be changed after the initial channel handshake. /// @@ -556,7 +597,7 @@ pub extern "C" fn ChannelConfig_get_announced_channel(this_ptr: &ChannelConfig) /// 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_preferences is set. +/// channels unless [`ChannelHandshakeLimits::force_announced_channel_preference`] is set. /// /// This cannot be changed after the initial channel handshake. /// @@ -596,15 +637,110 @@ pub extern "C" fn ChannelConfig_get_commit_upfront_shutdown_pubkey(this_ptr: &Ch pub extern "C" fn ChannelConfig_set_commit_upfront_shutdown_pubkey(this_ptr: &mut ChannelConfig, mut val: bool) { unsafe { &mut *this_ptr.inner }.commit_upfront_shutdown_pubkey = val; } +/// Limit our total exposure to in-flight HTLCs which are burned to fees as they are too +/// small to claim on-chain. +/// +/// When an HTLC present in one of our channels is below a \"dust\" threshold, the HTLC will +/// not be claimable on-chain, instead being turned into additional miner fees if either +/// party force-closes the channel. Because the threshold is per-HTLC, our total exposure +/// to such payments may be sustantial if there are many dust HTLCs present when the +/// channel is force-closed. +/// +/// 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 +/// important to prevent stealing of dust HTLCs by miners. +/// +/// Default value: 5_000_000 msat. +#[no_mangle] +pub extern "C" fn ChannelConfig_get_max_dust_htlc_exposure_msat(this_ptr: &ChannelConfig) -> u64 { + let mut inner_val = &mut unsafe { &mut *this_ptr.inner }.max_dust_htlc_exposure_msat; + *inner_val +} +/// Limit our total exposure to in-flight HTLCs which are burned to fees as they are too +/// small to claim on-chain. +/// +/// When an HTLC present in one of our channels is below a \"dust\" threshold, the HTLC will +/// not be claimable on-chain, instead being turned into additional miner fees if either +/// party force-closes the channel. Because the threshold is per-HTLC, our total exposure +/// to such payments may be sustantial if there are many dust HTLCs present when the +/// channel is force-closed. +/// +/// 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 +/// important to prevent stealing of dust HTLCs by miners. +/// +/// Default value: 5_000_000 msat. +#[no_mangle] +pub extern "C" fn ChannelConfig_set_max_dust_htlc_exposure_msat(this_ptr: &mut ChannelConfig, mut val: u64) { + unsafe { &mut *this_ptr.inner }.max_dust_htlc_exposure_msat = val; +} +/// The additional fee we're willing to pay to avoid waiting for the counterparty's +/// `to_self_delay` to reclaim funds. +/// +/// When we close a channel cooperatively with our counterparty, we negotiate a fee for the +/// closing transaction which both sides find acceptable, ultimately paid by the channel +/// funder/initiator. +/// +/// When we are the funder, because we have to pay the channel closing fee, we bound the +/// acceptable fee by our [`Background`] and [`Normal`] fees, with the upper bound increased by +/// this value. Because the on-chain fee we'd pay to force-close the channel is kept near our +/// [`Normal`] feerate during normal operation, this value represents the additional fee we're +/// willing to pay in order to avoid waiting for our counterparty's to_self_delay to reclaim our +/// funds. +/// +/// When we are not the funder, we require the closing transaction fee pay at least our +/// [`Background`] fee estimate, but allow our counterparty to pay as much fee as they like. +/// Thus, this value is ignored when we are not the funder. +/// +/// Default value: 1000 satoshis. +/// +/// [`Normal`]: crate::chain::chaininterface::ConfirmationTarget::Normal +/// [`Background`]: crate::chain::chaininterface::ConfirmationTarget::Background +#[no_mangle] +pub extern "C" fn ChannelConfig_get_force_close_avoidance_max_fee_satoshis(this_ptr: &ChannelConfig) -> u64 { + let mut inner_val = &mut unsafe { &mut *this_ptr.inner }.force_close_avoidance_max_fee_satoshis; + *inner_val +} +/// The additional fee we're willing to pay to avoid waiting for the counterparty's +/// `to_self_delay` to reclaim funds. +/// +/// When we close a channel cooperatively with our counterparty, we negotiate a fee for the +/// closing transaction which both sides find acceptable, ultimately paid by the channel +/// funder/initiator. +/// +/// When we are the funder, because we have to pay the channel closing fee, we bound the +/// acceptable fee by our [`Background`] and [`Normal`] fees, with the upper bound increased by +/// this value. Because the on-chain fee we'd pay to force-close the channel is kept near our +/// [`Normal`] feerate during normal operation, this value represents the additional fee we're +/// willing to pay in order to avoid waiting for our counterparty's to_self_delay to reclaim our +/// funds. +/// +/// When we are not the funder, we require the closing transaction fee pay at least our +/// [`Background`] fee estimate, but allow our counterparty to pay as much fee as they like. +/// Thus, this value is ignored when we are not the funder. +/// +/// Default value: 1000 satoshis. +/// +/// [`Normal`]: crate::chain::chaininterface::ConfirmationTarget::Normal +/// [`Background`]: crate::chain::chaininterface::ConfirmationTarget::Background +#[no_mangle] +pub extern "C" fn ChannelConfig_set_force_close_avoidance_max_fee_satoshis(this_ptr: &mut ChannelConfig, mut val: u64) { + unsafe { &mut *this_ptr.inner }.force_close_avoidance_max_fee_satoshis = val; +} /// Constructs a new ChannelConfig given each field #[must_use] #[no_mangle] -pub extern "C" fn ChannelConfig_new(mut fee_proportional_millionths_arg: u32, mut cltv_expiry_delta_arg: u16, mut announced_channel_arg: bool, mut commit_upfront_shutdown_pubkey_arg: bool) -> ChannelConfig { +pub extern "C" fn ChannelConfig_new(mut forwarding_fee_proportional_millionths_arg: u32, mut forwarding_fee_base_msat_arg: u32, mut cltv_expiry_delta_arg: u16, mut announced_channel_arg: bool, mut commit_upfront_shutdown_pubkey_arg: bool, mut max_dust_htlc_exposure_msat_arg: u64, mut force_close_avoidance_max_fee_satoshis_arg: u64) -> ChannelConfig { ChannelConfig { inner: Box::into_raw(Box::new(nativeChannelConfig { - fee_proportional_millionths: fee_proportional_millionths_arg, + forwarding_fee_proportional_millionths: forwarding_fee_proportional_millionths_arg, + forwarding_fee_base_msat: forwarding_fee_base_msat_arg, cltv_expiry_delta: cltv_expiry_delta_arg, announced_channel: announced_channel_arg, commit_upfront_shutdown_pubkey: commit_upfront_shutdown_pubkey_arg, + max_dust_htlc_exposure_msat: max_dust_htlc_exposure_msat_arg, + force_close_avoidance_max_fee_satoshis: force_close_avoidance_max_fee_satoshis_arg, })), is_owned: true } } impl Clone for ChannelConfig { @@ -729,14 +865,56 @@ pub extern "C" fn UserConfig_get_channel_options(this_ptr: &UserConfig) -> crate pub extern "C" fn UserConfig_set_channel_options(this_ptr: &mut UserConfig, mut val: crate::lightning::util::config::ChannelConfig) { unsafe { &mut *this_ptr.inner }.channel_options = *unsafe { Box::from_raw(val.take_inner()) }; } +/// 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 +/// [`ChannelHandshakeLimits::force_announced_channel_preference`]) and set this to false to +/// ensure you are not exposed to any forwarding risk. +/// +/// Note that because you cannot change a channel's announced state after creation, there is no +/// way to disable forwarding on public channels retroactively. Thus, in order to change a node +/// from a publicly-announced forwarding node to a private non-forwarding node you must close +/// all your channels and open new ones. For privacy, you should also change your node_id +/// (swapping all private and public key material for new ones) at that time. +/// +/// Default value: false. +#[no_mangle] +pub extern "C" fn UserConfig_get_accept_forwards_to_priv_channels(this_ptr: &UserConfig) -> bool { + let mut inner_val = &mut unsafe { &mut *this_ptr.inner }.accept_forwards_to_priv_channels; + *inner_val +} +/// 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 +/// [`ChannelHandshakeLimits::force_announced_channel_preference`]) and set this to false to +/// ensure you are not exposed to any forwarding risk. +/// +/// Note that because you cannot change a channel's announced state after creation, there is no +/// way to disable forwarding on public channels retroactively. Thus, in order to change a node +/// from a publicly-announced forwarding node to a private non-forwarding node you must close +/// all your channels and open new ones. For privacy, you should also change your node_id +/// (swapping all private and public key material for new ones) at that time. +/// +/// Default value: false. +#[no_mangle] +pub extern "C" fn UserConfig_set_accept_forwards_to_priv_channels(this_ptr: &mut UserConfig, mut val: bool) { + unsafe { &mut *this_ptr.inner }.accept_forwards_to_priv_channels = val; +} /// Constructs a new UserConfig given each field #[must_use] #[no_mangle] -pub extern "C" fn UserConfig_new(mut own_channel_config_arg: crate::lightning::util::config::ChannelHandshakeConfig, mut peer_channel_config_limits_arg: crate::lightning::util::config::ChannelHandshakeLimits, mut channel_options_arg: crate::lightning::util::config::ChannelConfig) -> UserConfig { +pub extern "C" fn UserConfig_new(mut own_channel_config_arg: crate::lightning::util::config::ChannelHandshakeConfig, mut peer_channel_config_limits_arg: crate::lightning::util::config::ChannelHandshakeLimits, mut channel_options_arg: crate::lightning::util::config::ChannelConfig, mut accept_forwards_to_priv_channels_arg: bool) -> UserConfig { UserConfig { inner: Box::into_raw(Box::new(nativeUserConfig { own_channel_config: *unsafe { Box::from_raw(own_channel_config_arg.take_inner()) }, peer_channel_config_limits: *unsafe { Box::from_raw(peer_channel_config_limits_arg.take_inner()) }, channel_options: *unsafe { Box::from_raw(channel_options_arg.take_inner()) }, + accept_forwards_to_priv_channels: accept_forwards_to_priv_channels_arg, })), is_owned: true } } impl Clone for UserConfig {