feat: port payjoin core to no_std by caarloshenriq · Pull Request #1615 · payjoin/rust-payjoin

caarloshenriq · 2026-06-07T02:19:10Z

Summary

This is a implementation of no_std support for the payjoin crate,
enabling its use on embedded devices

As discussed in #942, running payjoin logic on a hardware signer enables
stronger security guarantees: the device can verify the fallback transaction,
compare it against the payjoin proposal, and only sign previously-approved
inputs — without trusting the host machine.

Feature Architecture

A new v2-std feature was introduced to separate the state machine logic
from networking dependencies:

Feature	Description
`alloc`	bare metal support, state machine logic only
`v2`	async payjoin session logic without networking
`v2-std`	`v2` + networking (`url`, `ohttp`, `hpke`, `bhttp`, `http`)
`std`	full std support with `tokio`, `serde_json`, `bitcoin/base64`

Verified Build Targets

cargo build -p payjoin --no-default-features --features v2,alloc
cargo build -p payjoin --no-default-features --features v2,alloc --target thumbv7em-none-eabihf-p payjoin
cargo build -p payjoin --no-default-features --features v2,std

Notes for Reviewers

Please review commit by commit:

refactor: introduce no_std/alloc feature split in payjoin core
The main structural change — replaces std:: with core::/alloc:: and gates std-only deps behind #[cfg(feature = "std")] or #[cfg(feature = "v2-std")].

fix: gate v2 std-only code behind cfg features
Extends gating to v2 send/receive and persist. Key decisions: HasReplyableError now carries fallback_tx in both configs to preserve fallback through replay; MaybeSuccessTransition::deconstruct uses Save instead of SaveAndClose on success.

fix: update payjoin-ffi for no_std feature split
Minimal FFI updates to match new AsyncSessionPersister bounds.

fix: restore OHTTP test constants and enable v2 feature in test utils
KEM, KEY_ID, SYMMETRIC were dropped upstream without updating internal tests. Restores them in payjoin-test-utils/src/v2.rs.

chore: update CI, lock files and flake for no_std targets
Adds thumbv7em-none-eabihf to CI and ARM cross-toolchain to the Nix dev shell.

AI Assistance

This implementation was developed with AI assistance (Claude, Anthropic).

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](https://github.com/bitcoin/bitcoin/blob/master/CONTRIBUTING.md#committing-patches).

coveralls · 2026-06-07T02:26:09Z

Coverage Report for CI Build 31185032353

Warning

No base build found for commit c50dd7e on master.
Coverage changes can't be calculated without a base build.
If a base build is processing, this comment will update automatically when it completes.

Coverage: 86.161%

Details

Patch coverage: 107 uncovered changes across 15 files (320 of 427 lines covered, 74.94%).

Uncovered Changes

Top 10 Files by Coverage Impact	Changed	Covered	%
payjoin/src/core/send/v2/mod.rs	64	38	59.38%
payjoin/src/core/persist.rs	83	69	83.13%
payjoin/src/core/uri/v2.rs	51	37	72.55%
payjoin/src/core/send/v2/error.rs	11	0	0.0%
payjoin/src/core/receive/v2/mod.rs	19	10	52.63%
payjoin/src/core/send/error.rs	22	14	63.64%
payjoin/src/core/ohttp.rs	9	4	44.44%
payjoin/src/core/uri/mod.rs	108	103	95.37%
payjoin/src/core/error.rs	6	2	33.33%
payjoin/src/core/time.rs	5	1	20.0%
Total (25 files)	427	320	74.94%

Coverage Regressions

Requires a base build to compare against. How to fix this →

Coverage Stats


Relevant Lines:	16475
Covered Lines:	14195
Line Coverage:	86.16%
Coverage Strength:	343.76 hits per line

💛 - Coveralls

DanGould · 2026-06-07T03:59:39Z

Great to see this take off here. My biggest question is about v2-std which expresses that it's about "networking" but really it's the wire serialization. Is it possible to use the library without that? I'm not sure it is.

benalleng

Looks like a good start, though there are some feature organizations I have some questions about.

caarloshenriq · 2026-06-10T22:06:41Z

My biggest question is about v2-std which expresses that it's about "networking" but really it's the wire serialization. Is it possible to use the library without that? I'm not sure it is.

After reviewing the code, v2-std as a standalone feature had no clear use case, any consumer that needs OHTTP networking will reach for v2-ohttp or io, and v2-std alone didn't even compile correctly due to untested feature combinations. I've collapsed v2-std into v2-ohttp, simplifying the feature hierarchy to: alloc → v2 → v2-ohttp → io.

benalleng

Tested on a RPI Pico 2. It is a limited test that proves compilation and the ShortId round trip to begin the payjoin process.

$ sudo nix develop ~/rust-payjoin#embedded -c bash -c 'picotool uf2 convert --family absolute ~/payjoin-pico2-test/target/thumbv8m.main-none-eabihf/release/payjoin-pico2-test -t elf /tmp/main.uf2 && picotool load --ignore-partitions -x /tmp/main.uf2'
warning: Git tree '~/rust-payjoin' is dirty
Loading into Flash:   [==============================]  100%

The device was rebooted to start the application.
$ cat /dev/ttyACM0 


=== payjoin no_std (v2) on RP2350 ===

ShortId bytes: 4242424242424242

ShortId bech32m: GFPYYSJZGFPYY

round-trip ok: true

mailbox id bytes: 7f2f54ff94459f3a

mailbox id bech32m: 0UH4FLU5GK0N5

=== done ===

I created this repo to demonstrate my steps to get here. https://github.com/benalleng/payjoin-pico2

benalleng · 2026-06-29T19:49:03Z

I did add an additional target thumbv8m.main-none-eabihf in the embedded toolchain and picotool as an additional dev shell dep for working on the pico 2 directly but not totally sure if we need to make these first party requirements in our shell just for the pico

caarloshenriq · 2026-06-30T15:57:23Z

Tested on a RPI Pico 2. It is a limited test that proves compilation and the ShortId round trip to begin the payjoin process.

$ sudo nix develop ~/rust-payjoin#embedded -c bash -c 'picotool uf2 convert --family absolute ~/payjoin-pico2-test/target/thumbv8m.main-none-eabihf/release/payjoin-pico2-test -t elf /tmp/main.uf2 && picotool load --ignore-partitions -x /tmp/main.uf2'
warning: Git tree '~/rust-payjoin' is dirty
Loading into Flash:   [==============================]  100%

The device was rebooted to start the application.
$ cat /dev/ttyACM0 


=== payjoin no_std (v2) on RP2350 ===

ShortId bytes: 4242424242424242

ShortId bech32m: GFPYYSJZGFPYY

round-trip ok: true

mailbox id bytes: 7f2f54ff94459f3a

mailbox id bech32m: 0UH4FLU5GK0N5

=== done ===

I created this repo to demonstrate my steps to get here. https://github.com/benalleng/payjoin-pico2

Thanks for testing this against the branch directly, and for putting together the payjoin-pico2-test repo as a reference.

One note on target coverage: this is thumbv8m.main-none-eabihf, while CI targets thumbv7em-none-eabihf. Both are ARM no_std, but different architecture revisions, so an M4F test would still be ood to have before considering hardware coverage complete. I bought an STM32F411 board for that.

caarloshenriq · 2026-06-30T16:04:27Z

I did add an additional target thumbv8m.main-none-eabihf in the embedded toolchain and picotool as an additional dev shell dep for working on the pico 2 directly but not totally sure if we need to make these first party requirements in our shell just for the pico

On thumbv8m and picotool in the embedded devShell: agreed these probably shouldn't be first-party requirements just for Pico support. The PR's declared target is thumbv7em-none-eabihf, so I'd lean toward keeping the devShell scoped to that and letting Pico-specific tooling live in your payjoin-pico2-test repo instead. Open to hearing if there's a reason to keep them in-tree though, if you think other contributors testing on Pico hardware would benefit.

caarloshenriq · 2026-07-03T18:15:27Z

Tested on a WeAct STM32F411CEU6 Black Pill (Cortex-M4F, thumbv7em-none-eabihf), the PR's declared CI target.

$ sudo $(which dfu-util) -a 0 -s 0x08000000:leave -D target/thumbv7em-none-eabihf/release/payjoin-blackpill-test
dfu-util 0.11

Opening DFU capable USB device...
Device ID 0483:df11
Downloading element to address = 0x08000000, size = 134132
Erase           [=========================] 100%       134132 bytes
Erase    done.
Download        [=========================] 100%       134132 bytes
Download done.
File downloaded successfully
Submitting leave request...
Transitioning to dfuMANIFEST state

The test exercises ShortId round-trip and SHA256 → mailbox ID derivation on bare-metal, with no std. I created https://github.com/caarloshenriq/payjoin-blackpill-test to document the steps.

The v1 feature required std unconditionally, even though the protocol itself has no networking or OS dependency: it is plain byte-in/byte-out request/response handling, making it the natural fit for the no_std embedded receiver/sender work in this branch. Port the v1 send and receive paths to alloc-only: - Change the v1 feature to depend on alloc instead of std. - Gate the handful of genuinely std-only APIs (PjUri construction, SenderBuilder::new) behind std, leaving SenderBuilder::from_parts and PjParam::parse as the no_std entry points. - Replace bitcoin's Psbt FromStr/Display, which pulls in std through bitcoin's base64 feature, with direct use of a no_std-configured base64 crate on top of PSBT's existing binary (de)serialization. Shared with the v2 receive path, which used the same std-only entry point. - Fix several imports and cfg gates that were tied to std without a real std dependency (FeeRate, Version, FromStr, format!, and the query-string parsing in Params::from_query_str). - Simplify from_query_str's query parsing to avoid a percent-decoding dependency that is itself std-only; BIP78 query parameters don't need percent-decoding in practice. - Add a no_std fallback for ResponseError parsing, since the well-known JSON error format requires serde_json (std-only); it reports a generic parse failure instead of the decoded reason.

Add payjoin/tests/e2e.rs with two independent round trip tests, split into cfg-gated submodules since v1 and v2 have different feature requirements: - v1: runs entirely in memory under the no_std-compatible alloc,v1 feature set. Drives the full sender and receiver typestate chain with no OHTTP or directory involved, since v1 is plain request/response bytes. This is the test that actually exercises the no_std surface end to end, not just at compile time. - v2: cannot run under that restricted feature set, since the sender side of v2 still requires v2-ohttp/std. Instead this proves that the receiver side, driven by a real OHTTP-encapsulated request from a real sender, walks the same typestate chain already verified to compile for thumbv7em-none-eabihf. Uses a small in-memory stand-in for the directory and OHTTP relay (decapsulate, route GET/POST against a single-message mailbox, re-encapsulate) instead of the real local servers tests/integration.rs already spins up, so it stays fast and dependency-free. Both tests have the receiver contribute a real input from its own UTXO before finalizing, rather than only fee-bumping the original PSBT, so they exercise an actual payjoin (combined inputs from both parties) and not just protocol plumbing. Wire both into contrib/test.sh: the v2 module runs as part of the --all-features e2e run, and v1 gets its own explicit --no-default-features --features alloc,v1 invocation, since that's the only place the no_std guarantee is actually exercised at runtime rather than just checked at compile time.

Align cfg gates for Uri/PjUri and their bitcoin_uri-backed adapters with the crate's actual feature dependencies (std, v1, v2-ohttp), fixing build failures under alloc-only and v1-only configurations that were not caught until running check-nostd/check-nostd-v1.

Add a "Build embedded target v1" step alongside the existing v2 step so CI exercises both feature combinations (alloc,v1 and alloc,v2) against the thumbv7em-none-eabihf no_std target, matching the two combinations already covered by local check-nostd/check-nostd-v1 bacon jobs. Set CARGO_PROFILE_DEV_DEBUG=0 for both steps. secp256k1-sys's build script (via cc-rs) injects -fno-omit-frame-pointer and -mno-omit-leaf-frame-pointer for GCC when Cargo's DEBUG env var is set. The latter flag does not exist on arm-none-eabi-gcc, which only supports it on x86/AArch64, so the build fails whenever dependency resolution picks a cc version that adds this flag. This does not reproduce locally because a resolved Cargo.lock is not committed, so CI is exposed to any new cc release changing this behavior while a local checkout stays pinned to whatever cc version was first resolved. This only affects the payjoin core no_std compilation check in CI and has no effect on payjoin-no-std-harness firmware builds used to flash real hardware, which are built separately with debug symbols intact.

benalleng reviewed Jun 7, 2026

View reviewed changes

Comment thread payjoin/Cargo.toml

Comment thread payjoin-test-utils/Cargo.toml Outdated

Comment thread payjoin/Cargo.toml Outdated

Comment thread flake.nix Outdated

Comment thread flake.nix Outdated

Comment thread payjoin/Cargo.toml Outdated

benalleng linked an issue Jun 8, 2026 that may be closed by this pull request

Add no_std support #942

Open

benalleng removed a link to an issue Jun 8, 2026

Add no_std support #942

Open

caarloshenriq force-pushed the feat/payjoin-nostd branch from 249f524 to 04f34f6 Compare June 10, 2026 19:30

benalleng reviewed Jun 10, 2026

View reviewed changes

Comment thread .github/workflows/rust.yml Outdated

caarloshenriq force-pushed the feat/payjoin-nostd branch from 853bb38 to c0c2149 Compare June 10, 2026 21:47

caarloshenriq force-pushed the feat/payjoin-nostd branch 2 times, most recently from 504491c to 082564e Compare June 12, 2026 18:28

caarloshenriq force-pushed the feat/payjoin-nostd branch 2 times, most recently from 69d72e6 to 37bb1e8 Compare June 18, 2026 18:03

caarloshenriq requested a review from benalleng June 18, 2026 18:43

benalleng reviewed Jun 28, 2026

View reviewed changes

benalleng mentioned this pull request Jul 3, 2026

Add no_std support #942

Open

benalleng added the enhancement New feature or request label Jul 16, 2026

caarloshenriq force-pushed the feat/payjoin-nostd branch from 37bb1e8 to 641926c Compare July 16, 2026 23:38

caarloshenriq marked this pull request as draft July 16, 2026 23:40

caarloshenriq force-pushed the feat/payjoin-nostd branch from daa5aa6 to 4377a7b Compare July 20, 2026 16:42

caarloshenriq marked this pull request as ready for review July 20, 2026 16:56

caarloshenriq force-pushed the feat/payjoin-nostd branch from 4377a7b to fe7a432 Compare July 21, 2026 12:44

caarloshenriq force-pushed the feat/payjoin-nostd branch from fe7a432 to f786785 Compare August 4, 2026 17:14

caarloshenriq added 3 commits August 6, 2026 15:25

refactor: introduce no_std/alloc feature split in payjoin core

d7b7a6c

fix: gate v2 std-only code behind cfg features

b2129af

feat: declare nostd feature in payjoin/Cargo.toml

b07231a

caarloshenriq added 5 commits August 6, 2026 15:25

chore: update CI, lock files and flake for no_std targets

cfd8ea7

chore: use nix develop .#embedded for CI embedded build

ccfb676

caarloshenriq force-pushed the feat/payjoin-nostd branch from f786785 to 1286678 Compare August 7, 2026 13:55

Navigation Menu

Uh oh!

feat: port payjoin core to no_std - #1615

feat: port payjoin core to no_std#1615
caarloshenriq wants to merge 9 commits into
payjoin:masterfrom
caarloshenriq:feat/payjoin-nostd

caarloshenriq commented Jun 7, 2026

Uh oh!

coveralls commented Jun 7, 2026 •

edited

Loading

Uh oh!

DanGould commented Jun 7, 2026

Uh oh!

benalleng left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

caarloshenriq commented Jun 10, 2026

Uh oh!

benalleng left a comment

Uh oh!

benalleng commented Jun 29, 2026

Uh oh!

caarloshenriq commented Jun 30, 2026

Uh oh!

caarloshenriq commented Jun 30, 2026

Uh oh!

caarloshenriq commented Jul 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

caarloshenriq commented Jun 7, 2026

Summary

Feature Architecture

Verified Build Targets

Notes for Reviewers

AI Assistance

Uh oh!

coveralls commented Jun 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report for CI Build 31185032353

Coverage: 86.161%

Details

Uncovered Changes

Coverage Regressions

Coverage Stats

💛 - Coveralls

Uh oh!

DanGould commented Jun 7, 2026

Uh oh!

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

caarloshenriq commented Jun 10, 2026

Uh oh!

benalleng left a comment

Choose a reason for hiding this comment

Uh oh!

benalleng commented Jun 29, 2026

Uh oh!

caarloshenriq commented Jun 30, 2026

Uh oh!

caarloshenriq commented Jun 30, 2026

Uh oh!

caarloshenriq commented Jul 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

coveralls commented Jun 7, 2026 •

edited

Loading