Expand invoice module docs and include an example

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

diff --git a/lightning/src/offers/refund.rs b/lightning/src/offers/refund.rs
index fdf763ecb952653dfadea965a5978fe5dd8e841e..48be9774aec2f7bc5e220db29935654119c3e9b0 100644 (file)
--- a/lightning/src/offers/refund.rs
+++ b/lightning/src/offers/refund.rs
@@ -78,8 +78,10 @@ use core::convert::TryFrom;
 use core::str::FromStr;
 use core::time::Duration;
 use crate::io;
+use crate::ln::PaymentHash;
 use crate::ln::features::InvoiceRequestFeatures;
 use crate::ln::msgs::{DecodeError, MAX_VALUE_MSAT};
+use crate::offers::invoice::{BlindedPayInfo, InvoiceBuilder};
 use crate::offers::invoice_request::{InvoiceRequestTlvStream, InvoiceRequestTlvStreamRef};
 use crate::offers::offer::{OfferTlvStream, OfferTlvStreamRef};
 use crate::offers::parse::{Bech32Encode, ParseError, ParsedMessage, SemanticError};
@@ -202,8 +204,8 @@ impl RefundBuilder {
 /// [`Offer`]: crate::offers::offer::Offer
 #[derive(Clone, Debug)]
 pub struct Refund {
-       bytes: Vec<u8>,
-       contents: RefundContents,
+       pub(super) bytes: Vec<u8>,
+       pub(super) contents: RefundContents,
 }
 
 /// The contents of a [`Refund`], which may be shared with an [`Invoice`].
@@ -296,6 +298,44 @@ impl Refund {
                self.contents.payer_note.as_ref().map(|payer_note| PrintableString(payer_note.as_str()))
        }
 
+       /// Creates an [`Invoice`] for the refund 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 `signing_pubkey` is required to sign the invoice since refunds are not in response to an
+       /// offer, which does have a `signing_pubkey`.
+       ///
+       /// 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.
+       ///
+       /// [`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,
+               signing_pubkey: PublicKey,
+               #[cfg(not(feature = "std"))]
+               created_at: 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_refund(self, payment_paths, created_at, payment_hash, signing_pubkey)
+       }
+
        #[cfg(test)]
        fn as_tlv_stream(&self) -> RefundTlvStreamRef {
                self.contents.as_tlv_stream()