Consensus-critical API

Core

Basic core definitions, datastructures, and (context-independent) validation

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

A block including all transactions in it

GetHash()[source]

Return the block hash

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

static build_merkle_tree_from_txids(txids)[source]

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)[source]

Build a full merkle tree from transactions

calc_merkle_root()[source]

Calculate the merkle root

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

get_header()[source]

Return the block header

Returned header is a new object.

classmethod stream_deserialize(f)[source]
stream_serialize(f)[source]
vMerkleTree
vtx
class bitcoin.core.CBlockHeader(nVersion=2, hashPrevBlock='x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00', hashMerkleRoot='x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00', nTime=0, nBits=0, nNonce=0)[source]

A block header

static calc_difficulty(nBits)[source]

Calculate difficulty from nBits target

difficulty
hashMerkleRoot
hashPrevBlock
nBits
nNonce
nTime
nVersion
classmethod stream_deserialize(f)[source]
stream_serialize(f)[source]
class bitcoin.core.CMutableOutPoint(hash='x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00', n=4294967295)[source]

A mutable COutPoint

GetHash()

Return the hash of the serialized object

classmethod from_outpoint(outpoint)[source]

Create a mutable copy of an existing COutPoint

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

A mutable transaction

GetHash()

Return the hash of the serialized object

classmethod from_tx(tx)[source]

Create a fully mutable copy of a pre-existing transaction

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

A mutable CTxIn

GetHash()

Return the hash of the serialized object

classmethod from_txin(txin)[source]

Create a fully mutable copy of an existing TxIn

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

A mutable CTxOut

GetHash()

Return the hash of the serialized object

classmethod from_txout(txout)[source]

Create a fullly mutable copy of an existing TxOut

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

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

classmethod from_outpoint(outpoint)[source]

Create an immutable copy of an existing OutPoint

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

hash
is_null()[source]
n
classmethod stream_deserialize(f)[source]
stream_serialize(f)[source]
class bitcoin.core.CTransaction(vin=(), vout=(), nLockTime=0, nVersion=1)[source]

A transaction

classmethod from_tx(tx)[source]

Create an immutable copy of a pre-existing transaction

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

is_coinbase()[source]
nLockTime
nVersion
classmethod stream_deserialize(f)[source]
stream_serialize(f)[source]
vin
vout
class bitcoin.core.CTxIn(prevout=COutPoint(), scriptSig=CScript([]), nSequence=4294967295)[source]

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)[source]

Create an immutable copy of an existing TxIn

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

is_final()[source]
nSequence
prevout
scriptSig
classmethod stream_deserialize(f)[source]
stream_serialize(f)[source]
class bitcoin.core.CTxOut(nValue=-1, scriptPubKey=CScript([]))[source]

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)[source]

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()[source]
nValue
scriptPubKey
classmethod stream_deserialize(f)[source]
stream_serialize(f)[source]
bitcoin.core.CheckBlock(block, fCheckPoW=True, fCheckMerkleRoot=True, cur_time=None)[source]

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 matches transactions. cur_time - Current time. Defaults to time.time()

exception bitcoin.core.CheckBlockError[source]
bitcoin.core.CheckBlockHeader(block_header, fCheckPoW=True, cur_time=None)[source]

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.CheckBlockHeaderError[source]
bitcoin.core.CheckProofOfWork(hash, nBits)[source]

Check a proof-of-work

Raises CheckProofOfWorkError

exception bitcoin.core.CheckProofOfWorkError[source]
bitcoin.core.CheckTransaction(tx)[source]

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

Raises CheckTransactionError

exception bitcoin.core.CheckTransactionError[source]
class bitcoin.core.CoreChainParams[source]

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

GENESIS_BLOCK = None
NAME = None
PROOF_OF_WORK_LIMIT = None
SUBSIDY_HALVING_INTERVAL = None
class bitcoin.core.CoreMainParams[source]
GENESIS_BLOCK = CBlock(1, lx(0000000000000000000000000000000000000000000000000000000000000000), lx(4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b), 1231006505, 0x1d00ffff, 0x7c2bac1d)
NAME = u'mainnet'
PROOF_OF_WORK_LIMIT = 26959946667150639794667015087019630673637144422540572481103610249215L
SUBSIDY_HALVING_INTERVAL = 210000
class bitcoin.core.CoreRegTestParams[source]
GENESIS_BLOCK = CBlock(1, lx(0000000000000000000000000000000000000000000000000000000000000000), lx(4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b), 1296688602, 0x207fffff, 0x00000002)
NAME = u'regtest'
PROOF_OF_WORK_LIMIT = 57896044618658097711785492504343953926634992332820282019728792003956564819967L
SUBSIDY_HALVING_INTERVAL = 150
class bitcoin.core.CoreTestNetParams[source]
GENESIS_BLOCK = CBlock(1, lx(0000000000000000000000000000000000000000000000000000000000000000), lx(4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b), 1296688602, 0x1d00ffff, 0x18aea41a)
NAME = u'testnet'
bitcoin.core.GetLegacySigOpCount(tx)[source]
bitcoin.core.MoneyRange(nValue)[source]
exception bitcoin.core.ValidationError[source]

Base class for all blockchain validation errors

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

bitcoin.core.b2lx(b)[source]

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.b2x(b)[source]

Convert bytes to a hex string

bitcoin.core.lx(h)[source]

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.str_money_value(value)[source]

Convert an integer money value to a fixed point string

bitcoin.core.x(h)[source]

Convert a hex string to bytes

Bignum handling

Bignum routines

bitcoin.core.bignum.bin2bn(s)[source]
bitcoin.core.bignum.bn2bin(v)[source]
bitcoin.core.bignum.bn2mpi(v)[source]
bitcoin.core.bignum.bn2vch(v)[source]
bitcoin.core.bignum.bn_bytes(v, have_ext=False)[source]
bitcoin.core.bignum.mpi2bn(s)[source]
bitcoin.core.bignum.mpi2vch(s)[source]
bitcoin.core.bignum.vch2bn(s)[source]
bitcoin.core.bignum.vch2mpi(s)[source]

ECC Public Keys

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[source]

Wrapper around OpenSSL’s EC_KEY

POINT_CONVERSION_COMPRESSED = 2
POINT_CONVERSION_UNCOMPRESSED = 4
get_ecdh_key(other_pubkey, kdf=<function <lambda>>)[source]
get_privkey()[source]
get_pubkey()[source]
get_raw_ecdh_key(other_pubkey)[source]
set_compressed(compressed)[source]
set_privkey(key)[source]
set_pubkey(key)[source]
set_secretbytes(secret)[source]
sign(hash)[source]
verify(hash, sig)[source]

Verify a DER signature

class bitcoin.core.key.CPubKey[source]

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
verify(hash, sig)[source]

Scripts and Opcodes

Scripts

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

class bitcoin.core.script.CScript[source]

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)[source]

Get the SigOp count.

fAccurate - Accurately count CHECKMULTISIG, see BIP16 for details.

Note that this is consensus-critical.

has_canonical_pushes()[source]

Test if script only uses canonical pushes

Not yet consensus critical; may be in the future.

is_p2sh()[source]

Test if the script is a p2sh scriptPubKey

Note that this test is consensus-critical.

is_push_only()[source]

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()[source]

Test if the script is provably unspendable

is_valid()[source]

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.

join(iterable)[source]
raw_iter()[source]

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)[source]

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.

exception bitcoin.core.script.CScriptInvalidError[source]

Base class for CScript exceptions

class bitcoin.core.script.CScriptOp[source]

A single script opcode

decode_op_n()[source]

Decode a small integer opcode, returning an integer

static encode_op_n(n)[source]

Encode a small integer op, returning an opcode

static encode_op_pushdata(d)[source]

Encode a PUSHDATA op, returning bytes

is_small_int()[source]

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

exception bitcoin.core.script.CScriptTruncatedPushDataError(msg, data)[source]

Invalid pushdata due to truncation

bitcoin.core.script.FindAndDelete(script, sig)[source]

Consensus critical, see FindAndDelete() in Satoshi codebase

bitcoin.core.script.RawSignatureHash(script, txTo, inIdx, hashtype)[source]

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)[source]

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.

Script evaluation/verification

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.ArgumentsInvalidError(opcode, msg, **kwargs)[source]

Arguments are invalid

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

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.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)[source]

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)[source]
exception bitcoin.core.scripteval.MissingOpArgumentsError(opcode, s, n, **kwargs)[source]

Missing arguments

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

A VERIFY opcode failed

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

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.VerifyScriptError[source]
bitcoin.core.scripteval.VerifySignature(txFrom, txTo, inIdx)[source]

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.

exception bitcoin.core.scripteval.VerifySignatureError[source]

Serialization

Serialization routines

You probabably don’t need to use these directly.

class bitcoin.core.serialize.BytesSerializer[source]

Serialization of bytes instances

classmethod stream_deserialize(f)[source]
classmethod stream_serialize(b, f)[source]
exception bitcoin.core.serialize.DeserializationExtraDataError(msg, obj, padding)[source]

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.Hash(msg)[source]

SHA256^2)(msg) -> bytes

bitcoin.core.serialize.Hash160(msg)[source]

RIPEME160(SHA256(msg)) -> bytes

class bitcoin.core.serialize.ImmutableSerializable[source]

Immutable serializable object

GetHash()[source]

Return the hash of the serialized object

class bitcoin.core.serialize.Serializable[source]

Base class for serializable objects

GetHash()[source]

Return the hash of the serialized object

classmethod deserialize(buf, allow_padding=False)[source]

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()[source]

Serialize, returning bytes

classmethod stream_deserialize(f)[source]

Deserialize from a stream

stream_serialize(f)[source]

Serialize to a stream

exception bitcoin.core.serialize.SerializationError[source]

Base class for serialization errors

exception bitcoin.core.serialize.SerializationTruncationError[source]

Serialized data was truncated

Thrown by deserialize() and stream_deserialize()

class bitcoin.core.serialize.Serializer[source]

Base class for object serializers

classmethod deserialize(buf)[source]
classmethod serialize(obj)[source]
classmethod stream_deserialize(f)[source]
classmethod stream_serialize(obj, f)[source]
class bitcoin.core.serialize.VarIntSerializer[source]

Serialization of variable length ints

classmethod stream_deserialize(f)[source]
classmethod stream_serialize(i, f)[source]
class bitcoin.core.serialize.VarStringSerializer[source]

Serialize variable length strings

classmethod stream_deserialize(f)[source]
classmethod stream_serialize(s, f)[source]
class bitcoin.core.serialize.VectorSerializer[source]

Base class for serializers of object vectors

classmethod stream_deserialize(inner_cls, f)[source]
classmethod stream_serialize(inner_cls, objs, f)[source]
class bitcoin.core.serialize.intVectorSerialzer[source]
classmethod stream_deserialize(f)[source]
classmethod stream_serialize(ints, f)[source]
bitcoin.core.serialize.ser_read(f, n)[source]

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.uint256VectorSerializer[source]

Serialize vectors of uint256

classmethod stream_deserialize(f)[source]
classmethod stream_serialize(uints, f)[source]
bitcoin.core.serialize.uint256_from_compact(c)[source]

Convert compact encoding to uint256

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

bitcoin.core.serialize.uint256_from_str(s)[source]

Convert bytes to uint256

bitcoin.core.serialize.uint256_to_shortstr(u)[source]