README.md (3016B)
1 # ppad-base58 2 3 A pure Haskell implementation of base58 and base58check encoding & 4 decoding on strict ByteStrings. 5 6 ## Usage 7 8 A sample GHCi session: 9 10 ``` 11 > :set -XOverloadedStrings 12 > 13 > -- import qualified 14 > import qualified Data.ByteString.Base58 as B58 15 > import qualified Data.ByteString.Base58Check as B58Check 16 > 17 > -- simple base58 encoding and decoding 18 > let b58 = B58.encode "hello world" 19 > b58 20 "StV1DL6CwTryKyV" 21 > 22 > B58.decode b58 23 Just "hello world" 24 > 25 > -- base58check is a versioned, checksummed format 26 > let b58check = B58Check.encode 0x00 "hello world" 27 > b58check 28 "13vQB7B6MrGQZaxCqW9KER" 29 > 30 > B58Check.decodeb58check 31 Just (0,"hello world") 32 ``` 33 34 ## Documentation 35 36 Haddocks (API documentation, etc.) are hosted at 37 [docs.ppad.tech/base58](https://docs.ppad.tech/base58). 38 39 ## Performance 40 41 The aim is best-in-class performance for pure, highly-auditable Haskell 42 code. 43 44 Current benchmark figures on my mid-2020 MacBook Air look like (use 45 `cabal bench` to run the benchmark suite): 46 47 ``` 48 benchmarking ppad-base32/base58/encode/hello world 49 time 667.4 ns (661.2 ns .. 674.5 ns) 50 0.999 R² (0.999 R² .. 1.000 R²) 51 mean 673.5 ns (669.5 ns .. 678.8 ns) 52 std dev 15.91 ns (13.00 ns .. 21.13 ns) 53 54 benchmarking ppad-base32/base58/decode/StV1DL6CwTryKyV 55 time 741.2 ns (731.5 ns .. 752.5 ns) 56 0.999 R² (0.998 R² .. 0.999 R²) 57 mean 748.3 ns (741.8 ns .. 757.2 ns) 58 std dev 24.98 ns (20.60 ns .. 31.28 ns) 59 60 benchmarking ppad-base32/base58check/encode/0x00, hello world 61 time 5.411 μs (5.349 μs .. 5.472 μs) 62 0.999 R² (0.999 R² .. 1.000 R²) 63 mean 5.389 μs (5.352 μs .. 5.439 μs) 64 std dev 142.5 ns (119.5 ns .. 184.4 ns) 65 66 benchmarking ppad-base32/base58check/decode/13vQB7B6MrGQZaxCqW9KER 67 time 5.825 μs (5.722 μs .. 5.930 μs) 68 0.998 R² (0.997 R² .. 0.999 R²) 69 mean 5.718 μs (5.655 μs .. 5.792 μs) 70 std dev 228.0 ns (190.7 ns .. 275.4 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-base58 95 ``` 96 97 to get a REPL for the main library. 98 99 ## Attribution 100 101 The vectors used in the test suite for both base58 102 and base58check are verbatim from paulmillr's 103 [scure-base](https://github.com/paulmillr/scure-base) library. 104 105 [nixos]: https://nixos.org/ 106 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html