X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning-c-bindings%2Fsrc%2Flightning_invoice%2Futils.rs;h=0c066dfd3fd97e3afee9dd2eb1ffbe38998c87e6;hb=ae39d0e5a34ef021db50b12a7be96f0694fd1b18;hp=ef8b51fe65bb30ea8117fd91706aaa1eb1f20741;hpb=dd5bf474af6c806b20c26f4f2b751f3226a94dfd;p=ldk-c-bindings diff --git a/lightning-c-bindings/src/lightning_invoice/utils.rs b/lightning-c-bindings/src/lightning_invoice/utils.rs index ef8b51f..0c066df 100644 --- a/lightning-c-bindings/src/lightning_invoice/utils.rs +++ b/lightning-c-bindings/src/lightning_invoice/utils.rs @@ -8,28 +8,156 @@ //! Convenient utilities to create an invoice. -use std::str::FromStr; -use std::ffi::c_void; +use alloc::str::FromStr; +use core::ffi::c_void; use core::convert::Infallible; use bitcoin::hashes::Hash; use crate::c_types::*; +#[cfg(feature="no-std")] +use alloc::{vec::Vec, boxed::Box}; + +/// Utility to create an invoice that can be paid to one of multiple nodes, or a \"phantom invoice.\" +/// See [`PhantomKeysManager`] for more information on phantom node payments. +/// +/// `phantom_route_hints` parameter: +/// * Contains channel info for all nodes participating in the phantom invoice +/// * Entries are retrieved from a call to [`ChannelManager::get_phantom_route_hints`] on each +/// participating node +/// * It is fine to cache `phantom_route_hints` and reuse it across invoices, as long as the data is +/// updated when a channel becomes disabled or closes +/// * Note that if too many channels are included in [`PhantomRouteHints::channels`], the invoice +/// may be too long for QR code scanning. To fix this, `PhantomRouteHints::channels` may be pared +/// down +/// +/// `payment_hash` can be specified if you have a specific need for a custom payment hash (see the difference +/// between [`ChannelManager::create_inbound_payment`] and [`ChannelManager::create_inbound_payment_for_hash`]). +/// If `None` is provided for `payment_hash`, then one will be created. +/// +/// `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for +/// in excess of the current time. +/// +/// Note that the provided `keys_manager`'s `KeysInterface` implementation must support phantom +/// invoices in its `sign_invoice` implementation ([`PhantomKeysManager`] satisfies this +/// requirement). +/// +/// [`PhantomKeysManager`]: lightning::chain::keysinterface::PhantomKeysManager +/// [`ChannelManager::get_phantom_route_hints`]: lightning::ln::channelmanager::ChannelManager::get_phantom_route_hints +/// [`ChannelManager::create_inbound_payment`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment +/// [`ChannelManager::create_inbound_payment_for_hash`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment_for_hash +/// [`PhantomRouteHints::channels`]: lightning::ln::channelmanager::PhantomRouteHints::channels +/// +/// Note that payment_hash (or a relevant inner pointer) may be NULL or all-0s to represent None +#[no_mangle] +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 network: crate::lightning_invoice::Currency) -> crate::c_types::derived::CResult_InvoiceSignOrCreationErrorZ { + let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None }; + let mut local_payment_hash = if payment_hash.data == [0; 32] { None } else { Some( { ::lightning::ln::PaymentHash(payment_hash.data) }) }; + 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()) } }); }; + let mut ret = lightning_invoice::utils::create_phantom_invoice::(local_amt_msat, local_payment_hash, description.into_string(), invoice_expiry_delta_secs, local_phantom_route_hints, keys_manager, network.into_native()); + 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() }; + local_ret +} + +/// Utility to create an invoice that can be paid to one of multiple nodes, or a \"phantom invoice.\" +/// See [`PhantomKeysManager`] for more information on phantom node payments. +/// +/// `phantom_route_hints` parameter: +/// * Contains channel info for all nodes participating in the phantom invoice +/// * Entries are retrieved from a call to [`ChannelManager::get_phantom_route_hints`] on each +/// participating node +/// * It is fine to cache `phantom_route_hints` and reuse it across invoices, as long as the data is +/// updated when a channel becomes disabled or closes +/// * Note that if too many channels are included in [`PhantomRouteHints::channels`], the invoice +/// may be too long for QR code scanning. To fix this, `PhantomRouteHints::channels` may be pared +/// down +/// +/// `description_hash` is a SHA-256 hash of the description text +/// +/// `payment_hash` can be specified if you have a specific need for a custom payment hash (see the difference +/// between [`ChannelManager::create_inbound_payment`] and [`ChannelManager::create_inbound_payment_for_hash`]). +/// If `None` is provided for `payment_hash`, then one will be created. +/// +/// `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for +/// in excess of the current time. +/// +/// Note that the provided `keys_manager`'s `KeysInterface` implementation must support phantom +/// invoices in its `sign_invoice` implementation ([`PhantomKeysManager`] satisfies this +/// requirement). +/// +/// [`PhantomKeysManager`]: lightning::chain::keysinterface::PhantomKeysManager +/// [`ChannelManager::get_phantom_route_hints`]: lightning::ln::channelmanager::ChannelManager::get_phantom_route_hints +/// [`ChannelManager::create_inbound_payment`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment +/// [`ChannelManager::create_inbound_payment_for_hash`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment_for_hash +/// [`PhantomRouteHints::channels`]: lightning::ln::channelmanager::PhantomRouteHints::channels +/// +/// Note that payment_hash (or a relevant inner pointer) may be NULL or all-0s to represent None +#[no_mangle] +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 network: crate::lightning_invoice::Currency) -> crate::c_types::derived::CResult_InvoiceSignOrCreationErrorZ { + let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None }; + let mut local_payment_hash = if payment_hash.data == [0; 32] { None } else { Some( { ::lightning::ln::PaymentHash(payment_hash.data) }) }; + 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()) } }); }; + let mut ret = lightning_invoice::utils::create_phantom_invoice_with_description_hash::(local_amt_msat, local_payment_hash, invoice_expiry_delta_secs, *unsafe { Box::from_raw(description_hash.take_inner()) }, local_phantom_route_hints, keys_manager, network.into_native()); + 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() }; + local_ret +} /// Utility to construct an invoice. Generally, unless you want to do something like a custom /// cltv_expiry, this is what you should be using to create an invoice. The reason being, this /// method stores the invoice's payment secret and preimage in `ChannelManager`, so (a) the user /// doesn't have to store preimage/payment secret information and (b) `ChannelManager` can verify /// that the payment secret is valid when the invoice is paid. +/// +/// `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for +/// in excess of the current time. +#[no_mangle] +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, mut invoice_expiry_delta_secs: u32) -> crate::c_types::derived::CResult_InvoiceSignOrCreationErrorZ { + let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None }; + let mut ret = lightning_invoice::utils::create_invoice_from_channelmanager::(channelmanager.get_native_ref(), keys_manager, network.into_native(), local_amt_msat, description.into_string(), invoice_expiry_delta_secs); + 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() }; + local_ret +} + +/// Utility to construct an invoice. Generally, unless you want to do something like a custom +/// cltv_expiry, this is what you should be using to create an invoice. The reason being, this +/// method stores the invoice's payment secret and preimage in `ChannelManager`, so (a) the user +/// doesn't have to store preimage/payment secret information and (b) `ChannelManager` can verify +/// that the payment secret is valid when the invoice is paid. +/// Use this variant if you want to pass the `description_hash` to the invoice. +/// +/// `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for +/// in excess of the current time. +#[no_mangle] +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 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 { + let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None }; + let mut ret = lightning_invoice::utils::create_invoice_from_channelmanager_with_description_hash::(channelmanager.get_native_ref(), keys_manager, network.into_native(), local_amt_msat, *unsafe { Box::from_raw(description_hash.take_inner()) }, invoice_expiry_delta_secs); + 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() }; + local_ret +} + +/// See [`create_invoice_from_channelmanager_with_description_hash`] +/// This version can be used in a `no_std` environment, where [`std::time::SystemTime`] is not +/// available and the current time is supplied by the caller. +#[no_mangle] +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 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 { + let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None }; + let mut ret = lightning_invoice::utils::create_invoice_from_channelmanager_with_description_hash_and_duration_since_epoch::(channelmanager.get_native_ref(), keys_manager, 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); + 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() }; + local_ret +} + +/// See [`create_invoice_from_channelmanager`] +/// This version can be used in a `no_std` environment, where [`std::time::SystemTime`] is not +/// available and the current time is supplied by the caller. #[no_mangle] -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 { +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, mut invoice_expiry_delta_secs: u32) -> crate::c_types::derived::CResult_InvoiceSignOrCreationErrorZ { let mut local_amt_msat = if amt_msat.is_some() { Some( { amt_msat.take() }) } else { None }; - let mut ret = lightning_invoice::utils::create_invoice_from_channelmanager(channelmanager.get_native_ref(), keys_manager, network.into_native(), local_amt_msat, description.into_string()); + let mut ret = lightning_invoice::utils::create_invoice_from_channelmanager_and_duration_since_epoch::(channelmanager.get_native_ref(), keys_manager, network.into_native(), local_amt_msat, description.into_string(), core::time::Duration::from_secs(duration_since_epoch), invoice_expiry_delta_secs); 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() }; local_ret } use lightning_invoice::utils::DefaultRouter as nativeDefaultRouterImport; -pub(crate) type nativeDefaultRouter = nativeDefaultRouterImport<&'static lightning::routing::network_graph::NetworkGraph, crate::lightning::util::logger::Logger>; +pub(crate) type nativeDefaultRouter = nativeDefaultRouterImport<&'static lightning::routing::gossip::NetworkGraph, crate::lightning::util::logger::Logger>; /// A [`Router`] implemented using [`find_route`]. #[must_use] @@ -74,16 +202,17 @@ impl DefaultRouter { pub(crate) fn take_inner(mut self) -> *mut nativeDefaultRouter { assert!(self.is_owned); let ret = ObjOps::untweak_ptr(self.inner); - self.inner = std::ptr::null_mut(); + self.inner = core::ptr::null_mut(); ret } } -/// Creates a new router using the given [`NetworkGraph`] and [`Logger`]. +/// Creates a new router using the given [`NetworkGraph`], a [`Logger`], and a randomness source +/// `random_seed_bytes`. #[must_use] #[no_mangle] -pub extern "C" fn DefaultRouter_new(network_graph: &crate::lightning::routing::network_graph::NetworkGraph, mut logger: crate::lightning::util::logger::Logger) -> DefaultRouter { - let mut ret = lightning_invoice::utils::DefaultRouter::new(network_graph.get_native_ref(), logger); - DefaultRouter { inner: ObjOps::heap_alloc(ret), is_owned: true } +pub extern "C" fn DefaultRouter_new(network_graph: &crate::lightning::routing::gossip::NetworkGraph, mut logger: crate::lightning::util::logger::Logger, mut random_seed_bytes: crate::c_types::ThirtyTwoBytes) -> crate::lightning_invoice::utils::DefaultRouter { + let mut ret = lightning_invoice::utils::DefaultRouter::new(network_graph.get_native_ref(), logger, random_seed_bytes.data); + crate::lightning_invoice::utils::DefaultRouter { inner: ObjOps::heap_alloc(ret), is_owned: true } } impl From for crate::lightning_invoice::payment::Router { @@ -91,7 +220,7 @@ impl From for crate::lightning_invoice::payment::Router { let mut rust_obj = DefaultRouter { inner: ObjOps::heap_alloc(obj), is_owned: true }; let mut ret = DefaultRouter_as_Router(&rust_obj); // 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 - rust_obj.inner = std::ptr::null_mut(); + rust_obj.inner = core::ptr::null_mut(); ret.free = Some(DefaultRouter_free_void); ret } @@ -109,7 +238,7 @@ pub extern "C" fn DefaultRouter_as_Router(this_arg: &DefaultRouter) -> crate::li #[must_use] 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 { - let mut local_first_hops_base = if first_hops == std::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[..]); + 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[..]); let mut ret = >::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); 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() }; local_ret @@ -123,7 +252,7 @@ impl From for crate::lightning_invoice::payment::Payer { let mut rust_obj = ChannelManager { inner: ObjOps::heap_alloc(obj), is_owned: true }; let mut ret = ChannelManager_as_Payer(&rust_obj); // 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 - rust_obj.inner = std::ptr::null_mut(); + rust_obj.inner = core::ptr::null_mut(); ret.free = Some(ChannelManager_free_void); ret }