offer: make the merkle tree signature public #3892

vincenzopalazzo · 2025-06-26T10:30:20Z

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 · 2025-06-26T10:30:22Z

👋 Thanks for assigning @TheBlueMatt 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 · 2025-06-26T11:51:14Z

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 · 2025-06-26T15:08:45Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 88.95%. Comparing base (1d507f2) to head (93cf409).
Report is 130 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3892      +/-   ##
==========================================
- Coverage   89.00%   88.95%   -0.05%     
==========================================
  Files         166      168       +2     
  Lines      119990   122065    +2075     
  Branches   119990   122065    +2075     
==========================================
+ Hits       106798   108586    +1788     
- Misses      10770    11076     +306     
+ Partials     2422     2403      -19

Flag	Coverage Δ
fuzz	`?`
fuzzing	`22.69% <0.00%> (?)`
tests	`88.78% <100.00%> (?)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ 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.

lightning/src/offers/merkle.rs

ldk-reviews-bot · 2025-06-27T16:20:29Z

👋 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.

lightning/src/offers/merkle.rs

ldk-reviews-bot · 2025-07-07T10:48:01Z

🔔 1st Reminder

Hey @TheBlueMatt @valentinewallace! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-07T10:48:02Z

🔔 1st Reminder

Hey @TheBlueMatt @valentinewallace! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

vincenzopalazzo · 2025-07-07T17:18:52Z

cc @jkczyz

lightning/src/offers/invoice.rs

lightning/src/offers/merkle.rs

TheBlueMatt · 2025-07-09T01:06:27Z

Will take a look at this after @jkczyz's comments are addressed, assuming he thinks it needs a second reviewer at that point.

ldk-reviews-bot · 2025-07-09T10:49:03Z

🔔 2nd Reminder

Hey @valentinewallace! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

vincenzopalazzo · 2025-07-09T11:19:29Z

Ok, I pushed the change that @jkczyz requested, and now the PR is organised in two commits as follows:

bed3812 where expose the sign and verify method to verify manually an invoice signature, this is nice for people that are building command line tools and want to show how the signature verification is described inside the spec
-e60b87c38c043114642eda5499864c3c6898aa64 expose the offer_id inside the Bolt12Invoice that allows to compare it with the Offer to make sure that the invoice is linked with the Bolt12 one. This is useful for a sanity check, but requires trusting that the decoding of ldk will always verify the signature of the invoice

Let me know if you are fine with the commit divided in this way, or you prefer e60b87c

lightning/src/offers/invoice.rs

lightning/src/offers/offer.rs

lightning/src/offers/merkle.rs

lightning/src/offers/invoice.rs

vincenzopalazzo · 2025-07-11T08:40:44Z

lightning/src/offers/invoice.rs

+		let offer_id = match &contents {
+			InvoiceContents::ForOffer { .. } => Some(OfferId::from_valid_bolt12_tlv_stream(&bytes)),
+			InvoiceContents::ForRefund { .. } => None,
+		};
+		Self { bytes, experimental_bytes, contents, tagged_hash, offer_id }


@jkczyz do you think that we should add in OfferId a maybe_from_valid_bolt12_tlv_stream(&bytes) -> Option<OfferId> to include the refund case without duplicate the match here?

We'd need to take in the InvoiceContents then, too. Leaning towards not doing this for unsigned invoices after all. See next comment.

lightning/src/offers/static_invoice.rs

jkczyz · 2025-07-11T14:12:21Z

lightning/src/offers/invoice.rs

+		let offer_id = match &contents {
+			InvoiceContents::ForOffer { .. } => Some(OfferId::from_valid_bolt12_tlv_stream(&bytes)),
+			InvoiceContents::ForRefund { .. } => None,
+		};
+		Self { bytes, experimental_bytes, contents, tagged_hash, offer_id }


We'd need to take in the InvoiceContents then, too. Leaning towards not doing this for unsigned invoices after all. See next comment.

lightning/src/offers/invoice.rs

vincenzopalazzo · 2025-07-15T08:39:12Z

Ok pushed the changes, not sure that I have got 100% this review, but let me know if there is something that is still pending #3892 (comment)

vincenzopalazzo · 2025-07-15T08:57:33Z

I noted that for some reason, I was not making public the tagged_hash inside the Bolt12Invoice which was the way to execute manual verification. I pushed the code in ea5685c and added a test to show a user how to use the API that we are now making public

lightning/src/offers/invoice.rs

vincenzopalazzo · 2025-07-16T09:58:00Z

I had to rebase to make the CI happy because there was a problem fixed by some PR that is now merged.

So I think the only missing thing to resolve is the following one #3892 (comment)

Would love to have the API to hide the secp256k1, but I also understand that the code is simple enough that we do not need an API for skilled users. Let me know what you preferer

lightning/src/offers/invoice.rs

This is helpfull for the users that 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 that are building command line tools for the bolt12 offers. Signed-off-by: Vincenzo Palazzo <[email protected]>

- Add an Option<OfferId> field to Bolt12Invoice to track the originating offer. - Compute the offer_id for invoices created from offers by extracting the offer TLV records and hashing them with the correct tag. - Expose a public offer_id() accessor on invoice. - Add tests to ensure the offer_id in the invoice matches the originating Offer, and that refund invoices have no offer_id. - All existing and new tests pass. This enables linking invoices to their originating offers in a robust and spec-compliant way. Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com> Signed-off-by: Vincenzo Palazzo <[email protected]>

TheBlueMatt

Sure

TheBlueMatt · 2025-07-24T14:28:47Z

lightning/src/offers/static_invoice.rs

@@ -642,7 +651,8 @@ impl TryFrom<ParsedMessage<FullInvoiceTlvStream>> for StaticInvoice {
 		let pubkey = contents.signing_pubkey;
 		merkle::verify_signature(&signature, &tagged_hash, pubkey)?;

-		Ok(StaticInvoice { bytes, contents, signature })
+		let offer_id = OfferId::from_valid_bolt12_tlv_stream(&bytes);


This is a chunk more hashing on load. Its probably not crazy given we already do a signature validation, but if we assume most folks won't use it, does it make more sense to expose a calculate_offer_id method that does it live instead?

ldk-reviews-bot requested a review from valentinewallace June 26, 2025 10:40

vincenzopalazzo force-pushed the macros/markle-signature branch from 0ffed61 to be23002 Compare June 26, 2025 10:44

valentinewallace reviewed Jun 27, 2025

View reviewed changes

lightning/src/offers/merkle.rs Outdated Show resolved Hide resolved

vincenzopalazzo requested review from TheBlueMatt and valentinewallace July 5, 2025 10:47

graphite-app bot reviewed Jul 5, 2025

View reviewed changes

lightning/src/offers/merkle.rs Outdated Show resolved Hide resolved

vincenzopalazzo force-pushed the macros/markle-signature branch 2 times, most recently from dd046d5 to 29e5bd6 Compare July 8, 2025 20:46

jkczyz reviewed Jul 8, 2025

View reviewed changes

lightning/src/offers/invoice.rs Outdated Show resolved Hide resolved

lightning/src/offers/invoice.rs Outdated Show resolved Hide resolved

lightning/src/offers/invoice.rs Outdated Show resolved Hide resolved

lightning/src/offers/merkle.rs Outdated Show resolved Hide resolved

TheBlueMatt removed their request for review July 9, 2025 01:06

vincenzopalazzo force-pushed the macros/markle-signature branch from 0c7fe08 to 123e16f Compare July 9, 2025 10:19

vincenzopalazzo force-pushed the macros/markle-signature branch 2 times, most recently from 7429b6a to 1b958e9 Compare July 9, 2025 11:13

vincenzopalazzo force-pushed the macros/markle-signature branch from 1b958e9 to 699f37f Compare July 9, 2025 11:23

graphite-app bot reviewed Jul 9, 2025

View reviewed changes

lightning/src/offers/invoice.rs Outdated Show resolved Hide resolved

vincenzopalazzo force-pushed the macros/markle-signature branch from 22ef851 to e60b87c Compare July 9, 2025 20:12

jkczyz reviewed Jul 9, 2025

View reviewed changes

vincenzopalazzo force-pushed the macros/markle-signature branch 2 times, most recently from ec9b1c6 to 98d51cd Compare July 10, 2025 07:19

vincenzopalazzo requested a review from jkczyz July 10, 2025 11:06

vincenzopalazzo commented Jul 11, 2025

View reviewed changes

jkczyz reviewed Jul 11, 2025

View reviewed changes

vincenzopalazzo force-pushed the macros/markle-signature branch 3 times, most recently from 079db78 to 0e5217d Compare July 15, 2025 08:38

vincenzopalazzo requested a review from jkczyz July 15, 2025 08:39

vincenzopalazzo force-pushed the macros/markle-signature branch 2 times, most recently from 097c4a7 to 8df655b Compare July 15, 2025 08:56

vincenzopalazzo force-pushed the macros/markle-signature branch from 8df655b to 5ceaf4d Compare July 15, 2025 09:05

jkczyz reviewed Jul 15, 2025

View reviewed changes

lightning/src/offers/invoice.rs Show resolved Hide resolved

lightning/src/offers/invoice.rs Outdated Show resolved Hide resolved

lightning/src/offers/invoice.rs Show resolved Hide resolved

vincenzopalazzo force-pushed the macros/markle-signature branch 3 times, most recently from c5fe6a3 to f5fbd6c Compare July 16, 2025 09:55

vincenzopalazzo requested a review from jkczyz July 16, 2025 09:56

jkczyz reviewed Jul 16, 2025

View reviewed changes

lightning/src/offers/invoice.rs Show resolved Hide resolved

vincenzopalazzo force-pushed the macros/markle-signature branch from f5fbd6c to 87c74b1 Compare July 21, 2025 17:23

vincenzopalazzo requested a review from jkczyz July 21, 2025 17:25

jkczyz reviewed Jul 22, 2025

View reviewed changes

lightning/src/offers/invoice.rs Show resolved Hide resolved

vincenzopalazzo and others added 2 commits July 23, 2025 19:42

vincenzopalazzo force-pushed the macros/markle-signature branch from 87c74b1 to 93cf409 Compare July 23, 2025 17:43

vincenzopalazzo requested a review from jkczyz July 23, 2025 17:44

jkczyz approved these changes Jul 23, 2025

View reviewed changes

vincenzopalazzo requested review from valentinewallace and TheBlueMatt July 24, 2025 07:16

TheBlueMatt approved these changes Jul 24, 2025

View reviewed changes

TheBlueMatt merged commit 479c5c7 into lightningdevkit:main Jul 24, 2025
27 checks passed

offer: make the merkle tree signature public #3892

offer: make the merkle tree signature public #3892

Uh oh!

Conversation

vincenzopalazzo commented Jun 26, 2025

Uh oh!

ldk-reviews-bot commented Jun 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dunxen commented Jun 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Jun 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

ldk-reviews-bot commented Jun 27, 2025

Uh oh!

Uh oh!

ldk-reviews-bot commented Jul 7, 2025

Uh oh!

ldk-reviews-bot commented Jul 7, 2025

Uh oh!

vincenzopalazzo commented Jul 7, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

TheBlueMatt commented Jul 9, 2025

Uh oh!

ldk-reviews-bot commented Jul 9, 2025

Uh oh!

vincenzopalazzo commented Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vincenzopalazzo Jul 11, 2025

Choose a reason for hiding this comment

Uh oh!

jkczyz Jul 11, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jkczyz Jul 11, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

vincenzopalazzo commented Jul 15, 2025

Uh oh!

vincenzopalazzo commented Jul 15, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vincenzopalazzo commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

TheBlueMatt left a comment

Choose a reason for hiding this comment

Uh oh!

TheBlueMatt Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ldk-reviews-bot commented Jun 26, 2025 •

edited

Loading

dunxen commented Jun 26, 2025 •

edited

Loading

codecov bot commented Jun 26, 2025 •

edited

Loading

vincenzopalazzo commented Jul 9, 2025 •

edited

Loading

vincenzopalazzo commented Jul 16, 2025 •

edited

Loading