script

Representations and fast conversions for Script (docs.ppad.tech/script).
git clone git://git.ppad.tech/script.git
Log | Files | Refs | README | LICENSE

README.md (3907B)


      1 # script
      2 
      3 [![](https://img.shields.io/hackage/v/ppad-script?color=blue)](https://hackage.haskell.org/package/ppad-script)
      4 ![](https://img.shields.io/badge/license-MIT-brightgreen)
      5 [![](https://img.shields.io/badge/haddock-script-lightblue)](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