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.
• PushBytesErrorNeither 16-bit nor 32-bit
  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.