Ethermint

Ethereum powered by Tendermint consensus

Download the latest release

Join the chat!

We have a friendly community of like-minded people which are always eager to help someone in need of advice or just looking for casual banter.

Code of Conduct

Please read, understand and adhere to our code of conduct.

Documentation

We are using godoc for our documentation. In order to browse the interactive documentation, please open a terminal window and type this command

godoc -http=:6060

and then go see the interactive Ethermint documentation at http://localhost:6060/pkg/github.com/tendermint/ethermint

Maintainer

Adrian Brink - adrian@tendermint.com

About Ethermint

Ethermint enables ethereum to run as an ABCI application on tendermint and the COSMOS hub. This application allows you to get all the benefits of ethereum without having to run your own miners.

This means running an Ethereum EVM-based network that uses Tendermint consensus instead of proof-of-work. The way it's built makes it easy to use existing Ethereum tools (geth attach, web3) to interact with the node.

Installation

Binary Distribution

This installation involves the downloading of the binaries and subsequently moving them into your $PATH.

Download the binaries for your platform on the release page. Open a terminal window and switch into the folder that you downloaded ethermint to.

unzip -d /usr/local/bin ${the name of the ethermint binary}.zip

Docker

We are currently building docker images for both ethermint and tendermint. There are images for versioned releases, builds of master and builds of develop.

// TODO: Add example of how to get a node up and running using docker

Source

Ethermint builds with go1.8.3 and hence go1.8.3 needs to be installed. In order to manage your go installation we recommend GVM.

Once go is installed and configured you can download ethermint.

go get -u -d github.com/tendermint/ethermint

This places the ethermint source code into the appropriate directory in your $GOPATH.

Next you need to switch into the ethermint directory and install it.

cd $GOPATH/src/github.com/tendermint/ethermint

make install

This will download all the necessary dependencies and install ethermint in your $PATH.

Tendermint

Ethermint relies on the Tendermint executable to provide the networking and consensus engines.

go get -u -d github.com/tendermint/tendermint

cd $GOPATH/src/github.com/tendermint/tendermint

make install

This will download all the necessary dependencies and install tendermint in your $PATH.

Starting Ethermint

Initialisation

To get started, you need to initialise the genesis block for tendermint core and go-ethereum. We provide initialisation files with reasonable defaults and money allocated into a predefined account. If you installed from binary or docker please download these default files here.

You can choose where to store the ethermint files with --datadir. For this guide, we will use ~/.ethermint, which is a reasonable default in most cases.

Before you can run ethermint you need to initialise tendermint and ethermint with their respective genesis states. Please switch into the folder where you have the initialisation files. If you installed from source you can just follow these instructions.

ethermint --datadir ~/.ethermint --with-tendermint init

which will also invoke tendermint init --home ~/.ethermint/tendermint. You can prevent Tendermint from being starting by excluding the flag --with-tendermint for example

ethermint --datadir ~/.ethermint init

and then you will have to invoke tendermint in another shell with the command

tendermint init --home ~/.ethermint/tendermint

Note:

You can optionally copy a keystore to the Ethereum folder that you used in the steps above i.e ~/.ethermint e.g

cp -r keystore ~/.ethermint

Running

To execute ethermint we need to start two processes. The first one is for tendermint, which handles the P2P communication as well as the consensus process, while the second one is actually ethermint, which provides the go-ethereum functionality.

After running tendermint you will see a series of error messages: abci.socketClient failed to connect to tcp://127.0.0.1:46658. Retrying... module=abci-client connection=query. This is normal, tendermint is trying to find an ABCI app to which to connect. Next we run the ABCI app that tendermint will attach itself to by running:

ethermint --datadir ~/.ethermint --rpc --rpcaddr=0.0.0.0 --ws --wsaddr=0.0.0.0 --rpcapi eth,net,web3,personal,admin

and then in a separate shell, invoke

tendermint --home ~/.ethermint/tendermint node

Alternatively, ethermint can start tendermint for you as a subprocess, by using flag --with-tendermint e.g.

ethermint --with-tendermint --datadir ~/.ethermint --rpc --rpcaddr=0.0.0.0 --ws --wsaddr=0.0.0.0 --rpcapi eth,net,web3,personal,admin

Note: The password for the default account is 1234.

Connecting to Ethermint

Ethermint is fully compatible with the standard go-ethereum tooling such as geth, mist and truffle. Please install whichever tooling suits you best.

Below we are explaining how to connect these tools to ethermint. For installation instructions please visit the respective projects.

Geth

geth attach http://localhost:8545

This will drop you into a web3 console.

Mist

The mist tooling requires more setup, so be sure to read the explanations on the project site. Of course, you are welcome to ask for help in our slack channel.

meteor --no-release-check

electron . --rpc http://localhost:8545

Truffle

Truffle works without any extra arguments.

truffle init

truffle migrate

And you're off!

Multi-Node Deployments

If you are interested in using ethermint in a multi-node setup (like a blockchain really, doh) you can use our kubernetes scripts.

Please install minikube and all its dependencies.

First you have to start minikube

minikube start

Starting a cluster of ethermint nodes goes like this

./scripts/kubernetes/start.sh 3 3 3

start.sh N V S will start N number of instances with V validator and S seed nodes.

To get an overview of all the running nodes use the minikube dashboard

minikube dashboard

In order to connect to a node using the tooling described above you have to expose it first

./scripts/kubernetes/expose.sh 1

expose.sh N exposes N number of nodes. N can't be greater than the number of nodes you started previously. Minikube will assign a random port to every exposed node's services and hence you have to obtain that information as well.

minikube service tm-0 --format {{.IP}}:{{.Port}}

tm-0 refers to the first ethermint node. The first IP:Port combination is for the go-ethereum RPC and the second one is for the tendermint RPC.

To delete all nodes you can just run

./scripts/kubernetes/destroy.sh

Finally to shutdown kubernetes and minikube run

minikube stop

You might have wondered why you don't have to worry about starting tendermint and ethermint separately. Our scripts start both processes at the same time and expose it as one node. That is also the reason why the expose commands exposes both processes.

Run Ethereum Network Stats

The Ethereum network stats system consist of a frontend and a backend. In order for both of them to securely communicate with each other you have to set the environment variable WS_SECRET. You can just use any random string and in this example I will use ethermint as my WS_SECRET.

First you have to start Ethermint and Tendermint as described above and second you have to install two global dependencies.

npm install -g grunt-cli

To start the frontend you have to clone another repository, so please navigate to a suitable destination folder.

git clone https://github.com/cubedro/eth-netstats

cd eth-netstats

npm install

grunt

WS_SECRET=ethermint npm start

Now you can see the frontend running at http://localhost:3000, but no information will be present since we haven't started the backend.

To start the backend you have to clone another repository again, so please navigate to a suitable destination folder.

git clone https://github.com/tendermint/eth-net-intelligence-api.git

cd eth-net-intelligence-api

npm install

WS_SECRET=ethermint node app.js

Now you should be able to navigate to http://localhost:3000 and see constant information about your ethermint node streaming by.

Contributing to Ethermint

Thanks for considering making contributions to Ethermint!

Please follow standard github best practices: fork the repo, branch from the tip of develop, make some commits, test your code changes with make test, and submit a pull request to develop.

See the open issues for things we need help with!

Please make sure to use gofmt before every commit - the easiest way to do this is have your editor run it for you upon saving a file.

actly/ethermint2