The BigchainDB Class

class bigchaindb.BigchainDB(connection=None)

Bigchain API

Create, read, sign, write transactions to the database

post_transaction(transaction, mode)

Submit a valid transaction to the mempool.

write_transaction(transaction, mode)

Submit a valid transaction to the mempool.

update_utxoset(transaction)

Update the UTXO set given transaction. That is, remove the outputs that the given transaction spends, and add the outputs that the given transaction creates.

Parameters:transaction (Transaction) – A new transaction incoming into the system for which the UTXO set needs to be updated.

store_unspent_outputs(*unspent_outputs)

Store the given unspent_outputs (utxos).

Parameters:*unspent_outputs (tuple of dict) – Variable length tuple or list of unspent outputs.

get_utxoset_merkle_root()

Returns the merkle root of the utxoset. This implies that the utxoset is first put into a merkle tree.

For now, the merkle tree and its root will be computed each time. This obviously is not efficient and a better approach that limits the repetition of the same computation when unnecesary should be sought. For instance, future optimizations could simply re-compute the branches of the tree that were affected by a change.

The transaction hash (id) and output index should be sufficient to uniquely identify a utxo, and consequently only that information from a utxo record is needed to compute the merkle root. Hence, each node of the merkle tree should contain the tuple (txid, output_index).

Important

The leaves of the tree will need to be sorted in some kind of lexicographical order.

Returns:Merkle root in hexadecimal form. Return type:str

get_unspent_outputs()

Get the utxoset.

Returns:generator of unspent_outputs.

delete_unspent_outputs(*unspent_outputs)

Deletes the given unspent_outputs (utxos).

Parameters:*unspent_outputs (tuple of dict) – Variable length tuple or list of unspent outputs.

get_transactions_filtered(asset_id, operation=None, last_tx=None)

Get a list of transactions filtered on some criteria

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

store_block(block)

Create a new block.

get_latest_block()

Get the block with largest height.

get_block(block_id)

Get the block with the specified block_id.

Returns the block corresponding to block_id or None if no match is found.

Parameters:block_id (int) – block id of the block to get.

get_block_containing_tx(txid)

Retrieve the list of blocks (block ids) containing a

transaction with transaction id txid

Parameters:txid (str) – transaction id of the transaction to query Returns:Block id list (list(int))

validate_transaction(tx, current_transactions=[])

Validate a transaction against the current status of 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

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

store_validator_set(height, validators)

Store validator set at a given height. NOTE: If the validator set already exists at that height then an exception will be raised.

migrate_abci_chain()

Generate and record a new ABCI chain ID. New blocks are not accepted until we receive an InitChain ABCI request with the matching chain ID and validator set.

Chain ID is generated based on the current chain and height. chain-X => chain-X-migrated-at-height-5. chain-X-migrated-at-height-5 => chain-X-migrated-at-height-21.

If there is no known chain (we are at genesis), the function returns.