bolt9

Lightning feature flags, per BOLT #9 (docs.ppad.tech/bolt9).
git clone git://git.ppad.tech/bolt9.git
Log | Files | Refs | README | LICENSE

IMPL1.md (2699B)

      1 # IMPL1: Implementation plan for ppad-bolt9
      2 
      3 ## Scope
      4 
      5 Implement BOLT 9 feature flags with typed representation, parsing,
      6 validation, and tests driven by etc/09-features.md.
      7 
      8 ## Step plan
      9 
     10 1) Baseline types and context model
     11    - Add `Context` ADT and helpers for context rules (C-/C+).
     12    - Add newtypes for `BitIndex`, `OptionalBit`, `RequiredBit` with
     13      smart constructors enforcing odd/even parity.
     14    - Define `FeatureVector` wrapper over strict ByteString with basic
     15      operations (empty, set, clear, member).
     16    - Independent: yes, can proceed in parallel with step 2.
     17 
     18 2) Known feature table
     19    - Encode the known features from 09-features.md in a table with:
     20      name, base bit, contexts, dependencies, assumed.
     21    - Provide total lookup functions:
     22      `featureByBit`, `featureByName`.
     23    - Provide accessors for contexts and dependencies.
     24    - Independent: yes, can proceed in parallel with step 1.
     25 
     26 3) Parsing and rendering
     27    - Implement parse from ByteString into FeatureVector (bit order per
     28      BOLT 1, least-significant bit is bit 0).
     29    - Implement rendering back to ByteString preserving compact length
     30      rules (trim leading zero bytes).
     31    - Add total helpers to map between bits and features.
     32    - Depends on steps 1-2.
     33 
     34 4) Validation engine
     35    - Implement local validation:
     36      - no optional+required pair set
     37      - context restrictions (C-/C+ and allowed contexts)
     38      - dependency closure (transitive)
     39      - must set required bits for required features
     40    - Implement remote validation:
     41      - treat unknown optional bits as ignorable
     42      - reject unknown required bits
     43      - if both bits set, treat as required
     44    - Provide error ADT with structured reasons.
     45    - Depends on steps 1-3.
     46 
     47 5) Public API surface in Lightning.Protocol.BOLT9
     48    - Expose safe constructors and validation helpers.
     49    - Add Haddock examples for exported functions.
     50    - Ensure module header and OPTIONS_HADDOCK prune.
     51    - Depends on steps 1-4.
     52 
     53 6) Tests
     54    - Unit tests for known features table and bit parity.
     55    - Unit tests for context restrictions and dependency checks.
     56    - Property tests for render/parse roundtrip and dependency closure.
     57    - Depends on steps 1-4.
     58 
     59 7) Benchmarks
     60    - Criterion benchmarks for parse/validate/render.
     61    - Weigh benchmark for allocation profile.
     62    - Define NFData instances as needed.
     63    - Depends on steps 1-4.
     64 
     65 ## Notes for subagents
     66 
     67 - Use strictness annotations and INLINE for small helpers.
     68 - Avoid partial functions; make pattern matches exhaustive.
     69 - Keep lines under 80 chars.
     70 - Do not add new external deps without approval.
     71 - If you introduce validation policy knobs, keep defaults conservative
     72   (reject unknown required bits).
     73