feat(boltz): Boltz submarine & reverse swaps by coreyphillips · Pull Request #116 · synonymdev/bitkit-core

coreyphillips · 2026-06-26T14:36:29Z

Summary

Adds a boltz module integrating Boltz submarine (onchain → Lightning) and reverse (Lightning → onchain) swaps behind the UniFFI surface, for iOS/Android/Python.

The dangerous cryptography (MuSig2 Taproot cooperative signing, swap scripts, claim/refund tx construction) is delegated to the boltz-client crate. This module adds deterministic key management, SQLite persistence, lifecycle tracking, automatic claiming, and the FFI surface.

Key design decision: deterministic keys, no stored secrets

Swap keys and reverse-swap preimages are derived from the wallet seed via Boltz's BIP85 scheme (SwapMasterKey/derive_swapkey, Preimage::from_swap_key) — never random, never persisted. boltz.db stores only a monotonic per-swap derivation index.

Consequences:

A leaked database cannot move funds (it holds no key material).
Swaps are recoverable two ways: same-device (index + in-memory seed), or seed-only via Boltz's rescue API if boltz.db is lost.
The wallet mnemonic (+ optional BIP39 passphrase) now flows through the create/claim/refund/start-updates FFI calls. The background updates stream holds the mnemonic in memory only for its lifetime (dropped on stop) to auto-claim. The passphrase must match the wallet's, or derived keys won't control the funds.

Reviewers: please confirm threading the seed through these entry points fits Bitkit's key-handling conventions on the Swift/Kotlin side.

What's included

Submarine create/refund and reverse create/claim, with cooperative key-path → script-path fallback.
Managed WebSocket updates stream; auto-claims reverse swaps on transaction.confirmed (not mempool, to avoid revealing the preimage against an unconfirmed lockup).
Atomic, collision-free swap-index reservation; PRAGMA user_version migration anchor; input validation on create.
Idempotent claim/refund — returns the recorded txid without re-broadcasting.
Typed lifecycle status with forward-compatible Unknown { raw }; recovery/listing APIs.
Only one updates stream (one network) runs at a time — documented.

Testing

cargo build, all 9 boltz unit tests, clippy, and fmt are clean. Tests cover status mapping, DB round-trip/recovery, monotonic index reservation, and deterministic derivation. An ignored live E2E test creates a real reverse swap and cryptographically validates the locally-derived redeem script + invoice against Boltz's response (no broadcast).

Known follow-up: the claim/refund broadcast paths are not yet covered by an automated test — they need a regtest Boltz + Electrum stack. Recommended as a follow-up.

Integrate Boltz submarine (onchain -> Lightning) and reverse (Lightning -> onchain) swaps behind the UniFFI surface. Swap keys and reverse-swap preimages are derived deterministically from the wallet seed via Boltz's BIP85 scheme (SwapMasterKey/derive_swapkey, Preimage::from_swap_key). No key material is persisted: boltz.db stores only a monotonic per-swap derivation index, so a leaked database cannot move funds and swaps are recoverable from the seed alone (or via Boltz's rescue API if boltz.db is lost). - Submarine create/refund and reverse create/claim, with cooperative key-path then script-path fallback (delegated to boltz-client). - Managed WebSocket updates stream that auto-claims confirmed reverse swaps; mnemonic held in memory only for the stream's lifetime. - Atomic, collision-free swap-index reservation; schema user_version anchor; input validation on create. - Idempotent claim/refund (returns the recorded txid without re-broadcasting). - SQLite persistence, typed lifecycle status with forward-compatible Unknown { raw }, and recovery/listing APIs. - Unit tests for status mapping, DB round-trip, index reservation, and deterministic derivation; ignored live E2E test against the Boltz API.

ovitrif

reviewed the current draft, added a few considerations in scoped review comments

Add fee_rate_sat_per_vb to boltz_start_swap_updates so the wallet provides the fee rate used for automatic reverse-swap claims; core does no fee estimation. The rate is threaded through AutoClaimConfig into the auto-claim and falls back to the conservative default when None. Update the README signature and examples accordingly.

…terministic-keys

set_claim_tx and set_refund_tx previously updated only the tx id column, so a claimed or refunded swap kept its pre-claim status (the status column is otherwise advanced only by the live updates stream). They now also set the terminal transaction.claimed / transaction.refunded status, so claimed and refunded swaps report the correct state and drop out of the pending set.

…terministic-keys

Recording a claim or refund tx id now also advances the swap to its terminal status, so the test assertions for the pre-claim status and the pending set were stale. Also covers set_refund_tx, which was untested.

Rebuild the swap script from our own key and check it against the address Boltz returned, before the record is stored or the response reaches the caller. A submarine caller is about to fund the lockup address and a reverse caller is about to pay the invoice, so validating any later would still let the app act on a bad response.

Reading claim_tx_id, broadcasting, then recording the txid spans several await points, so the automatic claim from the updates stream and a manual recovery call could both see no recorded txid and both broadcast. Route both through guarded entry points that hold a per-swap lock across the whole read-broadcast-record sequence and re-read the record under it, so the second caller returns the first one's txid instead of broadcasting again.

Adds new public API (the boltz exports), so this is a minor bump. The iOS, Android and Python bindings now carry the boltz surface, which the checked-in artifacts were missing. Stop tracking the xcframework's static libraries. Linking boltz-client grew them past GitHub's 100 MB file limit, and they only duplicate the compressed copies inside BitkitCore.xcframework.zip, which is the archive Package.swift downloads from the release.

…terministic-keys # Conflicts: # Cargo.lock # Cargo.toml # Package.swift # bindings/android/gradle.properties # bindings/android/lib/src/main/jniLibs/arm64-v8a/libbitkitcore.so # bindings/android/lib/src/main/jniLibs/armeabi-v7a/libbitkitcore.so # bindings/android/lib/src/main/jniLibs/x86/libbitkitcore.so # bindings/android/lib/src/main/jniLibs/x86_64/libbitkitcore.so # bindings/ios/BitkitCore.xcframework.zip # bindings/ios/BitkitCore.xcframework/ios-arm64-simulator/libbitkitcore.a # bindings/ios/BitkitCore.xcframework/ios-arm64/libbitkitcore.a # bindings/python/bitkitcore/libbitkitcore.dylib # bindings/python/setup.py

…terministic-keys

coreyphillips · 2026-07-15T17:24:05Z

Latest release for testing can be found as v0.5.1 here.

ovitrif

I focused this review on the Boltz feature behavior and its fund-recovery paths. I left six scoped comments covering response validation, recovery state, updates lifecycle, input validation, and the documented FFI signature.

…m lifecycle - Bind the Bitcoin response terms boltz-client's validate leaves open: submarine script hashlock vs invoice payment hash, reverse script hashlock vs our preimage, and reverse invoice amount vs the requested amount_sat, with consistent-but-wrong response fixtures covering each - Validate the reverse claim address against the selected network before the create request; same for refund addresses before construction - Require a finite, positive fee rate before starting updates or constructing a claim/refund - Judge recovery by local completion: a settled reverse swap stays in the pending set until its claim txid is recorded locally, the updates stream retries such claims, and server updates no longer overwrite a locally recorded completion status - Serialize updates-stream replacement under the stream slot lock and abort superseded streams' tasks, with a concurrent-start test - Document the acceptZeroConf argument in the README table and examples

Takes master's Android publishing fixes (ELF build ids in .cargo/config.toml and the 16 KB-compatible gradle-publish workflow) and resolves the version and binary-artifact conflicts in favor of this branch: - Version stays 0.5.2 (master moved to 0.4.4 on the 0.4.x line; this branch bumped minor for the new boltz API) across Cargo.toml, Package.swift, gradle.properties and setup.py - Checked-in binaries (Android .so, iOS xcframework zip, Python dylib) stay at this branch's builds since they carry the boltz exports the committed binding sources reference; the next release build will regenerate them with master's linker flags included - The expanded xcframework static libraries stay deleted and gitignored (they exceed GitHub's 100 MB file limit; the zip is the SPM source)

- Bumps version to 0.5.3 - Updates bindings accordingly

ovitrif

Looks good overall. I left two non-blocking nits around refund metadata persistence and the stream-lifecycle test.

Store the validated refund address as the swap's onchain_address when recording a submarine refund, so boltzGetSwap and boltzListSwaps return the refund destination after completion, and cover the round-trip in the db tests. Await both wait_for_live_tasks calls in the concurrent-starts test; the futures were previously dropped without running, so the shutdown checks never executed.

coreyphillips · 2026-07-30T12:20:04Z

New build and version bump incoming...

- Bumps version to 0.5.4 - Updates bindings accordingly

coreyphillips · 2026-07-30T12:54:45Z

Updated build/bindings here.

coreyphillips changed the title ~~feat(boltz): Boltz submarine & reverse swaps with deterministic keys~~ feat(boltz): Boltz submarine & reverse swaps Jun 26, 2026

ovitrif reviewed Jun 30, 2026

View reviewed changes

Comment thread src/modules/boltz/api.rs

Comment thread src/lib.rs

Comment thread src/lib.rs Outdated

coreyphillips added 8 commits June 30, 2026 10:20

Merge remote-tracking branch 'origin/master' into feat/boltz-swaps-de…

937996e

…terministic-keys

Merge remote-tracking branch 'origin/master' into feat/boltz-swaps-de…

ef7612d

…terministic-keys

fix(boltz): update db test for terminal status on claim and refund

86a9441

Recording a claim or refund tx id now also advances the swap to its terminal status, so the test assertions for the pre-claim status and the pending set were stale. Also covers set_refund_tx, which was untested.

coreyphillips marked this pull request as ready for review July 14, 2026 16:16

coreyphillips added 5 commits July 15, 2026 08:13

chore: update bindings

0525f80

chore: regenerate bindings after merging master's onchain fix

a36eafc

Merge remote-tracking branch 'origin/master' into feat/boltz-swaps-de…

0e02949

…terministic-keys

chore: bump to 0.5.1 and regenerate bindings

158caf0

coreyphillips added 4 commits July 17, 2026 11:43

fix: reconcile swap status on subscribe

2bf8d4f

chore: bump to 0.5.2

eb3842e

feat: add instant claim and periodic reconcile

e41fa96

chore: update bindings

fdc2341

ovitrif self-requested a review July 27, 2026 14:12

ovitrif reviewed Jul 27, 2026

View reviewed changes

Comment thread src/modules/boltz/api.rs Outdated

Comment thread src/modules/boltz/db.rs Outdated

Comment thread src/modules/boltz/listener.rs

Comment thread src/modules/boltz/api.rs Outdated

Comment thread src/modules/boltz/claim.rs

Comment thread src/modules/boltz/README.md Outdated

coreyphillips added 3 commits July 28, 2026 08:42

chore: update bindings

4c859d3

- Bumps version to 0.5.3 - Updates bindings accordingly

coreyphillips requested a review from ovitrif July 28, 2026 16:03

ovitrif approved these changes Jul 30, 2026

View reviewed changes

Comment thread src/modules/boltz/refund.rs Outdated

Comment thread src/modules/boltz/listener.rs Outdated

chore: update bindings

43e9c1b

- Bumps version to 0.5.4 - Updates bindings accordingly

coreyphillips merged commit 7e98498 into master Jul 30, 2026
1 check passed

coreyphillips deleted the feat/boltz-swaps-deterministic-keys branch July 30, 2026 12:54

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(boltz): Boltz submarine & reverse swaps - #116

feat(boltz): Boltz submarine & reverse swaps#116
coreyphillips merged 23 commits into
masterfrom
feat/boltz-swaps-deterministic-keys

coreyphillips commented Jun 26, 2026

Uh oh!

ovitrif left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coreyphillips commented Jul 15, 2026 •

edited

Loading

Uh oh!

ovitrif left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ovitrif left a comment

Uh oh!

Uh oh!

Uh oh!

coreyphillips commented Jul 30, 2026

Uh oh!

coreyphillips commented Jul 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

coreyphillips commented Jun 26, 2026

Summary

Key design decision: deterministic keys, no stored secrets

What's included

Testing

Uh oh!

ovitrif left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coreyphillips commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ovitrif left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ovitrif left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

coreyphillips commented Jul 30, 2026

Uh oh!

coreyphillips commented Jul 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

coreyphillips commented Jul 15, 2026 •

edited

Loading