0b1f0bb14d694b9bca9bfea1d0d23e90b16e0147
[ldk-c-bindings] / lightning-c-bindings / src / lightning_invoice / utils.rs
1 // This file is Copyright its original authors, visible in version control
2 // history and in the source files from which this was generated.
3 //
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.
8
9 //! Convenient utilities to create an invoice.
10
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};
18
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.
21 ///
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
30 ///   down
31 ///
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.
35 ///
36 /// `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for
37 /// in excess of the current time.
38 ///
39 /// `duration_since_epoch` is the current time since epoch in seconds.
40 ///
41 /// You can specify a custom `min_final_cltv_expiry_delta`, or let LDK default it to
42 /// [`MIN_FINAL_CLTV_EXPIRY_DELTA`]. The provided expiry must be at least [`MIN_FINAL_CLTV_EXPIRY_DELTA`] - 3.
43 /// Note that LDK will add a buffer of 3 blocks to the delta to allow for up to a few new block
44 /// confirmations during routing.
45 ///
46 /// Note that the provided `keys_manager`'s `NodeSigner` implementation must support phantom
47 /// invoices in its `sign_invoice` implementation ([`PhantomKeysManager`] satisfies this
48 /// requirement).
49 ///
50 /// [`PhantomKeysManager`]: lightning::sign::PhantomKeysManager
51 /// [`ChannelManager::get_phantom_route_hints`]: lightning::ln::channelmanager::ChannelManager::get_phantom_route_hints
52 /// [`ChannelManager::create_inbound_payment`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment
53 /// [`ChannelManager::create_inbound_payment_for_hash`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment_for_hash
54 /// [`PhantomRouteHints::channels`]: lightning::ln::channelmanager::PhantomRouteHints::channels
55 /// [`MIN_FINAL_CLTV_EXPIRY_DETLA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA
56 ///
57 /// This can be used in a `no_std` environment, where [`std::time::SystemTime`] is not
58 /// available and the current time is supplied by the caller.
59 #[no_mangle]
60 pub extern "C" fn create_phantom_invoice(mut amt_msat: crate::c_types::derived::COption_u64Z, mut payment_hash: crate::c_types::derived::COption_PaymentHashZ, mut description: crate::c_types::Str, mut invoice_expiry_delta_secs: u32, mut phantom_route_hints: crate::c_types::derived::CVec_PhantomRouteHintsZ, mut entropy_source: crate::lightning::sign::EntropySource, mut node_signer: crate::lightning::sign::NodeSigner, mut logger: crate::lightning::util::logger::Logger, mut network: crate::lightning_invoice::Currency, mut min_final_cltv_expiry_delta: crate::c_types::derived::COption_u16Z, mut duration_since_epoch: u64) -> crate::c_types::derived::CResult_Bolt11InvoiceSignOrCreationErrorZ {
61         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
62         let mut local_payment_hash = { /*payment_hash*/ let payment_hash_opt = payment_hash; if payment_hash_opt.is_none() { None } else { Some({ { ::lightning::ln::PaymentHash({ payment_hash_opt.take() }.data) }})} };
63         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()) } }); };
64         let mut local_min_final_cltv_expiry_delta = if min_final_cltv_expiry_delta.is_some() { Some( { min_final_cltv_expiry_delta.take() }) } else { None };
65         let mut ret = lightning_invoice::utils::create_phantom_invoice::<crate::lightning::sign::EntropySource, crate::lightning::sign::NodeSigner, crate::lightning::util::logger::Logger>(local_amt_msat, local_payment_hash, description.into_string(), invoice_expiry_delta_secs, local_phantom_route_hints, entropy_source, node_signer, logger, network.into_native(), local_min_final_cltv_expiry_delta, core::time::Duration::from_secs(duration_since_epoch));
66         let mut local_ret = match ret { Ok(mut o) => crate::c_types::CResultTempl::ok( { crate::lightning_invoice::Bolt11Invoice { 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() };
67         local_ret
68 }
69
70 /// Utility to create an invoice that can be paid to one of multiple nodes, or a \"phantom invoice.\"
71 /// See [`PhantomKeysManager`] for more information on phantom node payments.
72 ///
73 /// `phantom_route_hints` parameter:
74 /// * Contains channel info for all nodes participating in the phantom invoice
75 /// * Entries are retrieved from a call to [`ChannelManager::get_phantom_route_hints`] on each
76 ///   participating node
77 /// * It is fine to cache `phantom_route_hints` and reuse it across invoices, as long as the data is
78 ///   updated when a channel becomes disabled or closes
79 /// * Note that the route hints generated from `phantom_route_hints` will be limited to a maximum
80 ///   of 3 hints to ensure that the invoice can be scanned in a QR code. These hints are selected
81 ///   in the order that the nodes in `PhantomRouteHints` are specified, selecting one hint per node
82 ///   until the maximum is hit. Callers may provide as many `PhantomRouteHints::channels` as
83 ///   desired, but note that some nodes will be trimmed if more than 3 nodes are provided.
84 ///
85 /// `description_hash` is a SHA-256 hash of the description text
86 ///
87 /// `payment_hash` can be specified if you have a specific need for a custom payment hash (see the difference
88 /// between [`ChannelManager::create_inbound_payment`] and [`ChannelManager::create_inbound_payment_for_hash`]).
89 /// If `None` is provided for `payment_hash`, then one will be created.
90 ///
91 /// `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for
92 /// in excess of the current time.
93 ///
94 /// `duration_since_epoch` is the current time since epoch in seconds.
95 ///
96 /// Note that the provided `keys_manager`'s `NodeSigner` implementation must support phantom
97 /// invoices in its `sign_invoice` implementation ([`PhantomKeysManager`] satisfies this
98 /// requirement).
99 ///
100 /// [`PhantomKeysManager`]: lightning::sign::PhantomKeysManager
101 /// [`ChannelManager::get_phantom_route_hints`]: lightning::ln::channelmanager::ChannelManager::get_phantom_route_hints
102 /// [`ChannelManager::create_inbound_payment`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment
103 /// [`ChannelManager::create_inbound_payment_for_hash`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment_for_hash
104 /// [`PhantomRouteHints::channels`]: lightning::ln::channelmanager::PhantomRouteHints::channels
105 ///
106 /// This can be used in a `no_std` environment, where [`std::time::SystemTime`] is not
107 /// available and the current time is supplied by the caller.
108 #[no_mangle]
109 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::derived::COption_PaymentHashZ, mut invoice_expiry_delta_secs: u32, mut description_hash: crate::lightning_invoice::Sha256, mut phantom_route_hints: crate::c_types::derived::CVec_PhantomRouteHintsZ, mut entropy_source: crate::lightning::sign::EntropySource, mut node_signer: crate::lightning::sign::NodeSigner, mut logger: crate::lightning::util::logger::Logger, mut network: crate::lightning_invoice::Currency, mut min_final_cltv_expiry_delta: crate::c_types::derived::COption_u16Z, mut duration_since_epoch: u64) -> crate::c_types::derived::CResult_Bolt11InvoiceSignOrCreationErrorZ {
110         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
111         let mut local_payment_hash = { /*payment_hash*/ let payment_hash_opt = payment_hash; if payment_hash_opt.is_none() { None } else { Some({ { ::lightning::ln::PaymentHash({ payment_hash_opt.take() }.data) }})} };
112         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()) } }); };
113         let mut local_min_final_cltv_expiry_delta = if min_final_cltv_expiry_delta.is_some() { Some( { min_final_cltv_expiry_delta.take() }) } else { None };
114         let mut ret = lightning_invoice::utils::create_phantom_invoice_with_description_hash::<crate::lightning::sign::EntropySource, crate::lightning::sign::NodeSigner, 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, entropy_source, node_signer, logger, network.into_native(), local_min_final_cltv_expiry_delta, core::time::Duration::from_secs(duration_since_epoch));
115         let mut local_ret = match ret { Ok(mut o) => crate::c_types::CResultTempl::ok( { crate::lightning_invoice::Bolt11Invoice { 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() };
116         local_ret
117 }
118
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 ///
125 /// `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for
126 /// in excess of the current time.
127 ///
128 /// You can specify a custom `min_final_cltv_expiry_delta`, or let LDK default it to
129 /// [`MIN_FINAL_CLTV_EXPIRY_DELTA`]. The provided expiry must be at least [`MIN_FINAL_CLTV_EXPIRY_DELTA`].
130 /// Note that LDK will add a buffer of 3 blocks to the delta to allow for up to a few new block
131 /// confirmations during routing.
132 ///
133 /// [`MIN_FINAL_CLTV_EXPIRY_DETLA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA
134 #[no_mangle]
135 pub extern "C" fn create_invoice_from_channelmanager(channelmanager: &crate::lightning::ln::channelmanager::ChannelManager, mut node_signer: crate::lightning::sign::NodeSigner, 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, mut min_final_cltv_expiry_delta: crate::c_types::derived::COption_u16Z) -> crate::c_types::derived::CResult_Bolt11InvoiceSignOrCreationErrorZ {
136         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
137         let mut local_min_final_cltv_expiry_delta = if min_final_cltv_expiry_delta.is_some() { Some( { min_final_cltv_expiry_delta.take() }) } else { None };
138         let mut ret = lightning_invoice::utils::create_invoice_from_channelmanager::<crate::lightning::chain::Watch, crate::lightning::chain::chaininterface::BroadcasterInterface, crate::lightning::sign::EntropySource, crate::lightning::sign::NodeSigner, crate::lightning::sign::SignerProvider, crate::lightning::chain::chaininterface::FeeEstimator, crate::lightning::routing::router::Router, crate::lightning::util::logger::Logger>(channelmanager.get_native_ref(), node_signer, logger, network.into_native(), local_amt_msat, description.into_string(), invoice_expiry_delta_secs, local_min_final_cltv_expiry_delta);
139         let mut local_ret = match ret { Ok(mut o) => crate::c_types::CResultTempl::ok( { crate::lightning_invoice::Bolt11Invoice { 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() };
140         local_ret
141 }
142
143 /// Utility to construct an invoice. Generally, unless you want to do something like a custom
144 /// cltv_expiry, this is what you should be using to create an invoice. The reason being, this
145 /// method stores the invoice's payment secret and preimage in `ChannelManager`, so (a) the user
146 /// doesn't have to store preimage/payment secret information and (b) `ChannelManager` can verify
147 /// that the payment secret is valid when the invoice is paid.
148 /// Use this variant if you want to pass the `description_hash` to the invoice.
149 ///
150 /// `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for
151 /// in excess of the current time.
152 ///
153 /// You can specify a custom `min_final_cltv_expiry_delta`, or let LDK default it to
154 /// [`MIN_FINAL_CLTV_EXPIRY_DELTA`]. The provided expiry must be at least [`MIN_FINAL_CLTV_EXPIRY_DELTA`].
155 /// Note that LDK will add a buffer of 3 blocks to the delta to allow for up to a few new block
156 /// confirmations during routing.
157 ///
158 /// [`MIN_FINAL_CLTV_EXPIRY_DETLA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA
159 #[no_mangle]
160 pub extern "C" fn create_invoice_from_channelmanager_with_description_hash(channelmanager: &crate::lightning::ln::channelmanager::ChannelManager, mut node_signer: crate::lightning::sign::NodeSigner, 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, mut min_final_cltv_expiry_delta: crate::c_types::derived::COption_u16Z) -> crate::c_types::derived::CResult_Bolt11InvoiceSignOrCreationErrorZ {
161         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
162         let mut local_min_final_cltv_expiry_delta = if min_final_cltv_expiry_delta.is_some() { Some( { min_final_cltv_expiry_delta.take() }) } else { None };
163         let mut ret = lightning_invoice::utils::create_invoice_from_channelmanager_with_description_hash::<crate::lightning::chain::Watch, crate::lightning::chain::chaininterface::BroadcasterInterface, crate::lightning::sign::EntropySource, crate::lightning::sign::NodeSigner, crate::lightning::sign::SignerProvider, crate::lightning::chain::chaininterface::FeeEstimator, crate::lightning::routing::router::Router, crate::lightning::util::logger::Logger>(channelmanager.get_native_ref(), node_signer, logger, network.into_native(), local_amt_msat, *unsafe { Box::from_raw(description_hash.take_inner()) }, invoice_expiry_delta_secs, local_min_final_cltv_expiry_delta);
164         let mut local_ret = match ret { Ok(mut o) => crate::c_types::CResultTempl::ok( { crate::lightning_invoice::Bolt11Invoice { 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() };
165         local_ret
166 }
167
168 /// See [`create_invoice_from_channelmanager_with_description_hash`]
169 /// This version can be used in a `no_std` environment, where [`std::time::SystemTime`] is not
170 /// available and the current time is supplied by the caller.
171 #[no_mangle]
172 pub extern "C" fn create_invoice_from_channelmanager_with_description_hash_and_duration_since_epoch(channelmanager: &crate::lightning::ln::channelmanager::ChannelManager, mut node_signer: crate::lightning::sign::NodeSigner, 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, mut min_final_cltv_expiry_delta: crate::c_types::derived::COption_u16Z) -> crate::c_types::derived::CResult_Bolt11InvoiceSignOrCreationErrorZ {
173         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
174         let mut local_min_final_cltv_expiry_delta = if min_final_cltv_expiry_delta.is_some() { Some( { min_final_cltv_expiry_delta.take() }) } else { None };
175         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::sign::EntropySource, crate::lightning::sign::NodeSigner, crate::lightning::sign::SignerProvider, crate::lightning::chain::chaininterface::FeeEstimator, crate::lightning::routing::router::Router, crate::lightning::util::logger::Logger>(channelmanager.get_native_ref(), node_signer, 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, local_min_final_cltv_expiry_delta);
176         let mut local_ret = match ret { Ok(mut o) => crate::c_types::CResultTempl::ok( { crate::lightning_invoice::Bolt11Invoice { 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() };
177         local_ret
178 }
179
180 /// See [`create_invoice_from_channelmanager`]
181 /// This version can be used in a `no_std` environment, where [`std::time::SystemTime`] is not
182 /// available and the current time is supplied by the caller.
183 #[no_mangle]
184 pub extern "C" fn create_invoice_from_channelmanager_and_duration_since_epoch(channelmanager: &crate::lightning::ln::channelmanager::ChannelManager, mut node_signer: crate::lightning::sign::NodeSigner, 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 min_final_cltv_expiry_delta: crate::c_types::derived::COption_u16Z) -> crate::c_types::derived::CResult_Bolt11InvoiceSignOrCreationErrorZ {
185         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
186         let mut local_min_final_cltv_expiry_delta = if min_final_cltv_expiry_delta.is_some() { Some( { min_final_cltv_expiry_delta.take() }) } else { None };
187         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::sign::EntropySource, crate::lightning::sign::NodeSigner, crate::lightning::sign::SignerProvider, crate::lightning::chain::chaininterface::FeeEstimator, crate::lightning::routing::router::Router, crate::lightning::util::logger::Logger>(channelmanager.get_native_ref(), node_signer, logger, network.into_native(), local_amt_msat, description.into_string(), core::time::Duration::from_secs(duration_since_epoch), invoice_expiry_delta_secs, local_min_final_cltv_expiry_delta);
188         let mut local_ret = match ret { Ok(mut o) => crate::c_types::CResultTempl::ok( { crate::lightning_invoice::Bolt11Invoice { 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() };
189         local_ret
190 }
191
192 /// See [`create_invoice_from_channelmanager_and_duration_since_epoch`]
193 /// This version allows for providing a custom [`PaymentHash`] for the invoice.
194 /// This may be useful if you're building an on-chain swap or involving another protocol where
195 /// the payment hash is also involved outside the scope of lightning.
196 #[no_mangle]
197 pub extern "C" fn create_invoice_from_channelmanager_and_duration_since_epoch_with_payment_hash(channelmanager: &crate::lightning::ln::channelmanager::ChannelManager, mut node_signer: crate::lightning::sign::NodeSigner, 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, mut min_final_cltv_expiry_delta: crate::c_types::derived::COption_u16Z) -> crate::c_types::derived::CResult_Bolt11InvoiceSignOrCreationErrorZ {
198         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
199         let mut local_min_final_cltv_expiry_delta = if min_final_cltv_expiry_delta.is_some() { Some( { min_final_cltv_expiry_delta.take() }) } else { None };
200         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::sign::EntropySource, crate::lightning::sign::NodeSigner, crate::lightning::sign::SignerProvider, crate::lightning::chain::chaininterface::FeeEstimator, crate::lightning::routing::router::Router, crate::lightning::util::logger::Logger>(channelmanager.get_native_ref(), node_signer, 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), local_min_final_cltv_expiry_delta);
201         let mut local_ret = match ret { Ok(mut o) => crate::c_types::CResultTempl::ok( { crate::lightning_invoice::Bolt11Invoice { 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() };
202         local_ret
203 }
204