From 4ccdad0d663f794181a368e5f006f34b28cf4df0 Mon Sep 17 00:00:00 2001 From: Olaoluwa Osuntokun Date: Tue, 10 Jan 2017 15:02:30 -0800 Subject: [PATCH] multi: add README's for all sub-packages --- README.md | 5 +- brontide/README.md | 30 ++++++ chainntnfs/README.md | 32 ++++++ channeldb/README.md | 26 +++++ lnrpc/README.md | 89 +++++++++++++++ lnwallet/README.md | 28 +++++ lnwire/README.md | 251 +++---------------------------------------- routing/README.md | 19 ++++ zpay32/README.md | 24 +++++ 9 files changed, 267 insertions(+), 237 deletions(-) create mode 100644 brontide/README.md create mode 100644 chainntnfs/README.md create mode 100644 channeldb/README.md create mode 100644 lnrpc/README.md create mode 100644 lnwallet/README.md create mode 100644 routing/README.md create mode 100644 zpay32/README.md diff --git a/README.md b/README.md index 45b8e8f5..cc5db2dd 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,8 @@ # `lnd` - the Lightning Network Daemon -[![Build Status](https://travis-ci.org/lightningnetwork/lnd.svg?branch=master)](https://travis-ci.org/lightningnetwork/lnd) + +[![Build Status](http://img.shields.io/travis/lightningnetwork/lnd.svg)] +(https://travis-ci.org/lightningnetwork/lnd) +[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)] `lnd` is a complete implementation of a node on the [Lightning diff --git a/brontide/README.md b/brontide/README.md new file mode 100644 index 00000000..fc2bb14a --- /dev/null +++ b/brontide/README.md @@ -0,0 +1,30 @@ +brontide +========== + +[![Build Status](http://img.shields.io/travis/lightningnetwork/lnd.svg)] +(https://travis-ci.org/lightningnetwork/lnd) +[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)] +[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)] +(http://godoc.org/github.com/lightningnetwork/lnd/brontide) + +The brontide package implements a secure crypto messaging protocol based off of +the [Noise Protocol Framework](http://noiseprotocol.org/noise.html). The +package exposes the raw state machine that handles the handshake and subsequent +message encryption/decryption scheme. Additionally, the package exposes a +[net.Conn](https://golang.org/pkg/net/#Conn) and a +[net.Listener](https://golang.org/pkg/net/#Listener) interface implementation +which allows the encrypted transport to be seamlessly integrated into a +codebase. + +The secure messaging scheme implemented within this package is described in +detail in [BOLT #8 of the Lightning Network specifications](https://github.com/lightningnetwork/lightning-rfc/blob/master/08-transport.md). + +This package has intentionally been designed so it can be used as a standalone +package for any projects needing secure encrypted+authenticated communications +between network enabled programs. + +## Installation and Updating + +```bash +$ go get -u github.com/lightningnetwork/lnd/brontide +``` diff --git a/chainntnfs/README.md b/chainntnfs/README.md new file mode 100644 index 00000000..5b849316 --- /dev/null +++ b/chainntnfs/README.md @@ -0,0 +1,32 @@ +chainntnfs +========== + +[![Build Status](http://img.shields.io/travis/lightningnetwork/lnd.svg)] +(https://travis-ci.org/lightningnetwork/lnd) +[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)] +[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)] +(http://godoc.org/github.com/lightningnetwork/lnd/chainntnfs) + +The chainntnfs package implements as set of interfaces which allow callers to +receive notifications in response to specific on-chain events. The set of +notifications available include: + + * Notifications for each new block connected to the current best chain. + * Notifications once a `txid` has reached a specified number of + confirmations. + * Notifications once a target outpoint (`txid:index`) has been spent. + +These notifications are used within `lnd` in order to properly handle the +workflows for: channel funding, cooperative channel closures, forced channel +closures, channel contract breaches, sweeping time-locked outputs, and finally +pruning the channel graph. + +This package is intentionally general enough to be applicable outside the +specific use cases within `lnd` outline above. The current sole concrete +implementation of the `ChainNotifier` interface depends on `btcd`. + +## Installation and Updating + +```bash +$ go get -u github.com/lightningnetwork/lnd/chainntnfs +``` diff --git a/channeldb/README.md b/channeldb/README.md new file mode 100644 index 00000000..314da9e9 --- /dev/null +++ b/channeldb/README.md @@ -0,0 +1,26 @@ +channeldb +========== + +[![Build Status](http://img.shields.io/travis/lightningnetwork/lnd.svg)] +(https://travis-ci.org/lightningnetwork/lnd) +[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)] +[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)] +(http://godoc.org/github.com/lightningnetwork/lnd/channeldb) + +The channeldb implements the persistent storage engine for `lnd` and +generically a data storage layer for the required state within the Lightning +Network. The backing storage engine is +[boltdb](https://github.com/boltdb/bolt), an embedded pure-go key-value stored +based off of LMDB. + +The package implements an object-oriented storage model with queries and +mutations flowing through a particular object instance rather than the database +itself. The storage implemented by the objects includes: open channels, past +commitment revocation states, the channel graph which includes authenticated +node and channel announcements, outgoing payments, and invoices + +## Installation and Updating + +```bash +$ go get -u github.com/lightningnetwork/lnd/channeldb +``` diff --git a/lnrpc/README.md b/lnrpc/README.md new file mode 100644 index 00000000..0b42ba8c --- /dev/null +++ b/lnrpc/README.md @@ -0,0 +1,89 @@ +lnrpc +===== + +[![Build Status](http://img.shields.io/travis/lightningnetwork/lnd.svg)] +(https://travis-ci.org/lightningnetwork/lnd) +[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)] +[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)] +(http://godoc.org/github.com/lightningnetwork/lnd/lnrpc) + +This lnrpc package implements both a client and server for `lnd`s RPC system +which is based off of the high-performance cross-platform +[gRPC](http://www.grpc.io/) RPC framework. By default, only the Go +client+server libraries are compiled within the package. In order to compile +the client side libraries for other supported languages, the `protoc` tool will +need to be used to generate the compiled protos for a specific language. + +The following languages are supported as clients to `lnrpc`: C++, Go, Node.js, +Java, Ruby, Android Java, PHP, Python, C#, Objective-C. + +The list of defined RPC's on the main service are the following (with a brief +description): + + * WalletBalance + * Returns the wallet's current confirmed balance in BTC. + * ChannelBalance + * Returns the daemons' available aggregate channel balance in BTC. + * GetTransactions + * Returns a list of on-chain transactions that pay to or are spends from + `lnd`. + * SendCoins + * Sends an amount of satoshis to a specific addresses. + * SubscribeTransactions + * Returns a stream which sends async notifications each time a transaction + is created or one is received that pays to us. + * SendMany + * Allows the caller to create a transaction with an arbitrary fan-out + (many outputs). + * NewAddress + * Returns a new addresses, the following address types are supported: + pay-to-public-key-hash (p2pkh), pay-to-witness-key-hash (p2wkh), and + nested-pay-to-witness-key-hash (np2wkh). + * ConnectPeer + * Connects to a peer identified by a public key and host. + * ListPeers + * Lists all available connected peers. + * GetInfo + * Returns basic data concerning the daemon. + * PendingChannels + * List the number of pending (not fully confirmed) channels. + * ListChannels + * List all active channels the daemon manages. + * OpenChannel + * Attempts to open a channel to a target peer with a specific amount and + push amount. + * SendPayment + * Send a payment over Lightning to a target peer. + * AddInvoice + * Adds an invoice to the daemon. Invoices are automatically settled once + seen as an incoming HTLC. + * ListInvoices + * Lists all stored invoices. + * LookupInvoice + * Attempts to look up an invoice by payment hash (r-hash). + * SubscribeInvoices + * Creates a uni-directional stream which receives async notifications as + the daemon settles invoices + * ListPayments + * List all outgoing Lightning payments the daemon has made. + * DescribeGraph + * Returns a description of the known channel graph from the PoV of the + node. + * GetChanInfo + * Returns information for a specific channel identified by channel ID. + * GetNodeInfo + * Returns information for a particular node identified by its identity + public key. + * QueryRoute + * Queries for a possible route to a target peer which can carry a certain + amount of payment. + * GetNetworkInfo + * Returns some network level statistics. + * SetAlias + * Sets the node alias whchi is to be advertised on the network. + +## Installation and Updating + +```bash +$ go get -u github.com/lightningnetwork/lnd/lnrpc +``` diff --git a/lnwallet/README.md b/lnwallet/README.md new file mode 100644 index 00000000..9aecd4ec --- /dev/null +++ b/lnwallet/README.md @@ -0,0 +1,28 @@ +lnwallet +========= + +[![Build Status](http://img.shields.io/travis/lightningnetwork/lnd.svg)] +(https://travis-ci.org/lightningnetwork/lnd) +[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)] +[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)] +(http://godoc.org/github.com/lightningnetwork/lnd/lnwallet) + +The lnwallet package implements an abstracted wallet controller that is able to +drive channel funding workflows, a number of script utilities, witness +generation functions for the various Lightning scripts, revocation key +derivation, and the commitment update state machine. + +The package is used within `lnd` as the core wallet of the daemon. The wallet +itself is composed of several distinct interface that decouple the +implementation of things like signing and blockchain access. This separation +allows new `WalletController` implementations to be be easily dropped into +`lnd` without disrupting the code base. A series of integration tests at the +interface level are also in place to ensure conformance of the implementation +with the interface. + + +## Installation and Updating + +```bash +$ go get -u github.com/lightningnetwork/lnd/lnwallet +``` diff --git a/lnwire/README.md b/lnwire/README.md index b7964f50..3e8feb5e 100644 --- a/lnwire/README.md +++ b/lnwire/README.md @@ -1,241 +1,20 @@ -# Funding (segwit+CSV) +lnwire +====== -This is two-party funder for a single Funding Transaction (more efficient and -makes the channel creation atomic, but doesn't work for -CSV-no-malleability-fix). +[![Build Status](http://img.shields.io/travis/lightningnetwork/lnd.svg)] +(https://travis-ci.org/lightningnetwork/lnd) +[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)] +[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)] +(http://godoc.org/github.com/lightningnetwork/lnd/lnwire) -### Funding Request +The lnwire package implements the Lightning Network wire protocol. -Someone wants to open a channel. The requester provides any inputs and relevant -information on how much they want to fund and the parameters, these paramters -are a proposal. +This package has intentionally been designed so it can be used as a standalone +package for any projects needing to interface with lighting peers at the wire +protocol level. -### Funding Response +## Installation and Updating -If the responder accepts the request, they also provide any inputs, and returns -with parameters as well. These parameters are now considered "Committed" and the -negotation has finished. If the requester doesn't agree with the new conditions, -they stop. The response also contains the first Commitment pubkey provided by the -responder, which refunds the initial balance back to both parties. - -### Funding SignAccept - -The requester now has sufficient information to get a refund if the transaction -is ever broadcast. The requester signs the Funding Transaction and this message -gives the signature to the responder. The requester also provides the signature -for the initial Commitment Transaction. - -### Funding SignComplete - -The responder has sufficient information to broadcast the Funding Transaction -(with the ability to receive a refund), the responder broadcasts on the -blockchain and returns the txid to the requester, with the signature of the -Funding Transaction. This is provided as a courtesy, it cannot be relied upon -with non-cooperative channel counterparties and the Funding Transaction can be -braodcast without this message being received by the requester. After the -necessary number of confirmations, Lightning Network transactions can proceed. - - -# Cooperative Channel Close - -This is when either party want to close out a channel with the current balance. -Requires the cooperation of both parites for this type. In the event of -non-cooperation, either party may broadcast the most recent Commitment -Transaction. - -### Close Request - -One party unilaterally sends their sig and fee amount to the other party. No -further channel updates are possible. In the future, we might include HTLCs in -the outputs, but for now, we're assuming *all* HTLCs are cleared out. - -### Close Complete - -Returns the Txid and sig as a courtesy. The counterparty might not send this if -they're being non-cooperative. - - -# Commitments and HTLCs - -This is designed to be non-blocking where there can be multiple Commitments per -person and the Commitments do not need to match. A HTLC is only believed to be -added when it's in both parties' most recent Commitment (same with -timeout/settle) and all prior Commitments not reflecting the change are revoked -by the counterparty. - -As a result, there can easily be hundreds of state updates/payments per second -per channel. - -### Commitment States - -Commitments: - -1. HTLCs, can be modified. Any add/settlement/timeout/etc. gets added to - staging. -2. Signed, more than one signed state at a time may exist per party. Takes - HTLCs staging and locks it in, can now be broadcast on-chain by the - counterparty. -3. Completed and Revoked, other party sends their revocation accepting this - Commitment. Sending a revocation means you *ACCEPT* the Commitment. There - should never be a case where a Commitment Signature happens and the client - refusees to revoke -- instead the client should immediately close out the - channel. -4. Deprecated, a commitment is old, marked as deprecated when there is a new - Commitment and this one is revoked. These commitments never be broadcasted. -5. Invalid, close out channel immediately. - -There can be multiple commitments going at a time per party (currently limits a -total of 16 possible in-flight that can be broadcast for sanity, but there's no -real limit). - -For validity, all you do is ensure that the changes from the old commitment are -legit (based on your HTLC/staging data) -COMMIT\_STAGING -COMMIT\_SIGNED -COMMIT\_COMPLETE - -Messages: -CommitSignature: Signature to establish COMMIT\_SIGNED state -CommitRevocation: Revoke prior states - -### ADD HTLCs - -Requester Add HTLC states (Adding HTLCs): - -1. Pre-staged, don't know if the other person wants it -2. Staged, both parties agree to add this HTLC. If a staging request packet is - received, then BOTH PARTIES will have it in their next Commitment. Nothing - is guaranteed here, but violations are treated as immediate channel closure. -3. Signed and sent the Commitment Tx to the counterparty, one should now assume - that there's a possibility that this HTLC will be boradcast on-chain. -4. Completed and Revoked, *counterparty* has included this in the Commitment - they're broadcasting and revoked their prior state. This means the - *Requeseter* can continue to take action, since the Commitment they have, - the HTLC doesn't exist (no payment), and the *Responder* will broadcast with - the payment to the *Responder*. However, the *Responder* cannot treat the - HTLC as cleared. -5. Cleared. Both parties have signed and revoked. Responder can continue - routing. Make sure it's included in *BOTH COMMITMENTS and ALL PREVIOUS - REVOKED* -6. Staging Reject, removal request, tx rejected, begin flow to reject HTLC from - other channels, can only be sent during the *pre-staging* state - -In the event that an HTLC stays in "Completed and Revoked" and it is timed out, -and the counterparty refuses to add it into a new Commitment, the channel is -*closed out on-chain*. In other words, when checking which ones to send a -settle/timeout notification, do it for anything which is -ADD\_SIGNING\_AND\_REVOKING, *or* ADD\_COMPLETE (AND ALL OTHER PRE-COMPLETE -STAGES, e.g. in timeout or settlement). - -As part of moving to any further stage, check if it's timed out. - -If there is a request to stage and it's already staged, treat it as accepting. - -When it has cleared and timed out, a timeout notification is sent. - -HTLC ID numbers are uint64 and each counterparty is responsible to only make -sequential/incremental, and each party can only make evens/odds (odd channel -creation responder, evens channel creation initiator) - -State is for *YOUR* signatures (what kind of action you need to do in the future) -ADD\_PRESTAGE -ADD\_STAGED -ADD\_SIGNING\_AND\_REVOKING -ADD\_COMPLETE -ADD\_REJECTED - -Messages: -HTLCAddRequest: Request to add to staging -HTLCAddAccept: Add to staging (both parties have added when recv) -HTLCAddReject: Deny add to staging (both parties don't have in staging) - -### HTLC Settle (payment success) - -Requester Settle HTLC states (Fulfill HTLCs): - -1. Pre-staged, don't know if the other person will agree to settle -2. Staged, both parties agree to settle this HTLC -3. Signed and sent Commitment Tx to the counterparty, there is now the - possibility that the HTLC does not exist on-chain (of course, the Commitment - includes the payment so there's no real loss of funds). In the event that it - does not complete past this step, then one *must* close out on-chain as if - it was never staged/signed in the first place and the counterparty went - offline. -4. Both parties have signed and revoked, the settlement is complete (there is - no intermediate step of Revoked because this is only reliable and actionable - if BOTH PARTIES have updated their settlement state). - -This has one less state because when adding, you're encumbering yourself. With -removing, both parties are potentially encumbered, so they cannot take action -until it's fully settled. - -State is for *your* signatures -SETTLE\_PRESTAGE -SETTLE\_STAGED -SETTLE\_SIGNING\_AND\_REVOKING -SETTLE\_COMPLETE - -Message: -HTLCSettleRequest: Request to add to staging the removal from Commitment. -HTLCSettleAccept: Add to staging the removal from Commitment. -(There is no HTLCSettleReject as the counterparty should immediately close out -or at worst ignore if it's getting garbage requests) - -### Timeout (falure/refund) - -Requester Timeout HTLC States: - -1. Pre-staged -2. Staged, both parties agree to time out the HTLC and refund the money -3. Signe dnad sent commitment to the counterparty, there is now the possibility - that the transaction will no longer exist on-chain (of course, they can be - redeemed either way). In the even that it does not complete past this step, - then one *must* close out on-chain as if it was never staged/signed in the - first place adn the counterparty was offline. -4. Both parties have signed and revoked, the settlement is complete (there is no - intermediate step of Revoked because there is only reliable and actionable if - BOTH PARTIES have updated their settlement state). - -Similar to HTLC Settlement, there is one less state. - -State is for *your* signatures -TIMEOUT\_PRESTAGE -TIMEOUT\_STAGED -TIMEOUT\_SIGNING\_AND\_REVOKING -TIMEOUT\_COMPLETE - - -### Example (this section to be removed) - -A bit redundant, but this was written first... will merge with "Add" example - -Adding a single HTLC process: - -1. Requester flags as pre-staged, and sends an "add requeset" -2. Responder decides whether to add. If they don't, they invalidate it. If they - do, they send a message accepting the staging request. It is now marked as - staged on both sides and is ready to be accepted into a Commitment. -3. When a party wants to update with a new Commitment, they send a new signed - Commitment, this includes data that the HTLC is part of it. Let's say it's - the Requester that sends this new Commitment. As a result, the HTLC is - marked *BY THE RESPONDER* as Signed. It's only when the Responder includes a - transaction including the new HTLC in a new Commitment that the Requester - marks it as Signed. -4. Upon the Responder receiving the new Commitment, they send the revocation - for the old Commitment, and commit to broadcasting only the new one. -5. The *Requester* marks the HTLC as complete, but the *Responder* waits until - they receive a Commitment (and the old one is revoked) before marking it as - complete on the Responder's end. -6. When both parties have the new Commitments and the old ones are revoked, - then the HTLC is marked as complete - -The two Commitment Transactions may not be completely in sync, but that's OK! -What's added in both (and removed in both) are regarded as valid and locked-in. -If it's only added to one, then it's regarded as in-transit and can go either -way. - -The behavior is to sign after all additions/removals/cancellations, but there -may be multiple in the staging buffer. - -Each party has their own revocation height (*for the other party to use*), and -they may be different. +```bash +$ go get -u github.com/lightningnetwork/lnd/lnwire +``` diff --git a/routing/README.md b/routing/README.md new file mode 100644 index 00000000..c4c12c73 --- /dev/null +++ b/routing/README.md @@ -0,0 +1,19 @@ +routing +======= + +[![Build Status](http://img.shields.io/travis/lightningnetwork/lnd.svg)] +(https://travis-ci.org/lightningnetwork/lnd) +[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)] +[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)] +(http://godoc.org/github.com/lightningnetwork/lnd/routing) + +The routing package implements authentication+validation of channel +announcements, pruning of the channel graph, path finding within the network, +sending outgoing payments into the network and synchronizing new peers to our +channel graph state. + +## Installation and Updating + +```bash +$ go get -u github.com/lightningnetwork/lnd/routing +``` diff --git a/zpay32/README.md b/zpay32/README.md new file mode 100644 index 00000000..39aa7d22 --- /dev/null +++ b/zpay32/README.md @@ -0,0 +1,24 @@ +zpay32 +======= + +[![Build Status](http://img.shields.io/travis/lightningnetwork/lnd.svg)] +(https://travis-ci.org/lightningnetwork/lnd) +[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)] +[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)] +(http://godoc.org/github.com/lightningnetwork/lnd/zpay32) + +The zpay32 package implements a basic scheme for the encoding of payment +requests between two `lnd` nodes within the Lightning Network. The zpay32 +encoding scheme uses the +[zbase32](https://philzimmermann.com/docs/human-oriented-base-32-encoding.txt) +scheme along with a checksum to encode a serialized payment request. + +The payment request serialized by the package consist of: the destination's +public key, the payment hash to use for the payment, and the value of payment +to send. + +## Installation and Updating + +```bash +$ go get -u github.com/lightningnetwork/lnd/zpay32 +```