From 3942efdd2ce1ab8911fb0b2c3feb9e5076ece1f7 Mon Sep 17 00:00:00 2001 From: Jeffrey Czyz Date: Mon, 26 Sep 2022 15:52:27 -0500 Subject: [PATCH] f - expand Offer docs --- lightning/src/offers/offer.rs | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/lightning/src/offers/offer.rs b/lightning/src/offers/offer.rs index ec22528b..847bafd6 100644 --- a/lightning/src/offers/offer.rs +++ b/lightning/src/offers/offer.rs @@ -24,8 +24,11 @@ use std::time::SystemTime; /// An `Offer` is a potentially long-lived proposal for payment of a good or service. /// /// An offer is precursor to an `InvoiceRequest`. A merchant publishes an offer from which a -/// customer may request an `Invoice` for a specific quantity and using a specific amount. Offers -/// may be denominated in currency other than bitcoin but are ultimately paid using the latter. +/// customer may request an `Invoice` for a specific quantity and using an amount enough to cover +/// that quantity (i.e., at least `quantity * amount`). See [`Offer::amount`]. +/// +/// Offers may be denominated in currency other than bitcoin but are ultimately paid using the +/// latter. /// /// Through the use of [`BlindedPath`]s, offers provide recipient privacy. #[derive(Clone, Debug)] @@ -64,12 +67,14 @@ impl Offer { .unwrap_or_else(|| vec![ChainHash::using_genesis_block(Network::Bitcoin)]) } - /// Metadata set by the originator. Useful for authentication and validating fields. + // TODO: Link to corresponding method in `InvoiceRequest`. + /// Metadata set by the originator. Useful for authentication and validating fields since it is + /// reflected in `invoice_request` messages along with all the other fields from the `offer`. pub fn metadata(&self) -> Option<&Vec> { self.contents.metadata.as_ref() } - /// The minimum amount required for a successful payment. + /// The minimum amount required for a successful payment of a single item. pub fn amount(&self) -> Option<&Amount> { self.contents.amount.as_ref() } @@ -79,7 +84,7 @@ impl Offer { &self.contents.description } - /// Features for paying the invoice. + /// Features pertaining to the offer. pub fn features(&self) -> &OfferFeatures { &self.contents.features } @@ -103,12 +108,14 @@ impl Offer { } } - /// The issuer of the offer, possibly beginning with `user@domain` or `domain`. + /// The issuer of the offer, possibly beginning with `user@domain` or `domain`. Intended to be + /// displayed to the user, so should be human-readable. pub fn issuer(&self) -> Option<&str> { self.contents.issuer.as_ref().map(|issuer| issuer.as_str()) } - /// Paths to the recipient originating from publicly reachable nodes. + /// Paths to the recipient originating from publicly reachable nodes. Blinded paths provide + /// recipient privacy by obfuscating its node id. pub fn paths(&self) -> &[BlindedPath] { self.contents.paths.as_ref().map(|paths| paths.as_slice()).unwrap_or(&[]) } -- 2.30.2