bolt5

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

ARCH1.md (4312B)

      1 # ARCH plan v1
      2 
      3 ## Goals
      4 
      5 - Implement BOLT #5 on-chain handling for mutual, unilateral, revoked
      6   closes.
      7 - Encode invariants in types; total, safe API.
      8 - Provide pure resolution engine that consumes chain events and returns
      9   actions to take (spend, watch, wait).
     10 - Keep dependencies minimal; prefer ppad libraries and GHC boot libs.
     11 - Implement tx primitives locally (Bitcoin.Prim.Tx) for later extraction
     12   into ppad-tx.
     13 
     14 ## Non-goals (v1)
     15 
     16 - Wallet integration, mempool publishing, or networking.
     17 - Full transaction construction for every policy variant unless
     18   needed by spec examples.
     19 - Persistent storage or chain sync.
     20 
     21 ## Public API shape (lib/Lightning/Protocol/BOLT5)
     22 
     23 - Re-export primary types and functions from internal modules.
     24 - Keep a small surface:
     25   - Channel parameters and state
     26   - On-chain events (funding spent, commitment seen, spend seen)
     27   - Resolution actions (spend tx, watch, wait, fail channel)
     28   - HTLC tx generation helpers
     29 
     30 ## Module layout
     31 
     32 ### Tx primitives (Bitcoin.Prim.*)
     33 
     34 These modules follow ppad-script conventions and will later be extracted
     35 to ppad-tx:
     36 
     37 - Bitcoin.Prim.Tx
     38   - Tx, TxIn, TxOut, OutPoint, Witness types
     39   - Serialisation (to/from ByteArray, base16)
     40   - TxId computation (double SHA256 of serialised tx)
     41 - Bitcoin.Prim.Tx.Sighash
     42   - SIGHASH flags, sighash computation for legacy/segwit
     43 
     44 ### BOLT #5 modules (Lightning.Protocol.BOLT5.*)
     45 
     46 - Lightning.Protocol.BOLT5
     47   - public re-exports, minimal glue
     48 - Lightning.Protocol.BOLT5.Types
     49   - newtypes, ADTs, smart constructors
     50 - Lightning.Protocol.BOLT5.Channel
     51   - channel parameters/state, validation
     52 - Lightning.Protocol.BOLT5.OnChain
     53   - resolution engine per BOLT #5
     54 - Lightning.Protocol.BOLT5.HTLC
     55   - HTLC tx generation, offered/received logic
     56 - Lightning.Protocol.BOLT5.Weight
     57   - weight calculations, constants
     58 
     59 (Keep clear separation between tx primitives and Lightning-specific
     60 logic; tx modules should have no Lightning dependencies.)
     61 
     62 ## Core types and invariants
     63 
     64 - newtype Satoshi, BlockHeight, BlockDepth, CSVDelay, Weight.
     65 - newtype TxId, OutPoint, TxIndex for on-chain references.
     66 - data Role = Local | Remote.
     67 - data CommitmentKind = LocalCommit | RemoteCommit | RevokedCommit.
     68 - data OutputKind = ToLocal | ToRemote | AnchorLocal | AnchorRemote
     69   | HTLCOffered | HTLCReceived.
     70 - data HTLC with amount, payment hash, cltv expiry, offerer.
     71 - data CommitmentView summarizes a commitment tx:
     72   - outputs list with kind, amount, scripts, htlc id
     73 - data OnChainEvent:
     74   - FundingSpent ClosingTx
     75   - CommitmentSeen CommitmentKind CommitmentView
     76   - SpendSeen OutPoint SpendingTx
     77 - data ResolutionAction:
     78   - Publish Tx
     79   - Watch OutPoint
     80   - WaitUntil BlockHeight
     81   - FailChannel Reason
     82 
     83 Smart constructors enforce:
     84 - Amounts >= 0 and within dust rules.
     85 - HTLC CLTV within bounds.
     86 - CSV delays non-negative.
     87 
     88 ## Resolution engine responsibilities
     89 
     90 - Given channel params + current state + event, derive required
     91   actions per BOLT #5.
     92 - Track unresolved outputs and allow re-entry on reorgs.
     93 - Local/remote symmetry: logic should be parametric on Role.
     94 - Separate "detection" (what tx is this) from "resolution" (what to do).
     95 
     96 ## Dependency strategy
     97 
     98 - Use ppad-script for Script representation.
     99 - Use ppad-sha256 for txid computation (double SHA256).
    100 - Implement tx primitives (Bitcoin.Prim.Tx) locally; extract to ppad-tx
    101   later. This will unify duplicated types across bolt2/3/7 (TxId,
    102   Outpoint, Satoshi, etc.).
    103 - Avoid new deps; ask before adding any non-boot libraries.
    104 - Use ByteString for hashes; keep MagicHash for hot paths only.
    105 
    106 ## Testing strategy
    107 
    108 - Unit tests with vectors from BOLT #5 (HTLC outputs, delays).
    109 - Property tests for invariants:
    110   - All unresolved outputs produce actions
    111   - Symmetry between local/remote roles
    112   - Idempotent handling across reorg replay
    113 
    114 ## Benchmarks
    115 
    116 - Criterion benchmarks for resolution engine on varied HTLC counts.
    117 - Weigh benchmarks for allocation hot spots in HTLC generation.
    118 
    119 ## Concurrency notes (for agent delegation)
    120 
    121 - Tx primitives (Bitcoin.Prim.Tx) are fully independent; start first.
    122 - Types + Channel params can be built once tx primitives exist.
    123 - Weight calculations and HTLC tx generation are independent.
    124 - On-chain resolution can be built once types are fixed.
    125 - Tests and benches can proceed after public API stabilizes.