offer: make the merkle tree signature public

[vincenzopalazzo]

This is helpful for users who want to use the Merkle tree signature in their own code, for example, to verify the signature of bolt12 invoices or recreate it.

Very useful for people who are building command line tools for the bolt12 offers.

I am opening this, but I do not know if it is something that you want to do, but at the same time, IMHO, this is very useful to expose because it allows to use LDK in command line tools and in learning tools.

However, this is not strictly necessary because Bolt12Invoice::try_from already verifies the signature, but I would open this to know your point of view.

[ldk-reviews-bot]

👋 Thanks for assigning @valentinewallace as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

[dunxen]

I'm not personally opposed to this and it may be nice to expose it for the use cases you mention.
However, maybe the doc comments for these should be updated to indicate that these don't need to be used directly and they're really for internal use, but made public for use in applications like you specified. We should redirect them to the appropriate methods for production use.

I'm also not sure about any API guarantees for these methods. I don't think it's too much of a hassle to treat them the same way we treat any other public API.

[codecov]

Codecov Report

Attention: Patch coverage is 90.00000% with 10 lines in your changes missing coverage. Please review.

Project coverage is 88.80%. Comparing base (0fe51c5) to head (285a45c).
Report is 46 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/offers/merkle.rs	90.00%	9 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3892      +/-   ##
==========================================
- Coverage   89.66%   88.80%   -0.87%     
==========================================
  Files         164      165       +1     
  Lines      134661   119171   -15490     
  Branches   134661   119171   -15490     
==========================================
- Hits       120743   105826   -14917     
+ Misses      11237    11016     -221     
+ Partials     2681     2329     -352     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[valentinewallace]

Do we have a user for this? Feels pretty low-level to be exposing. Echo dunxen's sentiments about improving the docs if we do want to expose it.

[TheBlueMatt]

Yea, if we're gonna expose this we should really add a validating wrapper version that checks the stream is valid and can Err instead of panicking.

[vincenzopalazzo]

Do we have a user for this? Feels pretty low-level to be exposing.

Yeah, there is. Everyone who wants to verify that an offer is linked to a bolt12 invoice, also if the big picture is that the bolt12 invoice will never be exposed, but for now that we do not have a better PoP a person should allow this kind of verification IMHO

A possible example of verification can be

/// Verify that an offer, invoice, and preimage are valid and consistent
pub fn verify_offer_payment(offer: &str, invoice: &str, preimage: &str) -> Result<()> {
    log::info!("Starting verification process...");
    log::info!("Offer: {}", offer);
    log::info!("Invoice: {}", invoice);
    log::info!("Preimage: {}", preimage);

    let offer =
        Offer::from_str(offer).map_err(|e| anyhow::anyhow!("Failed to parse offer: {:?}", e))?;

    // Parse the bolt12 invoice preimage
    let (hrp, data) = bech32::decode_without_checksum(invoice)?;
    if hrp.as_str() != "lni" {
        return Err(anyhow::anyhow!(
            "Invalid HRP: expected 'lni', found '{}'",
            hrp
        ));
    }

    let data = Vec::<u8>::from_base32(&data)?;

    let invoice = Bolt12Invoice::try_from(data)
        .map_err(|e| anyhow::anyhow!("Failed to parse BOLT12: {e:?}"))?;

    let issuer_sign_pubkey = if let Some(issue_sign_pubkey) = offer.issuer_signing_pubkey() {
        issue_sign_pubkey
    } else {
        let valid_signing_keys = offer
            .paths()
            .iter()
            .filter_map(|path| path.blinded_hops().last())
            .map(|hop| hop.blinded_node_id)
            .collect::<Vec<_>>();
        log::debug!("{:?}", valid_signing_keys);
        let valid_signing_keys = valid_signing_keys
            .first()
            .ok_or(anyhow::anyhow!(
                "Offer does not contain issuer signing pubkey"
            ))?
            .clone();
        valid_signing_keys
    };

    let inv_signing_pubkey = invoice.signing_pubkey();
    if issuer_sign_pubkey != inv_signing_pubkey {
        return Err(anyhow::anyhow!(
            "Offer and invoice issuer signing pubkeys do not match"
        ));
    }

    let mut bytes = vec![];
    invoice
        .write(&mut bytes)
        .map_err(|e| anyhow::anyhow!("Failed to serialize invoice: {:?}", e))?;
    let tagged_hash = TaggedHash::from_valid_tlv_stream_bytes(SIGNATURE_TAG, &bytes);
    if let Err(err) =
        merkle::verify_signature(&invoice.signature(), &tagged_hash, issuer_sign_pubkey)
    {
        anyhow::bail!("Failed to verify invoice signature: {:?}", err);
    }

    let preimage =
        hex::decode(preimage).map_err(|e| anyhow::anyhow!("Failed to decode preimage: {:?}", e))?;
    let preimage: [u8; 32] = preimage
        .try_into()
        .map_err(|_| anyhow::anyhow!("Preimage must be 32 bytes"))?;
    let preimage = PaymentPreimage(preimage);
    // Validate the Proof of Payment for the invoice
    let computed_hash = PaymentHash::from(preimage);
    let payment_hash = invoice.payment_hash();

    if computed_hash != payment_hash {
        anyhow::bail!("Fail to perform PoP");
    }

    log::info!("Parsed offer: {:?}", offer);
    log::info!("Parsed invoice: {:?}", invoice);
    Ok(())
}

[ldk-reviews-bot]

👋 The first review has been submitted!

Do you think this PR is ready for a second reviewer? If so, click here to assign a second reviewer.

[graphite-app]

The TLV stream validation implementation is missing a critical requirement from the Lightning Network specification: TLV records must appear in ascending order by type.

To ensure full compliance, consider tracking the previous type value during iteration and verifying that each new type is greater than the previous one:

let mut previous_type: Option<u64> = None;

while cursor.position() < bytes.len() as u64 {
    // Try to read type
    let type_result = <BigSize as Readable>::read(&mut cursor);
    if type_result.is_err() {
        return Err(TlvStreamError::InvalidRecord);
    }
    
    let current_type = type_result.unwrap().0;
    
    // Check ascending order
    if let Some(prev) = previous_type {
        if current_type <= prev {
            return Err(TlvStreamError::InvalidOrder);
        }
    }
    
    previous_type = Some(current_type);
    
    // Rest of the validation...
}

This would require adding an InvalidOrder variant to the TlvStreamError enum.

Suggested change

	pub fn from_tlv_stream_bytes(tag: &'static str, bytes: &[u8]) -> Result<Self, TlvStreamError> {
	// Validate the TLV stream first
	if bytes.is_empty() {
	return Err(TlvStreamError::EmptyStream);
	}
	// Try to parse the TLV stream to check validity
	let mut cursor = io::Cursor::new(bytes);
	let mut has_records = false;
	while cursor.position() < bytes.len() as u64 {
	// Try to read type
	let type_result = <BigSize as Readable>::read(&mut cursor);
	if type_result.is_err() {
	return Err(TlvStreamError::InvalidRecord);
	}
	// Try to read length
	let length_result = <BigSize as Readable>::read(&mut cursor);
	if length_result.is_err() {
	return Err(TlvStreamError::InvalidRecord);
	}
	let length = length_result.unwrap().0;
	let end_position = cursor.position() + length;
	// Check if the record extends beyond the buffer
	if end_position > bytes.len() as u64 {
	return Err(TlvStreamError::InvalidRecord);
	}
	// Skip the value
	cursor.set_position(end_position);
	has_records = true;
	}
	if !has_records {
	return Err(TlvStreamError::EmptyStream);
	}
	// If validation passes, create the tagged hash
	Ok(Self::from_valid_tlv_stream_bytes(tag, bytes))
	pub fn from_tlv_stream_bytes(tag: &'static str, bytes: &[u8]) -> Result<Self, TlvStreamError> {
	// Validate the TLV stream first
	if bytes.is_empty() {
	return Err(TlvStreamError::EmptyStream);
	}
	// Try to parse the TLV stream to check validity
	let mut cursor = io::Cursor::new(bytes);
	let mut has_records = false;
	let mut previous_type: Option<u64> = None;
	while cursor.position() < bytes.len() as u64 {
	// Try to read type
	let type_result = <BigSize as Readable>::read(&mut cursor);
	if type_result.is_err() {
	return Err(TlvStreamError::InvalidRecord);
	}
	let current_type = type_result.unwrap().0;
	// Check ascending order
	if let Some(prev) = previous_type {
	if current_type <= prev {
	return Err(TlvStreamError::InvalidOrder);
	}
	}
	previous_type = Some(current_type);
	// Try to read length
	let length_result = <BigSize as Readable>::read(&mut cursor);
	if length_result.is_err() {
	return Err(TlvStreamError::InvalidRecord);
	}
	let length = length_result.unwrap().0;
	let end_position = cursor.position() + length;
	// Check if the record extends beyond the buffer
	if end_position > bytes.len() as u64 {
	return Err(TlvStreamError::InvalidRecord);
	}
	// Skip the value
	cursor.set_position(end_position);
	has_records = true;
	}
	if !has_records {
	return Err(TlvStreamError::EmptyStream);
	}
	// If validation passes, create the tagged hash
	Ok(Self::from_valid_tlv_stream_bytes(tag, bytes))

Spotted by Diamond

Is this helpful? React 👍 or 👎 to let us know.