Feature: Add Bolt12 Uniffi Type Wrappers #542

alexanderwiederin · 2025-05-19T09:55:50Z

Second PR for #504.

This PR adds full Offer-, Refund- and Bolt12Invoice- types for the FFI bindings.

Changes:

Type definitions in ldk_node.udl and uniffi_types.rs
Implementation of UniffiType trait to standardize conversions between LDK types and their FFI-compatible wrappers in uniffi_conversions.rs
Integration of wrapper types in payment handling methods in bolt12.rs and unified_qr.rs

Benefits:

Direct access to Offer, Refund and Bolt12Invoice properties from FFI languages
Consistent API across languages

Note:

Appreciate that this PR is big. Happy to break down into smaller parts if preferred.

ldk-reviews-bot · 2025-05-19T09:55:52Z

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

src/uniffi_conversions.rs

tnull

Thanks, already looks pretty good! Did a first higher-level pass.

bindings/ldk_node.udl

src/uniffi_conversions.rs

src/uniffi_types.rs

bindings/ldk_node.udl

src/uniffi_types.rs

src/uniffi_conversions.rs

tnull

Cool, I like the proposed approach. Very clean!

Just a few comments.

src/ffi/conversions.rs

src/ffi/types.rs

src/ffi/conversions.rs

ldk-reviews-bot · 2025-06-04T12:53:35Z

🔔 1st Reminder

Hey @enigbe! 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-06-07T00:00:48Z

🔔 2nd Reminder

Hey @enigbe! 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-06-09T00:01:39Z

🔔 3rd Reminder

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

enigbe

Well done @alexanderwiederin,

I've reviewed this and just have a small question regarding fixed-sized arrays. The ffi/conversion approach looked good to me, but following your conversation with @tnull has highlighted some gaps in my understanding of Uniffi's internals especially with regards to heap allocation. I'll be looking into that further.

I've also tested this and it LGTM.

enigbe · 2025-06-09T14:15:08Z

src/ffi/types.rs

+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum OfferAmount {
+	Bitcoin { amount_msats: u64 },
+	Currency { iso4217_code: String, amount: u64 },
+}


Curious about why LdkAmount is not used directly here. OfferAmount is basically the same struct except for the iso4217_code field. Is this because there is no support for fixed-sized arrays?

Yea, that's pretty much it. OfferAmount provides a binding-friendly representation by using String instead of a fixed-size byte array for iso4217_code. I also don't think you can automatically convert complex types across FFI language boundaries in general.

enigbe · 2025-06-09T17:22:47Z

src/ffi/mod.rs

+}
+
+#[cfg(feature = "uniffi")]
+pub fn maybe_wrap<T>(ldk_type: impl Into<T>) -> std::sync::Arc<T> {


Why is ldk_type impl Into<T> and not just T?

Good question! T is not actually the type that is passed to maybe_wrap. impl Into<T> means that the argument we pass to maybe_wrap can be any type that implements Into<T> to convert itself into T. In our case T would be the UniFFI type that is needed at the call site.

For example, we pass LDK native types (like lightning_invoice::Bolt11Invoice), which gets converted to their corresponding UniFFI wrapper type (like ffi::types::Bolt11Invoice) using .into() before being wrapped in an Arc.

tnull

LGTM I think, mod one nit.

Let me know if you intend to make further changes or if this can land from your side.

src/ffi/mod.rs

This commit reorganizes the FFI architecture by introducing conversion traits for lightning types. Moves code from uniffi_types.rs to a dedicated ffi module for separation of concerns.

alexanderwiederin · 2025-06-10T10:47:47Z

Thanks for the feedback @tnull. This can land from my side!

bindings/ldk_node.udl

Implement Offer struct in ffi/types.rs to provide a wrapper around LDK's Offer for cross-language bindings. Modified payment handling in bolt12.rs to: - Support both native and FFI-compatible types via type aliasing - Implement conditional compilation for transparent FFI support - Update payment functions to handle wrapped types Added testing to verify that properties are preserved when wrapping/unwrapping between native and FFI types.

Implement Refund struct in ffi/types.rs to provide a wrapper around LDK's Refund for cross-language bindings. Modified payment handling in bolt12.rs to: - Support both native and FFI-compatible types via type aliasing - Implement conditional compilation for transparent FFI support - Update payment functions to handle wrapped types Added testing to verify that properties are preserved when wrapping/unwrapping between native and FFI types.

Implement Bolt12Invoice struct in ffi/types.rs to provide a wrapper around LDK's Bolt12Invoice for cross-language bindings. Modified payment handling in bolt12.rs to: - Support both native and FFI-compatible types via type aliasing - Implement conditional compilation for transparent FFI support - Update payment functions to handle wrapped types Added testing to verify that properties are preserved when wrapping/unwrapping between native and FFI types.

tnull

LGTM

alexanderwiederin commented May 19, 2025

View reviewed changes

src/uniffi_conversions.rs Outdated Show resolved Hide resolved

alexanderwiederin force-pushed the uniffi-bolt12-clean branch from f07aa51 to e85a185 Compare May 20, 2025 19:25

alexanderwiederin marked this pull request as ready for review May 20, 2025 21:21

ldk-reviews-bot requested a review from valentinewallace May 20, 2025 21:22

alexanderwiederin force-pushed the uniffi-bolt12-clean branch from e85a185 to 7188bca Compare May 22, 2025 08:27

tnull requested review from tnull and removed request for valentinewallace May 22, 2025 15:13

tnull reviewed May 22, 2025

View reviewed changes

bindings/ldk_node.udl Outdated Show resolved Hide resolved

src/uniffi_conversions.rs Outdated Show resolved Hide resolved

src/uniffi_conversions.rs Outdated Show resolved Hide resolved

alexanderwiederin force-pushed the uniffi-bolt12-clean branch from 7188bca to 2f3bc2e Compare May 25, 2025 15:35

enigbe reviewed May 28, 2025

View reviewed changes

src/uniffi_types.rs Outdated Show resolved Hide resolved

alexanderwiederin force-pushed the uniffi-bolt12-clean branch from 2f3bc2e to 670a885 Compare May 28, 2025 13:48

tnull mentioned this pull request May 29, 2025

offers: parse invoice and invoice request lightningdevkit/rust-lightning#3800

Closed

tnull reviewed May 29, 2025

View reviewed changes

src/uniffi_types.rs Outdated Show resolved Hide resolved

bindings/ldk_node.udl Show resolved Hide resolved

src/uniffi_types.rs Outdated Show resolved Hide resolved

src/uniffi_conversions.rs Outdated Show resolved Hide resolved

src/uniffi_conversions.rs Outdated Show resolved Hide resolved

alexanderwiederin force-pushed the uniffi-bolt12-clean branch from 670a885 to 2894d87 Compare June 2, 2025 11:49

alexanderwiederin requested review from tnull and enigbe June 2, 2025 12:08

tnull mentioned this pull request Jun 3, 2025

Support passing preimage for spontaneous payments #549

Open

tnull reviewed Jun 3, 2025

View reviewed changes

src/ffi/conversions.rs Outdated Show resolved Hide resolved

src/ffi/conversions.rs Outdated Show resolved Hide resolved

src/ffi/types.rs Outdated Show resolved Hide resolved

src/ffi/conversions.rs Outdated Show resolved Hide resolved

alexanderwiederin force-pushed the uniffi-bolt12-clean branch from 2894d87 to 3126d86 Compare June 3, 2025 20:08

alexanderwiederin force-pushed the uniffi-bolt12-clean branch 4 times, most recently from 4a4572a to 1ebcb89 Compare June 9, 2025 13:21

enigbe reviewed Jun 9, 2025

View reviewed changes

tnull reviewed Jun 10, 2025

View reviewed changes

src/ffi/mod.rs Outdated Show resolved Hide resolved

alexanderwiederin force-pushed the uniffi-bolt12-clean branch from 1ebcb89 to affe664 Compare June 10, 2025 09:56

Restructure FFI bindings with conversion traits for Lightning types

07b5471

This commit reorganizes the FFI architecture by introducing conversion traits for lightning types. Moves code from uniffi_types.rs to a dedicated ffi module for separation of concerns.

alexanderwiederin force-pushed the uniffi-bolt12-clean branch from affe664 to 0dd04ba Compare June 10, 2025 10:22

tnull reviewed Jun 10, 2025

View reviewed changes

bindings/ldk_node.udl Show resolved Hide resolved

alexanderwiederin added 3 commits June 10, 2025 13:53

alexanderwiederin force-pushed the uniffi-bolt12-clean branch from 0dd04ba to f01d021 Compare June 10, 2025 12:02

tnull approved these changes Jun 10, 2025

View reviewed changes

tnull merged commit 40a3aeb into lightningdevkit:main Jun 10, 2025
14 of 15 checks passed

This was referenced Jun 10, 2025

Expose proper Invoice / Offer types in bindings #504

Closed

Add support for sending to human-readable names (BIP 353) #528

Open

Feature: Add Bolt12 Uniffi Type Wrappers #542

Feature: Add Bolt12 Uniffi Type Wrappers #542

Conversation

alexanderwiederin commented May 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes:

Benefits:

Note:

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ldk-reviews-bot commented Jun 4, 2025

Uh oh!

ldk-reviews-bot commented Jun 7, 2025

Uh oh!

ldk-reviews-bot commented Jun 9, 2025

Uh oh!

enigbe left a comment

Choose a reason for hiding this comment

Uh oh!

enigbe Jun 9, 2025

Choose a reason for hiding this comment

Uh oh!

alexanderwiederin Jun 9, 2025

Choose a reason for hiding this comment

Uh oh!

enigbe Jun 9, 2025

Choose a reason for hiding this comment

Uh oh!

alexanderwiederin Jun 9, 2025

Choose a reason for hiding this comment

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

alexanderwiederin commented Jun 10, 2025

Uh oh!

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

alexanderwiederin commented May 19, 2025 •

edited

Loading

ldk-reviews-bot commented May 19, 2025 •

edited

Loading