INSTALL.md

Table of Contents

• Installation
  • Preliminaries
  • Installing dcrlnd
• Available Backend Operating Modes
  • dcrd Options
  • Using dcrd
    • Installing dcrd
    • Starting dcrd
    • Running dcrlnd using the dcrd backend
• Macaroons
• Network Reachability
• Simnet vs. Testnet Development
• Creating an dcrlnd.conf (Optional)

Installation

Preliminaries

In order to work with dcrlnd, the following build dependencies are required:

• Go: dcrlnd is written in Go. To install, run one of the following commands:

  Note: The minimum version of Go supported is Go 1.19. We recommend that users use the latest version of Go, which at the time of writing is 1.20.

  On Linux:

  sudo apt-get install golang-1.19-go
  

  Note that golang-1.19-go puts binaries in /usr/lib/go-1.19/bin. If you want them on your PATH, you need to make that change yourself. Alternatively, you can run:

  sudo ln -s /usr/lib/go-1.19/bin/go /usr/local/bin/go
  

  On Mac OS X:

  brew install go
  

  On FreeBSD:

  pkg install go
  

  Alternatively, one can download the pre-compiled binaries hosted on the golang download page. If one seeks to install from source, then more detailed installation instructions can be found here.

  At this point, you should set your $GOPATH environment variable, which represents the path to your workspace. By default, $GOPATH is set to ~/go. You will also need to add $GOPATH/bin to your PATH. This ensures that your shell will be able to detect the binaries you install.

  export GOPATH=~/gocode
  export PATH=$PATH:$GOPATH/bin

  We recommend placing the above in your .bashrc or in a setup script so that you can avoid typing this every time you open a new terminal window.

• go modules: This project uses go modules to manage dependencies as well as to provide reproducible builds.

  Usage of go modules (with go 1.19) means that you no longer need to clone dcrlnd into your $GOPATH for development purposes. Instead, your dcrlnd repo can now live anywhere!

Installing dcrlnd

With the preliminary steps completed, to install dcrlnd, dcrlncli, and all related dependencies run the following commands:

git clone https://github.com/decred/dcrlnd
cd dcrlnd
go install ./cmd/dcrlnd
go install ./cmd/dcrlncli

The command above will install the current master branch of dcrlnd. If you wish to install a tagged release of dcrlnd (as the master branch can at times be unstable), then visit then release page to locate the latest release. Assuming the name of the release is v0.x.x, then you can compile this release from source with a small modification to the above command:

git clone https://github.com/decred/dcrlnd
cd dcrlnd
git checkout v0.x.x
go install ./cmd/dcrlnd
go install ./cmd/dcrlncli

NOTE: Our instructions still use the $GOPATH directory from prior versions of Go, but with go 1.11, it's now possible for dcrlnd to live anywhere on your file system.

Alternatively, if you want to automatically include commit metadata on your binary (which might help debugging issues or keeping track of things when running multiple versions simultaneously) you can use make:

make install

On FreeBSD, use gmake instead of make.

Alternatively, if one doesn't wish to use `make`, then the `go` commands can be
used directly:
```shell
⛰  go install -v ./...
>>>>>>> f99cf4f7c (multi: Remove GO111MODULE env variable in Makefile)

Updating

To update your version of dcrlnd to the latest version run the following commands:

cd $GOPATH/src/github.com/decred/dcrlnd
git pull
go install ./cmd/dcrlnd
go install ./cmd/dcrlncli

Tests

To check that dcrlnd was installed properly run the following command:

make check

Available Backend Operating Modes

In order to run, dcrlnd requires, that the user specify a chain backend. At the time of writing of this document, only the dcrd backend can be used. We currently require --txindex when running with dcrd.

The set of arguments for each of the backend modes is as follows:

dcrd Options

dcrd:
      --dcrd.dir=                                             The base directory that contains the node's data, logs, configuration file, etc. (default: /Users/roasbeef/Library/Application Support/Dcrd)
      --dcrd.rpchost=                                         The daemon's rpc listening address. If a port is omitted, then the default port for the selected chain parameters will be used. (default: localhost)
      --dcrd.rpcuser=                                         Username for RPC connections
      --dcrd.rpcpass=                                         Password for RPC connections
      --dcrd.rpccert=                                         File containing the daemon's certificate file (default: /Users/roasbeef/Library/Application Support/Dcrd/rpc.cert)
      --dcrd.rawrpccert=                                      The raw bytes of the daemon's PEM-encoded certificate chain which will be used to authenticate the RPC connection.

Using dcrd

Installing dcrd

Use the official dcrd install instructions, preferably with one of the release-worthy builds.

Alternatively, when setting up a new machine for testing you can use make to install a dcrd version that is compatible with dcrlnd:

make dcrd

Starting dcrd

Running the following command will create rpc.cert and default dcrd.conf.

dcrd --testnet --rpcuser=REPLACEME --rpcpass=REPLACEME --txindex

If you want to use dcrlnd on testnet, dcrd needs to first fully sync the testnet blockchain. Depending on your hardware, this may take up to a few hours.

While dcrd is syncing you can check on its progress using dcrd's getinfo RPC command:

dcrctl --testnet --rpcuser=REPLACEME --rpcpass=REPLACEME getinfo
{
  "version": 120000,
  "protocolversion": 70002,
  "blocks": 1114996,
  "timeoffset": 0,
  "connections": 7,
  "proxy": "",
  "difficulty": 422570.58270815,
  "testnet": true,
  "relayfee": 0.00001,
  "errors": ""
}

Additionally, you can monitor dcrd's logs to track its syncing progress in real time.

You can test your dcrd node's connectivity using the getpeerinfo command:

dcrctl --testnet --rpcuser=REPLACEME --rpcpass=REPLACEME getpeerinfo | more

Running dcrlnd using the dcrd backend

If you are on testnet, run this command after dcrd has finished syncing. Otherwise, replace --testnet with --simnet. If you are installing dcrlnd in preparation for the tutorial, you may skip this step.

dcrlnd --testnet --debuglevel=debug --dcrd.rpcuser=kek --dcrd.rpcpass=kek --externalip=X.X.X.X

Macaroons

dcrlnd's authentication system is called macaroons, which are decentralized bearer credentials allowing for delegation, attenuation, and other cool features. You can learn more about them in Alex Akselrod's writeup on the original lnd issue.

Running dcrlnd for the first time will by default generate the admin.macaroon, read_only.macaroon, and macaroons.db files that are used to authenticate into dcrlnd. They will be stored in the network directory (default: lnddir/data/chain/decred/mainnet) so that it's possible to use a distinct password for mainnet, testnet, simnet, etc. Note that if you specified an alternative data directory (via the --datadir argument), you will have to additionally pass the updated location of the admin.macaroon file into dcrlncli using the --macaroonpath argument.

To disable macaroons for testing, pass the --no-macaroons flag into both dcrlnd and dcrlncli.

Network Reachability

If you'd like to signal to other nodes on the network that you'll accept incoming channels (as peers need to connect inbound to initiate a channel funding workflow), then the --externalip flag should be set to your publicly reachable IP address.

Simnet vs. Testnet Development

If you are doing local development, such as for the tutorial, you'll want to start both dcrd and dcrlnd in the simnet mode. Simnet is similar to regtest in that you'll be able to instantly mine blocks as needed to test dcrlnd locally. In order to start either daemon in the simnet mode use simnet instead of testnet, adding the --simnet flag instead of the --testnet flag.

Another relevant command line flag for local testing of new dcrlnd developments is the --debughtlc flag. When starting dcrlnd with this flag, it'll be able to automatically settle a special type of HTLC sent to it. This means that you won't need to manually insert invoices in order to test payment connectivity. To send this "special" HTLC type, include the --debugsend command at the end of your sendpayment commands.

Creating a dcrlnd.conf (Optional)

Optionally, if you'd like to have a persistent configuration between dcrlnd launches, allowing you to simply type dcrlnd --testnet at the command line, you can create an dcrlnd.conf.

On MacOS, located at: /Users/[username]/Library/Application Support/dcrlnd/dcrlnd.conf

On Linux, located at: ~/.dcrlnd/dcrlnd.conf

Here's a sample dcrlnd.conf for dcrd to get you started:

[Application Options]
debuglevel=trace
maxpendingchannels=10

[Decred]
testnet=1

Notice the [Decred] section. This section houses the parameters for the Decred chain. See a more detailed sample config file available here and explore the other sections for node configuration.