kustomzone/blockscript

Bit Script Playground

script

JavaScript implementation of Script, Bitcoin's scripting language, along with a Script Playground, deployed here. See my blog post for more.

The original ES6 source can be found on GitHub with the compiled ES5 output available for use as an npm package.

Usage

The npm package can be used to evaluate Bitcoin scripts as follows:

var evaluate = require('bitcoin-script').evaluate;
var script = 'OP_1 OP_VERIFY';
evaluate(script);
// => true

(Note: here, OP_VERIFY could be excluded, as default behavior is to check for a 1 on the top of the stack if there's no terminating command in the script.)

Alternatively, you can use the lock-unlock paradigm, which concatenates the scripts before evaluating:

var unlock = require('bitcoin-script').unlock;
var scriptSig = 'OP_1';
var scriptPubKey = 'OP_VERIFY';
unlock(scriptSig, scriptPubKey);
// => true

If you'd like to enable disabled commands, you can do so by passing true as the second argument to any of the exported functions. Here, we use the OP_MUL command, which is typically disabled:

var evaluate = require('bitcoin-script').evaluate;
var script = 'OP_2 OP_3 OP_MUL OP_6 OP_EQUAL OP_VERIFY';
evaluate(script, /* enableDisabled */ true);
// => true

Further examples and tests are available in the repo.

How It Works

Script programs are compiled to JavaScript using Jison, with behavior following the specification outlined on the Bitcoin Wiki.

The live editor is based off of Joel Burget's react-live-editor.

Functionality

(A longer explanation of Script and this implementation can be found in my blog post.)

Script is a stack-based programming language; that is, it operates by maintaining a stack onto/from which it pushes/pops as necessary. It is an intentionally simple language, containing if-statements, but no other control flow. The standard library includes functions for performing basic arithmetic and cryptographic operations, all of which can be found on the Wiki.

When the parser runs over a Script program, it returns an object of the following form:

{
    value: [value],
    code: [code]
}

This allows for inspection into the compiled code (e.g., for use in the live editor), as well as the return value (true or false) of the Script.

As a user, you should only be using the functions exported in index.js, which includes a parse function that returns this (value, code) pair.

Deviations From the Spec

Note that as this is an educational tool, the goal is not to create a full-fidelity re-implementation of Script, but rather, to focus on re-creating Script's core behavior. With that in mind, the implementation here differs from that described on the Wiki in a few ways. For example:

• Unlike in the official implementation, OP_CHECKMULTISIG does not pop an extra, arbitrary value off the stack (as this is considered a bug and would only serve to confuse new users).
• Signatures aren't generated by hashing transaction inputs and outputs (as the snippets only exist in isolation); instead, the protocol expects users to sign a simple nonce (in this case, the string 'Secure').
• Any hex data is pushed to the state with no limitations.

Live Editor

This repository also includes a live Script editor for use in the browser.

To build the live editor, run make from the live-editor directory, followed by python -m SimpleHTTPServer. Once running, you can head to localhost:8000/script-compiler.html. The live editor's build step will take care of ES6ifying and bundling for the browser.

Testing

Unit tests can be run with npm run test, which will execute the Jest test runner. Note that the cryptographic and primality-based tests can take a while (30+ seconds) to run.

License

MIT.