commit 7a30233a1417f34e9dae47455f2332bbf6d5b7f1
parent 6a8fe194e7148d95adcc5c803c7bc52f5a0b60af
Author: Jared Tobin <jared@jtobin.io>
Date: Mon, 12 Jan 2026 14:04:54 +0400
lib: basic module header
Diffstat:
1 file changed, 43 insertions(+), 2 deletions(-)
diff --git a/lib/Lightning/Protocol/BOLT8.hs b/lib/Lightning/Protocol/BOLT8.hs
@@ -12,11 +12,52 @@
-- License: MIT
-- Maintainer: Jared Tobin <jared@ppad.tech>
--
--- Encrypted and authenticated transport, per
+-- Encrypted and authenticated transport for the Lightning Network, per
-- [BOLT #8](https://github.com/lightning/bolts/blob/master/08-transport.md).
--
-- This module implements the Noise_XK_secp256k1_ChaChaPoly_SHA256
--- handshake protocol for Lightning Network transport encryption.
+-- handshake and subsequent encrypted message transport.
+--
+-- = Handshake
+--
+-- A BOLT #8 handshake consists of three acts. The /initiator/ knows the
+-- responder's static public key in advance and initiates the connection:
+--
+-- @
+-- (msg1, state) <- act1 i_sec i_pub r_pub entropy
+-- -- send msg1 (50 bytes) to responder
+-- -- receive msg2 (50 bytes) from responder
+-- (msg3, result) <- act3 state msg2
+-- -- send msg3 (66 bytes) to responder
+-- let session = 'session' result
+-- @
+--
+-- The /responder/ receives the connection and authenticates the initiator:
+--
+-- @
+-- -- receive msg1 (50 bytes) from initiator
+-- (msg2, state) <- act2 r_sec r_pub entropy msg1
+-- -- send msg2 (50 bytes) to initiator
+-- -- receive msg3 (66 bytes) from initiator
+-- result <- finalize state msg3
+-- let session = 'session' result
+-- @
+--
+-- = Message Transport
+--
+-- After a successful handshake, use 'encrypt' and 'decrypt' to exchange
+-- messages. Each returns an updated 'Session' that must be used for the
+-- next operation (keys rotate every 1000 messages):
+--
+-- @
+-- -- sender
+-- (ciphertext, session') <- 'encrypt' session plaintext
+--
+-- -- receiver
+-- (plaintext, session') <- 'decrypt' session ciphertext
+-- @
+--
+-- Maximum plaintext size is 65535 bytes.
module Lightning.Protocol.BOLT8 (
-- * Keys
