1 // This file is Copyright its original authors, visible in version control
4 // This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
5 // or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
6 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
7 // You may not use this file except in accordance with one or both of these
10 //! Convenient utilities for paying Lightning invoices and sending spontaneous payments.
12 use crate::Bolt11Invoice;
14 use bitcoin_hashes::Hash;
17 use lightning::chain::chaininterface::{BroadcasterInterface, FeeEstimator};
18 use lightning::sign::{NodeSigner, SignerProvider, EntropySource};
19 use lightning::ln::PaymentHash;
20 use lightning::ln::channelmanager::{ChannelManager, PaymentId, Retry, RetryableSendFailure, RecipientOnionFields};
21 use lightning::routing::router::{PaymentParameters, RouteParameters, Router};
22 use lightning::util::logger::Logger;
26 use core::time::Duration;
28 /// Pays the given [`Bolt11Invoice`], retrying if needed based on [`Retry`].
30 /// [`Bolt11Invoice::payment_hash`] is used as the [`PaymentId`], which ensures idempotency as long
31 /// as the payment is still pending. If the payment succeeds, you must ensure that a second payment
32 /// with the same [`PaymentHash`] is never sent.
34 /// If you wish to use a different payment idempotency token, see [`pay_invoice_with_id`].
35 pub fn pay_invoice<M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref>(
36 invoice: &Bolt11Invoice, retry_strategy: Retry,
37 channelmanager: &ChannelManager<M, T, ES, NS, SP, F, R, L>
38 ) -> Result<PaymentId, PaymentError>
40 M::Target: chain::Watch<<SP::Target as SignerProvider>::Signer>,
41 T::Target: BroadcasterInterface,
42 ES::Target: EntropySource,
43 NS::Target: NodeSigner,
44 SP::Target: SignerProvider,
45 F::Target: FeeEstimator,
49 let payment_id = PaymentId(invoice.payment_hash().into_inner());
50 pay_invoice_with_id(invoice, payment_id, retry_strategy, channelmanager)
54 /// Pays the given [`Bolt11Invoice`] with a custom idempotency key, retrying if needed based on
57 /// Note that idempotency is only guaranteed as long as the payment is still pending. Once the
58 /// payment completes or fails, no idempotency guarantees are made.
60 /// You should ensure that the [`Bolt11Invoice::payment_hash`] is unique and the same
61 /// [`PaymentHash`] has never been paid before.
63 /// See [`pay_invoice`] for a variant which uses the [`PaymentHash`] for the idempotency token.
64 pub fn pay_invoice_with_id<M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref>(
65 invoice: &Bolt11Invoice, payment_id: PaymentId, retry_strategy: Retry,
66 channelmanager: &ChannelManager<M, T, ES, NS, SP, F, R, L>
67 ) -> Result<(), PaymentError>
69 M::Target: chain::Watch<<SP::Target as SignerProvider>::Signer>,
70 T::Target: BroadcasterInterface,
71 ES::Target: EntropySource,
72 NS::Target: NodeSigner,
73 SP::Target: SignerProvider,
74 F::Target: FeeEstimator,
78 let amt_msat = invoice.amount_milli_satoshis().ok_or(PaymentError::Invoice("amount missing"))?;
79 pay_invoice_using_amount(invoice, amt_msat, payment_id, retry_strategy, channelmanager)
82 /// Pays the given zero-value [`Bolt11Invoice`] using the given amount, retrying if needed based on
85 /// [`Bolt11Invoice::payment_hash`] is used as the [`PaymentId`], which ensures idempotency as long
86 /// as the payment is still pending. If the payment succeeds, you must ensure that a second payment
87 /// with the same [`PaymentHash`] is never sent.
89 /// If you wish to use a different payment idempotency token, see
90 /// [`pay_zero_value_invoice_with_id`].
91 pub fn pay_zero_value_invoice<M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref>(
92 invoice: &Bolt11Invoice, amount_msats: u64, retry_strategy: Retry,
93 channelmanager: &ChannelManager<M, T, ES, NS, SP, F, R, L>
94 ) -> Result<PaymentId, PaymentError>
96 M::Target: chain::Watch<<SP::Target as SignerProvider>::Signer>,
97 T::Target: BroadcasterInterface,
98 ES::Target: EntropySource,
99 NS::Target: NodeSigner,
100 SP::Target: SignerProvider,
101 F::Target: FeeEstimator,
105 let payment_id = PaymentId(invoice.payment_hash().into_inner());
106 pay_zero_value_invoice_with_id(invoice, amount_msats, payment_id, retry_strategy,
108 .map(|()| payment_id)
111 /// Pays the given zero-value [`Bolt11Invoice`] using the given amount and custom idempotency key,
112 /// retrying if needed based on [`Retry`].
114 /// Note that idempotency is only guaranteed as long as the payment is still pending. Once the
115 /// payment completes or fails, no idempotency guarantees are made.
117 /// You should ensure that the [`Bolt11Invoice::payment_hash`] is unique and the same
118 /// [`PaymentHash`] has never been paid before.
120 /// See [`pay_zero_value_invoice`] for a variant which uses the [`PaymentHash`] for the
121 /// idempotency token.
122 pub fn pay_zero_value_invoice_with_id<M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref>(
123 invoice: &Bolt11Invoice, amount_msats: u64, payment_id: PaymentId, retry_strategy: Retry,
124 channelmanager: &ChannelManager<M, T, ES, NS, SP, F, R, L>
125 ) -> Result<(), PaymentError>
127 M::Target: chain::Watch<<SP::Target as SignerProvider>::Signer>,
128 T::Target: BroadcasterInterface,
129 ES::Target: EntropySource,
130 NS::Target: NodeSigner,
131 SP::Target: SignerProvider,
132 F::Target: FeeEstimator,
136 if invoice.amount_milli_satoshis().is_some() {
137 Err(PaymentError::Invoice("amount unexpected"))
139 pay_invoice_using_amount(invoice, amount_msats, payment_id, retry_strategy,
144 fn pay_invoice_using_amount<P: Deref>(
145 invoice: &Bolt11Invoice, amount_msats: u64, payment_id: PaymentId, retry_strategy: Retry,
147 ) -> Result<(), PaymentError> where P::Target: Payer {
148 let payment_hash = PaymentHash((*invoice.payment_hash()).into_inner());
149 let recipient_onion = RecipientOnionFields {
150 payment_secret: Some(*invoice.payment_secret()),
151 payment_metadata: invoice.payment_metadata().map(|v| v.clone()),
153 let mut payment_params = PaymentParameters::from_node_id(invoice.recover_payee_pub_key(),
154 invoice.min_final_cltv_expiry_delta() as u32)
155 .with_expiry_time(expiry_time_from_unix_epoch(invoice).as_secs())
156 .with_route_hints(invoice.route_hints()).unwrap();
157 if let Some(features) = invoice.features() {
158 payment_params = payment_params.with_bolt11_features(features.clone()).unwrap();
160 let route_params = RouteParameters {
162 final_value_msat: amount_msats,
165 payer.send_payment(payment_hash, recipient_onion, payment_id, route_params, retry_strategy)
168 fn expiry_time_from_unix_epoch(invoice: &Bolt11Invoice) -> Duration {
169 invoice.signed_invoice.raw_invoice.data.timestamp.0 + invoice.expiry_time()
172 /// An error that may occur when making a payment.
173 #[derive(Clone, Debug, PartialEq, Eq)]
174 pub enum PaymentError {
175 /// An error resulting from the provided [`Bolt11Invoice`] or payment hash.
176 Invoice(&'static str),
177 /// An error occurring when sending a payment.
178 Sending(RetryableSendFailure),
181 /// A trait defining behavior of a [`Bolt11Invoice`] payer.
183 /// Useful for unit testing internal methods.
185 /// Sends a payment over the Lightning Network using the given [`Route`].
187 /// [`Route`]: lightning::routing::router::Route
189 &self, payment_hash: PaymentHash, recipient_onion: RecipientOnionFields,
190 payment_id: PaymentId, route_params: RouteParameters, retry_strategy: Retry
191 ) -> Result<(), PaymentError>;
194 impl<M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref> Payer for ChannelManager<M, T, ES, NS, SP, F, R, L>
196 M::Target: chain::Watch<<SP::Target as SignerProvider>::Signer>,
197 T::Target: BroadcasterInterface,
198 ES::Target: EntropySource,
199 NS::Target: NodeSigner,
200 SP::Target: SignerProvider,
201 F::Target: FeeEstimator,
206 &self, payment_hash: PaymentHash, recipient_onion: RecipientOnionFields,
207 payment_id: PaymentId, route_params: RouteParameters, retry_strategy: Retry
208 ) -> Result<(), PaymentError> {
209 self.send_payment(payment_hash, recipient_onion, payment_id, route_params, retry_strategy)
210 .map_err(PaymentError::Sending)
217 use crate::{InvoiceBuilder, Currency};
218 use bitcoin_hashes::sha256::Hash as Sha256;
219 use lightning::events::Event;
220 use lightning::ln::msgs::ChannelMessageHandler;
221 use lightning::ln::{PaymentPreimage, PaymentSecret};
222 use lightning::ln::functional_test_utils::*;
223 use secp256k1::{SecretKey, Secp256k1};
224 use std::collections::VecDeque;
225 use std::time::{SystemTime, Duration};
228 expectations: core::cell::RefCell<VecDeque<Amount>>,
234 expectations: core::cell::RefCell::new(VecDeque::new()),
238 fn expect_send(self, value_msat: Amount) -> Self {
239 self.expectations.borrow_mut().push_back(value_msat);
243 fn check_value_msats(&self, actual_value_msats: Amount) {
244 let expected_value_msats = self.expectations.borrow_mut().pop_front();
245 if let Some(expected_value_msats) = expected_value_msats {
246 assert_eq!(actual_value_msats, expected_value_msats);
248 panic!("Unexpected amount: {:?}", actual_value_msats);
253 #[derive(Clone, Debug, PartialEq, Eq)]
254 struct Amount(u64); // msat
256 impl Payer for TestPayer {
258 &self, _payment_hash: PaymentHash, _recipient_onion: RecipientOnionFields,
259 _payment_id: PaymentId, route_params: RouteParameters, _retry_strategy: Retry
260 ) -> Result<(), PaymentError> {
261 self.check_value_msats(Amount(route_params.final_value_msat));
266 impl Drop for TestPayer {
268 if std::thread::panicking() {
272 if !self.expectations.borrow().is_empty() {
273 panic!("Unsatisfied payment expectations: {:?}", self.expectations.borrow());
278 fn duration_since_epoch() -> Duration {
279 #[cfg(feature = "std")]
280 let duration_since_epoch =
281 SystemTime::now().duration_since(SystemTime::UNIX_EPOCH).unwrap();
282 #[cfg(not(feature = "std"))]
283 let duration_since_epoch = Duration::from_secs(1234567);
287 fn invoice(payment_preimage: PaymentPreimage) -> Bolt11Invoice {
288 let payment_hash = Sha256::hash(&payment_preimage.0);
289 let private_key = SecretKey::from_slice(&[42; 32]).unwrap();
291 InvoiceBuilder::new(Currency::Bitcoin)
292 .description("test".into())
293 .payment_hash(payment_hash)
294 .payment_secret(PaymentSecret([0; 32]))
295 .duration_since_epoch(duration_since_epoch())
296 .min_final_cltv_expiry_delta(144)
297 .amount_milli_satoshis(128)
298 .build_signed(|hash| {
299 Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)
304 fn zero_value_invoice(payment_preimage: PaymentPreimage) -> Bolt11Invoice {
305 let payment_hash = Sha256::hash(&payment_preimage.0);
306 let private_key = SecretKey::from_slice(&[42; 32]).unwrap();
308 InvoiceBuilder::new(Currency::Bitcoin)
309 .description("test".into())
310 .payment_hash(payment_hash)
311 .payment_secret(PaymentSecret([0; 32]))
312 .duration_since_epoch(duration_since_epoch())
313 .min_final_cltv_expiry_delta(144)
314 .build_signed(|hash| {
315 Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)
322 let payment_id = PaymentId([42; 32]);
323 let payment_preimage = PaymentPreimage([1; 32]);
324 let invoice = invoice(payment_preimage);
325 let final_value_msat = invoice.amount_milli_satoshis().unwrap();
327 let payer = TestPayer::new().expect_send(Amount(final_value_msat));
328 pay_invoice_using_amount(&invoice, final_value_msat, payment_id, Retry::Attempts(0), &payer).unwrap();
332 fn pays_zero_value_invoice() {
333 let payment_id = PaymentId([42; 32]);
334 let payment_preimage = PaymentPreimage([1; 32]);
335 let invoice = zero_value_invoice(payment_preimage);
336 let amt_msat = 10_000;
338 let payer = TestPayer::new().expect_send(Amount(amt_msat));
339 pay_invoice_using_amount(&invoice, amt_msat, payment_id, Retry::Attempts(0), &payer).unwrap();
343 fn fails_paying_zero_value_invoice_with_amount() {
344 let chanmon_cfgs = create_chanmon_cfgs(1);
345 let node_cfgs = create_node_cfgs(1, &chanmon_cfgs);
346 let node_chanmgrs = create_node_chanmgrs(1, &node_cfgs, &[None]);
347 let nodes = create_network(1, &node_cfgs, &node_chanmgrs);
349 let payment_preimage = PaymentPreimage([1; 32]);
350 let invoice = invoice(payment_preimage);
351 let amt_msat = 10_000;
353 match pay_zero_value_invoice(&invoice, amt_msat, Retry::Attempts(0), nodes[0].node) {
354 Err(PaymentError::Invoice("amount unexpected")) => {},
360 #[cfg(feature = "std")]
361 fn payment_metadata_end_to_end() {
362 // Test that a payment metadata read from an invoice passed to `pay_invoice` makes it all
363 // the way out through the `PaymentClaimable` event.
364 let chanmon_cfgs = create_chanmon_cfgs(2);
365 let node_cfgs = create_node_cfgs(2, &chanmon_cfgs);
366 let node_chanmgrs = create_node_chanmgrs(2, &node_cfgs, &[None, None]);
367 let nodes = create_network(2, &node_cfgs, &node_chanmgrs);
368 create_announced_chan_between_nodes(&nodes, 0, 1);
370 let payment_metadata = vec![42, 43, 44, 45, 46, 47, 48, 49, 42];
372 let (payment_hash, payment_secret) =
373 nodes[1].node.create_inbound_payment(None, 7200, None).unwrap();
375 let invoice = InvoiceBuilder::new(Currency::Bitcoin)
376 .description("test".into())
377 .payment_hash(Sha256::from_slice(&payment_hash.0).unwrap())
378 .payment_secret(payment_secret)
380 .min_final_cltv_expiry_delta(144)
381 .amount_milli_satoshis(50_000)
382 .payment_metadata(payment_metadata.clone())
383 .build_signed(|hash| {
384 Secp256k1::new().sign_ecdsa_recoverable(hash,
385 &nodes[1].keys_manager.backing.get_node_secret_key())
389 pay_invoice(&invoice, Retry::Attempts(0), nodes[0].node).unwrap();
390 check_added_monitors(&nodes[0], 1);
391 let send_event = SendEvent::from_node(&nodes[0]);
392 nodes[1].node.handle_update_add_htlc(&nodes[0].node.get_our_node_id(), &send_event.msgs[0]);
393 commitment_signed_dance!(nodes[1], nodes[0], &send_event.commitment_msg, false);
395 expect_pending_htlcs_forwardable!(nodes[1]);
397 let mut events = nodes[1].node.get_and_clear_pending_events();
398 assert_eq!(events.len(), 1);
399 match events.pop().unwrap() {
400 Event::PaymentClaimable { onion_fields, .. } => {
401 assert_eq!(Some(payment_metadata), onion_fields.unwrap().payment_metadata);
403 _ => panic!("Unexpected event")