_ Git - ldk-c-bindings/blob - lightning-c-bindings/src/lightning/offers/invoice.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 //! Data structures and encoding for `invoice` messages.
  10 //!
  11 //! An [`Invoice`] can be built from a parsed [`InvoiceRequest`] for the \"offer to be paid\" flow or
  12 //! from a [`Refund`] as an \"offer for money\" flow. The expected recipient of the payment then sends
  13 //! the invoice to the intended payer, who will then pay it.
  14 //!
  15 //! The payment recipient must include a [`PaymentHash`], so as to reveal the preimage upon payment
  16 //! receipt, and one or more [`BlindedPath`]s for the payer to use when sending the payment.
  17 //!
  18 //! ```
  19 //! extern crate bitcoin;
  20 //! extern crate lightning;
  21 //!
  22 //! use bitcoin::hashes::Hash;
  23 //! use bitcoin::secp256k1::{KeyPair, PublicKey, Secp256k1, SecretKey};
  24 //! use core::convert::{Infallible, TryFrom};
  25 //! use lightning::offers::invoice_request::InvoiceRequest;
  26 //! use lightning::offers::refund::Refund;
  27 //! use lightning::util::ser::Writeable;
  28 //!
  29 //! # use lightning::ln::PaymentHash;
  30 //! # use lightning::offers::invoice::BlindedPayInfo;
  31 //! # use lightning::blinded_path::BlindedPath;
  32 //! #
  33 //! # fn create_payment_paths() -> Vec<(BlindedPath, BlindedPayInfo)> { unimplemented!() }
  34 //! # fn create_payment_hash() -> PaymentHash { unimplemented!() }
  35 //! #
  36 //! # fn parse_invoice_request(bytes: Vec<u8>) -> Result<(), lightning::offers::parse::ParseError> {
  37 //! let payment_paths = create_payment_paths();
  38 //! let payment_hash = create_payment_hash();
  39 //! let secp_ctx = Secp256k1::new();
  40 //! let keys = KeyPair::from_secret_key(&secp_ctx, &SecretKey::from_slice(&[42; 32])?);
  41 //! let pubkey = PublicKey::from(keys);
  42 //! let wpubkey_hash = bitcoin::util::key::PublicKey::new(pubkey).wpubkey_hash().unwrap();
  43 //! let mut buffer = Vec::new();
  44 //!
  45 //! // Invoice for the \"offer to be paid\" flow.
  46 //! InvoiceRequest::try_from(bytes)?
  47 //!
  48 //!    .respond_with(payment_paths, payment_hash)?
  49 //!
  50 //!     .relative_expiry(3600)
  51 //!     .allow_mpp()
  52 //!     .fallback_v0_p2wpkh(&wpubkey_hash)
  53 //!     .build()?
  54 //!     .sign::<_, Infallible>(|digest| Ok(secp_ctx.sign_schnorr_no_aux_rand(digest, &keys)))
  55 //!     .expect(\"failed verifying signature\")
  56 //!     .write(&mut buffer)
  57 //!     .unwrap();
  58 //! # Ok(())
  59 //! # }
  60 //!
  61 //! # fn parse_refund(bytes: Vec<u8>) -> Result<(), lightning::offers::parse::ParseError> {
  62 //! # let payment_paths = create_payment_paths();
  63 //! # let payment_hash = create_payment_hash();
  64 //! # let secp_ctx = Secp256k1::new();
  65 //! # let keys = KeyPair::from_secret_key(&secp_ctx, &SecretKey::from_slice(&[42; 32])?);
  66 //! # let pubkey = PublicKey::from(keys);
  67 //! # let wpubkey_hash = bitcoin::util::key::PublicKey::new(pubkey).wpubkey_hash().unwrap();
  68 //! # let mut buffer = Vec::new();
  69 //!
  70 //! // Invoice for the \"offer for money\" flow.
  71 //! \"lnr1qcp4256ypq\"
  72 //!     .parse::<Refund>()?
  73 //!
  74 //!    .respond_with(payment_paths, payment_hash, pubkey)?
  75 //!
  76 //!     .relative_expiry(3600)
  77 //!     .allow_mpp()
  78 //!     .fallback_v0_p2wpkh(&wpubkey_hash)
  79 //!     .build()?
  80 //!     .sign::<_, Infallible>(|digest| Ok(secp_ctx.sign_schnorr_no_aux_rand(digest, &keys)))
  81 //!     .expect(\"failed verifying signature\")
  82 //!     .write(&mut buffer)
  83 //!     .unwrap();
  84 //! # Ok(())
  85 //! # }
  86 //!
  87 //! ```
  88
  89 use alloc::str::FromStr;
  90 use core::ffi::c_void;
  91 use core::convert::Infallible;
  92 use bitcoin::hashes::Hash;
  93 use crate::c_types::*;
  94 #[cfg(feature="no-std")]
  95 use alloc::{vec::Vec, boxed::Box};
  96
  97
  98 use lightning::offers::invoice::UnsignedInvoice as nativeUnsignedInvoiceImport;
  99 pub(crate) type nativeUnsignedInvoice = nativeUnsignedInvoiceImport<'static>;
 100
 101 /// A semantically valid [`Invoice`] that hasn't been signed.
 102 #[must_use]
 103 #[repr(C)]
 104 pub struct UnsignedInvoice {
 105         /// A pointer to the opaque Rust object.
 106
 107         /// Nearly everywhere, inner must be non-null, however in places where
 108         /// the Rust equivalent takes an Option, it may be set to null to indicate None.
 109         pub inner: *mut nativeUnsignedInvoice,
 110         /// Indicates that this is the only struct which contains the same pointer.
 111
 112         /// Rust functions which take ownership of an object provided via an argument require
 113         /// this to be true and invalidate the object pointed to by inner.
 114         pub is_owned: bool,
 115 }
 116
 117 impl Drop for UnsignedInvoice {
 118         fn drop(&mut self) {
 119                 if self.is_owned && !<*mut nativeUnsignedInvoice>::is_null(self.inner) {
 120                         let _ = unsafe { Box::from_raw(ObjOps::untweak_ptr(self.inner)) };
 121                 }
 122         }
 123 }
 124 /// Frees any resources used by the UnsignedInvoice, if is_owned is set and inner is non-NULL.
 125 #[no_mangle]
 126 pub extern "C" fn UnsignedInvoice_free(this_obj: UnsignedInvoice) { }
 127 #[allow(unused)]
 128 /// Used only if an object of this type is returned as a trait impl by a method
 129 pub(crate) extern "C" fn UnsignedInvoice_free_void(this_ptr: *mut c_void) {
 130         let _ = unsafe { Box::from_raw(this_ptr as *mut nativeUnsignedInvoice) };
 131 }
 132 #[allow(unused)]
 133 impl UnsignedInvoice {
 134         pub(crate) fn get_native_ref(&self) -> &'static nativeUnsignedInvoice {
 135                 unsafe { &*ObjOps::untweak_ptr(self.inner) }
 136         }
 137         pub(crate) fn get_native_mut_ref(&self) -> &'static mut nativeUnsignedInvoice {
 138                 unsafe { &mut *ObjOps::untweak_ptr(self.inner) }
 139         }
 140         /// When moving out of the pointer, we have to ensure we aren't a reference, this makes that easy
 141         pub(crate) fn take_inner(mut self) -> *mut nativeUnsignedInvoice {
 142                 assert!(self.is_owned);
 143                 let ret = ObjOps::untweak_ptr(self.inner);
 144                 self.inner = core::ptr::null_mut();
 145                 ret
 146         }
 147 }
 148 /// The public key corresponding to the key needed to sign the invoice.
 149 #[must_use]
 150 #[no_mangle]
 151 pub extern "C" fn UnsignedInvoice_signing_pubkey(this_arg: &crate::lightning::offers::invoice::UnsignedInvoice) -> crate::c_types::PublicKey {
 152         let mut ret = unsafe { &*ObjOps::untweak_ptr(this_arg.inner) }.signing_pubkey();
 153         crate::c_types::PublicKey::from_rust(&ret)
 154 }
 155
 156
 157 use lightning::offers::invoice::BlindedPayInfo as nativeBlindedPayInfoImport;
 158 pub(crate) type nativeBlindedPayInfo = nativeBlindedPayInfoImport;
 159
 160 /// Information needed to route a payment across a [`BlindedPath`].
 161 #[must_use]
 162 #[repr(C)]
 163 pub struct BlindedPayInfo {
 164         /// A pointer to the opaque Rust object.
 165
 166         /// Nearly everywhere, inner must be non-null, however in places where
 167         /// the Rust equivalent takes an Option, it may be set to null to indicate None.
 168         pub inner: *mut nativeBlindedPayInfo,
 169         /// Indicates that this is the only struct which contains the same pointer.
 170
 171         /// Rust functions which take ownership of an object provided via an argument require
 172         /// this to be true and invalidate the object pointed to by inner.
 173         pub is_owned: bool,
 174 }
 175
 176 impl Drop for BlindedPayInfo {
 177         fn drop(&mut self) {
 178                 if self.is_owned && !<*mut nativeBlindedPayInfo>::is_null(self.inner) {
 179                         let _ = unsafe { Box::from_raw(ObjOps::untweak_ptr(self.inner)) };
 180                 }
 181         }
 182 }
 183 /// Frees any resources used by the BlindedPayInfo, if is_owned is set and inner is non-NULL.
 184 #[no_mangle]
 185 pub extern "C" fn BlindedPayInfo_free(this_obj: BlindedPayInfo) { }
 186 #[allow(unused)]
 187 /// Used only if an object of this type is returned as a trait impl by a method
 188 pub(crate) extern "C" fn BlindedPayInfo_free_void(this_ptr: *mut c_void) {
 189         let _ = unsafe { Box::from_raw(this_ptr as *mut nativeBlindedPayInfo) };
 190 }
 191 #[allow(unused)]
 192 impl BlindedPayInfo {
 193         pub(crate) fn get_native_ref(&self) -> &'static nativeBlindedPayInfo {
 194                 unsafe { &*ObjOps::untweak_ptr(self.inner) }
 195         }
 196         pub(crate) fn get_native_mut_ref(&self) -> &'static mut nativeBlindedPayInfo {
 197                 unsafe { &mut *ObjOps::untweak_ptr(self.inner) }
 198         }
 199         /// When moving out of the pointer, we have to ensure we aren't a reference, this makes that easy
 200         pub(crate) fn take_inner(mut self) -> *mut nativeBlindedPayInfo {
 201                 assert!(self.is_owned);
 202                 let ret = ObjOps::untweak_ptr(self.inner);
 203                 self.inner = core::ptr::null_mut();
 204                 ret
 205         }
 206 }
 207 /// Base fee charged (in millisatoshi) for the entire blinded path.
 208 #[no_mangle]
 209 pub extern "C" fn BlindedPayInfo_get_fee_base_msat(this_ptr: &BlindedPayInfo) -> u32 {
 210         let mut inner_val = &mut this_ptr.get_native_mut_ref().fee_base_msat;
 211         *inner_val
 212 }
 213 /// Base fee charged (in millisatoshi) for the entire blinded path.
 214 #[no_mangle]
 215 pub extern "C" fn BlindedPayInfo_set_fee_base_msat(this_ptr: &mut BlindedPayInfo, mut val: u32) {
 216         unsafe { &mut *ObjOps::untweak_ptr(this_ptr.inner) }.fee_base_msat = val;
 217 }
 218 /// Liquidity fee charged (in millionths of the amount transferred) for the entire blinded path
 219 /// (i.e., 10,000 is 1%).
 220 #[no_mangle]
 221 pub extern "C" fn BlindedPayInfo_get_fee_proportional_millionths(this_ptr: &BlindedPayInfo) -> u32 {
 222         let mut inner_val = &mut this_ptr.get_native_mut_ref().fee_proportional_millionths;
 223         *inner_val
 224 }
 225 /// Liquidity fee charged (in millionths of the amount transferred) for the entire blinded path
 226 /// (i.e., 10,000 is 1%).
 227 #[no_mangle]
 228 pub extern "C" fn BlindedPayInfo_set_fee_proportional_millionths(this_ptr: &mut BlindedPayInfo, mut val: u32) {
 229         unsafe { &mut *ObjOps::untweak_ptr(this_ptr.inner) }.fee_proportional_millionths = val;
 230 }
 231 /// Number of blocks subtracted from an incoming HTLC's `cltv_expiry` for the entire blinded
 232 /// path.
 233 #[no_mangle]
 234 pub extern "C" fn BlindedPayInfo_get_cltv_expiry_delta(this_ptr: &BlindedPayInfo) -> u16 {
 235         let mut inner_val = &mut this_ptr.get_native_mut_ref().cltv_expiry_delta;
 236         *inner_val
 237 }
 238 /// Number of blocks subtracted from an incoming HTLC's `cltv_expiry` for the entire blinded
 239 /// path.
 240 #[no_mangle]
 241 pub extern "C" fn BlindedPayInfo_set_cltv_expiry_delta(this_ptr: &mut BlindedPayInfo, mut val: u16) {
 242         unsafe { &mut *ObjOps::untweak_ptr(this_ptr.inner) }.cltv_expiry_delta = val;
 243 }
 244 /// The minimum HTLC value (in millisatoshi) that is acceptable to all channel peers on the
 245 /// blinded path from the introduction node to the recipient, accounting for any fees, i.e., as
 246 /// seen by the recipient.
 247 #[no_mangle]
 248 pub extern "C" fn BlindedPayInfo_get_htlc_minimum_msat(this_ptr: &BlindedPayInfo) -> u64 {
 249         let mut inner_val = &mut this_ptr.get_native_mut_ref().htlc_minimum_msat;
 250         *inner_val
 251 }
 252 /// The minimum HTLC value (in millisatoshi) that is acceptable to all channel peers on the
 253 /// blinded path from the introduction node to the recipient, accounting for any fees, i.e., as
 254 /// seen by the recipient.
 255 #[no_mangle]
 256 pub extern "C" fn BlindedPayInfo_set_htlc_minimum_msat(this_ptr: &mut BlindedPayInfo, mut val: u64) {
 257         unsafe { &mut *ObjOps::untweak_ptr(this_ptr.inner) }.htlc_minimum_msat = val;
 258 }
 259 /// The maximum HTLC value (in millisatoshi) that is acceptable to all channel peers on the
 260 /// blinded path from the introduction node to the recipient, accounting for any fees, i.e., as
 261 /// seen by the recipient.
 262 #[no_mangle]
 263 pub extern "C" fn BlindedPayInfo_get_htlc_maximum_msat(this_ptr: &BlindedPayInfo) -> u64 {
 264         let mut inner_val = &mut this_ptr.get_native_mut_ref().htlc_maximum_msat;
 265         *inner_val
 266 }
 267 /// The maximum HTLC value (in millisatoshi) that is acceptable to all channel peers on the
 268 /// blinded path from the introduction node to the recipient, accounting for any fees, i.e., as
 269 /// seen by the recipient.
 270 #[no_mangle]
 271 pub extern "C" fn BlindedPayInfo_set_htlc_maximum_msat(this_ptr: &mut BlindedPayInfo, mut val: u64) {
 272         unsafe { &mut *ObjOps::untweak_ptr(this_ptr.inner) }.htlc_maximum_msat = val;
 273 }
 274 /// Features set in `encrypted_data_tlv` for the `encrypted_recipient_data` TLV record in an
 275 /// onion payload.
 276 #[no_mangle]
 277 pub extern "C" fn BlindedPayInfo_get_features(this_ptr: &BlindedPayInfo) -> crate::lightning::ln::features::BlindedHopFeatures {
 278         let mut inner_val = &mut this_ptr.get_native_mut_ref().features;
 279         crate::lightning::ln::features::BlindedHopFeatures { inner: unsafe { ObjOps::nonnull_ptr_to_inner((inner_val as *const lightning::ln::features::BlindedHopFeatures<>) as *mut _) }, is_owned: false }
 280 }
 281 /// Features set in `encrypted_data_tlv` for the `encrypted_recipient_data` TLV record in an
 282 /// onion payload.
 283 #[no_mangle]
 284 pub extern "C" fn BlindedPayInfo_set_features(this_ptr: &mut BlindedPayInfo, mut val: crate::lightning::ln::features::BlindedHopFeatures) {
 285         unsafe { &mut *ObjOps::untweak_ptr(this_ptr.inner) }.features = *unsafe { Box::from_raw(val.take_inner()) };
 286 }
 287 /// Constructs a new BlindedPayInfo given each field
 288 #[must_use]
 289 #[no_mangle]
 290 pub extern "C" fn BlindedPayInfo_new(mut fee_base_msat_arg: u32, mut fee_proportional_millionths_arg: u32, mut cltv_expiry_delta_arg: u16, mut htlc_minimum_msat_arg: u64, mut htlc_maximum_msat_arg: u64, mut features_arg: crate::lightning::ln::features::BlindedHopFeatures) -> BlindedPayInfo {
 291         BlindedPayInfo { inner: ObjOps::heap_alloc(nativeBlindedPayInfo {
 292                 fee_base_msat: fee_base_msat_arg,
 293                 fee_proportional_millionths: fee_proportional_millionths_arg,
 294                 cltv_expiry_delta: cltv_expiry_delta_arg,
 295                 htlc_minimum_msat: htlc_minimum_msat_arg,
 296                 htlc_maximum_msat: htlc_maximum_msat_arg,
 297                 features: *unsafe { Box::from_raw(features_arg.take_inner()) },
 298         }), is_owned: true }
 299 }
 300 impl Clone for BlindedPayInfo {
 301         fn clone(&self) -> Self {
 302                 Self {
 303                         inner: if <*mut nativeBlindedPayInfo>::is_null(self.inner) { core::ptr::null_mut() } else {
 304                                 ObjOps::heap_alloc(unsafe { &*ObjOps::untweak_ptr(self.inner) }.clone()) },
 305                         is_owned: true,
 306                 }
 307         }
 308 }
 309 #[allow(unused)]
 310 /// Used only if an object of this type is returned as a trait impl by a method
 311 pub(crate) extern "C" fn BlindedPayInfo_clone_void(this_ptr: *const c_void) -> *mut c_void {
 312         Box::into_raw(Box::new(unsafe { (*(this_ptr as *mut nativeBlindedPayInfo)).clone() })) as *mut c_void
 313 }
 314 #[no_mangle]
 315 /// Creates a copy of the BlindedPayInfo
 316 pub extern "C" fn BlindedPayInfo_clone(orig: &BlindedPayInfo) -> BlindedPayInfo {
 317         orig.clone()
 318 }
 319 /// Generates a non-cryptographic 64-bit hash of the BlindedPayInfo.
 320 #[no_mangle]
 321 pub extern "C" fn BlindedPayInfo_hash(o: &BlindedPayInfo) -> u64 {
 322         if o.inner.is_null() { return 0; }
 323         // Note that we'd love to use alloc::collections::hash_map::DefaultHasher but it's not in core
 324         #[allow(deprecated)]
 325         let mut hasher = core::hash::SipHasher::new();
 326         core::hash::Hash::hash(o.get_native_ref(), &mut hasher);
 327         core::hash::Hasher::finish(&hasher)
 328 }
 329 /// Checks if two BlindedPayInfos contain equal inner contents.
 330 /// This ignores pointers and is_owned flags and looks at the values in fields.
 331 /// Two objects with NULL inner values will be considered "equal" here.
 332 #[no_mangle]
 333 pub extern "C" fn BlindedPayInfo_eq(a: &BlindedPayInfo, b: &BlindedPayInfo) -> bool {
 334         if a.inner == b.inner { return true; }
 335         if a.inner.is_null() || b.inner.is_null() { return false; }
 336         if a.get_native_ref() == b.get_native_ref() { true } else { false }
 337 }
 338 #[no_mangle]
 339 /// Serialize the BlindedPayInfo object into a byte array which can be read by BlindedPayInfo_read
 340 pub extern "C" fn BlindedPayInfo_write(obj: &crate::lightning::offers::invoice::BlindedPayInfo) -> crate::c_types::derived::CVec_u8Z {
 341         crate::c_types::serialize_obj(unsafe { &*obj }.get_native_ref())
 342 }
 343 #[no_mangle]
 344 pub(crate) extern "C" fn BlindedPayInfo_write_void(obj: *const c_void) -> crate::c_types::derived::CVec_u8Z {
 345         crate::c_types::serialize_obj(unsafe { &*(obj as *const nativeBlindedPayInfo) })
 346 }
 347 #[no_mangle]
 348 /// Read a BlindedPayInfo from a byte array, created by BlindedPayInfo_write
 349 pub extern "C" fn BlindedPayInfo_read(ser: crate::c_types::u8slice) -> crate::c_types::derived::CResult_BlindedPayInfoDecodeErrorZ {
 350         let res: Result<lightning::offers::invoice::BlindedPayInfo, lightning::ln::msgs::DecodeError> = crate::c_types::deserialize_obj(ser);
 351         let mut local_res = match res { Ok(mut o) => crate::c_types::CResultTempl::ok( { crate::lightning::offers::invoice::BlindedPayInfo { inner: ObjOps::heap_alloc(o), is_owned: true } }).into(), Err(mut e) => crate::c_types::CResultTempl::err( { crate::lightning::ln::msgs::DecodeError::native_into(e) }).into() };
 352         local_res
 353 }