cerc-io/laconicd-deprecated
19
0
Fork 1
Code Issues 21 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

testnet docs (#393)

Browse Source 
* testnet docs

* more updates on quickstart docs

* update quickstart

* more updates

* update quickstart

* final touches

* update lint
This commit is contained in:
Federico Kunze 2020-07-17 20:07:05 +02:00 committed by GitHub
parent 2fb4ab4862
commit 5ba8ce4605
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
15 changed files with 707 additions and 300 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/workflows/lint.yml vendored
View File

@ -23,7 +23,7 @@ jobs:
- uses: golangci/golangci-lint-action@master - uses: golangci/golangci-lint-action@master
with: with:
# Required: the version of golangci-lint is required and must be specified without patch version: we always use the latest patch version. # Required: the version of golangci-lint is required and must be specified without patch version: we always use the latest patch version.
version: v1.27 version: v1.28
args: --timeout 10m args: --timeout 10m
github-token: ${{ secrets.github_token }} github-token: ${{ secrets.github_token }}
if: "env.GIT_DIFF != ''" if: "env.GIT_DIFF != ''"

192
README.md
View File

@ -1,162 +1,72 @@
[![CircleCI](https://circleci.com/gh/cosmos/ethermint.svg?style=svg)](https://circleci.com/gh/cosmos/ethermint) <!--
[![](https://godoc.org/github.com/cosmos/ethermint?status.svg)](http://godoc.org/github.com/cosmos/ethermint) [![Go Report Card](https://goreportcard.com/badge/github.com/cosmos/ethermint)](https://goreportcard.com/report/github.com/cosmos/ethermint) parent:
order: false
-->
# Ethermint <div align="center">
<h1> Ethermint </h1>
</div>
__**WARNING:**__ Ethermint is under VERY ACTIVE DEVELOPMENT and should be treated as pre-alpha software. This means it is not meant to be run in production, its APIs are subject to change without warning and should not be relied upon, and it should not be used to hold any value. We will remove this warning when we have a release that is stable, secure, and properly tested. <div align="center">
<a href="https://github.com/ChainSafe/ethermint/releases/latest">
<img alt="Version" src="https://img.shields.io/github/tag/ChainSafe/ethermint.svg" />
</a>
<a href="https://github.com/ChainSafe/ethermint/blob/development/LICENSE">
<img alt="License: Apache-2.0" src="https://img.shields.io/github/license/ChainSafe/ethermint.svg" />
</a>
<a href="https://pkg.go.dev/github.com/cosmos/ethermint?tab=doc">
<img alt="GoDoc" src="https://godoc.org/github.com/ChainSafe/ethermint?status.svg" />
</a>
<a href="https://goreportcard.com/report/github.com/ChainSafe/ethermint">
<img alt="Go report card" src="https://goreportcard.com/badge/github.com/ChainSafe/ethermint"/>
</a>
<a href="https://codecov.io/gh/cosmos/ethermint">
<img alt="Code Coverage" src="https://codecov.io/gh/ChainSafe/ethermint/branch/development/graph/badge.svg"/>
</a>
</div>
<div align="center">
<a href="https://github.com/cosmos/ethermint">
<img alt="Lines Of Code" src="https://tokei.rs/b1/github/cosmos/ethermint" />
</a>
<a href="https://discord.gg/AzefAFd">
<img alt="Discord" src="https://img.shields.io/discord/669268347736686612.svg" />
</a>
<a href="https://github.com/ChainSafe/ethermint/actions?query=workflow%3ABuild">
<img alt="Build Status" src="https://github.com/ChainSafe/ethermint/workflows/Build/badge.svg" />
</a>
<a href="https://github.com/ChainSafe/ethermint/actions?query=workflow%3ALint">
<img alt="Lint Status" src="https://github.com/ChainSafe/ethermint/workflows/Lint/badge.svg" />
</a>
</div>
**Note**: Requires [Go 1.13+](https://golang.org/dl/) Ethermint is a scalable, high-throughput Proof-of-Stake blockchain that is fully compatible and
interoperable with Ethereum. It's build using the the [Cosmos SDK](https://github.com/cosmos/cosmos-sdk/) which runs on top of [Tendermint Core](https://github.com/tendermint/tendermint) consensus engine.
## What is it? > **WARNING:** Ethermint is under VERY ACTIVE DEVELOPMENT and should be treated as pre-alpha software. This means it is not meant to be run in production, its APIs are subject to change without warning and should not be relied upon, and it should not be used to hold any value. We will remove this warning when we have a release that is stable, secure, and properly tested.
`ethermint` will be an implementation of the EVM that runs on top of [`tendermint`](https://github.com/tendermint/tendermint) consensus, a Proof of Stake system. This project has as its primary goals: **Note**: Requires [Go 1.14+](https://golang.org/dl/)
- [Hard Spoon](https://blog.cosmos.network/introducing-the-hard-spoon-4a9288d3f0df) enablement: This is the ability to take a token from the Ethereum mainnet and "spoon" (shift) the balances over to another network. This feature is intended to make it easy for applications that require more transactions than the Ethereum main chain can provide to move their code over to a compatible chain with much more capacity. ## Quick Start
- Web3 Compatibility: In order enable applications to be moved over to an ethermint chain existing tooling (i.e. web3 compatible clients) need to be able to interact with `ethermint`.
### Implementation To learn how the Ethermint works from a high-level perspective, go to the [Introduction](./docs/intro/overview.md) section from the documentation.
#### Completed For more, please refer to the [Ethermint Docs](./docs/), which are also hosted on [docs.ethermint.zone](https://docs.ethermint.zone/).
- Have a working implementation that can parse and validate the existing ETH Chain and persist it in a Tendermint store ## Tests
- Implement Ethereum transactions in the CosmosSDK
- Implement web3 compatible API layer
- Implement the EVM as a CosmosSDK module
- Allow the Ethermint EVM to interact with other Cosmos SDK modules
#### Current Work Unit tests are invoked via:
- Ethermint is a functioning Cosmos SDK application and can be deployed as its own zone
- Full web3 compatibility to enable existing Ethereum applications to use Ethermint
#### Next Steps
- Hard spoon enablement: The ability to export state from `geth` and import token balances into Ethermint
### Building Ethermint
To build, execute the following commands:
```bash
# To build the project and install it in $GOBIN
make install
# To build the binary and put the resulting binary in ./build
make build
```
### Starting a Ethermint daemon (node)
The following config steps can be performed all at once by executing the `init.sh` file located in the root directory like this:
```bash
./init.sh
```
> This bash file removes previous blockchain data from `~/.emintd` and `~/.emintcli`. It uses the `keyring-backend` called `test` that should prevent you from needing to enter a passkey. The `keyring-backend` `test` is unsecured and should not be used in production.
To initalize your chain manually, first create a key to use in signing the genesis transaction:
```bash
emintcli keys add mykey --keyring-backend test
```
> replace mykey with whatever you want to name the key
Then, run these commands to start up a node
```bash
# Set moniker and chain-id for Ethermint (Moniker can be anything, chain-id must be an integer)
emintd init mymoniker --chain-id 8
# Set up config for CLI
emintcli config keyring-backend test
emintcli config chain-id 8
emintcli config output json
emintcli config indent true
emintcli config trust-node true
# Allocate genesis accounts (cosmos formatted addresses)
emintd add-genesis-account $(emintcli keys show mykey -a) 1000000000000000000photon,1000000000000000000stake
# Sign genesis transaction
emintd gentx --name mykey --keyring-backend test
# Collect genesis tx
emintd collect-gentxs
# Run this to ensure everything worked and that the genesis file is setup correctly
emintd validate-genesis
# Start the node (remove the --pruning=nothing flag if historical queries are not needed)
emintd start --pruning=nothing
```
> Note: If you used `make build` instead of make install, and replace all `emintcli` and `emintd` references to `./build/emintcli` and `./build/emintd` respectively
### Starting Ethermint Web3 RPC API
After the daemon is started, run (in another process):
```bash
emintcli rest-server --laddr "tcp://localhost:8545" --unlock-key mykey
```
and to make sure the server has started correctly, try querying the current block number:
```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' -H "Content-Type: application/json" http://localhost:8545
```
or point any dev tooling at `http://localhost:8545` or whatever port is chosen just as you would with an Ethereum node
#### Clearing data from chain
Data for the CLI and Daemon should be stored at `~/.emintd` and `~/.emintcli` by default, to start the node with a fresh state, run:
```bash
rm -rf ~/.emint*
```
To clear all data except key storage (if keyring backend chosen) and then you can rerun the commands to start the node again.
#### Keyring backend options
The instructions above include commands to use `test` as the `keyring-backend`. This is an unsecured keyring that doesn't require entering a password and should not be used in production. Otherwise, Ethermint supports using a file or OS keyring backend for key storage. To create and use a file stored key instead of defaulting to the OS keyring, add the flag `--keyring-backend file` to any relevant command and the password prompt will occur through the command line. This can also be saved as a CLI config option with:
```bash
emintcli config keyring-backend file
```
### Exporting Ethereum private key from Ethermint
To export the private key from Ethermint to something like Metamask, run:
```bash
emintcli keys unsafe-export-eth-key mykey
```
Import account through private key, and to verify that the Ethereum address is correct with:
```bash
emintcli keys parse $(emintcli keys show mykey -a)
```
### Tests
Integration tests are invoked via:
```bash ```bash
make test make test
``` ```
To run CLI tests, execute: To run JSON-RPC tests, execute:
```bash ```bash
make test-cli make test-rpc
``` ```
#### Ethereum Mainnet Import There is also an included Ethereum mainnet exported blockchain file in `importer/blockchain`
There is an included Ethereum mainnet exported blockchain file in `importer/blockchain`
that includes blocks up to height `97638`. To execute and test a full import of that includes blocks up to height `97638`. To execute and test a full import of
these blocks using the EVM module, execute: these blocks using the EVM module, execute:
@ -172,4 +82,4 @@ via the `--blockchain` flag. See `TestImportBlocks` for further documentation.
The following chat channels and forums are a great spot to ask questions about Ethermint: The following chat channels and forums are a great spot to ask questions about Ethermint:
- [Cosmos Discord](https://discord.gg/W8trcGV) - [Cosmos Discord](https://discord.gg/W8trcGV)
- Cosmos Forum [![Discourse status](https://img.shields.io/discourse/https/forum.cosmos.network/status.svg)](https://forum.cosmos.network) - [Cosmos Forum](https://forum.cosmos.network)

1
cmd/emintd/main.go
View File

@ -69,6 +69,7 @@ func main() {
rootCmd.AddCommand( rootCmd.AddCommand(
withChainIDValidation(genutilcli.InitCmd(ctx, cdc, app.ModuleBasics, app.DefaultNodeHome)), withChainIDValidation(genutilcli.InitCmd(ctx, cdc, app.ModuleBasics, app.DefaultNodeHome)),
genutilcli.CollectGenTxsCmd(ctx, cdc, bank.GenesisBalancesIterator{}, app.DefaultNodeHome), genutilcli.CollectGenTxsCmd(ctx, cdc, bank.GenesisBalancesIterator{}, app.DefaultNodeHome),
genutilcli.MigrateGenesisCmd(ctx, cdc),
genutilcli.GenTxCmd( genutilcli.GenTxCmd(
ctx, cdc, app.ModuleBasics, staking.AppModuleBasic{}, bank.GenesisBalancesIterator{}, ctx, cdc, app.ModuleBasics, staking.AppModuleBasic{}, bank.GenesisBalancesIterator{},
app.DefaultNodeHome, app.DefaultCLIHome, app.DefaultNodeHome, app.DefaultCLIHome,

1
docs/core/README.md
View File

@ -9,6 +9,5 @@ parent:
This repository contains reference documentation on the core concepts of Ethermint. This repository contains reference documentation on the core concepts of Ethermint.
1. [Encoding](./encoding.md) 1. [Encoding](./encoding.md)
2. [Events](./events.md)
After reading the core concepts, head on to the [guides](../guides/README.md) to learn how to use Ethereum tooling with Ethermint. After reading the core concepts, head on to the [guides](../guides/README.md) to learn how to use Ethereum tooling with Ethermint.

2
docs/core/encoding.md
View File

@ -70,4 +70,4 @@ will call this method for each necessary module.
## Next {hide} ## Next {hide}
Learn about [events](./events.md) {hide} Learn how to connect Ethermint to [Metamask](./../guides/metamask.md) {hide}

103
docs/core/events.md
View File

@ -1,103 +0,0 @@
<!--
order: 2
-->
# Events
`Event`s are objects that contain information about the execution of the application. They are mainly used by service providers like block explorers and wallet to track the execution of various messages and index transactions. {synopsis}
## Pre-requisite Readings
- [Cosmos SDK Events](https://docs.cosmos.network/master/core/events.html) {prereq}
- [Ethereum's PubSub JSON-RPC API](https://geth.ethereum.org/docs/rpc/pubsub) {prereq}
## Subscribing to Events
### SDK and Tendermint Events
It is possible to subscribe to `Events` via Tendermint's [Websocket](https://tendermint.com/docs/app-dev/subscribing-to-events-via-websocket.html#subscribing-to-events-via-websocket).
This is done by calling the `subscribe` RPC method via Websocket:
```json
{
"jsonrpc": "2.0",
"method": "subscribe",
"id": "0",
"params": {
"query": "tm.event='eventCategory' AND eventType.eventAttribute='attributeValue'"
}
}
```
The main `eventCategory` you can subscribe to are:
- `NewBlock`: Contains `events` triggered during `BeginBlock` and `EndBlock`.
- `Tx`: Contains `events` triggered during `DeliverTx` (i.e. transaction processing).
- `ValidatorSetUpdates`: Contains validator set updates for the block.
These events are triggered from the `state` package after a block is committed. You can get the
full list of `event` categories [here](https://godoc.org/github.com/tendermint/tendermint/types#pkg-constants).
The `type` and `attribute` value of the `query` allow you to filter the specific `event` you are looking for. For example, a `MsgEthereumTx` transaction triggers an `event` of type `ethermint` and has `sender` and `recipient` as `attributes`. Subscribing to this `event` would be done like so:
```json
{
"jsonrpc": "2.0",
"method": "subscribe",
"id": "0",
"params": {
"query": "tm.event='Tx' AND ethereum.recipient='hexAddress'"
}
}
```
where `hexAddress` is an Ethereum hex address (eg: `0x1122334455667788990011223344556677889900`).
### Ethereum JSON-RPC Events
<!-- TODO: PublicFiltersAPI -->
## Websocket Connection
### Tendermint Websocket
To start a connection with the Tendermint websocket you need to define the address with the `--node` flag when initializing the REST server (default `tcp://localhost:26657`):
```bash
emintcli rest-server --laddr "tcp://localhost:8545" --node "tcp://localhost:8080" --unlock-key <my_key> --chain-id <chain_id>
```
Then, start a websocket subscription with [ws](https://github.com/hashrocket/ws)
```bash
# connect to tendermint websocet at port 8080 as defined above
ws ws://localhost:8080/websocket
# subscribe to new Tendermint block headers
> { "jsonrpc": "2.0", "method": "subscribe", "params": ["tm.event='NewBlockHeader'"], "id": 1 }
```
### Ethereum Websocket
Since Ethermint runs uses Tendermint Core as it's consensus Engine and it's built with the Cosmos SDK framework, it inherits the event format from them. However, in order to support the native Web3 compatibility for websockets of the [Ethereum's PubSubAPI](https://geth.ethereum.org/docs/rpc/pubsub), Ethermint needs to cast the Tendermint responses retreived into the Ethereum types.
You can start a connection with the Ethereum websocket using the `--websocket-port` flag when initializing the REST server (default `7545`):
```bash
emintcli rest-server --laddr "tcp://localhost:8545" --websocket-port 8546 --unlock-key <my_key> --chain-id <chain_id>
```
Then, start a websocket subscription with [ws](https://github.com/hashrocket/ws)
```bash
# connect to tendermint websocet at port 8546 as defined above
ws ws://localhost:8546/
# subscribe to new Ethereum-formatted block Headers
> {"id": 1, "method": "eth_subscribe", "params": ["newHeads", {}]}
< {"jsonrpc":"2.0","result":"0x44e010cb2c3161e9c02207ff172166ef","id":1}
```
## Next {hide}
Learn how to connect Ethermint to [Metamask](./../guides/metamask.md) {hide}

32
docs/intro/overview.md
View File

@ -6,31 +6,33 @@ order: 1
## What is Ethermint ## What is Ethermint
Ethermint is a high throughput PoS blockchain that is fully compatible and Ethermint is a scalable, high-throughput Proof-of-Stake blockchain that is fully compatible and
interoperable with Ethereum. In other words, it allows for running vanilla Ethereum interoperable with Ethereum. It s build using the the [Cosmos SDK](https://github.com/cosmos/cosmos-sdk/) which runs on top of [Tendermint Core](https://github.com/tendermint/tendermint) consensus engine.
on top of [Tendermint](https://github.com/tendermint/tendermint) consensus via
the [Cosmos SDK](https://github.com/cosmos/cosmos-sdk/). This allows developers Ethermint allows for running vanilla Ethereum as a [Cosmos](https://cosmos.network/) application-specific blockchain. This allows developers
to have all the desired features of Ethereum, while at the same time benefit to have all the desired features of Ethereum, while at the same time, benefit
from Tendermint’s PoS implementation. Also, because it is built on top of the from Tendermint’s PoS implementation. Also, because it is built on top of the
Cosmos SDK, it will be able to exchange value with the rest of the Cosmos Ecosystem. Cosmos SDK, it will be able to exchange value with the rest of the Cosmos Ecosystem through the Inter Blockchain Communication Protocol (IBC).
### Features
Here’s a glance at some of the key features of Ethermint: Here’s a glance at some of the key features of Ethermint:
* Web3 compatibility * Web3 compatibility
* High throughput * High throughput via [Tendermint Core](https://github.com/tendermint/tendermint)
* Horizontal scalability * Horizontal scalability via [IBC](https://github.com/cosmos/ics)
* Transaction finality * Fast transaction finality
* [Hard Spoon](https://blog.cosmos.network/introducing-the-hard-spoon-4a9288d3f0df)
Ethermint enables these key features through: Ethermint enables these key features through:
* Implementing Tendermint's ABCI application interface to manage the base Blockchain * Implementing Tendermint Core's ABCI application interface to manage the blockchain
* Leveraging [modules](https://github.com/cosmos/cosmos-sdk/tree/master/x/) and other mechanisms implemented by the Cosmos SDK * Leveraging [modules](https://github.com/cosmos/cosmos-sdk/tree/master/x/) and other mechanisms implemented by the Cosmos SDK
* Utilizing [`geth`](https://github.com/ethereum/go-ethereum) as a library to avoid code reuse and improve maintainability * Utilizing [`geth`](https://github.com/ethereum/go-ethereum) as a library to avoid code reuse and improve maintainability.
* Exposing a fully compatible Web3 RPC layer for interacting with the system * Exposing a fully compatible Web3 RPC layer for interacting with existing Ethereum clients and tooling (Metamask, Remix, Truffle, etc).
The sum of these features allows developers to leverage existing Ethereum ecosystem The sum of these features allows developers to leverage existing Ethereum ecosystem tooling and
tooling and software to seamlessly deploy smart contracts which interact with the rest of the Cosmos software to seamlessly deploy smart contracts which interact with the rest of the Cosmos ecosystem!
ecosystem!
## Next {hide} ## Next {hide}

10
docs/quickstart/README.md
View File

@ -8,10 +8,16 @@ parent:
This repository contains reference documentation on how to install and run an Etheremint full node. This repository contains reference documentation on how to install and run an Etheremint full node.
1. [Run a Node](./run_node.md) 1. [Installation](./run_node.md)
2. [Run a Node](./run_node.md)
3. [Testnet](./testnet.md)
4. [Validator Setup](./validator-setup.md)
5. [Upgrade](./upgrade.md)
6. [Clients](./clients.md)
7. [Events](./events.md)
After going throught the Quick Start contents, head over to the [basics](./../basics/README.md) to learn more. After going throught the Quick Start contents, head over to the [basics](./../basics/README.md) to learn more.
## Next {hide} ## Next {hide}
Learn how to run an Ethermint [node](./../quickstart/run_node.md) {hide} Learn how to [install](./../quickstart/intallation.md) Ethermint {hide}

62
docs/quickstart/clients.md Normal file
View File

@ -0,0 +1,62 @@
<!--
order: 6
-->
# Clients
Learn how to connect a client to a running node. {synopsis}
## Pre-requisite Readings
- [Run a Node](./run_node.md) {prereq}
## Client Integrations
### Command Line Interface
Ethermint is integrated with a CLI client that can be used to send transactions and query the state from each module.
```bash
# available query commands
emintcli query -h
# available transaction commands
emintcli tx -h
```
### Client Servers
The Ethermint client supports both [REST endpoints](https://cosmos.network/rpc) from the SDK and Ethereum's [JSON-RPC](https://eth.wiki/json-rpc/API).
#### REST and Tendermint RPC
Ethermint exposes REST endpoints for all the integrated Cosmos-SDK modules. This makes it easier for wallets and block explorers to interact with the proof-of-stake logic.
To run the REST Server, you need to run the Ethermint daemon (`emintd`) and then execute (in another
process):
```bash
emintcli rest-server --laddr "tcp://localhost:8545" --unlock-key $KEY --chain-id $CHAINID --trace
```
You should see the logs from the REST and the RPC server.
```bash
I[2020-07-17|16:54:35.037] Starting application REST service (chain-id: "8")... module=rest-server
I[2020-07-17|16:54:35.037] Starting RPC HTTP server on 127.0.0.1:8545 module=rest-server
```
#### Ethereum JSON-RPC server
Ethermint also supports most of the standard web3 [JSON-RPC
APIs](https://eth.wiki/json-rpc/API) to connect with existing web3 tooling.
::: tip
Some of the JSON-RPC API [namespaces](https://geth.ethereum.org/docs/rpc/server) are currently under development.
:::
To connect to the JSON-PRC server, use the `rest-server` command as shown on the section above. Then, you can point any Ethereum development tooling to `http://localhost:8545` or whatever port you choose with the listen address flag (`--laddr`).
## Next {hide}
Process and subscribe to [events](./events.md) via websockets {hide}

134
docs/quickstart/events.md Normal file
View File

@ -0,0 +1,134 @@
<!--
order: 7
-->
# Events
`Event`s are objects that contain information about the execution of the application. They are
mainly used by service providers like block explorers and wallet to track the execution of various
messages and index transactions. {synopsis}
## Pre-requisite Readings
- [Cosmos SDK Events](https://docs.cosmos.network/master/core/events.html) {prereq}
- [Ethereum's PubSub JSON-RPC API](https://geth.ethereum.org/docs/rpc/pubsub) {prereq}
## Subscribing to Events
### SDK and Tendermint Events
It is possible to subscribe to `Events` via Tendermint's [Websocket](https://tendermint.com/docs/app-dev/subscribing-to-events-via-websocket.html#subscribing-to-events-via-websocket).
This is done by calling the `subscribe` RPC method via Websocket:
```json
{
"jsonrpc": "2.0",
"method": "subscribe",
"id": "0",
"params": {
"query": "tm.event='eventCategory' AND eventType.eventAttribute='attributeValue'"
}
}
```
The main `eventCategory` you can subscribe to are:
- `NewBlock`: Contains `events` triggered during `BeginBlock` and `EndBlock`.
- `Tx`: Contains `events` triggered during `DeliverTx` (i.e. transaction processing).
- `ValidatorSetUpdates`: Contains validator set updates for the block.
These events are triggered from the `state` package after a block is committed. You can get the full
list of `event` categories
[here](https://godoc.org/github.com/tendermint/tendermint/types#pkg-constants).
The `type` and `attribute` value of the `query` allow you to filter the specific `event` you are
looking for. For example, a `MsgEthereumTx` transaction triggers an `event` of type `ethermint` and
has `sender` and `recipient` as `attributes`. Subscribing to this `event` would be done like so:
```json
{
"jsonrpc": "2.0",
"method": "subscribe",
"id": "0",
"params": {
"query": "tm.event='Tx' AND ethereum.recipient='hexAddress'"
}
}
```
where `hexAddress` is an Ethereum hex address (eg: `0x1122334455667788990011223344556677889900`).
### Ethereum JSON-RPC Events
Ethermint also supports the Ethereum [JSON-RPC](https://eth.wiki/json-rpc/API) filters calls to
subscribe to [state logs](https://eth.wiki/json-rpc/API#eth_newfilter),
[blocks](https://eth.wiki/json-rpc/API#eth_newblockfilter) or [pending
transactions](https://eth.wiki/json-rpc/API#eth_newpendingtransactionfilter) changes.
Under the hood, it uses the Tendermint RPC client's event system to process subscriptions that are
then formatted to Ethereum-compatible events.
```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newBlockFilter","params":[],"id":1}' -H "Content-Type: application/json" http://localhost:8545
{"jsonrpc":"2.0","id":1,"result":"0x3503de5f0c766c68f78a03a3b05036a5"}
```
Then you can check if the state chages with the [`eth_getFilterChanges`](https://eth.wiki/json-rpc/API#eth_getfilterchanges) call:
```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getFilterChanges","params":["0x3503de5f0c766c68f78a03a3b05036a5"],"id":1}' -H "Content-Type: application/json" http://localhost:8545
{"jsonrpc":"2.0","id":1,"result":["0x7d44dceff05d5963b5bc81df7e9f79b27e777b0a03a6feca09f3447b99c6fa71","0x3961e4050c27ce0145d375255b3cb829a5b4e795ac475c05a219b3733723d376","0xd7a497f95167d63e6feca70f344d9f6e843d097b62729b8f43bdcd5febf142ab","0x55d80a4ba6ef54f2a8c0b99589d017b810ed13a1fda6a111e1b87725bc8ceb0e","0x9e8b92c17280dd05f2562af6eea3285181c562ebf41fc758527d4c30364bcbc4","0x7353a4b9d6b35c9eafeccaf9722dd293c46ae2ffd4093b2367165c3620a0c7c9","0x026d91bda61c8789c59632c349b38fd7e7557e6b598b94879654a644cfa75f30","0x73e3245d4ddc3bba48fa67633f9993c6e11728a36401fa1206437f8be94ef1d3"]}
```
## Websocket Connection
### Tendermint Websocket
To start a connection with the Tendermint websocket you need to define the address with the `--node`
flag when initializing the REST server (default `tcp://localhost:26657`):
```bash
emintcli rest-server --laddr "tcp://localhost:8545" --node "tcp://localhost:8080" --unlock-key <my_key> --chain-id <chain_id>
```
Then, start a websocket subscription with [ws](https://github.com/hashrocket/ws)
```bash
# connect to tendermint websocet at port 8080 as defined above
ws ws://localhost:8080/websocket
# subscribe to new Tendermint block headers
> { "jsonrpc": "2.0", "method": "subscribe", "params": ["tm.event='NewBlockHeader'"], "id": 1 }
```
### Ethereum Websocket
Since Ethermint runs uses Tendermint Core as it's consensus Engine and it's built with the Cosmos
SDK framework, it inherits the event format from them. However, in order to support the native Web3
compatibility for websockets of the [Ethereum's
PubSubAPI](https://geth.ethereum.org/docs/rpc/pubsub), Ethermint needs to cast the Tendermint
responses retreived into the Ethereum types.
You can start a connection with the Ethereum websocket using the `--wsport` flag when initializing
the REST server (default `8546`):
```bash
emintcli rest-server --laddr "tcp://localhost:8545" --wsport 8546 --unlock-key <my_key> --chain-id <chain_id>
```
Then, start a websocket subscription with [ws](https://github.com/hashrocket/ws)
```bash
# connect to tendermint websocet at port 8546 as defined above
ws ws://localhost:8546/
# subscribe to new Ethereum-formatted block Headers
> {"id": 1, "method": "eth_subscribe", "params": ["newHeads", {}]}
< {"jsonrpc":"2.0","result":"0x44e010cb2c3161e9c02207ff172166ef","id":1}
```
## Next {hide}
Learn about Ethermint [accounts](./../basic/accounts.md) {hide}

38
docs/quickstart/installation.md Normal file
View File

@ -0,0 +1,38 @@
<!--
order: 1
-->
# Installation
## Binaries
Clone and build Ethermint using `git`:
```bash
git clone https://github.com/ChainSafe/ethermint.git
cd ethermint
make install
```
Check that the binaries have been successfuly installed:
```bash
emintd -h
emintcli -h
```
<!-- ## Docker -->
<!-- TODO: -->
## Releases
::: warning
Ethermint is under VERY ACTIVE DEVELOPMENT and should be treated as pre-alpha software. This means it is not meant to be run in production, its APIs are subject to change without warning and should not be relied upon, and it should not be used to hold any value. We will remove this warning when we have a release that is stable, secure, and properly tested.
:::
You can also download a specific release available on the [Ethermint repository](https://github.com/ChainSafe/ethermint/releases)
## Next {hide}
Learn how to [run a node](./.run_node.md) {hide}

142
docs/quickstart/run_node.md
View File

@ -1,23 +1,22 @@
<!-- <!--
order: 1 order: 2
--> -->
# Run a Node # Run a Node
Run a local node and start the REST and JSON-RPC clients {synopsis} Run a local node and start the REST and JSON-RPC clients {synopsis}
Clone and build Ethermint: ## Pre-requisite Readings
```bash - [Installation](./installation.md) {prereq}
git clone <https://github.com/ChainSafe/ethermint>
cd ethermint
make install
```
Run the local testnet node with faucet enabled: ## Script deployment
Run the local node with faucet enabled:
::: warning ::: warning
The script below will remove any pre-existing binaries installed The script below will remove any pre-existing binaries installed. Use the manual deploy if you want
to keep your binaries and configuration files.
::: :::
```bash ```bash
@ -30,56 +29,127 @@ In another terminal window or tab, run the Ethereum JSON-RPC server as well as t
emintcli rest-server --laddr "tcp://localhost:8545" --unlock-key mykey --chain-id 8 emintcli rest-server --laddr "tcp://localhost:8545" --unlock-key mykey --chain-id 8
``` ```
## Key Management ## Manual setup
To run a node with the same key every time: These instructions are for setting up a brand new full node from scratch.
replace `emintcli keys add $KEY` in `./init.sh` with:
First, initialize the node and create the necessary config files:
```bash ```bash
echo "your mnemonic here" | emintcli keys add ethermintkey --recover emintd init <your_custom_moniker>
``` ```
::: tip ::: warning
Ethermint currently only supports 24 word mnemonics. Monikers can contain only ASCII characters. Using Unicode characters will render your node unreachable.
::: :::
You can generate a new key/mnemonic with You can edit this `moniker` later, in the `$(HOME)/.emintd/config/config.toml` file:
```toml
# A custom human readable name for this node
moniker = "<your_custom_moniker>"
```
You can edit the `$HOME/.emintd/config/app.toml` file in order to enable the anti spam mechanism and reject incoming transactions with less than the minimum gas prices:
```toml
# This is a TOML config file.
# For more information, see https://github.com/toml-lang/toml
##### main base config options #####
# The minimum gas prices a validator is willing to accept for processing a
# transaction. A transaction's fees must meet the minimum of any denomination
# specified in this config (e.g. 10uatom).
minimum-gas-prices = ""
```
Your full node is now initiallized.
## Start node
To start your node, just type:
```bash ```bash
emintcli keys add <mykey> emintd start
```
## Key Management
To run a node with the same key every time: replace `emintcli keys add $KEY` in `./init.sh` with:
```bash
echo "your mnemonic here" | emintcli keys add $KEY --recover
```
::: tip Ethermint currently only supports 24 word mnemonics.
:::
You can generate a new key/mnemonic with:
```bash
emintcli keys add $KEY
``` ```
To export your ethermint key as an ethereum private key (for use with Metamask for example): To export your ethermint key as an ethereum private key (for use with Metamask for example):
```bash ```bash
emintcli keys unsafe-export-eth-key <mykey> emintcli keys unsafe-export-eth-key $KEY
``` ```
## Requesting tokens though the testnet faucet For more about the available key commands, use the `--help` flag
Once the ethermint daemon is up and running, you can request tokens to your address using the `faucet` module:
```bash ```bash
# query your initial balance emintcli keys -h
emintcli q bank balances $(emintcli keys show <mykey> -a)
# send a tx to request tokens to your account address
emintcli tx faucet request 100photon --from <mykey>
# query your balance after the request
emintcli q bank balances $(emintcli keys show <mykey> -a)
``` ```
You can also check to total amount funded by the faucet and the total supply of the chain via: ### Keyring backend options
The instructions above include commands to use `test` as the `keyring-backend`. This is an unsecured
keyring that doesn't require entering a password and should not be used in production. Otherwise,
Ethermint supports using a file or OS keyring backend for key storage. To create and use a file
stored key instead of defaulting to the OS keyring, add the flag `--keyring-backend file` to any
relevant command and the password prompt will occur through the command line. This can also be saved
as a CLI config option with:
```bash ```bash
# total amount funded by the faucet emintcli config keyring-backend file
emintcli q faucet funded
# total supply
emintcli q supply total
``` ```
## Clearing data from chain
### Reset Data
Alternatively, you can **reset** the blockchain database, remove the node's address book files, and reset the `priv_validator.json` to the genesis state.
::: danger
If you are running a **validator node**, always be careful when doing `emintd unsafe-reset-all`. You should never use this command if you are not switching `chain-id`.
:::
::: danger
**IMPORTANT**: Make sure that every node has a unique `priv_validator.json`. **Do not** copy the `priv_validator.json` from an old node to multiple new nodes. Running two nodes with the same `priv_validator.json` will cause you to double sign!
:::
First, remove the outdated files and reset the data.
```bash
rm $HOME/.emintd/config/addrbook.json $HOME/.emintd/config/genesis.json
emintd unsafe-reset-all
```
Your node is now in a pristine state while keeping the original `priv_validator.json` and `config.toml`. If you had any sentry nodes or full nodes setup before, your node will still try to connect to them, but may fail if they haven't also been upgraded.
### Delete Data
Data for the Daemon and CLI binaries should be stored at `~/.emintd` and `~/.emintcli`, respectively by default. To **delete** the existing binaries and configuration, run:
```bash
rm -rf ~/.emint*
```
To clear all data except key storage (if keyring backend chosen) and then you can rerun the full node installation commands from above to start the node again.
## Next {hide} ## Next {hide}
Learn about Ethermint [accounts](./../basic/accounts.md) {hide} Learn about running a Ethermint [testnet](./testnet.md) {hide}

67
docs/quickstart/testnet.md Normal file
View File

@ -0,0 +1,67 @@
<!--
order: 3
-->
# Testnet
Learn how to deploy a local testnet or connect to an existing one {synopsis}
## Pre-requisite Readings
- [Run Node](./run_node.md) {prereq}
## Genesis and Seeds
### Copy the Genesis File
<!-- TODO: link to genesis procedure -->
::: tip
If you want to start a network from scratch, you will need to start the genesis procedure.
:::
If you want to connect to an existing testnet, fetch the testnet's `genesis.json` file and copy it into the `emintd`'s config directory (i.e `$HOME/.emintd/config/genesis.json`).
Then verify the correctness of the genesis configuration file:
```bash
emintd validate-genesis
```
### Add Seed Nodes
Your node needs to know how to find peers. You'll need to add healthy seed nodes to `$HOME/.emintd/config/config.toml`. If those seeds aren't working, you can find more seeds and persistent peers on an existing explorer.
For more information on seeds and peers, you can the Tendermint [P2P documentation](https://docs.tendermint.com/master/spec/p2p/peer.html).
### Start testnet
The final step is to [start the nodes](./run_node.md#start-node). Once enough voting power (+2/3) from the genesis validators is up-and-running, the testnet will start producing blocks.
## Testnet faucet
Once the ethermint daemon is up and running, you can request tokens to your address using the `faucet` module:
```bash
# query your initial balance
emintcli q bank balances $(emintcli keys show <mykey> -a)
# send a tx to request tokens to your account address
emintcli tx faucet request 100photon --from <mykey>
# query your balance after the request
emintcli q bank balances $(emintcli keys show <mykey> -a)
```
You can also check to total amount funded by the faucet and the total supply of the chain via:
```bash
# total amount funded by the faucet
emintcli q faucet funded
# total supply
emintcli q supply total
```
## Next {hide}
Learn about how to setup a [validator](./validator-setup.md) node on Ethermint {hide}

97
docs/quickstart/upgrade.md Normal file
View File

@ -0,0 +1,97 @@
<!--
order: 5
-->
# Upgrade Node
Learn how to upgrade your full node to the latest software version {synopsis}
## Software Upgrade
These instructions are for full nodes that have ran on previous versions of and would like to upgrade to the latest testnet.
First, stop your instance of `emintd`. Next, upgrade the software:
```bash
cd ethermint
git fetch --all && git checkout <new_version>
make install
```
::: tip
If you have issues at this step, please check that you have the latest stable version of GO installed.
:::
You will need to ensure that the version installed matches the one needed for th testnet. Check the Ethermint [release page](https://github.com/ChainSafe/ethermint/releases) for details on each release.
## Upgrade Genesis File
:::warning
If the new version you are upgrading to has breaking changes, you will have to restart your chain. If it is **not** breaking, you can skip to [Restart](#restart-node).
:::
To upgrade the genesis file, you can either fetch it from a trusted source or export it locally using the `emintd export` command.
### Fetch from a Trusted Source
If you are joining an existing testnet, you can fetch the genesis from the appropriate testnet source/repository where the genesis file is hosted.
Save the new genesis as `new_genesis.json`. Then, replace the old `genesis.json` with `new_genesis.json`.
```bash
cd $HOME/.emintd/config
cp -f genesis.json new_genesis.json
mv new_genesis.json genesis.json
```
Finally, go to the [reset data](./run_node.md#reset-data) section.
### Export State to a new Genesis locally
Ethermint can dump the entire application state to a JSON file. This, besides upgrades, can be
useful for manual analysis of the state at a given height.
Export state with:
```bash
emintd export > new_genesis.json
```
You can also export state from a particular height (at the end of processing the block of that height):
```bash
emintd export --height [height] > new_genesis.json
```
If you plan to start a new network for 0 height (i.e genesis) from the exported state, export with the `--for-zero-height` flag:
```bash
emintd export --height [height] --for-zero-height > new_genesis.json
```
Then, replace the old `genesis.json` with `new_genesis.json`.
```bash
cp -f genesis.json new_genesis.json
mv new_genesis.json genesis.json
```
At this point, you might want to run a script to update the exported genesis into a genesis state that is compatible with your new version.
You can use the `migrate` command to migrate from a given version to the next one (eg: `v0.X.X` to `v1.X.X`):
```bash
emintd migrate [target-version] [/path/to/genesis.json] --chain-id=<new_chain_id> --genesis-time=<yyyy-mm-ddThh:mm:ssZ>
```
## Restart Node
To restart your node once the new genesis has been updated, use the `start` command:
```bash
emintd start
```
## Next {hide}
Learn about how to setup a [validator](./validator-setup.md) node on Ethermint {hide}

124
docs/quickstart/validator-setup.md Normal file
View File

@ -0,0 +1,124 @@
<!--
order: 4
-->
# Run a Validator
Configure a validator node to propose blocks and earn staking rewards {synopsis}
## Pre-requisite Readings
- [Installation](./installation.md) {prereq}
- [Run a Full Node](./run_node.md) {prereq}
## What is a Validator?
[Validators](https://hub.cosmos.network/master/validators/overview.html) are responsible for committing new blocks to the blockchain through voting. A validator's stake is slashed if they become unavailable or sign blocks at the same height. Please read about [Sentry Node Architecture](https://hub.cosmos.network/master/validators/validator-faq.html#how-can-validators-protect-themselves-from-denial-of-service-attacks) to protect your node from DDOS attacks and to ensure high-availability.
::: danger Warning
If you want to become a validator for `mainnet`, you should [research security](https://hub.cosmos.network/master/validators/security.html).
:::
You may want to skip the next section if you have already set up a [full node](../emint-tutorials/join-mainnet.md).
## Create Your Validator
Your `cosmosvalconspub` consensus public key fron tendermint can be used to create a new validator by staking tokens. You can find your validator pubkey by running:
```bash
emintd tendermint show-validator
```
To create your validator, just use the following command:
```bash
emintcli tx staking create-validator \
--amount=1000000photon \
--pubkey=$(emintd tendermint show-validator) \
--moniker=<ethermint_validator> \
--chain-id=<chain_id> \
--commission-rate="0.10" \
--commission-max-rate="0.20" \
--commission-max-change-rate="0.01" \
--min-self-delegation="1" \
--gas="auto" \
--gas-prices="0.025uatom" \
--from=<key_name>
```
::: tip
When specifying commission parameters, the `commission-max-change-rate` is used to measure % _point_ change over the `commission-rate`. E.g. 1% to 2% is a 100% rate increase, but only 1 percentage point.
:::
::: tip
`Min-self-delegation` is a stritly positive integer that represents the minimum amount of self-delegated voting power your validator must always have. A `min-self-delegation` of 1 means your validator will never have a self-delegation lower than `1000000photon`
:::
You can confirm that you are in the validator set by using a third party explorer.
## Genesis transactions
A genesis transaction (aka `gentx`) is a JSON file carrying a self-delegation from a validator. All genesis transactions are collected by a genesis coordinator and validated against an initial `genesis.json` file.
A `gentx` does three things:
1. Makes the `validator` account you created into a validator operator account (i.e. the account that controls the validator).
2. Self-delegates the provided `amount` of staking tokens.
3. Link the operator account with a Tendermint node pubkey that will be used for signing blocks. If no `--pubkey` flag is provided, it defaults to the local node pubkey created via the `emintd init` command above.
If you want to participate in genesis as a validator, you need to justify that
you have some stake at genesis, create one (or multiple) transactions to bond this stake to your validator address, and include this transaction in the genesis file.
Your `cosmosvalconspub`, as shown on the section above, can be used to create a validator transaction on genesis as well.
Next, craft your `emintd gentx` command:
::: tip
When specifying commission parameters, the `commission-max-change-rate` is used to measure % _point_ change over the `commission-rate`. E.g. 1% to 2% is a 100% rate increase, but only 1 percentage point.
:::
```bash
emintd gentx \
--amount <amount_of_delegation_uatom> \
--commission-rate <commission_rate> \
--commission-max-rate <commission_max_rate> \
--commission-max-change-rate <commission_max_change_rate> \
--pubkey $(emintd tendermint show-validator) \
--name $KEY
```
::: tip
For more on `gentx`, use the help flag: `emintd gentx -h`
:::
## Confirm Your Validator is Running
Your validator is active if the following command returns anything:
```bash
emintcli query tendermint-validator-set | grep "$(emintd tendermint show-validator)"
```
You should now see your validator in one of the block explorers. You are looking for the `bech32`
encoded `address` in the `~/.emintd/config/priv_validator.json` file.
::: tip
To be in the validator set, you need to have more total voting power than the 100th validator.
:::
## Halting Your Validator
When attempting to perform routine maintenance or planning for an upcoming coordinated
upgrade, it can be useful to have your validator systematically and gracefully halt the chain and shutdown the node.
You can achieve this by setting one of the following flags during when using the `emintd start` command:
- `--halt-height`: to the block height at which to shutdown the node
- `--halt-time`: to the minimum block time (in Unix seconds) at which to shutdown the node
The node will stop processing blocks with a zero exit code at that given height/time after
committing the block.
## Next {hide}
Start and connect a [client](./clients.md) to a running network {hide}