bolt1

Base Lightning protocol, per BOLT #1 (docs.ppad.tech/bolt1).
git clone git://git.ppad.tech/bolt1.git
Log | Files | Refs | README | LICENSE

README.md (2951B)

      1 # ppad-bolt1
      2 
      3 [![](https://img.shields.io/hackage/v/ppad-bolt1?color=blue)](https://hackage.haskell.org/package/ppad-bolt1)
      4 ![](https://img.shields.io/badge/license-MIT-brightgreen)
      5 [![](https://img.shields.io/badge/haddock-bolt1-lightblue)](https://docs.ppad.tech/bolt1)
      6 
      7 A pure Haskell implementation of the Lightning Network base protocol,
      8 [BOLT #1][bolt1]: the fundamental types and their encodings, the TLV
      9 format, and the `init`, `error`, `warning`, `ping`, `pong`,
     10 `peer_storage` and `peer_storage_retrieval` messages.
     11 
     12 The fundamental types (channel ids, points, signatures, short channel
     13 ids, bounded amounts, etc.) and the TLV machinery are shared by the
     14 other ppad BOLT libraries.
     15 
     16 ## Usage
     17 
     18 A sample GHCi session:
     19 
     20 ```
     21   > :set -XOverloadedStrings
     22   > import Lightning.Protocol.BOLT1
     23   >
     24   > -- a ping carrying an (odd, hence ignorable) extension record
     25   > let Just ext = tlv_stream [TlvRecord 101 "ext"]
     26   > let Right wire = encode_message (MsgPing (Ping 4 "" ext))
     27   > wire
     28   "\NUL\DC2\NUL\EOT\NUL\NULe\ETXext"
     29   >
     30   > -- unknown odd records are preserved, so re-encoding is exact
     31   > decode_message wire
     32   Right (MsgPing (Ping {ping_num_pong_bytes = 4, ping_ignored = "",
     33     ping_tlvs = TlvStream [TlvRecord {tlv_type = 101, tlv_value = "ext"}]}))
     34   >
     35   > -- unknown even message types must close the connection
     36   > decode_message "\NUL\DC4\NUL"
     37   Left (DecodeUnknownEvenType 20)
     38   >
     39   > -- amounts are bounded at 21M BTC and use checked arithmetic
     40   > let Just a = satoshi 1000
     41   > let Just b = satoshi 2500
     42   > sub_sat a b
     43   Nothing
     44   > fmap sat_to_msat (add_sat a b)
     45   Just (MilliSatoshi 3500000)
     46 ```
     47 
     48 ## Documentation
     49 
     50 Haddocks (API documentation, etc.) are hosted at
     51 [docs.ppad.tech/bolt1](https://docs.ppad.tech/bolt1).
     52 
     53 ## Specification
     54 
     55 This library implements BOLT #1 as of lightning/bolts commit
     56 [1aadb719][spec] (2026-09-21); a copy lives in `etc/`.
     57 
     58 Feature vectors (in `init`) are represented with [ppad-bolt9][bolt9].
     59 The `remote_addr` address descriptor is kept as raw bytes.
     60 
     61 ## Performance
     62 
     63 The aim is best-in-class performance for pure Haskell code. Run the
     64 benchmarks with:
     65 
     66 ```
     67 $ cabal bench
     68 ```
     69 
     70 ## Security
     71 
     72 This library has received no security audit. It validates every field
     73 the specification constrains when decoding, rejects unknown even message
     74 and TLV types, and keeps secret types (preimages, per-commitment
     75 secrets) out of `Show` output, comparing them in constant time.
     76 
     77 ## Development
     78 
     79 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a
     80 development shell with:
     81 
     82 ```
     83 $ nix develop
     84 ```
     85 
     86 Then do e.g.:
     87 
     88 ```
     89 $ cabal repl ppad-bolt1
     90 ```
     91 
     92 to get a REPL for the main library.
     93 
     94 [bolt1]: https://github.com/lightning/bolts/blob/master/01-messaging.md
     95 [bolt9]: https://git.ppad.tech/bolt9
     96 [spec]: https://github.com/lightning/bolts/tree/1aadb719b4007c4cea0ba6e36b08c4fb53788dee
     97 [nixos]: https://nixos.org/
     98 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html