bolt4

Onion routing protocol, per BOLT #4 (docs.ppad.tech/bolt4).
git clone git://git.ppad.tech/bolt4.git
Log | Files | Refs | README | LICENSE

README.md (2940B)

      1 # ppad-bolt4
      2 
      3 [![](https://img.shields.io/hackage/v/ppad-bolt4?color=blue)](https://hackage.haskell.org/package/ppad-bolt4)
      4 ![](https://img.shields.io/badge/license-MIT-brightgreen)
      5 [![](https://img.shields.io/badge/haddock-bolt4-lightblue)](https://docs.ppad.tech/bolt4)
      6 
      7 A pure Haskell implementation of [BOLT #4][bolt4] (onion routing) from
      8 the Lightning Network protocol specification, including packet
      9 construction and processing, error handling, and route blinding.
     10 
     11 ## Usage
     12 
     13 A sample GHCi session:
     14 
     15 ```
     16   > :set -XOverloadedStrings
     17   >
     18   > -- construct an onion packet for a 3-hop route
     19   > import qualified Crypto.Curve.Secp256k1 as Secp256k1
     20   > import qualified Data.ByteString as BS
     21   > import qualified Lightning.Protocol.BOLT4.Construct as Construct
     22   > import qualified Lightning.Protocol.BOLT4.Process as Process
     23   > import Lightning.Protocol.BOLT4.Types
     24   >
     25   > -- session key (32 bytes random, use CSPRNG in production)
     26   > let sessionKey = BS.replicate 32 0x41
     27   >
     28   > -- node keys (in production, these come from the network)
     29   > let Just hop1Sec = Secp256k1.parse_integer (BS.replicate 32 0x01)
     30   > let Just hop1Pub = Secp256k1.mul Secp256k1._CURVE_G hop1Sec
     31   >
     32   > -- build a minimal payload
     33   > let payload = emptyHopPayload { hpAmtToForward = Just 1000
     34   >                               , hpOutgoingCltv = Just 144 }
     35   > let hop = Construct.Hop hop1Pub payload
     36   >
     37   > -- construct packet (returns packet + shared secrets for error handling)
     38   > let assocData = BS.replicate 32 0x00  -- typically payment_hash
     39   > let Right (packet, secrets) = Construct.construct sessionKey [hop] assocData
     40   >
     41   > -- process at receiving node
     42   > let result = Process.process (BS.replicate 32 0x01) packet assocData
     43   > case result of
     44   >   Right (Process.Receive info) -> print (riPayload info)
     45   >   _ -> putStrLn "not final hop"
     46 ```
     47 
     48 ## Modules
     49 
     50 The library is organized into the following modules:
     51 
     52 * `Lightning.Protocol.BOLT4.Construct` - onion packet construction
     53 * `Lightning.Protocol.BOLT4.Process` - onion packet processing
     54 * `Lightning.Protocol.BOLT4.Error` - failure message handling
     55 * `Lightning.Protocol.BOLT4.Blinding` - route blinding support
     56 * `Lightning.Protocol.BOLT4.Types` - core data types
     57 * `Lightning.Protocol.BOLT4.Codec` - serialization (BigSize, TLV)
     58 * `Lightning.Protocol.BOLT4.Prim` - cryptographic primitives
     59 
     60 ## Documentation
     61 
     62 Haddocks are hosted at [docs.ppad.tech/bolt4][hadoc].
     63 
     64 ## Security
     65 
     66 This is a pre-release library that claims no security properties whatsoever.
     67 
     68 ## Development
     69 
     70 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a
     71 development shell with:
     72 
     73 ```
     74 $ nix develop
     75 ```
     76 
     77 Then do e.g.:
     78 
     79 ```
     80 $ cabal build
     81 $ cabal test
     82 $ cabal bench
     83 ```
     84 
     85 [bolt4]: https://github.com/lightning/bolts/blob/master/04-onion-routing.md
     86 [hadoc]: https://docs.ppad.tech/bolt4
     87 [nixos]: https://nixos.org/
     88 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html