ARCH.md

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 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.