Add UniFFI Kotlin bindings for payjoin-ffi by ram0verflow · Pull Request #1869 · payjoin/rust-payjoin

ram0verflow · 2026-09-08T18:05:08Z

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.

What

UniFFI Kotlin/JVM bindings for payjoin-ffi, plus a BIP77 v2 round-trip
integration test.

Layout matches python/csharp:

payjoin-ffi/kotlin/scripts/generate_bindings.sh
payjoin-ffi/kotlin/contrib/test.sh
PAYJOIN_FFI_FEATURES (default _test-utils; empty string is passed
through) and PAYJOIN_FFI_PROFILE (default dev → target/debug)

Generated sources are not committed (gitignored under
kotlin/src/main/kotlin/org/). Generate is a build step.

CI runs inside nix develop .#kotlin (JDK 21, MSRV, nixpkgs bitcoind),
matching csharp/python/dart.

Unit tests (15) cover URIs, persistence, cancel, and validation — the
same count as the Python unit suite. The second commit adds the v2
integration test (16 Gradle tests on HEAD).

Why `[bindings.kotlin.rename]`

Generated UniFFI objects implement Disposable and AutoCloseable, so
close() drops the Rust handle. Payjoin also exports protocol close() on
ReceiverPendingFallback, SenderPendingFallback, and the four JSON
session persister traits. Kotlin cannot overload on return type.

The table is Kotlin-only. It maps those protocol methods to
closeSession(). No Rust API change. Other language bindings keep close.

Integration test

IntegrationTests.kt drives a full BIP77 v2 round trip, sender and
receiver, against the in-process directory, OHTTP relay, and a real
bitcoind. Under the kotlin nix shell, BITCOIND_EXE comes from nixpkgs
and BITCOIND_SKIP_DOWNLOAD=1. Outside the shell, corepc-node may
download Bitcoin Core into a temp regtest dir.

On Linux, v2ToV2Payjoin completes in about 4s.

TestHttp trusts only the directory's rcgen cert and proxies through the
OHTTP relay.

Wrapper pin

Gradle 9.1.0 wrapper is pinned with distributionSha256Sum.
validateDistributionUrl only checks the URL.

Release / publish

Not published anywhere. No pack, Maven, signing, or attestation jobs.

The workflow does not trigger on payjoin-kotlin-* tags. python.yml's
tag trigger runs wheel build, PyPI publish, and GitHub release assets.
Until Kotlin has something to publish, a tag trigger would only re-run
tests.

Follow-ups (out of this PR)

No ktfmt / treefmt registration for .kt
No Windows CI (same as python/dart/javascript)

Disclosure

This PR was written with Cursor Cloud Agent (Grok 4.6).

Code: Kotlin Gradle project, generate/test scripts, nix kotlin
shell, CI workflow, unit tests, and the v2 integration test were
AI-generated and then hand-reviewed against the Python suite and a
known-good round trip (~4s).
PR body: AI-drafted (this text).

Disclosure: co-authored by Cursor Grok 4.6

chavic · 2026-09-10T07:40:58Z

@ram0verflow Thanks, I'll take a look today

coveralls · 2026-09-10T14:38:12Z

Coverage Report for CI Build 34260940347

Warning

Build has drifted: This PR's base is out of sync with its target branch, so coverage data may include unrelated changes.
Quick fix: rebase this PR. Learn more →

Coverage remained the same at 86.64%

Details

Coverage remained the same as the base build.
Patch coverage: No coverable lines changed in this PR.
No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

Coverage Stats


Relevant Lines:	16474
Covered Lines:	14273
Line Coverage:	86.64%
Coverage Strength:	343.37 hits per line

💛 - Coveralls

chavic · 2026-09-10T15:04:31Z

@ram0verflow it looks like you're hitting an unrelated probelm, that's fixed on master, you want to rebase

chavic

A few comments below.

chavic · 2026-09-10T15:33:52Z

+
+tasks.test {
+    useJUnitPlatform()
+    val libDir = layout.projectDirectory.dir("lib").asFile


We should add inputs.file(native) here. Otherwise changing the Rust library without changing the generated Kotlin leaves the tests UP-TO-DATE. Confirmed with an isolated Gradle 9.1 repro.

chavic · 2026-09-10T15:33:53Z

+    @Test
+    fun missingAmountShouldBeOk() {
+        val uri = "bitcoin:12c6DSiU4Rq3P4ZxziKxzrL5LmMBrzjrJX?pj=https://testnet.demo.btcpayserver.org/BTC/pj"
+        assertNotNull(Url.parse(uri))


Should this be Uri.parse()? Same on line 36. Url.parse() accepts invalid Bitcoin addresses, so we're not testing the URI validation here.

chavic · 2026-09-10T15:33:53Z

+Protocol `close` is renamed to `closeSession` only in `[bindings.kotlin.rename]` in
+`payjoin-ffi/uniffi.toml`, so it does not clash with `AutoCloseable.close()`.
+
+A nix `.#kotlin` shell is not in the flake yet. Use a local JDK 21+ and the Gradle wrapper.


This is outdated or mismatched. The PR adds .#kotlin. The README also says nix doesn't supply bitcoind, but the shell sets BITCOIND_EXE. Let's update both.

caarloshenriq

Concept ACK.

Kotlin/JVM bindings alongside the other four is a good addition, and the layout mirrors python/csharp closely enough that it should be easy to keep in sync

caarloshenriq · 2026-09-10T15:33:55Z

+Protocol `close` is renamed to `closeSession` only in `[bindings.kotlin.rename]` in
+`payjoin-ffi/uniffi.toml`, so it does not clash with `AutoCloseable.close()`.
+
+A nix `.#kotlin` shell is not in the flake yet. Use a local JDK 21+ and the Gradle wrapper.


That same commit adds kotlinDevShell and CI runs nix develop .#kotlin.

caarloshenriq · 2026-09-10T15:35:54Z

+
+Or `bash ./contrib/test.sh` from this directory (uses `Cargo-recent.lock`).
+
+`./gradlew test` includes a v2↔v2 integration test that starts a local payjoin directory, OHTTP relay, and bitcoind. Bitcoin Core is downloaded by corepc-node (`29_0`) on first run; it is not supplied by nix.


Bitcoin Core is downloaded by corepc-node (29_0) on first run; it is not supplied by nix.

Inside .#kotlin it is: BITCOIND_EXE points at nixpkgs bitcoind and
BITCOIND_SKIP_DOWNLOAD=1. Reads correct if scoped to "outside the nix shell".

caarloshenriq · 2026-09-10T15:54:24Z

@@ -0,0 +1,38 @@
+plugins {
+    kotlin("jvm") version "2.1.20"


against the Gradle 9.1.0 wrapper pinned in gradle/wrapper/gradle-wrapper.properties: KGP 2.1.20's compatibility table tops out in the 8.x range, so 9.1.0 is outside the versions it is tested against. It may well build clean today, but a KGP bump (2.2.x) would put the pair back in the supported matrix and cost nothing here, since nothing is published yet.

Checked the KGP compatibility table. 2.2.x still caps at Gradle 8.14, so it wouldn't cover the 9.1.0 wrapper. 2.3.0 and 2.3.10 cap at 9.0.0. The first KGP that covers 9.1.0 is 2.3.20 (7.6.3–9.3.0).

ram0verflow · 2026-09-10T16:39:09Z

will fix and update

Generate with in-tree uniffi-bindgen --language kotlin, siloed like Python (no extra cargo feature). Rename protocol close to closeSession in Kotlin only so AutoCloseable still works. Pin the Gradle 9.1.0 wrapper with distributionSha256Sum; validateDistributionUrl only checks the download URL. Add a kotlin nix dev shell (JDK 21, MSRV, bitcoind) and run CI inside it, matching the other language bindings. Unit tests cover URIs, persistence, cancel, and validation.

Drive a full BIP77 round trip against the in-process directory, OHTTP relay, and bitcoind, mirroring the Python suite's RPC sequence and assertions. TestHttp trusts only the self-signed rcgen directory cert so HTTPS through the relay succeeds in the JVM. Parse bitcoind RPC responses with kotlinx-serialization-json.

ram0verflow requested review from DanGould, benalleng and spacebear21 as code owners September 8, 2026 18:05

ram0verflow mentioned this pull request Sep 8, 2026

Java language bindings for payjoin-ffi #1860

Open

chavic requested review from chavic and removed request for DanGould, benalleng and spacebear21 September 10, 2026 14:30

chavic reviewed Sep 10, 2026

View reviewed changes

caarloshenriq suggested changes Sep 10, 2026

View reviewed changes

ram0verflow added 3 commits September 10, 2026 22:48

Address Kotlin bindings review feedback

df8922e

ram0verflow force-pushed the kotlin-bindings-pr branch from a991880 to df8922e Compare September 10, 2026 17:21

Navigation Menu

Uh oh!

Add UniFFI Kotlin bindings for payjoin-ffi - #1869

Add UniFFI Kotlin bindings for payjoin-ffi#1869
ram0verflow wants to merge 3 commits into
payjoin:masterfrom
ram0verflow:kotlin-bindings-pr

ram0verflow commented Sep 8, 2026

Uh oh!

chavic commented Sep 10, 2026

Uh oh!

coveralls commented Sep 10, 2026

Uh oh!

chavic commented Sep 10, 2026

Uh oh!

chavic left a comment

Uh oh!

chavic Sep 10, 2026

Uh oh!

chavic Sep 10, 2026

Uh oh!

chavic Sep 10, 2026 •

edited

Loading

Uh oh!

caarloshenriq left a comment

Uh oh!

caarloshenriq Sep 10, 2026

Uh oh!

caarloshenriq Sep 10, 2026

Uh oh!

caarloshenriq Sep 10, 2026

Uh oh!

ram0verflow Sep 10, 2026

Uh oh!

ram0verflow commented Sep 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		Or `bash ./contrib/test.sh` from this directory (uses `Cargo-recent.lock`).

		`./gradlew test` includes a v2↔v2 integration test that starts a local payjoin directory, OHTTP relay, and bitcoind. Bitcoin Core is downloaded by corepc-node (`29_0`) on first run; it is not supplied by nix.

Uh oh!

Conversation

ram0verflow commented Sep 8, 2026

What

Why [bindings.kotlin.rename]

Integration test

Wrapper pin

Release / publish

Follow-ups (out of this PR)

Disclosure

Uh oh!

chavic commented Sep 10, 2026

Uh oh!

coveralls commented Sep 10, 2026

Coverage Report for CI Build 34260940347

Coverage remained the same at 86.64%

Details

Uncovered Changes

Coverage Regressions

Coverage Stats

💛 - Coveralls

Uh oh!

chavic commented Sep 10, 2026

Uh oh!

chavic left a comment

Choose a reason for hiding this comment

Uh oh!

chavic Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

chavic Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

chavic Sep 10, 2026 • 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!

caarloshenriq left a comment

Choose a reason for hiding this comment

Uh oh!

caarloshenriq Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

caarloshenriq Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

caarloshenriq Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

ram0verflow Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

ram0verflow commented Sep 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Why `[bindings.kotlin.rename]`

chavic Sep 10, 2026 •

edited

Loading