CLBOSS v0.17.3 "Swapping in the Dark" is a maintenance release for swaps. Swaps use the provider's API v2 with taproot lockups, a swap invoice is checked before it is paid, a swap request that gets no answer is restarted instead of blocking the swaps after it, and a peer with several channels is handled correctly in four more places. The requirements are those of v0.17.0: Core Lightning v26.04 or later, and the xrebalance plugin v0.4.5 or later.
Two notes on swaps first:
- Swaps on mainnet are not available at present. Boltz, the swap provider compiled into CLBOSS, suspended all swaps on 2026-08-03, and its host names no longer resolve. A mainnet node on this release gets no quotation and makes no swap; nothing is paid. Each attempt logs the provider as not accessible and the swap as failed. The swap changes in this release were validated on signet.
- The swap invoice check (#329) is the fix that would have mattered during the eMudhra certificate authority key compromise of October 2026. An impersonated provider endpoint could have had CLBOSS pay an invoice of its choosing; the check removes that path, whatever the host's trust store contains.
Posts
- What's new in CLBOSS v0.17.3: a short summary for busy operators.
Changed
- Swaps. Boltz swaps use the provider's API v2 with taproot lockups. The claim is cooperative, with one MuSig2 key-path signature; when the provider does not co-sign, CLBOSS claims through the claim leaf with its own signature and the preimage. Before paying, CLBOSS writes both tapscript leaves itself and accepts the provider's only when they match byte for byte. The preimage leaves the node only after our own node has the lockup three blocks deep. The claim is recorded before the preimage is sent, replaced when the going feerate rises above its own, and followed in our own blocks until the lockup is spent. The API v1 code is gone (#254).
- libsecp256k1. The vendored library moves from 0.3.2 to 0.6.0, which carries the MuSig2, extrakeys and schnorrsig modules that taproot swaps need (#375).
Fixed
- Swap invoice. A swap invoice from the provider was paid as received. CLBOSS pays it only when its payment hash is of the preimage CLBOSS generated and its amount is the one the provider was asked for; any other invoice is logged and left unpaid (#329).
- Swaps blocked. A swap whose address request or provider request never got an answer blocked every later swap until Core Lightning was restarted. The periodic check restarts a request that has had no answer for 30 minutes (#333).
- Provider errors. A provider answering with something other than JSON, such as an HTML error page or an empty body, surfaced as an unhandled parse error with a backtrace and no hint of which request failed. It is reported as an API error naming the endpoint (#269).
- Several channels to one peer, fee by balance. The modifier read only the first live channel and applied its multiplier to all of them. It sums our balance and the capacity over the peer's live channels (#352).
- Several channels to one peer, probes. The active prober sized its probe from the first live channel listed, which could be the smaller one. It probes through the channel with the most to spend (#352).
- Several channels to one peer, auto-close.
clboss-auto-closeissuedclose id=<node>, which lightningd refuses for such a peer, and retried it every cycle. It closes each closable channel by channel id (#352). contrib/clboss-channel-sizing. Balance samples recorded before 0.17.3 describe one channel of a peer, and the tool spread them over all of the peer's channels. The channel whose capacity matches reads the samples; the peer's other channels read as young (#352).- Signet. A new signet node can find peers again: the four hardcoded seeds had stopped accepting connections and are replaced with seven nodes that accept them (#379).
- Build. On Debian and Ubuntu, libunwind took over C++ exception unwinding and
make checkfailed under valgrind. The build links libgcc_s ahead of libunwind (#372).
Known issue
- A swap whose preimage is out, but whose payment the node does not yet report as complete at the swap's timeout, is started again with a smaller amount, so a second swap is paid for the same need. It needs a provider that does not settle for about 11 blocks after it has the preimage, and no funds are lost. Found by @Mohil-Ahuja in a review of this release's swap code; the fix is planned for 0.17.4.
Upgrading from v0.17.2
Finish or wait out any swap in flight before upgrading, and before downgrading again. The swap table gains ten columns on first use, and a swap created by one version cannot be claimed by the other, so it ends at its timeout and the payment fails back to the node. The Boltz::Service log lines show one in flight. Earlier releases still run on the upgraded database. Then install and restart; no option was added or removed.
Credits
Thanks to the contributors to this release:
- The contributor who sent the API v2 draft: the first version of the Boltz API v2 code, with taproot reverse swaps and MuSig2 claims (#254).
- @Mohil-Ahuja: the three fixes for several channels to one peer (#368, #371, #369), the balance-sample fix in
contrib/clboss-channel-sizing(#378) and the replacement signet seeds (#379). - @Amperstrand: reported that a swap invoice was paid without a check of its payment hash (#329).
- @tsjk: runs the signet swap backend that the swap changes were tested against.
See CHANGELOG.md for details.