sphinx-key/ARCHITECTURE.md

                     ┌──────────────────┐
                     │     CORE LN      │
                     │                  │
                     │                  │
                     │   - lightningd   │
                     │   - channeld     │
                     │   - openingd     │
                     │                  │
                     └────────▲─────────┘
                              │
                              │
                              │ UNIX FILE DESCRIPTORS
                              │
HSMD                          │
┌─────────────────────────────┼──────────────────────────────────────┐
│                             │                                      │
│                  ┌──────────┼───────────┐                          │
│                  │          │           │                          │
│                  │ ┌────────▼─────────┐ │                          │
│                  │ │    CLN CLIENT    │ │                          │
│                  │ │                  │ │                          │
│                  │ │                  │ │                          │
│   BROKER         │ │   SIGNER LOOP    │ │   ---------   BITCOIND   │
│                  │ └────────▲─────────┘ │                          │
│                  │          │           │                          │
│                  │          │           │                          │
│                  │          | MPSC      │                          │
│                  │          │           │                          │
│                  │          │           │                          │
│                  │   ┌──────▼──────┐    │                          │
│                  │   │ MQTT BROKER │    │                          │
│                  │   └──────▲──────┘    │                          │
│                  │          │           │                          │
│                  └──────────┼───────────┘                          │
│                             │                                      │
│                             │                                      │
│                             │ MQTT                                 │
│                             │                                      │
│                             │                                      │
│                ┌────────────┼────────────┐                         │
│                │            │            │                         │
│                │     ┌──────▼──────┐     │                         │
│                │     │ MQTT CLIENT │     │                         │
│                │     └──────▲──────┘     │                         │
│                │            │            │                         │
│   SPHINX-KEY   │            │            │                         │
│                │            │ MPSC       │                         │
│                │            │            │                         │
│                │            │            │                         │
│                │ ┌──────────▼──────────┐ │                         │
│                │ │ VLS PROTOCOL SIGNER │ │                         │
│                │ └──────────▲──────────┘ │                         │
│                │            │            │                         │
│                │            │            │                         │
│                │            │ HAL SPI    │                         │
│                │            │            │                         │
│                │            │            │                         │
│                │    ┌───────▼───────┐    │                         │
│                │    │ SD CARD, LEDs │    │                         │
│                │    └───────────────┘    │                         │
│                │                         │                         │
│                └─────────────────────────┘                         │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

Modules

• HSMD: Daemon taken out of Core Lightning that handles private key material, and serves signing requests remotely.
• BROKER: Proxies HSMD requests from CORE LN to SPHINX-KEY via MQTT.
• SPHINX-KEY: Stores the private keys, and responds to signing requests.

Key Components

• CORE LN: Sends HSMD requests to CLN CLIENT via UNIX file descriptors.
• CLN CLIENT: Reads and writes HSMD requests and responses via UNIX file descriptors. Lives in broker/unix_fd.rs.
• SIGNER LOOP: Loops on HSMD requests received on CLN CLIENT, and sends them to MQTT BROKER via rust std::sync::mpsc thread communication channels. Lives in broker/unix_fd.rs.
• MQTT BROKER: Receives requests from SIGNER LOOP via mpsc channels, and sends them to SPHINX KEY over the internet via authenticated MQTT. Lives in broker/mqtt.rs.
• BITCOIND: Provides on-chain data to BROKER for validation of the operations of VLS PROTOCOL SIGNER.
• MQTT CLIENT: Receives MQTT messages from MQTT BROKER over the internet and sends them to VLS PROTOCOL SIGNER via mpsc channels. MQTT CLIENT lives in sphinx-key/src/conn/mqtt.rs and VLS PROTOCOL SIGNER lives in signer/src/lib.rs.
• SD CARD: Persists data from VLS PROTOCOL SIGNER. Communicates with VLS PROTOCOL SIGNER via the SPI protocol implemented in esp_idf_hal::spi.
• LEDs: Show users and engineers the state of the sphinx-key, for both UX and debugging. Also communicate with VLS PROTOCOL SIGNER via esp_idf_hal::spi.

Paste the code block above into asciiblock.com to make edits. Then press the download button on the top right of the pane to bring it back here.