README.md (3436B)
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 M4 Silicon MacBook Air look like (use 51 `cabal bench` to run the benchmark suite): 52 53 ``` 54 benchmarking benchmarks/ppad-bech32/bech32 encode/120b 55 time 783.5 ns (781.4 ns .. 786.6 ns) 56 1.000 R² (1.000 R² .. 1.000 R²) 57 mean 791.1 ns (788.7 ns .. 793.5 ns) 58 std dev 8.193 ns (7.461 ns .. 8.973 ns) 59 60 benchmarking benchmarks/ppad-bech32/bech32 decode/120b 61 time 944.0 ns (943.1 ns .. 944.7 ns) 62 1.000 R² (1.000 R² .. 1.000 R²) 63 mean 942.4 ns (941.7 ns .. 943.1 ns) 64 std dev 2.197 ns (1.838 ns .. 2.669 ns) 65 66 benchmarking benchmarks/reference/bech32 encode/120b 67 time 1.282 μs (1.281 μs .. 1.283 μs) 68 1.000 R² (1.000 R² .. 1.000 R²) 69 mean 1.282 μs (1.282 μs .. 1.283 μs) 70 std dev 1.338 ns (996.0 ps .. 1.881 ns) 71 ``` 72 73 ## Security 74 75 This library aims at the maximum security achievable in a 76 garbage-collected language under an optimizing compiler such as GHC, in 77 which strict constant-timeness can be challenging to achieve. 78 79 If you discover any vulnerabilities, please disclose them via 80 security@ppad.tech. 81 82 ## Development 83 84 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a 85 development shell with: 86 87 ``` 88 $ nix develop 89 ``` 90 91 Then do e.g.: 92 93 ``` 94 $ cabal repl ppad-bech32 95 ``` 96 97 to get a REPL for the main library. 98 99 ## Attribution 100 101 The base32 implementation used internally is more or less a pure 102 translation of the [base32][bas32] package on Hackage. 103 104 [nixos]: https://nixos.org/ 105 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html 106 [bi173]: https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki 107 [bi350]: https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki 108 [bas32]: https://hackage.haskell.org/package/base32