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