multi: add README's for all sub-packages
This commit is contained in:
Olaoluwa Osuntokun
parent
e37b848f36
commit
4ccdad0d66
@ -1,5 +1,8 @@
|
||||
# `lnd` - the Lightning Network Daemon
|
||||
[](https://travis-ci.org/lightningnetwork/lnd)
|
||||
|
||||
[]
|
||||
(https://travis-ci.org/lightningnetwork/lnd)
|
||||
[]
|
||||
|
||||
|
||||
`lnd` is a complete implementation of a node on the [Lightning
|
||||
|
||||
30
brontide/README.md
Normal file
30
brontide/README.md
Normal file
@ -0,0 +1,30 @@
|
||||
brontide
|
||||
==========
|
||||
|
||||
[]
|
||||
(https://travis-ci.org/lightningnetwork/lnd)
|
||||
[]
|
||||
[]
|
||||
(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
|
||||
```
|
||||
32
chainntnfs/README.md
Normal file
32
chainntnfs/README.md
Normal file
@ -0,0 +1,32 @@
|
||||
chainntnfs
|
||||
==========
|
||||
|
||||
[]
|
||||
(https://travis-ci.org/lightningnetwork/lnd)
|
||||
[]
|
||||
[]
|
||||
(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
|
||||
```
|
||||
26
channeldb/README.md
Normal file
26
channeldb/README.md
Normal file
@ -0,0 +1,26 @@
|
||||
channeldb
|
||||
==========
|
||||
|
||||
[]
|
||||
(https://travis-ci.org/lightningnetwork/lnd)
|
||||
[]
|
||||
[]
|
||||
(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
|
||||
```
|
||||
89
lnrpc/README.md
Normal file
89
lnrpc/README.md
Normal file
@ -0,0 +1,89 @@
|
||||
lnrpc
|
||||
=====
|
||||
|
||||
[]
|
||||
(https://travis-ci.org/lightningnetwork/lnd)
|
||||
[]
|
||||
[]
|
||||
(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
|
||||
```
|
||||
28
lnwallet/README.md
Normal file
28
lnwallet/README.md
Normal file
@ -0,0 +1,28 @@
|
||||
lnwallet
|
||||
=========
|
||||
|
||||
[]
|
||||
(https://travis-ci.org/lightningnetwork/lnd)
|
||||
[]
|
||||
[]
|
||||
(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
|
||||
```
|
||||
251
lnwire/README.md
251
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).
|
||||
[]
|
||||
(https://travis-ci.org/lightningnetwork/lnd)
|
||||
[]
|
||||
[]
|
||||
(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
|
||||
```
|
||||
|
||||
19
routing/README.md
Normal file
19
routing/README.md
Normal file
@ -0,0 +1,19 @@
|
||||
routing
|
||||
=======
|
||||
|
||||
[]
|
||||
(https://travis-ci.org/lightningnetwork/lnd)
|
||||
[]
|
||||
[]
|
||||
(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
|
||||
```
|
||||
24
zpay32/README.md
Normal file
24
zpay32/README.md
Normal file
@ -0,0 +1,24 @@
|
||||
zpay32
|
||||
=======
|
||||
|
||||
[]
|
||||
(https://travis-ci.org/lightningnetwork/lnd)
|
||||
[]
|
||||
[]
|
||||
(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
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user