bolt8

commit d5ff3c2ef45779560e66a0e00fbdc65d87c98f9f
parent b8f9b66519630692847aa1fdcf4e0b0c1249a677
Author: Jared Tobin <jared@jtobin.io>
Date:   Sat, 10 Oct 2026 13:02:45 +0400

docs: correct rotation cadence and framing guidance

Keys rotate every 1000 nonces, i.e. every 500 messages per direction,
not every 1000 messages. The exact-frame function is 'decrypt', not
'decrypt_frame'; the latter consumes one frame from the front of a
buffer and returns the remainder.

Diffstat:
M
README.md
 | 
8
+++++---
M
lib/Lightning/Protocol/BOLT8.hs
 | 
13
++++++++-----
M
lib/Lightning/Protocol/BOLT8/Internal.hs
 | 
2
+-

3 files changed, 14 insertions(+), 9 deletions(-)
diff --git a/README.md b/README.md
@@ -40,9 +40,11 @@ A sample GHCi session:
 
 ## Framing
 
-On a byte stream, use `decrypt_frame` when you have an exact frame, or
-`decrypt_frame_partial` to work incrementally and learn how many bytes
-are still required for the next step.
+On a byte stream, use `decrypt` when you have exactly one frame,
+`decrypt_frame` when a buffer starts with a complete frame (it returns
+the unconsumed remainder), or `decrypt_frame_partial` to work
+incrementally and learn how many bytes are still required for the next
+step.
 
 ## Documentation
 
diff --git a/lib/Lightning/Protocol/BOLT8.hs b/lib/Lightning/Protocol/BOLT8.hs
@@ -46,7 +46,8 @@
 -- 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):
+-- every 1000 nonces, i.e. every 500 messages in each
+-- direction):
 --
 -- @
 -- -- sender
@@ -59,10 +60,12 @@
 -- = Message Framing
 --
 -- BOLT #8 runs over a byte stream, so callers often need to
--- deal with partial buffers. Use 'decrypt_frame' when you
--- have exactly one frame, or 'decrypt_frame_partial' to
--- handle incremental reads and return how many bytes are
--- still needed.
+-- deal with partial buffers. Use 'decrypt' when you have
+-- exactly one frame, 'decrypt_frame' when a buffer starts
+-- with a complete frame (it returns the unconsumed
+-- remainder), or 'decrypt_frame_partial' to handle
+-- incremental reads and return how many bytes are still
+-- needed.
 --
 -- Maximum plaintext size is 65535 bytes.
 
diff --git a/lib/Lightning/Protocol/BOLT8/Internal.hs b/lib/Lightning/Protocol/BOLT8/Internal.hs
@@ -704,7 +704,7 @@ decrypt sess packet = do
 --
 --   Returns the plaintext, any unconsumed bytes, and the
 --   updated session. Key rotation is handled automatically
---   every 1000 messages.
+--   every 1000 nonces (i.e. every 500 messages).
 --
 --   This is useful for streaming scenarios where multiple
 --   messages may be buffered together. The remainder can be