bolt1

Base Lightning protocol, per BOLT #1 (docs.ppad.tech/bolt1).
git clone git://git.ppad.tech/bolt1.git
Log | Files | Refs | README | LICENSE

ARCH1.md (2451B)

      1 # ARCH1 - ppad-bolt1 BOLT #1 Library Architecture
      2 
      3 ## Goals
      4 
      5 - Provide a safe, total, and performant Haskell implementation of BOLT #1
      6   message encoding/decoding.
      7 - Encode protocol invariants in types where practical, with smart
      8   constructors for validation.
      9 - Keep dependencies minimal (base/bytestring/primitive, ppad-*).
     10 - Provide clear error reporting for parse and protocol violations.
     11 
     12 ## Scope
     13 
     14 - BOLT #1 message envelope, TLV stream, and defined messages:
     15   init, error, warning, ping, pong, peer_storage, peer_storage_retrieval.
     16 - Fundamental types used by BOLT #1: big-endian u/s integers, truncated
     17   unsigned integers, BigSize, and fixed-size byte fields.
     18 
     19 ## Module Layout (proposed)
     20 
     21 - Lightning.Protocol.BOLT1
     22   - High-level API and re-exports.
     23 
     24 - Lightning.Protocol.BOLT1.Prim
     25   - Encoding/decoding primitives for:
     26     u16/u32/u64, s16/s32/s64, truncated unsigned ints, BigSize.
     27   - Minimal encoding checks, bounded size validation.
     28 
     29 - Lightning.Protocol.BOLT1.TLV
     30   - TLV record and stream types.
     31   - Encode/decode and validation (ordering, minimal encoding, length bounds,
     32     unknown even behavior).
     33 
     34 - Lightning.Protocol.BOLT1.Message
     35   - ADTs for BOLT #1 messages and message envelope.
     36   - Feature bitset types and init TLVs.
     37   - Smart constructors for messages with validation.
     38 
     39 - Lightning.Protocol.BOLT1.Codec
     40   - Encode/decode for messages and envelopes.
     41   - Error types and mapping from decode failures to protocol errors.
     42 
     43 ## Error Model
     44 
     45 - Parse errors:
     46   - non-minimal encoding, insufficient data, length mismatch, invalid TLV
     47     ordering, unknown even TLV, invalid extension.
     48 - Protocol errors:
     49   - unknown even message type, invalid message length for known type.
     50 
     51 Errors should be structured so callers can decide when to drop/close
     52 connections vs. ignore a message, per spec.
     53 
     54 ## Performance Strategy
     55 
     56 - Strict fields with UNPACK where it pays off.
     57 - INLINE small encode/decode helpers.
     58 - Prefer ByteString builders with manual sizing for small frames.
     59 - Avoid intermediate allocations in TLV parsing by slicing input.
     60 
     61 ## Public API
     62 
     63 - Total encode/decode functions returning Either error message.
     64 - Types re-exported from a single module for consumers:
     65   message ADTs, TLV types, and common primitives.
     66 
     67 ## Testing and Benchmarking
     68 
     69 - Unit tests from BOLT #1 vectors (BigSize, signed ints).
     70 - Property tests for round-trip and minimal encodings.
     71 - Benchmarks for encode/decode hot paths and allocation tracking.
     72