bolt2

Lightning peer protocol, per BOLT #2 (docs.ppad.tech/bolt2).
git clone git://git.ppad.tech/bolt2.git
Log | Files | Refs | README | LICENSE

README.md (4316B)

      1 # ppad-bolt2
      2 
      3 [![](https://img.shields.io/hackage/v/ppad-bolt2?color=blue)](https://hackage.haskell.org/package/ppad-bolt2)
      4 ![](https://img.shields.io/badge/license-MIT-brightgreen)
      5 [![](https://img.shields.io/badge/haddock-bolt2-lightblue)](https://docs.ppad.tech/bolt2)
      6 
      7 A pure Haskell implementation of the Lightning Network peer protocol,
      8 [BOLT #2][bolt2]: the messages for channel establishment (v1 and v2),
      9 interactive transaction construction, quiescence, channel close, normal
     10 operation and message retransmission, with their wire codecs.
     11 
     12 ## Usage
     13 
     14 A sample GHCi session:
     15 
     16 ```
     17   > :set -XOverloadedStrings
     18   > import qualified Data.ByteString as BS
     19   > import qualified Lightning.Protocol.BOLT1 as BOLT1
     20   > import Lightning.Protocol.BOLT2
     21   >
     22   > -- a channel_ready carrying an scid alias (a typed TLV record)
     23   > let Just cid   = BOLT1.channel_id (BS.replicate 32 0xab)
     24   > let Just point = BOLT1.point (BS.cons 0x02 (BS.replicate 32 0x11))
     25   > let alias      = BOLT1.short_channel_id 539268 845 1
     26   > let ready      = ChannelReady cid point alias BOLT1.empty_tlv_stream
     27   > let Right wire = encode_message (MsgChannelReady ready)
     28   > BS.length wire
     29   77
     30   > decode_message wire == Right (MsgChannelReady ready)
     31   True
     32   >
     33   > -- unknown odd TLV records are kept, so re-encoding is exact
     34   > let payload = BS.drop 2 wire
     35   > let Right ext = decode_channel_ready (payload <> "\x2b\x01\x2a")
     36   > channel_ready_tlvs ext
     37   TlvStream [TlvRecord {tlv_type = 43, tlv_value = "*"}]
     38   > encode_channel_ready ext == Right (payload <> "\x2b\x01\x2a")
     39   True
     40   >
     41   > -- unknown even records and malformed known ones are rejected
     42   > decode_channel_ready (payload <> "\x2a\x00")
     43   Left (DecodeTlvError (TlvUnknownEvenType 42))
     44   > let fixed = BS.take 65 payload
     45   > decode_channel_ready (fixed <> "\x01\x07" <> BS.replicate 7 0x00)
     46   Left (DecodeInvalidTlvValue 1)
     47   >
     48   > -- messages from other BOLTs (or splicing) aren't BOLT #2's
     49   > decode_message ("\x00\x50" <> payload)
     50   Left (DecodeUnknownEvenType 80)
     51 ```
     52 
     53 ## Documentation
     54 
     55 Haddocks (API documentation, etc.) are hosted at
     56 [docs.ppad.tech/bolt2](https://docs.ppad.tech/bolt2).
     57 
     58 ## Specification
     59 
     60 This library implements BOLT #2 as of lightning/bolts commit
     61 [1aadb719][spec] (2026-09-21); a copy lives in `etc/`.
     62 
     63 Fundamental types and the TLV format come from [ppad-bolt1][bolt1],
     64 transaction ids from [ppad-tx][tx], and `channel_type` feature vectors
     65 from [ppad-bolt9][bolt9]. Every TLV record the specification defines
     66 outside of splicing has a typed field; unknown odd records are kept.
     67 
     68 Not implemented:
     69 
     70 * Splicing: the `splice_init`, `splice_ack` and `splice_locked`
     71   messages, and the splicing-only TLV records. `tx_add_input`'s
     72   `shared_input_txid` and `tx_signatures`' `shared_input_signature` are
     73   rejected as unknown even types; `channel_reestablish`'s
     74   `my_current_funding_locked` is kept as an unknown odd record.
     75 * The `start_batch` message.
     76 * Channel-level validation: the library checks what decoding needs
     77   (field lengths, point prefixes, amounts of at most 21M BTC, TLV
     78   rules), and leaves rules that depend on channel state or negotiated
     79   features (reserves, feerates, shutdown script forms, `serial_id`
     80   parity, required TLV records, points being on the curve, etc.) to the
     81   caller.
     82 * Interpretation of the onion routing packet and attribution data,
     83   which are kept opaque (see BOLT #4).
     84 
     85 ## Performance
     86 
     87 The aim is best-in-class performance for pure Haskell code. Run the
     88 benchmarks with:
     89 
     90 ```
     91 $ cabal bench
     92 ```
     93 
     94 ## Security
     95 
     96 This library has received no security audit. It decodes strictly:
     97 every message must be consumed exactly, unknown even TLV records are
     98 rejected, and encoding a decoded message reproduces its bytes.
     99 
    100 ## Development
    101 
    102 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a
    103 development shell with:
    104 
    105 ```
    106 $ nix develop
    107 ```
    108 
    109 Then do e.g.:
    110 
    111 ```
    112 $ cabal repl ppad-bolt2
    113 ```
    114 
    115 to get a REPL for the main library.
    116 
    117 [bolt2]: https://github.com/lightning/bolts/blob/master/02-peer-protocol.md
    118 [bolt1]: https://git.ppad.tech/bolt1
    119 [bolt9]: https://git.ppad.tech/bolt9
    120 [tx]: https://git.ppad.tech/tx
    121 [spec]: https://github.com/lightning/bolts/tree/1aadb719b4007c4cea0ba6e36b08c4fb53788dee
    122 [nixos]: https://nixos.org/
    123 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html