Library Reference

driver

class bigchaindb_driver.BigchainDB(*nodes, transport_class=<class 'bigchaindb_driver.transport.Transport'>)

BigchainDB driver class.

A BigchainDB driver is initialized with a keypair and is able to create, sign, and submit transactions to a Node in the Federation. At the moment, a BigchainDB driver instance is bounded to a specific node in the Federation. In the future, a BigchainDB driver instance might connect to >1 nodes.

__init__(*nodes, transport_class=<class 'bigchaindb_driver.transport.Transport'>)

Initialize a BigchainDB driver instance.

If a verifying_key or signing_key are given, this instance will be bound to the keys and applied them as defaults whenever a verifying and/or signing key are needed.

Parameters:

• *nodes (str) – BigchainDB nodes to connect to. Currently, the full URL must be given. In the absence of any node, the default of the transport_class will be used, e.g.: 'http://localhost:9984/api/v1'.
• transport_class – Optional transport class to use. Defaults to Transport.

nodes

tuple of str: URLs of connected nodes.

transactions

TransactionsEndpoint: Exposes functionalities of the ‘/transactions’ endpoint.

transport

Transport: Object responsible for forwarding requests to a Connection instance (node).

class bigchaindb_driver.driver.TransactionsEndpoint(driver)

Endpoint for transactions.

path

str

The path of the endpoint.

__init__(driver)

Initializes an instance of NamespacedDriver with the given driver instance.

Parameters:driver (BigchainDB) – Instance of BigchainDB.

static fulfill(transaction, private_keys)

Fulfills the given transaction.

Parameters:

• transaction (dict) – The transaction to be fulfilled.
• private_keys (str | list | tuple) – One or more private keys to be used for fulfilling the transaction.

Returns:

The fulfilled transaction payload, ready to be sent to a BigchainDB federation.

Return type:

dict

Raises:

MissingSigningKeyError – If a private key, (aka signing key), is missing.

static prepare(*, operation='CREATE', owners_before=None, owners_after=None, asset=None, metadata=None, inputs=None)

Prepares a transaction payload, ready to be fulfilled.

Parameters:

• operation (str) – The operation to perform. Must be 'CREATE' or 'TRANSFER'. Case insensitive. Defaults to 'CREATE'.
• owners_before (list | tuple | str, optional) – One or more public keys representing the issuer(s) of the asset being created. Only applies for 'CREATE' operations. Defaults to None.
• owners_after (list | tuple | str, optional) – One or more public keys representing the new owner(s) of the asset being created or transferred. Defaults to None.
• asset (dict, optional) – The asset being created or transferred. MUST be supplied for 'TRANSFER' operations. Defaults to None.
• metadata (dict, optional) – Metadata associated with the transaction. Defaults to None.
• inputs (dict | list | tuple, optional) – One or more inputs holding the condition(s) that this transaction intends to fulfill. Each input is expected to be a dict. Only applies to, and MUST be supplied for, 'TRANSFER' operations.

Returns:

The prepared transaction.

Return type:

dict

Raises:

BigchaindbException – If operation is not 'CREATE' or 'TRANSFER'.

Important

CREATE operations

• owners_before MUST be set.

• owners_after, asset, and metadata MAY be set.

• The argument inputs is ignored.

• If owners_after is not given, or evaluates to False, it will be set equal to owners_before:

  if not owners_after:
      owners_after = owners_before
  

TRANSFER operations

• owners_after, asset, and inputs MUST be set.
• metadata MAY be set.
• The argument owners_before is ignored.

retrieve(txid)

Retrieves the transaction with the given id.

Parameters:txid (str) – Id of the transaction to retrieve. Returns:The transaction with the given id. Return type:dict

send(transaction)

Submit a transaction to the Federation.

Parameters:transaction (dict) – the transaction to be sent to the Federation node(s). Returns:The transaction sent to the Federation node(s). Return type:dict

status(txid)

Retrieves the status of the transaction with the given id.

Parameters:txid (str) – Id of the transaction to retrieve the status for. Returns:A dict containing a ‘status’ item for the transaction. Return type:dict

class bigchaindb_driver.driver.NamespacedDriver(driver)

Base class for creating endpoints (namespaced objects) that can be added under the BigchainDB driver.

__init__(driver)

Initializes an instance of NamespacedDriver with the given driver instance.

Parameters:driver (BigchainDB) – Instance of BigchainDB.

offchain

Module for operations that can be performed “offchain”, meaning without a connection to one or more BigchainDB federation nodes.

bigchaindb_driver.offchain.prepare_transaction(*, operation='CREATE', owners_before=None, owners_after=None, asset=None, metadata=None, inputs=None)

Prepares a transaction payload, ready to be fulfilled. Depending on the value of operation simply dispatches to either prepare_create_transaction() or prepare_transfer_transaction().

Parameters:

• operation (str) – The operation to perform. Must be 'CREATE' or 'TRANSFER'. Case insensitive. Defaults to 'CREATE'.
• owners_before (list | tuple | str, optional) – One or more public keys representing the issuer(s) of the asset being created. Only applies for 'CREATE' operations. Defaults to None.
• owners_after (list | tuple | str, optional) – One or more public keys representing the new owner(s) of the asset being created or transferred. Defaults to None.
• asset (dict, optional) – The asset being created or transferred. MUST be supplied for 'TRANSFER' operations. Defaults to None.
• metadata (dict, optional) – Metadata associated with the transaction. Defaults to None.
• inputs (dict | list | tuple, optional) – One or more inputs holding the condition(s) that this transaction intends to fulfill. Each input is expected to be a dict. Only applies to, and MUST be supplied for, 'TRANSFER' operations.

Returns:

The prepared transaction.

Return type:

dict

Raises:

BigchaindbException – If operation is not 'CREATE' or 'TRANSFER'.

Important

CREATE operations

• owners_before MUST be set.

• owners_after, asset, and metadata MAY be set.

• The argument inputs is ignored.

• If owners_after is not given, or evaluates to False, it will be set equal to owners_before:

  if not owners_after:
      owners_after = owners_before
  

TRANSFER operations

• owners_after, asset, and inputs MUST be set.
• metadata MAY be set.
• The argument owners_before is ignored.

bigchaindb_driver.offchain.prepare_create_transaction(*, owners_before, owners_after=None, asset=None, metadata=None)

Prepares a "CREATE" transaction payload, ready to be fulfilled.

Parameters:

• owners_before (list | tuple | str) – One or more public keys representing the issuer(s) of the asset being created.
• owners_after (list | tuple | str, optional) – One or more public keys representing the new owner(s) of the asset being created. Defaults to None.
• asset (dict, optional) – The asset being created. Defaults to None.
• metadata (dict, optional) – Metadata associated with the transaction. Defaults to None.

Returns:

The prepared "CREATE" transaction.

Return type:

dict

Important

If owners_after is not given, or evaluates to False, it will be set equal to owners_before:

if not owners_after:
    owners_after = owners_before

bigchaindb_driver.offchain.prepare_transfer_transaction(*, inputs, owners_after, asset, metadata=None)

Prepares a "TRANSFER" transaction payload, ready to be fulfilled.

Parameters:

• inputs (dict | list | tuple) – One or more inputs holding the condition(s) that this transaction intends to fulfill. Each input is expected to be a dict.
• owners_after (str | list | tuple) – One or more public keys representing the new owner(s) of the asset being transferred.
• asset (dict) – The asset being transferred.
• metadata (dict) – Metadata associated with the transaction. Defaults to None.

Returns:

The prepared "TRANSFER" transaction.

Return type:

dict

Example

In case it may not be clear what an input should look like, say Alice (public key: '3Cxh1eKZk3Wp9KGBWFS7iVde465UvqUKnEqTg2MW4wNf') wishes to transfer an asset over to Bob (public key: 'EcRawy3Y22eAUSS94vLF8BVJi62wbqbD9iSUSUNU9wAA'). Let the asset creation transaction payload be denoted by tx:

# noqa E501
>>> tx
{'id': '57cff2b9490468bdb6d4767a1b07905fdbe18d638d9c7783f639b4b2bc165c39',
 'transaction': {'asset': {'data': {'msg': 'Hello BigchainDB!'},
   'divisible': False,
   'id': 'd04b05de-774c-4f81-9e54-6c19ed3cd18d',
   'refillable': False,
   'updatable': False},
  'conditions': [{'amount': 1,
    'cid': 0,
    'condition': {'details': {'bitmask': 32,
      'public_key': '3Cxh1eKZk3Wp9KGBWFS7iVde465UvqUKnEqTg2MW4wNf',
      'signature': None,
      'type': 'fulfillment',
      'type_id': 4},
     'uri': 'cc:4:20:IMe7QSL5xRAYIlXon76ZonWktR0NI02M8rAG1bN-ugg:96'},
    'owners_after': ['3Cxh1eKZk3Wp9KGBWFS7iVde465UvqUKnEqTg2MW4wNf']}],
  'fulfillments': [{'fid': 0,
    'fulfillment': 'cf:4:IMe7QSL5xRAYIlXon76ZonWktR0NI02M8rAG1bN-ughA8-9lUJYc_LGAB_NtyTPCCV58LfMcNZ9-0PUB6m1y_6pgTbCOQFBEeDtm_nC293CbpZjziwq7j3skrzS-OiAI',
    'input': None,
    'owners_before': ['3Cxh1eKZk3Wp9KGBWFS7iVde465UvqUKnEqTg2MW4wNf']}],
  'metadata': None,
  'operation': 'CREATE',
  'timestamp': '1479393278'},
 'version': 1}

Then, the input may be constructed in this way:

cid = 0
condition = tx['transaction']['conditions'][cid]
input_ = {
    'fulfillment': condition['condition']['details'],
    'input': {
        'cid': cid,
        'txid': tx['id'],
    },
    'owners_before': condition['owners_after'],
}

Displaying the input on the prompt would look like:

>>> input_
{'fulfillment': {'bitmask': 32,
  'public_key': '3Cxh1eKZk3Wp9KGBWFS7iVde465UvqUKnEqTg2MW4wNf',
  'signature': None,
  'type': 'fulfillment',
  'type_id': 4},
 'input': {'cid': 0,
  'txid': '57cff2b9490468bdb6d4767a1b07905fdbe18d638d9c7783f639b4b2bc165c39'},
 'owners_before': ['3Cxh1eKZk3Wp9KGBWFS7iVde465UvqUKnEqTg2MW4wNf']}

To prepare the transfer:

>>> prepare_transfer_transaction(
...     inputs=input_,
...     owners_after='EcRawy3Y22eAUSS94vLF8BVJi62wbqbD9iSUSUNU9wAA',
...     asset=tx['transaction']['asset'],
... )

bigchaindb_driver.offchain.fulfill_transaction(transaction, *, private_keys)

Fulfills the given transaction.

Parameters:

• transaction (dict) – The transaction to be fulfilled.
• private_keys (str | list | tuple) – One or more private keys to be used for fulfilling the transaction.

Returns:

The fulfilled transaction payload, ready to be sent to a BigchainDB federation.

Return type:

dict

Raises:

MissingSigningKeyError – If a private key, (aka signing key), is missing.

transport

class bigchaindb_driver.transport.Transport(*nodes)

Transport class.

__init__(*nodes)

Initializes an instance of Transport.

Parameters:nodes – nodes

forward_request(method, path=None, json=None)

Forwards an http request to a connection.

Parameters:

• method (str) – HTTP method name (e.g.: 'GET'.
• path (str) – Path to be appended to the base url of a node. E.g.: '/transactions'.
• json (dict) – Payload to be sent with the HTTP request.

Returns:

Result of requests.models.Response.json()

Return type:

dict

get_connection()

Gets a connection from the pool.

Returns:A Connection instance.

init_pool(nodes)

Initializes the pool of connections.

pool

class bigchaindb_driver.pool.Pool(connections, picker_class=<class 'bigchaindb_driver.pool.RoundRobinPicker'>)

Pool of connections.

__init__(connections, picker_class=<class 'bigchaindb_driver.pool.RoundRobinPicker'>)

Initializes a Pool instance.

Parameters:connections (list) – List of Connection instances.

get_connection()

Gets a Connection instance from the pool.

Returns:A Connection instance.

class bigchaindb_driver.pool.RoundRobinPicker

Object to pick a Connection instance from a list of connections.

picked

str

List index of Connection instance that has been picked.

__init__()

Initializes a RoundRobinPicker instance. Sets picked to -1.

pick(connections)

Picks a Connection instance from the given list of Connection instances.

Parameters:connections (List) – List of Connection instances.

class bigchaindb_driver.pool.AbstractPicker

Abstract class for picker classes that pick connections from a pool.

pick(connections)

Picks a Connection instance from the given list of Connection instances.

Parameters:connections (List) – List of Connection instances.

connection

class bigchaindb_driver.connection.Connection(*, node_url)

A Connection object to make HTTP requests.

__init__(*, node_url)

Initializes a Connection instance.

Parameters:node_url (str) – Url of the node to connect to.

request(method, *, path=None, json=None, **kwargs)

Performs an HTTP requests for the specified arguments.

Parameters:

• method (str) – HTTP method (e.g.: ‘GET‘.
• path (str) – API endpoint path (e.g.: ‘/transactions’.
• json (dict) – JSON data to send along with the request.
• kwargs – Optional keyword arguments.

crypto

class bigchaindb_driver.crypto.CryptoKeypair(signing_key, verifying_key)

__getnewargs__()

Return self as a plain tuple. Used by copy and pickle.

__getstate__()

Exclude the OrderedDict from pickling

static __new__(_cls, signing_key, verifying_key)

Create new instance of CryptoKeypair(signing_key, verifying_key)

__repr__()

Return a nicely formatted representation string

signing_key

Alias for field number 0

verifying_key

Alias for field number 1

bigchaindb_driver.crypto.generate_keypair()

Generates a cryptographic key pair.

Returns:A collections.namedtuple with named fields signing_key and verifying_key. Return type:CryptoKeypair

exceptions

Exceptions used by bigchaindb_driver.

exception bigchaindb_driver.exceptions.BigchaindbException

Base exception for all Bigchaindb exceptions.

exception bigchaindb_driver.exceptions.TransportError

Base exception for transport related errors.

This is mainly for cases where the status code denotes an HTTP error, and for cases in which there was a connection error.

exception bigchaindb_driver.exceptions.ConnectionError

Exception for errors occurring when connecting, and/or making a request to Bigchaindb.

exception bigchaindb_driver.exceptions.NotFoundError

Exception for HTTP 404 errors.

exception bigchaindb_driver.exceptions.KeypairNotFoundException

Raised if an operation cannot proceed because the keypair was not given.

exception bigchaindb_driver.exceptions.InvalidSigningKey

Raised if a signing key is invalid. E.g.: None.

exception bigchaindb_driver.exceptions.InvalidVerifyingKey

Raised if a verifying key is invalid. E.g.: None.

exception bigchaindb_driver.exceptions.MissingSigningKeyError

Raised if a signing key is missing.

utils

Set of utilities to support various functionalities of the driver.

bigchaindb_driver.utils.ops_map

dict

Mapping between operation strings and classes. E.g.: The string 'CREATE' is mapped to CreateOperation.

class bigchaindb_driver.utils.CreateOperation

Class representing the 'CREATE' transaction operation.

class bigchaindb_driver.utils.TransferOperation

Class representing the 'TRANSFER' transaction operation.

bigchaindb_driver.utils._normalize_asset(asset, is_transfer=False)

Normalizes the given asset dictionary.

For now, this means converting the given asset dictionary to a Asset class.

Parameters:

• asset (dict) – The asset to normalize.
• is_transfer (boal, optional) – Flag used to indicate whether the asset is to be used as part of a ‘TRANSFER’ operation or not. Defaults to False.

Returns:

The Asset class, instantiated from the given asset dictionary.

Important

If the instantiation step fails, None may be returned.

Danger

For specific internal usage only. The behavior is tricky, and is subject to change.

bigchaindb_driver.utils._normalize_operation(operation)

Normalizes the given operation string. For now, this simply means converting the given string to uppercase, looking it up in ops_map, and returning the corresponding class if present.

Parameters:operation (str) – The operation string to convert. Returns:The class corresponding to the given string, CreateOperation or TransferOperation.

Important

If the str.upper() step, or the ops_map lookup fails, the given operation argument is returned.

Danger

For specific internal usage only. The behavior is tricky, and is subject to change.