akovalenko/lnd.xprv
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request #3259 from cfromknecht/watchtower-docs

Browse Source 
docs: watchtower guide + bump default sweep fee rate
This commit is contained in:
Olaoluwa Osuntokun 2019-07-01 17:52:10 -07:00 committed by GitHub
commit 36983214e8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 215 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

162
docs/watchtower.md Normal file
View File

@ -0,0 +1,162 @@
# Private Altruist Watchtowers
As of v0.7.0, `lnd` supports the ability to run a private, altruist watchtower
as a fully-integrated subsystem of `lnd`. Watchtowers act as a second line of
defense in responding to malicious or accidental breach scenarios in the event
that the client’s node is offline or unable to respond at the time of a breach,
offering greater degree of safety to channel funds.
In contrast to a _reward watchtower_ which demand a portion of the channel funds
as a reward for fulfilling its duty, an _altruist watchtower_ returns all of the
victim’s funds (minus on-chain fees) without taking a cut. Reward watchtowers
will be enabled in a subsequent release, though are still undergoing further
testing and refinement.
In addition, `lnd` can now be configured to operate as a _watchtower client_,
backing up encrypted breach-remedy transactions (aka. justice transactions) to
other altruist watchtowers. The watchtower stores fixed-size, encrypted blobs
and is only able to decrypt and publish the justice transaction after the
offending party has broadcast a revoked commitment state. Client communications
with a watchtower are encrypted and authenticated using ephemeral keypairs,
mitigating the amount of tracking the watchtower can perform on its clients
using long-term identifiers.
Note that we have chosen to deploy a restricted set of features in this release
that can begin to provide meaningful security to `lnd` users. Many more
watchtower-related features are nearly complete or have meaningful progress, and
we will continue to ship them as they receive further testing and become safe to
release.
Note: *For now, watchtowers will only backup the `to_local` and `to_remote` outputs
from revoked commitments; backing up HTLC outputs is slated to be deployed in a
future release, as the protocol can be extended to include the extra signature
data in the encrypted blobs.*
## Configuring a Watchtower
To set up a watchtower, command line users should compile in the optional
`watchtowerrpc` subserver, which will offer the ability to interface with the
tower via gRPC or `lncli`. The release binaries will include the `watchtowerrpc`
subserver by default.
The minimal configuration needed to activate the tower is `watchtower.active=1`.
Retrieving information about your tower’s configurations can be done using
`lncli tower info`:
```
🏔 lncli tower info
{
"pubkey": "03281d603b2c5e19b8893a484eb938d7377179a9ef1a6bca4c0bcbbfc291657b63",
"listeners": [
"[::]:9911"
],
"uris": null,
}
```
The entire set of watchtower configuration options can be found using
`lnd -h`:
```
watchtower:
--watchtower.active If the watchtower should be active or not
--watchtower.towerdir= Directory of the watchtower.db (default: $HOME/.lnd/data/watchtower)
--watchtower.listen= Add interfaces/ports to listen for peer connections
--watchtower.externalip= Add interfaces/ports where the watchtower can accept peer connections
--watchtower.readtimeout= Duration the watchtower server will wait for messages to be received before hanging up on client connections
--watchtower.writetimeout= Duration the watchtower server will wait for messages to be written before hanging up on client connections
```
### Listening Interfaces
By default, the watchtower will listen on `:9911` which specifies port `9911`
listening on all available interfaces. Users may configure their own listeners
via the `--watchtower.listen=` option. You can verify your configuration by
checking the `"listeners"` field in `lncli tower info`. If you're having trouble
connecting to your watchtower, ensure that `<port>` is open or your proxy is
properly configured to point to an active listener.
### External IP Addresses
Additionally, users can specify their tower’s external IP address(es) using
`watchtower.externalip=`, which will expose the full tower URIs
(pubkey@host:port) over RPC or `lncli tower info`:
```
...
"uris": [
"03281d603b2c5e19b8893a484eb938d7377179a9ef1a6bca4c0bcbbfc291657b63@1.2.3.4:9911"
]
```
The watchtower's URIs can be given to clients in order to connect and use the
tower by setting the `wtclient.private-tower-uris` option:
```
wtclient.private-tower-uris=03281d603b2c5e19b8893a484eb938d7377179a9ef1a6bca4c0bcbbfc291657b63@1.2.3.4:9911
```
If the watchtower's clients will need remote access, be sure to either:
- Open port 9911 or a port chosen via `watchtower.listen`.
- Use a proxy to direct traffic from an open port to the watchtower's listening
address.
Note: *The watchtower’s public key is distinct from `lnd`’s node public key. For
now this acts as a soft whitelist as it requires clients to know the tower’s
public key in order to use it for backups before more advanced whitelisting
features are implemented. We recommend NOT disclosing this public key openly,
unless you are prepared to open your tower up to the entire Internet.*
### Watchtower Database Directory
The watchtower's database can be moved using the `watchtower.towerdir=`
configuration option. Note that a trailing `/bitcoin/mainnet/watchtower.db`
will be appended to the chosen directory to isolate databases for different
chains, so setting `watchtower.towerdir=/path/to/towerdir` will yield a
watchtower database at `/path/to/towerdir/bitcoin/mainnet/watchtower.db`.
On linux, for example, the default watchtower database will be located at:
```
/$USER/.lnd/data/watchtower/bitcoin/mainnet/watchtower.db
```
## Configuring a Watchtower Client
In order to set up a watchtower client, you’ll need the watchtower URI of an
active watchtower, which will appear like:
```
03281d603b2c5e19b8893a484eb938d7377179a9ef1a6bca4c0bcbbfc291657b63@1.2.3.4:9911
```
The client will automatically be enabled if a URI is configured using
`wtclient.private-tower-uris`:
```
wtclient.private-tower-uris=03281d603b2c5e19b8893a484eb938d7377179a9ef1a6bca4c0bcbbfc291657b63@1.2.3.4:9911
```
At the moment, at most one private watchtower can be configured. If none are
provided, `lnd` will disable the watchtower client.
The entire set of watchtower client configuration options can be found using
`lnd -h`:
```
wtclient:
--wtclient.private-tower-uris= Specifies the URIs of private watchtowers to use in backing up revoked states. URIs must be of the form <pubkey>@<addr>. Only 1 URI is supported at this time, if none are provided the tower will not be enabled.
--wtclient.sweep-fee-rate= Specifies the fee rate in sat/byte to be used when constructing justice transactions sent to the watchtower.
```
### Justice Fee Rates
Users may optionally configure the fee rate of justice transactions by setting
the `wtclient.sweep-fee-rate` option, which accepts values in sat/byte. The
default value is 10 sat/byte, though users may choose to target higher rates to
offer greater priority during fee-spikes. Modifying the `sweep-fee-rate` will be
applied to all new updates after the daemon has been restarted.
### Monitoring
For now, no information regarding the operation of the watchtower client is
exposed over the RPC interface. We are working to expose this information in a
later release, progress on this can be tracked [in this
PR](https://github.com/lightningnetwork/lnd/pull/3184). Users will be reliant on
WTCL logs for observing the behavior of the client. We also plan to expand on
the initial feature set by permitting multiple active towers for redundancy, as
well as modifying the chosen set of towers dynamically without restarting the
daemon.

48
sample-lnd.conf
View File

@ -340,3 +340,51 @@ litecoin.node=ltcd
; This means that multiple applications (other than lnd) using Tor won't be mixed
; in with lnd's traffic.
; tor.streamisolation=1
[watchtower]
; Enable integrated watchtower listening on :9911 by default.
; watchtower.active=1
; Specify the interfaces to listen on for watchtower client connections. One
; listen address per line. If no port is specified the default port of 9911 will
; be added implicitly.
; All ipv4 on port 9911:
; watchtower.listen=0.0.0.0:9911
; On all ipv4 interfaces on port 9911 and ipv6 localhost port 9912:
; watchtower.listen=0.0.0.0:9911
; watchtower.listen=[::1]:9912
; Configure the external IP address of your watchtower. Setting this field does
; not have any behavioral changes to the tower or enable any sort of discovery,
; however it will make the full URI (pubkey@host:port) available via
; WatchtowerRPC.GetInfo and `lncli tower info`.
; watchtower.externalip=1.2.3.4
; Configure the default watchtower data directory. The default directory is
; data/watchtower relative to the chosen lnddir. This can be useful if one needs
; to move the database to a separate volume with more storage. In the example
; below, the database will be stored at:
; /path/to/towerdir/bitcoin/<network>/watchtower.db.
; watchtower.towerdir=/path/to/towerdir
; Duration the watchtower server will wait for messages to be received before
; hanging up on client connections.
; watchtower.readtimeout=15s
; Duration the watchtower server will wait for messages to be written before
; hanging up on client connections
; watchtower.writetimeout=15s
[wtclient]
; Configure the private tower to which lnd will connect to backup encrypted
; justice transactions. The format should be pubkey@host:port, where the port is
; optional and assumed to be 9911 otherwise. At most one private tower URI is
; supported at this time; if none are provided then the watchtower client will
; be inactive.
; wtclient.private-tower-uris=
; Specify the fee rate with which justice transactions will be signed. This fee
; rate should be chosen as a maximum fee rate one is willing to pay in order to
; sweep funds if a breach occurs while being offline. The fee rate should be
; specified in sat/byte, the default is 10 sat/byte.
; wtclient.sweep-fee-rate=10

6
watchtower/wtclient/client_test.go
View File

@ -1058,8 +1058,8 @@ var clientTests = []clientTest{
// less expensive than one that sweeps both.
name: "send and recv",
cfg: harnessCfg{
localBalance: 10000001, // ensure (% amt != 0)
remoteBalance: 20000001, // ensure (% amt != 0)
localBalance: 100000001, // ensure (% amt != 0)
remoteBalance: 200000001, // ensure (% amt != 0)
policy: wtpolicy.Policy{
TxPolicy: wtpolicy.TxPolicy{
BlobType: blob.TypeAltruistCommit,
@ -1071,7 +1071,7 @@ var clientTests = []clientTest{
fn: func(h *testHarness) {
var (
capacity = h.cfg.localBalance + h.cfg.remoteBalance
paymentAmt = lnwire.MilliSatoshi(200000)
paymentAmt = lnwire.MilliSatoshi(2000000)
numSends = uint64(h.cfg.localBalance / paymentAmt)
numRecvs = uint64(capacity / paymentAmt)
numUpdates = numSends + numRecvs // 200 updates

2
watchtower/wtdb/client_session.go
View File

@ -163,7 +163,7 @@ func (b *BackupID) Decode(r io.Reader) error {
// String returns a human-readable encoding of a BackupID.
func (b BackupID) String() string {
return fmt.Sprintf("backup(%x, %d)", b.ChanID, b.CommitHeight)
return fmt.Sprintf("backup(%v, %d)", b.ChanID, b.CommitHeight)
}
// CommittedUpdate holds a state update sent by a client along with its

2
watchtower/wtpolicy/policy.go
View File

@ -27,7 +27,7 @@ const (
// DefaultSweepFeeRate specifies the fee rate used to construct justice
// transactions. The value is expressed in satoshis per kilo-weight.
DefaultSweepFeeRate = lnwallet.SatPerKWeight(12000)
DefaultSweepFeeRate = lnwallet.SatPerKWeight(40000)
// MinSweepFeeRate is the minimum sweep fee rate a client may use in its
// policy, the current value is 4 sat/kw.