bolt5

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

IMPL1.md (4796B)

      1 # IMPL plan v1
      2 
      3 ## Step 0: Recon (independent)
      4 
      5 - Inventory ppad-* libraries for tx/script/crypto helpers.
      6 - Review existing BOLT implementations for duplicated types:
      7   - bolt2/Types.hs: TxId, Outpoint, Satoshis, MilliSatoshis, Point,
      8     Signature, ScriptPubKey, ChainHash, ShortChannelId.
      9   - bolt3/Types.hs: TxId, Outpoint, Sequence, Locktime, Script, Witness,
     10     Satoshi, MilliSatoshi, Point, Pubkey, PaymentHash.
     11   - bolt3/Tx.hs: Lightning-specific tx builders (CommitmentTx, HTLCTx,
     12     ClosingTx) but NOT raw Bitcoin tx serialisation.
     13   - bolt7/Types.hs: ChainHash, ShortChannelId, Signature, Point.
     14   - Common gap: no raw Tx structure, no serialisation, no txid computation.
     15 - Review ppad-script (../script) for module conventions.
     16 - Confirm which variants to support: anchors, no-anchors, etc.
     17 
     18 NOTE: Significant type duplication across bolt impls. Future ppad-tx
     19 extraction should unify these; for now, implement fresh in Bitcoin.Prim.Tx
     20 with eye toward becoming the canonical source.
     21 
     22 ## Step 1: Tx primitives (independent)
     23 
     24 - Create `lib/Bitcoin/Prim/Tx.hs` following ppad-script conventions.
     25 - Implement core types (filling gaps from bolt3/Types.hs):
     26   - Tx (version, inputs, outputs, locktime, witnesses)
     27   - TxIn (outpoint, scriptSig, sequence)
     28   - TxOut (value, scriptPubKey)
     29 - Reuse where sensible:
     30   - TxId, Outpoint, Sequence, Locktime patterns from bolt3/Types.hs
     31   - Or define fresh and unify later during ppad-tx extraction.
     32 - Serialisation (the key missing piece):
     33   - to_bytes / from_bytes (raw tx format)
     34   - to_base16 / from_base16
     35   - Segwit marker/flag handling (0x00 0x01 prefix)
     36 - TxId computation (double SHA256 of non-witness serialisation).
     37 - Keep this module independent of Lightning; will later become ppad-tx.
     38 
     39 ## Step 1b: Sighash (depends on Step 1)
     40 
     41 - Create `lib/Bitcoin/Prim/Tx/Sighash.hs`.
     42 - SIGHASH flags (ALL, NONE, SINGLE, ANYONECANPAY).
     43 - Legacy sighash computation.
     44 - BIP143 segwit sighash computation (needed for commitment tx signing).
     45 
     46 ## Step 2: BOLT5 types and invariants (depends on Step 1)
     47 
     48 - Create `lib/Lightning/Protocol/BOLT5/Types.hs`.
     49 - Implement newtypes and smart constructors:
     50   - Satoshi, Weight, BlockHeight, CSVDelay.
     51 - Re-export or newtype-wrap TxId, OutPoint from Bitcoin.Prim.Tx.
     52 - Define Role, CommitmentKind, OutputKind, HTLC.
     53 - Provide total helpers; no partials.
     54 
     55 ## Step 3: Channel parameters + state (depends on Step 2)
     56 
     57 - Create `lib/Lightning/Protocol/BOLT5/Channel.hs`.
     58 - Define ChannelParams (dust limits, delays, feature flags).
     59 - Define ChannelState (known commitments, unresolved outputs).
     60 - Encode invariants (e.g., anchor vs non-anchor rules).
     61 
     62 ## Step 4: HTLC tx generation (depends on Steps 1-2)
     63 
     64 - Create `lib/Lightning/Protocol/BOLT5/HTLC.hs`.
     65 - Implement offered/received HTLC tx templates.
     66 - Use Bitcoin.Prim.Tx for tx construction.
     67 - Add weight helpers and witness size constants.
     68 
     69 ## Step 5: Weight calculations (depends on Step 2)
     70 
     71 - Create `lib/Lightning/Protocol/BOLT5/Weight.hs`.
     72 - Implement expected weights from BOLT #5 Appendix A.
     73 - Provide functions to compute fee based on feerate.
     74 
     75 ## Step 6: On-chain resolution engine (depends on Steps 2-3)
     76 
     77 - Create `lib/Lightning/Protocol/BOLT5/OnChain.hs`.
     78 - Implement resolution rules for:
     79   - Mutual close
     80   - Local commitment
     81   - Remote commitment
     82   - Revoked commitment
     83 - Track unresolved outputs and required actions.
     84 - Handle reorg safety by making actions idempotent.
     85 
     86 ## Step 7: Public module + cabal glue (depends on Steps 1-6)
     87 
     88 - Update `lib/Lightning/Protocol/BOLT5.hs` to re-export API.
     89 - Update `ppad-bolt5.cabal` for new modules (including Bitcoin.Prim.*).
     90 - Add ppad-script, ppad-sha256 dependencies.
     91 
     92 ## Step 8: Tests (depends on Steps 1-7)
     93 
     94 - Replace placeholder tests in `test/Main.hs`.
     95 - Add unit tests for tx serialisation (known vectors).
     96 - Add tasty-hunit vectors from BOLT #5 text.
     97 - Add tasty-quickcheck properties for invariants.
     98 
     99 ## Step 9: Benchmarks (depends on Steps 1-7)
    100 
    101 - Update `bench/Main.hs` and `bench/Weight.hs`.
    102 - Provide NFData instances for benchmarked types.
    103 - Benchmark tx serialisation/deserialisation.
    104 
    105 ## Step 10: Docs and examples (parallel with Steps 7-9)
    106 
    107 - Add Haddock examples for exported functions.
    108 - Ensure module headers, line length, OPTIONS_HADDOCK prune.
    109 
    110 ## Delegation map
    111 
    112 - Agent A: Steps 1-1b (Tx primitives + Sighash).
    113 - Agent B: Steps 2-3 (BOLT5 Types + Channel).
    114 - Agent C: Steps 4-5 (HTLC + Weight).
    115 - Agent D: Step 6 (OnChain engine).
    116 - Agent E: Steps 8-9 (Tests + Bench).
    117 - Integrator: Step 7 + Step 10, resolve API mismatches.
    118 
    119 ## Future: ppad-tx extraction
    120 
    121 Once BOLT5 is stable, extract Bitcoin.Prim.Tx* into standalone ppad-tx:
    122 - Move lib/Bitcoin/Prim/Tx.hs and Sighash.hs to new repo.
    123 - Update ppad-bolt5 to depend on ppad-tx.
    124 - No API changes needed if module names are preserved.