lnd v0.2-alpha

lnd-v0.2-alpha marks the latest minor (but in a sense major) release of lnd! This release represents a substantial step forward in the stability, feature set, BOLT specification compliance, performance, reliability and maturity of lnd and also Lightning as a whole.

As the lead maintainer of the lnd software, I would like to express my gratitude to the extremely dedicated community of software testers and application developers that have started to emerge around lnd. Your swift bug reports, constant experimentation, and passion for the system you're helping to create have significantly accelerated the development progress of lnd, and for that I deeply thank you. In no particular order, I would like to recognize the efforts of (also bare in mind this isn't an exhaustive list):

• moli
• juscamarena
• takinbo
• mably
• weedcoder
• dts

NOTE: It is important to note that this release of lnd contains several breaking changes. As a result, users will either need to upgrade using a completely fresh installation, or remove their existing channel.db database file before upgrading. As a courtesy, we recommend that users close out their prior channels (either cooperatively if the peer is online, or unilaterally (force close) otherwise) before upgrading.

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

Notable Changes

Sphinx Packet Shared Secret Derivation Change

The method we use to generate the shared secret which is used to derive several keys used in the generation and processing of our Sphinx packets used in multi-hop routing has been modified. Previously we directly used the btcec.GenerateSharedSecret method which returned the raw bytes of the x-coordinate of the derived shared point. After our last release the BOLT#4 specification was modified to instead utilize the SHA-256 of the entire coordinate serialized in compressed format. Within the specification this derivation method was modified in order to align ourselves with the ECDH method used by libsecp256k1, a widely used and extremely well tested library within the Bitcoin ecosystem.

lncli Support for Positional Arguments

The lncli command line tool has now gained support for positional arguments, keyword arguments, and mixing the two within most command line commands. This change was made in order to minimize the required typing for users on the command lone. For example, commands like:

lncli openchannel --node_key=7a379c554dd680083432648e4416255deaf113d655d002baea62652cd9e5b95f --local_amt=100000000 --push_amt=50000 --num_confs=5

Can now optionally be entered as:

lncli openchannel 7a379c554dd680083432648e4416255deaf113d655d002baea62652cd9e5b95f 100000000 50000 5

Multi-Path Payment Path Finding

In this release of lnd, when attempting to select a candidate path for a payment requests we now utilize a modified version of Yen's algorithm to select a set of candidate paths which themselves each have the necessary capacity to carry a target payment. Within our modified version of Yen's algorithm, rather than removing conflicting edges in the current root path and non-spur node edges from the root path, we instead utilize a black-list of edges and vertexes which are to be ignored within the K_ith iteration. This allows us to avoid loading the entire graph into memory during our repeated graph traversals.

Once we obtain a set of candidate payments paths, we then rank the set of candidate paths according to the cumulative fee-rate, and then cumulative absolute time-lock value. As a result, the dispatch of payments within the daemon is now much more reliable as we're able to serially fall-back to lower ranked paths in the case that a payment attempt to the highest ranked path fails.

Additionally, the version of Dijkstra's algorithm we employ (which is used as a subroutine within Yen's) has been modified to: include the capacity of a target edge within the relaxation condition, utilize a binary heap when selecting the next edge to greedily explore and gains white-box knowledge of its role in Yen's algorithm. Finally, we've added an additional layer of caching/memoization of the map: {paymentAmt, targetVertex} -> [path_1, path_2, ....path_n]. Such caching serves as a significant optimization as we are able to skip any dis access when querying repeated payment tuple if no new edges have been added to the graph or modified since the last invocation.

Due to the changes above, the queryroute within the lncli tool and the QueryRoute RPC command of the gRPC Lightning service is no more. Instead they've been replaced with queryroutes and QueryRoutes which are identical to their predecessor commands aside from the fact that they now return a list of all eligible candidate paths rather than simply returning the first available path and exiting.

Complete Authenticated Channel Graph Verification

In the prior release(s) of lnd, the daemon didn't fully verify the authenticity of all vertex and edge announcements within the graph. This meant that lnd would gladly accept an invalid or false channel to it's channel graph, or a forged node announcement as a vertex within the graph. With this release, we now both fully validate all edge+vertex announcements seen within the network, and also generate valid channel authentication and node announcement proofs.

These changes eliminate a class of error encountered by our alpha testers wherein an invalid or non-existent channel would be accepted to the channel graph leading to egregious payment routing failures. Furthermore, with this change, lnd is now fully compliant with BOLT#7. Due to this change, the prior channel graph generate and accepted by prior version of lnd has now been invalidated.

BOLT Commitment State Machine Compliance

In the prior releases of lnd we utilized a channel commitment update state machine which pre-dated the one currently specified within the current BOLT drafts. This statement used an "initial revocation window" which was then dynamically adjusted using a TCP sliding window like commitment update procedure with explicit log indexes used in state transitions. In this new release of lnd, we've now restricted the functionality of lnd's state machine in order to comply with the current BOLT drafts. One minor deviation still exists: we use an initial revocation window of 1, as our current funding state machine still requires such as construct.

Independent of the modification of lnd's state machine a number of minor bugs within the state machine itself have been fixed which include: an incorrect reporting of the number of HTLC/s within the htlcSwitch logs, a fix for a HTLC commitment transaction overflow bug which could results in state desynchronization, and an omitted HTLC cancellation error back propagation within the state machine.

Graph Topology Notification Client

With this release of lnd we've added a new serving streaming RPC command. This RPC command, tilted: SubscribeChannelGraph allows callers to receive streaming asynchronous notification whenever the channel graph has been updated from the PoV of the serving lnd node. Within our integration tests usage of this new streaming RPC has allowed us tighten the running time of our integration test and eliminate several lingering flakes. Outside of our integration tests the addition of this new streaming RPC call opens up the door for client side applications to dynamically render the known channel graph in real-time.

The added gRPC stub service and new proto definitions follow:

rpc SubscribeChannelGraph(GraphTopologySubscription) returns (stream GraphTopologyUpdate);
message GraphTopologySubscription {}
message GraphTopologyUpdate {
    repeated NodeUpdate node_updates = 1; 
    repeated ChannelEdgeUpdate channel_updates = 2;
    repeated ClosedChannelUpdate closed_chans = 3;
}
message NodeUpdate {
    repeated string addresses = 1;
    string identity_key = 2;
    bytes global_features = 3;
    string alias = 4;
}
message ChannelEdgeUpdate {
    uint64 chan_id = 1;
    ChannelPoint chan_point = 2;
    int64 capacity = 3;
    RoutingPolicy routing_policy  = 4;
    string advertising_node  = 5;
    string connecting_node = 6;
}
message ClosedChannelUpdate {
    uint64 chan_id = 1;
    int64 capacity = 2;
    uint32 closed_height = 3;
    ChannelPoint chan_point = 4;
}

--externalip observance by NodeAnnouncement

In the prior releases of lnd, the externalip command-line/configuration parameter was present, yet unobserved and unused. With this new release of lnd, users that wish to advertise their willingness to accept inbound connection to establish channels from participants on the network should set their --externalip parameter to their publicly reachable IP address. Along with a set of global features, if set, this value will now be advertised to the network.

A future minor release of lnd will utilize this new reachability information to optionally automatically bootstrap a persistent channel balance by automatically maintaining a set of channels with peers selected via various heuristics.

Near Uniform Usage of Satoshis within the RPC Interface

In prior releases of lnd, we mixed the usage of BTC and Satoshis within he RPC interface, both when accepting input and displaying results to the user. In order...

lnd v0.1.1-alpha

This release marks the first minor point release after the initial release of lnd v0.1-alpha.

This release contains a number of bug fixes reported by testers exercising the prior release on testnet which were reported on IRC (#lnd on freenode), and also encountered via various interactions with the current proto Lightning Network developing on test. Some RPC's have had their responses augmented with additional data, but no new breaking change have been introduced in this release. Thanks to everyone that has been experimenting with lnd so far! Your feedback has been very valuable.

Notable Changes

Partial Channel Advertisement

Before this release, there was an implicit assumption in the daemon that both directed edges of a channel would always be advertised within the network. This assumption is false as whether or not to advertise the directed edge of the channel they control is a matter of node policy. This assumption led to a series of bugs when only one half of a ChannelUpdateAnnouncement was propagated through the network.

This release now properly supports partial channel advertisement by properly handling the non-existence of a directed of a channel with the ChannelGraph, ChannelRouter, and rpcSever.

Minimum Channel Size

Currently within the daemon, due to hardcoded fees in certain areas, the minimum channel size is 6000 SAT. Before this release creation of a channel funded with less than 6000 SAT would be allowed, but then the node would find that they were unable to close the channel due to the attempted creation of a negative valued output.

Full dynamic fee calculation and usage is planned for lnd, but until then, we now enforce a soft-limit on the minimum channel size that the daemon will created. To reiterate, this a temporary change and will be lifted in a future release.

Full Docker Configuration for Testnet

With this release, we now include a full docker configuration set up that will make it much easier to set up lnd. Within the new README for the docker package, we now outline two workflows for using the new configuration.

The first workflow walks the user through setting up a test Lightning Network cluster on their local machine using simnet. This set up can be useful to debug new features one is attempting to add to lnd or just to experiment with the capabilities of the daemon on a private network constrained to your local machine. Think of it sort of as a lightning-network-in-a-box.

The second workflow targets Bitcoin's current testnet and cleanly packages up both lnd and btcd allowing users to deploy both and join the network with just a few docker related commands. This container set up has been fashioned such that one doesn't even need Go or any other dependancies installed on their local machine before booting up lnd. The docker configuration will handle all the ncessary set up within the created containers.

RPC Interface Modifications:

Two new RPC commands have been added to lnd.

The first is the debuglevel command. This command lets uses modify the verbosity level of lnd's logs via the command line interface, or directly using gRPC. The RPC can either target a caorse grained, daemon wide logging level:

lncli debuglevel --level=debug

Or instead target a set of specific sub-systems with a more fine-grained level-spec target:

lncli debuglevel --level=PEER=trace

The second new RPC packaged as a part of this release is the decodepayreq command. This command allows users to decode an encoded payment request in order to obtain the exact conditions of the encoded payment request.

Example usage:

▶ lncli decodepayreq --pay_req=yep3c3bqqe43f5ombfca89t4r5rmenhjr4me5n5ind1t3fbj4tmn3jpyi4peh53jaoy7em4xoaxfcg7o7ircwcfb3dwz9najwfuhe5mbyyyyyyyyyyb6tg9yuk1y
{
    "destination": "021b96642e723592ee0b095983fe3a26c8b40b8926968d8b7510e51c9429d4562c",
    "payment_hash": "a5a0ae9a8e6f29c401d42f4f861e561bb0ed48ca30a1c8e97f8b09a167c46d61",
    "num_satoshis": 1000
}%

The final RPC interface modification concerts the sendpayment RPC command. The RPC command now returns the full route the payment took within the network to arrive at the target destination. This slight change gives users a greater degree of visibility into the network, detailing the fees and total time-lock required for the route.

Example usage:

github.com/lightningnetwork/lnd  master ✗                                                                                                                                                                      4d ◒
▶ lncli sendpayment --pay_req=yep3c3bqqe43f5ombfca89t4r5rmenhjr4me5n5ind1t3fbj4tmn3jpyi4peh53jaoy7em4xoaxfcg7o7ircwcfb3dwz9najwfuhe5mbyyyyyyyyyyb6tg9yuk1y
{
    "payment_route": {
        "total_time_lock": 2,
        "total_amt": 1000,
        "hops": [
            {
                "chan_id": 1191986053231738880,
                "chan_capacity": 100000000,
                "amt_to_forward": 1000
            },
            {
                "chan_id": 1190997592276926465,
                "chan_capacity": 100000000,
                "amt_to_forward": 1000
            }
        ]
    }
}%

0.1.1-alpha Change Log

Docs

• 1e8a801 -- docs: update INSTALL.md with new btcd commit hash, correct instructions

Database

• 5c41167 -- channeldb: return correct error when unable to find node
• 7a36fb4 -- channeldb: fix assumption that both channel edges will always be advertised
• 0c7fcb1 -- routing: fix nil pointer panic when node has no outgoing channels
• 7312565 -- routing: allow full syncing graph state with partially advertised edges
• e7631c9 -- rpcserver: ensure graph RPC's work with partially advertised channels

Wire Protocol

• d884efe -- lnwire+lnd: Make Logging Messages Great Again
• f82d957 -- lnwire+peer: introduce new error for unknown message type for forward compat

RPC

• 6a67d48 -- lnrpc: add CloseChannel to README description of RPC calls
• d79530e -- lnrpc: add encoded payment requests to the ListInvoices response
• 0bfdcde -- rpcserver: include encoded payment requesting ListInvoices response
• 9b4ac77 -- rpcserver: allow channels to be opened using --node_id
• 6beaa7f -- lnrpc: add DebugLevel command
• 012480b -- rpcsever: implement DebugLevel command
• ee96052 -- cmd/lncli: add parsing+dispatch for the debuglevel command
• 765d9fd -- lnrpc: return route taken in SendPayment response
• 7d6d818 -- rpcserver: return full path payments go over in SendPayment
• fb523ff -- rpcserver: add a min channel size for funding requests
• 440cf6f -- rpcserver: properly limit min channel size
• faae0b3 -- lnrpc: add new RPC to decode payment requests
• 9662887 -- rpcserver+cmd/lncli: implement DecodePayReq

Lightning Payments

• 99c1ef6 -- lnd: add additional logging statement on payment recv

Typos

• 9588861 -- multi: minor fixes for README's
• #99 51d53ea -- test: fix typos
• #101 40c7bac -- multi: fix a variety of typos throughout the repo

ChainNotifier

• cc4617c -- chainntnfs: break out of loop once txIndex is found

On-Chain Channel Events

• 8990de4 -- breacharbiter: ensure failure to retrieve channels triggers start-up error
• 1cbdf64 -- utxonursery: ensure we don't attempt to create negative value'd outputs

Configuration

• d7a050b -- config: remove deprecated configuration parameters

README

• #100 a13ac90 -- multi: add link to LICENSE in README license badges
• #99 299217a -- README: reformat and add IRC badge

Docker

• #99 a421069 -- docker: add send payment alice->bob workflow for newcomers
• a070d41 -- docker: add example output to commands in workflow
• be66e03 -- docker: general improvements
• 67b300f -- docker: make blockchain persistant
• 0948bc3 -- docker: add BITCOIN_NETWORK param
• 0325b0c -- docker: add 'Connect to faucet lightning node' section in readme
• 49df1b0 -- docker: make 'lnd' dockerfile download project from github rather than mount it localy

Build

• e057684 -- travis: update build to go1.7.4
• ff74d83 -- build: add release script
• c40cb49 -- build: update glide.lock to latest commit hashes
• 6405b1c -- glide: pin sphinx package dependency at the commit level

Integration Tests

• dc28052...

lnd v0.1-alpha

lnd - Lightning Network Daemon v0.1-alpha

This release marks the first pre-release for lnd, the Lightning Network Daemon. With this release, lnd implements a complete Lightning node capable of: opening channels with peers, closing channels, completely handling all cooperative and non-cooperative channel states, maintaining a fully authenticated+validated channel graph, performing path finding within the network, passively forwarding incoming payments, and sending outgoing onion-encrypted payments through the network.

Lightning Network Specification Compliance

Witth this release, lnd doesn't yet fully conform to the Lightning Network specification
(BOLT's). BOLT stands for:
Basic of Lightning Technologies. The specifications are currently being drafted
by several groups of implementers based around the world including the
developers of lnd. The set of specification documents as well as our
implementation of the specification are still a work-in-progress. With that
said, lnd the current status of lnd's BOLT compliance is:

• BOLT 1: Base Protocol
  • lnd currently utilizes a distinct wire format which was created before
    the emgergence of the current draft of BOLT specifications. We don't
    have an init message, but we do have analogues to all the other
    defined message types.
• BOLT 2: Peer Protocol for Channel Management
  • lnd implements all the functionality defined within the document,
    however we currently use a different set of wire messages. Additionally,
    lnd uses a distinct commitment update state-machine and doesn't yet
    support dynamically updating commitment fees.
• BOLT 3: Bitcoin Transaction and Script Formats
  • lnd currently uses a commitment design from a prior iteration of the
    protocol. Revocation secret generation is handled by elkrem and our
    scripts are slightly different.
• BOLT 4: Onion Routing Protocol
• BOLT 5: Recommendations for On-chain Transaction Handling
• BOLT 7: P2P Node and Channel Discovery
• BOLT 8: Encrypted and Authenticated Transport

Contributors (alphabetical order):

• Alex Akselrod
• Aleksei Ostrovskiy
• Andrew Samokhvalov
• Bryan Bishop (kanzure)
• Bryan Vu
• Christopher Jämthagen
• Evgeniy Scherbina
• John Newbery
• Joseph Poon
• Mykola Sakhno
• Olaoluwa Osuntokun (roasbeef)
• Riccardo Casatta
• PaulCapestany
• Slava Zhigulin
• Tadge Dryja