Conceptually, an input is a pointer to an output of a previous transaction. It specifies to whom an asset belonged before and it provides a proof that the conditions required to transfer the ownership of that asset (e.g., a person needs to sign) are fulfilled. In a CREATE transaction, there is no previous owner, so an input in a CREATE transaction simply specifies who the person is that is registering the object (this is usually the same as the initial owner of the asset). In a TRANSFER transaction, an input contains a proof that the user is authorized to spend (transfer or update) this particular output. In practical terms, this means that with the input, a user is stating which asset (e.g., the bike) should be transferred. He also demonstrates that he or she is authorized to do the transfer of that asset.


A transaction output specifies the conditions that need to be fulfilled to change the ownership of a specific asset. For instance: to transfer a bicycle, a person needs to sign the transaction with his or her private key. This also implicitly contains the information that the public key associated with that private key is the current owner of the asset.

The transaction can also have multiple outputs. These are called divisible assets. The output can also contain complex conditions (e.g., multiple signatures of multiple people) to acquire ownership.


The metadata field allows users to add additional data to a transaction. This can be any type of data, like the age of a bicycle or the kilometers driven [11]. The good thing about the metadata is that it can be updated with every transaction. In contrast to the data in the asset field, the metadata field allows to add new information to every transaction.

Transaction ID

The ID of a transaction is a unique hash that identifies a transaction. It contains all the information about the transaction in a hashed way.

Getting Started

Begin by creating an object of class BigchainDB:

In [1]: frombigchaindb_driverimportBigchainDB

In [2]: bdb_root_url=''#Use YOUR

BigchainDB Root URL here

If the BigchainDB node or cluster doesn’t require authentication tokens, you can do: In [3]: bdb=BigchainDB(bdb_root_url)

If it does require authentication tokens, you can do put them in a diet like so:

In [4]: tokens={'app_id':'your_app_id','app_key':'your_app_key'} In [5]: bdb=BigchainDB(bdb_root_url, headers=tokens)

Digital Asset Definition

As an example, let’s consider the creation and transfer of a digital asset that represents a bicycle:

In [6]: bicycle={

...: 1 data':{

...: 1 bicycle':{

...: 1serial_number':'abcdl234',

...: 'manufacturer':'bkfab',

Suppose a bike belongs to Alice and that it will be transferred to Bob. In general, use any dictionary for the data property.

Metadata Definition (Optional)

You can optionally add metadata to a transaction. Any dictionary is accepted.

For example:

In [7]: metadata={'planetearth'}

Asset Creation

Create the digital asset. First, prepare the transaction:

In [10]: prepared_creation_tx=bdb.transactions.prepare(

....: operation=1 CREATE 1,

....: signers=alice,public_key,

....: asset=bicycle,

....: metadata=metadata,


The prepared_creation_tx dictionary should be similar to

In [11]: prepared_creation_tx Out[11]:

{'asset': {'data': {'bicycle': {'manufacturer': 'bkfab',

'serial_number': 'abcdl234'}}},

'id': None,

'inputs': [{'fulfillment': {'public_key':

' 7rr59L64LwwMKr8dtieotdugkl3oHkosFFoTuXCj zz6 ',

'type': 'ed255l9-sha-256'},

'fulfills': None,

'owners_before': ['7rr59L64LvvwMKr8dtieotdugkl3oHkosFFoTuXCj

zz6 ' ] }] ,

'metadata': {'planet': 'earth'},

'operation': 'CREATE',

'outputs': [{'amount': '1',

'condition': {'details': {'public_key': '7rr59L64LwwMKr8

dtieotdugkl3oHkosFFoTuXCjzz6' ,

'type': 'ed255l9-sha-256'},

'uri' : 'ni:///sha-56;e2COOfzLhNG_nLwWVmZOyGbIQ61qDCduYZy7HKPr2 3c?fpt=ed255l9-sha-256&cost=13l072'},

'public_keys': ['7rr59L64LwwMKr8dtieotdugkl3oHkosFFoTuXCj

ZZ6'1 }] ,

'version': '2.0'}

The transaction now needs to be fulfilled by signing it with Alice’s private key:

In [12]: fulfilled_creation_tx=bdb.transactions.fulfill(

....: prepared_creation_tx, private_keys=alice.private_key)

In [13]: fulfilled_creation_tx


{'asset': {'data': {'bicycle': {'manufacturer': 'bkfab',

'serial_number': 'abcdl234'}}},

'id': 'bfe679e84f528410270fe67d309fl9d03afe09970650140621d


1 inputs 1: [{1 fulfillment1: 1pGSAIGXrEQNtYgyzOBswGHnoWgbU

WFWVE89Kez 25zti91PTzgUDY8sy8E9FtHw09-nab89wBspemhBCshbbRR JqLlqilTQ7Hb JZYMfr8_mawfTDre3lpJEgLSrqFU-clmJjkrwUO1,

  • 1 fulfills 1: None,
  • 1owners_before1: [17rr59L64LwwMKr8dtieotdugkl3oHkosFFoTuXCj zz6 1 ] }] ,

'metadata': {'planet': 'earth'},

'operation' : 'CREATE',

'outputs': [{'amount': '1',

'condition': {'details': {'public_key':

' 7rr59L64LwwMKr8dtieotdugkl3oHkosFFoTuXCj zz6 ',

'type': 'ed255l9-sha-256'},

'uri' : 'ni:///sha-2 56;e2C00f zLhNG_nLwWVmZOyGbIQ61qDCduYZy7HK


'public_keys': ['7rr59L64LwwMKr8dtieotdugkl3oHkosFFo

Tuxcjzz6' ] }] ,

'version': '2.0'}

And sent over to a BigchainDB node:

>>>sent_creation_tx=bdb.transactions.send_commit (fulfilled_creation_tx)

Note that the response from the node should be the same as that which was sent:

>>>sent_creation_tx==fulf illed_creation_tx True

Notice the transaction id:

In [14]: txid=fulfilled_creation_tx['id']

In [15] : txid

Out [15] : 'bfe679e84f528410270fe67d3 0 9fl9d03afe09970650140621


Check if the Transaction was sent successfully

After a couple of seconds, we can check if the transaction was included in a block.

# Retrieve the block height


This will return the block height containing the transaction. If the transaction is not in any block then None is returned. If it is None, it can have different reasons for example the transaction was not valid or is still in the queue and you can try again later. If the transaction was invalid or could not be sent an exception is raised.

If we want to see the whole block we can use the block height to retrieve the block itself.

# Retrieve the block that contains the transaction >>>block=bdb.blocks.retrieve(str(block_height))

Asset Transfer

Imagine some time goes by, during which Alice is happy with her bicycle, and one day she meets Bob, who is interested in acquiring her bicycle. The timing is good for Alice as she wanted to get a new bicycle [12].

To transfer the bicycle (asset) to Bob, Alice must consume the transaction in which the Bicycle asset was created.

Alice could retrieve the transaction:


or simply use fulfilled_creation_tx :

In [16]:creation_tx=fulfilled_creation_tx

In order to prepare the transfer transaction, we first need to know the id of the asset we’ll be transferring. Here, because Alice is consuming a |CREATE| transaction, we have a special case in that the asset id is NOT found on the asset | itself, but is simply the |CREATE| transaction’s id:

In [17]:asset_id=creation_tx['id']

In [18]:transfer_asset={

....: 'id1:asset_id,


Let’s now prepare the transfer transaction:

In [19]: output_index=0

In [20]: output=creation_tx['outputs'][output_index]

In [21]: transfer_input={

....: 'fulfillment':output['condition'] ['details 1],

. . . . : 'fulfills' : {

....: 1output_index1:output_index,

....: 1transaction_id1:creation_tx['id'],

. . . . : 'owners_before':output['public_keys ' ],


In [22]: prepared_transfer_tx=bdb.transactions.prepare(

....: operation='TRANSFER',

....: asset=transfer_asset,

....: inputs=transfer_input,

....: recipients=bob.public_key,


fulfill it:

In [23]: fulfilled_transfer_tx=bdb.transactions.fulfill(

....: prepared_transfer_tx,

....: private_keys=alice.private_key,


The fulfilled_transfer_tx dictionary should look something like:

In [24] : fulfilled_transfer_tx Out[24]:

{'asset': {'id': 'bfe679e84f5284l0270fe67d309fI9d03afe09

97065014062ldaedfe6f546598'} ,

'id': 'fb745cf6b645f5a20a82a4ladef835ce66913cc6ldd0lb2830085d


'inputs': [{'fulfillment': 'pGSAIGXrEQNtYgyzOBswGHno

WgbUWFWVE 89Kez25zti9lPTzgUBuHqMbJO 6C2vm9aBcaz90 CBXpg PZ-FQPrFLeGURN77an7Ej YXGvLGeUhf-fTB9uZvpYs6utzhZPt 24rdSJJXQC',

'fulfills': {'output_index': 0,


'bfe679e84f528410270fe67d309fl9d03afe09970 650140621 daedfe6f546598 '},

1owners_before': ['7rr59L64LwwMKr8dtieotdugkl3oHkos

FFoTuXCj ZZ6'1 }] ,

'metadata': None,

'operation': 'TRANSFER',

'outputs': [{'amount': '1',

'condition': {'details': {'public_key': 'SRaeQAZEEQMFCLBEDr Ktk5p Lue4SuVkdw9Xb55ucpvQ6',

'type': 'ed255l9-sha-2561},

'uri': 'ni:///sha-256;UKI3FbYGLQhOeu3QkZNuoWrjxGugzG4q7LxnhV qevHU? fpt=ed255l9-sha-256&cost=13l072' },

1public_keys1: ['5RaeQAZEEQMFCLBEDrKtk5pLue4SuVkdw9Xb55


'version': '2.0'}

and finally, send it to the connected BigchainDB node:





Bob is the new owner:

In [25]: fulfilled_transfer_tx['outputs'][0]['public_keys']

[0]==bob.public_key Out[25]:True

Alice is the former owner:

In [26]: fulfilled_transfer_tx['inputs'][0] ['owners_before']

[0]==alice,public_key Out[26]:True


Obtaining asset ids:

You might have noticed that we considered Alice’s case of consuming a | CREATE transaction as a special case. In order to obtain the asset id of a | CREATE] transaction, we had to use the CREATE] transaction’s id:


If you instead wanted to consume TRANSFER] transactions (e.g., fulfilled_transfer_tx|), you could obtain the asset id to transfer from the asset[‘id’] property:


< Prev   CONTENTS   Source   Next >