bolt2

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

IMPL1.md (2573B)

      1 # IMPL1: BOLT2 implementation plan
      2 
      3 Goal: implement full BOLT #2 message types, codecs, validation, tests,
      4 benchmarks.
      5 
      6 ## Work breakdown
      7 
      8 1) Core types
      9 - Implement newtypes for identifiers, amounts, hashes, and keys.
     10 - Provide smart constructors and validation helpers.
     11 - Add NFData instances for benchmark use.
     12 
     13 2) Message ADTs
     14 - Define per-message record types with strict fields.
     15 - Define the top-level `Message` sum type and tag mapping.
     16 
     17 3) TLV framework
     18 - Implement `TLVStream` type and parser.
     19 - Encode/decode BigSize, ordering, and unknown TLV retention.
     20 
     21 4) Codec layer
     22 - Implement `encodeMessage` and `decodeMessage` dispatchers.
     23 - Implement codecs for each message type using BOLT1 primitives.
     24 
     25 5) Validation layer
     26 - Implement `validateMessage` and per-message validators.
     27 - Enforce invariants that cannot be encoded in types.
     28 
     29 6) Tests
     30 - Add unit tests from BOLT #2 vectors.
     31 - Add property tests for roundtrip and TLV ordering.
     32 
     33 7) Benchmarks
     34 - Add criterion benchmarks for hot paths.
     35 - Add weigh benchmarks for allocation profile.
     36 
     37 8) Cabal + exports
     38 - Update `ppad-bolt2.cabal` to expose modules and tests/benchmarks.
     39 - Keep `Lightning.Protocol.BOLT2` as the public entry point.
     40 
     41 ## Parallelizable tasks
     42 
     43 - TLV framework can be built independently from message codecs.
     44 - Core types can be built in parallel with TLV and message ADTs.
     45 - Tests can be written in parallel once codecs and TLVs are sketched.
     46 - Benchmarks can be added after codecs are in place.
     47 
     48 ## Suggested subagent delegation
     49 
     50 - Agent A: Core types + validation helpers.
     51 - Agent B: TLV framework + TLV tests.
     52 - Agent C: Message ADTs + tag mapping.
     53 - Agent D: Codecs for v1 establishment + close messages.
     54 - Agent E: Codecs for v2 interactive-tx messages.
     55 - Agent F: Normal operation + reestablish messages.
     56 - Agent G: Test vectors + property tests.
     57 - Agent H: Benchmarks + NFData instances.
     58 
     59 ## Risks / notes
     60 
     61 - Some invariants depend on other BOLTs or feature bits. Keep validation
     62   modular and allow partial validation when necessary.
     63 - Ensure total decoders and avoid partial pattern matches.
     64 - Keep lines under 80 chars; use strict fields and UNPACK.
     65 - Do not add external deps without explicit approval.
     66 - If other BOLT implementations are needed (e.g. BOLT1), add them as
     67   flake inputs (e.g. `../bolt1`) and consume via Nix, not ad hoc paths.
     68 
     69 ## Acceptance criteria
     70 
     71 - All BOLT #2 messages are representable and roundtrip.
     72 - All public constructors are total and validated.
     73 - All tests and benchmarks compile and run via cabal.
     74 - No partial functions; no unchecked indexing in tests.