bolt5

On-chain transaction handling for Lightning (docs.ppad.tech/bolt5).
git clone git://git.ppad.tech/bolt5.git
Log | Files | Refs | README | LICENSE

CLAUDE.md (4525B)

      1 # ppad-bolt5
      2 
      3 Haskell implementation of BOLT #5 (Lightning Network on-chain transaction
      4 handling).
      5 
      6 Specification: https://github.com/lightning/bolts/blob/master/05-onchain.md
      7 (tracked as of lightning/bolts@1aadb719; copy in `etc/05-onchain.md`).
      8 
      9 The library's scope is being redesigned and it is not yet ready for
     10 release; see the README for what it does and doesn't cover.
     11 
     12 ## Project Structure
     13 
     14 - `lib/` - library source (public API: Lightning.Protocol.BOLT5;
     15   submodules are internal)
     16 - `test/` - tests (tasty, tasty-hunit, tasty-quickcheck), public API only;
     17   BOLT #3 Appendix C/F vectors inline
     18 - `bench/` - benchmarks (criterion for timing, weigh for allocations)
     19 - `etc/` - reference materials (BOLT spec, pinned upstream commit)
     20 - `flake.nix` - nix flake for dependency and build management
     21 - `ppad-bolt5.cabal` - cabal package definition
     22 - `CLAUDE.md` / `AGENTS.md` - keep these in sync
     23 
     24 ## Build and Test
     25 
     26 Enter devshell and use cabal:
     27 
     28 ```
     29 nix develop
     30 cabal build
     31 cabal test
     32 cabal bench
     33 ```
     34 
     35 Do not use stack. All dependency and build management via nix.
     36 
     37 ## Dependencies
     38 
     39 ### ppad libraries (use freely)
     40 
     41 Use ppad libraries (github.com/ppad-tech, git.ppad.tech) liberally.
     42 
     43 ### External libraries
     44 
     45 Use only minimal external dependencies. Prefer GHC's core/boot libraries
     46 (base, bytestring, primitive, etc.).
     47 
     48 **Ask for explicit confirmation before adding any library outside of:**
     49 - GHC boot/core libraries
     50 - ppad-* libraries
     51 - Test dependencies (tasty, QuickCheck, etc. for test-suite only)
     52 - Benchmark dependencies (criterion, weigh for benchmark only)
     53 
     54 Current dependencies: ppad-bolt1, ppad-bolt3, ppad-sha256, ppad-tx.
     55 
     56 ## Code Style
     57 
     58 ### Performance
     59 
     60 - Use strictness annotations (BangPatterns) liberally
     61 - Prefer UNPACK for strict record fields
     62 - Use MagicHash, UnboxedTuples, GHC.Exts for hot paths
     63 - Do not rely on UNBOX pragmas; implement primitives directly with
     64   MagicHash and GHC.Exts when needed
     65 - Use INLINE pragmas for small functions
     66 - Refer to ppad-sha256 and ppad-fixed for low-level patterns
     67 
     68 ### Type safety
     69 
     70 - Encode invariants into the type system
     71 - Use newtypes liberally
     72 - Use ADTs to make illegal states unrepresentable
     73 - Prefer smart constructors that validate inputs
     74 
     75 ### Safety
     76 
     77 - Never use partial Prelude functions (head, tail, !!, etc.)
     78 - Avoid brittle partials in tests too (e.g., unchecked indexing). Prefer
     79   bounds checks or total helpers even in test code.
     80 - Avoid non-exhaustive pattern matches and unsafe behavior; use total
     81   helpers and make all constructors explicit.
     82 - Use Maybe/Either for fallible operations
     83 - Validate all inputs at system boundaries
     84 
     85 ### Formatting
     86 
     87 - Keep lines under 80 characters
     88 - Use Haskell2010
     89 - Module header with copyright, license, maintainer
     90 - OPTIONS_HADDOCK prune for public modules
     91 - Haddock examples for exported functions
     92 
     93 ## Testing
     94 
     95 Use tasty to wrap all tests:
     96 - tasty-hunit for unit tests with known vectors
     97 - tasty-quickcheck for property-based tests
     98 - Source test vectors from specifications (RFC, BOLT spec, Wycheproof, etc.)
     99 
    100 Property tests should enforce invariants that can't be encoded in types.
    101 
    102 ## Benchmarking
    103 
    104 Always maintain benchmark suites:
    105 - `bench/Main.hs` - criterion for wall-time benchmarks
    106 - `bench/Weight.hs` - weigh for allocation tracking
    107 
    108 Define NFData instances for types that need benchmarking.
    109 
    110 ## Git Workflow
    111 
    112 - Feature branches for development; commit freely there
    113 - Logical, atomic commits on feature branches
    114 - Master should be mostly merge commits
    115 - Merge to master with `--no-ff` after validation
    116 - Always build and test before creating a merge commit
    117 - Write detailed merge commit messages summarising changes
    118 
    119 ### Worktree flow (for planned work)
    120 
    121 When starting work on an implementation plan:
    122 
    123 ```
    124 git worktree add ./impl-<desc> -b impl/<desc> master
    125 # work in that worktree
    126 # merge to master when complete
    127 git worktree remove ./impl-<desc>
    128 ```
    129 
    130 ### Commits
    131 
    132 - Higher-level descriptions in merge commits
    133 - Never update git config
    134 - Never use destructive git commands (push --force, hard reset) without
    135   explicit request
    136 - Never skip hooks unless explicitly requested
    137 
    138 ## Planning
    139 
    140 When planning work:
    141 - Highlight which steps can be done independently
    142 - Consider forking subagents for concurrent work on independent steps
    143 - Write implementation plans to `plans/IMPL<n>.md` if the project uses
    144   this convention
    145 
    146 ## Flake Structure
    147 
    148 The flake.nix follows ppad conventions:
    149 - Uses ppad-nixpkgs as base
    150 - Follows references to avoid duplication
    151 - Provides devShell with ghc, cabal, cc, llvm