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 (4469B)

      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 Just child = derive 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 my_xprv = hd_key child
     32   > xprv_key my_xprv
     33   82064013501759548583899633460204676801585795402966146917762774758050650403971
     34   >
     35   > -- use 'parse' to import an extended key
     36   > let Just hd = xprv child >>= parse
     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 Haskell code. Most time
     49 is spent on elliptic curve multiplication or hashing; strict BIP32
     50 functionality is only a small layer on top of that.
     51 
     52 Current benchmark figures on an M4 Silicon MacBook Air look like (use
     53 `cabal bench` to run the benchmark suite):
     54 
     55 ```
     56   benchmarking ppad-bip32 (wNAF)/derive_child_pub'
     57   time                 180.7 μs   (180.6 μs .. 180.9 μs)
     58                        1.000 R²   (1.000 R² .. 1.000 R²)
     59   mean                 180.8 μs   (180.6 μs .. 180.9 μs)
     60   std dev              493.6 ns   (382.1 ns .. 639.6 ns)
     61 
     62   benchmarking ppad-bip32 (wNAF)/derive_child_priv'
     63   time                 167.0 μs   (166.8 μs .. 167.2 μs)
     64                        1.000 R²   (1.000 R² .. 1.000 R²)
     65   mean                 167.0 μs   (166.8 μs .. 167.2 μs)
     66   std dev              667.4 ns   (488.1 ns .. 925.3 ns)
     67 
     68   benchmarking ppad-bip32/xpub
     69   time                 149.6 μs   (149.1 μs .. 150.2 μs)
     70                        1.000 R²   (1.000 R² .. 1.000 R²)
     71   mean                 149.3 μs   (149.0 μs .. 149.9 μs)
     72   std dev              1.296 μs   (653.2 ns .. 2.117 μs)
     73 
     74   benchmarking ppad-bip32/xprv
     75   time                 6.512 μs   (6.506 μs .. 6.519 μs)
     76                        1.000 R²   (1.000 R² .. 1.000 R²)
     77   mean                 6.512 μs   (6.507 μs .. 6.520 μs)
     78   std dev              19.72 ns   (12.91 ns .. 34.71 ns)
     79 
     80   benchmarking ppad-bip32/parse
     81   time                 6.905 μs   (6.899 μs .. 6.913 μs)
     82                        1.000 R²   (1.000 R² .. 1.000 R²)
     83   mean                 6.926 μs   (6.919 μs .. 6.933 μs)
     84   std dev              23.14 ns   (18.74 ns .. 28.17 ns)
     85 ```
     86 
     87 You should compile with the 'llvm' flag (and ensure [ppad-fixed][fixed],
     88 [ppad-sha256][sha256], [ppad-sha512][sha512], and [ppad-secp256k1][secp]
     89 are compiled with the 'llvm' flag) for maximum performance.
     90 
     91 ## Security
     92 
     93 This library aims at the maximum security achievable in a
     94 garbage-collected language under an optimizing compiler such as GHC, in
     95 which strict constant-timeness can be [challenging to achieve][const].
     96 
     97 The implementation within passes the official [BIP32 test
     98 vectors](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki#
     99 test-vectors), and all derivations involving secret keys execute in
    100 constant time, and with constant allocation -- see the "Security" notes
    101 in the 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