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

Bigchain API

Create, read, sign, write transactions to the database

__init__(host=None, port=None, dbname=None, public_key=None, private_key=None, keyring=[], consensus_plugin=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:

• 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).
• 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.

create_transaction(*args, **kwargs)

Create a new transaction

Refer to the documentation of your consensus plugin.

Returns:newly constructed transaction. Return type:dict

sign_transaction(transaction, *args, **kwargs)

Sign a transaction

Refer to the documentation of your consensus plugin.

Returns:transaction with any signatures applied. Return type:dict

validate_fulfillments(signed_transaction, *args, **kwargs)

Validate the fulfillment(s) of a transaction.

Refer to the documentation of your consensus plugin.

Returns:

True if the transaction’s required fulfillments are present

and correct, False otherwise.

Return type:bool

write_transaction(signed_transaction, durability='soft')

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 (dict) – transaction with the signature included. Returns:database response Return type:dict

get_transaction(txid, include_status=False)

Retrieve a transaction with txid from bigchain.

Queries the bigchain for a transaction, if it’s in a valid or invalid block.

Parameters:

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

Returns:

A dict with the transaction details if the transaction was found. Will add the transaction status to payload (‘valid’, ‘undecided’, or ‘backlog’). If no transaction with that txid was found it returns None

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)

search_block_election_on_index(value, index)

Retrieve block election information given a secondary index and value

Parameters:

• value – a value to search (e.g. transaction id string, payload hash string)
• index (str) – name of a secondary index, e.g. ‘transaction_id’

Returns:

A list of blocks with with only election information

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_tx_by_payload_uuid(payload_uuid)

Retrieves transactions related to a digital asset.

When creating a transaction one of the optional arguments is the payload. The payload is a generic dict that contains information about the digital asset.

To make it easy to query the bigchain for that digital asset we create a UUID for the payload and store it with the transaction. This makes it easy for developers to keep track of their digital assets in bigchain.

Parameters:payload_uuid (str) – the UUID for this particular payload. Returns:A list of transactions containing that payload. If no transaction exists with that payload it returns an empty list []

get_spent(tx_input)

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:tx_input (dict) – Input of a transaction in the form {‘txid’: ‘transaction id’, ‘cid’: ‘condition id’} Returns:The transaction that used the txid as an input if it exists else it returns None

get_owned_ids(owner)

Retrieve a list of txids that can we used has inputs.

Parameters:owner (str) – base58 encoded public key. Returns:list of txids currently owned by owner Return type:list

validate_transaction(transaction)

Validate a transaction.

Parameters:transaction (dict) – 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)

Check whether a transacion is valid or invalid.

Similar to validate_transaction but never raises an exception. It returns False if the transaction is invalid.

Parameters:transaction (dict) – transaction to check. Returns:transaction if the transaction is valid, False otherwise

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) – list of validated transactions. Returns:created block. Return type:dict

validate_block(block)

Validate a block.

Parameters:block (dict) – 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)

Check for previous votes from this node

Parameters:block (dict) – block to check. Returns:True if this block already has a valid vote from this node, False otherwise. Return type:bool Raises:ImproperVoteError – If there is already a vote, but the vote is invalid.

is_valid_block(block)

Check whether a block is valid or invalid.

Similar to validate_block but does not raise an exception if the block is invalid.

Parameters:block (dict) – block to check. Returns:True if the block is valid, False otherwise. Return type:bool

write_block(block, durability='soft')

Write a block to bigchain.

Parameters:block (dict) – 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)

Cast your vote on the block given the previous_block_hash and the decision (valid/invalid) return the block to the updated in the database.

Parameters:

• block_id (str) – The id of the block to vote.
• 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.

get_unvoted_blocks()

Return all the blocks that has not been voted by this node.

block_election_status(block)

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