lndk/ARCH.md

## Architecture
There are three components relevant to our architecture:

1. [LDK](https://github.com/lightningdevkit/rust-lightning): imported as a dependency to provide onion message processing and forwarding capabilities.
2. [LND](https://github.com/lightningnetwork/lnd): the grpc API that is exposed by the target LND node built with the appropriate rpc subservers.
3. [LNDK](https://github.com/lndk-org/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](https://github.com/lightningdevkit/rust-lightning/blob/435b3b480283e40f7b8a945eff6465438f39cd5b/lightning/src/onion_message/messenger.rs#L106) that can use LND's node key to process onion messages. This is achieved by implementing the [NodeSigner](https://github.com/lightningdevkit/rust-lightning/blob/fac5373687a4c7919c8639744dc712d922082cc3/lightning/src/chain/keysinterface.rs#L452) 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.

![Onion messenger](docs/arch-onionmessenger.png)

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](https://lightning.engineering/api-docs/api/lnd/lightning/subscribe-peer-events#grpc): subscribe to peer events and notify the `OnionMessenger` of `peer_connected` and `peer_disconnected` events.
2. [SubscribeCustomMessages](https://lightning.engineering/api-docs/api/lnd/lightning/subscribe-custom-messages#grpc): receive incoming onion messages from LND and deliver them to the `OnionMessenger` via `handle_onion_message`
3. [SendCustomMessage](https://lightning.engineering/api-docs/api/lnd/lightning/send-custom-message#grpc): poll the `OnionMessenger` for `next_onion_message_for_peer` and deliver queued outbound onion messages to LND for sending.

![Onion message processing](docs/arch-onionmessageflow.png)