[RFC] event: expose BOLT12 invoice in PaymentSuccessful for proof of payment by vincenzopalazzo · Pull Request #733 · lightningdevkit/ldk-node

vincenzopalazzo · 2025-12-29T13:51:52Z

This patch adds the bolt12_invoice field to the PaymentSuccessful event, enabling users to obtain proof of payment for BOLT12 transactions.

Problem:
Previously, after a successful BOLT12 payment, users had no way to access the paid invoice data. This made it impossible to provide proof of payment to third parties, who need both the payment preimage and the original invoice to verify that sha256(preimage) matches the invoice's payment_hash.

Solution:
Add a bolt12_invoice: Option<Vec<u8>> field to PaymentSuccessful that contains the serialized BOLT12 invoice bytes. The invoice is serialized using LDK's standard encoding, which can be parsed back using Bolt12Invoice::try_from(bytes) in native Rust, or by hex-encoding the bytes and using Bolt12Invoice.from_str() in FFI bindings.

Design decisions:

Store as Vec<u8> rather than the complex PaidBolt12Invoice type to avoid UniFFI limitations with objects in enum variants
Return None for StaticInvoice (async payments) since proof of payment is not possible for those payment types anyway
Use TLV tag 7 for serialization, maintaining backward compatibility with existing persisted events

This implementation follows the maintainer guidance from PR #563 to expose the invoice via the event rather than storing it in the payment store.

ldk-reviews-bot · 2025-12-29T13:51:54Z

👋 Thanks for assigning @tnull 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.

vincenzopalazzo · 2025-12-29T13:53:30Z

@tnull IDK if this is a good design to have with the ffi, but I had to work around some unify ffi limitation with the enum type that is used inside the PaymentSend in rust-lightning

ldk-reviews-bot · 2025-12-31T14:03:37Z

🔔 1st Reminder

Hey @tnull! 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 · 2026-01-03T00:00:36Z

🔔 2nd Reminder

Hey @tnull! 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 · 2026-01-05T00:01:25Z

🔔 3rd Reminder

Hey @tnull! 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.

tnull

Exposing the BOLT12 invoice makes sense to me, though we should do it properly instead of just exposing the bytes.

src/event.rs

tnull

The changes are getting closer, but please make sure to avoid unnecessary boilerplate and stick to the approach we took for the other types (like Offer, Refund, etc).

This also needs a rebase by now, sorry!

Btw, please re-request review when you made updates, otherwise I might not always see it immediately.

bindings/ldk_node.udl

src/types.rs

ldk-reviews-bot · 2026-01-12T12:09:56Z

🔔 1st Reminder

Hey @tnull! 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 · 2026-01-14T12:10:38Z

🔔 2nd Reminder

Hey @tnull! 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 · 2026-01-19T00:00:18Z

🔔 1st Reminder

Hey @tnull! 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.

tnull · 2026-01-19T11:30:11Z

bindings/ldk_node.udl

 	sequence<u8> encode();
 };

+// TODO: Add StaticInvoice and PaidBolt12Invoice once we upgrade to UniFFI 0.29+. See #757.


nit: Let's drop this TODO, one above on Event is sufficient.

tnull · 2026-01-19T11:31:02Z

src/payment/mod.rs

 pub use unified::{UnifiedPayment, UnifiedPaymentResult};
+
+#[cfg(not(feature = "uniffi"))]
+pub use crate::types::PaidBolt12Invoice;


No need to re-export the type here, let's just drop it and use the LDK type directly.

We should be good to drop these changes now?

src/event.rs

tnull · 2026-03-02T08:35:16Z

@vincenzopalazzo We now landed the uniffi v0.29 upgrade, so this should be unblocked. Note that as part of that upgrade we switched to use proc macros where possible, in particular Event is no longer exposed via the UDL file. So this should be unblocked, please rebase and let me know how it goes!

…ment Add the `bolt12_invoice` field to the `PaymentSuccessful` event, enabling users to obtain proof of payment for BOLT12 transactions. Problem: After a successful BOLT12 payment, users had no way to access the paid invoice data. This made it impossible to provide proof of payment to third parties, who need both the payment preimage and the original invoice to verify that sha256(preimage) matches the invoice's payment_hash. Solution: Add `bolt12_invoice: Option<PaidBolt12Invoice>` to `PaymentSuccessful`. With the UniFFI v0.29 upgrade now supporting objects in enum variants, we can expose the proper `PaidBolt12Invoice` type across both native Rust and FFI builds without cfg-gating the Event field. For non-UniFFI builds, LDK's `PaidBolt12Invoice` is re-exported directly. For UniFFI builds, a wrapper `PaidBolt12Invoice` enum is defined in ffi/types.rs with `From` conversions and delegating serialization. A minimal `StaticInvoice` FFI wrapper is also added to support the `PaidBolt12Invoice::StaticInvoice` variant. The FFI enum variants are named `Bolt12`/`Static` (rather than `Bolt12Invoice`/`StaticInvoice`) to avoid Kotlin sealed class name collisions where inner data classes would shadow top-level types. TLV tag 7 is used for serialization, maintaining backward compatibility: older readers silently skip the unknown odd tag, and newer readers deserialize `None` from events without it. Closes lightningdevkit#757. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

vincenzopalazzo · 2026-03-02T17:33:54Z

Thanks @tnull I used the help of claude to navigate a little bit the changes and now I pushed it (I have to change some name inside the enum for the kotlin naming convention hope this is not a big deal.

Please let me know if this is good enough or if there is a better way to implement the functionality in the codebase, thanks

tnull

Cool, mostly looks good, just some comments regarding cleanups we should now be able to do?

tnull · 2026-03-02T17:39:36Z

src/payment/mod.rs

 pub use unified::{UnifiedPayment, UnifiedPaymentResult};
+
+#[cfg(not(feature = "uniffi"))]
+pub use crate::types::PaidBolt12Invoice;


We should be good to drop these changes now?

tnull · 2026-03-02T17:40:47Z

src/types.rs

 pub(crate) type PendingPaymentStore = DataStore<PendingPaymentDetails, Arc<Logger>>;
+
+#[cfg(not(feature = "uniffi"))]
+pub use lightning::events::PaidBolt12Invoice;


I don't think we need this?

tnull · 2026-03-02T17:41:54Z

tests/integration_tests_rust.rs

+#[tokio::test(flavor = "multi_thread", worker_threads = 1)]
+async fn bolt12_proof_of_payment() {
+	let (bitcoind, electrsd) = setup_bitcoind_and_electrsd();
+	let chain_source = TestChainSource::Esplora(&electrsd);


Please use random_chain_source here so this test is run on all chain sources.

tnull · 2026-03-02T17:44:28Z

tests/integration_tests_rust.rs

 }

+#[tokio::test(flavor = "multi_thread", worker_threads = 1)]
+async fn bolt12_proof_of_payment() {


AFAICT this is essentially the same as simple_bolt12_send_receive? Should we just add a check for the proof-of-payment/invoice there?

tnull · 2026-03-02T17:45:14Z

tests/integration_tests_rust.rs

+				},
+			}
+
+			// Verify serialization round-trip (tests TLV tag 7 backward compatibility)


Hmm, that seems very out-of-place here? If anything, a serialization roundtrip test should be a unit test in event.rs, but I don't think we need it.

vincenzopalazzo marked this pull request as ready for review December 29, 2025 13:53

ldk-reviews-bot requested a review from tnull December 29, 2025 14:02

tnull reviewed Jan 5, 2026

View reviewed changes

src/event.rs Outdated Show resolved Hide resolved

tnull mentioned this pull request Jan 5, 2026

storage: store the bolt12invoice invoice #563

Closed

vincenzopalazzo force-pushed the macros/bolt12-pop branch from 4c6b18e to a3a60b3 Compare January 6, 2026 07:49

tnull reviewed Jan 8, 2026

View reviewed changes

bindings/ldk_node.udl Outdated Show resolved Hide resolved

src/types.rs Outdated Show resolved Hide resolved

src/types.rs Outdated Show resolved Hide resolved

src/types.rs Outdated Show resolved Hide resolved

vincenzopalazzo force-pushed the macros/bolt12-pop branch 4 times, most recently from 22abd3b to a8d05cb Compare January 10, 2026 12:05

vincenzopalazzo requested a review from tnull January 10, 2026 12:09

tnull removed their request for review January 14, 2026 15:12

thesimplekid mentioned this pull request Jan 15, 2026

feat: uniffi bindings for golang cashubtc/cdk#1118

Open

4 tasks

vincenzopalazzo mentioned this pull request Jan 15, 2026

Expose PaidBolt12Invoice in bindings after UniFFI 0.29+ upgrade #757

Open

vincenzopalazzo force-pushed the macros/bolt12-pop branch 3 times, most recently from 327a59a to e6200d6 Compare January 16, 2026 17:11

vincenzopalazzo requested a review from tnull January 16, 2026 17:14

tnull reviewed Jan 19, 2026

View reviewed changes

vincenzopalazzo force-pushed the macros/bolt12-pop branch 2 times, most recently from 025fea4 to 991fa56 Compare March 2, 2026 15:26

vincenzopalazzo force-pushed the macros/bolt12-pop branch from 971aee2 to cd7c42d Compare March 2, 2026 17:19

vincenzopalazzo requested a review from tnull March 2, 2026 17:32

tnull reviewed Mar 2, 2026

View reviewed changes

Conversation

vincenzopalazzo commented Dec 29, 2025

Uh oh!

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

Uh oh!

Uh oh!

vincenzopalazzo commented Dec 29, 2025

Uh oh!

ldk-reviews-bot commented Dec 31, 2025

Uh oh!

ldk-reviews-bot commented Jan 3, 2026

Uh oh!

ldk-reviews-bot commented Jan 5, 2026

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tnull left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ldk-reviews-bot commented Jan 12, 2026

Uh oh!

ldk-reviews-bot commented Jan 14, 2026

Uh oh!

ldk-reviews-bot commented Jan 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

tnull commented Mar 2, 2026

Uh oh!

vincenzopalazzo commented Mar 2, 2026

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ldk-reviews-bot commented Dec 29, 2025 •

edited

Loading

tnull left a comment •

edited

Loading