Technical Preview 2

[h4x3rotab]

Caveat

Technical Preview 2 is our second preview version and is not fully functional, but is useful to demonstrate the progress of development.

Changelog

• August 12: DNS Seeder Deploy DNS Seeder for LND #5
• August 3: Technical Preview 2
  • Migrate to our main repo: BTCGPU/lnd
  • Following upstream, get rid of Glide
  • Fix lncli queryroutes issue
  • Change dns seed
• June 17: Technical Preview 1
  • Initial working LND build

Status of this version

Code base: https://github.com/BTCGPU/lnd

Implementation Checklist

• BOLTs
  • BOLT 1: Base Protocol
  • BOLT 2: Peer Protocol for Channel Management
  • BOLT 3: Bitcoin Gold Transaction and Script Formats
  • 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
  • BOLT 9: Assigned Feature Flags
  • BOLT 10: DNS Bootstrap and Assisted Node Location
  • BOLT 11: Invoice Protocol for Lightning Payments
• Misc
  • Unit tests
  • Cross-client regression test
  • SPV client
• Application
  • GUI integration
  • Payment gateway integration

Have some fun

If you can set up a BTG LN node successfully, please connect to me: 0260af55e51ebb4def6298fd26eba1101e4ede0b54ca76d268f2c5dd30f3d5faa9@45.56.84.44:9735. I will pay you a virtual coffee by testnet btg.

Instructions (BTG testnet only)

This guide will help you compile your own LND for BTG and send / receive Lightning payments between LND nodes. Note that this guide is for testnet only. We use Ubuntu as the example environment.

Step 1: Run BTG core node on testnet

1. Compile the latest testnet full node from master branch. Make sure zmq support is enabled.
2. Edit the config file at $HOME/.bitcoingold/bitcoingold.conf. This is the default config file path for Linux builds. Please adjust if you are running on a different OS.

# The following settings are necessary for LND
server=1
rpcuser=your_rpc_user_name
rpcpassword=your_rpc_password
zmqpubrawblock=tcp://127.0.0.1:18501
zmqpubrawtx=tcp://127.0.0.1:18501
txindex=1
# We are still on testnet
testnet=1
# Optional settings
daemon=1
debug=1

3. Start the bgoldd daemon and fully sync to the testnet. You can check https://test-explorer.bitcoingold.org to ensure the node is at the right block height.

Step 2: Install LND

Generally the instructions are similar to the official LND installation guide (link), but you need to use our repo BTCGPU/lnd instead of the original one.

1. Install golang-1.10-go:

sudo apt-get install golang-1.10-go

• If apt failed to find the package, try apt update
• If your package manager doesn't have golang 1.10, you can try to download the binary.

2. Create Go's base directory $HOME/gocode (as an example) for source management and add the path to $PATH. If you put them in your .bashrc they'll always be ready for you:

export GOPATH=~/gocode
export PATH=$PATH:$GOPATH/bin:/usr/lib/go-1.10/bin

3. Install LND

git clone https://github.com/BTCGPU/lnd $GOPATH/src/github.com/BTCGPU/lnd
cd $GOPATH/src/github.com/BTCGPU/lnd
make
make install

• If you see errors like cannot find package "golang.org/x/sys/cpu", please check the Troubleshooting Section.

4. You should now be able to use the command line tools lnd and lncli.

Step 3: Configure LND

After installing LND, we connect LND to the BTG core client bgoldd. Note that LND will try to read the rpc credentials and zmq ports from the default core node configuration at $HOME/.bitcoingold/bitcoingold.conf.

1. Change the default LND config file at $HOME/.lnd/lnd.conf

[Application Options]
; The directory that logs are stored in. The logs are auto-rotated by default.
; Rotated logs are compressed in place.
logdir=~/.lnd/logs

; Disable macaroon authentication. Macaroons are used are bearer credentials to
; authenticate all RPC access. If one wishes to opt out of macaroons, uncomment
; the line below.
; no-macaroons=true

; Listen on port 9735 for incoming connections.
listen=0.0.0.0:9735

[Bitcoingold]
; If the Bitcoingold chain should be active. Atm, only a single chain can be
; active.
bitcoingold.active=1

; Use Bitcoingold's test network.
bitcoingold.testnet=1

; Use the bgoldd back-end
bitcoingold.node=bgoldd

2. Start bgoldd daemon on testnet and wait it to be fully synced.
3. Run lnd and it should show similar text as below:

Attempting automatic RPC configuration to bgoldd
Automatically obtained bgoldd's RPC credentials
2018-06-18 03:14:54.363 [INF] LTND: Version 0.3.0-alpha
2018-06-18 03:14:54.363 [INF] CHDB: Checking for schema update: latest_version=0, db_version=0
2018-06-18 03:14:54.367 [INF] RPCS: password gRPC proxy started at 127.0.0.1:8080
2018-06-18 03:14:54.367 [INF] RPCS: password RPC server listening on 127.0.0.1:10009
2018-06-18 03:14:54.367 [INF] LTND: Waiting for wallet encryption password. Use `lncli create` to create wallet, or `lncli unlock` to unlock already created wallet.

Step 4: Play with LND

The technical preview 1 has the functionality to run the tutorial:
https://dev.lightning.community/tutorial/01-lncli/index.html

We use lncli to control lnd.

Prepare the wallet

1. Following the instruction for lnd, run lncli create to create a new wallet with your password.
2. Restart lnd. This time run lncli unlock with your password to activate the daemon.
3. Run lncli newaddress np2wkh to generate a wallet address and send some coins to the address for testing. The testnet faucet can be used to get testnet coins. (Note: a segwit address is needed for establishing LN channel.)
4. (Optional) Check the wallet balance by lncli walletbalance.

Connect to another node

1. Run lncli getinfo. You can get basic information and your identity pubkey from the result.
2. To connect to another node the identity pubkey and the ip/port is needed. Example:

lncli connect 027c1d5d710579c641f4e00d5ee770620bb8d4a8a4f5080008e32ba97f1e18245f@45.56.84.44:9735

Note that when connecting two nodes, the one who accepts the connection should have its port (9735 by default) public accessible. To connect to a peer, you need to know its identity pubkey.

When the connection is established, you can check the connected peers by lncli listpeers:

{
    "peers": [
        {
            "pub_key": "036a5657e9a7fb5a5c2ed0dcc51558403e21f87192e0ed9d7beb42e2abd296f116",
            "address": "xx.xx.xx.xx:xxxx",
            "bytes_sent": "111",
            "bytes_recv": "111",
            "sat_sent": "0",
            "sat_recv": "0",
            "inbound": true,
            "ping_time": "367537"
        }
    ]
}

Caveat: Please be aware that a bgoldd instance cannot be shared with more than one lnd if you are doing experiment locally. Sharing the node may result in unexpected behavior.

Open channels

1. Open a channel to existing peers: lncli openchannel --node_key <target_pubkey> --local_amt <local_amount> --push_amt 0 --block 1.

• local_amt: Your initial funding for the new channel, in satoshi.
• push_amt: The money you want to push to the other side of the channel.

Output:

{
    "channel_point": "2fea431670516009900619d02d1e6b6b9f30ca31679852a28cb2209ea90c15e6:0"
}

2. (Optional) After opening a channel, it will be pending until the transaction being confirmed. Check the pending channels by: lncli pendingchannels
3. After a few confirmation, the channel will be opened. Check the status with lncli listchannels:

{
    "channels": [
        {
            "active": true,
            "remote_pubkey": "027c1d5d710579c641f4e00d5ee770620bb8d4a8a4f5080008e32ba97f1e18245f",
            "channel_point": "2fea431670516009900619d02d1e6b6b9f30ca31679852a28cb2209ea90c15e6:0",
            "chan_id": "19985822860574720",
            "capacity": "10000000",
            "local_balance": "9989140",
            "remote_balance": "0",
            "commit_fee": "10860",
            "commit_weight": "600",
            "fee_per_kw": "15000",
            "unsettled_balance": "0",
            "total_satoshis_sent": "0",
            "total_satoshis_received": "0",
            "num_updates": "0",
            "pending_htlcs": [
            ],
            "csv_delay": 1201
        }
    ]
}

4. (Optional) Check the overall balance with lncli walletbalance

Request money by invoice

1. The payee creates a payment request: lncli addinvoice --amt 1234 --memo "pay me a virtual coffee"

{
	"r_hash": "...",
	"pay_req": "lntbtg12340n1pdnl4m6pp5jkzj644hz9atcu3lm2qdws7xz55wwpud9gxljwmenznrvxtpd9rsdp9wpshjgrdv5sxzgrkd9e8gatpdssxxmmxvejk2cqzys4h5kj0hun46sda4veetl7gnhvh7qdc0a5vsylwc8xv4x0jerr855jak26vd3j94yz3nluv27wpwhrer04fjkl0hwf4wd7ycp6kz8hyqqsmddnk"
}

2. Send pay_req to the payer. The payer should first check the invoice: lncli decodepayreq <pay_req>
3. Then the payer pays the invoice: lncli payinvoice --pay_req lntbtg5u1pdnlkpvpp5h5852qdg27t6sq3le4pu7576q4kl8panlwrrsyj3l5ulmrcnrdjqdq4wpshjgrdv5s8qmr9v9ek2cqzysw2xd8rmsxzwxn6n0xpc4ck97l6y09hrmkxf7g88x6n60l8ppgmtsx806t7c6sufuqgvxe492hn7c8flr5uk2z2dlzj385xzgza25mrqqdehuuj

That's it! The instant transaction is done.

Multi-hop payment

1. Assume there are three nodes: A, B, C. We need to connect them in pairs by channels (e.g. A-B, B-C)
2. Now A, B, and C can pay to each other, within the channel capacity. A payment between A and C will be relayed by B.
3. (Optional) To check the route between two nodes, you can run lncli queryroutes <identity_pubkey> --amt <amount_in_sat> (known issue: "lncli queryroutes" crash #4)

Close channel

lncli closechannel --funding_txid 2fea431670516009900619d02d1e6b6b9f30ca31679852a28cb2209ea90c15e
{
    "closing_txid": "f17f006e355ce0d7394808f8346b4dae978e54657f95be1a8838c8c29efc161f"
}

[h4x3rotab]

Toubleshooting

1. Cannot find package when running go install

Error message:

vendor/golang.org/x/crypto/chacha20poly1305/chacha20poly1305_amd64.go:13:2: cannot find package "golang.org/x/sys/cpu" in any of:

.../gocode/src/github.com/shelvenzhou/lnd/vendor/golang.org/x/sys/cpu (vendor tree)
    /usr/lib/go-1.10/src/golang.org/x/sys/cpu (from $GOROOT)
    .../gocode/src/golang.org/x/sys/cpu (from $GOPATH)    

This issue is caused by bad glide dependency handling. We don't know the root cause but there are a few workarounds you can try.

Option 1

Sometimes the following command can solve the problem completely:

glide cc  # clear cache
glide update  # update the dependencies
go install . ./cmd/...  # try to build & install again

Option 2

If option 1 doesn't work, you may need to manually fix the bad file structure. The problem is that glide installed the dependency to a wrong directory. For example, golang.org/x/sys/cpu is a part of the package golang.org/x/sys, but if you check the content of the former directory, you will notice that glide actually downloaded the full package (x/sys) to the subdirectory (x/sys/cpu). We need to manually move the full package from the subdirectory to the root:

cp ./vendor/golang.org/x/sys/cpu/* ./vendor/golang.org/x/sys/

That's saying, each time when you get error like Cannot find package <dir>/golang.org/x/<pkg_name>/<subdir>, you should copy the content from <subdir> to <pkg_name>.

2. Can't connect to wallet when running lnd

Error:

unable to start wallet: Post http://localhost:18332: dial tcp [::1]:18332: connect: connection refused
unable to create chain control: Post http://localhost:18332: dial tcp [::1]:18332: connect: connection refused
Post http://localhost:18332: dial tcp [::1]:18332: connect: connection refused

Solution: lnd tries to connect to core wallet via port 18332. So we should set the rpcport to 18332 in $HOME/.bitcoingold/bitcoingold.conf.

3. No enough money to open a channel

[lncli] rpc error: code = Unknown desc = not enough witness outputs to create funding transaction, need 0.1 BTC only have 0 BTC  available

Only balance in SegWit addresses are usable to open a channel. You can check the balance of your witness wallets by:

lncli --no-macaroons walletbalance --witness_only

If your coins are in a non-segwit address, use sendcoins to move the funds (known issue: #3).

4. Transport is closing

[lncli] rpc error: code = Unavailable desc = transport is closing

It means lncli can't connect to lnd. Please check if lnd is dead.

5. lncli can't connect after the upgrade

[lncli] rpc error: code = Internal desc = connection error: desc = "transport: authentication handshake failed: remote error: tls: handshake failure"

Delete tls.key and tls.cert under $HOME/.lnd

6. Can't connect to remote peer with "OutOfRange" error

[lncli] rpc error: code = OutOfRange desc = EOF

LND doesn't have very well written error descriptions. A possible reason can be that the public key you specified in lncli connect command doesn't match the actual public key. Please reply here if you find you can't connect to my node:

0260af55e51ebb4def6298fd26eba1101e4ede0b54ca76d268f2c5dd30f3d5faa9@45.56.84.44:9735

See also: lightningnetwork#662

[Vutov]

Macaroons are flexible authorization credentials. You can read more here -
https://github.com/lightningnetwork/lnd/blob/master/docs/macaroons.md and here - https://ai.google/research/pubs/pub41892 .

• Three Macaroon files are auto-created on startup of the lnd located in $HOME/.lnd
• If you don't want the macaroons to be validated you can start lnd --no-macaroons , this will just not validate any macaroons (should replace --no-macaroons on every call, but has to be tested). Optionally to avoid having any Macaroons put no-macaroons=true in $HOME/.lnd/lnd.conf
• Macaroons are passed as hex of their file. To create that hex - $(xxd -ps -u -c 1000 $HOME/.lnd/admin.macaroon). It should be added to the header of the call as Grpc-Metadata-macaroon
• When running lnd with Macaroons the lncli is looking for /.lnd/admin.macaroon by default (where the files are auto-generated), so using the lncli from the console on the same machine works out of the box.

Example of remote call

curl --insecure --header "Grpc-Metadata-macaroon: 0201036C6E6402A201030A105FFBF56A5B1BFB879FFD8497405F05E11201301A160A0761646472657373120472656164120577726974651A130A04696E666F120472656164120577726974651A160A076D657373616765120472656164120577726974651A170A086F6666636861696E120472656164120577726974651A160A076F6E636861696E120472656164120577726974651A140A05706565727312047265616412057772697465000006202CCDFA5E245E4B390BD7A75D46BF2E5CFFE2B4159C8F1821BDFDD201DE9" https://62---:53280/v1/getinfo

Response

{"identity_pubkey":"03ec6515bb79e6e277ea327157a3e1773a322949d50439f5b8187d8c4c80e8574b","alias":"03ec6515bb79e6e277ea","block_height":18628,"block_hash":"000755b3a9c88f33c0bca04d6de6dd49c51b380775d6693346f4f67532fa261c","synced_to_chain":true,"testnet":true,"chains":["bitcoingold"],"best_header_timestamp":"1531316384"}

Toubleshooting:

1. LND does not start

Error message:

Detected RPC server listening on publicly reachable interface 0.0.0.0:8080 with authentication disabled! Refusing to start with --no-macaroons specified.

There is public url and Macaroons are required. Check $HOME/.lnd/lnd.conf for 'no-macaroons=true' and commet it out. Doing it will enable Macaroons for the lnd.

2. There are no Macaroon files in $HOME/.lnd

Start the lnd again, if the files are still missing - the wallet was created with no-macaroons=true in $HOME/.lnd/lnd.conf. Comment it out and delete '$HOME/.lnd/data'. It will force the lnd to create new macaroons and .db files on next start. NOTE: Deliting /data WILL DELETE THE WALLET TOO! (the wallet.db is stored there). After deleting it new wallet has to be created lncli create.

[h4x3rotab]

Make you reachable from others

Add the following items to the config file under [Application Options] section.
You can choose your nick name and color for your node.

externalip=<your public ip address>
alias=<nickname of your node, up to 32 utf8 characters>
color=#1a3868