LNDK

An experimental attempt at using LDK to implement bolt 12 features for LND.

• Contributor guidelines
• Code of Conduct

Setting up LNDK

To run LNDK, LND is assumed to be running. For directions on how to do this, try this guide.

When compiling LND, make sure that the peersrpc and signerrpc services are enabled, like this:

make install --tags="peersrpc signerrpc dev"

LND must also be run with --protocol.custom-message=513 to allow it to report onion messages to LNDK, which requires LND version v0.16.0-beta).

In order to successfully connect to LND, we need to pass in the grpc address and authentication credentials. These values can be passed in via the command line when running the LNDK program, like this:

• cargo run -- --address=<ADDRESS> --cert=<TLSPATH> --macaroon=<MACAROONPATH>

In a more concrete example:

cargo run -- --address=https://localhost:10009 --cert=/home/<USERNAME>/.lnd/tls.cert --macaroon=/home/<USERNAME>/.lnd/data/chain/bitcoin/regtest/admin.macaroon

Remember that the grpc address must start with https:// for the program to work.

• Alternatively, you can use a configuration file to add the required arguments.

• In the lndk directory, create fle named lndk.conf.
• Add the following lines to the file
  • address="https://localhost:10009"
  • cert="/home/<USERNAME>/.lnd/tls.cert"
  • macaroon="/home/<USERNAME>/.lnd/data/chain/bitcoin/regtest/admin.macaroon"
• Run cargo run -- --conf lndk.conf

• Use any of the commands with the --help option for more information about each argument.

Architecture

There are three components relevant to our architecture:

1. LDK: imported as a dependency to provide onion message processing and forwarding capabilities.
2. LND: the grpc API that is exposed by the target LND node built with the appropriate rpc subservers.
3. LNDK: a thin rust shim that connects to LND's API (via grpc), acting as a shim that connects LND's APIs to LDK's functionality and providing input/output to the LND node.

The use of LND's flexible API and LDK's modular lightning library allows us to re-use the bolt 12 implementation in LDK. LNDK itself is intended to act as a simple shim that facilitates communication between LND and the LDK library - wrapping API calls in trait implementations for LDK, converting types and passing messages between the LDK state machine and LND's APIs.

So, basically, Frankeinstein's monster. With extra steps.

Onion Messages

Onion messaging is implemented using by implementing a custom version of LDK's OnionMessenger that can use LND's node key to process onion messages. This is achieved by implementing the NodeSigner trait, making relevant calls to LND's signerrpc API to perform ECDH ops with the node's private key. All other components can use the built-in options available in LDK.

Once we have an OnionMessenger that can process messages on behalf of the LND node, we need to handle events that are relevant to the messenger.

1. SubscribePeerEvents: subscribe to peer events and notify the OnionMessenger of peer_connected and peer_disconnected events.
2. SubscribeCustomMessages: receive incoming onion messages from LND and deliver them to the OnionMessenger via handle_onion_message
3. SendCustomMessage: poll the OnionMessenger for next_onion_message_for_peer and deliver queued outbound onion messages to LND for sending.

NOTE: It is recommended to always use cargo-crev to verify the trustworthiness of each of your dependencies, including this one.