deep-stack/laconicd-deprecated
4
0
Fork 0
forked from cerc-io/laconicd-deprecated
Code Pull Requests 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 14:07:05 -04:00
committed by GitHub
parent 2fb4ab4862
commit 5ba8ce4605
15 changed files with 707 additions and 300 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/quickstart/README.md
+8 -2
View File
@@ -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}
docs/quickstart/clients.md
+62
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}
docs/quickstart/events.md
+134
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}
docs/quickstart/installation.md
+38
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}
docs/quickstart/run_node.md
+106 -36
View File
@@ -1,23 +1,22 @@
<!--
order: 1
order: 2
-->
# 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 <https://github.com/ChainSafe/ethermint>
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 <your_custom_moniker>
```
::: 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 = "<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
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):
```bash
emintcli keys unsafe-export-eth-key <mykey>
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 <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)
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}
docs/quickstart/testnet.md
+67
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}
docs/quickstart/upgrade.md
+97
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}
docs/quickstart/validator-setup.md
+124
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}