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, TaggedHash, TlvStream, WithoutSignatures, self};
+use crate::offers::merkle::{SignError, SignFunction, SignatureTlvStream, SignatureTlvStreamRef, TaggedHash, TlvStream, WithoutSignatures, self};
 use crate::offers::offer::{Amount, OFFER_TYPES, OfferTlvStream, OfferTlvStreamRef};
 use crate::offers::parse::{Bolt12ParseError, Bolt12SemanticError, ParsedMessage};
 use crate::offers::payer::{PAYER_METADATA_TYPE, PayerTlvStream, PayerTlvStreamRef};
@@ -383,10 +383,7 @@ impl<'a> UnsignedBolt12Invoice<'a> {
 	/// Signs the invoice using the given function.
 	///
 	/// This is not exported to bindings users as functions aren't currently mapped.
-	pub fn sign<F, E>(self, sign: F) -> Result<Bolt12Invoice, SignError<E>>
-	where
-		F: FnOnce(&TaggedHash, &[u8]) -> Result<Signature, E>
-	{
+	pub fn sign<F: SignFunction<E>, E>(self, sign: F) -> Result<Bolt12Invoice, SignError<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
 		// `RefundContents`.

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, TaggedHash, self};
+use crate::offers::merkle::{SignError, SignFunction, SignatureTlvStream, SignatureTlvStreamRef, TaggedHash, self};
 use crate::offers::offer::{Offer, OfferContents, OfferTlvStream, OfferTlvStreamRef};
 use crate::offers::parse::{Bolt12ParseError, ParsedMessage, Bolt12SemanticError};
 use crate::offers::payer::{PayerContents, PayerTlvStream, PayerTlvStreamRef};
@@ -353,10 +353,7 @@ impl<'a> UnsignedInvoiceRequest<'a> {
 	/// Signs the invoice request using the given function.
 	///
 	/// 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(&TaggedHash, &[u8]) -> Result<Signature, E>
-	{
+	pub fn sign<F: SignFunction<E>, E>(self, sign: F) -> Result<InvoiceRequest, SignError<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`.
 		let (payer_tlv_stream, _offer_tlv_stream, invoice_request_tlv_stream) =

lightning/src/offers/merkle.rs

@@ -25,13 +25,23 @@ tlv_stream!(SignatureTlvStream, SignatureTlvStreamRef, SIGNATURE_TYPES, {
 	(240, signature: Signature),
 });
 
+/// A function for signing a [`Message`] digest produced from the given [`TaggedHash`]. See
+/// [`TaggedHash`] 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(&TaggedHash, &[u8]) -> Result<Signature, E> {}
+
+impl<F, E> SignFunction<E> for F where F: FnOnce(&TaggedHash, &[u8]) -> Result<Signature, E> {}
+
 /// A hash for use in a specific context by tweaking with a context-dependent tag as per [BIP 340]
 /// and computed over the merkle root of a TLV stream to sign as defined in [BOLT 12].
 ///
 /// The hash is computed lazily from the TLV stream.
 ///
 /// [BIP 340]: https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki
 /// [BOLT 12]: https://github.com/rustyrussell/lightning-rfc/blob/guilt/offers/12-offer-encoding.md#signature-calculation
+/// Bytes associated with a tag, which are used to produced a [`Message`] digest to sign.
 pub struct TaggedHash<'a> {
 	/// Tag used for the hash function as defined in BOLT 12. Typically, either
 	/// [`invoice_request::SIGNATURE_TAG`] or [`invoice::SIGNATURE_TAG`].
@@ -76,12 +86,9 @@ pub enum SignError<E> {
 ///
 /// Panics if the underlying TLV stream of `message` is not a well-formed TLV stream containing at
 /// least one TLV record.
-pub(super) fn sign_message<F, E>(
+pub(super) fn sign_message<F: SignFunction<E>, E>(
 	sign: F, message: TaggedHash, metadata: &[u8], pubkey: PublicKey,
-) -> Result<Signature, SignError<E>>
-where
-	F: FnOnce(&TaggedHash, &[u8]) -> Result<Signature, E>
-{
+) -> Result<Signature, SignError<E>> {
 	let signature = sign(&message, metadata).map_err(|e| SignError::Signing(e))?;
 
 	let pubkey = pubkey.into();