Module script

Bitcoin scripts.

See also the Script type.

This module provides the structures and functions needed to support scripts.

What is Bitcoin script

Scripts define Bitcoin’s digital signature scheme: a signature is formed from a script (the second half of which is defined by a coin to be spent, and the first half provided by the spending transaction), and is valid iff the script leaves TRUE on the stack after being evaluated. Bitcoin’s script is a stack-based assembly language similar in spirit to Forth.

Script is represented as a sequence of bytes on the wire, each byte representing an operation, or data to be pushed on the stack.

See Bitcoin Wiki: Script for more information.

In this library we chose to keep the byte representation in memory and decode opcodes only when processing the script. This is similar to Rust choosing to represent strings as UTF-8-encoded bytes rather than slice of chars. In both cases the individual items can have different sizes and forcing them to be larger would waste memory and, in case of Bitcoin script, even some performance (forcing allocations).

Script vs ScriptBuf vs Builder

These are the most important types in this module and they are quite similar, so it may seem confusing what the differences are. Script is an unsized type much like str or Path are and ScriptBuf is an owned counterpart to Script just like String is an owned counterpart to str.

However it is common to construct an owned script and then pass it around. For this case a builder API is more convenient. To support this we provide Builder type which is very similar to ScriptBuf but its methods take self instead of &mut self and return Self. It also contains a cache that may make some modifications faster. This cache is usually not needed outside of creating the script.

At the time of writing there’s only one operation using the cache - push_verify, so the cache is minimal but we may extend it in the future if needed.

Modules

witness_program

The segregated witness program as defined by BIP141.

witness_version

The segregated witness version byte as defined by BIP141.

Structs

Builder

An Object which can be used to construct a script piece by piece.

Bytes

Iterator over bytes of a script

InstructionIndices

Iterator over script instructions with their positions.

Instructions

Iterator over a script returning parsed opcodes.

PushBytes

Byte slices that can be in Bitcoin script.

PushBytesBuf

Owned, growable counterpart to PushBytes.

PushBytesError

Error returned on attempt to create too large PushBytes.

Script

Bitcoin script slice.

ScriptBuf

An owned, growable script.

ScriptHash

A hash of Bitcoin Script bytecode.

WScriptHash

SegWit version of a Bitcoin Script bytecode hash.

Enums

Error

Ways that a script might fail. Not everything is split up as much as it could be; patches welcome if more detailed errors would help you.

Instruction

A “parsed opcode” which allows iterating over a Script in a more sensible way.

Traits

PushBytesErrorReport

Reports information about failed conversion into PushBytes.

Functions

read_scriptbool

Decodes a boolean.

read_scriptint

Decodes an integer in script(minimal CScriptNum) format.

read_scriptint_non_minimal

Decodes an integer in script format without non-minimal error.

write_scriptint

Encodes an integer in script(minimal CScriptNum) format.