f - rename some Bolt12Invoice methods and clarify docs

Author: jkczyz

lightning/src/offers/invoice.rs

@@ -487,14 +487,16 @@ macro_rules! invoice_accessors { ($self: ident, $contents: expr) => {
 	/// From [`Offer::chains`]; `None` if the invoice was created in response to a [`Refund`].
 	///
 	/// [`Offer::chains`]: crate::offers::offer::Offer::chains
-	pub fn chains(&$self) -> Option<Vec<ChainHash>> {
-		$contents.chains()
+	pub fn offer_chains(&$self) -> Option<Vec<ChainHash>> {
+		$contents.offer_chains()
 	}
 
-	/// A chain that the originating offer or refund is valid for.
+	/// The chain that must be used when paying the invoice; selected from [`offer_chains`] if the
+	/// invoice originated from an offer.
 	///
 	/// From [`InvoiceRequest::chain`] or [`Refund::chain`].
 	///
+	/// [`offer_chains`]: Self::offer_chains
 	/// [`InvoiceRequest::chain`]: crate::offers::invoice_request::InvoiceRequest::chain
 	pub fn chain(&$self) -> ChainHash {
 		$contents.chain()
@@ -565,8 +567,8 @@ macro_rules! invoice_accessors { ($self: ident, $contents: expr) => {
 	/// From [`Offer::paths`] or [`Refund::paths`].
 	///
 	/// [`Offer::paths`]: crate::offers::offer::Offer::paths
-	pub fn paths(&$self) -> &[BlindedPath] {
-		$contents.paths()
+	pub fn message_paths(&$self) -> &[BlindedPath] {
+		$contents.message_paths()
 	}
 
 	/// The quantity of items supported.
@@ -601,9 +603,9 @@ macro_rules! invoice_accessors { ($self: ident, $contents: expr) => {
 	}
 
 	/// A possibly transient pubkey used to sign the invoice request or to send an invoice for a
-	/// refund in case there are no [`paths`].
+	/// refund in case there are no [`message_paths`].
 	///
-	/// [`paths`]: Self::paths
+	/// [`message_paths`]: Self::message_paths
 	pub fn payer_id(&$self) -> PublicKey {
 		$contents.payer_id()
 	}
@@ -718,7 +720,7 @@ impl InvoiceContents {
 		}
 	}
 
-	fn chains(&self) -> Option<Vec<ChainHash>> {
+	fn offer_chains(&self) -> Option<Vec<ChainHash>> {
 		match self {
 			InvoiceContents::ForOffer { invoice_request, .. } =>
 				Some(invoice_request.inner.offer.chains()),
@@ -785,7 +787,7 @@ impl InvoiceContents {
 		}
 	}
 
-	fn paths(&self) -> &[BlindedPath] {
+	fn message_paths(&self) -> &[BlindedPath] {
 		match self {
 			InvoiceContents::ForOffer { invoice_request, .. } => {
 				invoice_request.inner.offer.paths()
@@ -1330,13 +1332,13 @@ mod tests {
 
 		assert_eq!(unsigned_invoice.bytes, buffer.as_slice());
 		assert_eq!(unsigned_invoice.payer_metadata(), &[1; 32]);
-		assert_eq!(unsigned_invoice.chains(), Some(vec![ChainHash::using_genesis_block(Network::Bitcoin)]));
+		assert_eq!(unsigned_invoice.offer_chains(), Some(vec![ChainHash::using_genesis_block(Network::Bitcoin)]));
 		assert_eq!(unsigned_invoice.metadata(), None);
 		assert_eq!(unsigned_invoice.amount(), Some(&Amount::Bitcoin { amount_msats: 1000 }));
 		assert_eq!(unsigned_invoice.description(), PrintableString("foo"));
 		assert_eq!(unsigned_invoice.offer_features(), Some(&OfferFeatures::empty()));
 		assert_eq!(unsigned_invoice.absolute_expiry(), None);
-		assert_eq!(unsigned_invoice.paths(), &[]);
+		assert_eq!(unsigned_invoice.message_paths(), &[]);
 		assert_eq!(unsigned_invoice.issuer(), None);
 		assert_eq!(unsigned_invoice.supported_quantity(), Some(Quantity::One));
 		assert_eq!(unsigned_invoice.signing_pubkey(), recipient_pubkey());
@@ -1372,13 +1374,13 @@ mod tests {
 
 		assert_eq!(invoice.bytes, buffer.as_slice());
 		assert_eq!(invoice.payer_metadata(), &[1; 32]);
-		assert_eq!(invoice.chains(), Some(vec![ChainHash::using_genesis_block(Network::Bitcoin)]));
+		assert_eq!(invoice.offer_chains(), Some(vec![ChainHash::using_genesis_block(Network::Bitcoin)]));
 		assert_eq!(invoice.metadata(), None);
 		assert_eq!(invoice.amount(), Some(&Amount::Bitcoin { amount_msats: 1000 }));
 		assert_eq!(invoice.description(), PrintableString("foo"));
 		assert_eq!(invoice.offer_features(), Some(&OfferFeatures::empty()));
 		assert_eq!(invoice.absolute_expiry(), None);
-		assert_eq!(invoice.paths(), &[]);
+		assert_eq!(invoice.message_paths(), &[]);
 		assert_eq!(invoice.issuer(), None);
 		assert_eq!(invoice.supported_quantity(), Some(Quantity::One));
 		assert_eq!(invoice.signing_pubkey(), recipient_pubkey());
@@ -1471,13 +1473,13 @@ mod tests {
 
 		assert_eq!(invoice.bytes, buffer.as_slice());
 		assert_eq!(invoice.payer_metadata(), &[1; 32]);
-		assert_eq!(invoice.chains(), None);
+		assert_eq!(invoice.offer_chains(), None);
 		assert_eq!(invoice.metadata(), None);
 		assert_eq!(invoice.amount(), None);
 		assert_eq!(invoice.description(), PrintableString("foo"));
 		assert_eq!(invoice.offer_features(), None);
 		assert_eq!(invoice.absolute_expiry(), None);
-		assert_eq!(invoice.paths(), &[]);
+		assert_eq!(invoice.message_paths(), &[]);
 		assert_eq!(invoice.issuer(), None);
 		assert_eq!(invoice.supported_quantity(), None);
 		assert_eq!(invoice.signing_pubkey(), recipient_pubkey());