lspd

README

lspd

lspd is a simple deamon that provides LSP services to Breez clients.

This is a simple example of an lspd that works with an lnd node or a cln node.

Breez SDK uses cln lsdp and Breez mobile uses lnd lspd.

Deployment

Installation and configuration instructions for both implementations can be found here:

Manual install

• CLN - step by step installation instructions for CLN
• LND - step by step installation instructions for LND

Automated deployment

• AWS - automated deployment of bitcoind, CLN and lspd to AWS, together with
• Bash - install everything on any debian/ubuntu server

Implement your own lspd

You can create your own lsdp by implementing the grpc methods described here.

Flow for creating channels

When Alice wants Bob to pay her an amount and Alice doesn't have a channel with sufficient capacity, she calls the lspd function RegisterPayment() and sending the paymentHash, paymentSecret (for mpp payments), destination (Alice pubkey), and two amounts. The first amount (incoming from the lsp point of view) is the amount BOB will pay. The second amount (outgoing from the lsp point of view) is the amount Alice will receive. The difference between these two amounts is the fees for the lsp. In order to open the channel on the fly, the lsp is connecting to lnd using the interceptor api.

Probing support

The lsp supports probing non-mpp payments if the payment hash for probing is sha256('probing-01:' || payment_hash) when payment_hash is the hash of the real payment.

Integration tests

In order to run the integration tests, you need:

• Docker running
• python3 installed
• lightningd v24.02.1
• lnd v0.17.2 lsp version https://github.com/breez/lnd/commit/0c939786ced78a981bd77c7da628bfcf86ada568
• lnd v0.16.4 breez client version https://github.com/breez/lnd/commit/b9b7d37852321146dd7171809d673141fe1137bf
• bitcoind (tested with v23.0)
• bitcoin-cli (tested with v23.0)
• build of lspd (make release-lspd)
• build of lspd cln plugin (make release-plugin)

To run the integration tests, run the following command from the lspd root directory (replacing the appropriate paths).

go test -timeout 20m -v ./itest \
  --lightningdexec /full/path/to/lightningd \
  --lndexec /full/path/to/lnd \
  --lndmobileexec /full/path/to/lnd \
  --clnpluginexec /full/path/to/lspd_cln_plugin \
  --lspdexec /full/path/to/lspd \

• Required: --lightningdexec Full path to lightningd development build executable. Defaults to lightningd in $PATH.
• Required: --lndexec Full path to LSP LND executable. Defaults to lnd in $PATH.
• Required: --lndmobileexec Full path to Breez mobile client LND executable. No default.
• Required: --lspdexec Full path to lspd executable to test. Defaults to lspd in $PATH.
• Required: --clnpluginexec Full path to the lspd cln plugin executable. No default.
• Recommended: --bitcoindexec Full path to bitcoind. Defaults to bitcoind in $PATH.
• Recommended: --bitcoincliexec Full path to bitcoin-cli. Defaults to bitcoin-cli in $PATH.
• Recommended: --testdir uses the testdir as root directory for test files. Recommended because the CLN lightning-rpc socket max path length is 104-108 characters. Defaults to a temp directory (which has a long path length usually).
• Optional: --preservelogs persists only the logs in the testing directory.
• Optional: --preservestate preserves all artifacts from the lightning nodes, miners, postgres container and startup scripts.
• Optional: --dumplogs dumps all logs to the console after a test is complete.

Unfortunately the tests cannot be cancelled with CTRL+C without having to clean up some artefacts. Here's where to look:

• lspd process
• lightningd process
• lnd process
• bitcoind process
• docker container for postgres with default name

It may be a good idea to clean your testdir every once in a while if you're using the preservelogs or preservestate flags.