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

docs: config updates (#409)

Browse Source 
* docs: more updates

* minor changes

* workflow

* yarn

* structure

* more updates

* cleanup

* additional cleanup

* docs

* interact with node

* additional guides and testnet docs

* update swagger

* update docs

* action
This commit is contained in:
Federico Kunze Küllmer
2021-08-09 21:21:21 +00:00
committed by GitHub
parent 73c2f8e529
commit 7b50331b98
41 changed files with 3095 additions and 1657 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/quickstart/README.md
+6 -9
View File
@@ -8,16 +8,13 @@ parent:
This repository contains reference documentation on how to install and run an Ethermint full node.
1. [Installation](./installation.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)
1. [Installation](./installation)
1. [Build and Configuration](./binary)
1. [Run a Node](./run_node)
1. [Interacting with the Node](./interact_node)
After going throught the Quick Start contents, head over to the [basics](./../basics/README.md) to learn more.
After going through the Quick Start contents, head over to the [basics](./../basics/README) to learn more.
## Next {hide}
Learn how to [install](./../quickstart/installation.md) Ethermint {hide}
Learn how to [install](./../quickstart/installation) Ethermint {hide}
docs/quickstart/binary.md
+148
View File
@@ -0,0 +1,148 @@
<!--
order: 2
-->
# `ethermintd`
`ethermintd` is the all-in-one command-line interface. It supports wallet management, queries and transaction operations {synopsis}
## Pre-requisite Readings
- [Installation](./installation.md) {prereq}
## Build and Configuration
### Using `ethermintd`
After you have obtained the latest `ethermintd` binary, run:
```bash
ethermintd [command]
```
Check the version you are running using
```bash
ethermintd version
```
There is also a `-h`, `--help` command available
```bash
ethermintd -h
```
::: tip
You can also enable auto-completion with the `ethermintd completion` command. For example, at the start of a bash session, run `. <(ethermintd completion)`, and all `ethermintd` subcommands will be auto-completed.
:::
### Config and data directory
By default, your config and data are stored in the folder located at the `~/.ethermintd` directory.
:::warning
Make sure you have backed up your wallet storage after creating the wallet or else your funds may be inaccessible in case of accident forever.
:::
To specify the `ethermintd` config and data storage directory; you can update it using the global flag `--home <directory>`
### Client configuration
We can view the default client config setting by using `ethermintd config` command:
```bash
ethermintd config
{
"chain-id": "",
"keyring-backend": "os",
"output": "text",
"node": "tcp://localhost:26657",
"broadcast-mode": "sync"
}
```
We can make changes to the default settings upon our choices, so it allows users to set the configuration beforehand all at once, so it would be ready with the same config afterward.
For example, the chain identifier can be changed to `ethermint-777` from a blank name by using:
```bash
ethermintd config "chain-id" ethermint-777
ethermintd config
{
"chain-id": "ethermint-777",
"keyring-backend": "os",
"output": "text",
"node": "tcp://localhost:26657",
"broadcast-mode": "sync"
}
```
Other values can be changed in the same way.
Alternatively, we can directly make the changes to the config values in one place at client.toml. It is under the path of `.ethermint/config/client.toml` in the folder where we installed ethermint:
```toml
############################################################################
### Client Configuration ###
############################################################################
# The network chain ID
chain-id = "ethermint-777"
# The keyring's backend, where the keys are stored (os|file|kwallet|pass|test|memory)
keyring-backend = "os"
# CLI output format (text|json)
output = "number"
# <host>:<port> to Tendermint RPC interface for this chain
node = "tcp://localhost:26657"
# Transaction broadcasting mode (sync|async|block)
broadcast-mode = "sync"
```
After the necessary changes are made in the `client.toml`, then save. For example, if we directly change the chain-id from `ethermint-0` to `etherminttest-1`, and output to number, it would change instantly as shown below.
```bash
ethermintd config
{
"chain-id": "etherminttest-1",
"keyring-backend": "os",
"output": "number",
"node": "tcp://localhost:26657",
"broadcast-mode": "sync"
}
```
### Options
A list of commonly used flags of `ethermintd` is listed below:
| Option | Description | Type | Default Value |
| ------------------- | ----------------------------- | ------------ | --------------- |
| `--chain-id` | Full Chain ID | String | --- |
| `--home` | Directory for config and data | string | `~/.ethermintd` |
| `--keyring-backend` | Select keyring's backend | os/file/test | os |
| `--output` | Output format | string | "text" |
## Command list
A list of commonly used `ethermintd` commands. You can obtain the full list by using the `ethermintd -h` command.
| Command | Description | Subcommands (example) |
| --------------- | ------------------------ | ------------------------------------------------------------ |
| `keys` | Keys management | `list`, `show`, `add`, `add --recover`, `delete` |
| `tx` | Transactions subcommands | `bank send`, `ibc-transfer transfer`, `distribution withdraw-all-rewards` |
| `query` | Query subcommands | `bank balance`, `staking validators`, `gov proposals` |
| `tendermint` | Tendermint subcommands | `show-address`, `show-node-id`, `version` |
| `config` | Client configuration | |
| `init` | Initialize full node | |
| `start` | Run full node | |
| `version` | Ethermint version | |
docs/quickstart/clients.md
-36
View File
@@ -1,36 +0,0 @@
<!--
order: 6
-->
# Clients
Learn how to connect a client to a running node. {synopsis}
## Pre-requisite Readings
- [Run a Node](./run_node.md) {prereq}
- [Interacting with the Node](https://docs.cosmos.network/v0.43/run-node/interact-node.html) {prereq}
### Client Servers
The Ethermint client supports both [gRPC endpoints](https://cosmos.network/rpc) from the SDK and Ethereum's [JSON-RPC](https://eth.wiki/json-rpc/API).
#### Cosmos gRPC and Tendermint RPC
Ethermint exposes gRPC endpoints (and REST) for all the integrated Cosmos-SDK modules. This makes it easier for
wallets and block explorers to interact with the proof-of-stake logic and native Cosmos transactions and queries:
#### 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
See the list of supported JSON-RPC API [namespaces](https://geth.ethereum.org/docs/rpc/server) and endpoints.
:::
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 (`--evm-rpc.address`).
## Next {hide}
Process and subscribe to [events](./events.md) via websockets {hide}
docs/quickstart/events.md
-134
View File
@@ -1,134 +0,0 @@
<!--
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 `--rpc.laddr`
flag when starting the node (default `tcp://127.0.0.1:26657`):
```bash
ethermintd start --rpc.laddr="tcp://127.0.0.1:26657"
```
Then, start a websocket subscription with [ws](https://github.com/hashrocket/ws)
```bash
# connect to tendermint websocket 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 `--evm-rpc.ws-address` flag when starting
the node (default `"0.0.0.0:8546"`):
```bash
ethermintd start --evm-rpc.address"0.0.0.0:8545" --evm-rpc.ws-address="0.0.0.0:8546" --evm.rpc.api="eth,web3,net,txpool,debug" --evm-rpc.enable
```
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}
docs/quickstart/installation.md
+16 -4
View File
@@ -4,7 +4,15 @@ order: 1
# Installation
## Binaries
## Pre-requisites
### Install [`jq`](https://stedolan.github.io/jq)
On Mac `brew install jq` or download the official binaries on the project [website](https://stedolan.github.io/jq/download/).
## Install Binaries
### GitHub
Clone and build Ethermint using `git`:
@@ -17,7 +25,7 @@ make install
Check that the binaries have been successfully installed:
```bash
ethermintd -h
ethermintd version
```
## Docker
@@ -32,7 +40,7 @@ This will install the binaries on the `./build` directory. Now, check that the b
successfully installed:
```bash
ethermintd -h
ethermintd version
```
## Releases
@@ -41,7 +49,11 @@ ethermintd -h
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/tharsis/ethermint/releases)
You can also download a specific release available on the Ethermint [repository](https://github.com/tharsis/ethermint/releases) or via command line:
```bash
go install github.com/tharsis/ethermint@latest
```
## Next {hide}
docs/quickstart/interact_node.md
+223
View File
@@ -0,0 +1,223 @@
<!--
order: 4
-->
# Interacting with the Node
There are multiple ways to interact with a node: using the CLI, using gRPC or using the REST endpoints. {synopsis}
## Using the CLI
Now that your very own node is running, it is time to try sending tokens from the first account you created to a second account. In a new terminal window, start by running the following query command:
```bash
ethermintd query bank balances $MY_VALIDATOR_ADDRESS --chain-id=ethermintd-1
```
You should see the current balance of the account you created, equal to the original balance of `eth` you granted it minus the amount you delegated via the `gentx`. Now, create a second account:
```bash
ethermintd keys add recipient --keyring-backend=file
# Put the generated address in a variable for later use.
RECIPIENT=$(ethermintd keys show recipient -a --keyring-backend=file)
```
The command above creates a local key-pair that is not yet registered on the chain. An account is created the first time it receives tokens from another account. Now, run the following command to send tokens to the `recipient` account:
```bash
ethermintd tx bank send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000000aphoton --chain-id=ethermintd-1 --keyring-backend=file
# Check that the recipient account did receive the tokens.
ethermintd query bank balances $RECIPIENT --chain-id=ethermintd-1
```
Finally, delegate some of the stake tokens sent to the `recipient` account to the validator:
```bash
ethermintd tx staking delegate $(ethermintd keys show my_validator --bech val -a --keyring-backend=file) 500aphoton --from=recipient --chain-id=ethermintd-1 --keyring-backend=file
# Query the total delegations to `validator`.
ethermintd query staking delegations-to $(ethermintd keys show my_validator --bech val -a --keyring-backend=file) --chain-id=ethermintd-1
```
You should see two delegations, the first one made from the `gentx`, and the second one you just performed from the `recipient` account.
## Using gRPC
The Protobuf ecosystem developed tools for different use cases, including code-generation from `*.proto` files into various languages. These tools allow the building of clients easily. Often, the client connection (i.e. the transport) can be plugged and replaced very easily. Let's explore one of the most popular transport: gRPC.
Since the code generation library largely depends on your own tech stack, we will only present three alternatives:
- `grpcurl` for generic debugging and testing
- programmatically via Go
- CosmJS for JavaScript/TypeScript developers
### grpcurl
[grpcurl](https://github.com/fullstorydev/grpcurl) is like `curl` but for gRPC. It is also available as a Go library, but we will use it only as a CLI command for debugging and testing purposes. Follow the instructions in the previous link to install it.
Assuming you have a local node running (either a localnet, or connected a live network), you should be able to run the following command to list the Protobuf services available (you can replace `localhost:9000` by the gRPC server endpoint of another node, which is configured under the `grpc.address` field inside [`app.toml`](/run-node.md#configuring-the-node-using-apptoml)):
```bash
grpcurl -plaintext localhost:9090 list
```
You should see a list of gRPC services, like `cosmos.bank.v1beta1.Query`. This is called reflection, which is a Protobuf endpoint returning a description of all available endpoints. Each of these represents a different Protobuf service, and each service exposes multiple RPC methods you can query against.
In order to get a description of the service you can run the following command:
```bash
# Service we want to inspect
grpcurl \
localhost:9090 \
describe cosmos.bank.v1beta1.Query
```
It's also possible to execute an RPC call to query the node for information:
```bash
grpcurl \
-plaintext
-d '{"address":"$MY_VALIDATOR"}' \
localhost:9090 \
cosmos.bank.v1beta1.Query/AllBalances
```
#### Query for historical state using grpcurl
You may also query for historical data by passing some [gRPC metadata](https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md) to the query: the `x-cosmos-block-height` metadata should contain the block to query. Using grpcurl as above, the command looks like:
```bash
grpcurl \
-plaintext \
-H "x-cosmos-block-height: 279256" \
-d '{"address":"$MY_VALIDATOR"}' \
localhost:9090 \
cosmos.bank.v1beta1.Query/AllBalances
```
Assuming the state at that block has not yet been pruned by the node, this query should return a non-empty response.
### Programmatically via Go
The following snippet shows how to query the state using gRPC inside a Go program. The idea is to create a gRPC connection, and use the Protobuf-generated client code to query the gRPC server.
```go
import (
"context"
"fmt"
"google.golang.org/grpc"
sdk "github.com/cosmos/cosmos-sdk/types"
"github.com/cosmos/cosmos-sdk/types/tx"
)
func queryState() error {
myAddress, err := sdk.AccAddressFromBech32("eth...")
if err != nil {
return err
}
// Create a connection to the gRPC server.
grpcConn := grpc.Dial(
"127.0.0.1:9090", // your gRPC server address.
grpc.WithInsecure(), // The SDK doesn't support any transport security mechanism.
)
defer grpcConn.Close()
// This creates a gRPC client to query the x/bank service.
bankClient := banktypes.NewQueryClient(grpcConn)
bankRes, err := bankClient.Balance(
context.Background(),
&banktypes.QueryBalanceRequest{Address: myAddress, Denom: "eth"},
)
if err != nil {
return err
}
fmt.Println(bankRes.GetBalance()) // Prints the account balance
return nil
}
```
#### Query for historical state using Go
Querying for historical blocks is done by adding the block height metadata in the gRPC request.
```go
import (
"context"
"fmt"
"google.golang.org/grpc"
"google.golang.org/grpc/metadata"
grpctypes "github.com/cosmos/cosmos-sdk/types/grpc"
"github.com/cosmos/cosmos-sdk/types/tx"
)
func queryState() error {
// --snip--
var header metadata.MD
bankRes, err = bankClient.Balance(
metadata.AppendToOutgoingContext(context.Background(), grpctypes.GRPCBlockHeightHeader, "12"), // Add metadata to request
&banktypes.QueryBalanceRequest{Address: myAddress, Denom: denom},
grpc.Header(&header), // Retrieve header from response
)
if err != nil {
return err
}
blockHeight = header.Get(grpctypes.GRPCBlockHeightHeader)
fmt.Println(blockHeight) // Prints the block height (12)
return nil
}
```
### CosmJS
CosmJS documentation can be found at [https://cosmos.github.io/cosmjs](https://cosmos.github.io/cosmjs). As of January 2021, CosmJS documentation is still work in progress.
## Using the REST Endpoints
All gRPC services on the Cosmos SDK are made available for more convenient REST-based queries through gRPC-gateway. The format of the URL path is based on the Protobuf service method's full-qualified name, but may contain small customizations so that final URLs look more idiomatic. For example, the REST endpoint for the `cosmos.bank.v1beta1.Query/AllBalances` method is `GET /cosmos/bank/v1beta1/balances/{address}`. Request arguments are passed as query parameters.
As a concrete example, the `curl` command to make balances request is:
```bash
curl \
-X GET \
-H "Content-Type: application/json" \
http://localhost:1317/cosmos/bank/v1beta1/balances/$MY_VALIDATOR
```
Make sure to replace `localhost:1317` with the REST endpoint of your node, configured under the `api.address` field.
The list of all available REST endpoints is available as a Swagger specification file, it can be viewed at `localhost:1317/swagger`. Make sure that the `api.swagger` field is set to true in your [`app.toml`](/run-node.md#configuring-the-node-using-apptoml) file.
### Query for historical state using REST
Querying for historical state is done using the HTTP header `x-cosmos-block-height`. For example, a curl command would look like:
```bash
curl \
-X GET \
-H "Content-Type: application/json" \
-H "x-cosmos-block-height: 279256"
http://localhost:1317/cosmos/bank/v1beta1/balances/$MY_VALIDATOR
```
Assuming the state at that block has not yet been pruned by the node, this query should return a non-empty response.
### Cross-Origin Resource Sharing (CORS)
[CORS policies](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) are not enabled by default to help with security. If you would like to use the rest-server in a public environment we recommend you provide a reverse proxy, this can be done with [nginx](https://www.nginx.com/). For testing and development purposes there is an `enabled-unsafe-cors` field inside [`app.toml`](/run-node.md#configuring-the-node-using-apptoml).
## Next {hide}
Sending transactions using gRPC and REST requires some additional steps: generating the transaction, signing it, and finally broadcasting it. Read about [generating and signing transactions](./txs.md). {hide}
docs/quickstart/run_node.md
+7 -2
View File
@@ -1,15 +1,20 @@
<!--
order: 2
order: 3
-->
# Run a Node
Run a local node and start the REST and JSON-RPC clients {synopsis}
Configure and run an Ethermint node {synopsis}
## Pre-requisite Readings
- [Installation](./installation.md) {prereq}
## Configure the node daemon
Before kick-starting your node, we will have to configure your node so that it connects to the testnet:
## Automated deployment
Run the local node
docs/quickstart/testnet.md
-316
View File
@@ -1,316 +0,0 @@
<!--
order: 3
-->
# Testnet
Learn how to deploy a local testnet or connect to an existing public one {synopsis}
## Pre-requisite Readings
- [Install Ethermint](./installation.md) {prereq}
- [Install Docker](https://docs.docker.com/engine/installation/) {prereq}
- [Install docker-compose](https://docs.docker.com/compose/install/) {prereq}
<!-- - [Install `jq`](https://stedolan.github.io/jq/download/) {prereq} -->
## Single-node, Local, Manual Testnet
This guide helps you create a single validator node that runs a network locally for testing and other development related uses.
### Initialize node
```bash
$MONIKER=testing
$KEY=mykey
$CHAINID="ethermint-1"
ethermintd init $MONIKER --chain-id=$CHAINID
```
::: warning
Monikers can contain only ASCII characters. Using Unicode characters will render your node unreachable.
:::
You can edit this `moniker` later, in the `$(HOME)/.ethermintd/config/config.toml` file:
```toml
# A custom human readable name for this node
moniker = "<your_custom_moniker>"
```
You can edit the `$HOME/.ethermintd/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. 10aphoton).
minimum-gas-prices = ""
```
### Genesis Procedure
```bash
# Create a key to hold your account
ethermintd keys add $KEY
# Add that key into the genesis.app_state.accounts array in the genesis file
# NOTE: this command lets you set the number of coins. Make sure this account has some coins
# with the genesis.app_state.staking.params.bond_denom denom, the default is staking
ethermintd add-genesis-account $(ethermintd keys show validator -a) 1000000000stake,10000000000aphoton
# Generate the transaction that creates your validator
ethermintd gentx --name $KEY
# Add the generated bonding transaction to the genesis file
ethermintd collect-gentxs
# Finally, check the correctness of the genesis.json file
ethermintd validate-genesis
```
### Run Testnet
Now its safe to start the daemon:
```bash
ethermintd start
```
You can then stop the node using Ctrl+C.
## Multi-node, Local, Automated Testnet
### Build Testnet & Start Testnet
To build start a 4 node testnet run:
```bash
make localnet-start
```
This command creates a 4-node network using the `ethermintdnode` Docker image.
The ports for each node are found in this table:
| Node ID | P2P Port | Tendermint RPC Port | REST/ Ethereum JSON-RPC Port | WebSocket Port |
|------------------|----------|---------------------|------------------------------|----------------|
| `ethermintnode0` | `26656` | `26657` | `8545` | `8546` |
| `ethermintnode1` | `26659` | `26660` | `8547` | `8548` |
| `ethermintnode2` | `26661` | `26662` | `8549` | `8550` |
| `ethermintnode3` | `26663` | `26664` | `8551` | `8552` |
To update the binary, just rebuild it and restart the nodes
```bash
make localnet-start
```
The command above command will run containers in the background using Docker compose. You will see the network being created:
```bash
...
Creating network "ethermint_localnet" with driver "bridge"
Creating ethermintdnode0 ... done
Creating ethermintdnode2 ... done
Creating ethermintdnode1 ... done
Creating ethermintdnode3 ... done
```
### Stop Testnet
Once you are done, execute:
```bash
make localnet-stop
```
### Configuration
The `make localnet-start` creates files for a 4-node testnet in `./build` by
calling the `ethermintd testnet` command. This outputs a handful of files in the
`./build` directory:
```bash
tree -L 3 build/
build/
├── ethermintd
├── ethermintd
├── gentxs
│   ├── node0.json
│   ├── node1.json
│   ├── node2.json
│   └── node3.json
├── node0
│   ├── ethermintd
│   │   ├── key_seed.json
│   │   └── keyring-test-cosmos
│   └── ethermintd
│   ├── config
│   ├── data
│   └── ethermintd.log
├── node1
│   ├── ethermintd
│   │   ├── key_seed.json
│   │   └── keyring-test-cosmos
│   └── ethermintd
│   ├── config
│   ├── data
│   └── ethermintd.log
├── node2
│   ├── ethermintd
│   │   ├── key_seed.json
│   │   └── keyring-test-cosmos
│   └── ethermintd
│   ├── config
│   ├── data
│   └── ethermintd.log
└── node3
├── ethermintd
│   ├── key_seed.json
│   └── keyring-test-cosmos
└── ethermintd
├── config
├── data
└── ethermintd.log
```
Each `./build/nodeN` directory is mounted to the `/ethermintd` directory in each container.
### Logging
In order to see the logs of a particular node you can use the following command:
```bash
# node 0: daemon logs
docker exec ethermintdnode0 tail ethermintd.log
# node 0: REST & RPC logs
docker exec ethermintdnode0 tail ethermintd.log
```
The logs for the daemon will look like:
```bash
I[2020-07-29|17:33:52.452] starting ABCI with Tendermint module=main
E[2020-07-29|17:33:53.394] Can't add peer's address to addrbook module=p2p err="Cannot add non-routable address 272a247b837653cf068d39efd4c407ffbd9a0e6f@192.168.10.5:26656"
E[2020-07-29|17:33:53.394] Can't add peer's address to addrbook module=p2p err="Cannot add non-routable address 3e05d3637b7ebf4fc0948bbef01b54d670aa810a@192.168.10.4:26656"
E[2020-07-29|17:33:53.394] Can't add peer's address to addrbook module=p2p err="Cannot add non-routable address 689f8606ede0b26ad5b79ae244c14cc67ab4efe7@192.168.10.3:26656"
I[2020-07-29|17:33:58.828] Executed block module=state height=88 validTxs=0 invalidTxs=0
I[2020-07-29|17:33:58.830] Committed state module=state height=88 txs=0 appHash=90CC5FA53CF8B5EC49653A14DA20888AD81C92FCF646F04D501453FD89FCC791
I[2020-07-29|17:34:04.032] Executed block module=state height=89 validTxs=0 invalidTxs=0
I[2020-07-29|17:34:04.034] Committed state module=state height=89 txs=0 appHash=0B54C4DB1A0DACB1EEDCD662B221C048C826D309FD2A2F31FF26BAE8D2D7D8D7
I[2020-07-29|17:34:09.381] Executed block module=state height=90 validTxs=0 invalidTxs=0
I[2020-07-29|17:34:09.383] Committed state module=state height=90 txs=0 appHash=75FD1EE834F0669D5E717C812F36B21D5F20B3CCBB45E8B8D415CB9C4513DE51
I[2020-07-29|17:34:14.700] Executed block module=state height=91 validTxs=0 invalidTxs=0
```
::: tip
You can disregard the `Can't add peer's address to addrbook` warning. As long as the blocks are
being produced and the app hashes are the same for each node, there should not be any issues.
:::
Whereas the logs for the REST & RPC server would look like:
```bash
I[2020-07-30|09:39:17.488] Starting application REST service (chain-id: "7305661614933169792")... module=rest-server
I[2020-07-30|09:39:17.488] Starting RPC HTTP server on 127.0.0.1:8545 module=rest-server
...
```
#### Follow Logs
You can also watch logs as they are produced via Docker with the `--follow` (`-f`) flag, for
example:
```bash
docker logs -f ethermintdnode0
```
### Interact With the Testnet
#### Ethereum JSON RPC & Websocket Ports
To interact with the testnet via WebSockets or RPC/API, you will send your request to the corresponding ports:
| EVM JSON-RPC | Eth Websocket |
|--------------|---------------|
| `8545` | `8546` |
You can send a curl command such as:
```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_accounts","params":[],"id":1}' -H "Content-Type: application/json" 192.162.10.1:8545
```
::: tip
The IP address will be the public IP of the docker container.
:::
Additional instructions on how to interact with the WebSocket can be found on the [events documentation](./events.md#ethereum-websocket).
### Keys & Accounts
To interact with `ethermintd` and start querying state or creating txs, you use the
`ethermintd` directory of any given node as your `home`, for example:
```bash
ethermintd keys list --home ./build/node0/ethermintd
```
Now that accounts exists, you may create new accounts and send those accounts
funds!
::: tip
**Note**: Each node's seed is located at `./build/nodeN/ethermintd/key_seed.json` and can be restored to the CLI using the `ethermintd keys add --restore` command
:::
### Special Binaries
If you have multiple binaries with different names, you can specify which one to run with the BINARY environment variable. The path of the binary is relative to the attached volume. For example:
```bash
# Run with custom binary
BINARY=ethermint make localnet-start
```
## Multi-node, Public, Manual Testnet
If you are looking to connect to a persistent public testnet. You will need to manually configure your node.
### 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](#genesis-procedure) by creating a `genesis.json` and submit + collect the genesis transactions from the [validators](./validator-setup.md).
:::
If you want to connect to an existing testnet, fetch the testnet's `genesis.json` file and copy it into the `ethermintd`'s config directory (i.e `$HOME/.ethermintd/config/genesis.json`).
Then verify the correctness of the genesis configuration file:
```bash
ethermintd validate-genesis
```
#### Add Seed Nodes
Your node needs to know how to find peers. You'll need to add healthy seed nodes to `$HOME/.ethermintd/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.
## Next {hide}
Learn about how to setup a [validator](./validator-setup.md) node on Ethermint {hide}
docs/quickstart/upgrade.md
-97
View File
@@ -1,97 +0,0 @@
<!--
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 `ethermintd`. 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/tharsis/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 `ethermintd 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/.ethermintd/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
ethermintd export > new_genesis.json
```
You can also export state from a particular height (at the end of processing the block of that height):
```bash
ethermintd 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
ethermintd 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
ethermintd 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
ethermintd start
```
## Next {hide}
Learn about how to setup a [validator](./validator-setup.md) node on Ethermint {hide}
docs/quickstart/validator-setup.md
-124
View File
@@ -1,124 +0,0 @@
<!--
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
ethermintd tendermint show-validator
```
To create your validator, just use the following command:
```bash
ethermintd tx staking create-validator \
--amount=1000000aphoton \
--pubkey=$(ethermintd 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 strictly 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 `1000000aphoton`
:::
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 `ethermintd 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 `ethvalconspub`, as shown on the section above, can be used to create a validator transaction on genesis as well.
Next, craft your `ethermintd 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
ethermintd 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 $(ethermintd tendermint show-validator) \
--name $KEY
```
::: tip
For more on `gentx`, use the help flag: `ethermintd gentx -h`
:::
## Confirm Your Validator is Running
Your validator is active if the following command returns anything:
```bash
ethermintd query tendermint-validator-set | grep "$(ethermintd 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 `~/.ethermintd/config/priv_validator.json` file.
::: tip
To be in the validator set, you need to have more total voting power than the 100th validator.
:::
## Halt Your Validator Node
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 `ethermintd 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}