A Developer’s Guide to Modex BCDB


Modex 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.

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 user maintains its data structure at the database level but gains access to all of the advantages of blockchain technology by storing its 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, data can now be accessed much faster, regardless of geographical position because, through Modex BCDB, information is now physically decentralized across multiple nodes.

You may also like: An Overview of Modex BCDB for Deploying Blockchain Solutions.

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. However, we recommend 16GB RAM for a smoother performance. Furthermore, you also need to have 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 https://modex.tech/bcdb-download-installer/. 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 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 by calling the API codes, which can be found in our documentation (https://modex.tech/bcdb-developers/ ), 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 and 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 bcdb.admin@modex.tech and the default password admin.

Signing into Modex BCDB

Signing into Modex BCDB

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, dan.popescu@modex.tech.

Creating a new user

Creating a new user

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.

Choosing users

Choosing users

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 to 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 latter 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, and role, where description and role are strings and age is a number. For 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.

Adding an entity

Adding an entity

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

Customer JSON schema

Customer entity JSON schema

Next, we will build the Account table. When creating the it, 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.

Adding an entity

Adding an entity

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

Account schema

Account schema

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 and Entity Data Access tab from the workbench. Once there, select from the drop-down the entity you are referring to. In our case, it’s the customer entity.

Press the 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 them. 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.

Choosing a group

Choosing a group

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: https://bcdb.modex.tech/docs/#/api-guide/rest-api https://bcdb.modex.tech/docs/api-guide/specs/data-api.html https://bcdb.modex.tech/docs/api-guide/specs/auth-api.html.

In order to be able to make calls to entity inserts and other interactions, developers need to log in. With Postman, developers select OAuth2 and request an authorization token. You are required to introduce relevant information in each field. For the 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.

Getting a new access token

Getting a new access token

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, while the body of the request contains information, which we already specified, such as 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.

POST operation

POST operation

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, as the hash matches the one stored in the blockchain. Now, we can observe that status has changed to COMMITTED, which means that the information has been successfully committed inside the blockchain.

Status changed to Committed

Status changed to Committed

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.

Making a GET call

Making a GET call

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 https://modex.tech/bcdb-developers/.

Further Reading

This UrIoTNews article is syndicated fromDzone