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