README.md (4246B)
1 # bip32 2 3 [](https://hackage.haskell.org/package/ppad-bip32) 4  5 [](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, 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 an M4 Silicon MacBook Air look like (use 53 `cabal bench` to run the benchmark suite): 54 55 ``` 56 benchmarking ppad-bip32/derive_child_pub 57 time 2.668 ms (2.663 ms .. 2.672 ms) 58 1.000 R² (1.000 R² .. 1.000 R²) 59 mean 2.661 ms (2.658 ms .. 2.664 ms) 60 std dev 8.440 μs (6.211 μs .. 13.00 μs) 61 62 benchmarking ppad-bip32/derive_child_priv 63 time 1.784 ms (1.783 ms .. 1.785 ms) 64 1.000 R² (1.000 R² .. 1.000 R²) 65 mean 1.781 ms (1.780 ms .. 1.782 ms) 66 std dev 2.300 μs (1.939 μs .. 2.835 μs) 67 68 benchmarking ppad-bip32/xpub 69 time 901.1 μs (900.0 μs .. 902.3 μs) 70 1.000 R² (1.000 R² .. 1.000 R²) 71 mean 900.3 μs (899.7 μs .. 901.7 μs) 72 std dev 3.053 μs (1.724 μs .. 5.362 μs) 73 74 benchmarking ppad-bip32/xprv 75 time 8.665 μs (8.656 μs .. 8.673 μs) 76 1.000 R² (1.000 R² .. 1.000 R²) 77 mean 8.667 μs (8.663 μs .. 8.670 μs) 78 std dev 12.75 ns (9.805 ns .. 17.26 ns) 79 80 benchmarking ppad-bip32/parse 81 time 9.295 μs (9.273 μs .. 9.330 μs) 82 1.000 R² (1.000 R² .. 1.000 R²) 83 mean 9.294 μs (9.288 μs .. 9.308 μs) 84 std dev 27.58 ns (11.06 ns .. 55.76 ns) 85 ``` 86 87 ## Security 88 89 This library aims at the maximum security achievable in a 90 garbage-collected language under an optimizing compiler such as GHC, in 91 which strict constant-timeness can be [challenging to achieve][const]. 92 93 The implementation within passes the official [BIP32 test 94 vectors](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki#test-vectors), and all derivations involving secret keys execute 95 *algorithmically* in constant time -- see the "Security" notes in the 96 README of [ppad-secp256k1][secp] for more details. 97 98 If you discover any vulnerabilities, please disclose them via 99 security@ppad.tech. 100 101 ## Development 102 103 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a 104 development shell with: 105 106 ``` 107 $ nix develop 108 ``` 109 110 Then do e.g.: 111 112 ``` 113 $ cabal repl ppad-bip32 114 ``` 115 116 to get a REPL for the main library. 117 118 [nixos]: https://nixos.org/ 119 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html 120 [const]: https://www.chosenplaintext.ca/articles/beginners-guide-constant-time-cryptography.html 121 [secp]: https://git.ppad.tech/secp256k1