interledgerjs / settlement-lightning

⚡️ Settle Interledger payments using the Lightning Network

Interledger Lightning Plugin

🚨 Expect breaking changes while this plugin is in beta.

Overview

ilp-plugin-lightning enables settlements between Interledger peers using the Lightning Network on Bitcoin. Using the ILP/Stream protocol, payments are chunked down into small increments, which can facilitate faster and more relaible payments compared with native Lightning!

The integration requires an existing Lightning node with connectivity to the greater Lightning network. Note that speed within the Lightning network degrades as two peers have more degrees of separation, and opening a direct channel provides a much faster experience.

Additional information on the Lightning Network is available here.

Install

npm install ilp-plugin-lightning

Requires Node.js 10+.

API

Here are the available options to pass to the plugin. Additional configuration options are also inherited from ilp-plugin-btp if the plugin is a client, and ilp-plugin-mini-accounts if the plugin is a server.

Clients do not settle automatically. Sending Lightning payments can be triggered by invoking sendMoney on the plugin, and the money handler is called upon receipt of incoming payments (set using registerMoneyHandler).

The balance configuration has been simplified for servers. Clients must prefund before sending any packets through a server, and if a client fulfills packets sent to them through a server, the server will automatically settle such that they owe 0 to the client. This configuration was chosen as a default due to it's security and protection against deadlocks.

role

• Type:
  • "client" to connect to a single counterparty
  • "server" enables multiple counterparties to connect
• Default: "client"

lnd

• Required
• Type: LndOpts
• Credentials to create a connection to the LND node, or an already constructed LND service

To have the plugin create the connection internally, provide an object with the following properties:

macaroon

• Required
• Type: string or Buffer
• LND macaroon to used authenticate daemon requests as a Base64-encoded string or Buffer (e.g. using fs.readFile)

tlsCert

• Required
• Type: string or Buffer
• TLS certificate to authenticate the connection to the Lightning daemon as a Base64-encoded string or Buffer (e.g. using fs.readFile)

hostname

• Required
• Type: string
• Hostname of the Lightning node

grpcPort

• Type: number
• Default: 10009
• Port of LND gRPC server

For example:

{
  hostname: 'localhost',
  macaroon:
    'AgEDbG5kArsBAwoQ3/I9f6kgSE6aUPd85lWpOBIBMBoWCgdhZGRyZXNzEgRyZWFkEgV3cml0ZRoTCgRpbmZvEgRyZWFkEgV32ml0ZRoXCghpbnZvaWNlcxIEcmVhZBIFd3JpdGUaFgoHbWVzc2FnZRIEcmVhZBIFd3JpdGUaFwoIb2ZmY2hhaW4SBHJlYWQSBXdyaXRlGhYKB29uY2hhaW4SBHJlYWQSBXdyaXRlGhQKBXBlZXJzEgRyZWFkEgV3cml0ZQAABiAiUTBv3Eh6iDbdjmXCfNxp4HBEcOYNzXhrm+ncLHf5jA==',
  tlsCert:
    'LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNpRENDQWkrZ0F3SUJBZ0lRZG81djBRQlhIbmppNGhSYWVlTWpOREFLQmdncWhrak9QUVFEQWpCSE1SOHcKSFFZRFZRUUtFeFpzYm1RZ1lYVjBiMmRsYm1WeVlYUmxaQ0JqWlhKME1TUXdJZ1lEVlFRREV4dEtkWE4wZFhOegpMVTFoWTBKdmIyc3RVSEp2TFRNdWJHOWpZV3d3SGhjTk1UZ3dPREl6TURVMU9ERXdXaGNOTVRreE1ERTRNRFUxCk9ERXdXakJITVI4d0hRWURWUVFLRXhac2JtUWdZWFYwYjJkbGJtVnlZWFJsWkNCalpYSjBNU1F3SWdZRFZRUUQKRXh0S2RYTjBkWE56TFUxaFkwSnZiMnN0VUhKdkxUTXViRzlqWVd3d1dUQVRCZ2NxaGtqT1BRSUJCZ2dxaGtpTwpQUU1CQndOQ0FBU0ZoUm0rdy9UMTBQb0t0ZzRsbTloQk5KakpENDczZmt6SHdQVUZ3eTkxdlRyUVNmNzU0M2oyCkpyZ0ZvOG1iVFYwVnRwZ3FrZksxSU1WS01MckYyMXhpbzRIOE1JSDVNQTRHQTFVZER3RUIvd1FFQXdJQ3BEQVAKQmdOVkhSTUJBZjhFQlRBREFRSC9NSUhWQmdOVkhSRUVnYzB3Z2NxQ0cwcDFjM1IxYzNNdFRXRmpRbTl2YXkxUQpjbTh0TXk1c2IyTmhiSUlKYkc5allXeG9iM04wZ2dSMWJtbDRnZ3AxYm1sNGNHRmphMlYwaHdSL0FBQUJoeEFBCkFBQUFBQUFBQUFBQUFBQUFBQUFCaHhEK2dBQUFBQUFBQUFBQUFBQUFBQUFCaHhEK2dBQUFBQUFBQUF3bGM5WmMKazdiRGh3VEFxQUVFaHhEK2dBQUFBQUFBQUJpTnAvLytHeFhHaHhEK2dBQUFBQUFBQUtXSjV0bGlET1JqaHdRSwpEd0FDaHhEK2dBQUFBQUFBQUc2V3ovLyszYXRGaHhEOTJ0RFF5djRUQVFBQUFBQUFBQkFBTUFvR0NDcUdTTTQ5CkJBTUNBMGNBTUVRQ0lBOU85eHRhem1keENLajBNZmJGSFZCcTVJN0pNbk9GUHB3UlBKWFFmcllhQWlCZDVOeUoKUUN3bFN4NUVDblBPSDVzUnB2MjZUOGFVY1hibXlueDlDb0R1ZkE9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg=='
}

maxPacketAmount

• Type: BigNumber, number, or string
• Default: Infinity
• Maximum amount in satoshis above which an incoming ILP packet should be rejected

Bilateral Communication

This plugin uses the Bilateral Transfer Protocol over WebSockets to send messages between peers. Two subprotocols are supported:

peeringRequest

• Format: [Identity public key], UTF-8 encoded
• Used for sharing pubkey of our Lightning node with the peer
• Only shares pubkey, does not attempt to peer over the Lightning network

paymentRequest

• Format: BOLT11 encoded, then UTF-8 encoded
• Used to send a invoice to the Interledger peer, so they have the ability to send payments to our instance
• By default, peers send 20 invoices ahead of time, and share an additional invoice as each invoice expires or is paid

Known Issues

• LND does not currently support pruning invoices (neither automatically nor manually). As this plugin may generate several invoices per second when a peer is actively streaming money, this can significantly increase the footprint of the LND database.
• LND may soon support spontaneous payments, which would eliminate the overhead of frequently sharing invoices.
• The plugin does not perform any accounting for Lightning Network fees.

settlement-lightning's Issues

doesn't assign ILP addresses correctly

The response to ildcp requests has info.clientAddress 'test.amundsen.bmp.btp18q1lnd', so missing the account part.

Add support for spontaneous payments

• lightningnetwork/lnd#2455
• No invoice sharing required!

Generated types fail linting

The generated proto service types rely on @types/long, which fails since it's not a dependency for packages that depend on this.

• Fix this
• Add the generated types to the tslint

Bundle LND & Neutrino light client

If no gRPC credentials are supplied, startup LND and Neutrino in the background and generate a new wallet.

Also requires:

• Mechanism for the connector operator to fund the wallet
• Way to open direct channels with peers (either automatically or manually)

Troubleshoot LND latency issues

Anecdotally, payments are very slow compared to the ETH/XRP implementations, even with a direct channel between two LND instances operating on the same machine.

• More formally benchmark this; identify bottlenecks
• How much does the 1.5 roundtrips when clearing HTLCs affect this?
• How much latency is from gRPC/notifications of settled invoices?
• How much does this PR, reducing roundtrips from 1.5 to 0.5 when settling HTLCs, reduce latency?

Retroactively credit incoming payments if notification failed

In the current implementation, the plugin must be online in order to credit an incoming Lightning payment. If the plugin is offline but the LND node is online, the sender may have sent a settlement, but it wouldn't be credited.

There should be a protocol or mechanism to retroactively credit settlements to get peers' balances back in sync if the receiver goes offline, then comes back online, or for some reason they fail to get the notification.

send claim after each sendData

We should overwrite sendData and make it call https://github.com/interledgerjs/ilp-plugin-lnd-asym-server/pull/6/files#diff-a4f485aa834ca5b3c24819fceb39c56fL220 after each successful interledger payment.

Clients cannot use non public lnd nodes

Description

The current client plugin almost works out of the box with Zap Wallet's bundled lnd node. But requires a small change.

Zap's lnd node doesn't have an external ip address set. This doesn't stop it sending or receiving payments. But causes the plugin to error on connect.

It fails here: https://github.com/interledgerjs/ilp-plugin-lightning/blob/9efe1886b90aed5236e97fbb3ee77a1ddbb82031/src/account.ts#L265
Because uris field of getInfo is empty: https://github.com/interledgerjs/ilp-plugin-lightning/blob/9efe1886b90aed5236e97fbb3ee77a1ddbb82031/src/index.ts#L222

Possible fix

If the external ip isn't known, send just the lnd node's pubKey on connect (instead of the full pubKey plus host ip). Then don't add the client plugin's node as a peer.

Current workaround

1. Get credentials for Zap's bundled lnd (on macOS):

   • tlsCert: cat "~/Library/Application Support/Zap/lnd/bitcoin/testnet/<wallet name>/tls.cert" | base64
   • macaroon: cat "~/Library/Application Support/Zap/lnd/bitcoin/testnet/<wallet name>/data/chain/bitcoin/testnet/admin.macaroon" | base64
   • host: localhost
   • port: currently 11009. Can be found here: https://github.com/LN-Zap/zap-desktop/blob/f096b01e0a6fb450596acf23a316cbf2d35f03bd/config/production.js#L5. Or by scanning for listening services on localhost ports.

   <wallet name> is usually wallet-1

2. Create a channel in zap to the connector's lnd node.

3. Add a lnd.conf file here ~/Library/Application Support/Zap/lnd/bitcoin/testnet/<wallet name>/lnd.conf with the following:

   [Application Options]
   externalip=<any random ip address>
   

(restart zap)

Return ILP Reject packets instead of throwing

Same as interledgerjs/ilp-plugin-xrp-asym-server#20

Max. unsecured amount?

The plugin does not keep track of the unsecured balance. How do you enforce the peer to send a claim before the unsecured balance gets too large?

Add reproducible integration tests

• https://medium.com/@bitstein/setting-up-a-bitcoin-lightning-network-test-environment-ab967167594a
• https://github.com/lightningnetwork/lnd/tree/master/docker

implement difference with -asym-client

I started this repo by copying some files from ilp-plugin-lnd-asym-client. Then, I changed the base class from ilp-plugin-btp to ilp-plugin-mini-accounts. That should be a good start towards making this a BTP server instead of a BTP client; some other things I will need to fix are:

• ignore sendMoney and send money after each accepted fulfill, like https://github.com/interledgerjs/ilp-plugin-xrp-asym-server/blob/43ec37dca0bc78a21f2c087f2ff48e7f634d3f89/index.js#L498
• deep packet inspection for sendData should be inherited as-is from mini-accounts
• anything else?

Implement _handleCustomData() instead of _handleData() ?

Is there any reason why _handleData() is overwritten? The function is also implemented in the parent class, mini-accounts, and it seems to duplicate code.

Should _handleData() be refactored into _handleCustomData() ?