bolt2

Lightning peer protocol, per BOLT #2 (docs.ppad.tech/bolt2).
git clone git://git.ppad.tech/bolt2.git
Log | Files | Refs | README | LICENSE

ARCH1.md (3919B)

      1 # ARCH1: BOLT2 architecture
      2 
      3 Goal: implement the Lightning Network peer protocol (BOLT #2) with
      4 strong types, total decoding, and high performance, using only core and
      5 ppad libraries.
      6 
      7 ## Scope
      8 
      9 - Messages defined in BOLT #2 (v1 and v2 channel establishment, close,
     10   normal operation, reestablish).
     11 - Binary encoding/decoding of messages and TLVs.
     12 - Validation of message invariants at boundary.
     13 - Tests against spec vectors and property tests for roundtrips.
     14 - Benchmarks for encode/decode hot paths.
     15 
     16 Out of scope: wire transport, encryption, gossip, BOLT #3/7 logic.
     17 
     18 ## Module layout (proposed)
     19 
     20 - `Lightning.Protocol.BOLT2`
     21   - Public re-exports, type aliases, and high level API.
     22 - `Lightning.Protocol.BOLT2.Types`
     23   - Newtypes and ADTs for identifiers, amounts, features, and message
     24     payloads.
     25 - `Lightning.Protocol.BOLT2.Message`
     26   - Sum type of all BOLT2 messages and message type tags.
     27 - `Lightning.Protocol.BOLT2.Codec`
     28   - Encoding/decoding for each message and the top-level dispatcher.
     29 - `Lightning.Protocol.BOLT2.TLV`
     30   - TLV stream types and known TLV records.
     31 - `Lightning.Protocol.BOLT2.Validation`
     32   - Smart constructors and invariants for all public types.
     33 
     34 A module split keeps API clean and allows smaller, INLINE-friendly
     35 functions in the codec.
     36 
     37 ## Types and invariants
     38 
     39 - Use newtypes for identifiers and amounts:
     40   - `ChannelId`, `ShortChannelId`, `Satoshis`, `MilliSatoshis`,
     41     `BlockHeight`, `FeeratePerKw`, `CsvDelay`, `HtlcId`, `CltvExpiry`.
     42 - Use fixed-size ByteString newtypes:
     43   - `PubKey33`, `Signature64`, `Sha256`, `ChainHash32`.
     44 - Encode legal states in ADTs:
     45   - `ShutdownScript` as a sum of allowed script forms.
     46   - `CloseFee` either `CloseFeeProposed` or `CloseFeeNone` for v2 flow.
     47 - Smart constructors validate lengths and numeric bounds.
     48 
     49 All public constructors should be total, validated, and return
     50 `Either DecodeError a` or `Maybe a`.
     51 
     52 ## Encoding and decoding
     53 
     54 - Use BOLT1 primitives (`encodeU16`, `decodeU16`, `encodeBigSize`, ...).
     55 - Provide `encodeMessage :: Message -> ByteString` and
     56   `decodeMessage :: ByteString -> Either DecodeError Message`.
     57 - Dispatch on message type tag; for known tags, parse body strictly.
     58 - Keep parsers total; never throw exceptions; return `DecodeError`.
     59 - For TLVs, parse as `TLVStream` with known/unknown TLVs preserved.
     60 
     61 ## TLV handling
     62 
     63 - Implement a small TLV framework using BigSize types.
     64 - Known TLVs decode into typed records; unknown TLVs preserved as raw
     65   `(type, bytes)` for roundtrip correctness.
     66 - For each message with TLVs, keep `tlvs :: TLVStream` field.
     67 
     68 ## Validation
     69 
     70 - Validate per-message invariants described in BOLT #2, for example:
     71   - channel reserve <= funding amount.
     72   - dust limits within limits.
     73   - maximum HTLC values consistent with fee rate.
     74   - feature bit constraints for v2 flows.
     75 - Provide `validateMessage :: Message -> Either ValidationError Message`.
     76 
     77 ## Error model
     78 
     79 - `DecodeError` enumerates: short input, unknown tag, invalid length,
     80   invalid field, invalid TLV ordering, and overflow.
     81 - `ValidationError` enumerates semantic violations.
     82 
     83 ## Performance
     84 
     85 - Strict fields with `BangPatterns` and `UNPACK` where practical.
     86 - Small, INLINE encode/decode helpers for hot paths.
     87 - Avoid intermediate lists in codecs; use ByteString builders.
     88 
     89 ## Tests
     90 
     91 - Unit tests from BOLT #2 examples.
     92 - Roundtrip tests for each message:
     93   - `decodeMessage (encodeMessage m) == Right m`.
     94 - Property tests for TLV ordering and unknown TLV preservation.
     95 - Totality tests for decoders with short or malformed inputs.
     96 
     97 ## Benchmarks
     98 
     99 - Encode/decode benchmarks for:
    100   - open_channel, accept_channel, commitment_signed,
    101     update_add_htlc, channel_reestablish.
    102 - Separate allocation benchmarks in `bench/Weight.hs`.
    103 
    104 ## Deliverables
    105 
    106 - New modules under `lib/Lightning/Protocol/BOLT2/*`.
    107 - Tests under `test/` and benchmarks under `bench/`.
    108 - Updated `ppad-bolt2.cabal` exports and test/bench stanzas.
    109