Update CI/Cargo.toml references to 0.0.122
[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 alloc::string::String;
13 use core::ffi::c_void;
14 use core::convert::Infallible;
15 use bitcoin::hashes::Hash;
16 use crate::c_types::*;
17 #[cfg(feature="no-std")]
18 use alloc::{vec::Vec, boxed::Box};
19
20 /// Utility to create an invoice that can be paid to one of multiple nodes, or a \"phantom invoice.\"
21 /// See [`PhantomKeysManager`] for more information on phantom node payments.
22 ///
23 /// `phantom_route_hints` parameter:
24 /// * Contains channel info for all nodes participating in the phantom invoice
25 /// * Entries are retrieved from a call to [`ChannelManager::get_phantom_route_hints`] on each
26 ///   participating node
27 /// * It is fine to cache `phantom_route_hints` and reuse it across invoices, as long as the data is
28 ///   updated when a channel becomes disabled or closes
29 /// * Note that if too many channels are included in [`PhantomRouteHints::channels`], the invoice
30 ///   may be too long for QR code scanning. To fix this, `PhantomRouteHints::channels` may be pared
31 ///   down
32 ///
33 /// `payment_hash` can be specified if you have a specific need for a custom payment hash (see the difference
34 /// between [`ChannelManager::create_inbound_payment`] and [`ChannelManager::create_inbound_payment_for_hash`]).
35 /// If `None` is provided for `payment_hash`, then one will be created.
36 ///
37 /// `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for
38 /// in excess of the current time.
39 ///
40 /// `duration_since_epoch` is the current time since epoch in seconds.
41 ///
42 /// You can specify a custom `min_final_cltv_expiry_delta`, or let LDK default it to
43 /// [`MIN_FINAL_CLTV_EXPIRY_DELTA`]. The provided expiry must be at least [`MIN_FINAL_CLTV_EXPIRY_DELTA`] - 3.
44 /// Note that LDK will add a buffer of 3 blocks to the delta to allow for up to a few new block
45 /// confirmations during routing.
46 ///
47 /// Note that the provided `keys_manager`'s `NodeSigner` implementation must support phantom
48 /// invoices in its `sign_invoice` implementation ([`PhantomKeysManager`] satisfies this
49 /// requirement).
50 ///
51 /// [`PhantomKeysManager`]: lightning::sign::PhantomKeysManager
52 /// [`ChannelManager::get_phantom_route_hints`]: lightning::ln::channelmanager::ChannelManager::get_phantom_route_hints
53 /// [`ChannelManager::create_inbound_payment`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment
54 /// [`ChannelManager::create_inbound_payment_for_hash`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment_for_hash
55 /// [`PhantomRouteHints::channels`]: lightning::ln::channelmanager::PhantomRouteHints::channels
56 /// [`MIN_FINAL_CLTV_EXPIRY_DETLA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA
57 ///
58 /// This can be used in a `no_std` environment, where [`std::time::SystemTime`] is not
59 /// available and the current time is supplied by the caller.
60 #[no_mangle]
61 pub extern "C" fn create_phantom_invoice(mut amt_msat: crate::c_types::derived::COption_u64Z, mut payment_hash: crate::c_types::derived::COption_ThirtyTwoBytesZ, 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 {
62         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
63         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) }})} };
64         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()) } }); };
65         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 };
66         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));
67         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() };
68         local_ret
69 }
70
71 /// Utility to create an invoice that can be paid to one of multiple nodes, or a \"phantom invoice.\"
72 /// See [`PhantomKeysManager`] for more information on phantom node payments.
73 ///
74 /// `phantom_route_hints` parameter:
75 /// * Contains channel info for all nodes participating in the phantom invoice
76 /// * Entries are retrieved from a call to [`ChannelManager::get_phantom_route_hints`] on each
77 ///   participating node
78 /// * It is fine to cache `phantom_route_hints` and reuse it across invoices, as long as the data is
79 ///   updated when a channel becomes disabled or closes
80 /// * Note that the route hints generated from `phantom_route_hints` will be limited to a maximum
81 ///   of 3 hints to ensure that the invoice can be scanned in a QR code. These hints are selected
82 ///   in the order that the nodes in `PhantomRouteHints` are specified, selecting one hint per node
83 ///   until the maximum is hit. Callers may provide as many `PhantomRouteHints::channels` as
84 ///   desired, but note that some nodes will be trimmed if more than 3 nodes are provided.
85 ///
86 /// `description_hash` is a SHA-256 hash of the description text
87 ///
88 /// `payment_hash` can be specified if you have a specific need for a custom payment hash (see the difference
89 /// between [`ChannelManager::create_inbound_payment`] and [`ChannelManager::create_inbound_payment_for_hash`]).
90 /// If `None` is provided for `payment_hash`, then one will be created.
91 ///
92 /// `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for
93 /// in excess of the current time.
94 ///
95 /// `duration_since_epoch` is the current time since epoch in seconds.
96 ///
97 /// Note that the provided `keys_manager`'s `NodeSigner` implementation must support phantom
98 /// invoices in its `sign_invoice` implementation ([`PhantomKeysManager`] satisfies this
99 /// requirement).
100 ///
101 /// [`PhantomKeysManager`]: lightning::sign::PhantomKeysManager
102 /// [`ChannelManager::get_phantom_route_hints`]: lightning::ln::channelmanager::ChannelManager::get_phantom_route_hints
103 /// [`ChannelManager::create_inbound_payment`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment
104 /// [`ChannelManager::create_inbound_payment_for_hash`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment_for_hash
105 /// [`PhantomRouteHints::channels`]: lightning::ln::channelmanager::PhantomRouteHints::channels
106 ///
107 /// This can be used in a `no_std` environment, where [`std::time::SystemTime`] is not
108 /// available and the current time is supplied by the caller.
109 #[no_mangle]
110 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_ThirtyTwoBytesZ, 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 {
111         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
112         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) }})} };
113         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()) } }); };
114         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 };
115         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));
116         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() };
117         local_ret
118 }
119
120 /// Utility to construct an invoice. Generally, unless you want to do something like a custom
121 /// cltv_expiry, this is what you should be using to create an invoice. The reason being, this
122 /// method stores the invoice's payment secret and preimage in `ChannelManager`, so (a) the user
123 /// doesn't have to store preimage/payment secret information and (b) `ChannelManager` can verify
124 /// that the payment secret is valid when the invoice is paid.
125 ///
126 /// `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for
127 /// in excess of the current time.
128 ///
129 /// You can specify a custom `min_final_cltv_expiry_delta`, or let LDK default it to
130 /// [`MIN_FINAL_CLTV_EXPIRY_DELTA`]. The provided expiry must be at least [`MIN_FINAL_CLTV_EXPIRY_DELTA`].
131 /// Note that LDK will add a buffer of 3 blocks to the delta to allow for up to a few new block
132 /// confirmations during routing.
133 ///
134 /// [`MIN_FINAL_CLTV_EXPIRY_DETLA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA
135 #[no_mangle]
136 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 {
137         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
138         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 };
139         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);
140         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() };
141         local_ret
142 }
143
144 /// Utility to construct an invoice. Generally, unless you want to do something like a custom
145 /// cltv_expiry, this is what you should be using to create an invoice. The reason being, this
146 /// method stores the invoice's payment secret and preimage in `ChannelManager`, so (a) the user
147 /// doesn't have to store preimage/payment secret information and (b) `ChannelManager` can verify
148 /// that the payment secret is valid when the invoice is paid.
149 /// Use this variant if you want to pass the `description_hash` to the invoice.
150 ///
151 /// `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for
152 /// in excess of the current time.
153 ///
154 /// You can specify a custom `min_final_cltv_expiry_delta`, or let LDK default it to
155 /// [`MIN_FINAL_CLTV_EXPIRY_DELTA`]. The provided expiry must be at least [`MIN_FINAL_CLTV_EXPIRY_DELTA`].
156 /// Note that LDK will add a buffer of 3 blocks to the delta to allow for up to a few new block
157 /// confirmations during routing.
158 ///
159 /// [`MIN_FINAL_CLTV_EXPIRY_DETLA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA
160 #[no_mangle]
161 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 {
162         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
163         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 };
164         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);
165         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() };
166         local_ret
167 }
168
169 /// See [`create_invoice_from_channelmanager_with_description_hash`]
170 /// This version can be used in a `no_std` environment, where [`std::time::SystemTime`] is not
171 /// available and the current time is supplied by the caller.
172 #[no_mangle]
173 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 {
174         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
175         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 };
176         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);
177         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() };
178         local_ret
179 }
180
181 /// See [`create_invoice_from_channelmanager`]
182 /// This version can be used in a `no_std` environment, where [`std::time::SystemTime`] is not
183 /// available and the current time is supplied by the caller.
184 #[no_mangle]
185 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 {
186         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
187         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 };
188         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);
189         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() };
190         local_ret
191 }
192
193 /// See [`create_invoice_from_channelmanager_and_duration_since_epoch`]
194 /// This version allows for providing a custom [`PaymentHash`] for the invoice.
195 /// This may be useful if you're building an on-chain swap or involving another protocol where
196 /// the payment hash is also involved outside the scope of lightning.
197 #[no_mangle]
198 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 {
199         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
200         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 };
201         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);
202         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() };
203         local_ret
204 }
205