Skip to main content

This article was originally published in DZone.

We took the example of Modex Blockchain Database (BCDB). Is an application which intervenes in the development stack by positioning itself between the database and the existing application server. In a classical flow scheme, the front end application makes API calls to an application server which in turn makes calls to the database. Most often these interactions are represented by the standard CRUD operations performed in a database system. Modex BCDB is a hybrid solution that acts as a liaison between a client’s database and a blockchain network.

After implementing our solution, insert commands still follow the paradigm of classic database systems, but each data entry passes through a hashing function that produces a unique hash that is stored into the blockchain to ensure data integrity and transform a centralized system into a decentralized one. In essence, a beneficiary maintains their data structure intact at the database level but gains access to all of the advantages of blockchain technology by storing their hash in a blockchain.

The advantages of this approach are clear cut. Traditionally, if someone tampers with your database, be it an external attacker, or someone from within the company who has clearance to access the database and wants to corrupt, hijack or ransom the data, they can pretty much do so at their leisure once they get in. But if you implement a solution like Modex BCDB which stores the hash of the information on a blockchain, any changes will ultimately be obsolete.

As most of you already know, hashing a string produces a unique hash digest that cannot be reversed to reveal the original input. If an attacker modifies an entry in the database, the hash of that data will also change, so when the system compares the new hash with the old one, it will reject any unauthorized changes, and recover the data from other nodes from the network. Besides the benefits that come with decentralization, the data can now be accessed much faster, regardless of geographical position, because through Modex BCDB the information is now physically decentralized across multiple nodes.

This is how Modex BCDB works at the database level. In the next segment of the article, we will showcase how to install and configure a Modex BCDB system. Keep in mind that we will demonstrate how to open a local test network. This guide will not describe how to install each node on a different machine, the focus will be on how to install the system to run on docker containers. This way we replicate the phenomenon as if it were on different machines when in actuality it runs on a single machine in docker containers.

Before getting started, make sure that your machine falls within the minimum hardware requirements: CPU of at least 4 cores bigger than 2.6Ghz and 8GB RAM. Though we recommend 16GB RAM for a smoother performance. Furthermore, you also need to have a docker and a docker compose. We will provide the rest: Rabbit MQ, MongoDB, among other utilities.

Step by step installation

Firstly, you are required to make an account and download the Modex BCDB installer from our site At the moment we have an installer for Ubuntu, Modex BCDB can also be installed on Windows, but in this example, we will use the Ubuntu version since it is the first choice for most people when it comes to servers.

To begin installation run the following command:

sudo apt-get install ./bcdb-0.2.9-beta_linux_amd64.deb

Because we use dockers you need to run the following command to build the docker images.

sudo bcdb-build-images

This is done to build the Rabbit MQ and MongoDB images where the system runs the OAuth calls and every service and mechanism we use inside the application. After you run the command to build the docker images, we need to start the network. Once the network has been started, the system automatically inserts users and all the entities necessary for developers to configure their application. This can be done either directly programmatically by calling the API codes which can be found in our documentation ( ), or through the workbench that we have created as a front end application for network administrators.

To start the test network, run the following command:

sudo bcdb-start-test-net

We will now present how to configure the network, the node structure, licensing and other similar processes. The scope of this guide is to illustrate how a developer creates new users, entities and how to grant permissions.

Workbench usage and configuration

As a first time user, you need to log in using the default administrator user which is built once the network starts. Use the user name [email protected] and the default password admin.


After you have successfully logged in, you need to access the user management tab from the workbench to create the first user, the admin user who will be used as the default user. From this interface, you can create multiple users who can access the system. You can create admin users who have full access to the whole system, or standard users who you can grant permissions to access entities, fields, or special permissions, depending on their needs.

In our example, we will create a new user, [email protected]

aCdeP3vsTDT6ocAqg 83k H2GY64l47hyKUtgSaje7t a34rr4toiIawh6SiXnDtHuwjt7HLHcoxux5rAp5g4BYZltbprsCAR6XcGrnvvRH7nekuAAQUkpFlE9 J83S7WvdpldZN

After we create the user, we will also create a group. To do this, we access User Management, select the Groups tab and press the Add Groups button. The next step is to choose what users you want to include in the new group, set a name for the group and add a description to the users. As you can see, our example has only one user.

nOda6yTd3wTV2j34 1DgHri Cqp03EvwpQvzbZC6LLglPXs81P2PUWTbdxoBqOiYlujgamf3XTaNkEB

Now we will focus on building the entities. For the scope of this presentation, we will build two entities, Customer Schema and Account Schema. For the Customer entity, we have selected the name field to be the Primary Key. Keep in mind that you can select multiple keys for identity generation. In our context, the keys are attributed the identity keyword. As you can see, during the creation process you have the option to add more tags to a field, such as encrypted, store on blockchain, identity or RefEntity.

The later can be used to access another table from the blockchain. Because name is the first entity we have created, we identify it as the primary key. We have also created multiple fields such as description, age, role, where description and role are strings and age is a number. From the types of fields we can select: string, number, Boolean, array, basically any primary types that can be added to a field in a standard database system.

pWvKrWlIwZAxTVKXu7ZnW18kSSaZaqSC6YZNuC4 W nEVdSSZB N6mElEETmuahDHsWNE gWV1Rvp3C6yvp0Z0VmvU k32vbofzM8lBKPtSIQ4 QbDn5N9oOA92AtZPh XI5pFv

This is the JSON Schema for the Customer entity that is added in Modex BCDB

a5OJUcIBXJPYPasgqX0W6A2OJXM3qgjsnhEK4eUZk5 Mlk3d7SpUxxGppj6IcUNuc4Qj QhR5UZueuZUUhLRUI VOOHO4X5QNSevetkQjiIkaoz7Md0 UklDusq7JIzid0FNEXTi

Next, we will build the Account table. When creating the account table, we will no longer use as primary key a field from the table, instead, we will use an auto-generated primary key, auto ID. The fields in the account type will be description (string), balance (number), currency (string) and customer ID (string). The customer ID field is important because it is a foreign key that connects to the customer entity we have previously created. The foreign key contains a reference to the main ID of every entry in the customer entity. This information can be found in the metadata.recordId in the default MongoDB system.

89D9 Z1EiqYdyWwe5zjjvGYIEQGItHtNqkwj1vD1a9LUhLOkp9w9jB0SohyJCVeAtsSPfJjC4JobQ8Z8EHeDfJY9lEsquCF6XMn9GPyG5W8k KcK2 cR65opJVQ6JCeVoAa2EZE4

This is how the Account JSON Schema looks like after creation.

O2ucIwl9VV9Ll2twXaazz fkl4mcWhcdB0XkJS2hvSECRcoiBiVktzuv9HKDxrFec Sl TzLSZUVjlllqivaHzBp4oRpDhG6CNwy3nSKlN256xvnAyIp9wAMbfiUGIN4 fpS 1W

After we have created the customer and account tables, we will grant access permissions to the group of users we have previously created. To do this you need to access the Permission Management, Entity Data Access tab from the workbench. Once here, select from the drop-down the entity you are referring to, in our case, the customer entity. Press Add Group button and select the group you want to grant access to the customer entity, and the type of permission you want to give. In this example, we will give write permissions.

You also have the option to grant a user permission to encrypt and decrypt information from the table. In our example, our table structure isn’t configured to include encryption and decryption fields, but developers can choose to do so.

We repeat the same process for the account table, the only difference being that instead of selecting Customer from the drop-down, you select Account.

3Om ga9YkdbTxnFy9u6irtogyV1Ry0

How to use Modex BCDB

Now you are ready to use the application in developer mode. Developers have the option to use the application in several ways: to make direct calls in the API; to use our libraries and HTTP drivers; to simplify the process front end users can use our GRAPHQL library. In this example, we will use Postman to make direct calls to the API. For more complex code examples, please check the documentation here:

In order to be able to make calls to entity inserts and other interactions, developers need to log in. With Postman, developers select the OAuth2 and request an authorization token. You are required to introduce in each field relevant information.

For Access Token URL you need to use the URL of our OAuth which can be found in the test network/token – this is where the request token is made. If Grant Type has Password Credentials selected, you are required to fill in Username and Password. You also need to specify Client ID and Client Secret . Their default configurations are 0x01 and 0x000001. After you have introduced all the relevant information, you are ready to make a token request.

2ePzndnuU0UAbOFV3mgB8ZXmgnovHPuf6wIXY8hlJ07B5 J6W 8qO558VVHI2hoEi60jESIqQVlgy AEDhjggr6J9h3W4ArHRZFFq0AC6vIdiIaQqvzJALSmgi8sTq73owBUhbUT

The token can be used to make successive inserts, updates and read operations from the system. To exemplify the process, we will make two inserts and two read operations.


First, we will insert an entity in the customer entity. The URL can be found in the description as well as in the official documentation of Modex BCDB. In our example we have set the previously generated token in the header, the body of the request contains information which we already specified, name, description, age, role.

After the request is posted, you will receive a screen with the following information: the ID represents the ID from the blockchain; metadata information; Metadata.recordId – the record ID from the metadata is the primary entity identifier which is generated from the entity fields; status which can be COMMITED or PENDING, the owner of the entity, when it was created and so on. The data field contains all the data we have previously inserted.

At the bottom of the screen, you can observe the fields validated and permission. Validated indicates if the field was validated against the blockchain, namely if the integrity check has been completed successfully. Permission indicates the type of permission that the current user has on the respective field. As you can see, we receive confirmation that the user has only WRITE permission.

Account insertions require a similar process. When performing account insertions, developers need to specify description, balance, currency and customer ID. At the customer ID field we need to take the record ID from the customer we have created, namely the entity identifier and make an insertion. The structure of the result will be similar to what we have already seen at customer insertions: metadata, data, validated and permissioned. Metadata holds the information in the current metadata, the data field holds the information per se and customer ID displays in clear text the previous record ID.

aQLJb crxTsC2udwjiHNAcaAPErVBOUGthVy 3Eqn 5t9QSHoJf3EuD4iV4 x2Y1bIqADbGQIvZQeyFs9he8ZddFtgo5xwL0Ny6HG 51aL6N NZoNS8CJy2jkPPqU238SdeGhMf1

Read operations

Read operations can be performed in multiple ways. An in-depth explanation can be found in the Modex BCDB documentation. In our example, we are going to read all the accounts present in our system. To read the account data we are going to use the list API using a POST call. This can be done by specifying the URL for the POST, Skip and Limit. In the body tab, we can add a complex filter, but because we have a single account in the system, we don’t need it, so we leave the filter empty and run the command in Postman.

As you can see it retrieves the account information we have previously introduced, but now we can observe that validated is true, which means that the information has been validated, it hasn’t been modified in the database, the hash matches the one stored in the blockchain. Now we can observe that status has changed to COMMITED, which means that the information has been successfully committed inside the blockchain.

5X8OxkiqJCL5FZoSbnVxxg3WgAo0oy5ZJ09 r NJ1Csgg9qGJJT6pgTAO5A5zJzjigkMreDKbSCqb0QizBVIPXq wBmXSNWtxVL7drsv7z

When reading the customer table make a GET call to the API to retrieve the customer information associated with that specific account. We take the respective ID and add it to the URL. As you can see, the URL has changed /data/customer/our entity/record ID from the account information. After we run the command, the system will retrieve the relevant information in a structure similar to our previous example. At account read, we would have received more information because it was a listing. So in our current example, the system will display only the information associated with the record ID we specified in the URL.

rjpYQW7Ah vzGYP VsJgcTgx9RvLVNfZKOhHw7BUKk B9upZ0xaNW33ipT38m0Y2CCqyHTV1ABNxq0lsPkVEl 06j5zRIkElziDyy24F85qXXlHjtYaqk4JIJhPtWVFCgys77dy

This has been a basic overview of how to use Modex BCDB. All the examples provided in this guide were done with Postman, but as we have previously mentioned all these operations can be done directly with code regardless of the programming language, as long as it can make calls to an external API, and as long as basic programming standards are respected: initial authentication, using the token to make requests. Keep in mind that the full list of requests is available in the Modex BCDB documentation .