bip32

Pure Haskell BIP32 hierarchical deterministic wallets (docs.ppad.tech/bip32).
git clone git://git.ppad.tech/bip32.git
Log | Files | Refs | README | LICENSE

README.md (4542B)

      1 # bip32
      2 
      3 [![](https://img.shields.io/hackage/v/ppad-bip32?color=blue)](https://hackage.haskell.org/package/ppad-bip32)
      4 ![](https://img.shields.io/badge/license-MIT-brightgreen)
      5 [![](https://img.shields.io/badge/haddock-bip32-lightblue)](https://docs.ppad.tech/bip32)
      6 
      7 An implementation of [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) hierarchical deterministic wallets and extended keys.
      8 
      9 ## Usage
     10 
     11 A sample GHCi session:
     12 
     13 ```
     14   > :set -XOverloadedStrings
     15   >
     16   > import Crypto.HDKey.BIP32
     17   >
     18   > -- derive a master node from a master seed
     19   > let Just m = master "plenty of entropy"
     20   >
     21   > -- use 'xpub', 'xprv', etc. to serialize
     22   > xpub m
     23   "xpub661MyMwAqRbcG6TPJvVs1yKFJGtN4vi785g2xDacQ9Luyw3gyAyvY5DNatPzfsUQK4nTUAmQboxw3WYDHtY4vfcGJR4FAuLLaUp2t7ejhoC"
     24   >
     25   > -- derive child nodes via a path
     26   > let child = derive_partial m "m/44'/0'/0'/0/0"
     27   > xpub child
     28   "xpub6GEwJiJFou5PH6LL8cagArvArrXhSaq35XWnT73CShNRBJa9jxHsWnPsydvmN2vcPBg9KHfRyYLiYnUKCJ8ncba4CgzF56n4kpkqMTSFy35"
     29   >
     30   > -- use the 'hd_key' record to extract the extended key
     31   > let Right (XPrv (X sec cod)) = hd_key child
     32   > sec
     33   82064013501759548583899633460204676801585795402966146917762774758050650403971
     34   >
     35   > -- use 'parse' to import an extended key
     36   > let Just hd = parse (xprv child)
     37   > hd == child
     38   True
     39 ```
     40 
     41 ## Documentation
     42 
     43 Haddocks (API documentation, etc.) are hosted at
     44 [docs.ppad.tech/bip32](https://docs.ppad.tech/bip32).
     45 
     46 ## Performance
     47 
     48 The aim is best-in-class performance for pure, highly-auditable Haskell
     49 code. Most time is spent on elliptic curve multiplication or hashing;
     50 strict BIP32 functionality is only a small layer on top of that.
     51 
     52 Current benchmark figures on my mid-2020 MacBook Air look like (use
     53 `cabal bench` to run the benchmark suite):
     54 
     55 ```
     56   benchmarking ppad-bip32/derive_child_pub
     57   time                 7.766 ms   (7.404 ms .. 8.215 ms)
     58                        0.985 R²   (0.975 R² .. 0.995 R²)
     59   mean                 7.717 ms   (7.565 ms .. 7.890 ms)
     60   std dev              463.5 μs   (362.7 μs .. 653.5 μs)
     61   variance introduced by outliers: 31% (moderately inflated)
     62 
     63   benchmarking ppad-bip32/derive_child_priv
     64   time                 5.080 ms   (4.884 ms .. 5.277 ms)
     65                        0.991 R²   (0.985 R² .. 0.997 R²)
     66   mean                 5.045 ms   (4.974 ms .. 5.140 ms)
     67   std dev              252.6 μs   (201.1 μs .. 310.9 μs)
     68   variance introduced by outliers: 28% (moderately inflated)
     69 
     70   benchmarking ppad-bip32/xpub
     71   time                 2.654 ms   (2.571 ms .. 2.771 ms)
     72                        0.984 R²   (0.976 R² .. 0.992 R²)
     73   mean                 2.613 ms   (2.538 ms .. 2.684 ms)
     74   std dev              242.8 μs   (204.0 μs .. 284.3 μs)
     75   variance introduced by outliers: 64% (severely inflated)
     76 
     77   benchmarking ppad-bip32/xprv
     78   time                 28.10 μs   (25.95 μs .. 30.39 μs)
     79                        0.949 R²   (0.910 R² .. 0.987 R²)
     80   mean                 27.39 μs   (25.84 μs .. 30.17 μs)
     81   std dev              6.442 μs   (3.813 μs .. 10.21 μs)
     82   variance introduced by outliers: 97% (severely inflated)
     83 
     84   benchmarking ppad-bip32/parse
     85   time                 33.20 μs   (31.98 μs .. 34.31 μs)
     86                        0.993 R²   (0.989 R² .. 0.997 R²)
     87   mean                 32.89 μs   (32.08 μs .. 33.81 μs)
     88   std dev              2.958 μs   (2.300 μs .. 3.970 μs)
     89   variance introduced by outliers: 81% (severely inflated)
     90 ```
     91 
     92 ## Security
     93 
     94 This library aims at the maximum security achievable in a
     95 garbage-collected language under an optimizing compiler such as GHC, in
     96 which strict constant-timeness can be [challenging to achieve][const].
     97 
     98 The implementation within passes the official [BIP32 test
     99 vectors](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki#test-vectors), and all derivations involving secret keys execute
    100 *algorithmically* in constant time -- see the "Security" notes in the
    101 README of [ppad-secp256k1][secp] for more details.
    102 
    103 If you discover any vulnerabilities, please disclose them via
    104 security@ppad.tech.
    105 
    106 ## Development
    107 
    108 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a
    109 development shell with:
    110 
    111 ```
    112 $ nix develop
    113 ```
    114 
    115 Then do e.g.:
    116 
    117 ```
    118 $ cabal repl ppad-bip32
    119 ```
    120 
    121 to get a REPL for the main library.
    122 
    123 [nixos]: https://nixos.org/
    124 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html
    125 [const]: https://www.chosenplaintext.ca/articles/beginners-guide-constant-time-cryptography.html
    126 [secp]: https://git.ppad.tech/secp256k1