X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Fln%2Fchannelmanager.rs;h=a970c52de6f22b762c648ce52a7ea0e0d74ba731;hb=6a79eece219858524b733953b96111b5061f8214;hp=672cc220576d9ab0f7de00fd66fb765d0b0b8509;hpb=25e4f3e46ed4d0221e41d34ccbaa82adc87421a2;p=rust-lightning diff --git a/lightning/src/ln/channelmanager.rs b/lightning/src/ln/channelmanager.rs index 672cc220..a970c52d 100644 --- a/lightning/src/ln/channelmanager.rs +++ b/lightning/src/ln/channelmanager.rs @@ -43,6 +43,7 @@ use chain::channelmonitor::{ChannelMonitor, ChannelMonitorUpdate, ChannelMonitor use chain::transaction::{OutPoint, TransactionData}; // Since this struct is returned in `list_channels` methods, expose it here in case users want to // construct one themselves. +use ln::{PaymentHash, PaymentPreimage, PaymentSecret}; pub use ln::channel::CounterpartyForwardingInfo; use ln::channel::{Channel, ChannelError}; use ln::features::{InitFeatures, NodeFeatures}; @@ -68,7 +69,6 @@ use std::sync::atomic::{AtomicUsize, Ordering}; use std::time::Duration; #[cfg(any(test, feature = "allow_wallclock_use"))] use std::time::Instant; -use std::marker::{Sync, Send}; use std::ops::Deref; use bitcoin::hashes::hex::ToHex; @@ -197,19 +197,6 @@ pub(super) enum HTLCFailReason { } } -/// payment_hash type, use to cross-lock hop -/// (C-not exported) as we just use [u8; 32] directly -#[derive(Hash, Copy, Clone, PartialEq, Eq, Debug)] -pub struct PaymentHash(pub [u8;32]); -/// payment_preimage type, use to route payment between hop -/// (C-not exported) as we just use [u8; 32] directly -#[derive(Hash, Copy, Clone, PartialEq, Eq, Debug)] -pub struct PaymentPreimage(pub [u8;32]); -/// payment_secret type, use to authenticate sender to the receiver and tie MPP HTLCs together -/// (C-not exported) as we just use [u8; 32] directly -#[derive(Hash, Copy, Clone, PartialEq, Eq, Debug)] -pub struct PaymentSecret(pub [u8;32]); - type ShutdownResult = (Option<(OutPoint, ChannelMonitorUpdate)>, Vec<(HTLCSource, PaymentHash)>); /// Error type returned across the channel_state mutex boundary. When an Err is generated for a @@ -362,6 +349,8 @@ struct PendingInboundPayment { /// Time at which this HTLC expires - blocks with a header time above this value will result in /// this payment being removed. expiry_time: u64, + /// Arbitrary identifier the user specifies (or not) + user_payment_id: u64, // Other required attributes of the payment, optionally enforced: payment_preimage: Option, min_value_msat: Option, @@ -449,7 +438,7 @@ pub struct ChannelManager>, @@ -586,6 +575,11 @@ pub(crate) const MAX_LOCAL_BREAKDOWN_TIMEOUT: u16 = 2 * 6 * 24 * 7; pub const MIN_CLTV_EXPIRY_DELTA: u16 = 6 * 6; pub(super) const CLTV_FAR_FAR_AWAY: u32 = 6 * 24 * 7; //TODO? +/// Minimum CLTV difference between the current block height and received inbound payments. +/// Invoices generated for payment to us must set their `min_final_cltv_expiry` field to at least +/// this value. +pub const MIN_FINAL_CLTV_EXPIRY: u32 = HTLC_FAIL_BACK_BUFFER; + // Check that our CLTV_EXPIRY is at least CLTV_CLAIM_BUFFER + ANTI_REORG_DELAY + LATENCY_GRACE_PERIOD_BLOCKS, // ie that if the next-hop peer fails the HTLC within // LATENCY_GRACE_PERIOD_BLOCKS then we'll still have CLTV_CLAIM_BUFFER left to timeout it onchain, @@ -610,6 +604,12 @@ pub struct ChannelDetails { /// Note that this means this value is *not* persistent - it can change once during the /// lifetime of the channel. pub channel_id: [u8; 32], + /// The Channel's funding transaction output, if we've negotiated the funding transaction with + /// our counterparty already. + /// + /// Note that, if this has been set, `channel_id` will be equivalent to + /// `funding_txo.unwrap().to_channel_id()`. + pub funding_txo: Option, /// The position of the funding transaction in the chain. None if the funding transaction has /// not yet been confirmed and the channel fully opened. pub short_channel_id: Option, @@ -634,10 +634,21 @@ pub struct ChannelDetails { /// Note that there are some corner cases not fully handled here, so the actual available /// inbound capacity may be slightly higher than this. pub inbound_capacity_msat: u64, + /// True if the channel was initiated (and thus funded) by us. + pub is_outbound: bool, + /// True if the channel is confirmed, funding_locked messages have been exchanged, and the + /// channel is not currently being shut down. `funding_locked` message exchange implies the + /// required confirmation count has been reached (and we were connected to the peer at some + /// point after the funding transaction received enough confirmations). + pub is_funding_locked: bool, /// True if the channel is (a) confirmed and funding_locked messages have been exchanged, (b) - /// the peer is connected, and (c) no monitor update failure is pending resolution. + /// the peer is connected, (c) no monitor update failure is pending resolution, and (d) the + /// channel is not currently negotiating a shutdown. + /// + /// This is a strict superset of `is_funding_locked`. pub is_live: bool, - + /// True if this channel is (or will be) publicly-announced. + pub is_public: bool, /// Information on the fees and requirements that the counterparty requires when forwarding /// payments to us through this channel. pub counterparty_forwarding_info: Option, @@ -960,6 +971,7 @@ impl ChannelMana let (inbound_capacity_msat, outbound_capacity_msat) = channel.get_inbound_outbound_available_balance_msat(); res.push(ChannelDetails { channel_id: (*channel_id).clone(), + funding_txo: channel.get_funding_txo(), short_channel_id: channel.get_short_channel_id(), remote_network_id: channel.get_counterparty_node_id(), counterparty_features: InitFeatures::empty(), @@ -967,7 +979,10 @@ impl ChannelMana inbound_capacity_msat, outbound_capacity_msat, user_id: channel.get_user_id(), + is_outbound: channel.is_outbound(), + is_funding_locked: channel.is_usable(), is_live: channel.is_live(), + is_public: channel.should_announce(), counterparty_forwarding_info: channel.counterparty_forwarding_info(), }); } @@ -2022,8 +2037,10 @@ impl ChannelMana } else if total_value == payment_data.total_msat { new_events.push(events::Event::PaymentReceived { payment_hash, - payment_secret: Some(payment_data.payment_secret), + payment_preimage: inbound_payment.get().payment_preimage, + payment_secret: payment_data.payment_secret, amt: total_value, + user_payment_id: inbound_payment.get().user_payment_id, }); // Only ever generate at most one PaymentReceived // per registered payment_hash, even if it isn't @@ -2122,7 +2139,7 @@ impl ChannelMana /// along the path (including in our own channel on which we received it). /// Returns false if no payment was found to fail backwards, true if the process of failing the /// HTLC backwards has been started. - pub fn fail_htlc_backwards(&self, payment_hash: &PaymentHash, _payment_secret: &Option) -> bool { + pub fn fail_htlc_backwards(&self, payment_hash: &PaymentHash) -> bool { let _persistence_guard = PersistenceNotifierGuard::new(&self.total_consistency_lock, &self.persistence_notifier); let mut channel_state = Some(self.channel_state.lock().unwrap()); @@ -2291,18 +2308,16 @@ impl ChannelMana /// generating message events for the net layer to claim the payment, if possible. Thus, you /// should probably kick the net layer to go send messages if this returns true! /// - /// You must specify the expected amounts for this HTLC, and we will only claim HTLCs - /// available within a few percent of the expected amount. This is critical for several - /// reasons : a) it avoids providing senders with `proof-of-payment` (in the form of the - /// payment_preimage without having provided the full value and b) it avoids certain - /// privacy-breaking recipient-probing attacks which may reveal payment activity to - /// motivated attackers. - /// - /// Note that the privacy concerns in (b) are not relevant in payments with a payment_secret - /// set. Thus, for such payments we will claim any payments which do not under-pay. + /// Note that if you did not set an `amount_msat` when calling [`create_inbound_payment`] or + /// [`create_inbound_payment_for_hash`] you must check that the amount in the `PaymentReceived` + /// event matches your expectation. If you fail to do so and call this method, you may provide + /// the sender "proof-of-payment" when they did not fulfill the full expected payment. /// /// May panic if called except in response to a PaymentReceived event. - pub fn claim_funds(&self, payment_preimage: PaymentPreimage, _payment_secret: &Option, expected_amount: u64) -> bool { + /// + /// [`create_inbound_payment`]: Self::create_inbound_payment + /// [`create_inbound_payment_for_hash`]: Self::create_inbound_payment_for_hash + pub fn claim_funds(&self, payment_preimage: PaymentPreimage) -> bool { let payment_hash = PaymentHash(Sha256::hash(&payment_preimage.0).into_inner()); let _persistence_guard = PersistenceNotifierGuard::new(&self.total_consistency_lock, &self.persistence_notifier); @@ -2323,7 +2338,7 @@ impl ChannelMana // we got all the HTLCs and then a channel closed while we were waiting for the user to // provide the preimage, so worrying too much about the optimal handling isn't worth // it. - let mut valid_mpp = sources[0].payment_data.total_msat >= expected_amount; + let mut valid_mpp = true; for htlc in sources.iter() { if let None = channel_state.as_ref().unwrap().short_to_id.get(&htlc.prev_hop.short_channel_id) { valid_mpp = false; @@ -3377,7 +3392,7 @@ impl ChannelMana } } - fn set_payment_hash_secret_map(&self, payment_hash: PaymentHash, payment_preimage: Option, min_value_msat: Option, invoice_expiry_delta_secs: u32) -> Result { + fn set_payment_hash_secret_map(&self, payment_hash: PaymentHash, payment_preimage: Option, min_value_msat: Option, invoice_expiry_delta_secs: u32, user_payment_id: u64) -> Result { assert!(invoice_expiry_delta_secs <= 60*60*24*365); // Sadly bitcoin timestamps are u32s, so panic before 2106 let payment_secret = PaymentSecret(self.keys_manager.get_secure_random_bytes()); @@ -3387,7 +3402,7 @@ impl ChannelMana match payment_secrets.entry(payment_hash) { hash_map::Entry::Vacant(e) => { e.insert(PendingInboundPayment { - payment_secret, min_value_msat, payment_preimage, + payment_secret, min_value_msat, user_payment_id, payment_preimage, // We assume that highest_seen_timestamp is pretty close to the current time - // its updated when we receive a new block with the maximum time we've seen in // a header. It should never be more than two hours in the future. @@ -3409,15 +3424,22 @@ impl ChannelMana /// This differs from [`create_inbound_payment_for_hash`] only in that it generates the /// [`PaymentHash`] and [`PaymentPreimage`] for you, returning the first and storing the second. /// + /// The [`PaymentPreimage`] will ultimately be returned to you in the [`PaymentReceived`], which + /// will have the [`PaymentReceived::payment_preimage`] field filled in. That should then be + /// passed directly to [`claim_funds`]. + /// /// See [`create_inbound_payment_for_hash`] for detailed documentation on behavior and requirements. /// + /// [`claim_funds`]: Self::claim_funds + /// [`PaymentReceived`]: events::Event::PaymentReceived + /// [`PaymentReceived::payment_preimage`]: events::Event::PaymentReceived::payment_preimage /// [`create_inbound_payment_for_hash`]: Self::create_inbound_payment_for_hash - pub fn create_inbound_payment(&self, min_value_msat: Option, invoice_expiry_delta_secs: u32) -> (PaymentHash, PaymentSecret) { + pub fn create_inbound_payment(&self, min_value_msat: Option, invoice_expiry_delta_secs: u32, user_payment_id: u64) -> (PaymentHash, PaymentSecret) { let payment_preimage = PaymentPreimage(self.keys_manager.get_secure_random_bytes()); let payment_hash = PaymentHash(Sha256::hash(&payment_preimage.0).into_inner()); (payment_hash, - self.set_payment_hash_secret_map(payment_hash, Some(payment_preimage), min_value_msat, invoice_expiry_delta_secs) + self.set_payment_hash_secret_map(payment_hash, Some(payment_preimage), min_value_msat, invoice_expiry_delta_secs, user_payment_id) .expect("RNG Generated Duplicate PaymentHash")) } @@ -3431,6 +3453,12 @@ impl ChannelMana /// The [`PaymentHash`] (and corresponding [`PaymentPreimage`]) must be globally unique. This /// method may return an Err if another payment with the same payment_hash is still pending. /// + /// `user_payment_id` will be provided back in [`PaymentReceived::user_payment_id`] events to + /// allow tracking of which events correspond with which calls to this and + /// [`create_inbound_payment`]. `user_payment_id` has no meaning inside of LDK, it is simply + /// copied to events and otherwise ignored. It may be used to correlate PaymentReceived events + /// with invoice metadata stored elsewhere. + /// /// `min_value_msat` should be set if the invoice being generated contains a value. Any payment /// received for the returned [`PaymentHash`] will be required to be at least `min_value_msat` /// before a [`PaymentReceived`] event will be generated, ensuring that we do not provide the @@ -3448,12 +3476,20 @@ impl ChannelMana /// If you need exact expiry semantics, you should enforce them upon receipt of /// [`PaymentReceived`]. /// + /// Pending inbound payments are stored in memory and in serialized versions of this + /// [`ChannelManager`]. If potentially unbounded numbers of inbound payments may exist and + /// space is limited, you may wish to rate-limit inbound payment creation. + /// /// May panic if `invoice_expiry_delta_secs` is greater than one year. /// + /// Note that invoices generated for inbound payments should have their `min_final_cltv_expiry` + /// set to at least [`MIN_FINAL_CLTV_EXPIRY`]. + /// /// [`create_inbound_payment`]: Self::create_inbound_payment /// [`PaymentReceived`]: events::Event::PaymentReceived - pub fn create_inbound_payment_for_hash(&self, payment_hash: PaymentHash, min_value_msat: Option, invoice_expiry_delta_secs: u32) -> Result { - self.set_payment_hash_secret_map(payment_hash, None, min_value_msat, invoice_expiry_delta_secs) + /// [`PaymentReceived::user_payment_id`]: events::Event::PaymentReceived::user_payment_id + pub fn create_inbound_payment_for_hash(&self, payment_hash: PaymentHash, min_value_msat: Option, invoice_expiry_delta_secs: u32, user_payment_id: u64) -> Result { + self.set_payment_hash_secret_map(payment_hash, None, min_value_msat, invoice_expiry_delta_secs, user_payment_id) } } @@ -3585,6 +3621,10 @@ where } max_time!(self.last_node_announcement_serial); max_time!(self.highest_seen_timestamp); + let mut payment_secrets = self.pending_inbound_payments.lock().unwrap(); + payment_secrets.retain(|_, inbound_payment| { + inbound_payment.expiry_time > header.time as u64 + }); } fn get_relevant_txids(&self) -> Vec { @@ -3736,7 +3776,7 @@ where } } -impl +impl ChannelMessageHandler for ChannelManager where M::Target: chain::Watch, T::Target: BroadcasterInterface, @@ -4280,6 +4320,7 @@ impl Readable for HTLCForwardInfo { impl_writeable!(PendingInboundPayment, 0, { payment_secret, expiry_time, + user_payment_id, payment_preimage, min_value_msat }); @@ -4824,7 +4865,7 @@ pub mod bench { payment_preimage.0[0..8].copy_from_slice(&payment_count.to_le_bytes()); payment_count += 1; let payment_hash = PaymentHash(Sha256::hash(&payment_preimage.0[..]).into_inner()); - let payment_secret = $node_b.create_inbound_payment_for_hash(payment_hash, None, 7200).unwrap(); + let payment_secret = $node_b.create_inbound_payment_for_hash(payment_hash, None, 7200, 0).unwrap(); $node_a.send_payment(&route, payment_hash, &Some(payment_secret)).unwrap(); let payment_event = SendEvent::from_event($node_a.get_and_clear_pending_msg_events().pop().unwrap()); @@ -4837,7 +4878,7 @@ pub mod bench { expect_pending_htlcs_forwardable!(NodeHolder { node: &$node_b }); expect_payment_received!(NodeHolder { node: &$node_b }, payment_hash, payment_secret, 10_000); - assert!($node_b.claim_funds(payment_preimage, &Some(payment_secret), 10_000)); + assert!($node_b.claim_funds(payment_preimage)); match $node_b.get_and_clear_pending_msg_events().pop().unwrap() { MessageSendEvent::UpdateHTLCs { node_id, updates } => {