# Release Notes (WIP)

## Architectural Changes

As is today, the default database for `lnd` is `bbolt`, an embedded key-value store based on a B+Tree. In the future, we'd like to enable users to be able to swap out `bbolt` for any arbitrary strongly consistent database. In this release, we've made a step towards this goal by introducing a new [KV-store databse abstraction](https://github.com/lightningnetwork/lnd/pull/3833). This new interface allows any database implementation which can adhere to the interface to be dropped into `lnd`.

In the upcoming versions of `lnd`, the first new database [we plan to support is `etcd`](https://github.com/lightningnetwork/lnd/pull/4015), a strngly consistente distributed key-value store which is used as the basis of projects such as Kubernetes. `etcd` actually uses `bbolt` underneath the hood, so it won't be a drastic departure. [Once this issue to further abstract the initializtion of `lnd` is complete](https://github.com/lightningnetwork/lnd/issues/3944), then users will be able to "build their own lnd", attaching a database implementation _at runtime_ which adhere to the the primary interface.

## Payments

### Multi-Path Payments Sending Support

Receiving multi-path payments was already possible since version 0.9. Today we are pleased to announce that this release completes the circle by adding support for [multi-path payment sending](https://github.com/lightningnetwork/lnd/pull/3967).

Preparatory changes for the send functionality that were implemented during the development process are [database support for multiple htlcs per payment](https://github.com/lightningnetwork/lnd/pull/4000) and a payment loop that is [aware of partial sends](https://github.com/lightningnetwork/lnd/pull/3970).

The splitting algorithm that is employed is a variation of "divide and conquer". First, `lnd` will try to complete the payment in a single shot. If that is not possible - because channel capacities aren't sufficient or other constraints like the fee limit are hit - an attempt is made for half the payment amount. After that htlc has been launched, a second path is searched for to pay the remaining amount (the other half). If further failures happen, amounts are repeatedly split until a minimum amount limit is reached or the payment succeeds.

We opted for this relatively simple strategy to begin with. It is expected to address various basic liquidity problems that arose in the past, but it is unlikely to always execute payments in a way that is optimal. The field of multi-path planning is still mostly uncharted and contains lots of challenges. Therefore we hope to collect valuable feedback with this release and use that to drive further development.

Multi-path payments can only be initiated through the `routerrpc.SendPayment` rpc. Payments will be single-shot by default unless the new parameter `max_shards` is set to a value greater than one. `max_shards` controls the maximum number of paths that will be used for the payment.

The following `lncli` command can be used to make a multi-path payment:

`lncli payinvoice --max_shards 5 <payreq>`

Additionally, the payment limit has now be removed for calls to the _new_ MPP-enabled payment API. This allows users to now send payments that fully utilize all their outgoing payment bandwidth.

### Payment tracking

Improvements have been made to provide more fine-grained information about the status of payments.

A list of per-payment htlcs was already added in a prior release. This has now been [extended](https://github.com/lightningnetwork/lnd/pull/4000) with the exact failure reason for failed htlcs.

Furthermore the payment status stream that is returned by `routerrpc.SendPayment` and `routerrpc.TrackPayment` now also [contains intermediate state updates](https://github.com/lightningnetwork/lnd/pull/3972). An example of this is the launch of an additional htlc. This will result in a state update on the stream.

The proto message on these update streams has been aligned to match the main rpc `Payment` message. *This is a breaking change in the sub-server API.*

## Invoices

### Lifted Invoice Limit

As part of the `mpp` changes, [the invoice limit has been lifted from 4.2 million satoshis](https://github.com/lightningnetwork/lnd/pull/4075). With this change, receivers will now be able to create invoices that can be used in tandem with `mpp` at the sender, to fully utilize the channel bandwidth at _both_ the sender and receiver to complete payments.

## Channel Commitments & Funding

### PSBT Funding

It is now possible to [open channels by using a PSBT](https://github.com/lightningnetwork/lnd/pull/4079). This allows users to fund multiple channels in one on-chain transaction and/or open channels directly from a hardware wallet without the need for a transaction to `lnd`'s wallet first. An example of how to use this new feature in combination with a `bitcoind` [node can be found here](https://github.com/lightningnetwork/lnd/blob/master/docs/psbt.md).

NOTE: The normal funding dialog between the initiator's node and the remote node is paused after the multisig keys for the funding transaction have been exchanged. It is therefore possible that the remote node will not wait indefinitely for the flow to continue and cancel the funding reservation after some time. `lnd` nodes will cancel after 10 minutes of inactivity for example.

Future versions of `lnd` will expand the PSBT capabilities in order to allow generalized usage of the transaction packet format for all transaction crafting within the daemon.

### Anchor commitment format

An new commitment format that includes [anchor outputs](https://github.com/lightningnetwork/lightning-rfc/pull/688) has been [added](https://github.com/lightningnetwork/lnd/pull/3821). Anchor outputs allow users to [increase the fee of their commitment transaction](https://github.com/lightningnetwork/lnd/pull/3758) after it has been published by making use of CPFP. The anchor output is [force-swept](https://github.com/lightningnetwork/lnd/pull/3809) in a child transaction that may be negatively yielding. It allows timely confirmation even if the miner fee of the commitment tx itself is insufficient.

To do so, the `BumpFee` rpc can be used to increase the fee of the total package. For channels in the `waiting_close_channels stage`, the following `lncli` command can be issued. Note that `lnd` must be built with the `walletrpc` build tag for this command to be available.

`lncli wallet bumpclosefee 2b66cf489298b5b4a9305127413e4124e385588178e4b0fc4cec2d28c277b17d:0 --sat_per_byte 15`

The specified fee rate is the fee rate of just the child transaction. It needs to be chosen such that the fee rate of the total package including the commitment transaction is bumped to the desired level.

To open a payment channel with anchors, both sides of the channel need to run `lnd` with `--protocol.anchors`. All newly opened channels between those peers will then automatically be of the anchor type.

To facilitate identification, the channel type is now exposed on [`ListChannels`](https://github.com/lightningnetwork/lnd/pull/4068) and [`PendingChannels`](https://github.com/lightningnetwork/lnd/pull/4129).

Be aware that anchor channels are experimental. They don't yet have the reliability track record of the regular commitment format and therefore carry more risk. The specification hasn't been finalized yet, so there is also still a chance of breaking changes in future releases. In that case, *lnd will likely require anchor channels to be closed before upgrading*.

## RPC Changes

Because `lncli` now uses the `jsonpb` JSON marshaler to print RPC responses, the `json_name` hints in the proto files [are no longer necessary and have been removed](https://github.com/lightningnetwork/lnd/pull/3996).

The proto files can now be formatted with the `make rpc-format` command, if the `clang-format` binary is installed. More importantly, [Travis CI now makes sure the proto files were compiled using the correct version](https://github.com/lightningnetwork/lnd/pull/4042) of the protobuf compiler.

`routerrpc` is [no longer conditionally compiled](https://github.com/lightningnetwork/lnd/pull/4128) and from now on available in any build. `lncli` is also switched over to use the payment rpcs of `routerrpc`. The asynchronous `SendPayment` call on the main rpc has been deprecated.

The `--reversed` flag for the `lncli listinvoices` [command has been removed in favor of a new flag: `--paginate-forwards`](https://github.com/lightningnetwork/lnd/pull/4003) in order to make the functionality easier to use.

[The `ListPayments` endpoint now supports _pagination_](https://github.com/lightningnetwork/lnd/pull/3960). The exposed API is similar to the existing pagination support for `ForwardingHistory`. On the command-line, users can set the `index_offset` and `max_payments` values to seek around within their past payment history.

Channel [open](https://github.com/lightningnetwork/lnd/pull/3961) and close initiators are now provided in `ClosedChannels` output. The open initiator field indicates which party paid the fees for the channel close, because channel openers are currently responsible for close fees. The channel initiator is also available for [pending chanenls](https://github.com/lightningnetwork/lnd/pull/4111).

When a channel is opened, the initiating party has the option to push balance to their peer. This balance is now [reflected](https://github.com/lightningnetwork/lnd/pull/4095/) in the `push_amount` field in `ListChannels`.

### Htlc Event Stream
The `routerrpc` server now exposes a [HTLC event stream](https://github.com/lightningnetwork/lnd/pull/3848) which provides an account of the HTLCs that your node is processing. This stream includes sends from and receives to your own node, as well as htlcs forwarded through your node.

Four types of events are produced by this stream:
- Forwarding events: produced by htlcs forwarded through your node, or locally initiated sends
- Settle events: present for successful htlc forwards, local sends and local receives
- Forwarding events: present when htlc forwards or local sends fail
- Link failures: reported when htlcs fail at our node, either due to decoding issues or forwards that fail our outgoing channel's policy

HTLCs in this stream are identified by the combination of their opening and closing channel ID and HTLC ID. Forward events can be matched to their corresponding failure or settle event using this identifier. When consuming this stream, events must be de-duplicated, because HTLCs may be replayed.

### Peer Error Tracking
Lnd now [tracks](https://github.com/lightningnetwork/lnd/pull/4051) the most recent 10 errors that it has received from peers that it has channels open with. We only store errors for peers that we have channels open with to prevent malicious peers from spamming us with errors. By default lncli will only display the most recent error we have received, the full list can be obtained using the `--list_errors` flag. The rpc endpoint will return the full list of errors by default, so there is no need to request the full list. These errors are tracked accross peer disconnections, but are not currently persisted by lnd.

## Routing

### Disallow Same Channel Circular Routes
If a malicious party wishes to lock up your funds on the Lightning Network, they can do so by routing a payment through your node and back to themselves then not settle the htlc until it fails back after the accumulated lock time on the route. The more times the payment can pass through your node's channels, the more liquidity a single payment can lock up. Lnd will [no longer allow](https://github.com/lightningnetwork/lnd/pull/3915) payments that are forwarded through your node to arrive and leave your node on the same channel. This decreases the number of times an attacker can pass through your channel, which increases the cost of attack because they have to make more payments to lock up your liquidity.

Note that this does not affect your own sends. Nor does it affect your ability to circular rebalance your own channels. It does affect your ability to receive invoiceless payments that are achieved by nodes routing a payment through your node and back to themselves, paying high fees to your node in lieu of an actual payment. This method was used by some earlier tipping lapps. Lnd's recently merged experimential Keysend feature provides an alternative way for nodes in the network to make payments without invoices. This protection can be disabled by running lnd with `--allow-circular-route`.

## `bitcoind` Support

[A new config option has been added to allow the user to select which fee estimation modifier](https://github.com/lightningnetwork/lnd/pull/4078) (the confidence parameter) we use when requesting fee estimates from `bitcoind`. users can now select from `CONSERVATIVE` and `ECONOMICAL` using the `--bitcoind.estimatemode` config setting.

## Documentation

An [Operational Safety Guidelines document](https://github.com/lightningnetwork/lnd/pull/3963) has been added that advises users on how to safely operate a mainnet `lnd` node.

## Tor

[We now support authenticating to tor via the `HASHEDPASSWORD` authentication mechanism](https://github.com/lightningnetwork/lnd/pull/4048). This allow users to delpoy `lnd` with `tor` enabled, in configruation where `lnd` may not have access to the filesystem that the `tor` daemon uses.

## Watchtowers

Watchtowers now have support for [automatically setting up a Tor hidden service](https://github.com/lightningnetwork/lnd/pull/4087). This supports both v2 and v3 hidden services and can either be specified on the command line or via config file. Instructions on how to do this can be found [here](https://github.com/lightningnetwork/lnd/blob/master/docs/watchtower.md#tor-hidden-services).

## Testing+Security

`lnd` has a new `fuzz` package which contains fuzzing harnesses for the `lnwire`, `wtwire`, and `brontide` packages. The harnesses for `lnwire` and `wtwire` check that (de)serialization works as expected. The `brontide` harnesses test the validity of various states of the initial brontide handshake. Documentation on how to get started with fuzzing `lnd` can be found [here](https://github.com/lightningnetwork/lnd/blob/master/docs/fuzz.md).

## Miscellaneous

To make automated unlocking of `lnd` nodes easier, the `lncli unlock` [now accepts the password from the standard input](https://github.com/lightningnetwork/lnd/pull/4066), if the `--stdin` flag is passed.
NOTE: This is considered to be unsafe/dangerous if the password is located in a file that can be read by another user. The `--stdin` flag should only be used in combination with some sort of password manager or secrets vault.

## Bug fixes

* The `channel.backup` file is now also [updated while a channel is still pending](https://github.com/lightningnetwork/lnd/pull/3993). Previously a channel was only added to the SCB file once it was fully confirmed on-chain.

* The JSON marshaler used by the REST gateway by default omitted "falsey" values (values that evaluate to `false` in JSON/JavaScript, like `0`, `""`, `false`). This was especially confusing/incorrect with enums. because the whole field was omitted if the first enum option was set (because that defaulted to `0` in the underlying gRPC transport). This [behavior was fixed in the REST marshaler](https://github.com/lightningnetwork/lnd/pull/3965).

* Channel updates received from the remote party are now [stored on disk](https://github.com/lightningnetwork/lnd/pull/3872) until we've produced a signature that includes these updates. Previously the updates were only stored in memory and dropped across restarts. This could lead to the production of an invalid signature and channel force closure.

* A current limitation of the Lightning protocol is that it is possible for the channel initiator to reach a balance that is so close to the reserve, that it is no longer possible to send or receive htlcs with a non-dust value. The internal available channel balance calculation [has been refined](https://github.com/lightningnetwork/lnd/pull/3691) to take this possibility into account and report a lower balance if necessary to prevent the channel from reaching a degraded state.

* Node-level failures are now [penalized harder](https://github.com/lightningnetwork/lnd/pull/3945) in mission control. This prevents routes that are unlikely to succeed from being explored and thereby speeds up the payment process.

* An erroroneous log message [has been nixed](https://github.com/lightningnetwork/lnd/pull/4107). Previously, this message would be printed upon each successful payment and caused some confusion for users when nothing was actually wrong.