f - docs about unknown, odd TLV records

Author: jkczyz

lightning/src/offers/invoice.rs

@@ -368,6 +368,11 @@ impl<'a> InvoiceBuilder<'a, DerivedSigningPubkey> {
 }
 
 /// A semantically valid [`Bolt12Invoice`] that hasn't been signed.
+///
+/// # Serialization
+///
+/// This is serialized as a TLV stream, which includes TLV records from the originating message. As
+/// such, it may include unknown, odd TLV records.
 pub struct UnsignedBolt12Invoice {
 	bytes: Vec<u8>,
 	contents: InvoiceContents,
@@ -396,7 +401,9 @@ impl UnsignedBolt12Invoice {
 		self.contents.fields().signing_pubkey
 	}
 
-	/// Signs the invoice using the given function.
+	/// Signs the [`TaggedHash`] of the invoice using the given function.
+	///
+	/// Note: The hash computation may have included unknown, odd TLV records.
 	///
 	/// This is not exported to bindings users as functions aren't currently mapped.
 	pub fn sign<F, E>(mut self, sign: F) -> Result<Bolt12Invoice, SignError<E>>

lightning/src/offers/invoice_request.rs

@@ -344,6 +344,11 @@ impl<'a, 'b, P: PayerIdStrategy, T: secp256k1::Signing> InvoiceRequestBuilder<'a
 }
 
 /// A semantically valid [`InvoiceRequest`] that hasn't been signed.
+///
+/// # Serialization
+///
+/// This is serialized as a TLV stream, which includes TLV records from the originating message. As
+/// such, it may include unknown, odd TLV records.
 pub struct UnsignedInvoiceRequest {
 	bytes: Vec<u8>,
 	contents: InvoiceRequestContents,
@@ -367,7 +372,9 @@ impl UnsignedInvoiceRequest {
 		Self { bytes, contents, tagged_hash }
 	}
 
-	/// Signs the invoice request using the given function.
+	/// Signs the [`TaggedHash`] of the invoice request using the given function.
+	///
+	/// Note: The hash computation may have included unknown, odd TLV records.
 	///
 	/// This is not exported to bindings users as functions are not yet mapped.
 	pub fn sign<F, E>(mut self, sign: F) -> Result<InvoiceRequest, SignError<E>>