Update docs regarding payment path privacy
[rust-lightning] / lightning-invoice / src / payment.rs
index 9fb472d3b311fbc872bdab4d5c74455a4f4e6857..82f1149db1fbf5771d043b6582a33e510f8ab5f6 100644 (file)
 //! # let router = FakeRouter {};
 //! # let scorer = RefCell::new(FakeScorer {});
 //! # let logger = FakeLogger {};
-//! let invoice_payer = InvoicePayer::new(&payer, router, &logger, event_handler, Retry::Attempts(2));
+//! let invoice_payer = InvoicePayer::new(&payer, &router, &logger, event_handler, Retry::Attempts(2));
 //!
 //! let invoice = "...";
 //! if let Ok(invoice) = invoice.parse::<Invoice>() {
@@ -184,12 +184,13 @@ mod sealed {
 /// (C-not exported) generally all users should use the [`InvoicePayer`] type alias.
 pub struct InvoicePayerUsingTime<
        P: Deref,
-       R: Router,
+       R: Deref,
        L: Deref,
        E: sealed::BaseEventHandler,
        T: Time
 > where
        P::Target: Payer,
+       R::Target: Router,
        L::Target: Logger,
 {
        payer: P,
@@ -316,10 +317,11 @@ pub enum PaymentError {
        Sending(PaymentSendFailure),
 }
 
-impl<P: Deref, R: Router, L: Deref, E: sealed::BaseEventHandler, T: Time>
+impl<P: Deref, R: Deref, L: Deref, E: sealed::BaseEventHandler, T: Time>
        InvoicePayerUsingTime<P, R, L, E, T>
 where
        P::Target: Payer,
+       R::Target: Router,
        L::Target: Logger,
 {
        /// Creates an invoice payer that retries failed payment paths.
@@ -630,10 +632,11 @@ fn has_expired(route_params: &RouteParameters) -> bool {
        } else { false }
 }
 
-impl<P: Deref, R: Router, L: Deref, E: sealed::BaseEventHandler, T: Time>
+impl<P: Deref, R: Deref, L: Deref, E: sealed::BaseEventHandler, T: Time>
        InvoicePayerUsingTime<P, R, L, E, T>
 where
        P::Target: Payer,
+       R::Target: Router,
        L::Target: Logger,
 {
        /// Returns a bool indicating whether the processed event should be forwarded to a user-provided
@@ -697,10 +700,11 @@ where
        }
 }
 
-impl<P: Deref, R: Router, L: Deref, E: EventHandler, T: Time>
+impl<P: Deref, R: Deref, L: Deref, E: EventHandler, T: Time>
        EventHandler for InvoicePayerUsingTime<P, R, L, E, T>
 where
        P::Target: Payer,
+       R::Target: Router,
        L::Target: Logger,
 {
        fn handle_event(&self, event: Event) {
@@ -711,10 +715,11 @@ where
        }
 }
 
-impl<P: Deref, R: Router, L: Deref, T: Time, F: Future, H: Fn(Event) -> F>
+impl<P: Deref, R: Deref, L: Deref, T: Time, F: Future, H: Fn(Event) -> F>
        InvoicePayerUsingTime<P, R, L, H, T>
 where
        P::Target: Payer,
+       R::Target: Router,
        L::Target: Logger,
 {
        /// Intercepts events required by the [`InvoicePayer`] and forwards them to the underlying event
@@ -734,7 +739,6 @@ mod tests {
        use crate::utils::create_invoice_from_channelmanager_and_duration_since_epoch;
        use bitcoin_hashes::sha256::Hash as Sha256;
        use lightning::ln::PaymentPreimage;
-       use lightning::ln::channelmanager;
        use lightning::ln::features::{ChannelFeatures, NodeFeatures};
        use lightning::ln::functional_test_utils::*;
        use lightning::ln::msgs::{ChannelMessageHandler, ErrorAction, LightningError};
@@ -747,7 +751,6 @@ mod tests {
        use secp256k1::{SecretKey, PublicKey, Secp256k1};
        use std::cell::RefCell;
        use std::collections::VecDeque;
-       use std::ops::DerefMut;
        use std::time::{SystemTime, Duration};
        use crate::time_utils::tests::SinceEpoch;
        use crate::DEFAULT_EXPIRY_TIME;
@@ -832,7 +835,7 @@ mod tests {
                let router = TestRouter::new(TestScorer::new());
                let logger = TestLogger::new();
                let invoice_payer =
-                       InvoicePayer::new(&payer, router, &logger, event_handler, Retry::Attempts(0));
+                       InvoicePayer::new(&payer, &router, &logger, event_handler, Retry::Attempts(0));
 
                let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
                assert_eq!(*payer.attempts.borrow(), 1);
@@ -860,7 +863,7 @@ mod tests {
                let router = TestRouter::new(TestScorer::new());
                let logger = TestLogger::new();
                let invoice_payer =
-                       InvoicePayer::new(&payer, router, &logger, event_handler, Retry::Attempts(2));
+                       InvoicePayer::new(&payer, &router, &logger, event_handler, Retry::Attempts(2));
 
                let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
                assert_eq!(*payer.attempts.borrow(), 1);
@@ -904,7 +907,7 @@ mod tests {
                let router = TestRouter::new(TestScorer::new());
                let logger = TestLogger::new();
                let invoice_payer =
-                       InvoicePayer::new(&payer, router, &logger, event_handler, Retry::Attempts(2));
+                       InvoicePayer::new(&payer, &router, &logger, event_handler, Retry::Attempts(2));
 
                assert!(invoice_payer.pay_invoice(&invoice).is_ok());
        }
@@ -925,7 +928,7 @@ mod tests {
                let router = TestRouter::new(TestScorer::new());
                let logger = TestLogger::new();
                let invoice_payer =
-                       InvoicePayer::new(&payer, router, &logger, event_handler, Retry::Attempts(2));
+                       InvoicePayer::new(&payer, &router, &logger, event_handler, Retry::Attempts(2));
 
                let payment_id = Some(PaymentId([1; 32]));
                let event = Event::PaymentPathFailed {
@@ -969,7 +972,7 @@ mod tests {
                let router = TestRouter::new(TestScorer::new());
                let logger = TestLogger::new();
                let invoice_payer =
-                       InvoicePayer::new(&payer, router, &logger, event_handler, Retry::Attempts(2));
+                       InvoicePayer::new(&payer, &router, &logger, event_handler, Retry::Attempts(2));
 
                let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
                assert_eq!(*payer.attempts.borrow(), 1);
@@ -1028,7 +1031,7 @@ mod tests {
                type InvoicePayerUsingSinceEpoch <P, R, L, E> = InvoicePayerUsingTime::<P, R, L, E, SinceEpoch>;
 
                let invoice_payer =
-                       InvoicePayerUsingSinceEpoch::new(&payer, router, &logger, event_handler, Retry::Timeout(Duration::from_secs(120)));
+                       InvoicePayerUsingSinceEpoch::new(&payer, &router, &logger, event_handler, Retry::Timeout(Duration::from_secs(120)));
 
                let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
                assert_eq!(*payer.attempts.borrow(), 1);
@@ -1067,7 +1070,7 @@ mod tests {
                let router = TestRouter::new(TestScorer::new());
                let logger = TestLogger::new();
                let invoice_payer =
-                       InvoicePayer::new(&payer, router, &logger, event_handler, Retry::Attempts(2));
+                       InvoicePayer::new(&payer, &router, &logger, event_handler, Retry::Attempts(2));
 
                let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
                assert_eq!(*payer.attempts.borrow(), 1);
@@ -1098,7 +1101,7 @@ mod tests {
                let router = TestRouter::new(TestScorer::new());
                let logger = TestLogger::new();
                let invoice_payer =
-                       InvoicePayer::new(&payer, router, &logger, event_handler, Retry::Attempts(2));
+                       InvoicePayer::new(&payer, &router, &logger, event_handler, Retry::Attempts(2));
 
                let payment_preimage = PaymentPreimage([1; 32]);
                let invoice = expired_invoice(payment_preimage);
@@ -1122,7 +1125,7 @@ mod tests {
                let router = TestRouter::new(TestScorer::new());
                let logger = TestLogger::new();
                let invoice_payer =
-                       InvoicePayer::new(&payer, router,  &logger, event_handler, Retry::Attempts(2));
+                       InvoicePayer::new(&payer, &router,  &logger, event_handler, Retry::Attempts(2));
 
                let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
                assert_eq!(*payer.attempts.borrow(), 1);
@@ -1162,7 +1165,7 @@ mod tests {
                let router = TestRouter::new(TestScorer::new());
                let logger = TestLogger::new();
                let invoice_payer =
-                       InvoicePayer::new(&payer, router, &logger, event_handler, Retry::Attempts(2));
+                       InvoicePayer::new(&payer, &router, &logger, event_handler, Retry::Attempts(2));
 
                let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
                assert_eq!(*payer.attempts.borrow(), 1);
@@ -1195,7 +1198,7 @@ mod tests {
                let router = TestRouter::new(TestScorer::new());
                let logger = TestLogger::new();
                let invoice_payer =
-                       InvoicePayer::new(&payer, router, &logger, event_handler, Retry::Attempts(2));
+                       InvoicePayer::new(&payer, &router, &logger, event_handler, Retry::Attempts(2));
 
                let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
                assert_eq!(*payer.attempts.borrow(), 1);
@@ -1230,7 +1233,7 @@ mod tests {
                let router = TestRouter::new(TestScorer::new());
                let logger = TestLogger::new();
                let invoice_payer =
-                       InvoicePayer::new(&payer, router, &logger, event_handler, Retry::Attempts(0));
+                       InvoicePayer::new(&payer, &router, &logger, event_handler, Retry::Attempts(0));
 
                let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
 
@@ -1268,7 +1271,7 @@ mod tests {
                let router = FailingRouter {};
                let logger = TestLogger::new();
                let invoice_payer =
-                       InvoicePayer::new(&payer, router, &logger, |_: Event| {}, Retry::Attempts(0));
+                       InvoicePayer::new(&payer, &router, &logger, |_: Event| {}, Retry::Attempts(0));
 
                let payment_preimage = PaymentPreimage([1; 32]);
                let invoice = invoice(payment_preimage);
@@ -1291,7 +1294,7 @@ mod tests {
                let router = TestRouter::new(TestScorer::new());
                let logger = TestLogger::new();
                let invoice_payer =
-                       InvoicePayer::new(&payer, router, &logger, |_: Event| {}, Retry::Attempts(0));
+                       InvoicePayer::new(&payer, &router, &logger, |_: Event| {}, Retry::Attempts(0));
 
                match invoice_payer.pay_invoice(&invoice) {
                        Err(PaymentError::Sending(_)) => {},
@@ -1314,7 +1317,7 @@ mod tests {
                let router = TestRouter::new(TestScorer::new());
                let logger = TestLogger::new();
                let invoice_payer =
-                       InvoicePayer::new(&payer, router, &logger, event_handler, Retry::Attempts(0));
+                       InvoicePayer::new(&payer, &router, &logger, event_handler, Retry::Attempts(0));
 
                let payment_id =
                        Some(invoice_payer.pay_zero_value_invoice(&invoice, final_value_msat).unwrap());
@@ -1336,7 +1339,7 @@ mod tests {
                let router = TestRouter::new(TestScorer::new());
                let logger = TestLogger::new();
                let invoice_payer =
-                       InvoicePayer::new(&payer, router,  &logger, event_handler, Retry::Attempts(0));
+                       InvoicePayer::new(&payer, &router,  &logger, event_handler, Retry::Attempts(0));
 
                let payment_preimage = PaymentPreimage([1; 32]);
                let invoice = invoice(payment_preimage);
@@ -1366,7 +1369,7 @@ mod tests {
                let router = TestRouter::new(TestScorer::new());
                let logger = TestLogger::new();
                let invoice_payer =
-                       InvoicePayer::new(&payer, router, &logger, event_handler, Retry::Attempts(2));
+                       InvoicePayer::new(&payer, &router, &logger, event_handler, Retry::Attempts(2));
 
                let payment_id = Some(invoice_payer.pay_pubkey(
                                pubkey, payment_preimage, final_value_msat, final_cltv_expiry_delta
@@ -1421,7 +1424,7 @@ mod tests {
                let router = TestRouter::new(scorer);
                let logger = TestLogger::new();
                let invoice_payer =
-                       InvoicePayer::new(&payer, router, &logger, event_handler, Retry::Attempts(2));
+                       InvoicePayer::new(&payer, &router, &logger, event_handler, Retry::Attempts(2));
 
                let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
                let event = Event::PaymentPathFailed {
@@ -1456,7 +1459,7 @@ mod tests {
                let router = TestRouter::new(scorer);
                let logger = TestLogger::new();
                let invoice_payer =
-                       InvoicePayer::new(&payer, router, &logger, event_handler, Retry::Attempts(2));
+                       InvoicePayer::new(&payer, &router, &logger, event_handler, Retry::Attempts(2));
 
                let payment_id = invoice_payer.pay_invoice(&invoice).unwrap();
                let event = Event::PaymentPathSuccessful {
@@ -1499,7 +1502,7 @@ mod tests {
                let router = TestRouter::new(scorer);
                let logger = TestLogger::new();
                let invoice_payer =
-                       InvoicePayer::new(&payer, router, &logger, event_handler, Retry::Attempts(0));
+                       InvoicePayer::new(&payer, &router, &logger, event_handler, Retry::Attempts(0));
 
                // Make first invoice payment.
                invoice_payer.pay_invoice(&payment_invoice).unwrap();
@@ -1553,7 +1556,7 @@ mod tests {
                let router = TestRouter::new(scorer);
                let logger = TestLogger::new();
                let invoice_payer =
-                       InvoicePayer::new(&payer, router, &logger, event_handler, Retry::Attempts(2));
+                       InvoicePayer::new(&payer, &router, &logger, event_handler, Retry::Attempts(2));
 
                // Fail 1st path, leave 2nd path inflight
                let payment_id = Some(invoice_payer.pay_invoice(&payment_invoice).unwrap());
@@ -2046,24 +2049,24 @@ mod tests {
                let node_chanmgrs = create_node_chanmgrs(2, &node_cfgs, &[None, None, None]);
                let nodes = create_network(2, &node_cfgs, &node_chanmgrs);
 
-               create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 1_000_000, 0, channelmanager::provided_init_features(), channelmanager::provided_init_features());
-               create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 1_000_000, 0, channelmanager::provided_init_features(), channelmanager::provided_init_features());
+               create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 1_000_000, 0);
+               create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 1_000_000, 0);
                let chans = nodes[0].node.list_usable_channels();
                let mut route = Route {
                        paths: vec![
                                vec![RouteHop {
                                        pubkey: nodes[1].node.get_our_node_id(),
-                                       node_features: channelmanager::provided_node_features(),
+                                       node_features: nodes[1].node.node_features(),
                                        short_channel_id: chans[0].short_channel_id.unwrap(),
-                                       channel_features: channelmanager::provided_channel_features(),
+                                       channel_features: nodes[1].node.channel_features(),
                                        fee_msat: 10_000,
                                        cltv_expiry_delta: 100,
                                }],
                                vec![RouteHop {
                                        pubkey: nodes[1].node.get_our_node_id(),
-                                       node_features: channelmanager::provided_node_features(),
+                                       node_features: nodes[1].node.node_features(),
                                        short_channel_id: chans[1].short_channel_id.unwrap(),
-                                       channel_features: channelmanager::provided_channel_features(),
+                                       channel_features: nodes[1].node.channel_features(),
                                        fee_msat: 100_000_001, // Our default max-HTLC-value is 10% of the channel value, which this is one more than
                                        cltv_expiry_delta: 100,
                                }],
@@ -2078,7 +2081,7 @@ mod tests {
                router.expect_find_route(Ok(route.clone()));
 
                let event_handler = |_: Event| { panic!(); };
-               let invoice_payer = InvoicePayer::new(nodes[0].node, router, nodes[0].logger, event_handler, Retry::Attempts(1));
+               let invoice_payer = InvoicePayer::new(nodes[0].node, &router, nodes[0].logger, event_handler, Retry::Attempts(1));
 
                assert!(invoice_payer.pay_invoice(&create_invoice_from_channelmanager_and_duration_since_epoch(
                        &nodes[1].node, nodes[1].keys_manager, nodes[1].logger, Currency::Bitcoin,
@@ -2097,16 +2100,16 @@ mod tests {
                let node_chanmgrs = create_node_chanmgrs(2, &node_cfgs, &[None, None, None]);
                let nodes = create_network(2, &node_cfgs, &node_chanmgrs);
 
-               create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 1_000_000, 0, channelmanager::provided_init_features(), channelmanager::provided_init_features());
-               create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 1_000_000, 0, channelmanager::provided_init_features(), channelmanager::provided_init_features());
+               create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 1_000_000, 0);
+               create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 1_000_000, 0);
                let chans = nodes[0].node.list_usable_channels();
                let mut route = Route {
                        paths: vec![
                                vec![RouteHop {
                                        pubkey: nodes[1].node.get_our_node_id(),
-                                       node_features: channelmanager::provided_node_features(),
+                                       node_features: nodes[1].node.node_features(),
                                        short_channel_id: chans[0].short_channel_id.unwrap(),
-                                       channel_features: channelmanager::provided_channel_features(),
+                                       channel_features: nodes[1].node.channel_features(),
                                        fee_msat: 100_000_001, // Our default max-HTLC-value is 10% of the channel value, which this is one more than
                                        cltv_expiry_delta: 100,
                                }],
@@ -2123,7 +2126,7 @@ mod tests {
                router.expect_find_route(Ok(route.clone()));
 
                let event_handler = |_: Event| { panic!(); };
-               let invoice_payer = InvoicePayer::new(nodes[0].node, router, nodes[0].logger, event_handler, Retry::Attempts(1));
+               let invoice_payer = InvoicePayer::new(nodes[0].node, &router, nodes[0].logger, event_handler, Retry::Attempts(1));
 
                assert!(invoice_payer.pay_invoice(&create_invoice_from_channelmanager_and_duration_since_epoch(
                        &nodes[1].node, nodes[1].keys_manager, nodes[1].logger, Currency::Bitcoin,
@@ -2155,38 +2158,38 @@ mod tests {
                let node_chanmgrs = create_node_chanmgrs(3, &node_cfgs, &[None, None, None]);
                let nodes = create_network(3, &node_cfgs, &node_chanmgrs);
 
-               let chan_1_scid = create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 10_000_000, 0, channelmanager::provided_init_features(), channelmanager::provided_init_features()).0.contents.short_channel_id;
-               let chan_2_scid = create_announced_chan_between_nodes_with_value(&nodes, 1, 2, 10_000_000, 0, channelmanager::provided_init_features(), channelmanager::provided_init_features()).0.contents.short_channel_id;
+               let chan_1_scid = create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 10_000_000, 0).0.contents.short_channel_id;
+               let chan_2_scid = create_announced_chan_between_nodes_with_value(&nodes, 1, 2, 10_000_000, 0).0.contents.short_channel_id;
 
                let mut route = Route {
                        paths: vec![
                                vec![RouteHop {
                                        pubkey: nodes[1].node.get_our_node_id(),
-                                       node_features: channelmanager::provided_node_features(),
+                                       node_features: nodes[1].node.node_features(),
                                        short_channel_id: chan_1_scid,
-                                       channel_features: channelmanager::provided_channel_features(),
+                                       channel_features: nodes[1].node.channel_features(),
                                        fee_msat: 0,
                                        cltv_expiry_delta: 100,
                                }, RouteHop {
                                        pubkey: nodes[2].node.get_our_node_id(),
-                                       node_features: channelmanager::provided_node_features(),
+                                       node_features: nodes[2].node.node_features(),
                                        short_channel_id: chan_2_scid,
-                                       channel_features: channelmanager::provided_channel_features(),
+                                       channel_features: nodes[2].node.channel_features(),
                                        fee_msat: 100_000_000,
                                        cltv_expiry_delta: 100,
                                }],
                                vec![RouteHop {
                                        pubkey: nodes[1].node.get_our_node_id(),
-                                       node_features: channelmanager::provided_node_features(),
+                                       node_features: nodes[1].node.node_features(),
                                        short_channel_id: chan_1_scid,
-                                       channel_features: channelmanager::provided_channel_features(),
+                                       channel_features: nodes[2].node.channel_features(),
                                        fee_msat: 0,
                                        cltv_expiry_delta: 100,
                                }, RouteHop {
                                        pubkey: nodes[2].node.get_our_node_id(),
-                                       node_features: channelmanager::provided_node_features(),
+                                       node_features: nodes[2].node.node_features(),
                                        short_channel_id: chan_2_scid,
-                                       channel_features: channelmanager::provided_channel_features(),
+                                       channel_features: nodes[2].node.channel_features(),
                                        fee_msat: 100_000_000,
                                        cltv_expiry_delta: 100,
                                }]
@@ -2204,7 +2207,7 @@ mod tests {
                        let event_checker = expected_events.borrow_mut().pop_front().unwrap();
                        event_checker(event);
                };
-               let invoice_payer = InvoicePayer::new(nodes[0].node, router, nodes[0].logger, event_handler, Retry::Attempts(1));
+               let invoice_payer = InvoicePayer::new(nodes[0].node, &router, nodes[0].logger, event_handler, Retry::Attempts(1));
 
                assert!(invoice_payer.pay_invoice(&create_invoice_from_channelmanager_and_duration_since_epoch(
                        &nodes[1].node, nodes[1].keys_manager, nodes[1].logger, Currency::Bitcoin,