bolt9

Lightning feature flags, per BOLT #9 (docs.ppad.tech/bolt9).
git clone git://git.ppad.tech/bolt9.git
Log | Files | Refs | README | LICENSE

README.md (3045B)

      1 # ppad-bolt9
      2 
      3 [![](https://img.shields.io/hackage/v/ppad-bolt9?color=blue)](https://hackage.haskell.org/package/ppad-bolt9)
      4 ![](https://img.shields.io/badge/license-MIT-brightgreen)
      5 [![](https://img.shields.io/badge/haddock-bolt9-lightblue)](https://docs.ppad.tech/bolt9)
      6 
      7 A Haskell implementation of Lightning Network feature flags (BOLT #9),
      8 providing type-safe feature vectors with validation and wire format
      9 encoding.
     10 
     11 ## Overview
     12 
     13 BOLT #9 defines feature flags that Lightning nodes advertise to indicate
     14 support for optional protocol features. Features are represented as bit
     15 positions in a variable-length bit vector:
     16 
     17 - **Even bits** (0, 2, 4, ...) indicate *required* support
     18 - **Odd bits** (1, 3, 5, ...) indicate *optional* support
     19 
     20 For example, `basic_mpp` (multi-part payments) uses bits 16/17. A node
     21 setting bit 16 requires peers to support it; bit 17 indicates optional
     22 support.
     23 
     24 ## Usage
     25 
     26 A sample GHCi session:
     27 
     28 ```
     29   > :set -XOverloadedStrings
     30   > import Lightning.Protocol.BOLT9
     31   > import Data.Maybe (fromJust)
     32   >
     33   > -- Look up features by name
     34   > let mpp = fromJust $ featureByName "basic_mpp"
     35   > featureBaseBit mpp
     36   16
     37   > featureDependencies mpp
     38   ["payment_secret"]
     39   >
     40   > -- Build a feature vector with optional basic_mpp support
     41   > let fv = setFeature mpp False empty
     42   > hasFeature mpp fv
     43   Just False
     44   >
     45   > -- Validation catches missing dependencies
     46   > validateLocal Init fv
     47   Left [MissingDependency "basic_mpp" "payment_secret"]
     48   >
     49   > -- Add the dependency
     50   > let ps = fromJust $ featureByName "payment_secret"
     51   > let fv' = setFeature ps False $ setFeature mpp False empty
     52   > validateLocal Init fv'
     53   Right ()
     54   >
     55   > -- Render to wire format (compact, no leading zeros)
     56   > render fv'
     57   "\STX\128"
     58   >
     59   > -- Parse from wire format
     60   > let fv'' = parse "\STX\128"
     61   > listFeatures fv''
     62   [(Feature {featureName = "payment_secret", ...},False),
     63    (Feature {featureName = "basic_mpp", ...},False)]
     64   >
     65   > -- Remote validation: unknown optional bits are OK
     66   > validateRemote Init (setBit 201 empty)
     67   Right ()
     68   >
     69   > -- But unknown required bits are rejected
     70   > validateRemote Init (setBit 200 empty)
     71   Left [UnknownRequiredBit 200]
     72 ```
     73 
     74 ## Documentation
     75 
     76 Haddocks (API documentation, etc.) are hosted at
     77 [docs.ppad.tech/bolt9](https://docs.ppad.tech/bolt9).
     78 
     79 ## Performance
     80 
     81 The aim is best-in-class performance for feature flag handling.
     82 Benchmarks are available under `bench/` and can be run with:
     83 
     84 ```
     85 $ cabal bench
     86 ```
     87 
     88 ## Security
     89 
     90 This is a pre-release library and makes no claims about security whatsoever.
     91 
     92 ## Development
     93 
     94 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a
     95 development shell with:
     96 
     97 ```
     98 $ nix develop
     99 ```
    100 
    101 Then do e.g.:
    102 
    103 ```
    104 $ cabal repl ppad-bolt9
    105 ```
    106 
    107 to get a REPL for the main library.
    108 
    109 ## Attribution
    110 
    111 This library implements the Lightning Network BOLT #9 specification:
    112 https://github.com/lightning/bolts/blob/master/09-features.md
    113 
    114 [nixos]: https://nixos.org/
    115 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html