f - clean-up and comments

Author: jkczyz

lightning/src/ln/inbound_payment.rs

@@ -75,6 +75,9 @@ impl ExpandedKey {
 		hmac
 	}
 
+	/// Derives a pubkey using the given nonce for use as [`Offer::signing_pubkey`].
+	///
+	/// [`Offer::signing_pubkey`]: crate::offers::offer::Offer::signing_pubkey
 	pub(crate) fn signing_pubkey_for_offer(&self, nonce: Nonce) -> PublicKey {
 		let secp_ctx = Secp256k1::new();
 		let mut tweak = [0; 32];
@@ -88,23 +91,29 @@ impl ExpandedKey {
 	}
 }
 
+/// A 128-bit number used only once.
+///
+/// Needed when constructing [`Offer::metadata`] and deriving [`Offer::signing_pubkey`] from
+/// [`ExpandedKey`].
 ///
+/// [`Offer::metadata`]: crate::offers::offer::Offer::metadata
+/// [`Offer::signing_pubkey`]: crate::offers::offer::Offer::signing_pubkey
 #[derive(Clone, Copy)]
 pub struct Nonce(pub(crate) [u8; Self::LENGTH]);
 
 impl Nonce {
-	///
+	/// Number of bytes in the nonce.
 	pub const LENGTH: usize = 16;
 
-	///
+	/// Creates a `Nonce` from the given [`EntropySource`].
 	pub fn from_entropy_source<ES: EntropySource>(entropy_source: &ES) -> Self {
-		let mut bytes = [0 as u8; Self::LENGTH];
+		let mut bytes = [0u8; Self::LENGTH];
 		let rand_bytes = entropy_source.get_secure_random_bytes();
 		bytes.copy_from_slice(&rand_bytes[..Self::LENGTH]);
 		Nonce(bytes)
 	}
 
-	///
+	/// Returns a slice of the underlying bytes of size [`Nonce::LENGTH`].
 	pub fn as_slice(&self) -> &[u8] {
 		&self.0
 	}

lightning/src/offers/offer.rs

@@ -41,7 +41,7 @@
 //! let pubkey = PublicKey::from(keys);
 //!
 //! let expiration = SystemTime::now() + Duration::from_secs(24 * 60 * 60);
-//! let offer = OfferBuilder::new("coffee, large".to_string(), pubkey)
+//! let offer = OfferBuilder::new("coffee, large".to_string(), pubkey.into())
 //!     .amount_msats(20_000)
 //!     .supported_quantity(Quantity::Unbounded)
 //!     .absolute_expiry(expiration.duration_since(SystemTime::UNIX_EPOCH).unwrap())
@@ -92,19 +92,12 @@ use crate::prelude::*;
 #[cfg(feature = "std")]
 use std::time::SystemTime;
 
-/// Builds an [`Offer`] for the "offer to be paid" flow.
-///
-/// See [module-level documentation] for usage.
-///
-/// [module-level documentation]: self
-pub struct OfferBuilder {
-	offer: OfferContents,
-	metadata_material: Option<(Nonce, HmacEngine<Sha256>)>,
-}
-
-///
+/// A pubkey for signing invoices, either given explicitly or derived.
 pub enum SigningPubkey<'a> {
+	/// A pubkey that is typically known like a node id.
 	Explicit(PublicKey),
+
+	/// Data needed to derive a pubkey.
 	Derived(&'a ExpandedKey, Nonce),
 }
 
@@ -114,6 +107,16 @@ impl<'a> From<PublicKey> for SigningPubkey<'a> {
 	}
 }
 
+/// Builds an [`Offer`] for the "offer to be paid" flow.
+///
+/// See [module-level documentation] for usage.
+///
+/// [module-level documentation]: self
+pub struct OfferBuilder {
+	offer: OfferContents,
+	metadata_material: Option<(Nonce, HmacEngine<Sha256>)>,
+}
+
 impl OfferBuilder {
 	/// Creates a new builder for an offer setting the [`Offer::description`] and using the
 	/// [`Offer::signing_pubkey`] for signing invoices. The associated secret key must be remembered
@@ -250,7 +253,8 @@ impl OfferBuilder {
 			}
 		}
 
-		// Created the metadata for stateless verification.
+		// Create the metadata for stateless verification. It consists of a 16-byte nonce and a
+		// 32-byte HMAC of the offer bytes excluding the signing pubkey.
 		if let Some((nonce, mut hmac)) = self.metadata_material {
 			debug_assert!(self.offer.metadata.is_none());
 			let mut tlv_stream = self.offer.as_tlv_stream();