README
¶
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
~/.etherminte.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.
Directories