bech32

Pure Haskell bech32, bech32m encodings (docs.ppad.tech/bech32).
git clone git://git.ppad.tech/bech32.git
Log | Files | Refs | README | LICENSE

README.md (3062B)

      1 # ppad-bech32
      2 
      3 A pure Haskell implementation of the bech32m and bech32 encodings on
      4 strict ByteStrings, as specified by [BIP350][bi350] and [BIP173][bi173].
      5 
      6 ## Usage
      7 
      8 A sample GHCi session:
      9 
     10 ```
     11   > :set -XOverloadedStrings
     12   >
     13   > -- import qualified
     14   > import qualified Data.ByteString.Bech32m as Bech32m
     15   >
     16   > -- create a bech32m-encoded string using a human-readable part (HRP)
     17   > -- and some input
     18   > let Just bech32m = Bech32m.encode "bc" "a standard word8 bytestring"
     19   > bech32m
     20   "bc1vys8xarpdejxzunyypmk7uny8qsxy7t5v4ehgunfdenswyuz0e"
     21   >
     22   > -- verify that a bech32m string has a valid checksum
     23   > Bech32m.verify bech32
     24   True
     25   >
     26   > -- tweaked stuff will obviously fail to verify (s/m/w below)
     27   > Bech32m.verify "bc1vys8xarpdejxzunyypwk7uny8qsxy7t5v4ehgunfdenswyuz0e"
     28   False
     29 ```
     30 
     31 ## Documentation
     32 
     33 Haddocks (API documentation, etc.) are hosted at
     34 [docs.ppad.tech/bech32](https://docs.ppad.tech/bech32).
     35 
     36 ## Performance
     37 
     38 The aim is best-in-class performance for pure, highly-auditable Haskell
     39 code. At present we're slightly faster than the official BIP173
     40 reference implementation.
     41 
     42 Current benchmark figures on my mid-2020 MacBook Air look like (use
     43 `cabal bench` to run the benchmark suite):
     44 
     45 ```
     46   benchmarking ppad-bech32/bech32 encode/120b
     47   time                 1.230 μs   (1.204 μs .. 1.255 μs)
     48                        0.998 R²   (0.996 R² .. 0.999 R²)
     49   mean                 1.209 μs   (1.194 μs .. 1.224 μs)
     50   std dev              51.37 ns   (42.90 ns .. 64.59 ns)
     51 
     52   benchmarking ppad-bech32/bech32 encode/128b (non 40-bit multiple length)
     53   time                 1.335 μs   (1.312 μs .. 1.354 μs)
     54                        0.997 R²   (0.995 R² .. 0.998 R²)
     55   mean                 1.343 μs   (1.318 μs .. 1.386 μs)
     56   std dev              101.4 ns   (72.87 ns .. 161.6 ns)
     57 
     58   benchmarking ppad-bech32/bech32 encode/240b
     59   time                 1.851 μs   (1.822 μs .. 1.879 μs)
     60                        0.999 R²   (0.998 R² .. 0.999 R²)
     61   mean                 1.848 μs   (1.825 μs .. 1.872 μs)
     62   std dev              77.27 ns   (63.06 ns .. 94.54 ns)
     63 ```
     64 
     65 ## Security
     66 
     67 This library aims at the maximum security achievable in a
     68 garbage-collected language under an optimizing compiler such as GHC, in
     69 which strict constant-timeness can be challenging to achieve.
     70 
     71 If you discover any vulnerabilities, please disclose them via
     72 security@ppad.tech.
     73 
     74 ## Development
     75 
     76 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a
     77 development shell with:
     78 
     79 ```
     80 $ nix develop
     81 ```
     82 
     83 Then do e.g.:
     84 
     85 ```
     86 $ cabal repl ppad-bech32
     87 ```
     88 
     89 to get a REPL for the main library.
     90 
     91 ## Attribution
     92 
     93 The base32 implementation used internally is more or less a pure
     94 translation of the [base32][bas32] package on Hackage.
     95 
     96 [nixos]: https://nixos.org/
     97 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html
     98 [bi173]: https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki
     99 [bi350]: https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki
    100 [bas32]: https://hackage.haskell.org/package/base32