Expand invoice module docs and include an example

[rust-lightning] / lightning / src / offers / invoice_request.rs

diff --git a/lightning/src/offers/invoice_request.rs b/lightning/src/offers/invoice_request.rs
index 21c11bcbfc6b2429b078807e5b8682fe02667f8a..4185c95ded90c278e71f645a27d96fb9402d3fa9 100644 (file)
--- a/lightning/src/offers/invoice_request.rs
+++ b/lightning/src/offers/invoice_request.rs
@@ -58,12 +58,15 @@ use bitcoin::secp256k1::{Message, PublicKey};
 use bitcoin::secp256k1::schnorr::Signature;
 use core::convert::TryFrom;
 use crate::io;
+use crate::ln::PaymentHash;
 use crate::ln::features::InvoiceRequestFeatures;
 use crate::ln::msgs::DecodeError;
+use crate::offers::invoice::{BlindedPayInfo, InvoiceBuilder};
 use crate::offers::merkle::{SignError, SignatureTlvStream, SignatureTlvStreamRef, self};
 use crate::offers::offer::{Offer, OfferContents, OfferTlvStream, OfferTlvStreamRef};
 use crate::offers::parse::{ParseError, ParsedMessage, SemanticError};
 use crate::offers::payer::{PayerContents, PayerTlvStream, PayerTlvStreamRef};
+use crate::onion_message::BlindedPath;
 use crate::util::ser::{HighZeroBytesDroppedBigSize, SeekReadable, WithoutLength, Writeable, Writer};
 use crate::util::string::PrintableString;
 
@@ -250,7 +253,7 @@ impl<'a> UnsignedInvoiceRequest<'a> {
 #[derive(Clone, Debug)]
 pub struct InvoiceRequest {
        pub(super) bytes: Vec<u8>,
-       contents: InvoiceRequestContents,
+       pub(super) contents: InvoiceRequestContents,
        signature: Signature,
 }
 
@@ -319,6 +322,41 @@ impl InvoiceRequest {
                self.signature
        }
 
+       /// Creates an [`Invoice`] for the request with the given required fields.
+       ///
+       /// Unless [`InvoiceBuilder::relative_expiry`] is set, the invoice will expire two hours after
+       /// calling this method in `std` builds. For `no-std` builds, a final [`Duration`] parameter
+       /// must be given, which is used to set [`Invoice::created_at`] since [`std::time::SystemTime`]
+       /// is not available.
+       ///
+       /// The caller is expected to remember the preimage of `payment_hash` in order to claim a payment
+       /// for the invoice.
+       ///
+       /// The `payment_paths` parameter is useful for maintaining the payment recipient's privacy. It
+       /// must contain one or more elements.
+       ///
+       /// Errors if the request contains unknown required features.
+       ///
+       /// [`Duration`]: core::time::Duration
+       /// [`Invoice`]: crate::offers::invoice::Invoice
+       /// [`Invoice::created_at`]: crate::offers::invoice::Invoice::created_at
+       pub fn respond_with(
+               &self, payment_paths: Vec<(BlindedPath, BlindedPayInfo)>, payment_hash: PaymentHash,
+               #[cfg(not(feature = "std"))]
+               created_at: core::time::Duration
+       ) -> Result<InvoiceBuilder, SemanticError> {
+               if self.features().requires_unknown_bits() {
+                       return Err(SemanticError::UnknownRequiredFeatures);
+               }
+
+               #[cfg(feature = "std")]
+               let created_at = std::time::SystemTime::now()
+                       .duration_since(std::time::SystemTime::UNIX_EPOCH)
+                       .expect("SystemTime::now() should come after SystemTime::UNIX_EPOCH");
+
+               InvoiceBuilder::for_offer(self, payment_paths, created_at, payment_hash)
+       }
+
        #[cfg(test)]
        fn as_tlv_stream(&self) -> FullInvoiceRequestTlvStreamRef {
                let (payer_tlv_stream, offer_tlv_stream, invoice_request_tlv_stream) =