_ Git - rust-lightning/blob - lightning/src/offers/invoice_request.rs

   1 // This file is Copyright its original authors, visible in version control
   2 // history.
   3 //
   4 // This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
   5 // or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   6 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
   7 // You may not use this file except in accordance with one or both of these
   8 // licenses.
   9
  10 //! Data structures and encoding for `invoice_request` messages.
  11
  12 use bitcoin::blockdata::constants::ChainHash;
  13 use bitcoin::secp256k1::PublicKey;
  14 use bitcoin::secp256k1::schnorr::Signature;
  15 use crate::ln::features::InvoiceRequestFeatures;
  16 use crate::offers::offer::OfferContents;
  17 use crate::offers::payer::PayerContents;
  18 use crate::util::string::PrintableString;
  19
  20 use crate::prelude::*;
  21
  22 /// An `InvoiceRequest` is a request for an `Invoice` formulated from an [`Offer`].
  23 ///
  24 /// An offer may provide choices such as quantity, amount, chain, features, etc. An invoice request
  25 /// specifies these such that its recipient can send an invoice for payment.
  26 ///
  27 /// [`Offer`]: crate::offers::offer::Offer
  28 #[derive(Clone, Debug)]
  29 pub struct InvoiceRequest {
  30         bytes: Vec<u8>,
  31         contents: InvoiceRequestContents,
  32         signature: Option<Signature>,
  33 }
  34
  35 /// The contents of an [`InvoiceRequest`], which may be shared with an `Invoice`.
  36 #[derive(Clone, Debug)]
  37 pub(crate) struct InvoiceRequestContents {
  38         payer: PayerContents,
  39         offer: OfferContents,
  40         chain: Option<ChainHash>,
  41         amount_msats: Option<u64>,
  42         features: InvoiceRequestFeatures,
  43         quantity: Option<u64>,
  44         payer_id: PublicKey,
  45         payer_note: Option<String>,
  46 }
  47
  48 impl InvoiceRequest {
  49         /// An unpredictable series of bytes, typically containing information about the derivation of
  50         /// [`payer_id`].
  51         ///
  52         /// [`payer_id`]: Self::payer_id
  53         pub fn metadata(&self) -> &[u8] {
  54                 &self.contents.payer.0[..]
  55         }
  56
  57         /// A chain from [`Offer::chains`] that the offer is valid for.
  58         ///
  59         /// [`Offer::chains`]: crate::offers::offer::Offer::chains
  60         pub fn chain(&self) -> ChainHash {
  61                 self.contents.chain.unwrap_or_else(|| self.contents.offer.implied_chain())
  62         }
  63
  64         /// The amount to pay in msats (i.e., the minimum lightning-payable unit for [`chain`]), which
  65         /// must be greater than or equal to [`Offer::amount`], converted if necessary.
  66         ///
  67         /// [`chain`]: Self::chain
  68         /// [`Offer::amount`]: crate::offers::offer::Offer::amount
  69         pub fn amount_msats(&self) -> Option<u64> {
  70                 self.contents.amount_msats
  71         }
  72
  73         /// Features for paying the invoice.
  74         pub fn features(&self) -> &InvoiceRequestFeatures {
  75                 &self.contents.features
  76         }
  77
  78         /// The quantity of the offer's item conforming to [`Offer::supported_quantity`].
  79         ///
  80         /// [`Offer::supported_quantity`]: crate::offers::offer::Offer::supported_quantity
  81         pub fn quantity(&self) -> Option<u64> {
  82                 self.contents.quantity
  83         }
  84
  85         /// A possibly transient pubkey used to sign the invoice request.
  86         pub fn payer_id(&self) -> PublicKey {
  87                 self.contents.payer_id
  88         }
  89
  90         /// Payer provided note to include in the invoice.
  91         pub fn payer_note(&self) -> Option<PrintableString> {
  92                 self.contents.payer_note.as_ref().map(|payer_note| PrintableString(payer_note.as_str()))
  93         }
  94
  95         /// Signature of the invoice request using [`payer_id`].
  96         ///
  97         /// [`payer_id`]: Self::payer_id
  98         pub fn signature(&self) -> Option<Signature> {
  99                 self.signature
 100         }
 101 }