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

[coreyphillips]

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.

[ovitrif]

I think the current dependency validation leaves several Bitcoin response terms unbound: submarine validation does not compare the script hashlock with the invoice, while reverse validation does not compare the script hashlock with the preimage or the invoice amount with amount_sat. Could we add those checks before returning payment details, with focused mismatched-response tests?

[coreyphillips]

Confirmed, and worth spelling out how much validate() leaves open on the Bitcoin branch: CreateSubmarineResponse::validate parses the invoice but never compares the script hashlock to it (only the Liquid arm does), and CreateReverseResponse::validate checks the invoice's payment hash and the lockup address but neither the script hashlock nor the invoice amount. A server could return an internally consistent script/address pair whose hashlock it controls, and for submarine swaps that is a theft vector: it could claim the lockup with its own preimage without paying the invoice. For reverse swaps a wrong hashlock silently breaks our script-path claim, and an unchecked amount lets the invoice ask for more than requested.

Fixed in 498be8f with a new validation module. validate_submarine_response binds the script hashlock to the invoice's payment hash160, and validate_reverse_response binds the script hashlock to our preimage's hash160 and the invoice amount to the requested amount_sat. Both wrap the existing response.validate call and run before anything is persisted or returned.

The mismatched-response tests build fixtures whose script, tree and taproot lockup address all agree with each other, so boltz-client's own address validation passes and only the term under test is wrong, which is exactly the malicious-server shape. Covered: reverse hashlock mismatch, reverse invoice amount mismatch, submarine hashlock mismatch, plus consistent baselines for both directions that must validate.

[ovitrif]

I think recovery needs to depend on local completion state here. A cooperative reverse claim can disclose the preimage before Electrum broadcast; if broadcast then fails, Boltz may report invoice.settled and this filter removes the swap even though claim_tx_id is absent. Delayed server updates can also overwrite a locally recorded completion status. Could we keep the swap recoverable while its local txid is absent and preserve local completion once a txid exists?

[coreyphillips]

You are right on both halves, and the scenario is real: the cooperative claim posts the preimage to Boltz before the Electrum broadcast, so Boltz can settle the invoice while our claim transaction never reached the chain. With the old filter that swap silently left the pending set with funds still sitting in the lockup.

Fixed in 498be8f. Recovery now depends on local completion state via SwapRecord::is_locally_complete: a terminal server status only completes a reverse swap if a claim txid is recorded locally, so invoice.settled with no local txid stays in the pending set. And update_status now refuses to touch a row once claim_tx_id or refund_tx_id is set, so a delayed or re-ordered server update (the WebSocket and the reconcile loop both feed it) cannot overwrite a locally recorded completion.

One step further so the swap actually completes rather than just staying visible: should_auto_claim now also fires on invoice.settled when no local claim txid exists. The periodic reconcile therefore retries the broadcast every cycle until it lands. The preimage is already disclosed at that point, so retrying carries no added risk.

Tests added: a settled reverse swap without a local claim txid stays recoverable and drops out once set_claim_tx records one; late server updates cannot regress a locally recorded claimed/refunded status; and the new invoice.settled arm of should_auto_claim, including that a recorded txid still suppresses it.

[ovitrif]

I think we need to serialize the updates-stream replacement. Two concurrent starts can both pass stop_swap_updates, spawn their tasks, and then replace each other here. Dropping the first handle does not abort its detached tasks, so an obsolete stream can remain active. Could we serialize the start/stop transition and ensure tasks spawned during failed or superseded initialization are aborted, with a concurrent-start test?

[coreyphillips]

Confirmed. Dropping a JoinHandle detaches rather than aborts, so two concurrent starts could both pass the stop, and whichever handle was overwritten left its three tasks (WebSocket loop, processor, reconciler) running forever. The error path had the same leak in miniature: a failing list_pending_swaps returned after the WebSocket task was already spawned.

Fixed in 498be8f by serializing the whole transition. start_swap_updates now holds the stream slot's mutex across teardown, setup and publication: it takes the old handle and calls its new shutdown() (which aborts all three tasks and drops the WebSocket), runs the only fallible step before anything is spawned so a failed start cannot leak a task, then spawns and stores the new handle while still holding the lock. stop_swap_updates goes through the same shutdown path, and the old internal stop call inside start is gone (it would now deadlock, which is a nice guarantee that every transition goes through the one lock).

For the test, aborts had to be observable, so each spawned task future carries an RAII marker counted in a static gauge; the count drops when the future is dropped, whether it completed or was aborted. The new test runs four concurrent starts against a shared slot and asserts exactly one stream (three live tasks) survives, then that stop_swap_updates takes it to zero.

[ovitrif]

Could we validate claim_address against the selected network before sending the create request? Reverse creation currently only checks that it is nonblank, while parsing and network validation happen later, after the caller may have paid the invoice, and the stored destination cannot be replaced.

[coreyphillips]

Done in 498be8f. create_reverse_swap now runs the claim address through validate_onchain_address before the create request: it must parse as a Bitcoin address and belong to the selected network, and the canonical (trimmed) form is what gets persisted as the claim destination. A malformed or wrong-network address now fails at creation, before any invoice exists to pay, instead of at claim time when the destination can no longer be replaced.

The refund path gets the same treatment for consistency: refund_submarine_swap_guarded validates the refund address against the swap's network before any transaction construction. That check sits after the idempotent early return, since a swap with a recorded refund txid returns it without using the address at all.

Tests cover a mainnet address rejected on testnet and regtest (and the reverse), garbage and empty input, and that surrounding whitespace is tolerated and stripped. The live E2E test now also picks its sample claim address per network so it keeps working under BOLTZ_LIVE_NETWORK overrides.

[ovitrif]

Could we require a finite, positive fee rate before starting updates or constructing a claim/refund? Arbitrary f64 values reach Fee::Relative; negative values and NaN become zero, while infinity saturates, so invalid configuration can fail only after fund-moving work begins.

[coreyphillips]

Done in 498be8f. validate_fee_rate requires a provided rate to be finite and strictly positive (None still falls back to the built-in default), and it runs at every entry point that leads to Fee::Relative: boltz_start_swap_updates rejects a bad auto-claim rate before any stream state exists, and claim_reverse_swap_guarded and refund_submarine_swap_guarded reject one at the top, before the swap lock is taken or any Boltz/Electrum work begins. Invalid configuration now surfaces as InvalidInput immediately instead of after fund-moving work has started.

Tests cover NaN, negative, zero and both infinities being rejected, and that valid rates and None pass.

[ovitrif]

Could we add the explicit acceptZeroConf argument to the API table and examples, using false in the safety-first examples? The generated Swift, Kotlin, and Python APIs require it, while the documentation still uses the five-argument signature.

[coreyphillips]

Done in 498be8f. The API table now shows the six-argument boltzStartSwapUpdates signature including acceptZeroConf, and every example that starts the stream (Swift, Kotlin, Python, and the recovery-after-restart snippet) passes it explicitly as false with a note that false claims only after the lockup confirms. The lifecycle section now describes acceptZeroConf as the opt-in for mempool-time claiming instead of the outdated suggestion to call boltzClaimReverseSwap manually for the 0-conf case, and the recovery section was updated for the new local-completion semantics of boltzListPendingSwaps from the other thread.