From 5ba8ce4605cfb9690628730b66a2d4984d9adc8a Mon Sep 17 00:00:00 2001 From: Federico Kunze <31522760+fedekunze@users.noreply.github.com> Date: Fri, 17 Jul 2020 20:07:05 +0200 Subject: [PATCH] testnet docs (#393) * testnet docs * more updates on quickstart docs * update quickstart * more updates * update quickstart * final touches * update lint --- .github/workflows/lint.yml | 2 +- README.md | 192 ++++++++--------------------- cmd/emintd/main.go | 1 + docs/core/README.md | 1 - docs/core/encoding.md | 2 +- docs/core/events.md | 103 ---------------- docs/intro/overview.md | 32 ++--- docs/quickstart/README.md | 10 +- docs/quickstart/clients.md | 62 ++++++++++ docs/quickstart/events.md | 134 ++++++++++++++++++++ docs/quickstart/installation.md | 38 ++++++ docs/quickstart/run_node.md | 142 +++++++++++++++------ docs/quickstart/testnet.md | 67 ++++++++++ docs/quickstart/upgrade.md | 97 +++++++++++++++ docs/quickstart/validator-setup.md | 124 +++++++++++++++++++ 15 files changed, 707 insertions(+), 300 deletions(-) delete mode 100644 docs/core/events.md create mode 100644 docs/quickstart/clients.md create mode 100644 docs/quickstart/events.md create mode 100644 docs/quickstart/installation.md create mode 100644 docs/quickstart/testnet.md create mode 100644 docs/quickstart/upgrade.md create mode 100644 docs/quickstart/validator-setup.md diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 980deb6c..c7abaa2d 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -23,7 +23,7 @@ jobs: - uses: golangci/golangci-lint-action@master with: # 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 github-token: ${{ secrets.github_token }} if: "env.GIT_DIFF != ''" diff --git a/README.md b/README.md index 609c002d..051b3515 100644 --- a/README.md +++ b/README.md @@ -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) + -# Ethermint +
+

Ethermint

+
-__**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. +
+ + Version + + + License: Apache-2.0 + + + GoDoc + + + Go report card + + + Code Coverage + +
+
+ + Lines Of Code + + + Discord + + + Build Status + + + Lint Status + +
-**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. -- 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`. +## Quick Start -### 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 -- 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 +## Tests -#### Current Work - -- 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: +Unit tests are invoked via: ```bash make test ``` -To run CLI tests, execute: +To run JSON-RPC tests, execute: ```bash -make test-cli +make test-rpc ``` -#### Ethereum Mainnet Import - -There is an included Ethereum mainnet exported blockchain file in `importer/blockchain` +There is also 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 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: - [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) diff --git a/cmd/emintd/main.go b/cmd/emintd/main.go index aa0d38fb..d0da3224 100644 --- a/cmd/emintd/main.go +++ b/cmd/emintd/main.go @@ -69,6 +69,7 @@ func main() { rootCmd.AddCommand( withChainIDValidation(genutilcli.InitCmd(ctx, cdc, app.ModuleBasics, app.DefaultNodeHome)), genutilcli.CollectGenTxsCmd(ctx, cdc, bank.GenesisBalancesIterator{}, app.DefaultNodeHome), + genutilcli.MigrateGenesisCmd(ctx, cdc), genutilcli.GenTxCmd( ctx, cdc, app.ModuleBasics, staking.AppModuleBasic{}, bank.GenesisBalancesIterator{}, app.DefaultNodeHome, app.DefaultCLIHome, diff --git a/docs/core/README.md b/docs/core/README.md index 4362fcf4..746c8fef 100644 --- a/docs/core/README.md +++ b/docs/core/README.md @@ -9,6 +9,5 @@ parent: This repository contains reference documentation on the core concepts of Ethermint. 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. diff --git a/docs/core/encoding.md b/docs/core/encoding.md index 08e6a58d..09f15d5c 100644 --- a/docs/core/encoding.md +++ b/docs/core/encoding.md @@ -70,4 +70,4 @@ will call this method for each necessary module. ## Next {hide} -Learn about [events](./events.md) {hide} +Learn how to connect Ethermint to [Metamask](./../guides/metamask.md) {hide} diff --git a/docs/core/events.md b/docs/core/events.md deleted file mode 100644 index b8a10b46..00000000 --- a/docs/core/events.md +++ /dev/null @@ -1,103 +0,0 @@ - - -# 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 - - - -## 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 --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 --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} diff --git a/docs/intro/overview.md b/docs/intro/overview.md index 7f2168d7..bfdb6da8 100644 --- a/docs/intro/overview.md +++ b/docs/intro/overview.md @@ -6,31 +6,33 @@ order: 1 ## What is Ethermint -Ethermint is a high throughput PoS blockchain that is fully compatible and -interoperable with Ethereum. In other words, it allows for running vanilla Ethereum -on top of [Tendermint](https://github.com/tendermint/tendermint) consensus via -the [Cosmos SDK](https://github.com/cosmos/cosmos-sdk/). This allows developers -to have all the desired features of Ethereum, while at the same time benefit +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. + +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 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: * Web3 compatibility -* High throughput -* Horizontal scalability -* Transaction finality +* High throughput via [Tendermint Core](https://github.com/tendermint/tendermint) +* Horizontal scalability via [IBC](https://github.com/cosmos/ics) +* Fast transaction finality +* [Hard Spoon](https://blog.cosmos.network/introducing-the-hard-spoon-4a9288d3f0df) 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 -* 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 +* 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 existing Ethereum clients and tooling (Metamask, Remix, Truffle, etc). -The sum of these features allows developers to leverage existing Ethereum ecosystem -tooling and software to seamlessly deploy smart contracts which interact with the rest of the Cosmos -ecosystem! +The sum of these features allows developers to leverage existing Ethereum ecosystem tooling and +software to seamlessly deploy smart contracts which interact with the rest of the Cosmos ecosystem! ## Next {hide} diff --git a/docs/quickstart/README.md b/docs/quickstart/README.md index 60566a2c..f4e17d50 100644 --- a/docs/quickstart/README.md +++ b/docs/quickstart/README.md @@ -8,10 +8,16 @@ parent: 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. ## Next {hide} -Learn how to run an Ethermint [node](./../quickstart/run_node.md) {hide} +Learn how to [install](./../quickstart/intallation.md) Ethermint {hide} diff --git a/docs/quickstart/clients.md b/docs/quickstart/clients.md new file mode 100644 index 00000000..fe3683eb --- /dev/null +++ b/docs/quickstart/clients.md @@ -0,0 +1,62 @@ + + +# 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} diff --git a/docs/quickstart/events.md b/docs/quickstart/events.md new file mode 100644 index 00000000..be2fc667 --- /dev/null +++ b/docs/quickstart/events.md @@ -0,0 +1,134 @@ + + +# 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 --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 --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} diff --git a/docs/quickstart/installation.md b/docs/quickstart/installation.md new file mode 100644 index 00000000..2bf55efd --- /dev/null +++ b/docs/quickstart/installation.md @@ -0,0 +1,38 @@ + + +# 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 +``` + + + + + +## 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} diff --git a/docs/quickstart/run_node.md b/docs/quickstart/run_node.md index afd58e84..43cad4e6 100644 --- a/docs/quickstart/run_node.md +++ b/docs/quickstart/run_node.md @@ -1,23 +1,22 @@ # Run a Node Run a local node and start the REST and JSON-RPC clients {synopsis} -Clone and build Ethermint: +## Pre-requisite Readings -```bash -git clone -cd ethermint -make install -``` +- [Installation](./installation.md) {prereq} -Run the local testnet node with faucet enabled: +## Script deployment + +Run the local node with faucet enabled: ::: 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 @@ -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 ``` -## Key Management +## Manual setup -To run a node with the same key every time: -replace `emintcli keys add $KEY` in `./init.sh` with: +These instructions are for setting up a brand new full node from scratch. + +First, initialize the node and create the necessary config files: ```bash -echo "your mnemonic here" | emintcli keys add ethermintkey --recover +emintd init ``` -::: tip -Ethermint currently only supports 24 word mnemonics. +::: warning +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 = "" +``` + +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 -emintcli keys add +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): ```bash -emintcli keys unsafe-export-eth-key +emintcli keys unsafe-export-eth-key $KEY ``` -## Requesting tokens though the testnet faucet - -Once the ethermint daemon is up and running, you can request tokens to your address using the `faucet` module: +For more about the available key commands, use the `--help` flag ```bash -# query your initial balance -emintcli q bank balances $(emintcli keys show -a) - -# send a tx to request tokens to your account address -emintcli tx faucet request 100photon --from - -# query your balance after the request -emintcli q bank balances $(emintcli keys show -a) +emintcli keys -h ``` -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 -# total amount funded by the faucet -emintcli q faucet funded - -# total supply -emintcli q supply total +emintcli config keyring-backend file ``` +## 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} -Learn about Ethermint [accounts](./../basic/accounts.md) {hide} +Learn about running a Ethermint [testnet](./testnet.md) {hide} diff --git a/docs/quickstart/testnet.md b/docs/quickstart/testnet.md new file mode 100644 index 00000000..e625b5bc --- /dev/null +++ b/docs/quickstart/testnet.md @@ -0,0 +1,67 @@ + + +# 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 + + +::: 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 -a) + +# send a tx to request tokens to your account address +emintcli tx faucet request 100photon --from + +# query your balance after the request +emintcli q bank balances $(emintcli keys show -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} diff --git a/docs/quickstart/upgrade.md b/docs/quickstart/upgrade.md new file mode 100644 index 00000000..aeb84596 --- /dev/null +++ b/docs/quickstart/upgrade.md @@ -0,0 +1,97 @@ + + +# 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 +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= --genesis-time= +``` + +## 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} diff --git a/docs/quickstart/validator-setup.md b/docs/quickstart/validator-setup.md new file mode 100644 index 00000000..acc96887 --- /dev/null +++ b/docs/quickstart/validator-setup.md @@ -0,0 +1,124 @@ + + +# 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= \ + --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= +``` + +::: 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 \ + --commission-rate \ + --commission-max-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}