bech32

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

README.md (3635B)


      1 # bech32
      2 
      3 [![](https://img.shields.io/hackage/v/ppad-bech32?color=blue)](https://hackage.haskell.org/package/ppad-bech32)
      4 ![](https://img.shields.io/badge/license-MIT-brightgreen)
      5 [![](https://img.shields.io/badge/haddock-bech32-lightblue)](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