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
- 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 theimpl
is a callable, and the resulting object is assigned to theself.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: bool | None = 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 toFalse
to disable statements using this type from being cached at all without a warning. When set toTrue
, the object’s class and selected elements from its state will be used as part of the cache key. For example, using aTypeDecorator
: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 forTypeDecorator
classes.New in version 1.4.28: - added the
ExternalType
mixin which generalizes thecache_ok
flag to both theTypeDecorator
andUserDefinedType
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 theimpl
is a callable, and the resulting object is assigned to theself.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: bool | None = 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 toFalse
to disable statements using this type from being cached at all without a warning. When set toTrue
, the object’s class and selected elements from its state will be used as part of the cache key. For example, using aTypeDecorator
: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 forTypeDecorator
classes.New in version 1.4.28: - added the
ExternalType
mixin which generalizes thecache_ok
flag to both theTypeDecorator
andUserDefinedType
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()