How shall we bind payjoin to flutter?

[DanGould]

flutter_rust_bindgen, dart:ffi, uniffi to kotlin/swift + dart wrapper, or uniffi-dart plugin??

payjoin-flutter is being used to give Bull Bitcoin Mobile and Cake wallet access to flutter. Whether or not our current approach is viable long term comes into question as the underlying API gets more complicated and we wish to offer payjoin to other targets through different bindings and compilation targets as well.

I've drawn up excalidraw payjoin-ffi architecture dependency diagrams to show some different options. Below, I go into details of options which may not be in the diagrams but have come up in various conversations on the subject. I'd like to discuss the viability of each approach, and consider Signal's Coding Guidelines's "High Level Priorities" to be a useful rubric for us to select a choice, since signal has similar security requirements and downstream targets to payjoin.

Flutter Rust Bridge

This is what we're using now, though imprecisely and with excess manual wrapping. According to the docs there is some way to let FRB directly generate most every function and struct binding automagically from payjoin-ffi, but that's not the current architecture, which uses wrappers on BOTH rust and dart sides (ew), so a proof of concept needs to be done.

FRB might be favored because it's automagic (though not the way we do it now), but the security story and dependency bloat leave me wondering if there is something better. I'm not sure what, if any, flutter specifics we want for bindings, or if just dart bindings are sufficient to target Bull Bitcoin mobile and Cake.

it'd also be trickier to test properly since we'd need to do a second bindings wrapper around payjoin-test-utils using FRB as well, and a lot of the work to make UniFFI work seems to need to be re-done to make it work with FRB.

Dart bindings to Kotlin / Swift UniFFI Output

@kumulynja claims to have made a proof of concept of this arch. Sharing one source of truth which defines uniffi bindings removes maintenance burden and makes me more comfortable that we've gotten things right. I haven't seen a PoC so I'm not sure how feasible it is.

dart:ffi

@konstantinullrich claims dart:ffi can bind directly to the rust. Apparently Dart ffigen can be used to generate bindings, and @konstantinullrich volunteered to maintain them. I have a limited understanding of this approach.

UniFFI Dart plugin

It'd be great to be able to compile dart directly from our UniFFI implementation.

The readme mentions this ancient uniffi-rs-dart, but that's 2 years old. Safe to say it's unmaintained.

There seems to be an alternative, uniffi-dart which is more regularly maintained, but we have to consider how long that maintainer will be around, and to what extent payjoin-dart consumers can maintain the plugin. Mozilla does not and will not maintain the dart plugin for the foreseeable future because they do not use it in their other UniFFI products.

[konstantinullrich]

Dartffi is not directly compatible with rust, but will work with rust as long als the interface provided by rust is C compatible. With ffigen you are able to generate the bindings based on a .h header file.

[DanGould]

@konstantinullrich mentioned elsewhere to me that UniFFI with kotlin and swift makes it difficult to support @cake-tech's desktop app. I'm not sure if it's possible to support that with kotlin multiplatform or how that affects a decision to go with Dartffi bindings yet.

[kumulynja]

Using the Kotlin/Swift UniFFI output, it would be bindings to Flutter, which make them platform specific and thus limited to Android, iOS/MacOS initially. But I guess most users/demand is from mobile apps anyways and not Desktop (Windows/Linux), so I don't think it's a big concern and can be managed later by adding more platform-specific code still. The advantage it has over the other ways is that the Kotlin and Swift bindings probably need to be generated for native Android/Swift apps anyways and so are reusable for both Flutter as native mobile development.

Since the payjoin protocol and Rust code itself don't require any platform specific things, it could indeed be done in pure Dart with dart:ffi and that would have the full cross-platform (Desktop and even server side or CLI's) advantage. But I think writing safe C compatible Rust wrappers for it is a bit more complex/tricky to implement than using native platform channels and ready to use autogenerated Swift/Kotlin packages.
(Just a side note to keep in mind that Dart Native Assets support is available, but still experimental. If we go the dart:ffi route I think we should bundle as Native Assets, although it is not required to just use dart:ffi already.)

Both the Kotlin/Swift bindings to Flutter and dart:ffi approach have the advantage over FRB to be possible with only standard dependencies and not cause dependency incompatibilities as occur between different packages using different versions of FRB.

A clearer comparison:

1. FRB
   (+) Can be the most autogenerated
   (-) Different architecture and refactor needed
   (-) constant version sync needed with other FRB-based packages in the Bitcoin ecosystem
2. Kotlin/Swift bindings to Flutter
   (+) Seems like the most straightforward and clear way without too many tricky parts to it
   (+) Native Android/Swift bindings are probably required anyways so reusable for Flutter too then
   (+) No non-standard dependencies needed, so less risk of incompatibilities with other packages
   (-) Requires manual implementation of both Kotlin and Swift platform code (and more in the future maybe) as well as shared Flutter "wrapper/API" code
   (-) Initially limited to Android/iOS/MacOS (no Windows/Linux/Server side/CLI)
3. Dart:ffi
   (+) Can be kept platform-agnostic in pure Dart, so no different implementations or extra work needed per platform
   (+) Fully cross-platform (Android/iOS/MacOS/Windows/Linux/Server side/CLI)
   (+) No non-standard dependencies needed, so less risk of incompatibilities with other packages
   (-) Requires manual implementation of C compatible Rust code as well as Dart "wrapper/API" code
   (-) Writing safe C compatible Rust wrappers might be tricky sometimes

Considering the above, I think pure Dart with dart:ffi would be the ideal, since it doesn't require writing platform specific code while covering all platforms, even Dart servers and CLI's could be build with it too then. But... I think getting the Rust wrappers right and safe is a pretty difficult task, so for simplicity and least risks I have a slight preference for number 2.

So, that's my 2 sats, hope it helps somewhat in deciding and happy to hear your thoughts/additions on this comparison.

[DanGould]

You're convincing me UniFFI Flutter wrapper is the way to go given our constraints.

Did you get a chance to prove the concept with bdk-ffi as you had mentioned? Might you share here? There is demand for Swift and Kotlin anyhow.

Also, I don't know anyone who wants Windows/Linux/Server/CLI dart bindings, since those seem to be covered by rust or other bindings. If you have a counterexample I'm very curious to know about it.

[DanGould]

Kotlin Multiplatform

In order to support @konstantinullrich's request for desktop while leveraging others' interest to use Kotlin Multiplatform (KMP) and our core UniFFI library that produces it, we may be able to bind flutter from the output of Kotlin Multiplatform. @kirillzh has already begun work binding pdk to kotlin multiplatform, so we know there's a reason to make KMP work anyway. Doing so seems like an appropriate path forward to support flutter desktop for @cake-tech while still doing as much code re-use as possible for the sake of correctness.

Criteria	FRB (①)	Dart FFI (②)	UniFFI to Swift/Kotlin (③)	UniFFI → KMP → Flutter (④)
Performance	🟢 Good	✅ Best (minimal)	🟢 Good	🟢 Good
Simplicity (Initial Setup)	✅ Simple	🟡 Moderate	🟠 Complex	🟠 Complex
Code Reuse (Cross-platform)	🔴 Dart-only	🔴 Dart-only	🟡 Android/iOS (native separate)	✅ High (shared KMP)
Maintenance & Abstraction	🟢 Good	🔴 Challenging	🟡 Moderate	🟢 Good
Alignment with Signal guidelines	🟡 Moderate	🔴 Low	✅ High	✅ Very High
Community & Ecosystem	✅ Well-established	🟡 Moderate	🟡 Moderate	🟡 Growing but younger

[spacebear21]

I don't totally understand the Dart FFI ratings (maybe because I don't totally understand the Dart FFI approach...).

Wouldn't "Code Reuse" be pretty good since we would need to provide a C interface, which could then be used by all other targets? The C FFI would replace uniffi.

Why is "alignment with Signal guidelines" low? In fact they seem to follow the C FFI approach which iiuc Dart FFI would build upon.

[DanGould]

Only because I'm assuming we aren't dropping UniFFI. If we did C FFI it'd be parallel to UniFFI, but if we just went with C FFI then I think that could work too, but I imagine it'd be a lot more tedious.

[konstantinullrich]

I have to aggree with @spacebear21 here.

Also I don't get the rating "Moderate" of Dart FFI in Community & Ecosytem. I would claim it is even more established than FRB since it even is part of the Dart SDK. FRB is just a wrapper around dart:ffi, but it has some quirks that I'd love to get rid off e.g. You can't use a library if the code was generated with a slightly different version of FRB.

[Johnosezele]

I myself lean on dart:ffi suggestion from @kumulynja and @konstantinullrich

The main issue raised was that this "requires manual implementation of C compatible Rust code" and "writing safe C compatible Rust wrappers might be tricky."
IMO this makes sense, especially since manually handling memory for strings, structs, and collections across the C boundary is error-prone and tedious.

But I think here's where serialization (like Protobuf) could simplify things:
Instead of exposing a complex surface of Rust functions with various struct parameters and return types over C ABI, we could expose just a minimal C ABI surface.
Something like:



// C-style header definition
// extern "C" uint8_t* process_payjoin_request(const uint8_t* request_bytes, size_t request_len, size_t* response_len);
// extern "C" void free_payjoin_response(uint8_t* response_bytes);



If I can sketch a theoretical flow with protobuf, I would say:

-Dart serializes its request into a Protobuf byte array
-Calls the ‘process_payjoin_request’ Rust function via dart:ffi, passing the pointer and length
-The Rust wrapper would:
* Take the raw bytes
* Convert to a safe Rust slice
* Deserialize via Protobuf to proper Rust types
* Call our internal Rust payjoin logic
* Serialize the result back to Protobuf
* Allocate memory for the response that Dart can access (and later free)
-Dart gets the pointer back, reconstructs the byte array, and deserializes

I think this is a viable middle-ground, also someone mentioned using this approach, and also limitations in production here: https://stackoverflow.com/questions/69474386/how-to-call-rust-functions-in-flutter-dart-via-ffi-but-with-convenience-and-s

[DanGould]

The main issue with something like extern "C" uint8_t* process_payjoin_request(const uint8_t* request_bytes, size_t request_len, size_t* response_len); is that we lose all of our strong type guarantees that prevent people from shooting themselves in the foot. Any solution needs to maintain high level type safety.

[Johnosezele]

Right! We can also build a Dart wrapper around these FFI calls to offer type safe API for anyone using the library.

[DanGould]

Maintaining a manual dart wrapper is exactly what UniFFI lets us avoid. If we're willing to write custom dart:ffi, a better long term solution would be to bite the bullet and write and maintain a dart plugin for UniFFI sufficient for our use case so that we can share code for it and other languages we wish to target. This would have knock-on effects to help bdk-ffi, bitcoin-ffi, etc, since they're all based on UniFFI anyway.

A proof of concept to bind to dart via uniffi plugin would start with the existing implmentations here and here and produce a proof of concept.

To bind dart:ffi we'd have to build a #[no_mangle] extern "C" interface on either rust-payjoin/payjoin or rust-payjoin/payjoin-ffi. The whole point of UniFFI is to produce ~ this interface automatically. We'd then need to write a dart interface to wrap it. Rather than write the dart interface, we could write the generator once and re-use it across the whole ecosystem. By using a plugin, we could re-use everything we learned in writing payjoin-ffi to keep the dart bits as slim as possible and checking our work in an abstract sense rather than for each custom type conversion.

[Johnosezele]

Ok, I see what you're getting at, it makes a lot of sense. The whole idea behind UniFFi is to save us from writing those manual wrappers. If we're going to put in the effort for Dart, focusing on a UniFFI Dart plugin seems much smarter in the long term. That way, we define our API once in Rust, and UniFFI can handle spitting out the Dart code, just like it does for Kotlin and Swift.
It seems like a bigger task upfront to work on this plugin, but in the end, solving the 'Rust to Dart' issue at the UniFFI level will make us avoid redoing work for every type.

[notmandatory]

Are you considering creating your own uniffi dart plugin? If the existing uniffi-dart project has most of what's needed and even a small community around it seems more efficient to work on upstreaming any missing features there. I like the general UniFFI approach because it's what we already use with BDK for Swift,Kotlin,Python, and would love to be able to offer a Dart option since it's also popular with our users.

[benalleng]

I am just in the process of making an update here! We are utilizing the uniffi-dart project with some modifications for now.

[benalleng]

@spacebear21 and I have begun implementing the dart bindings through the use of uniffi-dart. I think based on the interaction with the project's maintainer it seems like there is some reasonable expectation of maintenance for it into the future. However, we have created a divergent branch from main fixing many of the missing features as well as upgrading the uniffi dependency there to 0.29 to be inline with the existing uniffi version in our payjoin-ffi crate that will hopefully be moved upstream into the future to reduce our maintenance burden.

While I have created a minimal build validating that the auto-generated code has some level of correctness this is a very minimal build and many of the complex types exist outside of the uri crate I used. A real test will really need to wait for more code to be generated without errors to create more thorough integrations.

While there was a lot of cleanly generated code a few problem areas remained on initial generation.

1. Callback interfaces are not generated cleanly and callback interface vtables to allow rust to call dart are not generated at all
2. Dart bindings seem to not understand that there can be types and enums containing the name "Error" and must be changed to use "Exception" instead
3. The dart code was not binding the payjoin and bitcoin crates in parallel initially but still treating them as if they had been correctly created; importing the types from code that did not exist
4. Some other minor missing types or syntax errors requiring some modifications

Remaining hurdles

• Refine the callback interface generation creates separate vtable and pure callback interface methods cleanly
• Ensure that the auto-generated code is not just error-free but also correct across the code base

[spacebear21]

Yes, basically uniffi-dart gets us 80% of the way there, and we're in the process of implementing bindings generators for the types that aren't supported yet for our use cases (notably Callback traits, Bytes, and Custom Types) and other minor fixes. Once they are completed and validated for correctness we should be able to merge them upstream.

[spacebear21]

Another point that's worth mentioning: there will still be a role for payjoin-flutter after we complete the migration to uniffi-dart for bindings. uniffi-dart only produces dart (backend) bindings. payjoin-flutter could become a strictly frontend reference that uses uniffi-dart bindings instead of flutter_rust_bridge to produce an example app.

[Johnosezele]

Quick update: I recently worked with @spacebear21 on implementing 'custom types support' for uniffi-dart (one of the missing features mentioned). We successfully got uniffi 0.29 custom type working with a typedef-based approach that prioritizes performance over compile-time safety. The implementation should be ready for upstreaming...

Trade-offs question:
Given @DanGould original concern about "losing strong type guarantees...", I'd love a third eye on our type safety vs performance decision:

Our typedef approach means:

typedef Handle = i64;
// Handle and i64 are interchangeable at runtime - no compile-time type safety

vs a wrapper approach that would provide stronger guarantees:

class Handle {
  final i64 value;
  // Handle(123) ≠ 123 - true type safety but with wrapper overhead
}

• Are we comfortable relying primarily on Rust-side validation to catch type misuse?
• Is the simplicity/performance worth the trade-off for payjoin's security requirements?
• Should we consider optional runtime checks as a middle ground without full wrapper overhead?

[spacebear21]

We should keep in mind that the typedef approach only affects Custom Types, which are currently only used in payjoin-ffi for the bitcoin Txid type. So this only affects one type in our entire API at the moment.

Additionally, this approach is keeping in line with uniffi's official bindings for custom types (see official docs and kotlin reference). These implementations do allow for a custom configuration to be provided for custom types via uniffi.toml, but I think this is overkill for our use case and out of scope for a MVP dart bindings generator using uniffi.

Finally, I'm not sure that the implementation is ready for upstreaming just yet. We're very close to being able to validate it with our own code but for now all we know is that it compiles.

[Johnosezele]

I understand the typedef approach follows uniffi standards and works well for the current single custom type. If payjoin-ffi grows to include more custom types (which seems likely), we might regret not establishing stronger type safety patterns early.

That said, I appreciate the simplicity argument, and since this is currently just one type, the typedef approach is reasonable for an MVP. Perhaps we could revisit this if/when more custom types are added.

[BitcoinZavior]

@DanGould Using UniFFI to create Kotlin and Swift bindings, and using UniFFI to create a Flutter package via FRB, is still the most efficient approach.

I haven't seen things change dramatically in the ecosystem to enable more efficient and lower-maintenance options.

The third option in your Excalidraw diagram, Payjoin Compilation Targets Aspirational Option 1, is what was originally proposed here: original proposal

This is what is used for bdk and ldk-node at the moment.

Payjoin Compilation Targets Aspirational Option 2 eliminates FRB, but if I recall correctly, creating a Flutter package with Kotlin and Swift bindings had lower performance than using UniFFI+FRB.

It would be great if Dart FFI is ready to be used so that we can use it directly with UniFFI. There is a similar effort for React Native here: https://github.com/jhugman/uniffi-bindgen-react-native

However, both are not ready to use at the moment.

[spacebear21]

dart FFI status update:

• this fork of uniffi-dart now produces functioning dart bindings for payjoin-ffi. thanks @benalleng and @Johnosezele for contributing to this.
• i opened a draft PR in rust-payjoin that adds dart bindgen via my fork of uniffi-dart .
• @benalleng wrote some dart unit tests to prove out the basic utilization of the generated dart bindings and is now in the process of writing an integration test to prove that the payjoin state machine works as intended

some outstanding items:

• integration tests
• Dart workflow for github CI
• Upstream uniffi-dart changes (not a strict blocker since we can rely on my fork until this is resolved)

[spacebear21]

The Dart FFI PR has been merged with passing unit and integration tests.

uniffi-dart has been graciously transferred by the previous owner to a new org: https://github.com/Uniffi-Dart/uniffi-dart, and @chavic is continuing his work on uniffi-dart there. All changes required to get the payjoin integration working have been merged upstream.

Next steps:

• uniffi-dart now produces workable bindings for rust-payjoin, but there are still unhandled uniffi features and edge cases. @chavic is porting the uniffi-rs test fixtures to a) paint a better picture of what does and doesn't work and b) start fixing things that don't work.
• The rust-payjoin github workflow for dart is mostly ready but the integration test fails due to an incompatibility with testcontainers (dev dependency for redis-in-docker). Upgrading the testcontainers version fixes this but breaks MSRV. We are considering ripping out the redis/docker dependency from our test services.
• Make a payjoin-dart 0.24 release and upgrade downstream users (Bull Bitcoin Mobile and Cake Wallet).

[DanGould]

Do we want to do a payjoin-dart 0.24 release or are there sufficient changes to make more sense to roll straight into 0.25 (or 24.1 depending on which APIs we broke, I think we did break them). Until that time perhaps we just check integration on a git branch

[spacebear21]

Yeah I was considering holding off on an actual payjoin-dart release until we validate it in an actual integration. Using a git branch until then sounds reasonable.