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(public_key=None, private_key=None, keyring=[], connection=None, backlog_reassign_delay=None)

Bigchain API

Create, read, sign, write transactions to the database

__init__(public_key=None, private_key=None, keyring=[], connection=None, backlog_reassign_delay=None)

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:

• 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.
• connection (Connection) – A connection to the database.

BLOCK_INVALID = 'invalid'

return if a block has been voted invalid

BLOCK_VALID = 'valid'

return if a block is valid, or tx is in valid block

TX_VALID = 'valid'

return if a block is valid, or tx is in valid block

BLOCK_UNDECIDED = 'undecided'

return if block is undecided, or tx is in undecided block

TX_UNDECIDED = 'undecided'

return if block is undecided, or tx is in undecided block

TX_IN_BACKLOG = 'backlog'

return if transaction is in backlog

federation

Set of federation member public keys

write_transaction(signed_transaction)

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)

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)

Delete a transaction from the backlog.

Parameters:*transaction_id (str) – the transaction(s) to delete Returns:The database response.

get_stale_transactions()

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)

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_new_transaction(txid, exclude_block_id=None)

Return True if the transaction does not exist in any VALID or UNDECIDED block. Return False otherwise.

Parameters:

• txid (str) – Transaction ID
• exclude_block_id (str) – Exclude block from search

get_block(block_id, include_status=False)

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:

• block_id (str) – transaction id of the transaction to get
• include_status (bool) – also return the status of the block the return value is then a tuple: (block, status)

get_transaction(txid, include_status=False)

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:

• txid (str) – transaction id of the transaction to get
• include_status (bool) – also return the status of the transaction the return value is then a tuple: (tx, status)

Returns:

A Transaction instance if the transaction was found in a valid block, an undecided block, or the backlog table, otherwise None. If include_status is True, also returns the transaction’s status if the transaction was found.

get_status(txid)

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)

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_asset_by_id(asset_id)

Returns the asset associated with an asset_id.

Parameters:asset_id (str) – The asset id. Returns:dict if the asset exists else None.

get_spent(txid, output)

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, output) is only used once.

This method will check if the (txid, output) has already been spent in a transaction that is in either the VALID, UNDECIDED or BACKLOG state.

Parameters:

• txid (str) – The id of the transaction
• output (num) – the index of the output in the respective transaction

Returns:

The transaction (Transaction) that used the (txid, output) as an input else None

Raises:

• CriticalDoubleSpend – If the given (txid, output) was spent in
• more than one valid transaction.

get_owned_ids(owner)

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 output s pointing to another transaction’s condition Return type:list of TransactionLink

get_outputs_filtered(owner, spent=None)

Get a list of output links filtered on some criteria

Parameters:

• owner (str) – base58 encoded public_key.
• spent (bool) – If True return only the spent outputs. If False return only unspent outputs. If spent is not specified (None) return all outputs.

Returns:

list of txid s and output s pointing to another transaction’s condition

Return type:

list of TransactionLink

get_transactions_filtered(asset_id, operation=None)

Get a list of transactions filtered on some criteria

create_block(validated_transactions)

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)

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)

Check for previous votes from this node

Parameters:block_id (str) – the id of the block to check Returns:True if this block already has a valid vote from this node, False otherwise. Return type:bool

write_block(block)

Write a block to bigchain.

Parameters:block (Block) – block to write to bigchain.

prepare_genesis_block()

Prepare a genesis block.

create_genesis_block()

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)

Create a signed vote for a block given the previous_block_id and the decision (valid/invalid).

Parameters:

• block_id (str) – The id of the block to vote on.
• previous_block_id (str) – The id of the previous block.
• decision (bool) – Whether the block is valid or invalid.
• invalid_reason (Optional[str]) – Reason the block is invalid

write_vote(vote)

Write the vote to the database.

get_last_voted_block()

Returns the last block that this node voted on.

block_election_status(block)

Tally the votes on a block, and return the status: valid, invalid, or undecided.

get_assets(asset_ids)

Return a list of assets that match the asset_ids

Parameters:asset_ids (list of str) – A list of asset_ids to retrieve from the database. Returns:The list of assets returned from the database. Return type:list

get_metadata(txn_ids)

Return a list of metadata that match the transaction ids (txn_ids)

Parameters:txn_ids (list of str) – A list of txn_ids to retrieve from the database. Returns:The list of metadata returned from the database. Return type:list

write_assets(assets)

Writes a list of assets into the database.

Parameters:assets (list of dict) – A list of assets to write to the database.

write_metadata(metadata)

Writes a list of metadata into the database.

Parameters:metadata (list of dict) – A list of metadata to write to the database.

text_search(search, *, limit=0, table='assets')

Return an iterator of assets that match the text search

Parameters:

• search (str) – Text search string to query the text index
• limit (int, optional) – Limit the number of returned documents.

Returns:

An iterator of assets that match the text search.

Return type:

iter