README.md (3635B)
1 # bech32 2 3 [](https://hackage.haskell.org/package/ppad-bech32) 4  5 [](https://docs.ppad.tech/bech32) 6 7 A pure Haskell implementation of bech32m and bech32 encoding/decoding on 8 strict ByteStrings, as specified by [BIP350][bi350] and [BIP173][bi173]. 9 10 ## Usage 11 12 A sample GHCi session: 13 14 ``` 15 > :set -XOverloadedStrings 16 > 17 > -- import qualified 18 > import qualified Data.ByteString.Bech32m as Bech32m 19 > 20 > -- create a bech32m-encoded string using a human-readable part (HRP) 21 > -- and some input 22 > let Just bech32m = Bech32m.encode "bc" "a standard word8 bytestring" 23 > bech32m 24 "bc1vys8xarpdejxzunyypmk7uny8qsxy7t5v4ehgunfdenswyuz0e" 25 > 26 > -- verify that a bech32m string has a valid checksum 27 > Bech32m.verify bech32 28 True 29 > 30 > -- tweaked stuff will obviously fail to verify (s/m/w below) 31 > Bech32m.verify "bc1vys8xarpdejxzunyypwk7uny8qsxy7t5v4ehgunfdenswyuz0e" 32 False 33 > 34 > -- decode bech32m-encoded input 35 > Bech32m.decode bech32m 36 Just ("bc","a standard word8 bytestring") 37 ``` 38 39 ## Documentation 40 41 Haddocks (API documentation, etc.) are hosted at 42 [docs.ppad.tech/bech32](https://docs.ppad.tech/bech32). 43 44 ## Performance 45 46 The aim is best-in-class performance for pure, highly-auditable Haskell 47 code. At present we're a little over twice as fast as the official 48 BIP173 reference implementation. 49 50 Current benchmark figures on a relatively-beefy NixOS VPS look like (use 51 `cabal bench` to run the benchmark suite): 52 53 ``` 54 benchmarking benchmarks/ppad-bech32/bech32 encode/120b 55 time 1.126 μs (1.115 μs .. 1.136 μs) 56 0.999 R² (0.999 R² .. 1.000 R²) 57 mean 1.132 μs (1.125 μs .. 1.140 μs) 58 std dev 26.29 ns (21.47 ns .. 31.93 ns) 59 variance introduced by outliers: 29% (moderately inflated) 60 61 benchmarking benchmarks/ppad-bech32/bech32 decode/120b 62 time 1.293 μs (1.281 μs .. 1.308 μs) 63 0.999 R² (0.999 R² .. 1.000 R²) 64 mean 1.280 μs (1.274 μs .. 1.290 μs) 65 std dev 24.47 ns (18.39 ns .. 33.71 ns) 66 variance introduced by outliers: 21% (moderately inflated) 67 68 benchmarking benchmarks/reference/bech32 encode/120b 69 time 2.897 μs (2.865 μs .. 2.920 μs) 70 0.999 R² (0.999 R² .. 1.000 R²) 71 mean 2.828 μs (2.806 μs .. 2.856 μs) 72 std dev 81.33 ns (70.94 ns .. 97.46 ns) 73 variance introduced by outliers: 36% (moderately inflated) 74 ``` 75 76 ## Security 77 78 This library aims at the maximum security achievable in a 79 garbage-collected language under an optimizing compiler such as GHC, in 80 which strict constant-timeness can be challenging to achieve. 81 82 If you discover any vulnerabilities, please disclose them via 83 security@ppad.tech. 84 85 ## Development 86 87 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a 88 development shell with: 89 90 ``` 91 $ nix develop 92 ``` 93 94 Then do e.g.: 95 96 ``` 97 $ cabal repl ppad-bech32 98 ``` 99 100 to get a REPL for the main library. 101 102 ## Attribution 103 104 The base32 implementation used internally is more or less a pure 105 translation of the [base32][bas32] package on Hackage. 106 107 [nixos]: https://nixos.org/ 108 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html 109 [bi173]: https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki 110 [bi350]: https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki 111 [bas32]: https://hackage.haskell.org/package/base32