Getting Started with Blockchains and Smart Contracts Using Eris

The Eris platform is a great place to get started with blockchain technology. Eris Industries provides a number of tutorials on their website, but there can be a lot to digest if you’ve never worked with some of the components that are used in the platform. Many of our clients want to start getting some hands on experience by doing a proof-of-concept but are surprised by the learning curve.

[bonuscontent link=”/premium/blockchain-banking” linkTitle=”View Now”]Watch Levvel’s presentation on blockchain & banking.[/bonuscontent]

We’ve simplified the process for getting your own private, distributed blockchain working. In this blog post, I’ll show you Levvel’s Blocklab, a tool we developed to accelerate the deployment of proof-of-concept environments. I’ll also provide a summary of the key concepts behind this tool so you have a better understanding of the process involved in creating and using a distributed blockchain.

An explanation of blockchain technology itself is outside the scope of the document, but The Economist has a very good conceptual overview of blockchain and Eris provides a blockchain explainer that describes the technical underpinnings in more detail.


The Eris platform provides the software for deploying and using a blockchain-based data infrastructure. This infrastructure enables distributed applications, smart contracts, and distributed ledgers. At its core, the Eris platform uses the Tendermint blockchain. Surrounding this core is a variety of tools that communicate with the blockchain, manage keys, store files, and manage the platform using services. Creating a private Tendermint blockchain requires at least four validator nodes and, optionally, participant nodes and other tools that support blockchain services.

This blog focuses on configuring and deploying the nodes that will run the blockchain. Specifically, we’ll be configuring the validator and participant nodes that make up a private blockchain. While the number of validator and participant nodes in the network can vary, the network must have at least four validators because of the consensus mechanism used by the Tendermint blockchain. As a result, the architecture we’ll deploy in this blog will look like this:



Eris is a great place to start because it provides a way to explore blockchain use cases in a private, distributed network setting. This is ideal for individual entities looking to have a completely private blockchain within their organization and for groups of entities looking to operate a private blockchain amongst themselves. The concepts you’ll learn with Eris can also be more generally applied to other blockchain technologies. Additionally, the Eris blockchain allows you the flexibility to test financial use cases (for example, moving coins between accounts as part of a settlement process) as well as non-financial use cases like applying smart contracts to agreements between parties.


A number of configuration files and keys are necessary to start your blockchain. I’ll explain these files in a moment, but we’ve simplified the process of creating them by creating a blockchain labs tool.


The tool needs the following information to create your configuration:

  • Chain Name: An identifier for your blockchain on your network. It should be unique within your environment.
  • Number of Validator Nodes: Each validator node requires its own private/public key pair and must be added to the genesis.json file that configures your blockchain. The tool uses this number to know how many of these to create. (Reminder: this number should be >= 4. Networks with fewer than four nodes will appear to start but will not be able to operate correctly.)
  • Number of Participant Nodes: Similar to validator nodes, each participant node has its own key pair. Networks do not need participants, but they can be useful to have nodes on the network that participate in the blockchain without voting for consensus.
  • Number of Tokens: Each validator node will have a number of tokens that are allocated to it. This accomplishes two things for your blockchain: First, it ensures that there are coins immediately available to be moved between accounts on the chain. Second, the Tendermint blockchain used by Eris requires validators to post a bond deposit to validate transactions and wait for the coins to be returned. This acts as a disincentive for validators to fork the blockchain.
  • Seed Host: This is a hostname resolvable by DNS or an IP address of one of the validator nodes. This value will be used to seed your blockchain network and enable each node to discover each other by connecting to this node of the network. If you need to create new hosts to run your blockchain, see the section “Starting your blockchain nodes” below on how to create a host – we’ve published an AMI for AWS that makes this process very simple.
  • Email Address: The tool generates these configuration files asynchronously from a queue. We use your email address to send you a secure link to download your configuration files when they are ready. The process normally takes less than five minutes.

When you submit an environment configuration request through the tool it will generate a zip file for each node of your blockchain. It also generates private/public keypairs for each node. All of these files are then zipped in to a single file which you can download via the link in your notification email.

For example, if you request the configuration for a blockchain called “test” with four validator nodes, one participant node, and 20,000 coins per node, you’ll receive a zip file that contains the following:

Zip File Contents

(Note: The contents of your files will be different than what is shown here because each configuration request generates unique keys. Also, your information is kept on our servers only from the time it is created until the time you download it. As soon as the file is downloaded, we destroy your configuration including any keys that were created and cannot restore them.)


In the zip file you’ll see a keys directory (which includes CSV files used to generate your blockchain configuration), a data directory which includes the private/public key pairs, and a zip file corresponding to each node requested.

Within the zip file for each node you’ll see a structure that looks like this:

Validator Node Files

This zip file contains all of the configuration files needed for each node on the network. Notably, the genesis.json file contains the addresses, permissions, nodes, public keys and initial number of tokens for the network. The priv_validator.json file contains the public and private key pair used by the node to sign transactions (unique for each node). It also contains the configuration files for Eris, a start script that will be used to start the node, and a Dockerfile which can optionally be used to run the node as a Docker container.

We’ll use this configuration to setup your blockchain nodes.


To start your blockchain, you will need to need to have server hosts available to run the Eris platform and use the configuration files included in the zip file mentioned above to configure the nodes.


Eris makes use of Docker containers for its services and much of the Eris and Tendermint tooling is written in Go. To simplify the process of getting started, we’ve made an Amazon Web Services (AWS) machine image available that comes pre-installed with all the tools we’ll need. You can search for the AMI from the EC2 launch process by clicking on “Community APIs” and searching for “Levvel Eris AMI”:

Starting Your Blockchain Nodes

You’ll need to have at least as many EC2 instances available as you want nodes. Again, you’ll need at least four nodes for the network to operate. Make sure that your nodes are able to communicate between each other using a security group like the following:

Security Group Ports

If you don’t want to use AWS to host your nodes, you’ll need to have access to hosts that have Go version 1.4.x and Docker version 1.8.x installed. You’ll also need SSH access to the hosts and the ability to open the ports needed to communicate between the nodes.

To simplify some of the commands that we’ll use to SSH to these instances, you should add aliases to each of the hosts to your ~/.ssh/config file, like this:

Host eris0
 IdentityFile ~/.ssh/chris-levvel.pem
 User eris

Host eris1
 IdentityFile ~/.ssh/chris-levvel.pem
 User eris

Host eris2
 IdentityFile ~/.ssh/chris-levvel.pem
 User eris

Host eris3
 IdentityFile ~/.ssh/chris-levvel.pem
 User eris

Host eris4
 IdentityFile ~/.ssh/chris-levvel.pem
 User eris

With SSH access to your nodes available, you can now use the configuration files and script from your configure your nodes.


Simply scp your zip files to each node you configured above:

scp <chain_name>–[validator|participant]– eris:.

where chain_name is the name of your chain and n is 1..n for each of your nodes.

Now, ssh to each server, unzip the zip file, cd to the resulting directory and run The script will run a number of commands necessary to start the Eris tools which may take a few minutes to complete. Once the blockchain starts on all the nodes, you’ll begin seeing output that looks like this:

Configuring and Starting Your Nodes

Congratulations! That’s it. Your distributed blockchain is now running.


The Tendermint blockchain used by Eris exposes a number of RESTful web services that can be invoked to check on the status of the blockchain and create transactions. These services are exposed on every node on port 46657. For example, going to http://<validator_node_IP>:46657/status will produce output like this:

Checking on the status of your blockchain network

The highlighted text included in the output shows that blocks are being created on the network. Similarly, going to http://<validator_node_IP>:46657/list_accounts will show you the current accounts on the blockchain:

Checking on the status of your blockchain network1

The balance in the validator accounts will match the number of tokens you requested in the Blocklab tool.


With a private blockchain network running you can now experiment with distributed applications, smart contracts, and operating the network. In the coming weeks, we’ll be writing about how to apply these concepts using Eris real-world use cases. If you have ideas, feedback or questions, leave a comment below or drop us a line at

Chris Hart

Chris Hart


Chris Hart is a co-founder and CTO of Levvel. He has more than 15 years of technology leadership experience and has led software development, infrastructure, and QA organizations at multiple Fortune 100 companies. In addition to his enterprise experience, Chris has helped start or grow multiple early-stage technology companies. In the five years before starting Levvel, Chris was focused on financial technology solutions in the consumer, commercial and wealth management space. His technical expertise and enterprise-scale, global program management background helps Levvel’s clients transform their businesses.