feat(boltz): Boltz submarine & reverse swaps

[coreyphillips]

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.

[ovitrif]

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

[ovitrif]

Could we validate the Boltz create response before persisting or returning it? boltz-client exposes response.validate(...) for both submarine and reverse swaps, and that check proves the returned script/address matches our derived key and invoice/preimage before the app sends funds or pays the invoice.

[coreyphillips]

Good catch, done. Both create paths now validate before the response can do any damage.

create_submarine_swap calls response.validate(&invoice, &refund_public_key, network.as_chain()) and create_reverse_swap calls response.validate(&preimage, &claim_public_key, network.as_chain()). Both run immediately after the API call and before insert_swap and before the response is handed back, so a response that fails validation never reaches the database and never reaches the app. That ordering is the point: for submarine swaps the caller is about to fund the lockup address, and for reverse swaps it is about to pay the invoice, so validating after persisting would still let the app act on a bad response.

Failures surface as BoltzError::SwapError with the underlying reason.

One limitation worth stating plainly: I could not exercise this against a live Boltz response. The live_reverse_swap test skips right now because the Boltz testnet API is returning 502 Bad Gateway, so the validation is covered by the type checker and the existing offline tests, not by an observed round trip against a real server. Once testnet is healthy, cargo test modules::boltz -- --ignored will cover it.

[ovitrif]

Since this adds new UniFFI exports and public types, could we bump the package version and regenerate the mobile/Python bindings in this PR? Right now Rust builds, but downstream iOS/Android consumers would not get the new boltz* APIs from the checked-in artifacts.

[coreyphillips]

Done. Bumped to 0.5.0 and regenerated the iOS, Android and Python bindings, so the boltz* APIs are now in the checked-in artifacts.

Minor rather than patch: this PR adds new public API, and build.sh's default patch bump would have collided with the 0.4.1 already sitting on fix/broadcast-return-known-txid.

Version is in sync across Cargo.toml, Package.swift, bindings/android/gradle.properties and bindings/python/setup.py. The generated surfaces now carry the boltz exports, where before they had none: 231 references in bitkitcore.swift, 285 in bitkitcore.android.kt, 429 in the Python module, plus rebuilt native libraries for all four Android ABIs and both iOS slices.

One thing that needs a second opinion, since it changes what the repo tracks. Linking boltz-client grew the xcframework's static libraries from ~98 MB to ~113 MB, which is over GitHub's hard 100 MB per-file limit, so the push was rejected outright. They were already within 2 MB of the limit on master, so this was going to happen on the next dependency regardless. Stripping only got them to 103 MB, still over.

I stopped tracking BitkitCore.xcframework/**/libbitkitcore.a and gitignored it. Those files only duplicate the compressed copies inside BitkitCore.xcframework.zip (76 MB, still committed), and that zip is what Package.swift actually downloads from the GitHub release via binaryTarget(url:checksum:), so no consumer resolves iOS through the expanded directory. Nothing about the SPM consumption path changes.

Worth deciding as a team whether that is the fix you want long term, or whether these binaries should move to Git LFS or out of the repo entirely. The zip is at 76 MB and climbing, so it will hit the same wall eventually.

Separately: build.sh -r --<bump> all fails at the Android step if ANDROID_NDK_HOME points at an NDK that is not installed, and on the way out it deletes the checked-in jniLibs and Kotlin bindings instead of leaving them alone. It also strips [[bin]] example from Cargo.toml and removes example/main.rs, and skips its own cleanup if interrupted. I restored all of that by hand here, but the script could use some hardening.

[ovitrif]

Could we serialize claim/refund attempts per swap, or mark a claim/refund as in progress before broadcasting? As written, auto-claim and a manual recovery call can both see no recorded txid and try to broadcast before either path persists the result.

[coreyphillips]

You are right, and the idempotency check I had was not sufficient. Reading claim_tx_id, broadcasting, then recording the txid spans several .await points (Boltz plus Electrum round trips), so the auto-claim and a manual recovery call could both observe None and both broadcast. Checking harder at the top could not fix that; the check and the write had to become atomic.

Fixed by serializing per swap. New src/modules/boltz/guard.rs keeps a per-swap-id async lock, and claiming and refunding now go through single guarded entry points, claim_reverse_swap_guarded and refund_submarine_swap_guarded. Each one takes the swap's lock, re-reads the record under the lock (the caller's copy may be stale by then), returns the recorded txid if one appeared while it waited, and otherwise broadcasts and persists while still holding the lock.

Both racing paths now funnel through that: boltz_claim_reverse_swap / boltz_refund_submarine_swap in lib.rs, and auto_claim in the listener. Whichever arrives second waits, sees the first one's txid, and broadcasts nothing. The claim path returns a ClaimOutcome so the listener can tell the two cases apart: it only emits BoltzSwapEvent::Claimed when it actually broadcast, rather than double-reporting a claim the manual caller already received.

Tests added:

• a claim of an already-claimed swap returns the recorded txid without broadcasting (the record points at an unreachable Electrum server, so reaching the broadcast path at all would fail the test rather than pass it)
• the same for refunds
• a missing swap reports NotFound
• four concurrent claims of one swap never overlap in the critical section, while locks on different swaps stay independent

Scope: this serializes within the process, which is where the race you identified lives, since both racers are in this library. It is not a cross-process lock.