BitcoinPrimitives.jl Documentation

The raw transaction format and several peer-to-peer network messages use a type of variable-length integer to indicate the number of bytes in a following piece of data. Bitcoin Core code refers to these variable length integers as compactSize. Many other documents refer to them as var_int or varInt, but this risks conflation with other variable-length integer encodings—such as the CVarInt class used in Bitcoin Core for serializing data to disk. Because it’s used in the transaction format, the format of compactSize unsigned integers is part of the consensus rules. For numbers from 0 to 252, compactSize unsigned integers look like regular unsigned integers. For other numbers up to 0xffffffffffffffff, a byte is prefixed to the number to indicate its length—but otherwise the numbers look like regular unsigned integers in little-endian order.

For example, the number 515 is encoded as 0xfd0302.

Outpoint

Because a single transaction can include multiple outputs, the Outpoint structure includes both a TXID (or txid) and an output index number to refer to specific output.

• txid, the TXID of the transaction holding the output to spend. The TXID is a hash provided here in internal byte order.
• index, the output index number of the specific output to spend from the transaction. The first output is 0x00000000.

TxIn

Each non-coinbase input spends an outpoint from a previous transaction. A TxIn is composed of

• prevout::Outpoint, The previous outpoint being spent
• scriptsig::Vector{UInt8}, which satisfies the conditions placed in

the outpoint’s pubkey script. Should only contain data pushes

• sequence::UInt32 number. Default for Bitcoin Core and almost all other

programs is 0xffffffff

TxOut

Each output spends a certain number of satoshis, placing them under control of anyone who can satisfy the provided pubkey script. A TxOut is composed of

• value::UInt64, number of satoshis to spend. May be zero; the sum of all

outputs may not exceed the sum of satoshis previously spent to the outpoints provided in the input section. (Exception: coinbase transactions spend the block subsidy and collected transaction fees.)

• scriptpubkey::Script which defines the conditions which must be

satisfied to spend this output.

Bitcoin transactions are broadcast between peers in a serialized byte format, called raw format. It is this form of a transaction which is SHA256(SHA256()) hashed to create the TXID and, ultimately, the merkle root of a block containing the transaction—making the transaction format part of the consensus rules.

A raw transaction has the following top-level format:

• Transaction version number; currently version 1 or 2. Programs creating

transactions using newer consensus rules may use higher version numbers. Version 2 means that BIP 68 applies.

• A marker which MUST be a 1-byte zero value: 0x00 (BIP 141)
• A flag which MUST be a 1-byte non-zero value: 0x01 (BIP 141)
• Transaction inputs
• Transaction outputs
• A time (Unix epoch time) or block number (BIP 68)

A transaction may have multiple inputs and outputs, so the TxIn and TxOut structures may recur within a transaction.

Block

Data Structure representing a Block in the Bitcoin blockchain.

Consists of a block.header::Header and block.transactions::Vector{Tx}.

Header

Data Structure representing the Header of a Block in the Bitcoin blockchain.

Data are store as an NTuple{80, UInt8} without parsinf per se. The elements of the Header can be accessed by header.element.

header.version
header.prevhash
header.merkleroot
header.time
header.bits
header.nonce

Script

Script data type has a single data field, stored as Vector{Vector{UInt8}} in which each inner Vector{UInt8} represent a stack item. It represents either a PubKey or Signature script.

A script included in outputs which sets the conditions that must be fulfilled for those satoshis to be spent. Data for fulfilling the conditions can be provided in a signature script. Pubkey Scripts are called a scriptPubKey in code.

Data generated by a spender which is almost always used as variables to satisfy a pubkey script. Signature Scripts are called scriptSig in code.

Witness

Witness data type has a single data field, stored as Vector{Vector{UInt8}} in which each inner Vector{UInt8} represent a stack item.

The Witness is a serialization of all witness data of the transaction. Each TxIn is associated with a witness field. A witness field starts with a CompactSizeUInt to indicate the number of stack items for the TxIn. It is followed by stack items, with each item starts with a CompactSizeUInt to indicate the length. Witness data is NOT script.

A non-witness program TxIn MUST be associated with an empty witness field, represented by a 0x00. If all TxIns are not witness program, a transaction's wtxid is equal to its txid.

read(io::IOBuffer)::CompactSizeUInt

Returns a CompactSizeUInt from an IO stream

Outpoint(io::IOBuffer) -> Outpoint

Parse an Outpoint from an IOBuffer

Script(::IOBuffer) -> Script

Parse a Script from an IOBuffer

script(::Vector{UInt8}; type::Symbol=:P2WSH) -> Script

Returns a Script of set type for given hash.

• type can be :P2PKH, :P2SH, :P2WPKH or :P2WSH
• hash must be 32 bytes long for P2WSH script, 20 for the others

Witness(io::IO) -> Witness

Parse Witness from an IOBuffer

TxIn(io::IOBuffer) -> TxIn

Parse an IOBuffer to a TxIn

TxOut(io::IOBuffer)

Parse an IOBuffer to a TxOut

Tx(io::IOBuffer) -> Tx

Parse an IOBuffer to a Tx

Block(io::IOBuffer) -> Block

Parse a Block from an IOBuffer

Header(x::IO) -> Header

Parse Header from an IO

serialize(n::CompactSizeUInt) -> Vector{UInt8}

Returns the bytes serialization of a CompactSizeUInt

serialize(prevout::Outpoint) -> Vector{UInt8}

Returns the byte serialization of the outpoint

serialize(s::Script) -> Vector{UInt8}

Serialize a Script to a Vector{UInt8}

serialize(program::Witness) -> Vector{UInt8}

Serialize a Witness data type starting with a CompactSizeUInt to indicate the number of stack items for the TxIn. It is followed by stack items, with each item starts with a CompactSizeUInt to indicate the length.

serialize(tx::TxIn) -> Vector{UInt8}

Returns the byte serialization of the transaction input

serialize(tx::TxOut) -> Vector{UInt8}

Returns the byte serialization of the transaction output

serialize(tx::Tx; force_legacy::Bool=false) -> Vector{UInt8}

Returns the byte serialization of the transaction, force_legacy can optionally be set to true to serialize SegWit's (BIP 141) transaction as if they were legacy transaction to allow proper txid computation.

serialize(block::Header) -> Vector{UInt8}

Serialize a Block

iscoinbase(tx::Tx) -> Bool

Returns whether this transaction is a coinbase transaction or not

coinbase_height(tx::Tx) ->

Returns the height of the block this coinbase transaction is in Returns an AssertionError if tx isn't a coinbase transaction

script(::Vector{UInt8}; type::Symbol=:P2WSH) -> Script

Returns a Script of set type for given hash.

• type can be :P2PKH, :P2SH, :P2WPKH or :P2WSH
• hash must be 32 bytes long for P2WSH script, 20 for the others

type(script::Script) -> Symbol

Return type of Script : :P2PKH, :P2SH, :P2WPKH or :P2WSH

hash256(x::Block) -> Vector{UInt8}
hash256(x::Header) -> Vector{UInt8}
hash256(x::Tx) -> Vector{UInt8}

Returns the reversed double sha256 of a Block, Header, or Tx serialization. Tx is always serialized as a legacy transaction.

hash256(block)
hash256(header)
hash256(transaction)