bitcoin.core

Everything consensus critical is found in the core subpackage.

core

bitcoin.core.Hash(msg)

SHA256^2)(msg) -> bytes

bitcoin.core.Hash160(msg)

RIPEME160(SHA256(msg)) -> bytes

bitcoin.core.MoneyRange(nValue, params=None)

bitcoin.core.x(h)

Convert a hex string to bytes

bitcoin.core.b2x(b)

Convert bytes to a hex string

bitcoin.core.lx(h)

Convert a little-endian hex string to bytes

Lets you write uint256’s and uint160’s the way the Satoshi codebase shows them.

bitcoin.core.b2lx(b)

Convert bytes to a little-endian hex string

Lets you show uint256’s and uint160’s the way the Satoshi codebase shows them.

bitcoin.core.str_money_value(value)

Convert an integer money value to a fixed point string

exception bitcoin.core.ValidationError

Bases: exceptions.Exception

Base class for all blockchain validation errors

Everything that is related to validating the blockchain, blocks, transactions, scripts, etc. is derived from this class.

class bitcoin.core.COutPoint(hash='x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00', n=4294967295)

Bases: bitcoin.core.serialize.ImmutableSerializable

The combination of a transaction hash and an index n into its vout

classmethod from_outpoint(outpoint)

Create an immutable copy of an existing OutPoint

If outpoint is already immutable (outpoint.__class__ is COutPoint) it is returned directly.

hash

is_null()

n

classmethod stream_deserialize(f)

stream_serialize(f)

class bitcoin.core.CMutableOutPoint(hash='x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00', n=4294967295)

Bases: bitcoin.core.COutPoint

A mutable COutPoint

GetHash()

Return the hash of the serialized object

classmethod from_outpoint(outpoint)

Create a mutable copy of an existing COutPoint

class bitcoin.core.CTxIn(prevout=COutPoint(), scriptSig=CScript([]), nSequence=4294967295)

Bases: bitcoin.core.serialize.ImmutableSerializable

An input of a transaction

Contains the location of the previous transaction’s output that it claims, and a signature that matches the output’s public key.

classmethod from_txin(txin)

Create an immutable copy of an existing TxIn

If txin is already immutable (txin.__class__ is CTxIn) it is returned directly.

is_final()

nSequence

prevout

scriptSig

classmethod stream_deserialize(f)

stream_serialize(f)

class bitcoin.core.CMutableTxIn(prevout=None, scriptSig=CScript([]), nSequence=4294967295)

Bases: bitcoin.core.CTxIn

A mutable CTxIn

GetHash()

Return the hash of the serialized object

classmethod from_txin(txin)

Create a fully mutable copy of an existing TxIn

class bitcoin.core.CTxOut(nValue=-1, scriptPubKey=CScript([]))

Bases: bitcoin.core.serialize.ImmutableSerializable

An output of a transaction

Contains the public key that the next input must be able to sign with to claim it.

classmethod from_txout(txout)

Create an immutable copy of an existing TxOut

If txout is already immutable (txout.__class__ is CTxOut) then it will be returned directly.

is_valid()

nValue

scriptPubKey

classmethod stream_deserialize(f)

stream_serialize(f)

class bitcoin.core.CMutableTxOut(nValue=-1, scriptPubKey=CScript([]))

Bases: bitcoin.core.CTxOut

A mutable CTxOut

GetHash()

Return the hash of the serialized object

classmethod from_txout(txout)

Create a fullly mutable copy of an existing TxOut

class bitcoin.core.CTransaction(vin=(), vout=(), nLockTime=0, nVersion=1, witness=CTxWitness())

Bases: bitcoin.core.serialize.ImmutableSerializable

A transaction

Create a new transaction

vin and vout are iterables of transaction inputs and outputs respectively. If their contents are not already immutable, immutable copies will be made.

GetTxid()

Get the transaction ID. This differs from the transactions hash as given by GetHash. GetTxid excludes witness data, while GetHash includes it.

classmethod from_tx(tx)

Create an immutable copy of a pre-existing transaction

If tx is already immutable (tx.__class__ is CTransaction) then it will be returned directly.

has_witness()

True if witness

is_coinbase()

nLockTime

nVersion

classmethod stream_deserialize(f)

Deserialize transaction

This implementation corresponds to Bitcoin’s SerializeTransaction() and consensus behavior. Note that Bitcoin’s DecodeHexTx() also has the option to attempt deserializing as a non-witness transaction first, falling back to the consensus behavior if it fails. The difference lies in transactions which have zero inputs: they are invalid but may be (de)serialized anyway for the purpose of signing them and adding inputs. If the behavior of DecodeHexTx() is needed it could be added, but not here.

stream_serialize(f, include_witness=True)

vin

vout

wit

class bitcoin.core.CMutableTransaction(vin=None, vout=None, nLockTime=0, nVersion=1, witness=None)

Bases: bitcoin.core.CTransaction

A mutable transaction

GetHash()

Return the hash of the serialized object

classmethod from_tx(tx)

Create a fully mutable copy of a pre-existing transaction

class bitcoin.core.CTxWitness(vtxinwit=())

Bases: bitcoin.core.serialize.ImmutableSerializable

Witness data for all inputs to a transaction

classmethod from_txwitness(txwitness)

Create an immutable copy of an existing TxWitness

If txwitness is already immutable (txwitness.__class__ is CTxWitness) it is returned directly.

is_null()

stream_deserialize(f)

stream_serialize(f)

vtxinwit

class bitcoin.core.CTxInWitness(scriptWitness=CScriptWitness())

Bases: bitcoin.core.serialize.ImmutableSerializable

Witness data for a single transaction input

classmethod from_txinwitness(txinwitness)

Create an immutable copy of an existing TxInWitness

If txin is already immutable (txin.__class__ is CTxIn) it is returned directly.

is_null()

scriptWitness

classmethod stream_deserialize(f)

stream_serialize(f)

class bitcoin.core.CBlockHeader(nVersion=2, hashPrevBlock='x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00', hashMerkleRoot='x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00', nTime=0, nBits=0, nNonce=0)

Bases: bitcoin.core.serialize.ImmutableSerializable

A block header

static calc_difficulty(nBits)

Calculate difficulty from nBits target

difficulty

hashMerkleRoot

hashPrevBlock

nBits

nNonce

nTime

nVersion

classmethod stream_deserialize(f)

stream_serialize(f)

class bitcoin.core.CBlock(nVersion=2, hashPrevBlock='x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00', hashMerkleRoot='x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00', nTime=0, nBits=0, nNonce=0, vtx=())

Bases: bitcoin.core.CBlockHeader

A block including all transactions in it

Create a new block

GetHash()

Return the block hash

Note that this is the hash of the header, not the entire serialized block.

GetWeight()

Return the block weight: (stripped_size * 3) + total_size

static build_merkle_tree_from_txids(txids)

Build a full CBlock merkle tree from txids

txids - iterable of txids

Returns a new merkle tree in deepest first order. The last element is the merkle root.

WARNING! If you’re reading this because you’re learning about crypto and/or designing a new system that will use merkle trees, keep in mind that the following merkle tree algorithm has a serious flaw related to duplicate txids, resulting in a vulnerability. (CVE-2012-2459) Bitcoin has since worked around the flaw, but for new applications you should use something different; don’t just copy-and-paste this code without understanding the problem first.

static build_merkle_tree_from_txs(txs)

Build a full merkle tree from transactions

static build_witness_merkle_tree_from_txs(txs)

Calculate the witness merkle tree from transactions

calc_merkle_root()

Calculate the merkle root

The calculated merkle root is not cached; every invocation re-calculates it from scratch.

calc_witness_merkle_root()

Calculate the witness merkle root

The calculated merkle root is not cached; every invocation re-calculates it from scratch.

get_header()

Return the block header

Returned header is a new object.

get_witness_commitment_index()

Find txout # of witness commitment in coinbase

Return None or an index

classmethod stream_deserialize(f)

stream_serialize(f, include_witness=True)

vMerkleTree

vWitnessMerkleTree

vtx

class bitcoin.core.CoreChainParams

Bases: object

Define consensus-critical parameters of a given instance of the Bitcoin system

GENESIS_BLOCK = None

MAX_MONEY = None

NAME = None

PROOF_OF_WORK_LIMIT = None

SUBSIDY_HALVING_INTERVAL = None

class bitcoin.core.CoreMainParams

Bases: bitcoin.core.CoreChainParams

GENESIS_BLOCK = CBlock(1, lx(0000000000000000000000000000000000000000000000000000000000000000), lx(4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b), 1231006505, 0x1d00ffff, 0x7c2bac1d)

MAX_MONEY = 2100000000000000

NAME = 'mainnet'

PROOF_OF_WORK_LIMIT = 26959946667150639794667015087019630673637144422540572481103610249215L

SUBSIDY_HALVING_INTERVAL = 210000

class bitcoin.core.CoreTestNetParams

Bases: bitcoin.core.CoreMainParams

GENESIS_BLOCK = CBlock(1, lx(0000000000000000000000000000000000000000000000000000000000000000), lx(4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b), 1296688602, 0x1d00ffff, 0x18aea41a)

NAME = 'testnet'

class bitcoin.core.CoreRegTestParams

Bases: bitcoin.core.CoreTestNetParams

GENESIS_BLOCK = CBlock(1, lx(0000000000000000000000000000000000000000000000000000000000000000), lx(4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b), 1296688602, 0x207fffff, 0x00000002)

NAME = 'regtest'

PROOF_OF_WORK_LIMIT = 57896044618658097711785492504343953926634992332820282019728792003956564819967L

SUBSIDY_HALVING_INTERVAL = 150

exception bitcoin.core.CheckTransactionError

Bases: bitcoin.core.ValidationError

bitcoin.core.CheckTransaction(tx)

Basic transaction checks that don’t depend on any context.

Raises CheckTransactionError

exception bitcoin.core.CheckBlockHeaderError

Bases: bitcoin.core.ValidationError

exception bitcoin.core.CheckProofOfWorkError

Bases: bitcoin.core.CheckBlockHeaderError

bitcoin.core.CheckProofOfWork(hash, nBits)

Check a proof-of-work

Raises CheckProofOfWorkError

bitcoin.core.CheckBlockHeader(block_header, fCheckPoW=True, cur_time=None)

Context independent CBlockHeader checks.

fCheckPoW - Check proof-of-work.

cur_time - Current time. Defaults to time.time()

Raises CBlockHeaderError if block header is invalid.

exception bitcoin.core.CheckBlockError

Bases: bitcoin.core.CheckBlockHeaderError

bitcoin.core.GetLegacySigOpCount(tx)

bitcoin.core.CheckBlock(block, fCheckPoW=True, fCheckMerkleRoot=True, cur_time=None)

Context independent CBlock checks.

CheckBlockHeader() is called first, which may raise a CheckBlockHeader exception, followed the block tests. CheckTransaction() is called for every transaction.

fCheckPoW - Check proof-of-work.

fCheckMerkleRoot - Check merkle root and witness merkle root matches transactions.

• Check witness commitment in coinbase

cur_time - Current time. Defaults to time.time()

key

ECC secp256k1 crypto routines

WARNING: This module does not mlock() secrets; your private keys may end up on disk in swap! Use with caution!

class bitcoin.core.key.CECKey

Wrapper around OpenSSL’s EC_KEY

POINT_CONVERSION_COMPRESSED = 2

POINT_CONVERSION_UNCOMPRESSED = 4

get_ecdh_key(other_pubkey, kdf=<function <lambda>>)

get_privkey()

get_pubkey()

get_raw_ecdh_key(other_pubkey)

recover(sigR, sigS, msg, msglen, recid, check)

Perform ECDSA key recovery (see SEC1 4.1.6) for curves over (mod p)-fields

recid selects which key is recovered

if check is non-zero, additional checks are performed

set_compressed(compressed)

set_privkey(key)

set_pubkey(key)

set_secretbytes(secret)

sign(hash)

sign_compact(hash)

signature_to_low_s(sig)

verify(hash, sig)

Verify a DER signature

class bitcoin.core.key.CPubKey

Bases: str

An encapsulated public key

Attributes:

is_valid - Corresponds to CPubKey.IsValid()

is_fullyvalid - Corresponds to CPubKey.IsFullyValid()

is_compressed - Corresponds to CPubKey.IsCompressed()

is_compressed

is_valid

classmethod recover_compact(hash, sig)

Recover a public key from a compact signature.

verify(hash, sig)

script

Scripts

Functionality to build scripts, as well as SignatureHash(). Script evaluation is in bitcoin.core.scripteval

class bitcoin.core.script.CScriptOp

Bases: int

A single script opcode

decode_op_n()

Decode a small integer opcode, returning an integer

static encode_op_n(n)

Encode a small integer op, returning an opcode

static encode_op_pushdata(d)

Encode a PUSHDATA op, returning bytes

is_small_int()

Return true if the op pushes a small integer to the stack

exception bitcoin.core.script.CScriptInvalidError

Bases: exceptions.Exception

Base class for CScript exceptions

exception bitcoin.core.script.CScriptTruncatedPushDataError(msg, data)

Bases: bitcoin.core.script.CScriptInvalidError

Invalid pushdata due to truncation

class bitcoin.core.script.CScript

Bases: str

Serialized script

A bytes subclass, so you can use this directly whenever bytes are accepted. Note that this means that indexing does not work - you’ll get an index by byte rather than opcode. This format was chosen for efficiency so that the general case would not require creating a lot of little CScriptOP objects.

iter(script) however does iterate by opcode.

GetSigOpCount(fAccurate)

Get the SigOp count.

fAccurate - Accurately count CHECKMULTISIG, see BIP16 for details.

Note that this is consensus-critical.

has_canonical_pushes()

Test if script only uses canonical pushes

Not yet consensus critical; may be in the future.

is_p2sh()

Test if the script is a p2sh scriptPubKey

Note that this test is consensus-critical.

is_push_only()

Test if the script only contains pushdata ops

Note that this test is consensus-critical.

Scripts that contain invalid pushdata ops return False, matching the behavior in Bitcoin Core.

is_unspendable()

Test if the script is provably unspendable

is_valid()

Return True if the script is valid, False otherwise

The script is valid if all PUSHDATA’s are valid; invalid opcodes do not make is_valid() return False.

is_witness_scriptpubkey()

Returns true if this is a scriptpubkey signaling segregated witness data.

is_witness_v0_keyhash()

Returns true if this is a scriptpubkey for V0 P2WPKH.

is_witness_v0_nested_keyhash()

Returns true if this is a scriptpubkey for V0 P2WPKH embedded in P2SH.

is_witness_v0_nested_scripthash()

Returns true if this is a scriptpubkey for V0 P2WSH embedded in P2SH.

is_witness_v0_scripthash()

Returns true if this is a scriptpubkey for V0 P2WSH.

join(iterable) → string

Return a string which is the concatenation of the strings in the iterable. The separator between elements is S.

raw_iter()

Raw iteration

Yields tuples of (opcode, data, sop_idx) so that the different possible PUSHDATA encodings can be accurately distinguished, as well as determining the exact opcode byte indexes. (sop_idx)

to_p2sh_scriptPubKey(checksize=True)

Create P2SH scriptPubKey from this redeemScript

That is, create the P2SH scriptPubKey that requires this script as a redeemScript to spend.

checksize - Check if the redeemScript is larger than the 520-byte max pushdata limit; raise ValueError if limit exceeded.

Since a >520-byte PUSHDATA makes EvalScript() fail, it’s not actually possible to redeem P2SH outputs with redeem scripts >520 bytes.

witness_version()

Returns the witness version on [0,16].

class bitcoin.core.script.CScriptWitness(stack=())

Bases: bitcoin.core.serialize.ImmutableSerializable

An encoding of the data elements on the initial stack for (segregated witness)

is_null()

stack

classmethod stream_deserialize(f)

stream_serialize(f)

bitcoin.core.script.FindAndDelete(script, sig)

Consensus critical, see FindAndDelete() in Satoshi codebase

bitcoin.core.script.RawSignatureHash(script, txTo, inIdx, hashtype)

Consensus-correct SignatureHash

Returns (hash, err) to precisely match the consensus-critical behavior of the SIGHASH_SINGLE bug. (inIdx is not checked for validity)

If you’re just writing wallet software you probably want SignatureHash() instead.

bitcoin.core.script.SignatureHash(script, txTo, inIdx, hashtype, amount=None, sigversion=0)

Calculate a signature hash

‘Cooked’ version that checks if inIdx is out of bounds - this is not consensus-correct behavior, but is what you probably want for general wallet use.

bitcoin.core.script.IsLowDERSignature(sig)

Loosely correlates with IsLowDERSignature() from script/interpreter.cpp Verifies that the S value in a DER signature is the lowest possible value. Used by BIP62 malleability fixes.

scripteval

Script evaluation

Be warned that there are highly likely to be consensus bugs in this code; it is unlikely to match Satoshi Bitcoin exactly. Think carefully before using this module.

exception bitcoin.core.scripteval.EvalScriptError(msg, sop=None, sop_data=None, sop_pc=None, stack=None, scriptIn=None, txTo=None, inIdx=None, flags=None, altstack=None, vfExec=None, pbegincodehash=None, nOpCount=None)

Bases: bitcoin.core.ValidationError

Base class for exceptions raised when a script fails during EvalScript()

The execution state just prior the opcode raising the is saved. (if available)

exception bitcoin.core.scripteval.MaxOpCountError(**kwargs)

Bases: bitcoin.core.scripteval.EvalScriptError

exception bitcoin.core.scripteval.MissingOpArgumentsError(opcode, s, n, **kwargs)

Bases: bitcoin.core.scripteval.EvalScriptError

Missing arguments

exception bitcoin.core.scripteval.ArgumentsInvalidError(opcode, msg, **kwargs)

Bases: bitcoin.core.scripteval.EvalScriptError

Arguments are invalid

exception bitcoin.core.scripteval.VerifyOpFailedError(opcode, **kwargs)

Bases: bitcoin.core.scripteval.EvalScriptError

A VERIFY opcode failed

bitcoin.core.scripteval.EvalScript(stack, scriptIn, txTo, inIdx, flags=())

Evaluate a script

stack - Initial stack

scriptIn - Script

txTo - Transaction the script is a part of

inIdx - txin index of the scriptSig

flags - SCRIPT_VERIFY_* flags to apply

exception bitcoin.core.scripteval.VerifyScriptError

Bases: bitcoin.core.ValidationError

bitcoin.core.scripteval.VerifyScript(scriptSig, scriptPubKey, txTo, inIdx, flags=())

Verify a scriptSig satisfies a scriptPubKey

scriptSig - Signature

scriptPubKey - PubKey

txTo - Spending transaction

inIdx - Index of the transaction input containing scriptSig

Raises a ValidationError subclass if the validation fails.

exception bitcoin.core.scripteval.VerifySignatureError

Bases: bitcoin.core.ValidationError

bitcoin.core.scripteval.VerifySignature(txFrom, txTo, inIdx)

Verify a scriptSig signature can spend a txout

Verifies that the scriptSig in txTo.vin[inIdx] is a valid scriptSig for the corresponding COutPoint in transaction txFrom.

serialize

Serialization routines

You probabably don’t need to use these directly.

bitcoin.core.serialize.Hash(msg)

SHA256^2)(msg) -> bytes

bitcoin.core.serialize.Hash160(msg)

RIPEME160(SHA256(msg)) -> bytes

exception bitcoin.core.serialize.SerializationError

Bases: exceptions.Exception

Base class for serialization errors

exception bitcoin.core.serialize.SerializationTruncationError

Bases: bitcoin.core.serialize.SerializationError

Serialized data was truncated

Thrown by deserialize() and stream_deserialize()

exception bitcoin.core.serialize.DeserializationExtraDataError(msg, obj, padding)

Bases: bitcoin.core.serialize.SerializationError

Deserialized data had extra data at the end

Thrown by deserialize() when not all data is consumed during deserialization. The deserialized object and extra padding not consumed are saved.

bitcoin.core.serialize.ser_read(f, n)

Read from a stream safely

Raises SerializationError and SerializationTruncationError appropriately. Use this instead of f.read() in your classes stream_(de)serialization() functions.

class bitcoin.core.serialize.Serializable

Bases: object

Base class for serializable objects

GetHash()

Return the hash of the serialized object

classmethod deserialize(buf, allow_padding=False, params={})

Deserialize bytes, returning an instance

allow_padding - Allow buf to include extra padding. (default False)

If allow_padding is False and not all bytes are consumed during deserialization DeserializationExtraDataError will be raised.

serialize(params={})

Serialize, returning bytes

classmethod stream_deserialize(f, **kwargs)

Deserialize from a stream

stream_serialize(f, **kwargs)

Serialize to a stream

class bitcoin.core.serialize.ImmutableSerializable

Bases: bitcoin.core.serialize.Serializable

Immutable serializable object

GetHash()

Return the hash of the serialized object

class bitcoin.core.serialize.Serializer

Bases: object

Base class for object serializers

classmethod deserialize(buf)

classmethod serialize(obj)

classmethod stream_deserialize(f)

classmethod stream_serialize(obj, f)

class bitcoin.core.serialize.VarIntSerializer

Bases: bitcoin.core.serialize.Serializer

Serialization of variable length ints

classmethod stream_deserialize(f)

classmethod stream_serialize(i, f)

class bitcoin.core.serialize.BytesSerializer

Bases: bitcoin.core.serialize.Serializer

Serialization of bytes instances

classmethod stream_deserialize(f)

classmethod stream_serialize(b, f)

class bitcoin.core.serialize.VectorSerializer

Bases: bitcoin.core.serialize.Serializer

Base class for serializers of object vectors

classmethod stream_deserialize(inner_cls, f, inner_params={})

classmethod stream_serialize(inner_cls, objs, f, inner_params={})

class bitcoin.core.serialize.uint256VectorSerializer

Bases: bitcoin.core.serialize.Serializer

Serialize vectors of uint256

classmethod stream_deserialize(f)

classmethod stream_serialize(uints, f)

class bitcoin.core.serialize.intVectorSerializer

Bases: bitcoin.core.serialize.Serializer

classmethod stream_deserialize(f)

classmethod stream_serialize(ints, f)

class bitcoin.core.serialize.VarStringSerializer

Bases: bitcoin.core.serialize.Serializer

Serialize variable length byte strings

classmethod stream_deserialize(f)

classmethod stream_serialize(s, f)

bitcoin.core.serialize.uint256_from_str(s)

Convert bytes to uint256

bitcoin.core.serialize.uint256_from_compact(c)

Convert compact encoding to uint256

Used for the nBits compact encoding of the target in the block header.

bitcoin.core.serialize.compact_from_uint256(v)

Convert uint256 to compact encoding

bitcoin.core.serialize.uint256_to_str(u)

bitcoin.core.serialize.uint256_to_shortstr(u)