bolt3

Lightning transaction and script formats, per BOLT #3 (docs.ppad.tech/bolt3).
git clone git://git.ppad.tech/bolt3.git
Log | Files | Refs | README | LICENSE

ARCH1.md (2991B)

      1 # ARCH1: ppad-bolt3 architecture plan
      2 
      3 ## Goals
      4 
      5 - Implement BOLT #3 transaction formats and validation rules in Haskell.
      6 - Provide total, type-safe constructors and parsers for BOLT #3 data.
      7 - Keep dependencies minimal (GHC core/boot + ppad-* libraries).
      8 - Maintain performance with strict fields and unboxed primitives where
      9   useful.
     10 
     11 ## Scope
     12 
     13 - Channel funding, commitment, HTLC, and closing transaction formats.
     14 - Script templates and witness construction per BOLT #3.
     15 - Parsing and serialization of all BOLT #3 transaction types.
     16 - Fee/weight accounting and dust checks.
     17 - Test vectors from the BOLT spec and related references.
     18 
     19 ## Non-goals (initial)
     20 
     21 - Network-level negotiation (BOLT #2).
     22 - Gossip / routing (BOLT #7, #10).
     23 - On-chain wallet management.
     24 - Full Bitcoin scripting engine.
     25 
     26 ## Module layout
     27 
     28 - `Lightning.Protocol.BOLT3`
     29   - Re-export public API.
     30 
     31 - `Lightning.Protocol.BOLT3.Types`
     32   - Newtypes for satoshis, milli-satoshis, txid, outpoint, scripts.
     33   - Invariant-encoding ADTs for transaction variants.
     34 
     35 - `Lightning.Protocol.BOLT3.Keys`
     36   - Key derivation helpers (per-commitment point/secret handling).
     37 
     38 - `Lightning.Protocol.BOLT3.Scripts`
     39   - Script templates (P2WSH, HTLC scripts, to_remote/to_local).
     40   - Witness construction.
     41 
     42 - `Lightning.Protocol.BOLT3.Tx`
     43   - Transaction assembly for funding/commitment/HTLC/closing.
     44   - Weight and fee computation.
     45 
     46 - `Lightning.Protocol.BOLT3.Encode`
     47   - Serialization to Bitcoin tx format.
     48 
     49 - `Lightning.Protocol.BOLT3.Decode`
     50   - Parsing from Bitcoin tx format with validation.
     51 
     52 - `Lightning.Protocol.BOLT3.Validate`
     53   - Stateless validation rules (dust limits, script forms, fee rules).
     54 
     55 ## Data modeling principles
     56 
     57 - Use newtypes for all numeric and hash-like primitives.
     58 - Encode illegal states as unrepresentable (ADTs for tx variants).
     59 - Provide smart constructors for all externally supplied data.
     60 - Avoid partial functions; return `Maybe`/`Either` for fallible ops.
     61 
     62 ## Performance strategy
     63 
     64 - Use strict fields with `!` and `UNPACK` where helpful.
     65 - Inline small helpers; use `MagicHash` for hot-path primitives only
     66   when profiling shows the need.
     67 - Avoid intermediate allocations in serialization.
     68 
     69 ## External dependencies
     70 
     71 - Prefer GHC core/boot libs (base, bytestring, etc.).
     72 - Use ppad-* libraries for primitives (hashing, fixed-size types).
     73 - Ask before adding any external dependency outside policy.
     74 
     75 ## Testing strategy
     76 
     77 - `test/Main.hs` uses tasty.
     78 - Unit tests for each script/tx type using BOLT #3 vectors.
     79 - Property tests for invariants (serialization roundtrip, fee bounds).
     80 
     81 ## Benchmarking strategy
     82 
     83 - `bench/Main.hs`: criterion for serialization and tx assembly.
     84 - `bench/Weight.hs`: weigh for allocations in hot paths.
     85 - Add NFData instances for benchmarked types.
     86 
     87 ## Open questions
     88 
     89 - Which ppad-* libraries should be preferred for hash/bytes types?
     90 - Should we expose low-level Bitcoin tx types or keep them internal?
     91 - Expected API surface: minimal constructors or full builder API?