Reference

This is the reference section of the documentation.

class bigchain.Bigchain(host=None, port=None, dbname=None, public_key=None, private_key=None, keyring=[])

Bigchain API

Create, read, sign, write transactions to the database

__init__(host=None, port=None, dbname=None, public_key=None, private_key=None, keyring=[])

Initialize the Bigchain instance

There are three ways in which the Bigchain instance can get its parameters. The order by which the parameters are chosen are:

1. Setting them by passing them to the __init__ method itself.
2. Setting them as environment variables
3. Reading them from the config.json file.

Parameters:

• host (str) – hostname where the rethinkdb is running.
• port (int) – port in which rethinkb 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 ECDSA secp256k1 curve.
• private_key (str) – the base58 encoded private key for the ECDSA secp256k1 curve.
• keyring (list[str]) – list of base58 encoded public keys of the federation nodes.

create_transaction(current_owner, new_owner, tx_input, operation, payload=None)

Create a new transaction

A transaction in the bigchain is a transfer of a digital asset between two entities represented by public keys.

Currently the bigchain supports two types of operations:

CREATE - Only federation nodes are allowed to use this operation. In a create operation a federation node creates a digital asset in the bigchain and assigns that asset to a public key. The owner of the private key can then decided to transfer this digital asset by using the transaction id of the transaction as an input in a TRANSFER transaction.

TRANSFER - A transfer operation allows for a transfer of the digital assets between entities.

Parameters:

• current_owner (str) – base58 encoded public key of the current owner of the asset.
• new_owner (str) – base58 encoded public key of the new owner of the digital asset.
• tx_input (str) – id of the transaction to use as input.
• operation (str) – Either CREATE or TRANSFER operation.
• payload (Optional[dict]) – dictionary with information about asset

Returns:

unsigned transaction

Return type:

dict

sign_transaction(transaction, private_key)

Sign a transaction

A transaction signed with the current_owner corresponding private key.

Parameters:

• transaction (dict) – transaction to sign.
• private_key (str) – base58 encoded private key to create a signature of the transaction.

Returns:

transaction with the signature field included.

Return type:

dict

verify_signature(signed_transaction)

Verify the signature of a transaction

A valid transaction should have been signed current_owner corresponding private key.

Parameters:signed_transaction (dict) – a transaction with the signature included. Returns:True if the signature is correct, False otherwise. Return type:bool

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

get_transaction(txid)

Retrieve a transaction with txid from bigchain.

Queries the bigchain for a transaction that was already included in a block.

Parameters:txid (str) – transaction id of the transaction to query Returns:A dict with the transaction details if the transaction was found.

If no transaction with that txid was found it returns None

get_tx_by_payload_hash(payload_hash)

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 sha3-256 hash of the serialized payload and store it with the transaction. This makes it easy for developers to keep track of their digital assets in bigchain.

Parameters:payload_hash (str) – sha3-256 hash of the serialized payload. Returns:A list of transactions containing that payload. If no transaction exists with that payload it returns None

get_spent(txid)

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) – transaction 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 and 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 does not raise an exception if the transaction is valid.

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

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.

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)

Write a block to bigchain.

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

create_genesis_block()

Create the genesis block

Block created when bigchain is first initialized.

vote(block, 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 (dict) – 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

static serialize(data)

Static method used to serialize a dict into a JSON formatted string.

This method enforces rules like the separator and order of keys. This ensures that all dicts are serialized in the same way.

This is specially important for hashing data. We need to make sure that everyone serializes their data in the same way so that we do not have hash mismatches for the same structure due to serialization differences.

Parameters:data (dict) – dict to serialize Returns:JSON formatted string Return type:str

static deserialize(data)

Static method used to deserialize a JSON formatted string into a dict.

Parameters:data (str) – JSON formatted string. Returns:dict resulting from the serialization of a JSON formatted string. Return type:dict

static timestamp()

Static method to calculate a UTC timestamp with microsecond precision.

Returns:UTC timestamp. Return type:str

static generate_keys()

Generates a key pair.

Returns:(private_key, public_key). ECDSA key pair using the secp256k1 curve encoded in base58. Return type:tuple