IOV-core: Friendly Blockchain Communication Protocol

From the IOV whitepaper 📓 we can read:

“Blockchain Communication Protocol: a set of standards that each blockchain implements;

All blockchains adhering to the Blockchain Communication Protocol will be directly compatible with the IOV Wallet. Anyone wishing to create their own token only needs to follow the Blockchain Communication Protocol.”

Now, how do we implement this with our own project?

BCP Example: add MyBlockchain to IOV

The main idea of this example, is try to understand the steps required to add MyBlockchain to the IOV ecosystem. And we will specifically use the iov-faucet to do that.

Basically, at current faucet release v0.5.1, with the same build you can connect to:

• a local tendermint node running in localhost:23456 :

FAUCET_MNEMONIC="<secret bns mnemonic>" 
./bin/iov-faucet start bns ws://localhost:23456

• a local ethereum node running in localhost:7585

FAUCET_MNEMONIC="<secret eth mnemonic>" 
./bin/iov-faucet start ethereum http://localhost:8545

Side note 1: For those who are not yet impressed, bns is based on Ed25519 and ethereum in Secp256k1 and, just in case, faucet uses SLIP-0010 to handle mnemonics and BIP43 for derivation paths. 😎

• (and with the steps explained in the following lines) a local myblockchain running in localhost:3000

FAUCET_MNEMONIC="<secret myblockchain mnemonic>" 
./bin/iov-faucet start myblockchain http://localhost:3000

In order to get this myblockchain running, we need to add some logic to faucet and to iov-core, so let us start with the core

Side note 2: For those who are not yet impressed, the impact of connecting your blockchain to an ecosystem of tools that currently operates with cosmos and ethereum at the same time and will add more integrations in the future…is pretty high. 🎁

Add MyBlockchain to iov-core?

What is iov-core?
From main repo readme we have:
“This repo provides core functionality to all clients in a cross-platform typescript library.”

Here you will need to add myblockchain to iov-core. First things first: go to iov-core issues, create an issue to signal to the team that you are working in a new package to add myblockchain to iov ecosystem, so others can use it.

Add this todo list to the body of the issue, to track your progress:

Now, clone the project and install dependencies:

git clone https://github.com/iov-one/iov-core.git
cd iov-core
git checkout v0.13.3
yarn install

In iov-core/packages you need to create a new folder: myblockchain and add the following files:

Get ready, because now we will start the deep dive.

Add Codec

If you check some examples, like ethereumcodec.ts, liskcodec.ts, bnscodec or even the father of them iov-bcp/codec.ts, you will see the main entry point and the required api for this codec.

So let us add some structures to myblockchaincodec.ts.
We can do it as a constant or a class, we will follow the constant way on this example.

So far we generated a new codec that handles myblockchain, we can commit all and mark as done this task in the todo list, and also the one related to folder structure.

Add Connection

We have the codec, we will add the connection here.
Same as before, you can check some examples, like ethereumconnection.ts, liskconnection.ts, bnsconnection or even the mother of them iov-bcp/connection.ts, you will see the main entry point and the required api for this connection.

We will add some structures to myblockchainconnection.ts, now following the class way.

Really nice, we have a connection to myblockchain.
Time to mark this task as done, take a small break and be ready to continue with the last steps.

(drink some mate)

The file myblockchainconnector.ts establishes the connection with the node client and also exports the codec, so it will be used by the faucet program.

This is not very complex to do. You can check some connectors examples in iov-core.

Add Unit Tests

Don’t forget about unit test, it is a really important step to understand how to use a new blockchain and also analyze possible bugs.

And if you are reading this, you will need to generate index.ts to export all the files.

We use CI at IOV, so if you completed all these steps, we will review your code, ask for some changes, run some tests and if all is green, we will tag a new release with your package 👏

Add myblockchain to iov-faucet?

If you are still with me, congratulations, now comes the easy part.

We will need to use our new fresh package just added into iov-core from iov-faucet, because it is always nice to have a faucet running to test locally a new blockchain.

Same as before, we start with a new issue in the faucet repo

Now, we clone the project and install dependencies:

git clone https://github.com/iov-one/iov-faucet.git
cd iov-faucet
git checkout v0.5.1
## in package.json file, change the version from iov-core 
## and include myblockchain package in the dependencies
yarn install

We will need to add the new package reference to the following files:

• codec.ts
• crypto.ts
• codec.spec.ts

codec.ts

crypto.ts

codec.spec.ts

Don’t forget about tests.

If you complete all these steps and commit your changes, at IOV we will follow CI to make it available to all.
Congratulations!, your blockchain has been integrated 🎉

Final comments

This post covers the steps needed to add MyBlockchain to iov-faucet, there are more APIs in iov-core, you can explore them by looking into the master branch.

Please let us know your thoughts regarding add MyBlockchain to IOV, your feedback is very important to us.

For iov-core wallet integration, just wait our next post… 🐇