Update auto-generated bindings
[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::chain::keysinterface::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 ///
60 /// Note that payment_hash (or a relevant inner pointer) may be NULL or all-0s to represent None
61 #[no_mangle]
62 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 entropy_source: crate::lightning::chain::keysinterface::EntropySource, mut node_signer: crate::lightning::chain::keysinterface::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_InvoiceSignOrCreationErrorZ {
63         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
64         let mut local_payment_hash = if payment_hash.data == [0; 32] { None } else { Some( { ::lightning::ln::PaymentHash(payment_hash.data) }) };
65         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()) } }); };
66         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 };
67         let mut ret = lightning_invoice::utils::create_phantom_invoice::<crate::lightning::chain::keysinterface::EntropySource, crate::lightning::chain::keysinterface::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));
68         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() };
69         local_ret
70 }
71
72 /// Utility to create an invoice that can be paid to one of multiple nodes, or a \"phantom invoice.\"
73 /// See [`PhantomKeysManager`] for more information on phantom node payments.
74 ///
75 /// `phantom_route_hints` parameter:
76 /// * Contains channel info for all nodes participating in the phantom invoice
77 /// * Entries are retrieved from a call to [`ChannelManager::get_phantom_route_hints`] on each
78 ///   participating node
79 /// * It is fine to cache `phantom_route_hints` and reuse it across invoices, as long as the data is
80 ///   updated when a channel becomes disabled or closes
81 /// * Note that if too many channels are included in [`PhantomRouteHints::channels`], the invoice
82 ///   may be too long for QR code scanning. To fix this, `PhantomRouteHints::channels` may be pared
83 ///   down
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::chain::keysinterface::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 ///
109 /// Note that payment_hash (or a relevant inner pointer) may be NULL or all-0s to represent None
110 #[no_mangle]
111 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 entropy_source: crate::lightning::chain::keysinterface::EntropySource, mut node_signer: crate::lightning::chain::keysinterface::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_InvoiceSignOrCreationErrorZ {
112         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
113         let mut local_payment_hash = if payment_hash.data == [0; 32] { None } else { Some( { ::lightning::ln::PaymentHash(payment_hash.data) }) };
114         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()) } }); };
115         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 };
116         let mut ret = lightning_invoice::utils::create_phantom_invoice_with_description_hash::<crate::lightning::chain::keysinterface::EntropySource, crate::lightning::chain::keysinterface::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));
117         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() };
118         local_ret
119 }
120
121 /// Utility to construct an invoice. Generally, unless you want to do something like a custom
122 /// cltv_expiry, this is what you should be using to create an invoice. The reason being, this
123 /// method stores the invoice's payment secret and preimage in `ChannelManager`, so (a) the user
124 /// doesn't have to store preimage/payment secret information and (b) `ChannelManager` can verify
125 /// that the payment secret is valid when the invoice is paid.
126 ///
127 /// `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for
128 /// in excess of the current time.
129 ///
130 /// You can specify a custom `min_final_cltv_expiry_delta`, or let LDK default it to
131 /// [`MIN_FINAL_CLTV_EXPIRY_DELTA`]. The provided expiry must be at least [`MIN_FINAL_CLTV_EXPIRY_DELTA`].
132 /// Note that LDK will add a buffer of 3 blocks to the delta to allow for up to a few new block
133 /// confirmations during routing.
134 ///
135 /// [`MIN_FINAL_CLTV_EXPIRY_DETLA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA
136 #[no_mangle]
137 pub extern "C" fn create_invoice_from_channelmanager(channelmanager: &crate::lightning::ln::channelmanager::ChannelManager, mut node_signer: crate::lightning::chain::keysinterface::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_InvoiceSignOrCreationErrorZ {
138         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
139         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 };
140         let mut ret = lightning_invoice::utils::create_invoice_from_channelmanager::<crate::lightning::chain::Watch, crate::lightning::chain::chaininterface::BroadcasterInterface, crate::lightning::chain::keysinterface::EntropySource, crate::lightning::chain::keysinterface::NodeSigner, crate::lightning::chain::keysinterface::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);
141         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() };
142         local_ret
143 }
144
145 /// Utility to construct an invoice. Generally, unless you want to do something like a custom
146 /// cltv_expiry, this is what you should be using to create an invoice. The reason being, this
147 /// method stores the invoice's payment secret and preimage in `ChannelManager`, so (a) the user
148 /// doesn't have to store preimage/payment secret information and (b) `ChannelManager` can verify
149 /// that the payment secret is valid when the invoice is paid.
150 /// Use this variant if you want to pass the `description_hash` to the invoice.
151 ///
152 /// `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for
153 /// in excess of the current time.
154 ///
155 /// You can specify a custom `min_final_cltv_expiry_delta`, or let LDK default it to
156 /// [`MIN_FINAL_CLTV_EXPIRY_DELTA`]. The provided expiry must be at least [`MIN_FINAL_CLTV_EXPIRY_DELTA`].
157 /// Note that LDK will add a buffer of 3 blocks to the delta to allow for up to a few new block
158 /// confirmations during routing.
159 ///
160 /// [`MIN_FINAL_CLTV_EXPIRY_DETLA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA
161 #[no_mangle]
162 pub extern "C" fn create_invoice_from_channelmanager_with_description_hash(channelmanager: &crate::lightning::ln::channelmanager::ChannelManager, mut node_signer: crate::lightning::chain::keysinterface::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_InvoiceSignOrCreationErrorZ {
163         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
164         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 };
165         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::EntropySource, crate::lightning::chain::keysinterface::NodeSigner, crate::lightning::chain::keysinterface::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);
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() };
167         local_ret
168 }
169
170 /// See [`create_invoice_from_channelmanager_with_description_hash`]
171 /// This version can be used in a `no_std` environment, where [`std::time::SystemTime`] is not
172 /// available and the current time is supplied by the caller.
173 #[no_mangle]
174 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::chain::keysinterface::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_InvoiceSignOrCreationErrorZ {
175         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
176         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 };
177         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::EntropySource, crate::lightning::chain::keysinterface::NodeSigner, crate::lightning::chain::keysinterface::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);
178         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() };
179         local_ret
180 }
181
182 /// See [`create_invoice_from_channelmanager`]
183 /// This version can be used in a `no_std` environment, where [`std::time::SystemTime`] is not
184 /// available and the current time is supplied by the caller.
185 #[no_mangle]
186 pub extern "C" fn create_invoice_from_channelmanager_and_duration_since_epoch(channelmanager: &crate::lightning::ln::channelmanager::ChannelManager, mut node_signer: crate::lightning::chain::keysinterface::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_InvoiceSignOrCreationErrorZ {
187         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
188         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 };
189         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::EntropySource, crate::lightning::chain::keysinterface::NodeSigner, crate::lightning::chain::keysinterface::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);
190         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() };
191         local_ret
192 }
193
194 /// See [`create_invoice_from_channelmanager_and_duration_since_epoch`]
195 /// This version allows for providing a custom [`PaymentHash`] for the invoice.
196 /// This may be useful if you're building an on-chain swap or involving another protocol where
197 /// the payment hash is also involved outside the scope of lightning.
198 #[no_mangle]
199 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::chain::keysinterface::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_InvoiceSignOrCreationErrorZ {
200         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
201         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 };
202         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::EntropySource, crate::lightning::chain::keysinterface::NodeSigner, crate::lightning::chain::keysinterface::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);
203         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() };
204         local_ret
205 }
206