Library Reference

driver

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

Bases: object

BigchainDB driver class.

A BigchainDB driver is able to create, sign, and submit transactions to one or more nodes in a Federation.

If initialized with >1 nodes, the driver will send successive requests to different nodes in a round-robin fashion (this will be customizable in the future).

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

Initialize a BigchainDB driver instance.

Parameters:

• *nodes (str) – BigchainDB nodes to connect to. Currently, the full URL must be given. In the absence of any node, the default ('http://localhost:9984') will be used.
• transport_class – Optional transport class to use. Defaults to Transport.
• headers (dict) – Optional headers that will be passed with each request. To pass headers only on a per-request basis, you can pass the headers to the method of choice (e.g. BigchainDB().transactions.send()).

api_info(headers=None)

Retrieves information provided by the API root endpoint '/api/v1'.

Parameters:headers (dict) – Optional headers to pass to the request. Returns:Details of the HTTP API provided by the BigchainDB server. Return type:dict

info(headers=None)

Retrieves information of the node being connected to via the root endpoint '/'.

Parameters:headers (dict) – Optional headers to pass to the request. Returns:Details of the node that this instance is connected to. Some information that may be interesting:

• the server version,
• the public key of the node, and
• its key ring (list of public keys of the nodes this node is connected to).

Return type:dict

Note

Currently limited to one node, and will be expanded to return information for each node that this instance is connected to.

nodes

tuple of str: URLs of connected nodes.

outputs

OutputsEndpoint: Exposes functionalities of the '/outputs' endpoint.

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)

Bases: bigchaindb_driver.driver.NamespacedDriver

Exposes functionality of the '/transactions/' endpoint.

path

str

The path of the endpoint.

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:

MissingPrivateKeyError – If a private key is missing.

get(*, asset_id, operation=None, headers=None)

Given an asset id, get its list of transactions (and optionally filter for only 'CREATE' or 'TRANSFER' transactions).

Parameters:

• asset_id (str) – Id of the asset.
• operation (str) – The type of operation the transaction should be. Either 'CREATE' or 'TRANSFER'. Defaults to None.
• headers (dict) – Optional headers to pass to the request.

Note

Please note that the id of an asset in BigchainDB is actually the id of the transaction which created the asset. In other words, when querying for an asset id with the operation set to 'CREATE', only one transaction should be expected. This transaction will be the transaction in which the asset was created, and the transaction id will be equal to the given asset id. Hence, the following calls to retrieve() and get() should return the same transaction.

>>> bdb = BigchainDB()
>>> bdb.transactions.retrieve('foo')
>>> bdb.transactions.get(asset_id='foo', operation='CREATE')

Since get() returns a list of transactions, it may be more efficient to use retrieve() instead, if one is only interested in the 'CREATE' operation.

Returns:List of transactions. Return type:list

static prepare(*, operation='CREATE', signers=None, recipients=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'.
• signers (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.
• recipients (list | tuple | str, optional) – One or more public keys representing the new recipients(s) of the asset being created or transferred. Defaults to None.
• asset (dict, optional) – The asset to be 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

• signers MUST be set.

• recipients, asset, and metadata MAY be set.

• If asset is set, it MUST be in the form of:

  {
      'data': {
          ...
      }
  }
  

• The argument inputs is ignored.

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

  if not recipients:
      recipients = signers
  

TRANSFER operations

• recipients, asset, and inputs MUST be set.

• asset MUST be in the form of:

  {
      'id': '<Asset ID (i.e. TX ID of its CREATE transaction)>'
  }
  

• metadata MAY be set.

• The argument signers is ignored.

retrieve(txid, headers=None)

Retrieves the transaction with the given id.

Parameters:

• txid (str) – Id of the transaction to retrieve.
• headers (dict) – Optional headers to pass to the request.

Returns:

The transaction with the given id.

Return type:

dict

send(transaction, headers=None)

Submit a transaction to the Federation.

Parameters:

• transaction (dict) – the transaction to be sent to the Federation node(s).
• headers (dict) – Optional headers to pass to the request.

Returns:

The transaction sent to the Federation node(s).

Return type:

dict

status(txid, headers=None)

Retrieves the status of the transaction with the given id.

Parameters:

• txid (str) – Id of the transaction to retrieve the status for.
• headers (dict) – Optional headers to pass to the request.

Returns:

A dict containing a ‘status’ item for the transaction.

Return type:

dict

class bigchaindb_driver.driver.OutputsEndpoint(driver)

Bases: bigchaindb_driver.driver.NamespacedDriver

Exposes functionality of the '/outputs' endpoint.

path

str

The path of the endpoint.

get(public_key, unspent=False, headers=None)

Parameters:

• public_key (str) – Public key for which unfulfilled conditions are sought.
• unspent (bool) – Whether to get the unconsumed outputs only. Defaults to False, meaning that both consumed, and unconsumed outputs will be returned.
• headers (dict) – Optional headers to pass to the request.

Returns:

List of unfulfilled conditions.

Return type:

list of str

Example

Given a transaction with id da1b64a907ba54 having an ed25519 condition (at index 0) with alice’s public key:

>>> bdb = BigchainDB()
>>> bdb.unspents.get(alice_pubkey)
... ['../transactions/da1b64a907ba54/conditions/0']

class bigchaindb_driver.driver.NamespacedDriver(driver)

Bases: object

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', signers=None, recipients=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'.
• signers (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.
• recipients (list | tuple | str, optional) – One or more public keys representing the new recipients(s) of the asset being created or transferred. Defaults to None.
• asset (dict, optional) – The asset to be 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

• signers MUST be set.

• recipients, asset, and metadata MAY be set.

• If asset is set, it MUST be in the form of:

  {
      'data': {
          ...
      }
  }
  

• The argument inputs is ignored.

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

  if not recipients:
      recipients = signers
  

TRANSFER operations

• recipients, asset, and inputs MUST be set.

• asset MUST be in the form of:

  {
      'id': '<Asset ID (i.e. TX ID of its CREATE transaction)>'
  }
  

• metadata MAY be set.

• The argument signers is ignored.

bigchaindb_driver.offchain.prepare_create_transaction(*, signers, recipients=None, asset=None, metadata=None)

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

Parameters:

• signers (list | tuple | str) – One or more public keys representing the issuer(s) of the asset being created.
• recipients (list | tuple | str, optional) – One or more public keys representing the new recipients(s) of the asset being created. Defaults to None.
• asset (dict, optional) – The asset to be 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 asset is set, it MUST be in the form of:

  {
      'data': {
          ...
      }
  }
  

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

  if not recipients:
      recipients = signers
  

bigchaindb_driver.offchain.prepare_transfer_transaction(*, inputs, recipients, 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.
• recipients (str | list | tuple) – One or more public keys representing the new recipients(s) of the asset being transferred.
• asset (dict) – A single-key dictionary holding the id of the asset being transferred with this transaction.
• metadata (dict) – Metadata associated with the transaction. Defaults to None.

Returns:

The prepared "TRANSFER" transaction.

Return type:

dict

Important

• asset MUST be in the form of:

  {
      'id': '<Asset ID (i.e. TX ID of its CREATE transaction)>'
  }
  

Example

Todo

Replace this section with docs.

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!'},
   'id': '57cff2b9490468bdb6d4767a1b07905fdbe18d638d9c7783f639b4b2bc165c39'},
  '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_,
...     recipients='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:

MissingPrivateKeyError – If a private key is missing.

transport

class bigchaindb_driver.transport.Transport(*nodes, headers=None)

Bases: object

Transport class.

__init__(*nodes, headers=None)

Initializes an instance of Transport.

Parameters:

• nodes – nodes
• headers (dict) – Optional headers to pass to the Connection instances, which will add it to the headers to be sent with each request.

forward_request(method, path=None, json=None, params=None, headers=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.
• params (dict) – Dictionary of URL (query) parameters.
• headers (dict) – Optional headers to pass to the 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, headers=None)

Initializes the pool of connections.

pool

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

Bases: object

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

Bases: bigchaindb_driver.pool.AbstractPicker

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

Bases: object

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, headers=None)

Bases: object

A Connection object to make HTTP requests.

__init__(*, node_url, headers=None)

Initializes a Connection instance.

Parameters:

• node_url (str) – Url of the node to connect to.
• headers (dict) – Optional headers to send with each request.

request(method, *, path=None, json=None, params=None, headers=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.
• params (dict) – Dictionary of URL (query) parameters.
• headers (dict) – Optional headers to pass to the request.
• kwargs – Optional keyword arguments.

crypto

class bigchaindb_driver.crypto.CryptoKeypair(private_key, public_key)

Bases: tuple

__getnewargs__()

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

__getstate__()

Exclude the OrderedDict from pickling

static __new__(_cls, private_key, public_key)

Create new instance of CryptoKeypair(private_key, public_key)

__repr__()

Return a nicely formatted representation string

private_key

Alias for field number 0

public_key

Alias for field number 1

bigchaindb_driver.crypto.generate_keypair()

Generates a cryptographic key pair.

Returns:A collections.namedtuple with named fields private_key and public_key. Return type:CryptoKeypair

exceptions

Exceptions used by bigchaindb_driver.

exception bigchaindb_driver.exceptions.BigchaindbException

Bases: Exception

Base exception for all Bigchaindb exceptions.

exception bigchaindb_driver.exceptions.TransportError

Bases: bigchaindb_driver.exceptions.BigchaindbException

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

Bases: bigchaindb_driver.exceptions.TransportError

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

exception bigchaindb_driver.exceptions.NotFoundError

Bases: bigchaindb_driver.exceptions.TransportError

Exception for HTTP 404 errors.

exception bigchaindb_driver.exceptions.KeypairNotFoundException

Bases: bigchaindb_driver.exceptions.BigchaindbException

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

exception bigchaindb_driver.exceptions.InvalidPrivateKey

Bases: bigchaindb_driver.exceptions.BigchaindbException

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

exception bigchaindb_driver.exceptions.InvalidPublicKey

Bases: bigchaindb_driver.exceptions.BigchaindbException

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

exception bigchaindb_driver.exceptions.MissingPrivateKeyError

Bases: bigchaindb_driver.exceptions.BigchaindbException

Raised if a private 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

Bases: object

Class representing the 'CREATE' transaction operation.

class bigchaindb_driver.utils.TransferOperation

Bases: object

Class representing the 'TRANSFER' transaction operation.

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.