@Roasbeef Roasbeef released this Feb 6, 2019 · 784 commits to master since this release

This release is minor release of lnd, which includes several fixes which increase the stability of lnd, and also further increases cross implementation compatibility. There are no new database migrations, or functional RPC changes in this new version. As a result, users should expect a smooth upgrade path with no manual intervention required.

Verifying the Release

In order to verify the release, you'll need to have gpg or gpg2 installed on your system. Once you've obtained a copy (and hopefully verified that as well), you'll first need to import the keys that have signed this release if you haven't done so already:

curl https://keybase.io/roasbeef/pgp_keys.asc | gpg --import

Once you have his PGP key you can verify the release (assuming manifest-v0.5.2-beta.txt and manifest-v0.5.2-beta.txt.sig are in the current directory) with:

gpg --verify manifest-v0.5.2-beta.txt.sig

You should see the following if the verification was successful:

gpg: assuming signed data in 'manifest-v0.5.2-beta.txt'
gpg: Signature made Thu Feb  7 13:29:16 2019 PST
gpg:                using RSA key F8037E70C12C7A263C032508CE58F7F8E20FD9A2
gpg: Good signature from "Olaoluwa Osuntokun <laolu32@gmail.com>" [ultimate]

That will verify the signature on the main manifest page which ensures integrity and authenticity of the binaries you've downloaded locally. Next, depending on your operating system you should then re-calculate the sha256 sum of the binary, and compare that with the following hashes (which are included in the manifest file):

8c1d4c50847c665ac277bc8a659b8320f8a053d074a05e99c59f52ac87033968  lnd-darwin-386-v0.5.2-beta.tar.gz
478833d7d4efbbfe5c04f6ce7f5d69f45a163fcca0d4b83a1cba96556e76b916  lnd-darwin-amd64-v0.5.2-beta.tar.gz
8c351581f7887e5eeb9b2fc905e2057e5d1b03d5e58c29acbaeb19fb320cc157  lnd-dragonfly-amd64-v0.5.2-beta.tar.gz
29bc87951a65d8541b355cba3600db5439d70720addfb8c194a5e035fd20ff47  lnd-freebsd-386-v0.5.2-beta.tar.gz
5dfb7eb58039389f14d0c76a5a54f7d890c80f97ad1be3cb7e39a032b19634b5  lnd-freebsd-amd64-v0.5.2-beta.tar.gz
6422cdee33b42b7efcad84fff4c3d6dddd3e6f015057b7b131f6ce262cc2bf61  lnd-freebsd-arm-v0.5.2-beta.tar.gz
ae2858e8ae7b2cfd9b0901032634056f9839bc26d01edc32e26524d2ba386084  lnd-linux-386-v0.5.2-beta.tar.gz
d876ffe5f18431cb0ec97c75e3d8b34a8d2c84e36a0114636a92dabe71340a99  lnd-linux-amd64-v0.5.2-beta.tar.gz
e178ba9aa7b207b5381519c34fd0b24cc74eebb0e1498536cf267988c6946858  lnd-linux-arm64-v0.5.2-beta.tar.gz
f03401fb24ce7a5d4dc498a6f3c88a766c186ac88d7f52791ecb95b5e983ef5c  lnd-linux-armv6-v0.5.2-beta.tar.gz
9adf9f3d0b8a62942f68d75ffe043f9255319209f751dee4eac82375ec0a86cd  lnd-linux-armv7-v0.5.2-beta.tar.gz
e8ef8bd34384b8f9c52198a53034c30f162cccb8b31262b822424d640ad5dfaf  lnd-linux-mips64-v0.5.2-beta.tar.gz
33037ed61c7f0c1939b1233d579fb39aa9261086f75dd24c7172ea3dba1aa63f  lnd-linux-mips64le-v0.5.2-beta.tar.gz
671bf900995eaa9349e869383397580c9f4d6cbe4d5fbb32673c7b217b4fe10f  lnd-linux-ppc64-v0.5.2-beta.tar.gz
3d3b4d117594becd19f89c1ed82a6167b53a8b22a3351e85b5d21045ade821e8  lnd-netbsd-386-v0.5.2-beta.tar.gz
b090505e313a9998d307c06dc340908145167f262746accca6f330f1d74bbfad  lnd-netbsd-amd64-v0.5.2-beta.tar.gz
d720671b9fc253c4e857bb53875daa15a367b21d20e2d9d2e149714315cfb15a  lnd-openbsd-386-v0.5.2-beta.tar.gz
af0db952379a67e40f988eb94261f59fb0173f63de1806eb38c529751dd6c674  lnd-openbsd-amd64-v0.5.2-beta.tar.gz
f3b601a66fe5a277f8e7600637f15712146971be11adf7074cc01a0edd869be7  lnd-source-v0.5.2-beta.tar.gz
64ce298461dae68133823b3b43cfa7cb05e821e7688f29df14fbce02e64e14a9  lnd-windows-386-v0.5.2-beta.zip
9ac0667a877e3884627c019390cc593b5a783777314b2e30121aac76d1c71993  lnd-windows-amd64-v0.5.2-beta.zip
70607224b051c8919090f108669c35f5582c080cc0341ee1fe953b10b82368ca  vendor.tar.gz

One can use the shasum -a 256 <file name here> tool in order to re-compute the sha256 hash of the target binary for your operating system. The produced hash should be compared with the hashes listed above and they should match exactly.

Finally, you can also verify the tag itself with the following command:

git verify-tag v0.5.2-beta

Building the Contained Release

With this new version of lnd, we've modified our release process to ensure the bundled release is now fully self contained. As a result, with only the attached payload with this release, users will be able to rebuild the target release themselves without having to fetch any of the dependancies. Note that at this stage, binaries aren't yet fully reproducible (even with
go modules). This is due to the fact that by default, Go will include the full directory path where the binary was built in the binary itself. As a result, unless your file system exactly mirrors the machine used to build the binary, you'll get a different binary, as it includes artifacts from your local file system. This will be fixed in go1.13, and before then we may modify our release system to do this automatically.

In order to re-build from scratch, assuming that vendor.tar.gz and lnd-source-v0.5.2-beta.tar.gz are in the current directory:

tar -xvzf vendor.tar.gz
tar -xvzf lnd-source-v0.5.2-beta.tar.gz
GO111MODULE=on go install -v -mod=vendor -ldflags "-X github.com/lightningnetwork/lnd/build.Commit=v0.5.2-beta"
GO111MODULE=on go install -v -mod=vendor -ldflags "-X github.com/lightningnetwork/lnd/build.Commit=v0.5.2-beta" ./cmd/lncli

The -mod=vendor flag tells the go build command that it doesn't need to fetch the dependencies, and instead, they're all enclosed in the local vendor directory.

Additionally, it's now possible to use the enclosed release.sh script to bundle a release for a specific system like so:

LNDBUILDSYS="linux-arm64 darwin-amd64" ./release.sh

The release.sh script will now also properly include the commit hash once again, as a regression caused by a change to the internal build system has been fixed.

⚡️⚡️⚡️ OK, now to the rest of the release notes! ⚡️⚡️⚡️

Notable changes

Expansion of lncli block size

In this release, we increase the gRPC block size from 4MB to 50MB. Recently, the output of lncli describegraph has hit the block size cap due to the expansion of the mainnet graph. Without this attempts to fetch the graph return an error of:

[lncli] rpc error: code = ResourceExhausted desc = grpc: received message larger than max (4246753 vs. 4194304)

With this commit, we give ourselves some breathing room. It's important to note that the max message size limit is a client side setting. As a result, any developers driving lnd with gRPC will also need to raise their block size limit as well if they wish to fetch the graph over gRPC.

Switch to Go Modules for Dependency Management

With this release, lnd now uses go modules rather than glide to handle our package dependency management. End users and developers should see no functional change, as the Makefile is still the primary interaction point when building and testing lnd. Switching to go modules also preps us for the fully reproducible binary builds for Go which are slated to land in go1.13.

Wallet Bug Fixes

The wallet will no longer rescan from the seed birthday if a wallet has no UTXOs once it has already been created.

Config and Wire Protocol Validation Fixes

A node's color is now properly validated when passed in as a config or command line parameter. This fix ensures that we're able to properly parse a hex color before attempting to commit it to the database. With this change, if an invalid color is passed, then lnd will refuse to start.

We'll now validate our own node announcement as a sanity check to ensure generated announcements elsewhere in lnd are fully protocol compliant.

We'll now properly avoid creating empty buckets within bolt which have been the source of prior inadvertent bugs.

We'll now ensure that we don't accept any node announcements with an invalid alias.

A bug has been fixed wherein we'd encode an invalid (too long) length for the enclosed ChannelUpdate within an onion error. This didn't affect lnd nodes as we didn't rely on the encoded length when decoding the error payload. However, other implementations did, which rendered them unable to decode a sub-set of our onion error messages.

lnd will now reject (by default) requests for funding confirmations that we deem are too large.

A bug related to the FeeUpdate message has been fixed which could at times cause two channels to de-synchronize.

lnd, will no longer send the IncorrectHtlcAmount error. Instead, it will now use the new UnknownPaymentHash error that includes the amount of the HTLC.

Network Level Channel Advertisements

All channels created by lnd will now properly have the new max_htlc field set. This is a prep for our upcoming AMP implementation. Payment splitting heuristics can use this value as a guide when determining payment chunk size, and nodes can use this value to control the largest payment shard they'll accept. In a future release, we'll make this value configurable over the RPC interface.

Payment Path Finding and Retries

We've modified our retry and search space pruning code when routing payments to be more consistent. The following issues has been fixed:

  • If the channel update of FailFeeInsufficient contains an invalid channel
    id, it is not possible to properly add to the failed channels set.
  • FailAmountBelowMinimum may apply a channel update, but does not retry.
  • FailIncorrectCltvExpiry immediately prunes the vertex without
    trying one more time.

A bug has been fixed to ensure that we get passed a non-nil route. Previously with unchecked usage of the SendToRoute API, this may have caused a panic.

A change has been made to decouple the disabled bit from our local path finding. This is a preparatory step for an overhaul w.r.t the way we enable/disable channels, which is expected to land in 0.6.

RPC Interface Bug Fixes

We'll now properly validate the ChannelPoint argument for the CloseChannel RPC call. The lncli command validates this field already, but a check was lacking in the main RPC pipeline as it assumed lncli was being used.

Invoices that were created with hop hints will now show up as "private" within the output of lncli listinvoices.

Additional validation has been added to ensure that it's no longer possible to attempt to force close a channel twice over the RPC interface. The second time wouldn't generate any new changes, but could at times unnecessarily block this second call.

Channels that are waiting to be opened, but which also have an unconfirmed closing transaction will now properly show up within lncli pendingchannels.

The UnsettledBalance field in the PendingChannels field will now properly be set.

False positives related to to showing a channel as active have been located and patched.

HTLC Forwarding Fixes

We'll now properly return FinalFailExpiryTooSoon rather than FinalFailIncorrectCltvExpiry when the final hop of a route receives an HTLC expiry that's too soon.

Switch from bolt to bbolt.

In this version, we've made a full switch from bolt to bbolt. bbolt is the maintained fork of the original bolt project. As it's maintained by CoreOS it actively has bug fixes land it in, which should increase the stability of our primary database.

Optimizations

We'll now scan backwards from the latest height back to the height hint when a sub-system needs to query for the unspentness of an output. This speeds up routine scans of recent channel closes as we no longer need to start from potentially months back in the past.

Rather than create a thread pool to generate/check signatures for the commitment updated protocol, we'll now use a global signature thread pool. This serves to reduce the total number of goroutines, idle CPU usage, and memory usage of lnd for larger nodes.

Changelog

The full list of changes since 0.5-beta can be found here:

Contributors (Alphabetical Order)

Chris Coverdale (ccdle12)
Conner Fromknecht
ErikEk
Federico Bond
Johan T. Halseth
Joost Jager
Olaoluwa Osuntokun
orbitalturtle
Valentine Wallace
Wilmer Paulino
Xavi Soler

Assets 26

@halseth halseth released this Nov 28, 2018 · 784 commits to master since this release

This release is minor release of lnd, which includes several fixes and optimizations to make lnd even better. This time around one of the points of focus has been around the reliability, robustness and speed of the Neutrino backend, which is now in a state where it can be used for building applications for the Bitcoin testnet. This will let us sort out the last quirks and performance bottlenecks before it is ready to be enabled for mainnet.

Additionally, a series of bugs have been fixed in primary wallet backend btcwallet. As a result of these prior bugs, there may have been an instance in time when your wallet missed a change addresses. The root cause of this issue has been resolved, with test coverage hardened in the affected areas. In order to ensure all funds are accounted for (and funds are safu!) lnd will perform a chain rescan from birthday once it starts up. For older nodes, nodes with many channels, and nodes with many used addresses, this may take some time. It's recommend to start your node with the LNWL=trace logging level in order to monitor the progress of the rescan.

It is highly encouraged to update to this version.

Breaking changes

  • Remove NewWitnessAddress: The RPC NewWitnessAddress has been removed. Since we are only using witness addresses, addresses can be fetched using NewAddress.

A few RPCs have changed their behavior slightly, see the the RPC changes section.

Database migrations

We have made a change to the closed channels database format (see Dataloss protection improvements), and we now store the wallet's birthday block in the database to speed up rescans. If you are upgrading from an older version of lnd you should at startup see something like

2018-11-28 09:58:46.744 [INF] LTND: Active chain: Bitcoin (network=testnet)
2018-11-28 09:58:46.747 [INF] CHDB: Checking for schema update: latest_version=7, db_version=6
2018-11-28 09:58:46.747 [INF] CHDB: Performing database schema migration
2018-11-28 09:58:46.747 [INF] CHDB: Applying migration #7
2018-11-28 09:58:46.747 [INF] CHDB: Migrating to new closed channel format...
2018-11-28 09:58:46.747 [INF] CHDB: Migration to new closed channel format complete!
2018-11-28 09:58:46.762 [INF] RPCS: password RPC server listening on 127.0.0.1:10006
2018-11-28 09:58:46.762 [INF] RPCS: password gRPC proxy started at 127.0.0.1:8086
2018-11-28 09:58:46.762 [INF] LTND: Waiting for wallet encryption password. Use `lncli create` to create a wallet, `lncli unlock` to unlock an existing wallet, or `lncli changepassword` to change the password of an existing wallet and unlock it.
2018-11-28 09:59:20.459 [INF] LNWL: Applying wallet transaction manager migration #2
2018-11-28 09:59:20.459 [INF] LNWL: Dropping wallet transaction history
2018-11-28 09:59:20.459 [INF] LNWL: Applying wallet address manager migration #6
2018-11-28 09:59:20.460 [INF] LNWL: Setting the wallet's birthday block from timestamp=2018-09-16 20:15:05 +0200 CEST
2018-11-28 09:59:20.461 [INF] LNWL: Estimated birthday block from timestamp=2018-09-16 20:15:05 +0200 CEST: height=400721, hash=0000000001874116d18dca88baf9f5f41b48c69e9c01a7d4fe467df09e5de352
2018-11-28 09:59:20.461 [INF] LNWL: Applying wallet address manager migration #7
2018-11-28 09:59:21.331 [INF] LNWL: Opened wallet

Note that it will then perform a rescan from the birthday, which might take a while. By setting the debug level to debug you'll be able to track the process of this rescan.

Verifying the Release

In order to verify the release, you'll need to have gpg or gpg2 installed on your system. Once you've obtained a copy (and hopefully verified that as well), you'll first need to import the keys that have signed this release if you haven't done so already:

curl https://keybase.io/roasbeef/pgp_keys.asc | gpg --import
curl https://keybase.io/halseth/pgp_keys.asc | gpg --import

Once you have his PGP key you can verify the release (assuming manifest-v0.5.1-beta.txt and manifest-v0.5.1-beta.txt.sig are in the current directory) with:

gpg --verify manifest-v0.5.1-beta.txt.sig
gpg --verify manifest-v0.5.1-beta.txt.sig.halseth manifest-v0.5.1-beta.txt

You should see the following if the verification was successful:

gpg: assuming signed data in 'manifest-v0.5.1-beta.txt'
gpg: Signature made Wed Nov 28 13:31:43 2018 PST
gpg:                using RSA key F8037E70C12C7A263C032508CE58F7F8E20FD9A2
gpg: Good signature from "Olaoluwa Osuntokun <laolu32@gmail.com>" [ultimate]

gpg: Signature made Wed Nov 28 23:30:24 2018 CET
gpg:                using RSA key 7AB3D7F5911708842796513415BAADA29DA20D26
gpg: Good signature from "Johan T Halseth <johanth@gmail.com>" [unknown]

That will verify the signature on the main manifest page which ensures integrity and authenticity of the binaries you've downloaded locally. Next, depending on your operating system you should then re-calculate the sha256 sum of the binary, and compare that with the following hashes (which are included in the manifest file):

e0bfb53c722005d2447be2ccc0e7a5a8f0213e0733f3938264d9164d04d67ee7  lnd-darwin-386-v0.5.1-beta.tar.gz
5886c0228c97fbe5c7798f90c436a38815ac0e88112f78af025ce90b344ad888  lnd-darwin-amd64-v0.5.1-beta.tar.gz
448a6ca7015f1a225dbe162f61669c1bfd4a7a98af405877f020a5eb9ae4d41f  lnd-dragonfly-amd64-v0.5.1-beta.tar.gz
ae9ff40da44db16f51c047101b34cfc1c0903018895f041c8746c91877798a03  lnd-freebsd-386-v0.5.1-beta.tar.gz
16f8a9f357dea4e90ab025cebab57e48d93c3b9026f340d8f3de3675add3b890  lnd-freebsd-amd64-v0.5.1-beta.tar.gz
18867fed043d0a63014df65b8dda16774ede07b5d4496c5f1e6319b873c99d79  lnd-freebsd-arm-v0.5.1-beta.tar.gz
39b529597577c30b4cfa809edebed36031df5f951d0604d3f705bdfc847f8bb7  lnd-linux-386-v0.5.1-beta.tar.gz
41bff3deda46777f498a23feb7feff331638bd0a745fac43ecff99179c701675  lnd-linux-amd64-v0.5.1-beta.tar.gz
a5f3dfff3d93e420b45994b69b1eb97a183c3d3f67e143da0bbb34fb2893ba5b  lnd-linux-arm64-v0.5.1-beta.tar.gz
f714f2bd7db653f921df219fa123fd55e0090d9d4aa20f0f82aae2a2f3db31a8  lnd-linux-armv6-v0.5.1-beta.tar.gz
c8be77708fe95d5076fa6988229100598c14ae6c54e92a56d5f09f3e17732244  lnd-linux-armv7-v0.5.1-beta.tar.gz
da6798a93820889e6f0a68bf03c742510accdf2a684f0a145442e10ea8de91b9  lnd-linux-mips64-v0.5.1-beta.tar.gz
97c97b064088a809e584636733f47c2885b843cc8d802858932c6d1c1a6d5fdb  lnd-linux-mips64le-v0.5.1-beta.tar.gz
1207d49ea114ccdf6b2c10e437c3442adb2f32250444b82e58beaca1cccee443  lnd-linux-ppc64-v0.5.1-beta.tar.gz
a8324390835bb0da44296b3a7468ef3fb676b4ef8b169ca35d473bfd9beac2a0  lnd-netbsd-386-v0.5.1-beta.tar.gz
3bfd0ca1759079217dd09572ddcf0661793fc3eb1db8242d9a861b0597d4ce97  lnd-netbsd-amd64-v0.5.1-beta.tar.gz
0cdd2f32eef3849b5315c2112b90e148c4005e14fe83e5b7c8fb9235bf430447  lnd-openbsd-386-v0.5.1-beta.tar.gz
11ba3a4b5d144f2941b10353bd9b2c98ae5f4d8194c3c347d3fec998e270f8cb  lnd-openbsd-amd64-v0.5.1-beta.tar.gz
f05bcc38bd0dd9ae7f676f3587e96fdb699d0c960146fad0b56571c06bc50f65  lnd-windows-386-v0.5.1-beta.zip
c95b9374c139024bee54a254dc84d9b311c44c4f14b9613d8a7dee79f19e4b10  lnd-windows-amd64-v0.5.1-beta.zip

One can use the shasum -a 256 <file name here> tool in order to re-compute the sha256 hash of the target binary for your operating system. The produced hash should be compared with the hashes listed above and they should match exactly.

Finally, you can also verify the tag itself with the following command:

git verify-tag v0.5.1-beta

⚡️⚡️⚡️ OK, now to the rest of the release notes! ⚡️⚡️⚡️

Notable changes

Neutrino

Neutrino is a new light client for Bitcoin, that is more private and tailored for use on the Lightning Network than previous light clients. For more information, check out this blog post.

Since the previous release of lnd, the version of neutrino used has gained a lot in terms of stability and speed. We now start catching up to the necessary filter hashes the moment we have enough block headers to verify them. This let us do most of the header fetching in parallel, drastically speeding up initial sync.

A number of fixes has also been deployed to ensure neutrino correctly handles header and filter responses from multiple peers in parallel, and even peers serving invalid filters.

Height hint cache

When lnd opens channels to other nodes, it must always make sure the counterparty hasn't unilaterally closed the channel without its consent. This is done by scanning all blocks following the opening of the channel, to ensure no closing transaction has been confirmed. This is a quick check on full nodes, but since neutrino doesn't keep the entire chain around, it must request filters (and potentially blocks) from the network to perform this check.

lnd performs this scan on every restart, checking if any of its channels have been closed while offline. With the addition of height hint caches we are now able to cache the results of previous such scans, letting us start the scan from where we left off, instead of scanning the chain all the way from the block where the channel was opened. With these additions, both txid confirmations and spend detection is now cached. This saves a lot on time and bandwidth at startup, letting light client users get back into sync with the network faster.

Validating received channel updates

When sending a payment, there exists situation where the graph information the client has is not up to date with the nodes it is attempting to route through. In these cases the routing nodes will send an error back along with the updated information, such that the client can retry the payment with the correct parameters.

Previously we didn't check the signatures on this updated information, making it possible for nodes to respond with information for channels they didn't control. With an added validity check, this is no longer the case, and all graph information must be signed by the controlling parties.

forgetchannel RPC

A new RPC has been added for debug builds, that let users forcefully remove channels from their databases. This must be used with caution, as all state for the targeted channels will be lost, essentially making it impossible to recover any funds kept in these channels. This RPC is added to let advanced users get rid of leftover channels from earlier versions of lnd, where channels were not always cleaned up properly. Channels that had their funding transactions broadcast with a fee too small can also be removed with this RPC. To make sure no one uses this functionality by accident, it is only possible to use in debug builds.

Build package

A new package build has been added to lnd, greatly simplifying the process of adding build dependent changes, and improving logging during unit tests. The version string of lnd will with this change include the version tag, commit hash and number of commits since the tag. Logs from unit tests can be inspected by passing log="stdout <loglevel>" to make unit.

Smarter rate limiting

lnd will now rate limit peers that are requesting excessive amounts of data to avoid DOS attacks. Since there are still older nodes running on the network which are acting spammy during graph sync, these will quickly be rate limited. To make sure a single "bad peer" won't degrade the performance of the daemon, they are limited on a per-peer basis.

go 1.11 support

The recommended go version has been upgraded to v1.11! The project now supports go 1.10 and go 1.11.

gRPC 1.15.0

lnd uses gRPC for its RPC interface, making it easy to gain access to the functionality of lnd from a wide set of languages. The gRPC version used was due for an upgrade, and has been updated to v1.15.0, up from v1.5.2. You shouldn't be seeing any breaking changes with this upgrade.

Reject insane timelocks

We now check that forwarded payments don't impose a timelock that is too far in the future. Earlier an attacker willing to lock up his own funds could craft routes where funds got locked up for a very long time.

New sweep package

A new package sweep has been introduced, intended to take care of all kinds of sweeps within lnd, such as retrieving funds from closed channels. This is part of an ongoing effort to reduce the statefulness of funds sweeping, and be smarter about batching sweeps together in bigger transactions to save on chain fees.

rejectpush option

When opening a channel to a peer on the network, you have the option to immediately send some funds as part of the opening process (what is called push amount). For most users accepting incoming channels this is not a problem (hey, free money!), but some merchants have seen customers pushing funds to them by mistake, resulting in an annoying refund process. Now there's a new configuration option --rejectpush that makes the node reject any incoming channels that include a push amount.

Use SendToRoute with private channels

SendToRoute is an RPC that is used by advanced users to send payments along custom paths. Previously it had the restriction that the edges used in these custom paths were known to lnd. A new option pub_key in the route description given to SendToRoute lets lnd create the route without relying on the channel graph, making it possible to attempt payments even for channels unknown to lnd, such as private channels. This works since the payment is encrypted with the given public key, and now all information needed to construct the payload can be supplied over the RPC.

RPC changes

  • Deprecating untyped value fields: Since RPC fields are not always typed to indicate their unit, there has been confusion especially whether satoshis or millisatoshis are used for certain RPCs. Going forward fields should indicate their type (ending with _sat or _msat), and you might see the existing, untyped fields getting deprecated.
  • IncludeUnannounced flag for DescribeGraph: The DescribeGraph RPC is used to get a list of the current information found in the local graph, including all known nodes and channels. Earlier this would include information about private nodes and channels you knew about. With this recent change, the caller must explicitly set the IncludeUnannounced flag if it wishes this private information to be part of the output, to avoid this information being leaked involuntarily.
  • Prevent spending unconfirmed funds by default: The SpendUnconfirmed flag must now be set for the wallet to use unconfirmed inputs when opening channels.
  • Reversed QueryInvoices consistency: When querying for an offset of invoices in the reverse order, we would earlier list the first available invoice found after this offset. This was inconsistent with the non-reversed case, and has been changed.
  • Number of inactive channels in GetInfo: The GetInfo RPC call now shows the number of inactive channels in addition to the number of active.

Changelog

The full list of changes since 0.5-beta can be found here:

Contributors (Alphabetical Order)

AdamISZ
Alex Bosworth
Boblechinois
Carlos Garcia Ortiz
CirroStorm
Conner Fromknecht
Daniel McNally
Dave Kerr
Desuuuu
ErikEk
Francisco Calderón
Harald Nordgren
Johan T. Halseth
Joost Jager
Olaoluwa Osuntokun
Oliver Gugger
Oscar Lafarga
Patrick
Roei Erez
Valentine Wallace
Vincent Woo
Wilmer Paulino
Xavi Soler
babonet13
bluetegu
bob-333
chokoboko
maurycy
sevastos
tailnode
whythat

Assets 25
Nov 26, 2018
lnd v0.5.1-beta-rc4
Nov 21, 2018
lnd v0.5.1-beta-rc3
Nov 16, 2018
lnd v0.5.1-beta-rc2
Pre-release
Pre-release

@halseth halseth released this Nov 15, 2018 · 829 commits to master since this release

lnd v0.5.1-beta-rc1
Assets 2

@Roasbeef Roasbeef released this Sep 18, 2018 · 1182 commits to master since this release

This release marks the 5th major release release of lnd: v0.5-beta! This release marks a massive step in the robustness and reliability of lnd as a routing node daemon for the Lightning Network. Additionally, a number of optimizations have been implemented which will reduce the memory and CPU footprint of lnd making it more amendable to run on smaller devices like Raspberry Pis and also eventually mobile phones! A number of bug fixes related to reliable HTLC forwarding, persistence recovery, and path finding have also landed in this release. As a result users should generally find path finding to be a smoother experience, and should find that lnd is able to recover from a number of partial and complete failures in routine protocol exchanges.

The 0.5-beta release doesn't include any strictly breaking changes. So a result, users should find the upgrade process to be smooth. If one is upgrading from 0.4.2, the initial starting logs should look something like:

2018-09-16 21:55:16.911 [INF] LTND: Version 0.5.0-beta commit=14bc024030d8603fd21b9d18e27a7bb061815d26
2018-09-16 21:55:16.911 [INF] LTND: Active chain: Bitcoin (network=testnet)
2018-09-16 21:55:16.911 [INF] CHDB: Checking for schema update: latest_version=6, db_version=0
2018-09-16 21:55:16.911 [INF] CHDB: Performing database schema migration
2018-09-16 21:55:16.911 [INF] CHDB: Applying migration #1
2018-09-16 21:55:16.911 [INF] CHDB: Populating new node update index bucket
2018-09-16 21:55:16.913 [INF] CHDB: Populating new edge update index bucket
2018-09-16 21:55:16.981 [INF] CHDB: Migration to node and edge update indexes complete!
2018-09-16 21:55:16.981 [INF] CHDB: Applying migration #2
2018-09-16 21:55:16.981 [INF] CHDB: Migrating invoice database to new time series format
2018-09-16 21:55:16.981 [INF] CHDB: Migration to invoice time series index complete!
2018-09-16 21:55:16.981 [INF] CHDB: Applying migration #3
2018-09-16 21:55:16.981 [INF] CHDB: Applying migration #4
2018-09-16 21:55:17.028 [INF] CHDB: Migration of edge policies complete!
2018-09-16 21:55:17.028 [INF] CHDB: Applying migration #5
2018-09-16 21:55:17.028 [INF] CHDB: Migrating database to support payment statuses
2018-09-16 21:55:17.028 [INF] CHDB: Marking all known circuits with status InFlight
2018-09-16 21:55:17.028 [INF] CHDB: Marking all existing payments with status Completed
2018-09-16 21:55:17.028 [INF] CHDB: Applying migration #6
2018-09-16 21:55:17.029 [INF] CHDB: Migrating database to properly prune edge update index
2018-09-16 21:55:17.218 [INF] CHDB: Migration to properly prune edge update index complete!

Breaking Changes

  • One lncli related change that users running on simnet or testnet will notice is that the default location for macaroons has now changed. As a result, lnd will generate a new set of macaroons after it has initially been upgraded. Further details will be found below, but lnd will now generate a distinct set of macaroons for simnet, testnet, and mainnet. As a result, you may need to supply additional arguments for lncli to have it work as normal on testnet like so:

    lncli --network=testnet getinfo
    

    or

    lncli --chain=litecoin --network=testnet getinfo
    

    In order to cut down on the typing one needs to go through, we recommend creating an alias like so:

    alias tlncli=lncli --network=testnet
    

    NOTE: In this release, the --noencryptwallet command line and config argument to lnd has been phased out. It has instead been replaced with an argument identical in functionality, but distinct in naming: --noseedbackup. The rationale for this change is to remove the foot gun that was the prior config value, as many users would unknowingly create mainnet nodes using the argument. This is dangerous, as if done, the user wouldn't receive a recovery mnemonic to recover their on-chain funds in the case of disaster. We've changed the name of the argument to better reflect the underlying semantics.

  • Users running a bitcoind backend will need to modify their existing ZMQ-related settings. Previously, lnd listened on one shared port for both blocks and transactions. 0.5 requires two distinct ports to be set, such that they are isolated. Users should remove the old bitcoind.zmqpath entry in lnd.conf, and, for example, replace it with:

     bitcoind.zmqpubrawblock=tcp://127.0.0.1:28332
     bitcoind.zmqpubrawtx=tcp://127.0.0.1:28333
    

    Also ensure that bitcoind is exposing distinct ZMQ ports in bitcoin.conf:

    zmqpubrawblock=tcp://127.0.0.1:28332
    zmqpubrawtx=tcp://127.0.0.1:28333
    

Verifying the Release

In order to verify the release, you'll need to have gpg or gpg2 installed on your system. Once you've obtained a copy (and hopefully verified that as well), you'll first need to import roasbeef's key if you haven't done so already:

curl https://keybase.io/roasbeef/pgp_keys.asc | gpg --import

The keybase page of roasbeef includes several attestations across distinct platforms in order to provide a degree of confidence that this release was really signed by "roasbeef".

Once you have his PGP key you can verify the release (assuming manifest-v0.5-beta.txt and manifest-v0.5-beta.txt.sig are in the current directory) with:

gpg --verify manifest-v0.5-beta.txt.sig

You should see the following if the verification was successful:

gpg: assuming signed data in 'manifest-v0.5-beta.txt'
gpg: Signature made Fri Sep 14 13:26:49 2018 PDT
gpg:                using RSA key F8037E70C12C7A263C032508CE58F7F8E20FD9A2
gpg: Good signature from "Olaoluwa Osuntokun <laolu32@gmail.com>" [ultimate]

That will verify the signature on the main manifest page which ensures integrity and authenticity of the binaries you've downloaded locally. Next, depending on your operating system you should then re-calculate the sha256 sum of the binary, and compare that with the following hashes (which are included in the manifest file):

4f88ab4f19a41193e2e246a13981cec3c20f5b3bb7422af60955acf1a077e1cd  lnd-darwin-386-v0.5-beta.tar.gz
079c5398b952f8a479b3b0cad3bac2d4bcd52f7d5140688da2255728a607cf76  lnd-darwin-amd64-v0.5-beta.tar.gz
03942a1b09287653767c57278180806ad26f943e80121c2ce2fda9856438ffdf  lnd-dragonfly-amd64-v0.5-beta.tar.gz
95cc950191a1cddf03010052a3fd5b92971bbbfe53f84a17290863bb09974705  lnd-freebsd-386-v0.5-beta.tar.gz
9b7b92077a301cacaf5fe9a1f19473c9cc44adffaee401b1028c6d313882c574  lnd-freebsd-amd64-v0.5-beta.tar.gz
0834b4cd949cea3a3602c5c532e1f4b31ceba6ea6a54a47b941170709991086f  lnd-freebsd-arm-v0.5-beta.tar.gz
7fddc4a8cc039535a9450c24dc253f34a2d7620d306aaa894d6313ec510bf5b7  lnd-linux-386-v0.5-beta.tar.gz
d42ebcc3626016417c9473285190db90e4d7a634c69142fa16f0b182befe7edc  lnd-linux-amd64-v0.5-beta.tar.gz
b634e8877d18079d4a8dbdb6e8126806a1fd51a1752c00b934379b0f0fd93577  lnd-linux-arm64-v0.5-beta.tar.gz
3ac1113ae94c99609abd0c4da78f472689277551a9bd8e1a4e33d8b5051c8675  lnd-linux-armv6-v0.5-beta.tar.gz
f3d578e90061541935e0de888a40377d5131bb5008317ff8af11e245fe2c8510  lnd-linux-armv7-v0.5-beta.tar.gz
b842bdb31410a1de45e8edbeaade49987e7277592b846e8ef2f26421b71d9b9f  lnd-linux-mips64-v0.5-beta.tar.gz
b00489e3dc31359578011559acc88e851d53a6a4b9d7a49d4da5d4f614f25b55  lnd-linux-mips64le-v0.5-beta.tar.gz
bdc3a5ca87130520e93be58533a6d8bb40f709716c87051d69572a5f077d12b5  lnd-linux-ppc64-v0.5-beta.tar.gz
792c3296b90fc8b71bd00e391e930a6563fd1725508d58c815e6a83eb52e23c9  lnd-netbsd-386-v0.5-beta.tar.gz
9cb9c93eb185439bbd8059b2bac083b9f2de2f23a2e73beac9d4c9697d8b1958  lnd-netbsd-amd64-v0.5-beta.tar.gz
b39325128b19863ed67653f41abca10c8412eeea216c4721cdec516df6ecf77a  lnd-openbsd-386-v0.5-beta.tar.gz
9e545e29252559173866e037e08b4b94425d9acb82d0701da001d51815773857  lnd-openbsd-amd64-v0.5-beta.tar.gz
1bd6a2738de0d3408d8eff5e1a345eee0712553f72352fefe0ee1af133811218  lnd-windows-386-v0.5-beta.zip
c6d4b1a54338753a808c6cd3c23da4a840e1dab6aafd58030fe1a5e81a6d7e5d  lnd-windows-amd64-v0.5-beta.zip

One can use the shasum -a 256 <file name here> tool in order to re-compute the sha256 hash of the target binary for your operating system. The produced hash should be compared with the hashes listed above and they should match exactly.

Finally, you can also verify the tag itself with the following command:

git verify-tag v0.5-beta

This release can also be found in roasbeef's public keybase folder.

After go1.12 is released, we'll be switching to a method in order to allow deterministic builds to allow for third party verifiability of the binaries included in this release.

⚡️⚡️⚡️ OK, now to the rest of the release notes! ⚡️⚡️⚡️

Notable Changes

Switch to Mainline btcsuite Libraries

With this release of lnd, the project no longer uses roasbeef's set of forks for the btcsuite family of libraries such as btcd, and btcutil. The old set of forks will no longer be maintained as all development will now be focused on mainline btcsuite. Additionally, roasbeef is now a maintainer of the btcsuite set of libraries. As a result, we'll be able to easily integrate any new feature or bug fixes we need to btcsuite directly, rather than maintaining our own fork again. As a result, we recommend that those users running lnd with a btcd upgrade to the latest versions of the master branch of btcd.

txindex For Full Node Backends is Now Optional!

Before this release, if a user was running with any of the supported full node backends we required them to run with the transaction index active. With this version of lnd, running a full node backend with a transaction index is now optional! As a result, if a user wishes to run a lighter version of their full node without the transaction index, then they're able to do so. However, for performance reasons until the persistent height hints are re-activated, we recommend running with an active transaction index for your full node which backs lnd. In either case, lnd will automatically detect if the backing full node has an active transaction index and act accordingly.

Future releases of lnd will allow for even lighter full node configuration by supporting pruned nodes as a first class citizen.

Neutrino BIP 157+158 Compliance and Optimizations

This release of lnd contains several bug fixes, and optimizations for the neutrino light client backend. Additionally, our implementation of BIP 157 and BIP 158 are now fully compliant with the latest version of the set of BIPs. The primary change between this version of the BIP 158 and the prior version lies in exactly what the filters contain In a prior version, the regular filter contained: the txid of each transaction found in a block, the previous outpoint that all inputs spend, and finally the pkScript of each created output. The new version instead simply includes: the previous output script that each input references, and each pkScript created by outputs in the block. This modification results in more compact filters as scripts can be de-duplicated across blocks, and we drop an additional element per transaction. Several core interfaces within lnd have been revamped to listen for spends based on scripts (rather than outpoints) and confirmations based on scripts (rather than txids).

A re-write of the syncing logic for neutrino was undertaken in order to fix a number of stalling and performance related bugs in the prior implementation. At the time of writing of these release notes btcd is the only full node implementation that is able to serve BIP 157 clients. The latest version of the master branch of btcd has also been updated to be fully compliant with both BIP 157 and 158.

The latest version of the neutrino implementation that's packaged with lnd will now cache filters and blocks in memory. In prior versions of the implementation all filters would be written to disk. This is unnecessary, as in the typical case, a filter is only scanned and checked once, therefore it's safe to never write them to disk and instead only maintain a simple in-memory cache with a size based eviction policy. Caching filters (with an option to write select filters to disk) allows us to reduce to reduce the on-disk footprint for the neutrino mode of operation. We'll also now maintain a cache for blocks as during channel validation, it's likely that a block contains several funding transactions. Caching these blocks allows us to cut down on redundant p2p traffic, instead utilizing a pre-deserialized version of a block for validation purposes.

Finally, a number of bugs have been fixed in the primary rescan logic for neutrino which serves as a base abstraction for many components within lnd.

Duplicate Payments

A new ControlTower has been integrated into the switch, which prevents payments exhibiting the reused payment hashes from being in-flight simultaneously, in addition to rejecting further attempts once a payment to a given hash is successful. By comparing the payment hashes directly, this also prevents paying two distinct invoices that include the same payment hash.

Query Graph Sync

With this version of lnd, we now implement the "query graph syncing" feature which has recently been added to the BOLT specifications. With this change, establishing connections to new peers for a fresh node is much lighter. The primary distinction is that when requesting the network view of the node we're connecting to, we'll now longer request they send all the data they have. Instead, treating the blockchain and channels opened within it as a time series, we're able to precisely request only the data we need, eliminating redundant bandwidth usage and processing on both sides.

As a result of this change, the load on routing nodes should generally be much lower, as they'll only request new channels they don't already know of from newly connected peers. We've taken an additional step forward, and now require this feature for nodes that the neutrino mode will connect out to. By doing this, we ensure the node we're connecting to doesn't send any zombie channels, causing us to populate our local network view with stale, likely abandoned channels.

Aggressive Graph Vertex Pruning

In order to maintain a healthy view of the network, lnd currently prunes any channels which haven't sent out a channel update heartbeat in 2 weeks. We call these pruned channels "zombie channels". In this release, [we now go a step further and prune out any nodes which don't have any active channels within the network](#1371. This serves to keep our view of the network tight and lively.

lnd currently keeps a special set of LinkNodes within the database that represent nodes which we have direct channels with. In addition to this unconnected vertex pruning, we now ensure that we won't automatically attempt to connect to a node on start up if we don't have any existing channels to itself. In the past, a lack of this feature has caused issues for larger nodes that have historically had a high channel turn over rate.

Async Daemon Start Up

In prior versions of lnd a number of blocking actions such as re-registering for confirmation and spend notifications would slow down the startup time of the deamon as we would wait for things like historical dispatches to finish before moving onto the next sub-system to start up. Additionally, in the prior release, establishing a new peer connection was done in a synchronous manner, meaning that we would only be able to carry out a single p2p handshake at a time. In the worst case, lnd would take tens of minutes to start up if the node was heavily loaded with channels.

In this new release we've modified all ChainNotifier registrations to be fully async. As a result, we'll no longer block for their historical dispatch checks on startup, and instead can pipeline the start up of all sub-systems within the daemon. On the server, side, once we obtain a TCP socket, all other peer negotiation is now done in a distinct goroutine. These two changes should dramatically lower the initial start up time of the daemon for more heavily loaded nodes.

New SendToRoute RPC!

A new routing/payment related RPC has been added to lnd: SendToRoute. The RPC can be seen as a companion RPC to the existing QueryRoutes RPC. One can view this RPC as the Lightning analog to the createrawtransaction RPC typically implemented within Bitcoin full node daemons. The SendToRoute RPC allows a caller to specify a custom route, which includes all details required to dispatch an HTLC such as the fee and time lock information at each hop of the route. The RPC has been fashioned in a way that allows users to either re-use the existing output from the QueryRoutes command, or craft a custom route by hand via a special JSON route format.

There are three ways to specify routes:

  • using the --routes parameter to manually specify a JSON encode set of routes in the format of the return value of queryroutes: lncli sendtoroute --payment_hash=<pay_hash> --routes=<route>

  • passing the routes as a positional argument: lncli sendtoroute --payment_hash=pay_hash <route>

  • or reading in the routes from stdin, which can allow chaining the response from queryroutes, or even read in a file with a set of pre-computed routes: lncli queryroutes --args.. | lncli sendtoroute --payment_hash=H -. Notice the '-' at the end, which signals that lncli should read the route in from stdin

This was one of our most requested RPCs as it allows the caller to execute advanced maneuvers on the Lightning Network such as self-rebalancing channels, making custom protocols which rely on data delivered within the Sphinx per-hop onion blob, and also cross-chain atomic swaps which need to manually specify the a particular HTLC is to be forwarded on a distinct chain from that which it came in on.

Strict Local HTLC Forwarding

In order to more precisely support the creation of self channel rebalancing scripts, we've modified the HTLC Switch to implement strict local forwarding. Before this change, when a node had multiple channels to another node and the first hop specified was meant to traverse that node's links, the system would select the link with the highest available bandwidth. However, it may be the case that a users rebalancing script instead wishes to target a distinct channel. With strict forwarding however, we'll ensure that we take the specified first hop rather than attempt to make a forwarding time decision using our additional information. Notably, we don't do so for remote routes, as there's no guarantee as to which link a node forwarding a remote HTLC will choose as there's no way to enforce a particular action.

Automatic Channel Disable Policy

Within the protocol there exists a mechanism that allows nodes to "disable" a channel, marking it ineligible for carrying routed HTLC payments. Disabling channels that are faulty, inactive, or unable to route for w/e reason allows nodes on the network to have a better view of the "healthy" set of routable channels. The latest version of lnd will now disable channels in two instances:

  1. When we co-op close or force close a channel. This signals to the network that the channel is in the process of being closed on the main chain, and therefore isn't eligible to route HTLCs. By sending out this disable update, we save the network a set of between the point of commitment broadcast, and the transaction being mined into the chain.
  2. If the peer is unreachable for a period of time T. The current default period is 20 miuntes, however this can be set from the command line via the inactivechantimeout option:
      --inactivechantimeout=                                  If a channel has been inactive for the set time, send a ChannelUpdate disabling it. (default: 20m0s)

These two measures should serve to reduce the number of failed routed HTLCs due to UnknownNextPeer errors, and we start to tend towards a network view of nodes with high uptime and availability. This is a small step towards our goal of bootstrapping a network with reliable, highly available nodes.

Reduced Idle CPU Usage

Users operating more heavily-loaded routing nodes should generally perceive lower idle CPU usage time. A number of optimization have been executed which reduce the number of idle goroutines, the number of goroutines per connection/channel, and also the number of high frequency tickers within the codebase.

In 0.4.2, idle links would wake up every 50ms to check if they had any HTLCs to process. This caused wasteful CPU utilization, since we should only need to do so if there are unprocessed HTLCs. To remedy this, a new ticker package was implemented that allows the tickers to be stopped and resumed conditionally, based on the presence or absence of pending HTLCs. With 0.5, the idle CPU usage of active links has been reduced drastically since links will now be truly asleep when not processing HTLCs.

Automatic Tor V2+V3 Onion Services

Prior versions of lnd introduced the ability to establish outbound connections over Tor via the socks proxy interface. This allows users to run routing nodes or clients without revealing the location of their routing nodes. This adds an additional layer of privacy as nodes no longer need to expose their IP address in order to route or send payments within the network. The latest version of lnd takes things a step further and enables automatic provisioning of an onion service to allow a node to accept inbound connections over Tor.

The auto setup works as follows: if --tor.active --tor.v2 is set within the configuration, then lnd will attempt to automatically seek out and authenticate with the Tor daemon running at the specified control port. If we're able to connect out, then we'll create a new onion service identity, and modify lnd to only listen on localhost. In this mode, we also ensure that all DNS queries utilize the SOCKS5 interface for tunneling DNS over Tor. In this version we also support the new v3 onion services (--tor.v3. The new onion service protocol represents a large step for the Tpr network, as it does away with the existing legacy crypto used within the system, and also strengthens onion services against a number of discovered attacks.

We'll soon be updating our DNS seed to be able to crawl and serve onion service peers. This will allow those that wish to run purely over Tor to easily find peers they can connect to. For further documentation we recommend users check out our official Tor integration docs, as well as the relevant section of the sample-lnd.conf.

Dataloss Protection Recovery

Within the protocol, there exists a measure put in place that will allow nodes that have partially or complete lost data to recovery a portion of the funds they had within active channels. We call this feature "dataloss protection". The latest version of lnd has now completely implemented this feature! In the rare case that users exhibit partial data loss, upon connection to a peer which we had a channel open with, lnd will automatically prompt the user to close out the channel as it can no longer be used. At that point, we'll then proceed to sweep out settled balance within the commitment transaction on-chain, and clean up the remaining channel state.

Future versions of lnd, will finalize the ingratiation of this feature by also introducing static channel backups. These backups are essentially static files which represent a description of the channel, namely: the parameters used, location on chain, channel peer, key paths we used within the channel, etc. With this set up backups and a users seed, in the face of total data loss, we'll be able to recover the settled balance in the set of open channels.

Reliability improvements to bitcoind backend

Prior versions of lnd were plagued with reliability issues when interacting with the bitcoind backend. We'd at times miss notifications, or even drop block notification causing is to miss events such as a funding transaction confirming, or a channel being closed. With this new version of lnd we've implemented several measures to ensure that we no longer miss any notifications from bitcoind, and even if we do, then we're able to safely backtrack and recover from any missed block notifications.

Before 0.5, we would receive block and transaction notification via the same zmq socket. As transaction notifications (mempool inclusion) is much more common than block notifications, they would dominate the queued backlog at any given time. In certain conditions, due to the notification backlog, block notifications would be dropped once the queue gets above a high water mark. To avoid possibly missing block notifications, we now split the notification sources into two distinct sockets. This ensures that the less critical transaction notifications are isolated to a distinct queue from the block notifications. Due to this change, users must now specify distinct sockets for block and transaction notifications like so:

lnd --bitcoin.active --bitcoin.testnet --bitcoin.node=bitcoind --bitcoind.zmqpubrawblock=tcp://127.0.0.1:28332 --bitcoind.zmqpubrawtx=tcp://127.0.0.1:28333

HTLC Switch Persistence and Reliability Improvements

Removing links has been reworked to be blocking from the caller’s perspective, offering safer isolation during shutdown and interactions with flapping peers. When shutting down LND, stopping links is now done concurrently, offering faster shutdowns to users with high channel counts.

Prior to the added safety surrounding removal of links, some issues were found that caused users to end up with an invalid, albeit recoverable, database state. 0.5 includes a fix to automatically cleanup any databases that entered this state, which would otherwise prevent startup. The link startup logic has also been altered to ensure we don’t read from this invalid state.

The htlcswitch relies on a series of internal logs, referred to as forwarding packages, for ensuring that HTLCs are retransmitted internally with at-least-once semantics. An issue was fixed in 0.5 where a missing reference on failed packets would prevent the persistent references from being removed, and resulting in unnecessary internal retransmission and processing of the HTLCs on startup and peer reconnection. To correct databases that were not properly cleaning up this state, links will now cleanup any references for packets that are detected as duplicates internally. The combined result of both changes is reduced log spam and startup/reconnection latency.

Processing of locally-sourced HTLC responses has been made asynchronous, so that it does not block the primary forwarding loop within the switch resulting in better performance and database batching. The ordering of database operations has also been reordered to properly cleanup forwarding package references, even if the daemon has been restarted. References that had not been cleaned up prior will be cleaned up after a restart with 0.5.

On channel reestablisment, links will now force close the channel when detecting certain irrecoverable failure cases, such as remote data loss and invalid commitment points.

When sending locally-initiated payments out of the switch, we will now honor the exact channel requested by the channel router. Previously, we allowed the switch to select the best link to the same peer if multiple existed. However, this caused issues when trying to use SendToRoute since the user couldn’t be sure which channel the payment would flow over. This change allows provides a more feedback mechanism to the router, since local failures are now known to have been sourced from the outgoing link.

Link-level fee updates are less aggressive, and now use randomized interval for each link. Prior all links checked for fee updates with each block, which resulted in an unnecessary number of state updates.

Timelocks of forwarded HTLCs are now validated against the outgoing channel policy. Previously, the CLTV was incorrectly compared to the policy of the incoming link, resulting in unnecessary routing failures.

An exit hop will now properly return FailFinalExpiryTooSoon when rejecting an HTLC whose timeout is too close to the current block height. The previous behavior incorrectly returned FailFinalIncorrectCltvExpiry, which should only be used if the timeouts are malformed.

Default Autopilot Improvements

The current autpoilot driving agent has received a number of updates in this new version.

t's now possible to instruct the agent to only create unadvertised channels via the autopilot.private flag. This will be useful for desktop and mobile clients which won't be actively routing payments. When attempting to receive funds over these non-advertised channels, the AddInvoice RPC will now automatically populate the required routing hints which will allow nodes to traverse these non-advertised channels on the "edge" of the graph.

One can now also specify the number of confirmation that outputs need to have before the agent starts to use them as inputs into channels. By specifying 0 confirmations, the agent is able to aggressively pipeline channel openings, resulting in a faster time-to-first-n-channels than prior versions.

Finally, the agent will now first probe nodes to see if they're actually active and online, before marking them as a target directive to be executed. This will result in less failed attempts, as we only try to open a channel with a node that we know will respond to our request.

Distinct Network Macaroons

In prior versions of lnd, a single set of macaroons were used for all possible networks (testnet, simnet, mainnet). This approach was flawed however, due to the fact that if one gave out a (possibly attenuated) macaroon for say testnet, then that same macaroon would be utilized for mainnet. This new version of lnd has now reverted this behavior, in favor of network specific macaroons. With this change, the default location of all macaroons has been modified, and the behavior of lncli change das well. Once users upgrade, a new set of macaroons will be created under the chain data directory for each supported network. For example, one can find the testnet invoice macaroon for Bitcoin at:

~/.lnd/data/chain/bitcoin/testnet/invoice.macaroon

Most other behavior has been left unchanged, however, one must now also specify the target network (and also possibly chain) when using lncli, via the new set of arguments:

   --chain value, -c value    the chain lnd is running on e.g. bitcoin (default: "bitcoin")
   --network value, -n value  the network lnd is running on e.g. mainnet, testnet, etc. (default: "mainnet")

Any scripts or gRPC programs will need to be modified in order to utilize the new set of macaroons, as any other prior created macaroons are now invalidated, as the root macaroon key has been regenerated.

Revamp of HTLC Pathfinding Algorithm

A number of changes have been made to the default HTLC path finding algorithm to fix existing bugs in our fee calculation, edge weighting, and also fee ceiling enforcement.

The old path finding algorithm would proceed to look for a path to the destination, starting from a given source (lnd). The old algorithm had several issues, namely: we would take into account our first outgoing edge in the edge weighting, we wouldn't properly factor in the carry over backwards in the route as fees were added meaning we wouldn't compute the fee ceiling properly, and finally we would skew the path finding based on our own outbound routing policies. The new path finding code fixes all of these issues, and also revamps our testing infrastructure to make it easy to add new test cases in the future.

Our old weighting function would at times prefer a route with higher fees but a an identical timelock, over a shorter route with lower fees and a similar timelock. Rather than try to scale the fees or timelock to be promotional, we instead now normalize the timelock values to essentially act as "extra fees". We borrow the terminology of a "risk factor" from c-lightning. Check out this table from the original PR for a demonstration w.r.t how this improves our path selection given a set of candiate routes.

Finally, the prior path finding code had a bug where it wouldn't properly carry over the fees from the prior hop when traversing backwards to convert a path into a route. This issue would cause unnecessary HTLC routing errors when routing over edges with a particular configuration fee wise. This new release of lnd fixes this bug by ensuring we properly compute and carry over fees which allows us to properly detect the case where a link can carry the initial amount, but once we factor in fees, it can no longer carry the final HTLC.

contractcourt Reliability Improvements

A number of bug fixes and reliability improvements has been made within the contractcourt, the sub-system that lnd uses to handle all on-chain interaction related to contract (such as HTLCs, etc). We now ensure that the handoff of a closed channel to the resolver which will ultimately resolve any pending contract is fully reliable.

Optional NAT Traversal (NAT-PMP + UPnP)

lnd has now gained the ability to optionally attempt NAT traversal so clients that are behind at NAT are able to establish incoming connections from other peers in the network. The current system will try either NAT-PMP or UPnP to punch a hole in the nat, which ever of them works first. If lnd is unable to punch a hole, then it will fail to start in order to inform the users that the networking maneuver was unsuccessful. Additionally, lnd will spawn a background goroutine which will periodically poll the router to see if the external IP has changed, if so, then we'll send out a new announcement on the network so that nodes always reach us at our latest IP address. This feature will be useful for those that cannot obtain static IPs where they run their nodes, and instead have a dynamic IP address which changes every few hours/days.

In order to activate the auto NAT traversal use the following argument:

      --nat                                                   Toggle NAT traversal support (using either UPnP or NAT-PMP) to automatically advertise your external IP address to the network -- NOTE this does not support devices behind multiple NATs

Unix Socket Support for RPC

The primary gRPC server is now able to listen on unix sockets! An example of a valid configuration is:

rpclisten=unix:///var/run/lnd/lnd-rpclistener.sock

Robust Streaming Notification Delivery for Received Payments

In this new version of lnd, we modify the streaming invoice subscription API slightly in order to allow callers to have assurance that they haven't missed any new payments. The SubscribeInvoice API now has two new values: add_index, and settle_index. To match these new values, the Invoice message has also gained a similar set of fields. These two indexes effectively act as an event time series: each time a new invoice is added the add_index will be incremented, and each time a new invoice is settled the settle_index will be incremented. With this new feature, clients can now specify one or both of these new optional fields with the last index they know of. If specified, then we'll query the database to find all events greater than this index, and then deliver these backlog notifications before sending out any new notifications.

Care has been taken to ensure that the new API is backwards compatible with the expectations of the old API. Namely, if the fields aren't specified (are zero), then no backlog notifications will be delivered. As a result, the index on-disk actually starts at 1.

A database migration has been created in order to upgrade old databases to the new invoice schema that has these two new indexes which need to be updated each time a new invoice has been added, or an exiting one settled.

Finally, a new field has been added to the on-disk Invoice struct: AmtPaid. This new field allows the link to commit exactly what value was accepted for the final invoice. This is important as invoices may have not have any value attached to them at all ("donation" invoices), or it may be the case that the invoice was overpaid. In either case, the final value accepted for an invoice will now be stored on disk, and queryable over the RPC interface. The value is exposed via RPC in satoshi and millisatoshi deominations,AmtPaidSat and AmtPaidMsat repsecitvely.

RPC Changes:

The ListInvoices command can now optionally be paginated. This was added as after a certain amount of invoice have been created, we can no longer return them in a single response over gRPC. On the command line, a new set of arguments have been added to control the pagination:

⛰ lncli listinvoices -h
NAME:
   lncli listinvoices - List all invoices currently stored.

USAGE:
   lncli listinvoices [command options] [arguments...]

CATEGORY:
   Payments

OPTIONS:
   --pending_only        toggles if all invoices should be returned, or only those that are currently unsettled
   --index_offset value  the number of invoices to skip (default: 0)
   --max_invoices value  the max number of invoices to return (default: 0)

A new ClosedChannels RPC has been added which will allow users to query for their historical closed channel state. The new command allows users to query for a particular close type as well:

⛰i  lncli closedchannels -h
NAME:
   lncli closedchannels - List all closed channels.

USAGE:
   lncli closedchannels [command options] [arguments...]

CATEGORY:
   Channels

OPTIONS:
   --cooperative       list channels that were closed cooperatively
   --local_force       list channels that were force-closed by the local node
   --remote_force      list channels that were force-closed by the remote node
   --breach            list channels for which the remote node attempted to broadcast a prior revoked channel state
   --funding_canceled  list channels that were never fully opened

On-Chain Fee Management

On-chain fee management within lnd has been revamped in order to fix a number of errors related to fees being too low, and rounding errors that can occur when converting between vsize and weight. With these changes, we now use the kilo-weight unit everywhere internally, and now also ensure that we never dip below the widely used min relay fee on the network. In the past there were many issues related to funds not being swept from contracts due to sweeping transaction not propagating during times when fees on mainnet and testnet where very low.

Changelog

The full list of changes since 0.4.2-beta can be found here:

Contributors (Alphabetical Order)

  • 34ro
  • Ben Woosley
  • Brenden Matthews
  • Conner Fromknecht
  • Dan Bolser
  • Johan T. Halseth
  • John Griffith
  • jonny1000
  • Joost Jager
  • Lightning Koala
  • hackerrdave
  • Matthew Lilley
  • maurycy
  • Offer Markovich
  • Olaoluwa Osuntokun
  • Oliver Gugger
  • parth
  • Phil Opaola
  • rawtxapp
  • Rudy Godoy
  • Rui Gomes
  • Sebastian Delgado
  • shtirlic
  • Stefan Menzel
  • Suriyaa ✌️
  • t4sk
  • Vadym Popov
  • Valentine Wallace
  • Vegard Engen
  • Wilmer Paulino
  • Xinxi Wang
  • Yaacov Akiba Slama
  • Yohei Okada
Assets 24

@Roasbeef Roasbeef released this Sep 6, 2018 · 1263 commits to master since this release

This release marks the 5th major release release of lnd: v0.5-beta! This release marks a massive step in the robustness and reliability of lnd as a routing node daemon for the Lightning Network. Additionally, a number of optimizations have been implemented which will reduce the memory and CPU footprint of lnd making it more amendable to run on smaller devices like Raspberry Pis and also eventually mobile phones! A number of bug fixes related to reliable HTLC forwarding, persistence recovery, and path finding have also landed in this release. As a result users should generally find path finding to be a smoother experience, and should find that lnd is able to recover from a number of partial and complete failures in routine protocol exchanges.

The 0.5-beta release doesn't include any strictly breaking changes. So a result, users should find the upgrade process to be smooth. If one is upgrading from 0.4.2, the initial starting logs should look something like:

2018-08-29 01:50:42.690 [INF] LTND: Version 0.5.0-beta commit=73af09a06ae9cd5ba92a376e8253ae5450fe09cc
2018-08-29 01:50:42.690 [INF] LTND: Active chain: Bitcoin (network=mainnet)
2018-08-29 01:50:42.925 [INF] CHDB: Checking for schema update: latest_version=5, db_version=0
2018-08-29 01:50:42.925 [INF] CHDB: Performing database schema migration
2018-08-29 01:50:42.925 [INF] CHDB: Applying migration #1
2018-08-29 01:50:43.100 [INF] CHDB: Populating new node update index bucket
2018-08-29 01:50:45.345 [INF] CHDB: Populating new edge update index bucket
2018-08-29 01:51:19.532 [INF] CHDB: Migration to node and edge update indexes complete!
2018-08-29 01:51:19.532 [INF] CHDB: Applying migration #2
2018-08-29 01:51:19.613 [INF] CHDB: Migrating invoice database to new time series format
2018-08-29 01:51:19.613 [INF] CHDB: Migration to invoice time series index complete!
2018-08-29 01:51:19.613 [INF] CHDB: Applying migration #3
2018-08-29 01:51:19.613 [INF] CHDB: Migrating invoice database to new outgoing payment format
2018-08-29 01:51:19.613 [INF] CHDB: Migration to outgoing payment invoices complete!
2018-08-29 01:51:19.613 [INF] CHDB: Applying migration #4
2018-08-29 01:51:57.457 [INF] CHDB: Migration of edge policies complete!
2018-08-29 01:51:57.457 [INF] CHDB: Applying migration #5
2018-08-29 01:51:57.458 [INF] CHDB: Migrating database to support payment statuses
2018-08-29 01:51:57.458 [INF] CHDB: Marking all known circuits with status InFlight
2018-08-29 01:51:57.458 [INF] CHDB: Marking all existing payments with status Completed
2018-08-29 01:51:57.458 [INF] CHDB: Migration of payment statuses complete!

One lncli related change that users running on simnet or testnet will notice is that the default location for macaroons has now changed. As a result, lnd will generate a new set of macaroons after it has initially been upgraded. Further details will be found below, but lnd will now generate a distinct set of macaroons for simnet, testnet, and mainnet. As a result, you may need to supply additional arguments for lncli to have it work as normal on testnet like so:

lncli --network=testnet getinfo

or

lncli --chain=litecoin --network=testnet getinfo

In order to cut down on the typing one needs to go through, we recommend creating an alias like so:

alias tlncli=lncli --network=testnet

NOTE: In this release, the --noencryptwallet command line and config argument to lnd has been phased out. It has instead been replaced with an argument identical in functionality, but distinct in naming: --nowalletseed. The rationale for this change is to remove the foot gun that was the prior config value, as many users would unknowingly create mainnet nodes using the argument. This is dangerous, as if done, the user wouldn't receive a recovery mnemonic to recover their on-chain funds in the case of disaster. We've changed the name of the argument to better reflect the underlying semantics.

Verifying the Release

In order to verify the release, you'll need to have gpg or gpg2 installed on your system. Once you've obtained a copy (and hopefully verified that as well), you'll first need to import roasbeef's key if you haven't done so already:

curl https://keybase.io/roasbeef/pgp_keys.asc | gpg --import

The keybase page of roasbeef includes several attestations across distinct platforms in order to provide a degree of confidence that this release was really signed by "roasbeef".

Once you have his PGP key you can verify the release (assuming manifest-v0.5-beta-rc2.txt and manifest-v0.5-beta-rc2.txt.sig are in the current directory) with:

gpg --verify manifest-v0.5-beta-rc2.txt.sig

That will verify the signature on the main manifest page which ensures integrity and authenticity of the binaries you've downloaded locally. Next, depending on your operating system you should then re-calculate the sha256 sum of the binary, and compare that with the following hashes (which are included in the manifest file):

0e7b733346734882f52f635c1d76473f9d2eda045a581c4c42e67d3044f04de6  lnd-darwin-386-v0.5-beta-rc2.tar.gz
73b6cecf56cfd7895890aea2e5dee5ea56e521f6cc65f8cea5482dfe94fd984a  lnd-darwin-amd64-v0.5-beta-rc2.tar.gz
cda6e9399a6b3dc447d2ccaf6679b3affc4220619c9d1aa859fd5a915abc97ce  lnd-dragonfly-amd64-v0.5-beta-rc2.tar.gz
ae4df8a4f871f9bf57498084ed3939eb4f7bf108c573ff85bf50023f655492eb  lnd-freebsd-386-v0.5-beta-rc2.tar.gz
7c21b6db971550bd6fe182d79b79028cf10fa41ddeeb856adb6369fd9d036e95  lnd-freebsd-amd64-v0.5-beta-rc2.tar.gz
b65c1b5bbfce0d2491e9a0a84924b7b975f789142bd4449ef073ca4d49b2db4e  lnd-freebsd-arm-v0.5-beta-rc2.tar.gz
60254c1ce30dc08faa68b87cd29264fc36eb27fad1bc7f6b15d80b1fe176a09d  lnd-linux-386-v0.5-beta-rc2.tar.gz
1ae4bd6a30f0bb4a4077fc40c3782a27ec48dcc41bb96f9faa8f56506f3a4fc3  lnd-linux-amd64-v0.5-beta-rc2.tar.gz
d82eb2ee2cd89d0689ed4582ad9803700f2db0d94449e2c7b239be05a133c899  lnd-linux-arm-v0.5-beta-rc2.tar.gz
4b26f06cc3d9f8a1aefeefb5399ac45ec693a719c0f3a39a42b582213022816a  lnd-linux-arm64-v0.5-beta-rc2.tar.gz
eac9ae87925c5b1bc1b7235a720992aa202a61aed789e8e235d2dd1d525e4ef3  lnd-linux-mips64-v0.5-beta-rc2.tar.gz
d9cdfa8655bf3dd8e32104d635532d71519cf4fb0f6e87a0c3fa590562273087  lnd-linux-mips64le-v0.5-beta-rc2.tar.gz
67a7004777d1a61c078ea2ed097adfa04c9184c6b909f0cefa6bddff14f7f752  lnd-linux-ppc64-v0.5-beta-rc2.tar.gz
c4ac913e6d516375516b8532d354e0cf242a2de5848aa868441a01078923ae5b  lnd-netbsd-386-v0.5-beta-rc2.tar.gz
b4727576bf1f453ef3261bc9fb65bc3b29c8949258818c1463bf21935d867712  lnd-netbsd-amd64-v0.5-beta-rc2.tar.gz
9369d62931dbd6977ad73e92add97960f63bdea97b55fa3d017a42db7b38d520  lnd-openbsd-386-v0.5-beta-rc2.tar.gz
f95a56223eb00ded888c22723cb662d9c827607d7880b01fb65daf565026d428  lnd-openbsd-amd64-v0.5-beta-rc2.tar.gz
15ee42130313fbfe81f5090064a26268bb21e3deba063f895d6e582fe84fd5d4  lnd-windows-386-v0.5-beta-rc2.zip
ad985b635651d59b74628d3f9e9bce7c17643c7326030b286246b6fe5a70d4ed  lnd-windows-amd64-v0.5-beta-rc2.zip

One can use the shasum -a 256 <file name here> tool in order to re-compute the sha256 hash of the target binary for your operating system. The produced hash should be compared with the hashes listed above and they should match exactly.

Finally, you can also verify the tag itself with the following command:

git verify-tag v0.5-beta-rc2

You should see the following if the verification was successful:

gpg: Signature made Wed Sep  5 21:41:45 2018 PDT
gpg:                using RSA key 65317176B6857F98834EDBE8964EA263DD637C21
gpg: Good signature from "Olaoluwa Osuntokun <laolu32@gmail.com>" [ultimate]

After go1.12 is released, we'll be switching to a method in order to allow deterministic builds to allow for third party verifiability of the binaries included in this release.

This release can also be found in roasbeef's public keybase folder.

⚡️⚡️⚡️ OK, now to the rest of the release notes! ⚡️⚡️⚡️

Notable Changes

Switch to Mainline btcsuite Libraries

With this release of lnd, the project no longer uses roasbeef's set of forks for the btcsuite family of libraries such as btcd, and btcutil. The old set of forks will no longer be maintained as all development will now be focused on mainline btcsuite. Additionally, roasbeef is now a maintainer of the btcsuite set of libraries. As a result, we'll be able to easily integrate any new feature or bug fixes we need to btcsuite directly, rather than maintaining our own fork again. As a result, we recommend that those users running lnd with a btcd upgrade to the latest versions of the master branch of btcd.

txindex For Full Node Backends is Now Optional!

Before this release, if a user was running with any of the supported full node backends we required them to run with the transaction index active. With this version of lnd, running a full node backend with a transaction index is now optional! As a result, if a user wishes to run a lighter version of their full node without the transaction index, then they're able to do so. However, for performance reasons until the persistent height hints are re-activated, we recommend running with an active transaction index for your full node which backs lnd. In either case, lnd will automatically detect if the backing full node has an active transaction index and act accordingly.

Future releases of lnd will allow for even lighter full node configuration by supporting pruned nodes as a first class citizen.

Neutrino BIP 157+158 Compliance and Optimizations

This release of lnd contains several bug fixes, and optimizations for the neutrino light client backend. Additionally, our implementation of BIP 157 and BIP 158 are now fully compliant with the latest version of the set of BIPs. The primary change between this version of the BIP 158 and the prior version lies in exactly what the filters contain In a prior version, the regular filter contained: the txid of each transaction found in a block, the previous outpoint that all inputs spend, and finally the pkScript of each created output. The new version instead simply includes: the previous output script that each input references, and each pkScript created by outputs in the block. This modification results in more compact filters as we scripts can be de-duplicated across blocks, and we drop an additional element per transaction. Several core interfaces within lnd have been revamped to listen for spends based on scripts (rather than outpoints) and confirmations based on scripts (rater than txids).

A re-write of the syncing logic for neutrino was undertaken in order to fix a number of stalling and performance related bugs in the prior implementation. At the time of writing of these release notes btcd is the only full node implementation that is able to serve BIP 157 clients. The latest version of the master branch of btcd has also been updated to be fully compliant with both BIP 157 and 158.

The latest version of the neutrino implementation that's packaged with lnd will now cache filters and blocks in memory. In prior versions of the implementation all filters would be written to disk. This is unnecessary, as in the typical case, a filter is only scanned and checked once, therefore it's safe to never write them to disk and instead only maintain a simple in-memory cache with a size based eviction policy. Caching filters (with an option to write select filters to disk) allows us to reduce to reduce the on-disk footprint for the neutrino mode of operation. We'll also now maintain a cache for blocks as during channel validation, it's likely that a block contains several funding transactions. Caching these blocks allows us to cut down on redundant p2p traffic, instead utilizing a pre-deserialized version of a block for validation purposes.

Finally, a number of bugs have been fixed in the primary rescan logic for neutrino which serves as a base abstraction for many components within lnd.

Duplicate Payments

A new ControlTower has been integrated into the switch, which prevents payments exhibiting the reused payment hashes from being in-flight simultaneously, in addition to rejecting further attempts once a payment to a given hash is successful. By comparing the payment hashes directly, this also prevents paying two distinct invoices that include the same payment hash.

Query Graph Sync

With this version of lnd, we now implement the "query graph syncing" feature which has recently been added to the BOLT specifications. With this change, establishing connections to new peers for a fresh node is much lighter. The primary distinction is that when requesting the network view of the node we're connecting to, we'll now longer request they send all the data they have. Instead, treating the blockchain and channels opened within it as a time series, we're able to precisely request only the data we need, eliminating redundant bandwidth usage and processing on both sides.

As a result of this change, the load on routing nodes should generally be much lower, as they'll only request new channels they don't already know of from newly connected peers. We've taken an additional step forward, and now require this feature for nodes that the neutrino mode will connect out to. By doing this, we ensure the node we're connecting to doesn't send any zombie channels, causing us to populate our local network view with stale, likely abandoned channels.

Aggressive Graph Vertex Pruning

In order to maintain a healthy view of the network, lnd currently prunes any channels which haven't sent out a channel update heartbeat in 2 weeks. We call these pruned channels "zombie channels". In this release, [we now go a step further and prune out any nodes which don't have any active channels within the network](#1371. This serves to keep our view of the network tight and lively.

lnd currently keeps a special set of LinkNodes within the database that represent nodes which we have direct channels with. In addition to this unconnected vertex pruning, we now ensure that we won't automatically attempt to connect to a node on start up if we don't have any existing channels to itself. In the past a lack of this feature has caused issues for larger nodes that have historically had a high channel turn over rate.

Async Daemon Start Up

In prior versions of lnd a number of blocking actions such as re-registering for confirmation and spend notifications would slow down the start up time of the deamon as we would wait for things like historical dispatches to finish before moving onto the next sub-system to start up. Additionally, in prior release establishing a new peer connection was done in a synchronous manner, meaning that we would only be able to carry out a single p2p handshake at a time. In the worst case, lnd would take tens of minutes to start up if the node was heavily loaded with channels.

In this new release we've modified all ChainNotifier registrations to be fully async. As a result, we'll no longer block for their historical dispatch checks on startup, and instead can pipeline the start up of all sub-systems within the daemon. On the server side, once we obtain a TCP socket, all other peer negotiation is now done in a distinct goroutine. These two changes should dramatically lower the initial start up time of the daemon for more heavily loaded nodes.

New SendToRoute RPC!

A new routing/payment related RPC has been added to lnd: SendToRoute. The RPC can be seen as a companion RPC to the existing QueryRoutes RPC. One can view this RPC as the Lightning analog to the createrawtransaction RPC typically implemented within Bitcoin full node daemons. The SendToRoute RPC allows a caller to specify a custom route, which includes all details required to dispatch an HTLC such as the fee and time lock information at each hop of the route. The RPC has been fashioned in a way that allows users to either re-use the existing output from the QueryRoutes command, or craft a custom route by hand via a special JSON route format.

There are three ways to specify routes:

  • using the --routes parameter to manually specify a JSON encode set of routes in the format of the return value of queryroutes: lncli sendtoroute --payment_hash=<pay_hash> --routes=<route>

  • passing the routes as a positional argument: lncli sendtoroute --payment_hash=pay_hash <route>

  • or reading in the routes from stdin, which can allow chaining the response from queryroutes, or even read in a file with a set of pre-computed routes: lncli queryroutes --args.. | lncli sendtoroute --payment_hash=H -. Notice the '-' at the end, which signals that lncli should read the route in from stdin

This was one of our most requested RPCs as it allows the caller to execute advanced maneuvers on the Lightning Network such as self-rebalancing channels, making custom protocols which rely on data delivered within the Sphinx per-hop onion blob, and also cross-chain atomic swaps which need to manually specify the a particular HTLC is to be forwarded on a distinct chain from that which it came in on.

Strict Local Forwarding Switch

In order to more precisely support the creation of self channel rebalancing scripts, we've modified the HTLC Switch to implement strict local forwarding. Before this change, when node had multiple channels to another node, and the first hop specified was meant to traverse that nodes links, the system would select the link with the highest available bandwidth. However, it may be the case that a users rebalancing script instead wishes to target a distinct channel. With strict forwarding however, we'll ensure that we take the specified first hop rather than attempt to make a forwarding time decision using our additional information. Notably, we don't do so for remote routes, as there's no guarantee as to which link a node forwarding a remote HTLC will choose as there's no way to enforce a particular action.

Automatic Channel Disable Policy

Within the protocol there exists a mechanism that allows nodes to "disable" a channel, marking it ineligible for carrying routed HTLC payments. Disabling channels that are faulty, inactive, or unable to route for w/e reason allows nodes on the network to have a better view of the "healthy" set of routable channels. The latest version of lnd will now disable channels in two instances:

  1. When we co-op close or force close a channel. This signals to the network that the channel is in the process of being closed on the main chain, and therefore isn't eligible to route HTLCs. By sending out this disable update, we save the network a set of between the point of commitment broadcast, and the transaction being mined into the chain.
  2. If the peer is unreachable for a period of time T. The current default period is 20 miuntes, however this can be set from the command line via the inactivechantimeout option:
      --inactivechantimeout=                                  If a channel has been inactive for the set time, send a ChannelUpdate disabling it. (default: 20m0s)

These two measures should serve to reduce the number of failed routed HTLCs due to UnknownNextPeer errors, and we start to tend towards a network view of nodes with high uptime and availability. This is a small step towards our goal of bootstrapping a network with reliable, highly available nodes.

Reduced Idle CPU Usage

Users operating more heavily-loaded routing nodes should generally perceive lower idle CPU usage time. A number of optimization have been executed which reduce the number of idle goroutines, the number of goroutines per connection/channel, and also the number of high frequency tickers within the codebase.

In 0.4.2, idle links would wake up every 50ms to check if they had any HTLCs to process. This caused wasteful CPU utilization, since we should only need to do so if there are unprocessed HTLCs. To remedy this, a new ticker package was implemented that allows the tickers to be stopped and resumed conditionally, based on the presence or absence of pending HTLCs. With 0.5, the idle CPU usage of active links has been reduced drastically since links will now be truly asleep when not processing HTLCs.

Automatic Tor V2+V3 Onion Services

Prior versions of lnd introduced the ability to establish outbound connections over Tor via the socks proxy interface. This allows users to run routing nodes or clients without revealing the location of their routing nodes. This adds an additional layer of privacy as nodes no longer need to expose their IP address in order to route or send payments within the network. The latest version of lnd takes things a step further and enables automatic provisioning of an onion service to allow a node to accept inbound connections over Tor.

The auto setup works as follows: if --tor.active --tor.v2 is set within the configuration, then lnd will attempt to automatically seek out and authenticate with the Tor daemon running at the specified control port. If we're able to connect out, then we'll create a new onion service identity, and modify lnd to only listen on localhost. In this mode, we also ensure that all DNS queries utilize the SOCKS5 interface for tunneling DNS over Tor. In this version we also support the new v3 onion services (--tor.v3. The new onion service protocol represents a large step for the Tor network as it does away with the existing legacy crypto used within the system, and also strengthens onion services against a number of discovered attacks.

We'll soon be updating our DNS seed to be able to crawl and serve onion service peers. This will allow those that wish to run purely over Tor to easily find peers they can connect to. For further documentation we recommend users check out our official Tor integration docs, as well as the relevant section of the sample-lnd.conf.

Dataloss Protection Recovery

Within the protocol, there exists a measure put in place that will allow nodes that have partially or complete lost data to recover a portion of the funds they had within active channels. We call this feature "dataloss protection". The latest version of lnd has now completely implemented this feature! In the rare case that users exhibit partial data loss, upon connection to a peer which we had a channel open with, lnd will automatically prompt the user to close out the channel as it can no longer be used. At that point, we'll then proceed to sweep out settled balance within the commitment transaction on-chain, and clean up the remaining channel state.

Future versions of lnd, will finalize the ingratiation of this feature by also introducing static channel backups. These backups are essentially static files which represent a description of the channel, namely: the parameters used, location on chain, channel peer, key paths we used within the channel, etc. With this set up backups and a users seed, in the face of total data loss, we'll be able to recover the settled balance in the set of open channels.

Reliability improvements to bitcoind backend

Prior versions of lnd were plagued with reliability issues when interacting with the bitcoind backend. We'd at times miss notifications, or even drop block notification causing is to miss events such as a funding transaction confirming, or a channel being closed. With this new version of lnd we've implemented several measures to ensure that we no longer miss any notifications from bitcoind, and even if we do, then we're able to safely backtrack and recover from any missed block notifications.

Before 0.5, we would receive block and transaction notification via the same zmq socket. As transaction notifications (mempool inclusion) is much more common than block notifications, they would dominate the queued backlog at any given time. In certain conditions, due to the notification backlog, block notifications would be dropped once the queue gets above a high water mark. To avoid possibly missing block notifications, we now split the notification sources into two distinct sockets. This ensures that the less critical transaction notifications are isolated to a distinct queue from the block notifications. Due to this change, users must now specify distinct sockets for block and transaction notifications like so:

lnd --bitcoin.active --bitcoin.testnet --bitcoin.node=bitcoind --bitcoind.zmqpubrawblock=tcp://127.0.0.1:28332 --bitcoind.zmqpubrawblock=tcp://127.0.0.1:28333

HTLC Switch Persistence and Reliability Improvements

Removing links has been reworked to be blocking from the caller’s perspective, offering safer isolation during shutdown and interactions with flapping peers. When shutting down LND, stopping links is now done concurrently, offering faster shutdowns to users with high channel counts.

Prior to the added safety surrounding removal of links, some issues were found that caused users to end up with an invalid, albeit recoverable, database state. 0.5 includes a fix to automatically cleanup any databases that entered this state, which would otherwise prevent startup. The link startup logic has also been altered to ensure we don’t read from this invalid state.

The htlcswitch relies on a series of internal logs, referred to as forwarding packages, for ensuring that HTLCs are retransmitted internally with at-least-once semantics. An issue was fixed in 0.5 where a missing reference on failed packets would prevent the persistent references from being removed, and resulting in unnecessary internal retransmission and processing of the HTLCs on startup and peer reconnection. To correct databases that were not properly cleaning up this state, links will now cleanup any references for packets that are detected as duplicates internally. The combined result of both changes is reduced log spam and startup/reconnection latency.

Processing of locally-sourced HTLC responses has been made asynchronous, so that it does not block the primary forwarding loop within the switch resulting in better performance and database batching. The ordering of database operations has also been reordered to properly cleanup forwarding package references, even if the daemon has been restarted. References that had not been cleaned up prior will be cleaned up after a restart with 0.5.

On channel reestablisment, links will now force close the channel when detecting certain irrecoverable failure cases, such as remote data loss and invalid commitment points.

When sending locally-initiated payments out of the switch, we will now honor the exact channel requested by the channel router. Previously, we allowed the switch to select the best link to the same peer if multiple existed. However, this caused issues when trying to use SendToRoute since the user couldn’t be sure which channel the payment would flow over. This change allows provides a more feedback mechanism to the router, since local failures are now known to have been sourced from the outgoing link.

Link-level fee updates are less aggressive, and now use randomized interval for each link. Prior all links checked for fee updates with each block, which resulted in an unnecessary number of state updates.

Timelocks of forwarded HTLCs are now validated against the outgoing channel policy. Previously, the CLTV was incorrectly compared to the policy of the incoming link, resulting in unnecessary routing failures.

An exit hop will now properly return FailFinalExpiryTooSoon when rejecting an HTLC whose timeout is too close to the current block height. The previous behavior incorrectly returned FailFinalIncorrectCltvExpiry, which should only be used if the timeouts are malformed.

Default Autopilot Improvements

The current autpoilot driving agent has received a number of updates in this new version.

t's now possible to instruct the agent to only create unadvertised channels via the autopilot.private flag. This will be useful for desktop and mobile clients which won't be actively routing payments. When attempting to receive funds over these non-advertised channels, the AddInvoice RPC will now automatically populate the required routing hints which will allow nodes to traverse these non-advertised channels on the "edge" of the graph.

One can now also specify the number of confirmation that outputs need to have before the agent starts to use them as inputs into channels. By specifying 0 confirmations, the agent is able to aggressively pipeline channel openings, resulting in a faster time-to-first-n-channels than prior versions.

Finally, the agent will now first probe nodes to see if they're actually active and online, before marking them as a target directive to be executed. This will result in less failed attempts, as we only try to open a channel with a node that we know will respond to our request.

Distinct Network Macaroons

In prior versions of lnd, a single set of macaroons were used for all possible networks (testnet, simnet, mainnet). This approach was flawed however, due to the fact that if one gave out a (possibly attenuated) macaroon for say testnet, then that same macaroon would be utilized for mainnet. This new version of lnd has now reverted this behavior, in favor of network specific macaroons. With this change, the default location of all macaroons has been modified, and the behavior of lncli change as well. Once users upgrade, a new set of macaroons will be created under the chain data directory for each supported network. For example, one can find the testnet invoice macaroon for Bitcoin at:

~/.lnd/data/chain/bitcoin/testnet/invoice.macaroon

Most other behavior has been left unchanged, however, one must now also specify the target network (and also possibly chain) when using lncli, via the new set of arguments:

   --chain value, -c value    the chain lnd is running on e.g. bitcoin (default: "bitcoin")
   --network value, -n value  the network lnd is running on e.g. mainnet, testnet, etc. (default: "mainnet")

Any scripts or gRPC programs will need to be modified in order to utilize the new set of macaroons, as any other prior created macaroons are now invalidated, as the root macaroon key has been regenerated.

Revamp of HTLC Pathfinding Algorithm

A number of changes have been made to the default HTLC path finding algorithm to fix exiting bugs in our fee calculation, edge weighting, and also fee ceiling enforcement.

The old path finding algorithm would proceed to look for a path to the destination, starting from a given source (lnd). The old algorithm had several issues, namely: we would take into account our first outgoing edge in the edge weighting, we wouldn't properly factor in the carry over backwards in the route as fees were added meaning we wouldn't compute the fee ceiling properly, and finally we would skew the path finding based on our own outbound routing policies. The new path finding code fixes all of these issues, and also revamps our testing infrastructure to make it easy to add new test cases in the future.

Our old weighting function would at times prefer a route with higher fees but an identical timelock, over a shorter route with lower fees and a similar timelock. Rather than try to scale the fees or timelock to be promotional, we instead now normalize the timelock values to essentially act as "extra fees". We borrow the terminology of a "risk factor" from c-lightning. Check out this table from the original PR for a demonstration w.r.t how this improves our path selection given a set of candiate routes.

Finally, the prior path finding code had a bug where it wouldn't properly carry over the fees from the prior hop when traversing backwards to convert a path into a route. This issue would cause unnecessary HTLC routing errors when routing over edges with a particular configuration fee wise. This new release of lnd fixes this bug by ensuring we properly compute and carry over fees which allows us to properly detect the case where a link can carry the initial amount, but once we factor in fees, it can no longer carry the final HTLC.

contractcourt Reliability Improvements

A number of bug fixes and reliability improvements has been made within the contractcourt, the sub-system that lnd uses to handle all on-chain interaction related to contract (such as HTLCs, etc). We now ensure that the handoff of a closed channel to the resolver which will ultimately resolve any pending contract is fully reliable.

Optional NAT Traversal (NAT-PMP + UPnP)

lnd has now gained the ability to optionally attempt NAT traversal so clients that are behind at NAT are able to establish incoming connections from other peers in the network. The current system will try either NAT-PMP or UPnP to punch a hole in the nat, which ever of them works first. If lnd is unable to punch a hole, then it will fail to start in order to inform the users that the networking maneuver was unsuccessful. Additionally, lnd will spawn a background goroutine which will periodically poll the router to see if the external IP has changed, if so, then we'll send out a new announcement on the network so that nodes always reach us at our latest IP address. This feature will be useful for those that cannot obtain static IPs where they run their nodes, and instead have a dynamic IP address which changes every few hours/days.

In order to activate the auto NAT traversal use the following argument:

      --nat                                                   Toggle NAT traversal support (using either UPnP or NAT-PMP) to automatically advertise your external IP address to the network -- NOTE this does not support devices behind multiple NATs

Unix Socket Support for RPC

The primary gRPC server is now able to listen on unix sockets! An example of a valid configuration is:

rpclisten=unix:///var/run/lnd/lnd-rpclistener.sock

Robust Streaming Notification Delivery for Received Payments

In this new version of lnd, we modify the streaming invoice subscription API slightly in order to allow callers to have assurance that they haven't missed any new payments. The SubscribeInvoice API now has two new values: add_index, and settle_index. To match these new values, the Invoice message has also gained a similar set of fields. These two indexes effectively act as an event time series: each time a new invoice is added the add_index will be incremented, and each time a new invoice is settled the settle_index will be incremented. With this new feature, clients can now specify one or both of these new optional fields with the last index they know of. If specified, then we'll query the database to find all events greater than this index, and then deliver these backlog notifications before sending out any new notifications.

Care has been taken to ensure that the new API is backwards compatible with the expectations of the old API. Namely, if the fields aren't specified (are zero), then no backlog notifications will be delivered. As a result, the index on-disk actually starts at 1.

A database migration has been created in order to upgrade old databases to the new invoice schema that has these two new indexes which need to be updated each time a new invoice has been added, or an exiting one settled.

Finally, a new field has been added to the on-disk Invoice struct: AmtPaid. This new field allows the link to commit exactly what value was accepted for the final invoice. This is important as invoices may have not have any value attached to them at all ("donation" invoices), or it may be the case that the invoice was overpaid. In either case, the final value accepted for an invoice will now be stored on disk, and queryable over the RPC interface.

RPC Changes:

The ListInvoices command can now optionally be paginated. This was added as after a certain amount of invoice have been created, we can no longer return them in a single response over gRPC. On the command line, a new set of arguments have been added to control the pagination:

⛰ lncli listinvoices -h
NAME:
   lncli listinvoices - List all invoices currently stored.

USAGE:
   lncli listinvoices [command options] [arguments...]

CATEGORY:
   Payments

OPTIONS:
   --pending_only        toggles if all invoices should be returned, or only those that are currently unsettled
   --index_offset value  the number of invoices to skip (default: 0)
   --max_invoices value  the max number of invoices to return (default: 0)

A new ClosedChannels RPC has been added which will allow users to query for their historical closed channel state. The new command allows users to query for a particular close type as well:

⛰i  lncli closedchannels -h
NAME:
   lncli closedchannels - List all closed channels.

USAGE:
   lncli closedchannels [command options] [arguments...]

CATEGORY:
   Channels

OPTIONS:
   --cooperative       list channels that were closed cooperatively
   --local_force       list channels that were force-closed by the local node
   --remote_force      list channels that were force-closed by the remote node
   --breach            list channels for which the remote node attempted to broadcast a prior revoked channel state
   --funding_canceled  list channels that were never fully opened

On-Chain Fee Management

On-chain fee management within lnd has been revamped in order to fix a number of errors related to fees being too low, and rounding errors that can occur when converting between vsize and weight. With these changes, we now use the kilo-weight unit everywhere internally, and now also ensure that we never dip below the widely used min relay fee on the network. In the past there were many issues related to funds not being swept from contracts due to sweeping transaction not propagating during times when fees on mainnet and testnet where very low.

Changelog

The full list of changes since 0.4.2-beta can be found here:

Contributors (Alphabetical Order)

  • 34ro
  • Ben Woosley
  • Brenden Matthews
  • Conner Fromknecht
  • Dan Bolser
  • Johan T. Halseth
  • John Griffith
  • jonny1000
  • Joost Jager
  • Lightning Koala
  • hackerrdave
  • Matthew Lilley
  • maurycy
  • Offer Markovich
  • Olaoluwa Osuntokun
  • Oliver Gugger
  • parth
  • Phil Opaola
  • rawtxapp
  • Rudy Godoy
  • Rui Gomes
  • Sebastian Delgado
  • shtirlic
  • Stefan Menzel
  • Suriyaa ✌️
  • t4sk
  • Vadym Popov
  • Valentine Wallace
  • Vegard Engen
  • Wilmer Paulino
  • Xinxi Wang
  • Yaacov Akiba Slama
  • Yohei Okada
Assets 23