1 // This file is Copyright its original authors, visible in version control
2 // history and in the source files from which this was generated.
4 // This file is licensed under the license available in the LICENSE or LICENSE.md
5 // file in the root of this repository or, if no such file exists, the same
6 // license as that which applies to the original source files from which this
7 // source was automatically generated.
9 //! Convenient utilities to create an invoice.
11 use alloc::str::FromStr;
12 use core::ffi::c_void;
13 use core::convert::Infallible;
14 use bitcoin::hashes::Hash;
15 use crate::c_types::*;
16 #[cfg(feature="no-std")]
17 use alloc::{vec::Vec, boxed::Box};
19 /// Utility to create an invoice that can be paid to one of multiple nodes, or a \"phantom invoice.\"
20 /// See [`PhantomKeysManager`] for more information on phantom node payments.
22 /// `phantom_route_hints` parameter:
23 /// * Contains channel info for all nodes participating in the phantom invoice
24 /// * Entries are retrieved from a call to [`ChannelManager::get_phantom_route_hints`] on each
25 /// participating node
26 /// * It is fine to cache `phantom_route_hints` and reuse it across invoices, as long as the data is
27 /// updated when a channel becomes disabled or closes
28 /// * Note that if too many channels are included in [`PhantomRouteHints::channels`], the invoice
29 /// may be too long for QR code scanning. To fix this, `PhantomRouteHints::channels` may be pared
32 /// `payment_hash` can be specified if you have a specific need for a custom payment hash (see the difference
33 /// between [`ChannelManager::create_inbound_payment`] and [`ChannelManager::create_inbound_payment_for_hash`]).
34 /// If `None` is provided for `payment_hash`, then one will be created.
36 /// `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for
37 /// in excess of the current time.
39 /// Note that the provided `keys_manager`'s `KeysInterface` implementation must support phantom
40 /// invoices in its `sign_invoice` implementation ([`PhantomKeysManager`] satisfies this
43 /// [`PhantomKeysManager`]: lightning::chain::keysinterface::PhantomKeysManager
44 /// [`ChannelManager::get_phantom_route_hints`]: lightning::ln::channelmanager::ChannelManager::get_phantom_route_hints
45 /// [`ChannelManager::create_inbound_payment`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment
46 /// [`ChannelManager::create_inbound_payment_for_hash`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment_for_hash
47 /// [`PhantomRouteHints::channels`]: lightning::ln::channelmanager::PhantomRouteHints::channels
49 /// Note that payment_hash (or a relevant inner pointer) may be NULL or all-0s to represent None
51 pub extern "C" fn create_phantom_invoice(mut amt_msat: crate::c_types::derived::COption_u64Z, mut payment_hash: crate::c_types::ThirtyTwoBytes, mut description: crate::c_types::Str, mut invoice_expiry_delta_secs: u32, mut phantom_route_hints: crate::c_types::derived::CVec_PhantomRouteHintsZ, mut keys_manager: crate::lightning::chain::keysinterface::KeysInterface, mut logger: crate::lightning::util::logger::Logger, mut network: crate::lightning_invoice::Currency) -> crate::c_types::derived::CResult_InvoiceSignOrCreationErrorZ {
52 let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
53 let mut local_payment_hash = if payment_hash.data == [0; 32] { None } else { Some( { ::lightning::ln::PaymentHash(payment_hash.data) }) };
54 let mut local_phantom_route_hints = Vec::new(); for mut item in phantom_route_hints.into_rust().drain(..) { local_phantom_route_hints.push( { *unsafe { Box::from_raw(item.take_inner()) } }); };
55 let mut ret = lightning_invoice::utils::create_phantom_invoice::<crate::lightning::chain::keysinterface::KeysInterface, crate::lightning::util::logger::Logger>(local_amt_msat, local_payment_hash, description.into_string(), invoice_expiry_delta_secs, local_phantom_route_hints, keys_manager, logger, network.into_native());
56 let mut local_ret = match ret { Ok(mut o) => crate::c_types::CResultTempl::ok( { crate::lightning_invoice::Invoice { inner: ObjOps::heap_alloc(o), is_owned: true } }).into(), Err(mut e) => crate::c_types::CResultTempl::err( { crate::lightning_invoice::SignOrCreationError::native_into(e) }).into() };
60 /// Utility to create an invoice that can be paid to one of multiple nodes, or a \"phantom invoice.\"
61 /// See [`PhantomKeysManager`] for more information on phantom node payments.
63 /// `phantom_route_hints` parameter:
64 /// * Contains channel info for all nodes participating in the phantom invoice
65 /// * Entries are retrieved from a call to [`ChannelManager::get_phantom_route_hints`] on each
66 /// participating node
67 /// * It is fine to cache `phantom_route_hints` and reuse it across invoices, as long as the data is
68 /// updated when a channel becomes disabled or closes
69 /// * Note that if too many channels are included in [`PhantomRouteHints::channels`], the invoice
70 /// may be too long for QR code scanning. To fix this, `PhantomRouteHints::channels` may be pared
73 /// `description_hash` is a SHA-256 hash of the description text
75 /// `payment_hash` can be specified if you have a specific need for a custom payment hash (see the difference
76 /// between [`ChannelManager::create_inbound_payment`] and [`ChannelManager::create_inbound_payment_for_hash`]).
77 /// If `None` is provided for `payment_hash`, then one will be created.
79 /// `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for
80 /// in excess of the current time.
82 /// Note that the provided `keys_manager`'s `KeysInterface` implementation must support phantom
83 /// invoices in its `sign_invoice` implementation ([`PhantomKeysManager`] satisfies this
86 /// [`PhantomKeysManager`]: lightning::chain::keysinterface::PhantomKeysManager
87 /// [`ChannelManager::get_phantom_route_hints`]: lightning::ln::channelmanager::ChannelManager::get_phantom_route_hints
88 /// [`ChannelManager::create_inbound_payment`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment
89 /// [`ChannelManager::create_inbound_payment_for_hash`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment_for_hash
90 /// [`PhantomRouteHints::channels`]: lightning::ln::channelmanager::PhantomRouteHints::channels
92 /// Note that payment_hash (or a relevant inner pointer) may be NULL or all-0s to represent None
94 pub extern "C" fn create_phantom_invoice_with_description_hash(mut amt_msat: crate::c_types::derived::COption_u64Z, mut payment_hash: crate::c_types::ThirtyTwoBytes, mut invoice_expiry_delta_secs: u32, mut description_hash: crate::lightning_invoice::Sha256, mut phantom_route_hints: crate::c_types::derived::CVec_PhantomRouteHintsZ, mut keys_manager: crate::lightning::chain::keysinterface::KeysInterface, mut logger: crate::lightning::util::logger::Logger, mut network: crate::lightning_invoice::Currency) -> crate::c_types::derived::CResult_InvoiceSignOrCreationErrorZ {
95 let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
96 let mut local_payment_hash = if payment_hash.data == [0; 32] { None } else { Some( { ::lightning::ln::PaymentHash(payment_hash.data) }) };
97 let mut local_phantom_route_hints = Vec::new(); for mut item in phantom_route_hints.into_rust().drain(..) { local_phantom_route_hints.push( { *unsafe { Box::from_raw(item.take_inner()) } }); };
98 let mut ret = lightning_invoice::utils::create_phantom_invoice_with_description_hash::<crate::lightning::chain::keysinterface::KeysInterface, crate::lightning::util::logger::Logger>(local_amt_msat, local_payment_hash, invoice_expiry_delta_secs, *unsafe { Box::from_raw(description_hash.take_inner()) }, local_phantom_route_hints, keys_manager, logger, network.into_native());
99 let mut local_ret = match ret { Ok(mut o) => crate::c_types::CResultTempl::ok( { crate::lightning_invoice::Invoice { inner: ObjOps::heap_alloc(o), is_owned: true } }).into(), Err(mut e) => crate::c_types::CResultTempl::err( { crate::lightning_invoice::SignOrCreationError::native_into(e) }).into() };
103 /// Utility to construct an invoice. Generally, unless you want to do something like a custom
104 /// cltv_expiry, this is what you should be using to create an invoice. The reason being, this
105 /// method stores the invoice's payment secret and preimage in `ChannelManager`, so (a) the user
106 /// doesn't have to store preimage/payment secret information and (b) `ChannelManager` can verify
107 /// that the payment secret is valid when the invoice is paid.
109 /// `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for
110 /// in excess of the current time.
112 pub extern "C" fn create_invoice_from_channelmanager(channelmanager: &crate::lightning::ln::channelmanager::ChannelManager, mut keys_manager: crate::lightning::chain::keysinterface::KeysInterface, mut logger: crate::lightning::util::logger::Logger, mut network: crate::lightning_invoice::Currency, mut amt_msat: crate::c_types::derived::COption_u64Z, mut description: crate::c_types::Str, mut invoice_expiry_delta_secs: u32) -> crate::c_types::derived::CResult_InvoiceSignOrCreationErrorZ {
113 let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
114 let mut ret = lightning_invoice::utils::create_invoice_from_channelmanager::<crate::lightning::chain::Watch, crate::lightning::chain::chaininterface::BroadcasterInterface, crate::lightning::chain::keysinterface::KeysInterface, crate::lightning::chain::chaininterface::FeeEstimator, crate::lightning::util::logger::Logger>(channelmanager.get_native_ref(), keys_manager, logger, network.into_native(), local_amt_msat, description.into_string(), invoice_expiry_delta_secs);
115 let mut local_ret = match ret { Ok(mut o) => crate::c_types::CResultTempl::ok( { crate::lightning_invoice::Invoice { inner: ObjOps::heap_alloc(o), is_owned: true } }).into(), Err(mut e) => crate::c_types::CResultTempl::err( { crate::lightning_invoice::SignOrCreationError::native_into(e) }).into() };
119 /// Utility to construct an invoice. Generally, unless you want to do something like a custom
120 /// cltv_expiry, this is what you should be using to create an invoice. The reason being, this
121 /// method stores the invoice's payment secret and preimage in `ChannelManager`, so (a) the user
122 /// doesn't have to store preimage/payment secret information and (b) `ChannelManager` can verify
123 /// that the payment secret is valid when the invoice is paid.
124 /// Use this variant if you want to pass the `description_hash` to the invoice.
126 /// `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for
127 /// in excess of the current time.
129 pub extern "C" fn create_invoice_from_channelmanager_with_description_hash(channelmanager: &crate::lightning::ln::channelmanager::ChannelManager, mut keys_manager: crate::lightning::chain::keysinterface::KeysInterface, mut logger: crate::lightning::util::logger::Logger, mut network: crate::lightning_invoice::Currency, mut amt_msat: crate::c_types::derived::COption_u64Z, mut description_hash: crate::lightning_invoice::Sha256, mut invoice_expiry_delta_secs: u32) -> crate::c_types::derived::CResult_InvoiceSignOrCreationErrorZ {
130 let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
131 let mut ret = lightning_invoice::utils::create_invoice_from_channelmanager_with_description_hash::<crate::lightning::chain::Watch, crate::lightning::chain::chaininterface::BroadcasterInterface, crate::lightning::chain::keysinterface::KeysInterface, crate::lightning::chain::chaininterface::FeeEstimator, crate::lightning::util::logger::Logger>(channelmanager.get_native_ref(), keys_manager, logger, network.into_native(), local_amt_msat, *unsafe { Box::from_raw(description_hash.take_inner()) }, invoice_expiry_delta_secs);
132 let mut local_ret = match ret { Ok(mut o) => crate::c_types::CResultTempl::ok( { crate::lightning_invoice::Invoice { inner: ObjOps::heap_alloc(o), is_owned: true } }).into(), Err(mut e) => crate::c_types::CResultTempl::err( { crate::lightning_invoice::SignOrCreationError::native_into(e) }).into() };
136 /// See [`create_invoice_from_channelmanager_with_description_hash`]
137 /// This version can be used in a `no_std` environment, where [`std::time::SystemTime`] is not
138 /// available and the current time is supplied by the caller.
140 pub extern "C" fn create_invoice_from_channelmanager_with_description_hash_and_duration_since_epoch(channelmanager: &crate::lightning::ln::channelmanager::ChannelManager, mut keys_manager: crate::lightning::chain::keysinterface::KeysInterface, mut logger: crate::lightning::util::logger::Logger, mut network: crate::lightning_invoice::Currency, mut amt_msat: crate::c_types::derived::COption_u64Z, mut description_hash: crate::lightning_invoice::Sha256, mut duration_since_epoch: u64, mut invoice_expiry_delta_secs: u32) -> crate::c_types::derived::CResult_InvoiceSignOrCreationErrorZ {
141 let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
142 let mut ret = lightning_invoice::utils::create_invoice_from_channelmanager_with_description_hash_and_duration_since_epoch::<crate::lightning::chain::Watch, crate::lightning::chain::chaininterface::BroadcasterInterface, crate::lightning::chain::keysinterface::KeysInterface, crate::lightning::chain::chaininterface::FeeEstimator, crate::lightning::util::logger::Logger>(channelmanager.get_native_ref(), keys_manager, logger, network.into_native(), local_amt_msat, *unsafe { Box::from_raw(description_hash.take_inner()) }, core::time::Duration::from_secs(duration_since_epoch), invoice_expiry_delta_secs);
143 let mut local_ret = match ret { Ok(mut o) => crate::c_types::CResultTempl::ok( { crate::lightning_invoice::Invoice { inner: ObjOps::heap_alloc(o), is_owned: true } }).into(), Err(mut e) => crate::c_types::CResultTempl::err( { crate::lightning_invoice::SignOrCreationError::native_into(e) }).into() };
147 /// See [`create_invoice_from_channelmanager`]
148 /// This version can be used in a `no_std` environment, where [`std::time::SystemTime`] is not
149 /// available and the current time is supplied by the caller.
151 pub extern "C" fn create_invoice_from_channelmanager_and_duration_since_epoch(channelmanager: &crate::lightning::ln::channelmanager::ChannelManager, mut keys_manager: crate::lightning::chain::keysinterface::KeysInterface, mut logger: crate::lightning::util::logger::Logger, mut network: crate::lightning_invoice::Currency, mut amt_msat: crate::c_types::derived::COption_u64Z, mut description: crate::c_types::Str, mut duration_since_epoch: u64, mut invoice_expiry_delta_secs: u32) -> crate::c_types::derived::CResult_InvoiceSignOrCreationErrorZ {
152 let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
153 let mut ret = lightning_invoice::utils::create_invoice_from_channelmanager_and_duration_since_epoch::<crate::lightning::chain::Watch, crate::lightning::chain::chaininterface::BroadcasterInterface, crate::lightning::chain::keysinterface::KeysInterface, crate::lightning::chain::chaininterface::FeeEstimator, crate::lightning::util::logger::Logger>(channelmanager.get_native_ref(), keys_manager, logger, network.into_native(), local_amt_msat, description.into_string(), core::time::Duration::from_secs(duration_since_epoch), invoice_expiry_delta_secs);
154 let mut local_ret = match ret { Ok(mut o) => crate::c_types::CResultTempl::ok( { crate::lightning_invoice::Invoice { inner: ObjOps::heap_alloc(o), is_owned: true } }).into(), Err(mut e) => crate::c_types::CResultTempl::err( { crate::lightning_invoice::SignOrCreationError::native_into(e) }).into() };
158 /// See [`create_invoice_from_channelmanager_and_duration_since_epoch`]
159 /// This version allows for providing a custom [`PaymentHash`] for the invoice.
160 /// This may be useful if you're building an on-chain swap or involving another protocol where
161 /// the payment hash is also involved outside the scope of lightning.
163 pub extern "C" fn create_invoice_from_channelmanager_and_duration_since_epoch_with_payment_hash(channelmanager: &crate::lightning::ln::channelmanager::ChannelManager, mut keys_manager: crate::lightning::chain::keysinterface::KeysInterface, mut logger: crate::lightning::util::logger::Logger, mut network: crate::lightning_invoice::Currency, mut amt_msat: crate::c_types::derived::COption_u64Z, mut description: crate::c_types::Str, mut duration_since_epoch: u64, mut invoice_expiry_delta_secs: u32, mut payment_hash: crate::c_types::ThirtyTwoBytes) -> crate::c_types::derived::CResult_InvoiceSignOrCreationErrorZ {
164 let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
165 let mut ret = lightning_invoice::utils::create_invoice_from_channelmanager_and_duration_since_epoch_with_payment_hash::<crate::lightning::chain::Watch, crate::lightning::chain::chaininterface::BroadcasterInterface, crate::lightning::chain::keysinterface::KeysInterface, crate::lightning::chain::chaininterface::FeeEstimator, crate::lightning::util::logger::Logger>(channelmanager.get_native_ref(), keys_manager, logger, network.into_native(), local_amt_msat, description.into_string(), core::time::Duration::from_secs(duration_since_epoch), invoice_expiry_delta_secs, ::lightning::ln::PaymentHash(payment_hash.data));
166 let mut local_ret = match ret { Ok(mut o) => crate::c_types::CResultTempl::ok( { crate::lightning_invoice::Invoice { inner: ObjOps::heap_alloc(o), is_owned: true } }).into(), Err(mut e) => crate::c_types::CResultTempl::err( { crate::lightning_invoice::SignOrCreationError::native_into(e) }).into() };
170 impl From<nativeChannelManager> for crate::lightning_invoice::payment::Payer {
171 fn from(obj: nativeChannelManager) -> Self {
172 let mut rust_obj = ChannelManager { inner: ObjOps::heap_alloc(obj), is_owned: true };
173 let mut ret = ChannelManager_as_Payer(&rust_obj);
174 // We want to free rust_obj when ret gets drop()'d, not rust_obj, so wipe rust_obj's pointer and set ret's free() fn
175 rust_obj.inner = core::ptr::null_mut();
176 ret.free = Some(ChannelManager_free_void);
180 /// Constructs a new Payer which calls the relevant methods on this_arg.
181 /// This copies the `inner` pointer in this_arg and thus the returned Payer must be freed before this_arg is
183 pub extern "C" fn ChannelManager_as_Payer(this_arg: &ChannelManager) -> crate::lightning_invoice::payment::Payer {
184 crate::lightning_invoice::payment::Payer {
185 this_arg: unsafe { ObjOps::untweak_ptr((*this_arg).inner) as *mut c_void },
187 node_id: ChannelManager_Payer_node_id,
188 first_hops: ChannelManager_Payer_first_hops,
189 send_payment: ChannelManager_Payer_send_payment,
190 send_spontaneous_payment: ChannelManager_Payer_send_spontaneous_payment,
191 retry_payment: ChannelManager_Payer_retry_payment,
192 abandon_payment: ChannelManager_Payer_abandon_payment,
193 inflight_htlcs: ChannelManager_Payer_inflight_htlcs,
198 extern "C" fn ChannelManager_Payer_node_id(this_arg: *const c_void) -> crate::c_types::PublicKey {
199 let mut ret = <nativeChannelManager as lightning_invoice::payment::Payer<>>::node_id(unsafe { &mut *(this_arg as *mut nativeChannelManager) }, );
200 crate::c_types::PublicKey::from_rust(&ret)
203 extern "C" fn ChannelManager_Payer_first_hops(this_arg: *const c_void) -> crate::c_types::derived::CVec_ChannelDetailsZ {
204 let mut ret = <nativeChannelManager as lightning_invoice::payment::Payer<>>::first_hops(unsafe { &mut *(this_arg as *mut nativeChannelManager) }, );
205 let mut local_ret = Vec::new(); for mut item in ret.drain(..) { local_ret.push( { crate::lightning::ln::channelmanager::ChannelDetails { inner: ObjOps::heap_alloc(item), is_owned: true } }); };
209 extern "C" fn ChannelManager_Payer_send_payment(this_arg: *const c_void, route: &crate::lightning::routing::router::Route, mut payment_hash: crate::c_types::ThirtyTwoBytes, mut payment_secret: crate::c_types::ThirtyTwoBytes, mut payment_id: crate::c_types::ThirtyTwoBytes) -> crate::c_types::derived::CResult_NonePaymentSendFailureZ {
210 let mut local_payment_secret = if payment_secret.data == [0; 32] { None } else { Some( { ::lightning::ln::PaymentSecret(payment_secret.data) }) };
211 let mut ret = <nativeChannelManager as lightning_invoice::payment::Payer<>>::send_payment(unsafe { &mut *(this_arg as *mut nativeChannelManager) }, route.get_native_ref(), ::lightning::ln::PaymentHash(payment_hash.data), &local_payment_secret, ::lightning::ln::channelmanager::PaymentId(payment_id.data));
212 let mut local_ret = match ret { Ok(mut o) => crate::c_types::CResultTempl::ok( { () /*o*/ }).into(), Err(mut e) => crate::c_types::CResultTempl::err( { crate::lightning::ln::channelmanager::PaymentSendFailure::native_into(e) }).into() };
216 extern "C" fn ChannelManager_Payer_send_spontaneous_payment(this_arg: *const c_void, route: &crate::lightning::routing::router::Route, mut payment_preimage: crate::c_types::ThirtyTwoBytes, mut payment_id: crate::c_types::ThirtyTwoBytes) -> crate::c_types::derived::CResult_NonePaymentSendFailureZ {
217 let mut ret = <nativeChannelManager as lightning_invoice::payment::Payer<>>::send_spontaneous_payment(unsafe { &mut *(this_arg as *mut nativeChannelManager) }, route.get_native_ref(), ::lightning::ln::PaymentPreimage(payment_preimage.data), ::lightning::ln::channelmanager::PaymentId(payment_id.data));
218 let mut local_ret = match ret { Ok(mut o) => crate::c_types::CResultTempl::ok( { () /*o*/ }).into(), Err(mut e) => crate::c_types::CResultTempl::err( { crate::lightning::ln::channelmanager::PaymentSendFailure::native_into(e) }).into() };
222 extern "C" fn ChannelManager_Payer_retry_payment(this_arg: *const c_void, route: &crate::lightning::routing::router::Route, mut payment_id: crate::c_types::ThirtyTwoBytes) -> crate::c_types::derived::CResult_NonePaymentSendFailureZ {
223 let mut ret = <nativeChannelManager as lightning_invoice::payment::Payer<>>::retry_payment(unsafe { &mut *(this_arg as *mut nativeChannelManager) }, route.get_native_ref(), ::lightning::ln::channelmanager::PaymentId(payment_id.data));
224 let mut local_ret = match ret { Ok(mut o) => crate::c_types::CResultTempl::ok( { () /*o*/ }).into(), Err(mut e) => crate::c_types::CResultTempl::err( { crate::lightning::ln::channelmanager::PaymentSendFailure::native_into(e) }).into() };
227 extern "C" fn ChannelManager_Payer_abandon_payment(this_arg: *const c_void, mut payment_id: crate::c_types::ThirtyTwoBytes) {
228 <nativeChannelManager as lightning_invoice::payment::Payer<>>::abandon_payment(unsafe { &mut *(this_arg as *mut nativeChannelManager) }, ::lightning::ln::channelmanager::PaymentId(payment_id.data))
231 extern "C" fn ChannelManager_Payer_inflight_htlcs(this_arg: *const c_void) -> crate::lightning::routing::router::InFlightHtlcs {
232 let mut ret = <nativeChannelManager as lightning_invoice::payment::Payer<>>::inflight_htlcs(unsafe { &mut *(this_arg as *mut nativeChannelManager) }, );
233 crate::lightning::routing::router::InFlightHtlcs { inner: ObjOps::heap_alloc(ret), is_owned: true }
236 use crate::lightning::ln::channelmanager::nativeChannelManager as nativeChannelManager;
237 use crate::lightning::ln::channelmanager::ChannelManager;
238 use crate::lightning::ln::channelmanager::ChannelManager_free_void;