This release adds official support for two important lightning features: zero-conf channels and channel aliases. It also adds experimental support for dual-funding and a lot of preparatory work for Bolt 12 offers.

⚠️ we also require at least Bitcoin Core 23.0: make sure to upgrade and reconfigure your node (see instructions below)!

This release adds support for Bitcoin Core 23.x and removes support for previous Bitcoin Core versions. Please make sure you have updated your Bitcoin Core node before updating eclair, as eclair won't start when connected to older versions of bitcoind.

Bitcoin Core 23.0 updated what type of change outputs are created: when sending funds to an address, bitcoind will create a change output that matches that address type. This is undesirable for lightning, as non-segwit inputs cannot be used for lightning channels (funds can be lost when using them). Bitcoin Core needs to be configured to generate segwit addresses only, so you must add the following lines to your bitcoin.conf:

addresstype=bech32
changetype=bech32

Note that you may also use bech32m if your peers support option_shutdown_anysegwit.

Channel aliases offer a way to use arbitrary channel identifiers for routing. This feature improves privacy by not leaking the funding transaction of the channel during payments.

This feature is enabled by default, but your peer has to support it too, and it is not compatible with public channels.

Zeroconf channels make it possible to use a newly created channel before the funding tx is confirmed on the blockchain.

⚠️ Zeroconf requires the fundee to trust the funder. For this reason it is disabled by default, and you can only enable it on a peer-by-peer basis.

Below is how to enable zeroconf with a given peer in eclair.conf. With this config, your node will accept zeroconf channels from node 03864e....

override-init-features = [
  {
    nodeid = "03864ef025fde8fb587d989186ce6a4a186895ee44a926bfc370e2c366597a3f8f",
    features = {
      // dependencies of zeroconf
      option_static_remotekey = optional
      option_anchors_zero_fee_htlc_tx = optional
      option_scid_alias = optional
      // enable zeroconf
      option_zeroconf = optional
    }
  }
]

Note that, as funder, Eclair will happily use an unconfirmed channel if the peer sends an early channel_ready, even if the option_zeroconf feature isn't enabled, as long as the peer provides a channel alias.

You can enable option_scid_alias and option_zeroconf features by requesting them in the channel type, even if those options aren't enabled in your features.

The new channel types variations are:

• anchor_outputs_zero_fee_htlc_tx+scid_alias
• anchor_outputs_zero_fee_htlc_tx+zeroconf
• anchor_outputs_zero_fee_htlc_tx+scid_alias+zeroconf

Examples using the command-line interface:

• open a public zeroconf channel:

$ ./eclair-cli open --nodeId=03864e... --fundingSatoshis=100000 --channelType=anchor_outputs_zero_fee_htlc_tx+zeroconf --announceChannel=true

• open a private zeroconf channel with aliases:

$ ./eclair-cli open --nodeId=03864e... --fundingSatoshis=100000 --channelType=anchor_outputs_zero_fee_htlc_tx+scid_alias+zeroconf --announceChannel=false

This release adds experimental support for dual-funded channels, as specified here. Dual-funded channels have many benefits:

• both peers can contribute to channel funding
• the funding transaction can be RBF-ed

This feature is turned off by default, because there may still be breaking changes in the specification. To turn it on, simply enable the feature in your eclair.conf (use at your own risk until the specification is final!):

eclair.features.option_dual_fund = optional

If your peer also supports the feature, eclair will automatically use dual-funding when opening a channel. If the channel doesn't confirm, you can use the rbfopen RPC to initiate an RBF attempt and speed up confirmation.

In this first version, the non-initiator cannot yet contribute funds to the channel. This will be added in future updates, most likely in combination with liquidity ads.

The specification says that a channel should be pruned whenever one side has not updated their channel_update in two weeks. Eclair previously only pruned channels when both sides didn't update, because we assumed that nodes would not keep generating useless channel_updates if their peer is offline. But that assumption wasn't correct: lnd does generate such updates.

This release fixes the pruning behavior to strictly follow the specification, which results in a slightly smaller network DB.

Whenever an outgoing payment is attempted, eclair will use the result to keep track of the balance of channels in the path. The path-finding algorithm doesn't yet use these estimates: we want to gather real-world data and improve the model before we can actually use it. But a future release of eclair will leverage this data to improve payments reliability. See #2272 for more details.

Eclair supports overriding features on a per-peer basis, using the eclair.override-init-features field in eclair.conf. These overrides will now be applied on top of the default features, whereas the previous behavior was to completely ignore default features. We provide detailed examples in the documentation.

Dropped support for version 2 of Tor protocol. That means:

• Eclair can't open control connection to Tor daemon version 0.3.3.5 and earlier anymore
• Eclair can't create hidden services for Tor protocol v2 with newer versions of Tor daemon

IMPORTANT: You'll need to upgrade your Tor daemon if for some reason you still use Tor v0.3.3.5 or earlier before upgrading to this release.

This version of eclair uses libsecp256k1 natively, we include bindings for Linux arm64 but not for MacOS arm64 yet. This can be worked around by downloading an x86-64 version of the JVM to run eclair. See the following issue for more details.

• channelbalances retrieves information about the balances of all local channels (#2196)
• channelbalances and usablebalances return a shortIds object instead of a single shortChannelId (#2323)
• stop stops eclair: please note that the recommended way of stopping eclair is simply to kill its process (#2233)
• rbfopen lets the initiator of a dual-funded channel RBF the funding transaction (#2275)
• listinvoices and listpendinginvoices now accept --count and --skip parameters to limit the number of retrieved items (#2474)

Eclair can export metrics to Prometheus and consume them from Grafana. Head over to the documentation to set it up for your node. The dashboards we provide are currently very basic: if they are useful to you, please consider opening pull requests to improve them.

When sending a payment, if the cltv expiry used for the final node is very close to the current block height, it lets intermediate nodes figure out their position in the route. To protect against this, a random delta is now added to the current block height, which makes it look like there are more hops after the final node.

You can configure the delta used in your eclair.conf:

// minimum value that will be added to the current block height
eclair.send.recipient-final-expiry.min-delta = 100
// maximum value that will be added to the current block height
eclair.send.recipient-final-expiry.max-delta = 400

You can also disable this feature by setting both values to 1:

// Note that if you set it to 0, payments will fail if the recipient has just received a new block.
// It is thus recommended to set if to a low value that is greater than 0.
eclair.send.recipient-final-expiry.min-delta = 1
eclair.send.recipient-final-expiry.max-delta = 1

When updating the relay fees for a channel, eclair can now continue accepting to relay payments using the old fee even if they would be rejected with the new fee. By default, eclair will still accept the old fee for 10 minutes, you can change it by setting eclair.relay.fees.enforcement-delay to a different value.

If you want a specific fee update to ignore this delay, you can update the fee twice to make eclair forget about the previous fee.

New settings have been added to independently control the minimum funding required to open public and private channels to your node.

The eclair.channel.min-funding-satoshis setting has been deprecated and replaced with the following two new settings and defaults:

• eclair.channel.min-public-funding-satoshis = 100000
• eclair.channel.min-private-funding-satoshis = 100000

If your configuration file changes eclair.channel.min-funding-satoshis then you should replace it with both of these new settings.

Expired incoming invoices that are unpaid will be searched for and purged from the database when Eclair starts up. Thereafter searches for expired unpaid invoices to purge will run once every 24 hours. You can disable this feature, or change the search interval with two new settings:

• eclair.purge-expired-invoices.enabled = true
• eclair.purge-expired-invoices.interval = 24 hours

When using anchor outputs and a channel force-closes without HTLCs in the commitment transaction, funds cannot be stolen by your counterparty. In that case eclair can skip spending the anchor output to save on-chain fees, even if the transaction doesn't confirm. This can be activated by setting the following value in your eclair.conf:

eclair.on-chain-fees.spend-anchor-without-htlcs = false

This is disabled by default, because there is still a risk of losing funds until bitcoin adds support for package relay. If the mempool becomes congested and the feerate is too low, the commitment transaction may never reach miners' mempools because it's below the minimum relay feerate.

You can now specify a DNS host name as one of your server.public-ips addresses (see PR #911). Note: you can not specify more than one DNS host name.

To test Eclair with bitcoind configured for signet, set the following values in eclair.conf:

eclair.chain = "signet"
eclair.bitcoind.rpcport=38332

The encrypted errors returned with failed payments were previously limited to 256 bytes. Eclair now allows errors of arbitrary length, which paves the way for future updates to the onion errors used in lightning. See #2441 for more details.

Gossip compression using zlib has been deprecated in the specification and removed from eclair (#2244). Eclair still supports decompressing zlib content for backwards-compatibility, but will not compress outgoing gossip anymore.

The legacy onion format has been replaced by the more flexible variable-length onion format. Support for the legacy format has been removed from the specification.

The payment_secret was introduced years ago to ensure that intermediate nodes cannot steal from payments to amountless invoices. It is now fully supported across the network, so we make it mandatory.

You will need gpg and our release signing key 7A73FE77DE2C4027. Note that you can get it:

• from our website: https://acinq.co/pgp/drouinf.asc
• from github user @sstone, a committer on eclair: https://api.github.com/users/sstone/gpg_keys

To import our signing key:

$ gpg --import drouinf.asc

To verify the release file checksums and signatures:

$ gpg -d SHA256SUMS.asc > SHA256SUMS.stripped
$ sha256sum -c SHA256SUMS.stripped

Eclair builds are deterministic. To reproduce our builds, please use the following environment (*):

• Ubuntu 20.04
• AdoptOpenJDK 11.0.6
• Maven 3.8.1

Use the following command to generate the eclair-node package:

mvn clean install -DskipTests

That should generate eclair-node/target/eclair-node-<version>-XXXXXXX-bin.zip with sha256 checksums that match the one we provide and sign in SHA256SUMS.asc

(*) You may be able to build the exact same artefacts with other operating systems or versions of JDK 11, we have not tried everything.

This release is fully compatible with previous eclair versions. You don't need to close your channels, just stop eclair, upgrade and restart.

• 4451069 Back to Dev (#2159)
• cc61f12 Fix publish loop when funding tx double-spent (#2162)
• 648f93f Ignore revoked htlcs after restart (#2161)
• 8a65e35 Don't broadcast commit before funding locked (#2163)
• 4307bad Refactoring of PaymentRequest (#2144)
• fa31d81 Improve postman (#2147)
• 553727c Convert wiki pages in to files in the docs directory and general docs file cleanups (#2165)
• 9401592 Typed features (#2164)
• daddee1 fixup! Convert wiki pages in to files in the docs directory and general docs file cleanups (#2165) (#2167)
• ca71a3c Update a few dependencies (#2166)
• 66aafd6 Better logging for NegativeProbability exception (#2171)
• 92221e8 Fix path-finding (#2172)
• 53cb50a Restrict building and publishing docker images to new pushes on master (#2182)
• 99aabda Add txId in logback.xml (#2183)
• 609c206 Ignore IBD in regtest (#2185)
• b5b2022 Add more PR details to contributing guidelines (#2186)
• 068b139 purge expired invoice at given time interval (#2174)
• 8f7c6ed Refactor Closing.claimRemoteCommitMainOutput() (#2191)
• 67fb392 Use direct channel when available (#2192)
• ab30af8 minFinalExpiryDelta is not optional (#2195)
• dba73c8 (Minor) Flatten ChannelDataSpec tests
• be78e0c Separate htlc calculation from local/remote commit (no quicklens) (#2194)
• c4f67e7 Bump postgres-jdbc version (#2198)
• f3c6c78 Do not fail to relay payments with insufficient fee rate that satisfy the previous fee rate (#2201)
• 8f2c93c Add delayed fees to release notes (#2204)
• f14300e two new min-funding config parameters for public and private channels (#2203)
• 7b5cefa Replace FeatureScope by type hierarchy (#2207)
• 18ba900 (Minor) Fix timeout in tests (#2208)
• 5af042a Add messages for when startup fails due to wrong bitcoind wallet(s) loaded (#2209)
• fd84909 Fix TLV tag number in exception (#2212)
• 3e02046 Add logs about local channel graph inclusion (#2184)
• dbd9e38 Add explicit github permissions to bitcoin core build (#2200)
• 6823309 Use NodeAddress everywhere instead of InetAddress (#2202)
• 0e88440 Make trampoline pay the right fee (#2206)
• d135224 Refactor channel into separate traits (#2217)
• 2872d87 Fix latest bitcoin build (#2218)
• 9358e5e Add channelbalances API call (#2196)
• 6f31ed2 Add release notes for new min-funding settings and invoice purger (#2210)
• 1627682 Remove ipv6 zone identifier test (#2220)
• 7883bf6 Use bitcoin-kmp through bitcoin-lib (#2038)
• 36ed788 Update experimental trampoline feature bit (#2219)
• 446a780 Refactor channel transitions (#2228)
• ddb52d8 Check that channel seed has not been modified (#2226)
• 7cf2e20 Remove Phoenix workaround for PaymentSecret dependency (#2230)
• 787c51a Add a "stop" API method (#2233)
• c7c515a Add Bolt12 types and codecs (#2145)
• 86145a7 Remove unused PerHopPayloadFormat traits (#2235)
• 9a31dfa Rename channel funder to initiator (#2236)
• 443266d Add dual funding codecs and feature bit (#2231)
• a4ddbc3 Give best capacity score to local channels (#2239)
• f099409 Disable invoice purger in tests (#2240)
• 56c9e06 Only define decode method in legacy codecs (#2241)
• 6958970 Fix flaky MempoolTxMonitor test (#2249)
• 74ef082 Use log probability in path-finding (#2257)
• ee74f10 Stop compressing with zlib (#2244)
• 1605c04 Introduce ChannelRelayParams in the graph (#2264)
• 95213bc Remove unused LocalChannel class in the router (#2265)
• b691e87 Fix flaky replaceable tx publisher tests (#2262)
• 10eb9e9 Improve wallet double-spend detection (#2258)
• 8e2fc7a Run channel state tests sequentially (#2271)
• 81571b9 Fix flaky test PeerConnectionSpec (#2277)
• bb7703a Add simple integration test between Channel and Router (#2270)
• 03097b0 Add localChannelReserve and remoteChannelReserve (#2237)
• 1e8791c Update dual funding codecs (#2245)
• 6fa02a0 Use long id instead of short id in ChannelRelay (#2221)
• d98da6f Index unannounced channels on channelId instead of shortChannelId in the router (#2269)
• 44e7127 (Minor) Postgres: use write instead of writePretty (#2279)
• 9c7ddcd Increase closed timeout from 10s to 1min (#2281)
• 45f19f6 Fix test when run in Intellij (#2288) (#2289)
• 749d92b Add option to disable sending remote addr in init (#2285)
• 088de6f Don't RBF anchor if commit is confirmed (#2283)
• ee46c56 Remove dependency between dual funding and anchors (#2297)
• 9610fe3 Define a proper base class for fixture tests (#2286)
• 47c5b95 Drop support for Tor v2 hidden services (#2296)
• ecbec93 Add traits for permanent channel features (#2282)
• e08353b Remove close() in db interfaces (#2303)
• c5620b2 Log routing hint when finding a route (#2242)
• 340b568 (Minor) Test nits (#2306)
• 682e9bf Fix minimal node fixture flakyness (#2302)
• 4722755 Estimate balances of remote channels (#2272)
• c4786f3 Store disabled channel update when offline (#2307)
• 3e3f786 Allow disabling bitcoind requests batching (#2301)
• e8c9df4 Add more GraphSpec tests (#2292) (#2293)
• e5f5cd1 Add support for zero-conf and scid-alias (#2224)
• f47c7c3 Don't block when generating shutdown script (#2284)
• bfba9e4 (Minor) Include the discriminator in all channel codecs (#2317)
• 7630c51 (Minor) Fix flaky ZeroConfAliasIntegrationSpec (#2319)
• 6882bc9 Clean up scid parsing from coordinates string (#2320)
• fc30eab Remove channelId from PublicChannel (#2324)
• 26741fa Reuse postgres instance in tests (#2313)
• 6b2e415 Expose scraping endpoint for prometheus metrics (#2321)
• 70de271 Make actors signal when they are ready (#2322)
• 0c84063 add arm64v8 Dockerfile (#2304)
• af79f44 Move arm64 docker file to contrib and udpate README.md (#2327)
• 08d2ad4 Random values for generateLocalAlias() (#2337)
• c9810d5 Resume reading after processing unknown messages (#2332)
• e880b62 Refactor routing hints to prepare for payments to blinded routes (#2315)
• 8af14ac Backport from feature branches (#2326)
• 6011c86 Additive per-node feature override (#2328)
• a1f7c1e Return local channel alias in payment failures (#2323)
• 2790b2f Activate 0-conf based on per-peer feature override (#2329)
• 2461ef0 Call resolve() on configuration (#2339)
• 3b97e44 Allow disabling no-htlc commitment fee-bump (#2246)
• 276340d Add host metrics grafana dashboard (#2334)
• 3196462 Proper json serializer for BlockHeight (#2340)
• e1dc358 Fix RoutingHeuristics.normalize (#2331)
• c20b3c9 Remove redundant routing hint (#2349)
• 214873e Use the correct extra edges to put in metrics (#2350)
• 23de6c4 Fix flaky zeroconf test (#2352)
• 99d9bc1 Relay blinded payments (#2253)
• 4fd3d90 Emit event when receiving Pong (#2355)
• b171a16 Remove payments overview DB (#2357)
• 8a42246 Update offers types (#2351)
• 85fea72 Broadcast commit tx when nothing at stake (#2360)
• c71c3b4 Make htlc_maximum_msat mandatory in channel updates (#2361)
• 9f9cf9c (Minor) Test improvements (#2354)
• f49eb0e Update sqlite to 3.39.2.0 (#2369)
• 0310bf5 Implement first steps of the dual funding flow (#2247)
• de1ac34 Add explicit duration to ExcludeChannel (#2368)
• 2f590a8 Refactor routing hint failure updates (#2370)
• e8dda28 Remove invalid channel updates from DB at startup (#2379)
• a13c3d5 Prune channels if any update is stale (#2380)
• 5f4f720 Remove legacy force-close htlc matching (#2376)
• 33e6fac Implement the interactive-tx protocol (#2273)
• bb6148e Support DNS hostnames in node announcements (#2234)
• 285fe97 Fix blinded path amount to forward calculation (#2367)
• 4e3b377 Update route blinding test vectors (#2075)
• 8f2028f Limit default from and to API parameters (#2384)
• 323aeec Add support for the signet test network (#2387)
• a97e88f Dual funding channel confirmation (#2274)
• ad19a66 Unlock utxos during dual funding failures (#2390)
• a735ba8 Dual funding RBF support (#2275)
• 278f391 Add akka metrics grafana dashboard (#2347)
• a4faa90 Add eclair metrics grafana dashboard (#2343)
• fb6eb48 Fix dual funding flaky test (#2392)
• c1daaf3 Check input out of bounds early in tx_add_input (#2393)
• 81af619 (Minor) Ignore line ending when comparing strings in tests (#2403)
• 40b2d44 Remove support for legacy Sphinx payloads (#2190)
• 3568dd6 Rework log capture in tests (#2409)
• ee1136c Assume sent htlcs will succeed in the balance computation (#2410)
• 611b796 More lenient interactive-tx RBF validation (#2402)
• 065cb28 Add option to require confirmed inputs in interactive-tx (#2406)
• 37863a4 Use deterministic serial IDs in interactive-tx (#2407)
• 7c8a777 Add a ChannelOrigin placeholder (#2411)
• 40b83a7 Nits (#2413)
• 517c0fd Fix collision bug in local alias generation (#2415)
• 59f6cda Separate tlv decoding from content validation (#2414)
• 09f1940 Implement latest route blinding spec updates (#2408)
• 9d17b1d Receive payments for Bolt 12 invoices (#2416)
• 3191878 Allow receiving to blinded routes (#2418)
• ba2b928 Add tests for invoice feature validation (#2421)
• b00a0b2 Don't set channel reserve for dual funded channels (#2430)
• 3fdad68 Remove channelReserve.getOrElse(0 sat) (#2432)
• 1b0ce80 Add support for push amount with dual funding (#2433)
• 1b36697 Fix duplicate SLF4J loggers in tests (#2436)
• afdaf46 Add initial support for async payment trampoline relay (#2435)
• 6e381d4 Fix availableForSend fuzz tests (#2440)
• 0de91f4 Bump scala-library from 2.13.8 to 2.13.9 (#2444)
• 06ead3c Add tlvField codec (#2439)
• ca68695 Validate payment using minFinalExpiryDelta from node params (#2448)
• dad0a51 Complete codec for TLV fields (#2452)
• 3b12475 Make payment secret not optional (#2457)
• a0433aa Fix flaky CommitmentsSpec test (#2458)
• c1a925d Use 0-conf based on local features only (#2460)
• dd3d694 Remove onion message size limit (#2459)
• 1f32652 Add tlv to require confirmed inputs for dual funding (#2461)
• 5e85c7c Fix pruned channels coming back online (#2456)
• a11984b Use tx_hash in dual funding and verify nSequence (#2463)
• 7c8bdb9 Explain how and why we use bitcoin core (#2473)
• 21c6278 Only use txid in error messages (#2423)
• c385ca2 Add support for arbitrary length onion errors (#2441)
• a8389a0 Add private flag to channel updates (#2362)
• 31f61c1 Randomize final cltv expiry (#2469)
• a566d53 Allow nodes to overshoot final htlc amount and expiry (#2468)
• 0906804 Support scid_alias and zero_conf for all commitment types (#2404)
• 9ae4dea Reduce diff with feature branch (#2476)
• 8f1af28 Add pagination on listInvoices (#2474)
• 7dbaa41 Update to bitcoind 23.x (#2466)
• 6eba3e7 Fix static default from and to pagination (#2484)
• 003aae0 Explicitly request bech32 static remotekey (#2486)
• 37a3911 Fix circular dependency (#2485)
• 1e252e5 Make eclair-cli -s display short channel ids correctly (#2488)
• 6d3991b Accept payments to zero-hop blinded route (#2500)
• e32697e Build Bolt12 invoices with provided intermediary nodes (#2499)
• 6569eaf Cancel previous LiftChannelExclusion (#2510)
• 8afcb46 Fix closing channel state when nothing at stake (#2512)
• 731a7ee Implement correct ordering of tx_signatures (#2501)
• 5b0aa35 Create routes to self using remote alias (#2507)
• a230395 Test change address type generation (#2513)
• 77b9aa0 Remove warning for pruned local channel update (#2514)