It is not necessarily a simple matter to “make” a permissioned chain. With the
eris tooling, we make it as simple as possible, but it does take a bit of crafting to get everything correctly sorted.
This tutorial is structured to walk individuals through parts of the eris developer tool kit while also showing readers how to make a simple permissioned blockchain.
Note – This tutorial is built for Eris versions
>= 0.11.4. For other versions of this tutorial please see below:
There are three steps to making a permissioned blockchain:
- Make (or Get) the public keys for the individuals
- Make the genesis.json file
- Instantiate the blockchain
We shall go through these in their logical order.
To do this we need to, first, consider, who will get what permissions and why. It is outside the scope of this tutorial to outline all of the considerations which would come into play when thinking about creating a permissioning system, but for the purposes of this tutorial, we will craft the genesis block to use the following paradigm:
- 3 Administrators (these would be developers who have full control over the chain) (one of which will be “running” the chain performing validation)
If you would like to understand all of the permissions which an eris chains smart contract network is capable of providing, please see our documentation on the subject.
We use an abstraction to simplify the chain making process called Account Types. This abstraction is just that, an abstraction to help users quickly get up to speed. In order to reduce the complexity of dealing with different types of accounts typically built on a chain, we use the idea of “account types”. Account types are not restrictive in the sense that they are not the “only” types of accounts you can make with eris chains.
Account types are simply bundles of permissions no more no less. Using the eris tooling you can also create your own account types with your own bundles of permissions which will be helpful.
A Note Regarding This Tutorial
eris toolchain is designed to be very unix like, and as such we are able to craft most of what is needed in simple bash scripts which any competant developer should be able to understand. Bash really, truly, is the common denominator as it does not require any specialized language specific knowledge beyond a bare minimum to understand what is happening.
For this tutorial, we have kept the bash scripting to a bare minimum, but should you have any questions regarding any of the bash scripting, please let us know on our Support Forums and we will endeavor to make more clear what any commands that are unclear are actually doing.
Step 1. Make (or Get) the Public Keys
Everyone who interacts with an eris chains blockchain will need to have a properly formated keypair. To make a keypair we will use
eris keys usually operates as a signing daemon, but when we use eris keys to create key pairs what we are doing effectively is writing files. As is usual with the eris tooling,
eris keys is opinionated and will work by default against the following directory:
~/.eris/keys/data. When a key pair is created, that key pair will get written into that directory.
Because we use Docker to take out most of the edge cases with various operating systems and simplify the development environment for our users, these files will be written to a file system located inside the eris keys container. As we go through this tutorial we will explain a bit about what that means. When we are using containers, these containers are not built to hold data, but rather are built to hold what is needed to run processes. But, if we’re making keypairs, then we definitely want to keep these.
To accomplish this, we will use the
eris tooling only. First we need to start the eris-keys daemon:
eris services start keys
eris is a very “quiet” tool. To check that the keys service started correctly type:
eris services ls
You’ll see something like:
SERVICE ON CONTAINER ID DATA CONTAINER keys * f2e9930e4a 3644788be1
which indicates that the keys services is on (running). To see a more comprehensive output for your services, try
eris services ls -a.
To see what we can do with eris keys we will run:
eris services exec keys "eris-keys -h"
What this is doing is running the
eris-keys -h “inside” the keys containers. Technically it is not inside the keys container, but inside a separate container based on the keys image with the data container mounted, but if this sentence doesn’t make sense to you then feel free to ignore.
But instead of dealing with the
eris-keys service directly, we mostly use
eris keys from the eris cli tool. The
eris keys commands are basically wrappers around the
eris-keys commands which are ran inside containers. To see the wrappers which the eris cli tooling provides around the
eris-keys daemon, please type:
eris keys -h
Now it is time to generate some keys!
For the purposes of this tutorial only we will also create all of the necessary keys for all of the “users” of the chain and we will do so without passwords. Again, this is for demonstration purposes only, for a production system you will not do what we’re about to do.
eris keys gen
This will create one key for you. The output here should look something like this:
Now. Let’s export that key onto our host’s drive so that we can back it up and keep it safe in the future.
eris keys export 49CA2456F65B524BDEF50217AE539B8E10B37421
Note, that in the above command we used the output from the
eris keys gen command with the
eris keys export. You will want to replace the argument in the
export command with whatever the address for the public key you created is. Your key will in the directory at
To see the keys which eris-keys generated both inside the container type and available on your host machine type:
eris keys ls
Before we move on to actual chainmaking, if you would like to explore more of the eris keys functionality please see our keys tutorial.
Now, we’re all ready to make a chain.
Step 2. Make the genesis.json
Before we begin, we should quickly talk through the various files which are needed to run an eris chain. When you ran
eris init during the getting started step, eris created a folder called
~/.eris/chains/default on your host’s hard drive. This is to hold the default files for using eris chains. There are a few primary files used by eris chains:
- the config file for the tendermint consensus engine called
- the chain definition file for eris chains called
chainNameis the name of your chain) (these are located in your ~/.eris/chains directory)
genesis.jsonwhich tells eris chains how it should configure itself at the beginning of the chain (or, its genesis state)
- the config file for the eris:db application engine called
- the keypair which the tendermit consensus engine will use to sign blocks, etc. called the
In general you do not really need to mess with
server_conf.toml unless you know what you’re doing and need to move away from the default settings. Similarly, you should not need to edit
chainName.toml unless you have a deeper understanding of docker or specific needs around how your chain will run.
The three files you may need to edit are the
priv_validator.json (both of which we’re about to get “made” for us) and the
In any chain with more than one validator the
config.toml file will be edited to fill in the
moniker fields. The
seeds field is used to point your consensus engine to the peers it should connect into. For more information on how to deal with this please see our advanced chain deploying tutorial. The
moniker field is “your node’s name on the network”. It should be unique on the given network.
genesis.json is the primary file which tells eris chains how to instantiate a particular blockchain. It provides the “genesis” state of the blockchain including the accounts, permissions, and validators which will be used at the beginning of the chain. These can always be updated over the life of the chain of course, but the genesis.json provides the starting point. Luckily
eris takes care of making this for you and there is very little which should be required for you in way of editing (unless you know what you’re doing of course, in which case why are you reading this ;-) ).
With all that said, we’re ready to make a chain. First let us make a “fake” chain just to get a tour of the chain maker tool. Once we go through that process then we will make our “real” chain which we will use for the rest of this tutorial series. Let’s see what eris chains make can do for us.
eris chains make -h
That will give you an overview of the chains maker tool. Now we are ready.
eris chains make toRemoveLater
This will drop you into an interactive, command line wizard. Follow the text and the prompts to chain making bliss. Since we’re going to throw this chain away later you can just press “Enter” at each of the prompts or you can change the variables and get a feel for the wizard.
Once the wizard exits let’s take a look at what was created:
You should see three
*.csv files and a bunch of directories. Let’s look in one of those directories:
In that directory you should see a genesis.json and a priv_validator.json. The marmots call these a “bundle” as generally they are what is needed to get a chain going (in addition to a config.toml which with the proper seed and moniker filled out).
What about those
csv files? There should be three of them. Let’s take a look:
cat ~/.eris/chains/toRemoveLater/accounts.csv cat ~/.eris/chains/toRemoveLater/validators.csv cat ~/.eris/chains/toRemoveLater/addresses.csv
The first two files can be used later to create a new genesis.json if the actual json gets lost. One of the things about this tooling is that it creates the keys for you. That is helpful in some circumstances. In other circumstances this is not helpful.
In general, we recommend that if you are making a chain for a consortium that you have your consortium members make their own keys and then send the public key to you. Once you’ve assembled the keys then you will create an accounts.csv and validators.csv files in this format and then run
eris chains make with the
--known flag. More information on complex chain making is included in our advanced chain making tutorial.
The last file is the
addresses.csv file which is another artifact of the chain making process. It simply has the addresses and the “names” of the nodes. We find it useful when scripting out complex interactions and it is simply a reference file along the lines of
addr=$(cat $chain_dir/addresses.csv | grep $name | cut -d ',' -f 1).
OK, enough playing around let’s get serious!
cd ~/.eris/chains rm -rf ~/.eris/chains/toRemoveLater
That command will remove all of the stuff we’ve been working on. Per the above and after our review of the account types, we know we want to have two Root account types and one Full account type for our new chain. So let’s get to business.
That will just create a few variables we’ll be using in the future. Now, we’re ready.
eris chains make --account-types=Root:2,Full:1 simplechain
That’s it! Let’s double check the files to make sure we are squared away.
ls $chain_dir ls $chain_dir_this
Step 3. Instantiate the Blockchain
With all the files prepared we’re ready to rock and roll.
eris chains new simplechain --dir $chain_dir_this
Check that the chain is running with:
eris chains ls
You’ll see something like:
CHAIN ON CONTAINER ID DATA CONTAINER simplechain * efeeb0dd63 d06301b3a5
As with the
eris services ls -a command, you can also see more information about your chain with
eris chains ls -a. Note: the same holds true with
eris ls and
eris ls -a.
To see the logs of the chain:
eris chains logs simplechain
To turn off the chain:
eris chains stop simplechain
Boom. You’re all set with your custom built, permissioned, smart contract-ified, blockchain.
You can remove all trace of the chain with:
eris chains rm simplechain --data --dir --file --force
and clean up your eris environment with:
Where to next?
Next, you’ll want to deploy some contracts!