eclair/docs/release-notes/eclair-v0.7.0.md

Eclair v0.7.0

This release adds official support for two long-awaited lightning features: anchor outputs and onion messages. Support for the PostreSQL database backend is also now production ready!

This release also includes a few bug fixes and many new (smaller) features. It is fully compatible with 0.6.2 (and all previous versions of eclair).

Because this release changes the default type of channels that your node will use, make sure you read the release notes carefully!

Major changes

Anchor outputs activated by default

Experimental support for anchor outputs channels was first introduced in eclair v0.4.2. Going from an experimental feature to production-ready required a lot more work than we expected! What seems to be a simple change in transaction structure had a lot of impact in many unexpected places, and fundamentally changes the mechanisms to ensure funds safety.

When using anchor outputs, you will need to keep utxos available in your bitcoind wallet to fee-bump HTLC transactions when channels are force-closed. Eclair will warn you via the notifications.log file when your bitcoind wallet balance is too low to protect your funds against malicious channel peers. Eclair will wait for you to add funds to your wallet and automatically retry, but you may be at risk in the meantime if you had pending payments at the time of the force-close.

We recommend activating debug logs for the transaction publication mechanisms. This will make it much easier to follow the trail of RBF-ed transactions, and shouldn't be too noisy unless you constantly have a lot of channels force-closing. To activate these logs, simply add the following line to your logback.xml:

<logger name="fr.acinq.eclair.channel.publish" level="DEBUG"/>

You don't even need to restart eclair, it will automatically pick up the logging configuration update after a short while.

If you don't want to use anchor outputs, you can disable the feature in your eclair.conf:

eclair.features.option_anchors_zero_fee_htlc_tx = disabled

Postgres database backend graduates to production-ready

Postgres support was introduced in Eclair 0.4.1 as beta, and has since been improved continuously over several versions. It is now production-ready and is the recommended database backend for larger nodes.

Postgres offers superior administration capabilities, advanced JSON queries over channel data, streaming replication, and more, which makes it a great choice for enterprise setups.

A step-by-step migration guide from Sqlite to Postgres is provided for users who wish to do the switch.

Sqlite remains fully supported.

Alternate strategy to avoid mass force-close of channels in certain cases

The default strategy, when an unhandled exception or internal error happens, is to locally force-close the channel. Not only is there a delay before the channel balance gets refunded, but if the exception was due to some misconfiguration or bug in eclair that affects all channels, we risk force-closing all channels.

This is why an alternative behavior is to simply log an error and stop the node. Note that if you don't closely monitor your node, there is a risk that your peers take advantage of the downtime to try and cheat by publishing a revoked commitment. Additionally, while there is no known way of triggering an internal error in eclair from the outside, there may very well be a bug that allows just that, which could be used as a way to remotely stop the node (with the default behavior, it would "only" cause a local force-close of the channel).

Separate log for important notifications

Eclair added a new log file (notifications.log) for important notifications that require an action from the node operator. Node operators should watch this file very regularly.

An event is also sent to the event stream for every such notification. This lets plugins notify the node operator via external systems (push notifications, email, etc).

Support for onion messages

Eclair now supports the option_onion_messages feature (see https://github.com/lightning/bolts/pull/759). This feature is enabled by default: eclair will automatically relay onion messages it receives.

By default, eclair will only accept and relay onion messages from peers with whom you have channels. You can change that strategy by updating eclair.onion-messages.relay-policy in your eclair.conf.

Eclair applies some rate-limiting on the number of messages that can be relayed to and from each peer. You can choose what limits to apply by updating eclair.onion-messages.max-per-peer-per-second in your eclair.conf.

Whenever an onion message for your node is received, eclair will emit an event, that can for example be received on the websocket (onion-message-received).

You can also send onion messages via the API. This will be covered in the API changes section below.

To disable the feature, you can simply update your eclair.conf:

eclair.features.option_onion_messages = disabled

Support for option_payment_metadata

Eclair now supports the option_payment_metadata feature (see https://github.com/lightning/bolts/pull/912). This feature will let recipients generate "light" invoices that don't need to be stored locally until they're paid. This is particularly useful for payment hubs that generate a lot of invoices (e.g. to be displayed on a website) but expect only a fraction of them to actually be paid.

Eclair includes a small payment_metadata field in all invoices it generates. This lets node operators verify that payers actually support that feature.

Optional safety checks when using Postgres

When using postgres, at startup we optionally run a few basic safety checks, e.g. the number of local channels, how long since the last local channel update, etc. The goal is to make sure that we are connected to the correct database instance.

Those checks are disabled by default because they wouldn't pass on a fresh new node with zero channels. You should enable them when you already have channels, so that there is something to compare to, and the values should be specific to your setup, particularly for local channels. Configuration is done by overriding max-age and min-count values in your eclair.conf:

eclair.db.postgres.safety-checks
 {
  enabled = true
  max-age {
    local-channels = 3 minutes
    network-nodes = 30 minutes
    audit-relayed = 10 minutes
  }
  min-count {
    local-channels = 10
    network-nodes = 3000
    network-channels = 20000
  }
}

API changes

Timestamps

All timestamps are now returned as an object with two attributes:

• iso: ISO-8601 format with GMT time zone. Precision may be second or millisecond depending on the timestamp.
• unix: seconds since epoch formats (seconds since epoch). Precision is always second.

Examples:

• second-precision timestamp:

  • before:

  {
    "timestamp": 1633357961
  }
  

  • after

  {
    "timestamp": {
      "iso": "2021-10-04T14:32:41Z",
      "unix": 1633357961
    }
  }
  

• milli-second precision timestamp:

  • before:

  {
    "timestamp": 1633357961456
  }
  

  • after (note how the unix format is in second precision):

  {
    "timestamp": {
      "iso": "2021-10-04T14:32:41.456Z",
      "unix": 1633357961
    }
  }
  

Sending onion messages

You can now send onion messages with sendonionmessage.

There are two ways to specify the recipient:

• when you're sending to a known nodeId, you must set it in the --recipientNode field
• when you're sending to an unknown node behind a blinded route, you must provide the blinded route in the --recipientBlindedRoute field (hex-encoded)

If you're not connected to the recipient and don't have channels with them, eclair will try connecting to them based on the best address it knows (usually from their node_announcement). If that fails, or if you don't want to expose your nodeId by directly connecting to the recipient, you should find a route to them and specify the nodes in that route in the --intermediateNodes field.

You can send arbitrary content to the recipient, by providing a hex-encoded tlv in the --content field.

If you expect a response, you should provide a route from the recipient back to you in the --replyPath field. Eclair will create a corresponding blinded route, and the API will wait for a response (or timeout if it doesn't receive a response).

Balance

The detailed balance json format has been slightly updated for channels in state normal and shutdown, and closing.

Amounts corresponding to incoming htlcs for which we knew the preimage were previously included in toLocal, they are now grouped with outgoing htlcs amounts and the field has been renamed from htlcOut to htlcs.

Miscellaneous

This release contains many other API updates:

• deleteinvoice allows you to remove unpaid invoices (#1984)
• findroute, findroutetonode and findroutebetweennodes supports new output format full (#1969)
• findroute, findroutetonode and findroutebetweennodes now accept --ignoreNodeIds to specify nodes you want to be ignored in path-finding (#1969)
• findroute, findroutetonode and findroutebetweennodes now accept --ignoreShortChannelIds to specify channels you want to be ignored in path-finding (#1969)
• findroute, findroutetonode and findroutebetweennodes now accept --maxFeeMsat to specify an upper bound of fees (#1969)
• getsentinfo output includes failedNode field for all failed routes
• for payinvoice and sendtonode, --feeThresholdSat has been renamed to --maxFeeFlatSat
• for open, --channelFlags has been replaced by --announceChannel
• the networkstats API has been removed

Have a look at our API documentation for more details.

Miscellaneous improvements and bug fixes

• Eclair now supports cookie authentication for Bitcoin Core RPC (#1986)
• Eclair echoes back the remote peer's IP address in init (#1973)
• Eclair now supports circular rebalancing

Verifying signatures

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

Building

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-0.7.0-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.

Upgrading

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

Changelog

• 57bf860 Back to Dev (#1993)
• df63ea4 Deprecation warning for relay fees config (#2012)
• 498e9a7 Remove CoinUtils.scala. (#2013)
• b22b1cb Fix API hanging on invalid remote params (#2008)
• 9057c8e Minor improvements (#1998)
• b4d285f Proper types for UNIX timestamps (#1990)
• 6018988 Check serialization consistency in all channel tests (#1994)
• 6b202c3 Add low-level route blinding features (#1962)
• f3b1604 Add API to delete an invoice (#1984)
• 93481d9 Higher walletpassphrase timeout in tests (#2022)
• bdef833 Additional parameters for findroute* API calls (#1969)
• 9274582 Balance: take signed fulfills into account (#2023)
• 4e9190a Minor: higher timeout in payment fsm test (#2026)
• 28d04ba Store blinding pubkey for introduction node (#2024)
• 570dc22 Fix flaky transaction published event test (#2020)
• 99a8896 ignoreShortChannelIds should disable edges in both directions (#2032)
• 494e346 Minor: put htlc info logs in debug (#2030)
• 765a0c5 Add log file for important notifications (#1982)
• 1573f7b EncryptedRecipientData TLV stream should not be length-prefixed (#2029)
• e54aaa8 API: fix default time boundaries (#2035)
• c5fa39f Front: stop the jvm after coordinated shutdown (#2028)
• 2e9f8d9 Cookie-based authentication for Bitcoin Core RPC (#1986)
• 2c0c24e Rework channel reestablish (#2036)
• 4f458d3 Alternate strategy for unhandled exceptions (#2037)
• 9f65f3a Make compatibility code for waitingSince work on testnet (#2041)
• 1f613ec Handle mutual close published from the outside (#2046)
• f7a79d1 Fix response for updaterelayfee (#2047)
• 3dc4ae1 Refactor payment onion utilities (#2051)
• b45dd00 Refactor sphinx payment packet (#2052)
• 4ac8236 Remove dumpprivkey from tests (#2053)
• 083dc3c Onion messages (#1957)
• 333e9ef Clarify route blinding types (#2059)
• 6cc37cb Simplify onion message codec (#2060)
• fb96e5e Add failed node ID field to FailureSummary (#2042)
• 59b4035 Relay onion messages (#2061)
• 9792c72 Rename feeThresholdSat to maxFeeFlatSat (#2079)
• 4ad502c Abort HTLC tx publisher if remote commit confirms (#2080)
• 589e84f Support private channels in SendToRoute (#2082)
• 86aed63 Remove misleading claim-htlc-success log (#2076)
• bacb31c Add channel type feature bit (#2073)
• 3003289 No error when updating the relay fees not in normal state (#2086)
• a470d41 Write received onion messages to the websocket (#2091)
• 62cc073 Remove network stats computation (#2094)
• ee852d6 (Minor) Handle disconnect request when offline (#2095)
• 40cc458 Switchboard exposes peer information (#2097)
• 3451974 Raise default connection timeout values (#2093)
• ac9e274 Add message relay policies (#2099)
• 535daec Fix unhandled event in DbEventHandler (#2103)
• 4ebc8b5 Notify node operator on low fee bumping reserve (#2104)
• 576c0f6 Increase timeout onion message integration tests (#2106)
• 3d88c43 Kill idle peers (#2096)
• 8ff7dc7 Avoid default arguments in test helpers (#2108)
• 7e7de53 Filter out non-standard channels from channelInfo API (#2107)
• ec13281 Add nightly build with bitcoind master (#2027)
• c370abe Rate limit onion messages (#2090)
• 8afb02a Add payment hash to ClaimHtlcSuccessTx (#2101)
• bf0969a Add defenses against looping paths (#2109)
• 7693696 Fix potential loop in path-finding (#2111)
• 0b807d2 Set max timestamp in API call to 9999/12/31 (#2112)
• 2827be8 Make ClaimHtlcTx replaceable (#2102)
• 1fd6344 Define 9999-12-31 as max value for timestamps (#2118)
• fda3818 Rename raw tx publisher to final tx publisher (#2119)
• 7421098 Process replies to onion messages (#2117)
• 27579a5 (Minor) Use sys package instead of System when applicable (#2124)
• 6e88532 Add support for option_payment_metadata (#2063)
• 7f7ee03 Handle onion creation failures (#2087)
• 546ca23 Activate onion messages (#2133)
• 27e29ec Fix onion message tests by changing the rate limiter (#2132)
• 88dffbc Publish docker images (#2130)
• 40f7ff4 Replaceable txs fee bumping (#2113)
• 58f9ebc Use BlockHeight everywhere (#2129)
• 52a6ee9 Rename TxPublishLogContext (#2131)
• e2b1b26 Activate anchor outputs (#2134)
• 2f07b3e (Minor) Nits (#2139)
• f8d507b Send remote address in init (#1973)
• c180ca2 Postgres: add safety checks at startup (#2140)
• 0a37213 Add randomization on node addresses (#2123)
• 85f9455 Fix error logs formatting in TxPublisher (#2136)
• 2d64187 More aggressive confirmation target when low on utxos (#2141)
• d59d434 Improve getsentinfo accuracy (#2142)
• f3604cf Document onchain wallet backup. (#2143)
• 8758d50 Update cluster documentation [ci skip] (#2122)
• 75ef66e Front: use IMDSv2 to retrieve the instance ip (#2146)
• 57c2cc5 Type ChannelFlags instead of using a raw Byte (#2148)
• ffecd62 Move channel parameters to their own conf section (#2149)
• 1f6a7af Have sqlite also write to jdbc url file (#2153)
• 0333e11 Database migration Sqlite->Postgres (#2156)