README.md (3759B)
1 # ppad-script 2 3 Representations for [Script](https://en.bitcoin.it/wiki/Script), 4 including abstract syntax, 'ByteArray', and base16-encoded 'ByteString' 5 versions, as well as fast conversion utilities for working with them. 6 7 ## Usage 8 9 A sample GHCi session: 10 11 ``` 12 > :set -XOverloadedStrings 13 > 14 > -- import qualified 15 > import qualified Bitcoin.Prim.Script as S 16 > 17 > -- base16-encoded p2pkh scriptPubKey 18 > let p2pkh = "76a91489abcdefabbaabbaabbaabbaabbaabbaabbaabba88ac" 19 > 20 > -- bytearray-encoded 21 > let Just script = S.from_base16 p2pkh 22 > script 23 Script [ 0x76, 0xa9, 0x14, 0x89, 0xab, 0xcd, 0xef 24 , 0xab, 0xba, 0xab, 0xba, 0xab, 0xba, 0xab 25 , 0xba, 0xab, 0xba, 0xab, 0xba, 0xab, 0xba 26 , 0xab, 0xba, 0x88, 0xac 27 ] 28 > 29 > -- abstract syntax-encoded 30 > let terms = S.from_script script 31 > terms 32 [ OP_DUP, OP_HASH160, OP_PUSHBYTES_20, 0x89, 0xab, 0xcd, 0xef 33 , 0xab, 0xba, 0xab, 0xba, 0xab, 0xba, 0xab 34 , 0xba, 0xab, 0xba, 0xab, 0xba, 0xab, 0xba 35 , 0xab, 0xba, OP_EQUALVERIFY, OP_CHECKSIG 36 ] 37 > 38 > -- round-trip 39 > S.to_base16 (S.to_script terms) 40 "76a91489abcdefabbaabbaabbaabbaabbaabbaabbaabba88ac" 41 ``` 42 43 ## Documentation 44 45 Haddocks (API documentation, etc.) are hosted at 46 [docs.ppad.tech/script](https://docs.ppad.tech/script). 47 48 ## Performance 49 50 The aim is best-in-class performance for highly-auditable Haskell code. 51 52 Current benchmark figures on my mid-2020 MacBook Air look like (use 53 `cabal bench` to run the benchmark suite): 54 55 ``` 56 benchmarking to_script 57 time 484.9 ns (478.3 ns .. 491.4 ns) 58 0.998 R² (0.997 R² .. 0.999 R²) 59 mean 496.2 ns (485.8 ns .. 508.1 ns) 60 std dev 37.17 ns (30.08 ns .. 49.95 ns) 61 variance introduced by outliers: 83% (severely inflated) 62 63 benchmarking from_script 64 time 380.8 ns (374.3 ns .. 387.5 ns) 65 0.998 R² (0.996 R² .. 0.999 R²) 66 mean 383.0 ns (375.3 ns .. 395.4 ns) 67 std dev 31.88 ns (22.41 ns .. 43.86 ns) 68 variance introduced by outliers: 86% (severely inflated) 69 70 benchmarking to_base16 71 time 291.3 ns (285.6 ns .. 297.9 ns) 72 0.996 R² (0.995 R² .. 0.998 R²) 73 mean 298.3 ns (291.8 ns .. 308.1 ns) 74 std dev 26.38 ns (21.25 ns .. 34.27 ns) 75 variance introduced by outliers: 87% (severely inflated) 76 77 benchmarking from_base16 78 time 439.1 ns (429.9 ns .. 448.2 ns) 79 0.997 R² (0.996 R² .. 0.998 R²) 80 mean 437.9 ns (429.9 ns .. 450.0 ns) 81 std dev 32.67 ns (26.12 ns .. 44.04 ns) 82 variance introduced by outliers: 83% (severely inflated) 83 ``` 84 85 where the inputs to the above functions are variations of the script found 86 in the 'Usage' section. 87 88 ## Security 89 90 This library aims at the maximum security achievable in a 91 garbage-collected language under an optimizing compiler such as GHC, in 92 which strict constant-timeness can be challenging to achieve. 93 94 This is an early-development, pre-production-ready release, and is not 95 **not** yet suitable for mainnet use. 96 97 If you discover any vulnerabilities, please disclose them via 98 security@ppad.tech. 99 100 ## Development 101 102 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a 103 development shell with: 104 105 ``` 106 $ nix develop 107 ``` 108 109 Then do e.g.: 110 111 ``` 112 $ cabal repl ppad-script 113 ``` 114 115 to get a REPL for the main library. 116 117 ## Attribution 118 119 The list of opcodes was originally taken 120 verbatim from the 'opcode' crate found in 121 [rust-bitcoin](https://github.com/rust-bitcoin/rust-bitcoin). 122 123 [nixos]: https://nixos.org/ 124 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html