bech32

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

README.md (3060B)

      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 fast 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.
     47 
     48 Current benchmark figures on a M4 Silicon MacBook Air look like (use
     49 `cabal bench` to run the benchmark suite):
     50 
     51 ```
     52   benchmarking benchmarks/ppad-bech32/bech32 encode/120b
     53   time                 240.8 ns   (238.1 ns .. 243.3 ns)
     54                        0.999 R²   (0.999 R² .. 1.000 R²)
     55   mean                 240.3 ns   (238.7 ns .. 242.4 ns)
     56   std dev              6.035 ns   (5.059 ns .. 7.607 ns)
     57   variance introduced by outliers: 36% (moderately inflated)
     58 
     59   benchmarking benchmarks/ppad-bech32/bech32 decode/120b
     60   time                 257.5 ns   (256.0 ns .. 259.7 ns)
     61                        0.999 R²   (0.999 R² .. 1.000 R²)
     62   mean                 262.3 ns   (260.5 ns .. 264.5 ns)
     63   std dev              6.611 ns   (5.482 ns .. 8.776 ns)
     64   variance introduced by outliers: 36% (moderately inflated)
     65 ```
     66 
     67 You should compile with the 'llvm' flag for maximum performance.
     68 
     69 ## Security
     70 
     71 This library aims at the maximum security achievable in a
     72 garbage-collected language under an optimizing compiler such as GHC, in
     73 which strict constant-timeness can be challenging to achieve.
     74 
     75 If you discover any vulnerabilities, please disclose them via
     76 security@ppad.tech.
     77 
     78 ## Development
     79 
     80 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a
     81 development shell with:
     82 
     83 ```
     84 $ nix develop
     85 ```
     86 
     87 Then do e.g.:
     88 
     89 ```
     90 $ cabal repl ppad-bech32
     91 ```
     92 
     93 to get a REPL for the main library.
     94 
     95 [nixos]: https://nixos.org/
     96 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html
     97 [bi173]: https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki
     98 [bi350]: https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki
     99 [bas32]: https://hackage.haskell.org/package/base32