Skip to content

Native FFI builds - #2023

Merged
spacebear21 merged 6 commits into
payjoin:masterfrom
spacebear21:native-build
Nov 6, 2026
Merged

spacebear21 merged 6 commits into
payjoin:masterfrom
spacebear21:native-build

Conversation

@spacebear21

@spacebear21 spacebear21 commented Oct 30, 2026 •

Copy link
Copy Markdown
Collaborator

Supersedes #2016

Combines phases 1 and 2 from #1997

Build every payjoin-ffi native library once per release, check that two builds of each are byte-identical, and ship those exact files through Python, C#, Dart and the GitHub release.

  • contrib/native/build.sh builds the featureless library for 11 targets on Linux in a new .#native devshell, with Rust 1.85.1, Cargo-recent.lock and path remapping.
    contrib/native/README.md documents the rules.
  • native.yml builds each target twice from different paths and fails on any mismatch. A macOS job checks the Apple libraries against Xcode and runs an iOS simulator smoke test. It
    runs daily and in releases, not on PRs.
  • Releases attach the libraries with SHA256SUMS and attestations. payjoin-ffi/VERIFYING.md explains how to check or rebuild them.
  • Python and C# package these files instead of building their own, and check every packed library byte for byte.
  • Dart ships the libraries in the package (26 MiB compressed), so apps need no Rust toolchain. build: source keeps the previous behaviour.

The first three commits are independent of the rest (Dart 16 KB alignment on NDK r27, Rust 1.85.1 for release bindings, Kotlin bindings from the lock) and will also be opened as small PRs.

Validated locally: every target reproduced across two builds with no build paths, the wheel and NuGet replays packed exactly those bytes, and the staged Dart package loaded its
library in prebuilt mode. The macOS job, the macOS and Windows smoke tests, release attestation and upload, and a Flutter app build in prebuilt mode run for the first time in CI.

Pull Request Checklist

Please confirm the following before requesting review:

@coveralls

coveralls commented Oct 30, 2026 •

Copy link
Copy Markdown
Collaborator

Coverage Report for CI Build 42261193754

Coverage remained the same at 87.778%

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

Coverage Status
Relevant Lines: 18466
Covered Lines: 16209
Line Coverage: 87.78%
Coverage Strength: 316.28 hits per line

💛 - Coveralls

@spacebear21
spacebear21 marked this pull request as ready for review November 2, 2026 18:11
@spacebear21
spacebear21 requested a review from chavic November 2, 2026 18:11
@spacebear21

Copy link
Copy Markdown
Collaborator Author

@ethicnology I'd like to hear your thoughts on this since BBM is the main consumer it affects:

Currently the payjoin package pub.dev compiles rust-payjoin locally from source (reproducibly as of #1996).

This PR would make prebuilt native libraries the default mode for the dart package, but also leaves a build: source option that keeps the build-from-source mode available.

With the default prebuilt mode, CI builds them twice from different paths and they must be byte-identical, they are attached to the GitHub release with SHA256SUMS and attestations. Your APK builds would still reproduce, since both builds bundle the same library, but your app would contain our compiled library instead of one built by your toolchain.

I'm on the fence about keeping the build: source mode, where the hook compiles payjoin locally from a locked graph as 0.25.1 does today. Keeping it costs a fair amount of maintenance: the shipped Rust crate and lockfile, the lock staging, and a CI job dedicated to source build reproducibility.

Would Bull Bitcoin be OK using the prebuilt libraries, as long as they are reproducible, or do you need to compile payjoin from source yourselves, for example for a "built from source" policy or a future F-Droid listing?

@ethicnology

Copy link
Copy Markdown
Contributor

We can use the pre-built binaries but we will need to build from source in order to satisfy a future F-Droid listing SatoshiPortal/bullbitcoin-mobile#297

@spacebear21

Copy link
Copy Markdown
Collaborator Author

Great to know, thanks! This should be ready to ship as-is then @chavic

chavic
chavic previously approved these changes Nov 6, 2026

@chavic chavic left a comment •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tACK c9e9767

Each binding builds its native libraries in its own job, on its own
runner, with whatever toolchain that job sets up, so no shipped file
can be rebuilt bit for bit. Add one script that builds every shipped
target on Linux with one pinned toolchain:

    contrib/native/build.sh <triple> <out-dir>
Nothing yet checks that build.sh produces the same bytes twice. Build
each target twice, on separate runners. The second build runs from
another checkout path, home and cargo home, all with a space in them,
so any path that leaks into a library breaks the match, including one
from a cache the toolchain keeps under the home directory. A compare
job fails unless the second build matches the first one's hashes.

Once they match, the compare job combines the two macOS slices with
llvm-lipo into universal2-apple-darwin, the file Python ships. lipo
output depends only on its inputs, so the derived file needs no second
build. Every checked library is uploaded as one `payjoin-native`
artifact, laid out by triple, for the bindings to package.

The workflow runs in the daily bindings run and not on pull requests:
two builds of eleven targets is 22 jobs, too many for every PR, so
the scheduled run carries this check.
The Linux builds link against stubs derived from zig's macOS
libSystem, not Apple's SDKs, so a symbol missing on the platform would
link and then fail to load. Nothing has yet loaded these libraries on
an Apple system.

Add a macOS job that verifies the libraries and never produces any:

* Xcode's linker resolves every import of each iOS and macOS library
  against the real SDK of its platform.
* Each library, the universal2 one included, is renamed with
  install_name_tool and signed with codesign, as Flutter does when it
  wraps a dylib in a framework.
* A small Flutter app runs a smoke test in the arm64 simulator. A
  stand-in build hook makes it bundle the Linux-built library, so the
  test goes through Flutter's own embed path with those exact bytes.

The smoke test does not reuse the Dart unit tests, because those call
helpers from the `_test-utils` feature, which the shipped library is
built without.
The release shipped native libraries only inside the wheels and the
NuGet package, and nothing in it came from the native workflow's checked
double build.

The release workflow now calls the native workflow once, and every
publish job waits for it, so a library that does not reproduce or fails
the Apple checks stops the release. The GitHub release job names each
library payjoin_ffi-<version>-<target>.<ext>, attaches all 12, lists
them in SHA256SUMS and attests them, so a consumer can check a library
against the release without unpacking a package. VERIFYING.md explains
how to check one, or rebuild it from the Linux devshell, iOS included,
and compare.
The NuGet native assets were cross-built with their own toolchain:
cargo-zigbuild and cargo-xwin from pip, clang-cl and llvm-lib from the
runner image, Rust 1.85.0, and the `csharp` feature, which only the
bindings generator needs but which changes the library's metadata hash.
The wheel's libraries were built by build-wheel.sh itself: the Linux
one with the python devshell's host cargo, so its glibc floor was
whatever the runner's toolchain linked against, and the universal2
macOS one with cargo-zigbuild, which links with `-g` and needs a
toolchain of its own. None of it followed the native build contract,
so the shipped files could not be rebuilt bit for bit, and they were
not the ones the native workflow had checked.

Both now download the payjoin-native artifact of the same run: the
wheels take the Linux and universal2 files, and the NuGet package takes
one file per RID, which removes the six build-nuget-native jobs, the
pip pins, the clang-cl symlinks and the cross branch of
build_nuget_native.sh. The release and the daily run make python and
csharp wait for native. The per-RID smoke tests still install the
packed nupkg on each platform.

build-wheel.sh now takes the library to bundle as its argument. It
generates the bindings from a development build of the same
featureless library, because uniffi reads its metadata from the static
symbol table, which the zig-linked Linux library lacks. The Linux
library needs at most glibc 2.17, so auditwheel tags the wheel
manylinux_2_17, and the macOS wheel is tagged macosx_10_15_universal2,
the contract's floor, as the changelog notes. The python devshell no
longer cross-links anything, so it drops cargo-zigbuild and the macOS
targets on Linux.

Since the GitHub release lists each library on its own, the wheel build
and the pack job compare every library inside the package with the
native file and fail on any difference. They run before publishing,
which the GitHub release job does not. With that check in place,
SHA256SUMS no longer lists the NuGet members a second time, and
generate-sha256sums.sh loses its archive option, which nothing else
uses.
Every Dart consumer compiled payjoin-ffi with their own Rust toolchain,
so none of them got the library the release checks for
reproducibility, and every app build needed Rust and the targets'
toolchains.

prepare-publish.sh now copies the native workflow's payjoin-native
artifact into the staged package as prebuilt/<target>/<file>, for the
11 targets the hook maps; the universal macOS library is left out. The
release and the daily run make dart wait for native to get it. The 11
libraries add about 26 MiB to the compressed archive, well under
pub.dev's 100 MiB limit.

The build hook now has three modes, chosen by the `build` user define
in the root package's pubspec:

- prebuilt, the default, registers the packaged library for the target.
  The build needs no network, no GitHub and no Rust, so it works
  offline and is hermetic. pub checks the archive against the sha256
  in the consumer's pubspec.lock, and the release attests the staged
  archive. A target without a library is a build error that says how
  to switch to source, never a silent source build.
- source builds the shipped native/Cargo.lock with --locked, as
  consumers did until now.
- workspace builds payjoin-ffi from the checkout with _test-utils, and
  is what the package's own pubspec sets. It replaces the presence of
  .cargo/config.local.toml as the development signal, so a copy of the
  package directory no longer becomes a development build by accident.

Both kinds of library register as uniffi:payjoin_ffi. uniffi-dart's
bindings bind every function with @Native(assetId:), so they resolve
by that id and the file name does not matter.

A prebuilt-linux job runs the consumer program against the staged
package. Pull requests build no release libraries, so the Linux test
job places the host library its tests built under prebuilt/ and runs
the same check. The reproducibility job's consumer now selects source,
which it exists to test.

Because the libraries travel inside the package, publish-dart keeps its
place beside the other publish jobs and the release still needs one
approval. It now also attests the staged package archive the release
attaches, as the other registries attest theirs.
@spacebear21

Copy link
Copy Markdown
Collaborator Author

rebased a changelog conflict @chavic

@spacebear21
spacebear21 requested a review from chavic November 6, 2026 20:03

@chavic chavic left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

re-ACK 9734b87

@spacebear21
spacebear21 merged commit aebecd6 into payjoin:master Nov 6, 2026
40 of 43 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants