_ Git - ldk-c-bindings/blob - 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` and `payment_secret` come from [`ChannelManager::create_inbound_payment`] or
  33 /// [`ChannelManager::create_inbound_payment_for_hash`]. These values can be retrieved from any
  34 /// participating node.
  35 ///
  36 /// Note that the provided `keys_manager`'s `KeysInterface` implementation must support phantom
  37 /// invoices in its `sign_invoice` implementation ([`PhantomKeysManager`] satisfies this
  38 /// requirement).
  39 ///
  40 /// [`PhantomKeysManager`]: lightning::chain::keysinterface::PhantomKeysManager
  41 /// [`ChannelManager::get_phantom_route_hints`]: lightning::ln::channelmanager::ChannelManager::get_phantom_route_hints
  42 /// [`PhantomRouteHints::channels`]: lightning::ln::channelmanager::PhantomRouteHints::channels
  43 #[no_mangle]
  44 pub extern "C" fn create_phantom_invoice(mut amt_msat: crate::c_types::derived::COption_u64Z, mut description: crate::c_types::Str, mut payment_hash: crate::c_types::ThirtyTwoBytes, mut payment_secret: crate::c_types::ThirtyTwoBytes, mut phantom_route_hints: crate::c_types::derived::CVec_PhantomRouteHintsZ, mut keys_manager: crate::lightning::chain::keysinterface::KeysInterface, mut network: crate::lightning_invoice::Currency) -> crate::c_types::derived::CResult_InvoiceSignOrCreationErrorZ {
  45         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
  46         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()) } }); };
  47         let mut ret = lightning_invoice::utils::create_phantom_invoice::<crate::lightning::chain::keysinterface::Sign, crate::lightning::chain::keysinterface::KeysInterface>(local_amt_msat, description.into_string(), ::lightning::ln::PaymentHash(payment_hash.data), ::lightning::ln::PaymentSecret(payment_secret.data), local_phantom_route_hints, keys_manager, network.into_native());
  48         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() };
  49         local_ret
  50 }
  51
  52 /// Utility to construct an invoice. Generally, unless you want to do something like a custom
  53 /// cltv_expiry, this is what you should be using to create an invoice. The reason being, this
  54 /// method stores the invoice's payment secret and preimage in `ChannelManager`, so (a) the user
  55 /// doesn't have to store preimage/payment secret information and (b) `ChannelManager` can verify
  56 /// that the payment secret is valid when the invoice is paid.
  57 #[no_mangle]
  58 pub extern "C" fn create_invoice_from_channelmanager(channelmanager: &crate::lightning::ln::channelmanager::ChannelManager, mut keys_manager: crate::lightning::chain::keysinterface::KeysInterface, mut network: crate::lightning_invoice::Currency, mut amt_msat: crate::c_types::derived::COption_u64Z, mut description: crate::c_types::Str) -> crate::c_types::derived::CResult_InvoiceSignOrCreationErrorZ {
  59         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
  60         let mut ret = lightning_invoice::utils::create_invoice_from_channelmanager::<crate::lightning::chain::keysinterface::Sign, 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, network.into_native(), local_amt_msat, description.into_string());
  61         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() };
  62         local_ret
  63 }
  64
  65 /// See [`create_invoice_from_channelmanager`]
  66 /// This version can be used in a `no_std` environment, where [`std::time::SystemTime`] is not
  67 /// available and the current time is supplied by the caller.
  68 #[no_mangle]
  69 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 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) -> crate::c_types::derived::CResult_InvoiceSignOrCreationErrorZ {
  70         let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None };
  71         let mut ret = lightning_invoice::utils::create_invoice_from_channelmanager_and_duration_since_epoch::<crate::lightning::chain::keysinterface::Sign, 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, network.into_native(), local_amt_msat, description.into_string(), core::time::Duration::from_secs(duration_since_epoch));
  72         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() };
  73         local_ret
  74 }
  75
  76
  77 use lightning_invoice::utils::DefaultRouter as nativeDefaultRouterImport;
  78 pub(crate) type nativeDefaultRouter = nativeDefaultRouterImport<&'static lightning::routing::network_graph::NetworkGraph, crate::lightning::util::logger::Logger>;
  79
  80 /// A [`Router`] implemented using [`find_route`].
  81 #[must_use]
  82 #[repr(C)]
  83 pub struct DefaultRouter {
  84         /// A pointer to the opaque Rust object.
  85
  86         /// Nearly everywhere, inner must be non-null, however in places where
  87         /// the Rust equivalent takes an Option, it may be set to null to indicate None.
  88         pub inner: *mut nativeDefaultRouter,
  89         /// Indicates that this is the only struct which contains the same pointer.
  90
  91         /// Rust functions which take ownership of an object provided via an argument require
  92         /// this to be true and invalidate the object pointed to by inner.
  93         pub is_owned: bool,
  94 }
  95
  96 impl Drop for DefaultRouter {
  97         fn drop(&mut self) {
  98                 if self.is_owned && !<*mut nativeDefaultRouter>::is_null(self.inner) {
  99                         let _ = unsafe { Box::from_raw(ObjOps::untweak_ptr(self.inner)) };
 100                 }
 101         }
 102 }
 103 /// Frees any resources used by the DefaultRouter, if is_owned is set and inner is non-NULL.
 104 #[no_mangle]
 105 pub extern "C" fn DefaultRouter_free(this_obj: DefaultRouter) { }
 106 #[allow(unused)]
 107 /// Used only if an object of this type is returned as a trait impl by a method
 108 pub(crate) extern "C" fn DefaultRouter_free_void(this_ptr: *mut c_void) {
 109         unsafe { let _ = Box::from_raw(this_ptr as *mut nativeDefaultRouter); }
 110 }
 111 #[allow(unused)]
 112 impl DefaultRouter {
 113         pub(crate) fn get_native_ref(&self) -> &'static nativeDefaultRouter {
 114                 unsafe { &*ObjOps::untweak_ptr(self.inner) }
 115         }
 116         pub(crate) fn get_native_mut_ref(&self) -> &'static mut nativeDefaultRouter {
 117                 unsafe { &mut *ObjOps::untweak_ptr(self.inner) }
 118         }
 119         /// When moving out of the pointer, we have to ensure we aren't a reference, this makes that easy
 120         pub(crate) fn take_inner(mut self) -> *mut nativeDefaultRouter {
 121                 assert!(self.is_owned);
 122                 let ret = ObjOps::untweak_ptr(self.inner);
 123                 self.inner = core::ptr::null_mut();
 124                 ret
 125         }
 126 }
 127 /// Creates a new router using the given [`NetworkGraph`] and  [`Logger`].
 128 #[must_use]
 129 #[no_mangle]
 130 pub extern "C" fn DefaultRouter_new(network_graph: &crate::lightning::routing::network_graph::NetworkGraph, mut logger: crate::lightning::util::logger::Logger) -> DefaultRouter {
 131         let mut ret = lightning_invoice::utils::DefaultRouter::new(network_graph.get_native_ref(), logger);
 132         DefaultRouter { inner: ObjOps::heap_alloc(ret), is_owned: true }
 133 }
 134
 135 impl From<nativeDefaultRouter> for crate::lightning_invoice::payment::Router {
 136         fn from(obj: nativeDefaultRouter) -> Self {
 137                 let mut rust_obj = DefaultRouter { inner: ObjOps::heap_alloc(obj), is_owned: true };
 138                 let mut ret = DefaultRouter_as_Router(&rust_obj);
 139                 // 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
 140                 rust_obj.inner = core::ptr::null_mut();
 141                 ret.free = Some(DefaultRouter_free_void);
 142                 ret
 143         }
 144 }
 145 /// Constructs a new Router which calls the relevant methods on this_arg.
 146 /// This copies the `inner` pointer in this_arg and thus the returned Router must be freed before this_arg is
 147 #[no_mangle]
 148 pub extern "C" fn DefaultRouter_as_Router(this_arg: &DefaultRouter) -> crate::lightning_invoice::payment::Router {
 149         crate::lightning_invoice::payment::Router {
 150                 this_arg: unsafe { ObjOps::untweak_ptr((*this_arg).inner) as *mut c_void },
 151                 free: None,
 152                 find_route: DefaultRouter_Router_find_route,
 153         }
 154 }
 155
 156 #[must_use]
 157 extern "C" fn DefaultRouter_Router_find_route(this_arg: *const c_void, mut payer: crate::c_types::PublicKey, params: &crate::lightning::routing::router::RouteParameters, _payment_hash: *const [u8; 32], first_hops: *mut crate::c_types::derived::CVec_ChannelDetailsZ, scorer: &crate::lightning::routing::scoring::Score) -> crate::c_types::derived::CResult_RouteLightningErrorZ {
 158         let mut local_first_hops_base = if first_hops == core::ptr::null_mut() { None } else { Some( { let mut local_first_hops_0 = Vec::new(); for mut item in unsafe { &mut *first_hops }.as_slice().iter() { local_first_hops_0.push( { item.get_native_ref() }); }; local_first_hops_0 }) }; let mut local_first_hops = local_first_hops_base.as_ref().map(|a| &a[..]);
 159         let mut ret = <nativeDefaultRouter as lightning_invoice::payment::Router<_>>::find_route(unsafe { &mut *(this_arg as *mut nativeDefaultRouter) }, &payer.into_rust(), params.get_native_ref(), &::lightning::ln::PaymentHash(unsafe { *_payment_hash }), local_first_hops, scorer);
 160         let mut local_ret = match ret { Ok(mut o) => crate::c_types::CResultTempl::ok( { crate::lightning::routing::router::Route { inner: ObjOps::heap_alloc(o), is_owned: true } }).into(), Err(mut e) => crate::c_types::CResultTempl::err( { crate::lightning::ln::msgs::LightningError { inner: ObjOps::heap_alloc(e), is_owned: true } }).into() };
 161         local_ret
 162 }
 163
 164 use crate::lightning::ln::channelmanager::nativeChannelManager as nativeChannelManager;
 165 use crate::lightning::ln::channelmanager::ChannelManager;
 166 use crate::lightning::ln::channelmanager::ChannelManager_free_void;
 167 impl From<nativeChannelManager> for crate::lightning_invoice::payment::Payer {
 168         fn from(obj: nativeChannelManager) -> Self {
 169                 let mut rust_obj = ChannelManager { inner: ObjOps::heap_alloc(obj), is_owned: true };
 170                 let mut ret = ChannelManager_as_Payer(&rust_obj);
 171                 // 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
 172                 rust_obj.inner = core::ptr::null_mut();
 173                 ret.free = Some(ChannelManager_free_void);
 174                 ret
 175         }
 176 }
 177 /// Constructs a new Payer which calls the relevant methods on this_arg.
 178 /// This copies the `inner` pointer in this_arg and thus the returned Payer must be freed before this_arg is
 179 #[no_mangle]
 180 pub extern "C" fn ChannelManager_as_Payer(this_arg: &ChannelManager) -> crate::lightning_invoice::payment::Payer {
 181         crate::lightning_invoice::payment::Payer {
 182                 this_arg: unsafe { ObjOps::untweak_ptr((*this_arg).inner) as *mut c_void },
 183                 free: None,
 184                 node_id: ChannelManager_Payer_node_id,
 185                 first_hops: ChannelManager_Payer_first_hops,
 186                 send_payment: ChannelManager_Payer_send_payment,
 187                 send_spontaneous_payment: ChannelManager_Payer_send_spontaneous_payment,
 188                 retry_payment: ChannelManager_Payer_retry_payment,
 189                 abandon_payment: ChannelManager_Payer_abandon_payment,
 190         }
 191 }
 192
 193 #[must_use]
 194 extern "C" fn ChannelManager_Payer_node_id(this_arg: *const c_void) -> crate::c_types::PublicKey {
 195         let mut ret = <nativeChannelManager as lightning_invoice::payment::Payer<>>::node_id(unsafe { &mut *(this_arg as *mut nativeChannelManager) }, );
 196         crate::c_types::PublicKey::from_rust(&ret)
 197 }
 198 #[must_use]
 199 extern "C" fn ChannelManager_Payer_first_hops(this_arg: *const c_void) -> crate::c_types::derived::CVec_ChannelDetailsZ {
 200         let mut ret = <nativeChannelManager as lightning_invoice::payment::Payer<>>::first_hops(unsafe { &mut *(this_arg as *mut nativeChannelManager) }, );
 201         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 } }); };
 202         local_ret.into()
 203 }
 204 #[must_use]
 205 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) -> crate::c_types::derived::CResult_PaymentIdPaymentSendFailureZ {
 206         let mut local_payment_secret = if payment_secret.data == [0; 32] { None } else { Some( { ::lightning::ln::PaymentSecret(payment_secret.data) }) };
 207         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);
 208         let mut local_ret = match ret { Ok(mut o) => crate::c_types::CResultTempl::ok( { crate::c_types::ThirtyTwoBytes { data: o.0 } }).into(), Err(mut e) => crate::c_types::CResultTempl::err( { crate::lightning::ln::channelmanager::PaymentSendFailure::native_into(e) }).into() };
 209         local_ret
 210 }
 211 #[must_use]
 212 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) -> crate::c_types::derived::CResult_PaymentIdPaymentSendFailureZ {
 213         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));
 214         let mut local_ret = match ret { Ok(mut o) => crate::c_types::CResultTempl::ok( { crate::c_types::ThirtyTwoBytes { data: o.0 } }).into(), Err(mut e) => crate::c_types::CResultTempl::err( { crate::lightning::ln::channelmanager::PaymentSendFailure::native_into(e) }).into() };
 215         local_ret
 216 }
 217 #[must_use]
 218 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 {
 219         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));
 220         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() };
 221         local_ret
 222 }
 223 extern "C" fn ChannelManager_Payer_abandon_payment(this_arg: *const c_void, mut payment_id: crate::c_types::ThirtyTwoBytes) {
 224         <nativeChannelManager as lightning_invoice::payment::Payer<>>::abandon_payment(unsafe { &mut *(this_arg as *mut nativeChannelManager) }, ::lightning::ln::channelmanager::PaymentId(payment_id.data))
 225 }
 226