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 (3436B)


      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 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