Add SignFunction trait to document parameters

Author: jkczyz

lightning/src/offers/invoice.rs

@@ -110,7 +110,7 @@ use crate::ln::features::{BlindedHopFeatures, Bolt12InvoiceFeatures};
 use crate::ln::inbound_payment::ExpandedKey;
 use crate::ln::msgs::DecodeError;
 use crate::offers::invoice_request::{INVOICE_REQUEST_PAYER_ID_TYPE, INVOICE_REQUEST_TYPES, IV_BYTES as INVOICE_REQUEST_IV_BYTES, InvoiceRequest, InvoiceRequestContents, InvoiceRequestTlvStream, InvoiceRequestTlvStreamRef};
-use crate::offers::merkle::{SignError, SignatureTlvStream, SignatureTlvStreamRef, TaggedBytes, TlvStream, WithoutSignatures, self};
+use crate::offers::merkle::{SignError, SignFunction, SignatureTlvStream, SignatureTlvStreamRef, TaggedBytes, TlvStream, WithoutSignatures, self};
 use crate::offers::offer::{Amount, OFFER_TYPES, OfferTlvStream, OfferTlvStreamRef};
 use crate::offers::parse::{ParseError, ParsedMessage, SemanticError};
 use crate::offers::payer::{PAYER_METADATA_TYPE, PayerTlvStream, PayerTlvStreamRef};
@@ -383,7 +383,7 @@ impl<'a> UnsignedInvoice<'a> {
 	/// This is not exported to bindings users as functions aren't currently mapped.
 	pub fn sign<F, E>(self, sign: F) -> Result<Invoice, SignError<E>>
 	where
-		F: FnOnce(&TaggedBytes, &[u8]) -> Result<Signature, E>
+		F: SignFunction<E>
 	{
 		// Use the invoice_request bytes instead of the invoice_request TLV stream as the latter may
 		// have contained unknown TLV records, which are not stored in `InvoiceRequestContents` or

lightning/src/offers/invoice_request.rs

@@ -66,7 +66,7 @@ use crate::ln::features::InvoiceRequestFeatures;
 use crate::ln::inbound_payment::{ExpandedKey, IV_LEN, Nonce};
 use crate::ln::msgs::DecodeError;
 use crate::offers::invoice::{BlindedPayInfo, DerivedSigningPubkey, ExplicitSigningPubkey, InvoiceBuilder};
-use crate::offers::merkle::{SignError, SignatureTlvStream, SignatureTlvStreamRef, TaggedBytes, self};
+use crate::offers::merkle::{SignError, SignFunction, SignatureTlvStream, SignatureTlvStreamRef, TaggedBytes, self};
 use crate::offers::offer::{Offer, OfferContents, OfferTlvStream, OfferTlvStreamRef};
 use crate::offers::parse::{ParseError, ParsedMessage, SemanticError};
 use crate::offers::payer::{PayerContents, PayerTlvStream, PayerTlvStreamRef};
@@ -354,7 +354,7 @@ impl<'a> UnsignedInvoiceRequest<'a> {
 	/// This is not exported to bindings users as functions are not yet mapped.
 	pub fn sign<F, E>(self, sign: F) -> Result<InvoiceRequest, SignError<E>>
 	where
-		F: FnOnce(&TaggedBytes, &[u8]) -> Result<Signature, E>
+		F: SignFunction<E>
 	{
 		// Use the offer bytes instead of the offer TLV stream as the offer may have contained
 		// unknown TLV records, which are not stored in `OfferContents`.

lightning/src/offers/merkle.rs

@@ -25,6 +25,15 @@ tlv_stream!(SignatureTlvStream, SignatureTlvStreamRef, SIGNATURE_TYPES, {
 	(240, signature: Signature),
 });
 
+/// A function for signing a [`Message`] digest produced from the given [`TaggedBytes`]. See
+/// [`TaggedBytes::digest`] for details.
+///
+/// The second parameter is either the payer or offer metadata, depending on the TLV stream
+/// represented by the first parameter, and may be useful in order to derive the signing keys.
+pub trait SignFunction<E>: FnOnce(&TaggedBytes, &[u8]) -> Result<Signature, E> {}
+
+impl<F, E> SignFunction<E> for F where F: FnOnce(&TaggedBytes, &[u8]) -> Result<Signature, E> {}
+
 /// Bytes associated with a tag, which are used to produced a [`Message`] digest to sign.
 pub struct TaggedBytes<'a> {
 	tag: &'a str,
@@ -38,7 +47,8 @@ impl<'a> TaggedBytes<'a> {
 		Self { tag, bytes, digest: RefCell::new(None) }
 	}
 
-	/// Returns the digest to sign.
+	/// Returns the digest to sign as defined in the BOLT 12 spec's "Signature Calculation" section.
+	/// (i.e., the tagged merkle root of a TLV stream).
 	pub fn digest(&self) -> Message {
 		*self.digest.borrow_mut().get_or_insert_with(|| message_digest(self.tag, self.bytes))
 	}
@@ -64,7 +74,7 @@ pub(super) fn sign_message<F, E>(
 	sign: F, message: TaggedBytes, metadata: &[u8], pubkey: PublicKey,
 ) -> Result<Signature, SignError<E>>
 where
-	F: FnOnce(&TaggedBytes, &[u8]) -> Result<Signature, E>
+	F: SignFunction<E>
 {
 	let signature = sign(&message, metadata).map_err(|e| SignError::Signing(e))?;