The Bigchain class¶
The Bigchain class is the top-level Python API for BigchainDB. If you want to create and initialize a BigchainDB database, you create a Bigchain instance (object). Then you can use its various methods to create transactions, write transactions (to the object/database), read transactions, etc.
-
class
bigchaindb.
Bigchain
(host=None, port=None, dbname=None, backend=None, public_key=None, private_key=None, keyring=[], backlog_reassign_delay=None)[source]¶ Bigchain API
Create, read, sign, write transactions to the database
-
__init__
(host=None, port=None, dbname=None, backend=None, public_key=None, private_key=None, keyring=[], backlog_reassign_delay=None)[source]¶ Initialize the Bigchain instance
A Bigchain instance has several configuration parameters (e.g. host). If a parameter value is passed as an argument to the Bigchain __init__ method, then that is the value it will have. Otherwise, the parameter value will come from an environment variable. If that environment variable isn’t set, then the value will come from the local configuration file. And if that variable isn’t in the local configuration file, then the parameter will have its default value (defined in bigchaindb.__init__).
Parameters: - host (str) – hostname where RethinkDB is running.
- port (int) – port in which RethinkDB is running (usually 28015).
- dbname (str) – the name of the database to connect to (usually bigchain).
- backend (
RehinkDBBackend
) – the database backend to use. - public_key (str) – the base58 encoded public key for the ED25519 curve.
- private_key (str) – the base58 encoded private key for the ED25519 curve.
- keyring (list[str]) – list of base58 encoded public keys of the federation nodes.
-
write_transaction
(signed_transaction, durability='soft')[source]¶ Write the transaction to bigchain.
When first writing a transaction to the bigchain the transaction will be kept in a backlog until it has been validated by the nodes of the federation.
Parameters: signed_transaction (Transaction) – transaction with the signature included. Returns: database response Return type: dict
-
reassign_transaction
(transaction)[source]¶ Assign a transaction to a new node
Parameters: transaction (dict) – assigned transaction Returns: database response or None if no reassignment is possible Return type: dict
-
delete_transaction
(*transaction_id)[source]¶ Delete a transaction from the backlog.
Parameters: *transaction_id (str) – the transaction(s) to delete Returns: The database response.
-
get_stale_transactions
()[source]¶ Get a cursor of stale transactions.
Transactions are considered stale if they have been assigned a node, but are still in the backlog after some amount of time specified in the configuration
-
validate_transaction
(transaction)[source]¶ Validate a transaction.
Parameters: transaction (Transaction) – transaction to validate. Returns: The transaction if the transaction is valid else it raises an exception describing the reason why the transaction is invalid.
-
is_valid_transaction
(transaction)[source]¶ Check whether a transaction is valid or invalid.
Similar to
validate_transaction()
but never raises an exception. It returnsFalse
if the transaction is invalid.Parameters: transaction ( Transaction
) – transaction to check.Returns: The Transaction
instance if valid, otherwiseFalse
.
-
get_block
(block_id, include_status=False)[source]¶ Get the block with the specified block_id (and optionally its status)
Returns the block corresponding to block_id or None if no match is found.
Parameters:
-
get_transaction
(txid, include_status=False)[source]¶ Get the transaction with the specified txid (and optionally its status)
This query begins by looking in the bigchain table for all blocks containing a transaction with the specified txid. If one of those blocks is valid, it returns the matching transaction from that block. Else if some of those blocks are undecided, it returns a matching transaction from one of them. If the transaction was found in invalid blocks only, or in no blocks, then this query looks for a matching transaction in the backlog table, and if it finds one there, it returns that.
Parameters: Returns: A
Transaction
instance if the transaction was found in a valid block, an undecided block, or the backlog table, otherwiseNone
. Ifinclude_status
isTrue
, also returns the transaction’s status if the transaction was found.
-
get_status
(txid)[source]¶ Retrieve the status of a transaction with txid from bigchain.
Parameters: txid (str) – transaction id of the transaction to query Returns: transaction status (‘valid’, ‘undecided’, or ‘backlog’). If no transaction with that txid was found it returns None Return type: (string)
-
get_blocks_status_containing_tx
(txid)[source]¶ Retrieve block ids and statuses related to a transaction
Transactions may occur in multiple blocks, but no more than one valid block.
Parameters: txid (str) – transaction id of the transaction to query Returns: A dict of blocks containing the transaction, e.g. {block_id_1: ‘valid’, block_id_2: ‘invalid’ ...}, or None
-
get_transaction_by_metadata_id
(metadata_id)[source]¶ Retrieves valid or undecided transactions related to a particular metadata.
When creating a transaction one of the optional arguments is the metadata. The metadata is a generic dict that contains extra information that can be appended to the transaction.
To make it easy to query the bigchain for that particular metadata we create a UUID for the metadata and store it with the transaction.
Parameters: metadata_id (str) – the id for this particular metadata. Returns: A list of valid or undecided transactions containing that metadata. If no transaction exists with that metadata it returns an empty list []
-
get_transactions_by_asset_id
(asset_id)[source]¶ Retrieves valid or undecided transactions related to a particular asset.
A digital asset in bigchaindb is identified by an uuid. This allows us to query all the transactions related to a particular digital asset, knowing the id.
Parameters: asset_id (str) – the id for this particular asset. Returns: A list of valid or undecided transactions related to the asset. If no transaction exists for that asset it returns an empty list []
-
get_asset_by_id
(asset_id)[source]¶ Returns the asset associated with an asset_id.
Parameters: asset_id (str) – The asset id. Returns: Asset
if the asset exists else None.
-
get_spent
(txid, cid)[source]¶ Check if a txid was already used as an input.
A transaction can be used as an input for another transaction. Bigchain needs to make sure that a given txid is only used once.
Parameters: - txid (str) – The id of the transaction
- cid (num) – the index of the condition in the respective transaction
Returns: The transaction (Transaction) that used the txid as an input else None
-
get_owned_ids
(owner)[source]¶ Retrieve a list of `txid`s that can be used as inputs.
Parameters: owner (str) – base58 encoded public key. Returns: list of `txid`s and `cid`s pointing to another transaction’s condition Return type: list
of TransactionLink
-
create_block
(validated_transactions)[source]¶ Creates a block given a list of validated_transactions.
Note that this method does not validate the transactions. Transactions should be validated before calling create_block.
Parameters: validated_transactions (list(Transaction)) – list of validated transactions. Returns: created block. Return type: Block
-
validate_block
(block)[source]¶ Validate a block.
Parameters: block (Block) – block to validate. Returns: The block if the block is valid else it raises and exception describing the reason why the block is invalid.
-
has_previous_vote
(block_id, voters)[source]¶ Check for previous votes from this node
Parameters: Returns: True
if this block already has a valid vote from this node,False
otherwise.Return type: Raises: ImproperVoteError
– If there is already a vote, but the vote is invalid.
-
write_block
(block, durability='soft')[source]¶ Write a block to bigchain.
Parameters: block (Block) – block to write to bigchain.
-
create_genesis_block
()[source]¶ Create the genesis block
Block created when bigchain is first initialized. This method is not atomic, there might be concurrency problems if multiple instances try to write the genesis block when the BigchainDB Federation is started, but it’s a highly unlikely scenario.
-
vote
(block_id, previous_block_id, decision, invalid_reason=None)[source]¶ Create a signed vote for a block given the
previous_block_id
and thedecision
(valid/invalid).Parameters:
-