bitcoinlib.db module

class bitcoinlib.db.Db(db_uri=None, password=None)[source]

Bases: object

Bitcoinlib Database object used by Service() and HDWallet() class. Initialize database and open session when creating database object.

Create new database if is doesn’t exist yet

drop_db(yes_i_am_sure=False)[source]

class bitcoinlib.db.DbConfig(**kwargs)[source]

Bases: Base

BitcoinLib configuration variables

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

value

variable

class bitcoinlib.db.DbKey(**kwargs)[source]

Bases: Base

Database definitions for keys in Sqlalchemy format

Part of a wallet, and used by transactions

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

account_id: ID of account if key is part of a HD structure

address: Address representation of key. An cryptocurrency address is a hash of the public key

address_index: Index of address in HD key structure address level

balance: Total balance of UTXO’s linked to this key

change: Change or normal address: Normal=0, Change=1

compressed: Is key compressed or not. Default is True

cosigner_id: ID of cosigner, used if key is part of HD Wallet

depth: Depth of key if it is part of a HD structure. Depth=0 means masterkey, depth=1 are the masterkeys children.

encoding: Encoding used to represent address: base58 or bech32

id: Unique Key ID

is_private: Is key private or not?

key_type: Type of key: single, bip32 or multisig. Default is bip32

latest_txid: TxId of latest transaction downloaded from the blockchain

multisig_children: List of children keys

multisig_parents: List of parent keys

name: Key name string

network: DbNetwork object for this key

network_name: Name of key network, i.e. bitcoin, litecoin, dash

parent_id: Parent Key ID. Used in HD wallets

path: String of BIP-32 key path

private: Bytes representation of private key

public: Bytes representation of public key

purpose: Purpose ID, default is 44

transaction_inputs: All DbTransactionInput objects this key is part of

transaction_outputs: All DbTransactionOutput objects this key is part of

used: Has key already been used on the blockchain in as input or output? Default is False

wallet: Related Wallet object

wallet_id: Wallet ID which contains this key

wif: Public or private WIF (Wallet Import Format) representation

class bitcoinlib.db.DbKeyMultisigChildren(**kwargs)[source]

Bases: Base

Use many-to-many relationship for multisig keys. A multisig keys contains 2 or more child keys and a child key can be used in more then one multisig key.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

child_id

key_order

parent_id

class bitcoinlib.db.DbNetwork(**kwargs)[source]

Bases: Base

Database definitions for networks in Sqlalchemy format

Most network settings and variables can be found outside the database in the libraries configurations settings. Use the bitcoinlib/data/networks.json file to view and manage settings.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

description

name: Network name, i.e.: bitcoin, litecoin, dash

class bitcoinlib.db.DbTransaction(**kwargs)[source]

Bases: Base

Database definitions for transactions in Sqlalchemy format

Refers to 1 or more keys which can be part of a wallet

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

account_id: ID of account

block_height: Number of block this transaction is included in

coinbase: Is True when this is a coinbase transaction, default is False

confirmations: Number of confirmation when this transaction is included in a block. Default is 0: unconfirmed

date: Date when transaction was confirmed and included in a block. Or when it was created when transaction is not send or confirmed

fee: Transaction fee

id: Unique transaction index for internal usage

input_total: Total value of the inputs of this transaction. Input total = Output total + fee. Default is 0

inputs: List of all inputs as DbTransactionInput objects

is_complete: Allow to store incomplete transactions, for instance if not all inputs are known when retrieving UTXO’s

locktime: Transaction level locktime. Locks the transaction until a specified block (value from 1 to 5 million) or until a certain time (Timestamp in seconds after 1-jan-1970). Default value is 0 for transactions without locktime

network: Link to DbNetwork object

network_name: Blockchain network name of this transaction

output_total: Total value of the outputs of this transaction. Output total = Input total - fee

outputs: List of all outputs as DbTransactionOutput objects

raw: Raw transaction hexadecimal string. Transaction is included in raw format on the blockchain

size: Size of the raw transaction in bytes

status: Current status of transaction, can be one of the following: new’, ‘unconfirmed’, ‘confirmed’. Default is ‘new’

txid: Bytes representation of transaction ID

verified: Is transaction verified. Default is False

version: Tranaction version. Default is 1 but some wallets use another version number

wallet: Link to Wallet object which contains this transaction

wallet_id: ID of wallet which contains this transaction

witness_type: Is this a legacy or segwit transaction?

class bitcoinlib.db.DbTransactionInput(**kwargs)[source]

Bases: Base

Transaction Input Table

Relates to Transaction table and Key table

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

address: Address string of input, used if no key is associated. An cryptocurrency address is a hash of the public key or a redeemscript

double_spend: Indicates if a service provider tagged this transaction as double spend

index_n: Index number of transaction input

key: Related DbKey object

key_id: ID of key used in this input

output_n: Output_n of previous transaction output that is spent in this input

prev_txid: Transaction hash of previous transaction. Previous unspent outputs (UTXO) is spent in this input

script: Unlocking script to unlock previous locked output

script_type: Unlocking script type. Can be ‘coinbase’, ‘sig_pubkey’, ‘p2sh_multisig’, ‘signature’, ‘unknown’, ‘p2sh_p2wpkh’ or ‘p2sh_p2wsh’. Default is sig_pubkey

sequence: Transaction sequence number. Used for timelock transaction inputs

transaction: Related DbTransaction object

transaction_id: Input is part of transaction with this ID

value: Value of transaction input

witness_type: Type of transaction, can be legacy, segwit or p2sh-segwit. Default is legacy

witnesses: Witnesses (signatures) used in Segwit transaction inputs

class bitcoinlib.db.DbTransactionOutput(**kwargs)[source]

Bases: Base

Transaction Output Table

Relates to Transaction and Key table

When spent is False output is considered an UTXO

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

address: Address string of output, used if no key is associated. An cryptocurrency address is a hash of the public key or a redeemscript

key: List of DbKey object used in this output

key_id: ID of key used in this transaction output

output_n: Sequence number of transaction output

script: Locking script which locks transaction output

script_type: Locking script type. Can be one of these values: ‘p2pkh’, ‘multisig’, ‘p2sh’, ‘p2pk’, ‘nulldata’, ‘unknown’, ‘p2wpkh’, ‘p2wsh’, ‘p2tr’. Default is p2pkh

spending_index_n: Index number of transaction input which spends this output

spending_txid: Transaction hash of input which spends this output

spent: Indicated if output is already spent in another transaction

transaction: Link to transaction object

transaction_id: Transaction ID of parent transaction

value: Total transaction output value

class bitcoinlib.db.DbWallet(**kwargs)[source]

Bases: Base

Database definitions for wallets in Sqlalchemy format

Contains one or more keys.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

children: Wallet IDs of children wallets, used in multisig wallets

cosigner_id: ID of cosigner of this wallet. Used in multisig wallets to differentiate between different wallets

default_account_id: ID of default account for this wallet if multiple accounts are used

encoding: Default encoding to use for address generation, i.e. base58 or bech32. Default is base58.

id: Unique wallet ID

key_path: Key path structure used in this wallet. Key path for multisig wallet, use to create your own non-standard key path. Key path must follow the following rules: * Path start with masterkey (m) and end with change / address_index * If accounts are used, the account level must be 3. I.e.: m/purpose/coin_type/account/ * All keys must be hardened, except for change, address_index or cosigner_id Max length of path is 8 levels

keys: Link to keys (DbKeys objects) in this wallet

main_key_id: Masterkey ID for this wallet. All other keys are derived from the masterkey in a HD wallet bip32 wallet

multisig: Indicates if wallet is a multisig wallet. Default is True

multisig_n_required: Number of required signature for multisig, only used for multisignature master key

name: Unique wallet name

network: Link to DbNetwork object

network_name: Name of network, i.e.: bitcoin, litecoin

owner: Wallet owner

parent_id: Wallet ID of parent wallet, used in multisig wallets

purpose: Wallet purpose ID. BIP-44 purpose field, indicating which key-scheme is used default is 44

scheme: Key structure type, can be BIP-32 or single

sort_keys: Sort keys in multisig wallet

transactions: Link to transaction (DbTransactions) in this wallet

witness_type: Wallet witness type. Can be ‘legacy’, ‘segwit’ or ‘p2sh-segwit’. Default is legacy.

class bitcoinlib.db.EncryptedBinary(*args: Any, **kwargs: Any)[source]

Bases: TypeDecorator

FieldType for encrypted Binary storage using EAS encryption

Construct a TypeDecorator.

Arguments sent here are passed to the constructor of the class assigned to the impl class level attribute, assuming the impl is a callable, and the resulting object is assigned to the self.impl instance attribute (thus overriding the class attribute of the same name).

If the class level impl is not a callable (the unusual case), it will be assigned to the same instance attribute ‘as-is’, ignoring those arguments passed to the constructor.

Subclasses can override this to customize the generation of self.impl entirely.

cache_ok: Optional[bool] = True

Indicate if statements using this ExternalType are “safe to cache”.

The default value None will emit a warning and then not allow caching of a statement which includes this type. Set to False to disable statements using this type from being cached at all without a warning. When set to True, the object’s class and selected elements from its state will be used as part of the cache key. For example, using a TypeDecorator:

class MyType(TypeDecorator):
    impl = String

    cache_ok = True

    def __init__(self, choices):
        self.choices = tuple(choices)
        self.internal_only = True

The cache key for the above type would be equivalent to:

>>> MyType(["a", "b", "c"])._static_cache_key
(<class '__main__.MyType'>, ('choices', ('a', 'b', 'c')))

The caching scheme will extract attributes from the type that correspond to the names of parameters in the __init__() method. Above, the “choices” attribute becomes part of the cache key but “internal_only” does not, because there is no parameter named “internal_only”.

The requirements for cacheable elements is that they are hashable and also that they indicate the same SQL rendered for expressions using this type every time for a given cache value.

To accommodate for datatypes that refer to unhashable structures such as dictionaries, sets and lists, these objects can be made “cacheable” by assigning hashable structures to the attributes whose names correspond with the names of the arguments. For example, a datatype which accepts a dictionary of lookup values may publish this as a sorted series of tuples. Given a previously un-cacheable type as:

class LookupType(UserDefinedType):
    '''a custom type that accepts a dictionary as a parameter.

    this is the non-cacheable version, as "self.lookup" is not
    hashable.

    '''

    def __init__(self, lookup):
        self.lookup = lookup

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect):
        # ...  works with "self.lookup" ...

Where “lookup” is a dictionary. The type will not be able to generate a cache key:

>>> type_ = LookupType({"a": 10, "b": 20})
>>> type_._static_cache_key
<stdin>:1: SAWarning: UserDefinedType LookupType({'a': 10, 'b': 20}) will not
produce a cache key because the ``cache_ok`` flag is not set to True.
Set this flag to True if this type object's state is safe to use
in a cache key, or False to disable this warning.
symbol('no_cache')

If we did set up such a cache key, it wouldn’t be usable. We would get a tuple structure that contains a dictionary inside of it, which cannot itself be used as a key in a “cache dictionary” such as SQLAlchemy’s statement cache, since Python dictionaries aren’t hashable:

>>> # set cache_ok = True
>>> type_.cache_ok = True

>>> # this is the cache key it would generate
>>> key = type_._static_cache_key
>>> key
(<class '__main__.LookupType'>, ('lookup', {'a': 10, 'b': 20}))

>>> # however this key is not hashable, will fail when used with
>>> # SQLAlchemy statement cache
>>> some_cache = {key: "some sql value"}
Traceback (most recent call last): File "<stdin>", line 1,
in <module> TypeError: unhashable type: 'dict'

The type may be made cacheable by assigning a sorted tuple of tuples to the “.lookup” attribute:

class LookupType(UserDefinedType):
    '''a custom type that accepts a dictionary as a parameter.

    The dictionary is stored both as itself in a private variable,
    and published in a public variable as a sorted tuple of tuples,
    which is hashable and will also return the same value for any
    two equivalent dictionaries.  Note it assumes the keys and
    values of the dictionary are themselves hashable.

    '''

    cache_ok = True

    def __init__(self, lookup):
        self._lookup = lookup

        # assume keys/values of "lookup" are hashable; otherwise
        # they would also need to be converted in some way here
        self.lookup = tuple(
            (key, lookup[key]) for key in sorted(lookup)
        )

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect):
        # ...  works with "self._lookup" ...

Where above, the cache key for LookupType({"a": 10, "b": 20}) will be:

>>> LookupType({"a": 10, "b": 20})._static_cache_key
(<class '__main__.LookupType'>, ('lookup', (('a', 10), ('b', 20))))

New in version 1.4.14: - added the cache_ok flag to allow some configurability of caching for TypeDecorator classes.

New in version 1.4.28: - added the ExternalType mixin which generalizes the cache_ok flag to both the TypeDecorator and UserDefinedType classes.

See also

sql_caching

impl: alias of LargeBinary

key = None

process_bind_param(value, dialect)[source]

Receive a bound parameter value to be converted.

Custom subclasses of _types.TypeDecorator should override this method to provide custom behaviors for incoming data values. This method is called at statement execution time and is passed the literal Python data value which is to be associated with a bound parameter in the statement.

The operation could be anything desired to perform custom behavior, such as transforming or serializing data. This could also be used as a hook for validating logic.

Parameters

value – Data to operate upon, of any type expected by this method in the subclass. Can be None.
dialect – the Dialect in use.

See also

types_typedecorator

_types.TypeDecorator.process_result_value()

process_result_value(value, dialect)[source]

Receive a result-row column value to be converted.

Custom subclasses of _types.TypeDecorator should override this method to provide custom behaviors for data values being received in result rows coming from the database. This method is called at result fetching time and is passed the literal Python data value that’s extracted from a database result row.

The operation could be anything desired to perform custom behavior, such as transforming or deserializing data.

Parameters

value – Data to operate upon, of any type expected by this method in the subclass. Can be None.
dialect – the Dialect in use.

See also

types_typedecorator

_types.TypeDecorator.process_bind_param()

class bitcoinlib.db.EncryptedString(*args: Any, **kwargs: Any)[source]

Bases: TypeDecorator

FieldType for encrypted String storage using EAS encryption

Construct a TypeDecorator.

Arguments sent here are passed to the constructor of the class assigned to the impl class level attribute, assuming the impl is a callable, and the resulting object is assigned to the self.impl instance attribute (thus overriding the class attribute of the same name).

If the class level impl is not a callable (the unusual case), it will be assigned to the same instance attribute ‘as-is’, ignoring those arguments passed to the constructor.

Subclasses can override this to customize the generation of self.impl entirely.

cache_ok: Optional[bool] = True

Indicate if statements using this ExternalType are “safe to cache”.

The default value None will emit a warning and then not allow caching of a statement which includes this type. Set to False to disable statements using this type from being cached at all without a warning. When set to True, the object’s class and selected elements from its state will be used as part of the cache key. For example, using a TypeDecorator:

class MyType(TypeDecorator):
    impl = String

    cache_ok = True

    def __init__(self, choices):
        self.choices = tuple(choices)
        self.internal_only = True

The cache key for the above type would be equivalent to:

>>> MyType(["a", "b", "c"])._static_cache_key
(<class '__main__.MyType'>, ('choices', ('a', 'b', 'c')))

The caching scheme will extract attributes from the type that correspond to the names of parameters in the __init__() method. Above, the “choices” attribute becomes part of the cache key but “internal_only” does not, because there is no parameter named “internal_only”.

The requirements for cacheable elements is that they are hashable and also that they indicate the same SQL rendered for expressions using this type every time for a given cache value.

To accommodate for datatypes that refer to unhashable structures such as dictionaries, sets and lists, these objects can be made “cacheable” by assigning hashable structures to the attributes whose names correspond with the names of the arguments. For example, a datatype which accepts a dictionary of lookup values may publish this as a sorted series of tuples. Given a previously un-cacheable type as:

class LookupType(UserDefinedType):
    '''a custom type that accepts a dictionary as a parameter.

    this is the non-cacheable version, as "self.lookup" is not
    hashable.

    '''

    def __init__(self, lookup):
        self.lookup = lookup

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect):
        # ...  works with "self.lookup" ...

Where “lookup” is a dictionary. The type will not be able to generate a cache key:

>>> type_ = LookupType({"a": 10, "b": 20})
>>> type_._static_cache_key
<stdin>:1: SAWarning: UserDefinedType LookupType({'a': 10, 'b': 20}) will not
produce a cache key because the ``cache_ok`` flag is not set to True.
Set this flag to True if this type object's state is safe to use
in a cache key, or False to disable this warning.
symbol('no_cache')

If we did set up such a cache key, it wouldn’t be usable. We would get a tuple structure that contains a dictionary inside of it, which cannot itself be used as a key in a “cache dictionary” such as SQLAlchemy’s statement cache, since Python dictionaries aren’t hashable:

>>> # set cache_ok = True
>>> type_.cache_ok = True

>>> # this is the cache key it would generate
>>> key = type_._static_cache_key
>>> key
(<class '__main__.LookupType'>, ('lookup', {'a': 10, 'b': 20}))

>>> # however this key is not hashable, will fail when used with
>>> # SQLAlchemy statement cache
>>> some_cache = {key: "some sql value"}
Traceback (most recent call last): File "<stdin>", line 1,
in <module> TypeError: unhashable type: 'dict'

The type may be made cacheable by assigning a sorted tuple of tuples to the “.lookup” attribute:

class LookupType(UserDefinedType):
    '''a custom type that accepts a dictionary as a parameter.

    The dictionary is stored both as itself in a private variable,
    and published in a public variable as a sorted tuple of tuples,
    which is hashable and will also return the same value for any
    two equivalent dictionaries.  Note it assumes the keys and
    values of the dictionary are themselves hashable.

    '''

    cache_ok = True

    def __init__(self, lookup):
        self._lookup = lookup

        # assume keys/values of "lookup" are hashable; otherwise
        # they would also need to be converted in some way here
        self.lookup = tuple(
            (key, lookup[key]) for key in sorted(lookup)
        )

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect):
        # ...  works with "self._lookup" ...

Where above, the cache key for LookupType({"a": 10, "b": 20}) will be:

>>> LookupType({"a": 10, "b": 20})._static_cache_key
(<class '__main__.LookupType'>, ('lookup', (('a', 10), ('b', 20))))

New in version 1.4.14: - added the cache_ok flag to allow some configurability of caching for TypeDecorator classes.

New in version 1.4.28: - added the ExternalType mixin which generalizes the cache_ok flag to both the TypeDecorator and UserDefinedType classes.

See also

sql_caching

impl: alias of String

key = None

process_bind_param(value, dialect)[source]

Receive a bound parameter value to be converted.

Custom subclasses of _types.TypeDecorator should override this method to provide custom behaviors for incoming data values. This method is called at statement execution time and is passed the literal Python data value which is to be associated with a bound parameter in the statement.

The operation could be anything desired to perform custom behavior, such as transforming or serializing data. This could also be used as a hook for validating logic.

Parameters

value – Data to operate upon, of any type expected by this method in the subclass. Can be None.
dialect – the Dialect in use.

See also

types_typedecorator

_types.TypeDecorator.process_result_value()

process_result_value(value, dialect)[source]

Receive a result-row column value to be converted.

Custom subclasses of _types.TypeDecorator should override this method to provide custom behaviors for data values being received in result rows coming from the database. This method is called at result fetching time and is passed the literal Python data value that’s extracted from a database result row.

The operation could be anything desired to perform custom behavior, such as transforming or deserializing data.

Parameters

value – Data to operate upon, of any type expected by this method in the subclass. Can be None.
dialect – the Dialect in use.

See also

types_typedecorator

_types.TypeDecorator.process_bind_param()

bitcoinlib.db.add_column(engine, table_name, column)[source]

Used to add new column to database with migration and update scripts

Parameters

engine –
table_name –
column –

Returns

bitcoinlib.db.compile_largebinary_mysql(type_, compiler, **kwargs)[source]

bitcoinlib.db.db_update(db, version_db, code_version='0.6.10')[source]

bitcoinlib.db.db_update_version_id(db, version)[source]