Add javascript language bindings #1190

spacebear21 · 2025-11-13T20:13:27Z

This PR adds javascript bindings to payjoin-ffi via uniffi-bindgen-react-native. I highly recommend reviewing commit by commit for it to make sense. Claude came in clutch for porting over the unit/integration tests from other language bindings, and also for writing the test-utils wrapper via napi-rs. The remaining TODOs below can be left as follow-ups IMO.

TODOs:

Add javascript build-and-test CI workflow
Write an integration test. This will be tricky because _test-utils does not build on WASM targets due to the tokio net dependency.
io feature is disabled, so ideally the JS bindings should offer an alternative for fetching OHTTP keys.
- tracking in JS bindings should include io functionality #1250
Upstream uniffi-bindgen-react-native changes from my fork (or find alternative fix)
- tracking in package.json and tsconfig.json module values conflict jhugman/uniffi-bindgen-react-native#324

Pull Request Checklist

Please confirm the following before requesting review:

I have disclosed my use of
AI
in the body of this PR.
I have read CONTRIBUTING.md and rebased my branch to produce hygienic commits.

coveralls · 2025-11-13T20:18:14Z

Pull Request Test Coverage Report for Build 19553229768

Details

0 of 0 changed or added relevant lines in 0 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage remained the same at 83.578%

Totals
Change from base Build 18946545260:	0.0%
Covered Lines:	8988
Relevant Lines:	10754

💛 - Coveralls

DanGould

Only reviewed the first three commits so far and wanted to post it rather than sit on it

DanGould · 2025-11-19T14:44:21Z

payjoin-ffi/javascript/wasm-manifest-patch.toml

Why are these patched separately from the top level workspace patches? Do you know what unpatches them to require this second patch file?

Good question, adding this comment to the patch file for clarity:

ubrn build generates a Rust wasm crate in rust_modules/wasm, with wasm-bindgen annotated functions.
That crate is used to generate TS bindings which call into the wasm-bindgen functions.
Because that generated crate doesn't belong to the payjoin workspace, we need to patch the generated Cargo.toml accordingly for local development.
The patch is applied via the ubrn.config.yaml manifestPatchFile option.

DanGould · 2025-11-19T14:46:35Z

payjoin-ffi/javascript/scripts/generate_bindings.sh

making brew and npm dependencies definitely seems WAY hackier than using a flake which defines these llvm, llvm-ar, and clang dependencies.

I'm not opposed to supporting preliminary scaffolding this way but I'd want to fix this sooner than later. Can see the mistake of easily building on "works on my machine" building up

I don't love the llvm hack but replacing the brew dependency with a nix dependency seems ~equivalent, and most macOS devs already use homebrew. If the concern is reproducible builds I guess nix is better but we haven't really committed to using nix in the rest of the project or in any CI workflows, so I'm a bit reluctant to introduce it here as a dependency without using nix for other workflows myself.

Yes I see this is not installing anything, it's just calling deps documented as requirements. The only difference with making nix a requirement would be removing the brew --prefix I suppose

DanGould · 2025-11-19T14:50:13Z

payjoin/src/core/time.rs

I know web_time already does the cfg switching, but if these two files (time.rs and receive/v2/mod.rs) are the only places we're importing time types I do prefer keeping the cfg switching in our code as a double sanity check.

Adding a clarifying code comment for posterity.

DanGould · 2025-11-19T14:52:11Z

payjoin-ffi/javascript/test/unit.test.ts

+
+        const senderPersister = new InMemorySenderPersister(1);
+        const psbt =
+            "cHNidP8BAHMCAAAAAY8nutGgJdyYGXWiBEb45Hoe9lWGbkxh/6bNiOJdCDuDAAAAAAD+////AtyVuAUAAAAAF6kUHehJ8GnSdBUOOv6ujXLrWmsJRDCHgIQeAAAAAAAXqRR3QJbbz0hnQ8IvQ0fptGn+votneofTAAAAAAEBIKgb1wUAAAAAF6kU3k4ekGHKWRNbA1rV5tR5kEVDVNCHAQcXFgAUx4pFclNVgo1WWAdN1SYNX8tphTABCGsCRzBEAiB8Q+A6dep+Rz92vhy26lT0AjZn4PRLi8Bf9qoB/CMk0wIgP/Rj2PWZ3gEjUkTlhDRNAQ0gXwTO7t9n+V14pZ6oljUBIQMVmsAaoNWHVMS02LfTSe0e388LNitPa1UQZyOihY+FFgABABYAFEb2Giu6c4KO5YW0pfw3lGp9jMUUAAA=";


I suppose these test vectors really need to come from a common utils library or common fixtures (and perhaps they do in following commits?) because otherwise they all need to be crosschecked in each language.

Good point, I will address this in a follow-up as there are other things I'd like to cleanup across all language bindings.

DanGould

I went through the whole thing. Your wrangling with uniffi-bindgen-react-native gets me so excited about our bindings story because 1. I know it's in talented hands and 2. javascript is such a pain compared to other languages, and this wasn't an impossible review.

I don't think there are any major offenders, so this could be merged as-is but I'd prefer if my comments were addressed before that

payjoin-ffi/Cargo.toml

DanGould · 2025-11-19T22:01:49Z

payjoin-ffi/javascript/scripts/generate_bindings.sh

+# Heinous hack to pin a transitive dependency to be MSRV compatible on 1.85
+cd node_modules/uniffi-bindgen-react-native
+cargo add home@=0.5.11 --package uniffi-bindgen-react-native
+cd ../..
+
+rustup target add wasm32-unknown-unknown


What would a not heinous 'proper' way to do this be? If known, it'd be cool to doc in the comment here.

If Rust had a sane way to manage MSRV it might help other library providers not accidentally breaking compatibility, but as it stands the only alternative I can think of is to ignore MSRV in payjoin-ffi. Though that might break shared dependencies in the payjoin workspace, so we'd have to exclude payjoin-ffi from the workspace.

DanGould · 2025-11-19T22:03:28Z

.github/workflows/javascript.yml

+      - name: "Install dependencies"
+        run: npm ci


@thebrandonlucas is npm the thing to use or is there another javascript package manager we should be using? Bun?

TBF, it seems like js package managers is a rotating fashion choice and I think npm is lindy and fine.

DanGould · 2025-11-19T22:12:41Z

payjoin-ffi/javascript/test-utils/src/lib.rs

Will it ever be possible to make these bindings with uniffi or is this a wontfix issue? If this works, it's test utils and it seems like a fine hack as long as it's a documented decision, which it seems to be in the commit message.

Though I do wonder if integrations like Bull Bitcoin would use node bindings that allow I/O in closures (if wasm doesn't already)

Will it ever be possible to make these bindings with uniffi or is this a wontfix issue?

If we make all test-utils not require io, e.g. by replacing requests/responses with hardcoded mock values, we could just compile test utils to wasm. For the time being I consider it wontfix since this workaround seems acceptable for testing.

Not sure what you mean by allowing I/O in closures?

The whole reason to do node.js was for native io. I wonder if native IO works if it's done in node but the interface is wasm for purposes of Bull Bitcoin exchange's persistence. I bet it would still work because the closure is just a function pointer.

Ah I see, yes I think that works for the reason you mentioned. FWIW we could just generate native node bindings using napi-rs like we did for test-utils, but I think uniffi-bindgen-react-native gives us more options if we want to extend the bindings to web wallets or React Native in the future while keeping with our uniffi-all-the-things approach.

DanGould · 2025-11-19T22:14:11Z

payjoin-ffi/javascript/test/integration.test.ts

only 570 lines is impressive stuff!

DanGould · 2025-11-19T22:15:27Z

.codespellrc

nit: put this commit before the offending commit so that no intermediate commits fail ci

chavic · 2025-11-20T09:20:49Z

This is some awesome work, gonna see if there's anything I can catch, probably minor things

chavic · 2025-11-20T09:22:32Z

payjoin-ffi/javascript/README.md

The new README under javascript/ still opens with “Payjoin Dart Bindings”

Good catch, thanks!

This includes: - package.json with uniffi-bindgen-react-native and other relevant dependencies. It also includes several npm commands to generate the bindings. - A minimal ubrn.config.yaml to generate bindings for node.js. - tsconfig.json instructions for the `tsc` compiler. - wasm-manifest-patch.toml ensures that the generated WASM crate uses the local payjoin crates for development. - fix-imports.js is a sad workaround for node.js-compatible imports. - generate_bindings.sh is a helper following the pattern established in python/ and dart/ bindings. For MacOS it's necessary to use llvm's clang because Apple's clang doesn't have a WASM backend.

This is a drop-in replacement for compatibility with WASM targets wherever core components use std::time. `io` is already incompatible with WASM due to the tokio `net` dependency, so I left that import of `std::time` unchanged.

Robot ported these from the python tests.

The `io` feature is incompatible with WASM due to the tokio `net` dependency.

uniffi-dart has a built-in tokio dependency which is incompatible with WASM. We should investigate whether that dependency is necessary for uniffi-dart or how it might be feature-gate, but for now just feature gate uniffi-dart here.

This allows conditionally enabling the `getrandom/js` feature flag to avoid bloat on other platforms https://docs.rs/getrandom/latest/getrandom/#webassembly-support. getrandom is already an implicit dependency and unfortunately Cargo doesn't support enabling feature flags on transitive dependencies directly, so it must be added to the explicit dependencies.

payjoin-test-utils requires native I/O for networking operations, process spawning, and filesystem operations. WASM cannot support these, so the JS payjoin bindings do not include test utils (or any io for that matter). This is problematic for writing integration tests. This commit introduces a new, thin binding layer exclusively for payjoin-test-utils, that compiles to a native Node.js add-on. The production code stays as WASM (via uniffi-bindgen-react-native) for cross-platform compatibility, and the test infrastructure is available via platform-specific binaries generated by napi-rs.

spacebear21 · 2025-11-20T22:34:15Z

Thanks for the reviews @DanGould and @chavic, I think I addressed all of your comments in the latest push and replies.

DanGould · 2025-12-29T05:15:51Z

There are still two open checks here, do they need their own issues? or tracking?

spacebear21 · 2025-12-29T10:45:13Z

Good point, made an issue for io in JS #1250. The upstream change is tracked here jhugman/uniffi-bindgen-react-native#324 but we are pointing at a git rev for now, that check was for me to remember to make an upstream PR.

spacebear21 marked this pull request as draft November 13, 2025 20:13

spacebear21 force-pushed the ffi-javascript branch 5 times, most recently from 1aa3218 to b7e4521 Compare November 14, 2025 17:46

spacebear21 mentioned this pull request Nov 14, 2025

package.json and tsconfig.json module values conflict jhugman/uniffi-bindgen-react-native#324

Open

spacebear21 force-pushed the ffi-javascript branch 5 times, most recently from d835e8b to dcae416 Compare November 19, 2025 00:42

spacebear21 marked this pull request as ready for review November 19, 2025 00:56

spacebear21 changed the title ~~Ffi javascript~~ Add javascript language bindings Nov 19, 2025

spacebear21 requested review from DanGould, arminsabouri and chavic November 19, 2025 00:57

This was referenced Nov 19, 2025

Compare to payjoin-ffi javascript bindings Horus-Org/payjoin-react-native#98

Open

PayJoin hsjoberg/blixt-wallet#1262

Open

DanGould reviewed Nov 19, 2025

View reviewed changes

DanGould approved these changes Nov 19, 2025

View reviewed changes

chavic reviewed Nov 20, 2025

View reviewed changes

spacebear21 added 6 commits November 20, 2025 12:07

Ignore package-lock.json in spell checker

f5f8b8f

Use web-time for wasm targets instead of std::time

98b7697

This is a drop-in replacement for compatibility with WASM targets wherever core components use std::time. `io` is already incompatible with WASM due to the tokio `net` dependency, so I left that import of `std::time` unchanged.

Port unit tests for JS bindings

ea1fc17

Robot ported these from the python tests.

Feature gate io in payjoin-ffi

85c63a2

The `io` feature is incompatible with WASM due to the tokio `net` dependency.

Feature gate uniffi-dart in payjoin-ffi

1d7da1a

uniffi-dart has a built-in tokio dependency which is incompatible with WASM. We should investigate whether that dependency is necessary for uniffi-dart or how it might be feature-gate, but for now just feature gate uniffi-dart here.

spacebear21 added 5 commits November 20, 2025 14:29

Add javascript github workflow

990930b

Update payjoin-ffi READMEs

4568bb4

Add TS integration test

cf265f8

nothingmuch mentioned this pull request Nov 20, 2025

Add no_std support #942

Open

spacebear21 force-pushed the ffi-javascript branch from dcae416 to cf265f8 Compare November 20, 2025 22:23

spacebear21 mentioned this pull request Nov 20, 2025

Shared test vectors in bindings tests #1199

Open

spacebear21 merged commit b05365a into payjoin:master Nov 21, 2025
16 checks passed

This was referenced Nov 25, 2025

Bull Bitcoin x Payjoin Tracking Issue #1206

Open

Support WASM with wasm_bindgen and conditional compilation #740

Closed

Add javascript language bindings #1190

Add javascript language bindings #1190

Uh oh!

Conversation

spacebear21 commented Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coveralls commented Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 19553229768

Details

💛 - Coveralls

Uh oh!

DanGould 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!

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!

DanGould left a comment

Choose a reason for hiding this comment

Uh oh!

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!

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!

chavic commented Nov 20, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

spacebear21 commented Nov 20, 2025

Uh oh!

Uh oh!

DanGould commented Dec 29, 2025

Uh oh!

spacebear21 commented Dec 29, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

spacebear21 commented Nov 13, 2025 •

edited

Loading

coveralls commented Nov 13, 2025 •

edited

Loading