cerc-io/laconicd
18
0
Fork 2
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases 10 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 17:21:21 -04:00 committed by GitHub
parent 73c2f8e529
commit 7b50331b98
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
41 changed files with 3095 additions and 1657 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
.github/workflows/docs.yml vendored
View File

@ -1,34 +1,58 @@
name: Documentation name: Documentation
# This job builds and deploys documenation to github pages.
# It runs on every push to main.
on: on:
# trigger deployment on every push to main branch
push: push:
branches: branches:
- main - main
schedule: # trigger deployment manually
- cron: "* 0 * * *" workflow_dispatch:
jobs: jobs:
build-and-deploy: docs:
runs-on: ubuntu-latest runs-on: ubuntu-latest
container:
image: tendermintdev/docker-website-deployment
steps: steps:
- name: Checkout 🛎️ - uses: actions/checkout@v2.3.4
uses: actions/checkout@v2.3.1
with: with:
persist-credentials: false # fetch all commits to get last updated time or other git log info
fetch-depth: 0 fetch-depth: 0
repository: "tharsis/ethermint"
- name: Install and Build 🔧 - name: Setup Node.js
run: | uses: actions/setup-node@v1
apk add rsync
make build-docs LEDGER_ENABLED=false
- name: Deploy 🚀
uses: JamesIves/github-pages-deploy-action@4.1.4
with: with:
# choose node.js version to use
node-version: '14'
# cache node_modules
- name: Cache dependencies
uses: actions/cache@v2
id: yarn-cache
with:
path: |
**/node_modules
key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
restore-keys: |
${{ runner.os }}-yarn-
# install dependencies if the cache did not hit
- name: Install dependencies
if: steps.yarn-cache.outputs.cache-hit != 'true'
run: yarn --frozen-lockfile
# run build script
- name: Build VuePress site
run: yarn docs:build
# please check out the docs of the workflow for more details
# @see https://github.com/crazy-max/ghaction-github-pages
- name: Deploy to GitHub Pages
uses: crazy-max/ghaction-github-pages@v2
with:
# deploy to gh-pages branch
target_branch: gh-pages
# deploy the default output dir of VuePress
build_dir: docs/.vuepress/dist
env:
# @see https://docs.github.com/en/actions/reference/authentication-in-a-workflow#about-the-github_token-secret
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
BRANCH: gh-pages
FOLDER: ~/output

20
Makefile
View File

@ -265,18 +265,22 @@ godocs:
@echo "--> Wait a few seconds and visit http://localhost:6060/pkg/github.com/tharsis/ethermint/types" @echo "--> Wait a few seconds and visit http://localhost:6060/pkg/github.com/tharsis/ethermint/types"
godoc -http=:6060 godoc -http=:6060
# Start docs site at localhost:8080
docs-serve:
@cd docs && \
yarn && \
yarn run serve
# This builds a docs site for each branch/tag in `./docs/versions` # This builds a docs site for each branch/tag in `./docs/versions`
# and copies each site to a version prefixed path. The last entry inside # and copies each site to a version prefixed path. The last entry inside
# the `versions` file will be the default root index.html. # the `versions` file will be the default root index.html.
build-docs: build-docs:
@cd docs && \ # Build the site into docs/.vuepress/dist
while read -r branch path_prefix; do \ @$(MAKE) docs-tools-stamp && \
(git checkout $${branch} && npm install && VUEPRESS_BASE="/$${path_prefix}/" npm run build) ; \ cd docs && \
mkdir -p ~/output/$${path_prefix} ; \ yarn && \
cp -r .vuepress/dist/* ~/output/$${path_prefix}/ ; \ yarn run build
cp ~/output/$${path_prefix}/index.html ~/output ; \ .PHONY: docs-serve build-docs
done < versions ;
.PHONY: build-docs
############################################################################### ###############################################################################
### Tests & Simulation ### ### Tests & Simulation ###

2
client/docs/statik/statik.go
View File

File diff suppressed because one or more lines are too long

128
docs/.vuepress/config.js
View File

@ -6,6 +6,29 @@ module.exports = {
lang: 'en-US' lang: 'en-US'
}, },
}, },
markdown: {
extendMarkdown: (md) => {
md.use(require("markdown-it-katex"));
},
},
head: [
[
"link",
{
rel: "stylesheet",
href:
"https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.5.1/katex.min.css",
},
],
[
"link",
{
rel: "stylesheet",
href:
"https://cdn.jsdelivr.net/github-markdown-css/2.2.1/github-markdown.css",
},
],
],
base: process.env.VUEPRESS_BASE || '/', base: process.env.VUEPRESS_BASE || '/',
themeConfig: { themeConfig: {
repo: 'tharsis/ethermint', repo: 'tharsis/ethermint',
@ -15,7 +38,7 @@ module.exports = {
editLinks: true, editLinks: true,
custom: true, custom: true,
logo: { logo: {
src: '/logo.svg', src: '/ethermint-logo-horizontal-alpha.svg',
}, },
algolia: { algolia: {
id: 'BH4D9OD16A', id: 'BH4D9OD16A',
@ -27,9 +50,11 @@ module.exports = {
}, },
sidebar: { sidebar: {
auto: false, auto: false,
nav: [{ nav: [
{
title: 'Reference', title: 'Reference',
children: [{ children: [
{
title: 'Introduction', title: 'Introduction',
directory: true, directory: true,
path: '/intro' path: '/intro'
@ -49,11 +74,51 @@ module.exports = {
directory: true, directory: true,
path: '/core' path: '/core'
}, },
]
},
{
title: 'Guides',
children: [
{
title: 'Localnet',
directory: true,
path: '/guides/localnet'
},
{
title: 'Wallets',
directory: true,
path: '/guides/wallets'
},
{
title: 'Ethereum Tooling',
directory: true,
path: '/guides/tools'
},
]
},
{
title: 'APIs',
children: [
{
title: 'JSON-RPC',
directory: true,
path: '/api/json-rpc'
},
{
title: 'Protobuf Reference',
directory: false,
path: '/api/proto-docs'
},
]
},
{
title: 'Testnet',
children: [
{ {
title: 'Guides', title: 'Guides',
directory: true, directory: true,
path: '/guides' path: '/testnet'
} },
] ]
}, },
{ {
@ -65,17 +130,18 @@ module.exports = {
}] }]
}, { }, {
title: 'Resources', title: 'Resources',
children: [{ children: [
{
title: 'Ethermint API Reference', title: 'Ethermint API Reference',
path: 'https://godoc.org/github.com/tharsis/ethermint' path: 'https://pkg.go.dev/github.com/tharsis/ethermint'
}, },
{ {
title: 'Cosmos REST API Spec', title: 'Cosmos REST API Spec',
path: 'https://cosmos.network/rpc/' path: 'https://cosmos.network/rpc/'
}, },
{ {
title: 'Ethereum JSON RPC API Reference', title: 'JSON-RPC API Reference',
path: 'https://eth.wiki/json-rpc/API' path: '/api/json-rpc/endpoints'
} }
] ]
} }
@ -86,13 +152,13 @@ module.exports = {
chat: { chat: {
title: 'Developer Chat', title: 'Developer Chat',
text: 'Chat with Ethermint developers on Discord.', text: 'Chat with Ethermint developers on Discord.',
url: 'https://discordapp.com/channels/669268347736686612', url: 'https://discord.gg/3ZbxEq4KDu',
bg: 'linear-gradient(103.75deg, #1B1E36 0%, #22253F 100%)' bg: 'linear-gradient(103.75deg, #1B1E36 0%, #22253F 100%)'
}, },
forum: { forum: {
title: 'Ethermint Developer Forum', title: 'Ethermint Developer Forum',
text: 'Join the Ethermint Developer Forum to learn more.', text: 'Join the Ethermint Developer Forum to learn more.',
url: 'https://forum.cosmos.network/', url: 'https://forum.cosmos.network/c/ethermint',
bg: 'linear-gradient(221.79deg, #3D6B99 -1.08%, #336699 95.88%)', bg: 'linear-gradient(221.79deg, #3D6B99 -1.08%, #336699 95.88%)',
logo: 'ethereum-white' logo: 'ethereum-white'
}, },
@ -105,20 +171,33 @@ module.exports = {
footer: { footer: {
logo: '/logo-bw.svg', logo: '/logo-bw.svg',
textLink: { textLink: {
text: 'tharsis.finance/ethermint', text: 'ethermint.dev',
url: 'https://tharsis.finance/ethermint' url: 'https://ethermint.dev'
}, },
services: [{ services: [
{
service: 'github', service: 'github',
url: 'https://github.com/tharsis/ethermint' url: 'https://github.com/tharsis/ethermint'
} },
{
service: "twitter",
url: "https://twitter.com/ethermint",
},
{
service: "linkedin",
url: "https://www.linkedin.com/company/tharsis-finance/",
},
{
service: "medium",
url: "https://medium.com/@tharsis_labs",
},
], ],
smallprint: 'This website is maintained by Tharsis.', smallprint: 'This website is maintained by Tharsis Labs Ltd.',
links: [{ links: [{
title: 'Documentation', title: 'Documentation',
children: [{ children: [{
title: 'Cosmos SDK Docs', title: 'Cosmos SDK Docs',
url: 'https://docs.cosmos.network' url: 'https://docs.cosmos.network/master/'
}, },
{ {
title: 'Ethereum Docs', title: 'Ethereum Docs',
@ -133,8 +212,8 @@ module.exports = {
{ {
title: 'Community', title: 'Community',
children: [{ children: [{
title: 'Cosmos Community', title: 'Ethermint Community',
url: 'https://discord.gg/W8trcGV' url: 'https://discord.gg/3ZbxEq4KDu'
}, },
{ {
title: 'Ethermint Forum', title: 'Ethermint Forum',
@ -143,14 +222,11 @@ module.exports = {
] ]
}, },
{ {
title: 'Contributing', title: 'Tharsis',
children: [{ children: [
title: 'Contributing to the docs',
url: 'https://github.com/tharsis/ethermint/tree/main/docs'
},
{ {
title: 'Source code on GitHub', title: 'Jobs at Tharsis',
url: 'https://github.com/tharsis/ethermint/blob/main/docs/DOCS_README.md' url: 'https://tharsis.notion.site/Jobs-at-Tharsis-5a1642eb89b34747ae6f2db2d356fc0d'
} }
] ]
} }

84
docs/.vuepress/public/ethermint-logo-horizontal-alpha.svg Normal file
View File

@ -0,0 +1,84 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- Generator: Adobe Illustrator 25.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 0) -->
<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
viewBox="0 0 526 192" style="enable-background:new 0 0 526 192;" xml:space="preserve">
<style type="text/css">
.st0{fill:url(#SVGID_1_);}
.st1{fill:url(#SVGID_2_);}
.st2{fill:url(#SVGID_3_);}
.st3{fill:url(#SVGID_4_);}
.st4{fill:#B3C9F4;}
.st5{fill-rule:evenodd;clip-rule:evenodd;fill:#FFFFFF;}
.st6{fill:#717BBF;}
.st7{opacity:0.5;fill:url(#SVGID_5_);enable-background:new ;}
.st8{opacity:0.5;fill:url(#SVGID_6_);enable-background:new ;}
.st9{fill:#131516;}
</style>
<linearGradient id="SVGID_1_" gradientUnits="userSpaceOnUse" x1="96.4904" y1="115.7662" x2="80.8316" y2="187.581" gradientTransform="matrix(1 0 0 -1 0 194)">
<stop offset="0" style="stop-color:#8D8DE4"/>
<stop offset="1" style="stop-color:#89A2E5;stop-opacity:0"/>
<stop offset="1" style="stop-color:#BBD9FF;stop-opacity:0"/>
</linearGradient>
<path class="st0" d="M76.9,7v123.2l54.8-32.3L76.9,7z"/>
<linearGradient id="SVGID_2_" gradientUnits="userSpaceOnUse" x1="85.6408" y1="131.291" x2="28.6749" y2="93.2238" gradientTransform="matrix(1 0 0 -1 0 194)">
<stop offset="0" style="stop-color:#8D8DE4"/>
<stop offset="1" style="stop-color:#89A2E5;stop-opacity:0"/>
<stop offset="1" style="stop-color:#BBD9FF;stop-opacity:0"/>
</linearGradient>
<path class="st1" d="M22.1,97.8l54.8,32.3V7L22.1,97.8z"/>
<linearGradient id="SVGID_3_" gradientUnits="userSpaceOnUse" x1="22.1" y1="47.25" x2="76.9" y2="47.25" gradientTransform="matrix(1 0 0 -1 0 194)">
<stop offset="0" style="stop-color:#E3FFFF"/>
<stop offset="1" style="stop-color:#89A2E5"/>
<stop offset="1" style="stop-color:#BBF9FF;stop-opacity:0"/>
</linearGradient>
<path class="st2" d="M22.1,108.2l54.8,77.1v-44.8L22.1,108.2z"/>
<linearGradient id="SVGID_4_" gradientUnits="userSpaceOnUse" x1="-52.6532" y1="253.8875" x2="422.5458" y2="-79.853">
<stop offset="6.489749e-03" style="stop-color:#DC614D"/>
<stop offset="0.3603" style="stop-color:#8D8DE4"/>
<stop offset="1" style="stop-color:#89A2E5"/>
</linearGradient>
<path class="st3" d="M76.9,140.5v44.8l54.8-77.1L76.9,140.5z"/>
<g>
<path class="st4" d="M76.9,72.9L22.1,97.8l54.8,32.3l54.8-32.3L76.9,72.9z"/>
</g>
<path class="st5" d="M89.6,62.4c-4-1.6-8.3-2.4-12.7-2.4c-9.2,0-17.8,3.6-24.3,10.1s-10,15.2-10.1,24.3v1.2l1.1,0.6
c5.2,2.9,11,4.5,16.9,4.5c0.2,0,0.3,0,0.5,0c5.2-0.1,10.3-1.3,14.9-3.6c-1.5-0.8-2.9-1.7-4.2-2.8c-8.1,3.2-17.2,2.8-24.9-1.2
c0.8-16.1,14-29,30.1-29c4.5,0,8.9,1,12.9,2.9C89.8,65.5,89.8,64,89.6,62.4"/>
<path class="st5" d="M111.3,94.2c-0.1-11.5-5.7-21.9-14.9-28.3c0,1.7-0.1,3.4-0.3,5c6.6,5.4,10.6,13.3,11,22
c-14.2,7.3-31.9,2.2-40-11.8c-2.2-3.8-3.5-8-3.9-12.4c-1.4,0.8-2.7,1.6-3.9,2.6c0.7,4.2,2.1,8.2,4.2,11.9c4.6,8,12,13.7,20.8,16.1
c3,0.8,6,1.2,9,1.2c5.9,0,11.7-1.5,17-4.5l1.1-0.6L111.3,94.2z"/>
<path class="st5" d="M78.1,36L77,35.4L76,36c-5.2,3.1-9.6,7.5-12.6,12.7c-2.6,4.5-4.1,9.6-4.5,14.8c1.4-0.9,2.9-1.6,4.5-2.2
c1.3-8.6,6.3-16.3,13.7-21C90.6,49,95,67.1,86.9,81.1c-2.2,3.8-5.2,7.1-8.8,9.6c1.3,0.8,2.7,1.5,4.2,2.1c3.3-2.7,6.1-5.9,8.2-9.6
C100,66.8,94.4,45.6,78.1,36"/>
<polygon class="st6" points="76.9,146.5 131.7,108.2 131.7,108.2 76.9,140.5 22.1,108.2 22.1,108.2 "/>
<linearGradient id="SVGID_5_" gradientUnits="userSpaceOnUse" x1="75.5332" y1="186.2992" x2="42.3256" y2="50.7691" gradientTransform="matrix(1 0 0 -1 0 194)">
<stop offset="0" style="stop-color:#E3FFFF"/>
<stop offset="1" style="stop-color:#BBF9FF;stop-opacity:0"/>
</linearGradient>
<path class="st7" d="M22.1,97.8l54.8,32.3V7L22.1,97.8z"/>
<linearGradient id="SVGID_6_" gradientUnits="userSpaceOnUse" x1="117.958" y1="89.2972" x2="55.3226" y2="144.3732" gradientTransform="matrix(1 0 0 -1 0 194)">
<stop offset="1.975860e-02" style="stop-color:#DD5C47"/>
<stop offset="1" style="stop-color:#BBF9FF;stop-opacity:0"/>
</linearGradient>
<path class="st8" d="M76.9,7v123.2l54.8-32.3L76.9,7z"/>
<g>
<path class="st9" d="M182.2,76.1h34.4v8.4h-24.7V97h19.8v8.4h-19.8v13.8h25.5v8.5h-35.2L182.2,76.1L182.2,76.1z"/>
<path class="st9" d="M235.6,79.3v11.2h10.3v7.6h-10.3v16.2c0,3.8,2,5.7,5.4,5.7h4.9v7.7h-6c-8.1,0-13.4-4.7-13.4-13V98.2h-7.3v-7.6
h7.3V79.3H235.6z"/>
<path class="st9" d="M252.8,74.6h9v21.7c2.1-4.1,6.4-6.4,11.7-6.4c8.3,0,13.8,6.1,13.8,14.8v23h-9v-21.1c0-5.1-3.2-8.6-7.8-8.6
c-5,0-8.6,4-8.6,9.5v20.3h-9L252.8,74.6L252.8,74.6z"/>
<path class="st9" d="M328.9,115.4c-1.4,7.9-8.3,13-17.5,13c-12.2,0-19-9.6-19-19.4s6.1-19.1,18.2-19.1c12.5,0,18.1,9.1,18.1,17.9
c0,1.3-0.1,2.4-0.1,3.1h-27.5c0.7,6,4.5,9.8,10.3,9.8c4.7,0,7.7-1.9,8.6-5.5h8.9V115.4z M301.4,105h18.3c-0.4-4.7-3.6-8.3-9-8.3
C305.6,96.7,302.3,99.4,301.4,105z"/>
<path class="st9" d="M351.2,98.2c-5.8,0-8.1,4.9-8.1,12v17.6H334V90.5h9.1v6.6c1.8-4.7,4.7-6.6,9.5-6.6h4.4v7.6L351.2,98.2
L351.2,98.2z"/>
<path class="st9" d="M361.2,90.5h9.1v5.8c1.8-3.8,5.5-6.4,10.8-6.4c5.9,0,10,2.5,11.6,7.1c1.7-3.8,6.4-7.1,12.3-7.1
c8.1,0,13.2,5.8,13.2,13.7v24.1h-9v-21.3c0-5.2-2.7-8.7-7.1-8.7c-4.9,0-7.9,3.5-7.9,8.7v21.3h-9v-21.3c0-5.2-2.7-8.7-7.1-8.7
c-4.8,0-7.8,3.5-7.8,8.7v21.3h-9.1V90.5z"/>
<path class="st9" d="M434.7,74.6v10.1h-9.8V74.6H434.7z M425.3,90.5h9.1v37.2h-9.1V90.5z"/>
<path class="st9" d="M441.5,90.5h9.1v5.8c2.1-4.1,6.3-6.4,11.6-6.4c8.4,0,13.9,6.1,13.9,14.8v23H467v-21.1c0-5.1-3.1-8.6-7.8-8.6
c-5.1,0-8.6,4-8.6,9.5v20.3h-9.1V90.5z"/>
<path class="st9" d="M495.6,79.3v11.2h10.3v7.6h-10.3v16.2c0,3.8,2,5.7,5.4,5.7h4.9v7.7h-6c-8.1,0-13.4-4.7-13.4-13V98.2h-7.3v-7.6
h7.3V79.3H495.6z"/>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 5.5 KiB

12
docs/api/README.md Normal file
View File

@ -0,0 +1,12 @@
<!--
order: false
parent:
order: 5
-->
# API
This section contains different client and API reference document.
1. [JSON-RPC](./json_rpc)
1. [Protobuf Docs](./proto-docs)

14
docs/basics/json_rpc.md → docs/api/json-rpc/endpoints.md
View File

@ -1,31 +1,31 @@
<!-- <!--
order: 5 order: 1
--> -->
# JSON-RPC Server # JSON-RPC Server
Check the JSON-RPC methods and namespaces supported on Ethermint. {synopsis} Check the JSON-RPC methods supported on Ethermint. {synopsis}
## Pre-requisite Readings ## Pre-requisite Readings
- [Ethereum JSON-RPC](https://eth.wiki/json-rpc/API) {prereq} - [Ethereum JSON-RPC](https://eth.wiki/json-rpc/API) {prereq}
- [Geth JSON-RPC APIs](https://geth.ethereum.org/docs/rpc/server) {prereq} - [Geth JSON-RPC APIs](https://geth.ethereum.org/docs/rpc/server) {prereq}
## JSON-RPC Server ## Running the server
To enable RPC server use the following flag (set to true by default). To enable RPC server use the following flag (set to true by default).
``` ```bash
ethermintd start --evm-rpc.enable ethermintd start --evm-rpc.enable
``` ```
`Eth`,`Net` and `Web3` namespaces are enabled by default. In order to enable other namespaces use flag `--evm-rpc.api`. `Eth`,`Net` and `Web3` namespaces are enabled by default. In order to enable other namespaces use flag `--evm-rpc.api`.
``` ```bash
ethermintd start --evm-rpc.api eth,txpool,personal,net,debug,web3 ethermintd start --evm-rpc.api eth,txpool,personal,net,debug,web3,miner
``` ```
## JSON-RPC Methods ## Endpoints
| Method | Namespace | Implemented | Notes | | Method | Namespace | Implemented | Notes |
|-----------------------------------------------------------------------------------|-----------|-------------|---------------------------| |-----------------------------------------------------------------------------------|-----------|-------------|---------------------------|

12
docs/api/json-rpc/namespaces.md Normal file
View File

@ -0,0 +1,12 @@
<!--
order: 2
-->
# Namespaces
Check the JSON-RPC namespaces supported on Ethermint. {synopsis}
## Pre-requisite Readings
- [JSON-RPC](./endpoints) {prereq}
- [Geth JSON-RPC Namespaces](https://geth.ethereum.org/docs/rpc/server) {prereq}

0
docs/core/proto-docs.md → docs/api/proto-docs.md
View File

11
docs/basics/README.md
View File

@ -8,10 +8,9 @@ parent:
This repository contains reference documentation on the basic concepts of Ethermint. This repository contains reference documentation on the basic concepts of Ethermint.
1. [Accounts](./accounts.md) 1. [Accounts](./accounts)
2. [Gas and Fees](./gas.md) 2. [Gas and Fees](./gas)
3. [Lifecycle of a transaction](./transactions.md) 3. [Lifecycle of a transaction](./transactions)
4. [Tokens](./tokens.md) 4. [Tokens](./tokens)
5. [JSON-RPC Server](./json_rpc.md)
After reading the basics, head on to the [Core Reference](../core/README.md) for more advanced material. After reading the basics, head on to the [Core Reference](../core/README) for more advanced material.

115
docs/basics/accounts.md
View File

@ -21,7 +21,13 @@ The root HD path for Ethermint-based accounts is `m/44'/60'/0'/0`.
## Addresses and Public Keys ## Addresses and Public Keys
There are 3 main types of `Addresses`/`PubKeys` available by default on Ethermint: [BIP-0173](https://github.com/satoshilabs/slips/blob/master/slip-0173.md) defines a new format for segregated witness output addresses that contains a human-readable part that identifies the Bech32 usage. Ethermint uses the following HRP (human readable prefix) as the base HRP:
| Network | Mainnet | Testnet | Regtest |
| --------- | ------- | ------- | ------- |
| Ethermint | `eth` | `eth` | |
There are 3 main types of HRP for the `Addresses`/`PubKeys` available by default on Ethermint:
- Addresses and Keys for **accounts**, which identify users (e.g. the sender of a `message`). They are derived using the **`eth_secp256k1`** curve. - Addresses and Keys for **accounts**, which identify users (e.g. the sender of a `message`). They are derived using the **`eth_secp256k1`** curve.
- Addresses and Keys for **validator operators**, which identify the operators of validators. They are derived using the **`eth_secp256k1`** curve. - Addresses and Keys for **validator operators**, which identify the operators of validators. They are derived using the **`eth_secp256k1`** curve.
@ -35,49 +41,106 @@ There are 3 main types of `Addresses`/`PubKeys` available by default on Ethermin
## Address formats for clients ## Address formats for clients
`EthAccount`s can be represented in both [Bech32](https://en.bitcoin.it/wiki/Bech32) and hex format for Ethereum's Web3 tooling compatibility. `EthAccount` can be represented in both [Bech32](https://en.bitcoin.it/wiki/Bech32) (`eth1...`) and hex (`0x...`) formats for Ethereum's Web3 tooling compatibility.
The Bech32 format is the default format for Cosmos-SDK queries and transactions through CLI and REST The Bech32 format is the default format for Cosmos-SDK queries and transactions through CLI and REST
clients. The hex format on the other hand, is the Ethereum `common.Address` representation of a clients. The hex format on the other hand, is the Ethereum `common.Address` representation of a
Cosmos `sdk.AccAddress`. Cosmos `sdk.AccAddress`.
- Address (Bech32): `eth1crwhac03z2pcgu88jfnqnwu66xlthlz2rhljah` - **Address (Bech32)**: `eth14au322k9munkmx5wrchz9q30juf5wjgz2cfqku`
- Address ([EIP55](https://eips.ethereum.org/EIPS/eip-55) Hex): `0xc0dd7ee1f112838470e7926609bb9ad1bebbfc4a` - **Address ([EIP55](https://eips.ethereum.org/EIPS/eip-55) Hex)**: `0xAF79152AC5dF276D9A8e1E2E22822f9713474902`
- Compressed Public Key (Bech32): `ethpub1pfqnmk6pqnwwuw0h9hj58t2hyzwvqc3truhhp5tl5hfucezcfy2rs8470nkyzju2vmk645fzmw2wveaqcqek767kwa0es9rmxe9nmmjq84cpny3fvj6tpg` - **Compressed Public Key**: `{"@type":"/ethermint.crypto.v1beta1.ethsecp256k1.PubKey","key":"ApNNebT58zlZxO2yjHiRTJ7a7ufjIzeq5HhLrbmtg9Y/"}`
You can query an account address using the Cosmos CLI or REST clients: ### Address conversion
The `ethermintd debug addr <address>` can be used to convert an address between hex and bech32 formats. For example:
```bash ```bash
# NOTE: the --output (-o) flag will define the output format in JSON or YAML (text) ethermintd debug addr eth12uqc42yj77hk64cdr3vsnpkfs6k0pllln7rudt
ethermintd q auth account $(ethermintd keys show <MYKEY> -a) -o text Address: [87 1 138 168 146 247 175 109 87 13 28 89 9 134 201 134 172 240 255 255]
| Address (hex): 57018AA892F7AF6D570D1C590986C986ACF0FFFF
address: eth1f8rqrfwut7ngkxwth0gt99h0lxnxsp09ngvzwl Bech32 Acc: eth12uqc42yj77hk64cdr3vsnpkfs6k0pllln7rudt
eth_address: 0x49c601A5DC5FA68b19CBbbd0b296eFF9a66805e5 Bech32 Val: ethvaloper12uqc42yj77hk64cdr3vsnpkfs6k0pllldvagr4
coins:
- denom: aphoton ethermintd debug addr 57018AA892F7af6D570D1c590986c986aCf0fFff
amount: "1000000000000000000" Address: [87 1 138 168 146 247 175 109 87 13 28 89 9 134 201 134 172 240 255 255]
- denom: stake Address (hex): 57018AA892F7AF6D570D1C590986C986ACF0FFFF
amount: "999999999900000000" Bech32 Acc: eth12uqc42yj77hk64cdr3vsnpkfs6k0pllln7rudt
public_key: ethpub1pfqnmkepqw45vpsn6dzvm7k22zrghx0nfewjdfacy7wyycv5evfk57kyhwr8cqj5r4x Bech32 Val: ethvaloper12uqc42yj77hk64cdr3vsnpkfs6k0pllldvagr4
account_number: 0
sequence: 1
code_hash: c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470
``` ```
``` bash ::: tip
# GET /auth/accounts/{address} Add the `0x` prefix to the returned hex address above to represent the Ethereum hex address format. For example:
curl -X GET "<NODE_IP>/auth/accounts/eth1f8rqrfwut7ngkxwth0gt99h0lxnxsp09ngvzwl" -H "accept: application/json" `Address (hex): 57018AA892F7AF6D570D1C590986C986ACF0FFFF` implies that `0x57018AA892F7AF6D570D1C590986C986ACF0FFFF` is the Ethereum hex address.
``` :::
### Key output
::: tip ::: tip
The Cosmos SDK Keyring output (i.e `ethermintd keys`) only supports addresses and public keys in Bech32 format. The Cosmos SDK Keyring output (i.e `ethermintd keys`) only supports addresses and public keys in Bech32 format.
::: :::
To retrieve the Ethereum hex address using Web3, use the JSON-RPC [`eth_accounts`](./json_rpc.md#eth-accounts) endpoint: We can use the `keys show` command of `ethermintd` with the flag `--bech <type> (acc|val|cons)` to
obtain the addresses and keys as mentioned above,
```bash
ethermintd keys show mykey --bech acc
- name: mykey
type: local
address: eth1qsklxwt77qrxur494uvw07zjynu03dq9alwh37
pubkey: '{"@type":"/ethermint.crypto.v1alpha1.ethsecp256k1.PubKey","key":"A8nbJ3eW9oAb2RNZoS8L71jFMfjk6zVa1UISYgKK9HPm"}'
mnemonic: ""
ethermintd keys show test --bech val
- name: mykey
type: local
address: ethvaloper1qsklxwt77qrxur494uvw07zjynu03dq9rdsrlq
pubkey: '{"@type":"/ethermint.crypto.v1alpha1.ethsecp256k1.PubKey","key":"A8nbJ3eW9oAb2RNZoS8L71jFMfjk6zVa1UISYgKK9HPm"}'
mnemonic: ""
ethermintd keys show test --bech cons
- name: mykey
type: local
address: ethvalcons1qsklxwt77qrxur494uvw07zjynu03dq9h7rlnp
pubkey: '{"@type":"/ethermint.crypto.v1alpha1.ethsecp256k1.PubKey","key":"A8nbJ3eW9oAb2RNZoS8L71jFMfjk6zVa1UISYgKK9HPm"}'
mnemonic: ""
```
## Querying an Account
You can query an account address using the CLI, gRPC or
### Command Line Interface
```bash
# NOTE: the --output (-o) flag will define the output format in JSON or YAML (text)
ethermintd q auth account $(ethermintd keys show <MYKEY> -a) -o text
|
'@type': /ethermint.types.v1beta1.EthAccount
base_account:
account_number: "3"
address: inj14au322k9munkmx5wrchz9q30juf5wjgz2cfqku
pub_key: null
sequence: "0"
code_hash: xdJGAYb3IzySfn2y3McDwOUAtlPKgic7e/rYBF2FpHA=
```
### Cosmos gRPC and REST
``` bash
# GET /cosmos/auth/v1beta1/accounts/{address}
curl -X GET "http://localhost:10337/cosmos/auth/v1beta1/accounts/eth14au322k9munkmx5wrchz9q30juf5wjgz2cfqku" -H "accept: application/json"
```
### JSON-RPC
To retrieve the Ethereum hex address using Web3, use the JSON-RPC [`eth_accounts`](./../api/json-rpc/endpoints#eth-accounts) or [`personal_listAccounts`](./../api/json-rpc/endpoints#personal-listAccounts) endpoints:
```bash ```bash
# query against a local node # query against a local node
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_accounts","params":[],"id":1}' -H "Content-Type: application/json" http://localhost:26664 curl -X POST --data '{"jsonrpc":"2.0","method":"eth_accounts","params":[],"id":1}' -H "Content-Type: application/json" http://localhost:8545
curl -X POST --data '{"jsonrpc":"2.0","method":"personal_listAccounts","params":[],"id":1}' -H "Content-Type: application/json" http://localhost:8545
``` ```
## Next {hide} ## Next {hide}

4
docs/basics/gas.md
View File

@ -56,7 +56,6 @@ To ignore the SDK gas consumption, we reset the transaction `GasMeter` count to
+++ https://github.com/tharsis/ethermint/blob/098da6d0cc0e0c4cefbddf632df1057383973e4a/x/evm/keeper/state_transition.go#L188 +++ https://github.com/tharsis/ethermint/blob/098da6d0cc0e0c4cefbddf632df1057383973e4a/x/evm/keeper/state_transition.go#L188
### `AnteHandler` ### `AnteHandler`
The Cosmos SDK [`AnteHandler`](https://docs.cosmos.network/master/basics/gas-fees.html#antehandler) The Cosmos SDK [`AnteHandler`](https://docs.cosmos.network/master/basics/gas-fees.html#antehandler)
@ -96,8 +95,7 @@ transaction might be higher than the value returned by the EVM after applying th
A cache context will be used during the whole execution to avoid changes be persisted in the state. A cache context will be used during the whole execution to avoid changes be persisted in the state.
+++ +++ https://github.com/tharsis/ethermint/blob/098da6d0cc0e0c4cefbddf632df1057383973e4a/x/evm/keeper/grpc_query.go#L100
https://github.com/tharsis/ethermint/blob/098da6d0cc0e0c4cefbddf632df1057383973e4a/x/evm/keeper/grpc_query.go#L392
## Next {hide} ## Next {hide}

1
docs/core/README.md
View File

@ -10,6 +10,5 @@ This repository contains reference documentation on the core concepts of Ethermi
1. [Encoding](./encoding.md) 1. [Encoding](./encoding.md)
2. [Pending State](./pending_state.md) 2. [Pending State](./pending_state.md)
3. [Protobuf Docs](./proto-docs.md)
After reading the core concepts, head on to the [guides](../guides/README.md) to learn how to use Ethereum tooling with Ethermint. After reading the core concepts, head on to the [guides](../guides/README.md) to learn how to use Ethereum tooling with Ethermint.

2
docs/core/pending_state.md
View File

@ -34,7 +34,7 @@ transaction mempool. A pending state query made will be subjective and the query
target node's mempool. Thus, the pending state will not be the same for the same query to two target node's mempool. Thus, the pending state will not be the same for the same query to two
different nodes. different nodes.
### RPC Calls on Pending Transactions ### JSON-RPC Calls on Pending Transactions
- [`eth_getBalance`](./../basics/json_rpc.md#eth_getbalance) - [`eth_getBalance`](./../basics/json_rpc.md#eth_getbalance)
- [`eth_getTransactionCount`](./../basics/json_rpc.md#eth-gettransactioncount) - [`eth_getTransactionCount`](./../basics/json_rpc.md#eth-gettransactioncount)

10
docs/guides/README.md
View File

@ -6,9 +6,9 @@ parent:
# Guides # Guides
This section contains different guides to use popular Ethereum tools with Ethermint. This section contains different guides to use wallets and popular Ethereum tools with Ethermint.
1. [Truffle](./truffle.md) 1. [Keyring](./wallets/keyring)
2. [Metamask](./metamask.md) 1. [Metamask](./wallets/metamask)
3. [Remix](./remix.md) 1. [Truffle](./tools/truffle)
4. [Deploy Testnet on Cloud Provider](./cloud_testnet.md) 1. [Remix](./tools/remix)

2
docs/quickstart/events.md → docs/guides/events.md
View File

@ -1,5 +1,5 @@
<!-- <!--
order: 7 order: 6
--> -->
# Events # Events

123
docs/quickstart/testnet.md → docs/guides/localnet/multi_node.md
View File

@ -1,93 +1,26 @@
<!-- <!--
order: 3 order: 2
--> -->
# Testnet # Multi Node
Learn how to deploy a local testnet or connect to an existing public one {synopsis}
## Pre-requisite Readings ## Pre-requisite Readings
- [Install Ethermint](./installation.md) {prereq} - [Install Starport](https://docs.starport.network/intro/install.html) {prereq}
- [Install Docker](https://docs.docker.com/engine/installation/) {prereq} - [Install Docker](https://docs.docker.com/engine/installation/) {prereq}
- [Install docker-compose](https://docs.docker.com/compose/install/) {prereq} - [Install docker-compose](https://docs.docker.com/compose/install/) {prereq}
<!-- - [Install `jq`](https://stedolan.github.io/jq/download/) {prereq} --> ## Automated Localnet with Starport
## Single-node, Local, Manual Testnet Once you have installed `starport`, just run the localnet by using
This guide helps you create a single validator node that runs a network locally for testing and other development related uses.
### Initialize node
```bash ```bash
$MONIKER=testing starport serve
$KEY=mykey
$CHAINID="ethermint-1"
ethermintd init $MONIKER --chain-id=$CHAINID
``` ```
::: warning ## Automated Localnet with Docker
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: ### Build & Start
```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: To build start a 4 node testnet run:
@ -123,7 +56,7 @@ Creating ethermintdnode3 ... done
``` ```
### Stop Testnet ### Stop Localnet
Once you are done, execute: Once you are done, execute:
@ -234,9 +167,9 @@ example:
docker logs -f ethermintdnode0 docker logs -f ethermintdnode0
``` ```
### Interact With the Testnet ### Interact with the Localnet
#### Ethereum JSON RPC & Websocket Ports #### Ethereum JSON-RPC & Websocket Ports
To interact with the testnet via WebSockets or RPC/API, you will send your request to the corresponding ports: To interact with the testnet via WebSockets or RPC/API, you will send your request to the corresponding ports:
@ -280,37 +213,3 @@ If you have multiple binaries with different names, you can specify which one to
# Run with custom binary # Run with custom binary
BINARY=ethermint make localnet-start 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}

87
docs/guides/localnet/single_node.md Normal file
View File

@ -0,0 +1,87 @@
<!--
order: 1
-->
# Single Node
## Pre-requisite Readings
- [Install Binary](./../../quickstart/installation) {prereq}
- [Install Starport](https://docs.starport.network/intro/install.html) {prereq}
## Automated Localnet (script)
```bash
init.sh
```
## Manual Localnet
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-777"
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.

16
docs/guides/remix.md → docs/guides/tools/remix.md
View File

@ -1,5 +1,5 @@
<!-- <!--
order: 3 order: 2
--> -->
# Remix # Remix
@ -8,15 +8,15 @@ Set up a Remix Ethermint local development environment. {synopsis}
## Pre-requisite Readings ## Pre-requisite Readings
- [Installation](./../quickstart/installation.md) {prereq} - [Installation](./../../quickstart/installation.md) {prereq}
- [Run a node](./../quickstart/run_node.md) {prereq} - [Run a node](./../../quickstart/run_node.md) {prereq}
- [Metamask](./metamask.md) {prereq} - [Metamask](./../wallets/metamask.md) {prereq}
[Remix](http://remix.ethereum.org/) is an in-browser IDE for [Solidity](https://github.com/ethereum/solidity) smart contracts. In this guide, we will learn how to deploy a contract to a running Ethermint network through Remix and interact with it. [Remix](http://remix.ethereum.org/) is an in-browser IDE for [Solidity](https://github.com/ethereum/solidity) smart contracts. In this guide, we will learn how to deploy a contract to a running Ethermint network through Remix and interact with it.
## Connect Ethermint account to Remix ## Connect Ethermint account to Remix
First, follow the steps in the [Metamask guide](./metamask.md) to import your Ethermint private key into Metamask. Start the Ethermint daemon and rest server. First, follow the steps in the [Metamask guide](./../wallets/metamask.md) to import your Ethermint private key into Metamask. Start the Ethermint daemon and rest server.
Once that is complete, go to [Remix](http://remix.ethereum.org/). There are some contracts in the File Explorer. Select any of these contracts. In this example, we use `Counter.sol` from the [Truffle](./truffle.md) guide. On the left-most bar, select the Solidity Compiler and compile the contract. Once that is complete, go to [Remix](http://remix.ethereum.org/). There are some contracts in the File Explorer. Select any of these contracts. In this example, we use `Counter.sol` from the [Truffle](./truffle.md) guide. On the left-most bar, select the Solidity Compiler and compile the contract.
@ -24,7 +24,7 @@ Next, select the `Deploy and Run` option. Select `injected web3` as the environm
You should see your account show up in the left-hand panel. You should see your account show up in the left-hand panel.
![remix connected to ethermint](./img/remix_deploy.png) ![remix connected to ethermint](./../img/remix_deploy.png)
## Deploy and Interact ## Deploy and Interact
@ -36,8 +36,8 @@ I[2020-07-15|17:26:43.155] Added good transaction module=m
Once the contract has been successfully deployed, you will see it show up in the `Deployed Contracts` section in the left-hand side, as well as a green check in the Remix console showing the transaction details. Once the contract has been successfully deployed, you will see it show up in the `Deployed Contracts` section in the left-hand side, as well as a green check in the Remix console showing the transaction details.
![deployed contract through remix](./img/remix_deployed.png) ![deployed contract through remix](./../img/remix_deployed.png)
Now, you are able to interact with the contract through Remix. For `Counter.sol`, click `add`. This will open a Metamask pop-up asking you to confirm. Confirm the transaction. Then, click `getCounter` to get the count, which should be `1`. Now, you are able to interact with the contract through Remix. For `Counter.sol`, click `add`. This will open a Metamask pop-up asking you to confirm. Confirm the transaction. Then, click `getCounter` to get the count, which should be `1`.
![interacting with deployed contract through remix](./img/remix_interact.png) ![interacting with deployed contract through remix](./../img/remix_interact.png)

6
docs/guides/truffle.md → docs/guides/tools/truffle.md
View File

@ -21,7 +21,7 @@ First, install the latest Truffle version on your machine globally.
yarn install truffle -g yarn install truffle -g
``` ```
You will also need to install Ethermint. Check this [document](./../quickstart/installation.md) for the full instructions. You will also need to install Ethermint. Check this [document](./../../quickstart/installation.md) for the full instructions.
## Create Truffle Project ## Create Truffle Project
@ -113,7 +113,7 @@ init.sh
``` ```
::: tip ::: tip
For further information on how to run a node, please refer to [this](./../quickstart/run_node.md) quickstart document. For further information on how to run a node, please refer to [this](./../../quickstart/run_node.md) quickstart document.
::: :::
## Deploy contract ## Deploy contract
@ -158,4 +158,4 @@ Compiling your contracts...
## Next {hide} ## Next {hide}
Learn how to connect Ethermint to [Metamask](./../guides/metamask.md) {hide} Learn how to connect Ethermint to [Metamask](./../wallets/metamask.md) {hide}

0
docs/quickstart/upgrade.md → docs/guides/upgrade.md
View File

121
docs/guides/wallets/keyring.md Normal file
View File

@ -0,0 +1,121 @@
<!--
order: 1
-->
# Keyring
Create, import, export and delete keys using the CLI keyring {synopsis}
The keyring holds the private/public keypairs used to interact with the node. For instance, a validator key needs to be set up before running the node, so that blocks can be correctly signed. The private key can be stored in different locations, called ["backends"](#keyring-backends), such as a file or the operating system's own key storage.
## Add keys
You can use `ethermintd keys` for help about the keys command and `ethermintd keys [command] --help` for more information about a particular subcommand.
To create a new key in the keyring, run the `add` subcommand with a `<key_name>` argument. For the purpose of this tutorial, we will solely use the `test` backend, and call our new key `mykey`. This key will be used in the next section.
```bash
ethermintd keys add mykey --keyring-backend test
# Put the generated address in a variable for later use.
MY_VALIDATOR_ADDRESS=$(ethermintd keys show mykey -a --keyring-backend test)
```
This command generates a new 24-word mnemonic phrase, persists it to the relevant backend, and outputs information about the keypair. If this keypair will be used to hold value-bearing tokens, be sure to write down the mnemonic phrase somewhere safe!
By default, the keyring generates a `eth_secp256k1` keypair. The keyring also supports `ed25519` keys, which may be created by passing the `--algo ed25519` flag. A keyring can of course hold both types of keys simultaneously.
## Keyring Backends
### OS
The `os` backend relies on operating system-specific defaults to handle key storage
securely. Typically, an operating system's credential sub-system handles password prompts,
private keys storage, and user sessions according to the user's password policies. Here
is a list of the most popular operating systems and their respective passwords manager:
- macOS (since Mac OS 8.6): [Keychain](https://support.apple.com/en-gb/guide/keychain-access/welcome/mac)
- Windows: [Credentials Management API](https://docs.microsoft.com/en-us/windows/win32/secauthn/credentials-management)
- GNU/Linux:
- [libsecret](https://gitlab.gnome.org/GNOME/libsecret)
- [kwallet](https://api.kde.org/frameworks/kwallet/html/index.html)
GNU/Linux distributions that use GNOME as default desktop environment typically come with
[Seahorse](https://wiki.gnome.org/Apps/Seahorse). Users of KDE based distributions are
commonly provided with [KDE Wallet Manager](https://userbase.kde.org/KDE_Wallet_Manager).
Whilst the former is in fact a `libsecret` convenient frontend, the latter is a `kwallet`
client.
`os` is the default option since operating system's default credentials managers are
designed to meet users' most common needs and provide them with a comfortable
experience without compromising on security.
The recommended backends for headless environments are `file` and `pass`.
### File
The `file` stores the keyring encrypted within the app's configuration directory. This
keyring will request a password each time it is accessed, which may occur multiple
times in a single command resulting in repeated password prompts. If using bash scripts
to execute commands using the `file` option you may want to utilize the following format
for multiple prompts:
```bash
# assuming that KEYPASSWD is set in the environment
yes $KEYPASSWD | ethermintd keys add me
yes $KEYPASSWD | ethermintd keys show me
# start ethermintd with keyring-backend flag
ethermintd --keyring-backend=file start
```
::: tip
The first time you add a key to an empty keyring, you will be prompted to type the password twice.
:::
### Password Store
The `pass` backend uses the [pass](https://www.passwordstore.org/) utility to manage on-disk
encryption of keys' sensitive data and metadata. Keys are stored inside `gpg` encrypted files
within app-specific directories. `pass` is available for the most popular UNIX
operating systems as well as GNU/Linux distributions. Please refer to its manual page for
information on how to download and install it.
::: tip
**pass** uses [GnuPG](https://gnupg.org/) for encryption. `gpg` automatically invokes the `gpg-agent`
daemon upon execution, which handles the caching of GnuPG credentials. Please refer to `gpg-agent`
man page for more information on how to configure cache parameters such as credentials TTL and
passphrase expiration.
:::
The password store must be set up prior to first use:
```sh
pass init <GPG_KEY_ID>
```
Replace `<GPG_KEY_ID>` with your GPG key ID. You can use your personal GPG key or an alternative
one you may want to use specifically to encrypt the password store.
### KDE Wallet Manager
The `kwallet` backend uses `KDE Wallet Manager`, which comes installed by default on the
GNU/Linux distributions that ships KDE as default desktop environment. Please refer to
[KWallet Handbook](https://docs.kde.org/stable5/en/kdeutils/kwallet5/index.html) for more
information.
### Testing
The `test` backend is a password-less variation of the `file` backend. Keys are stored
**unencrypted** on disk.
:::danger
Provided for testing purposes only. The `test` backend is **NOT** recommended for use in production environments.
:::
### In Memory
The `memory` backend stores keys in memory. The keys are immediately deleted after the program has exited.
:::danger
Provided for testing purposes only. The `memory` backend is **NOT** recommended for use in production environments.
:::

26
docs/guides/metamask.md → docs/guides/wallets/metamask.md
View File

@ -6,24 +6,6 @@ order: 2
Connect your Metamask wallet with Ethermint on a localnet mode. {synopsis} Connect your Metamask wallet with Ethermint on a localnet mode. {synopsis}
## Start node and REST server
Start the Ethermint node using your terminal:
```bash
ethermintd start --pruning=nothing --rpc.unsafe --log_level "main:info,state:info,mempool:info"
```
::: tip
You can also start a node from scratch by running `./init.sh` from the Ethermint repository directory. This will generate a key called `mykey` that you can use on the next step.
:::
In another tab start the REST server. Here replace `mykey` with the name of the key that you want to use and set the `chain-id` the chain identifier of your application.
```bash
ethermintd rest-server --laddr "tcp://localhost:8545" --unlock-key mykey --chain-id 1
```
## Adding a custom Network for Ethermint ## Adding a custom Network for Ethermint
One of the main limitations of using the default `Localhost 8545` network is that the tokens will be represented as `ETH`. One of the main limitations of using the default `Localhost 8545` network is that the tokens will be represented as `ETH`.
@ -32,13 +14,13 @@ Open the Metamask extension on your browser, you may have to log in to your Meta
are not already. Then click the top right circle and go to `Settings` > `Networks`. Press the `Add are not already. Then click the top right circle and go to `Settings` > `Networks`. Press the `Add
Network` button and fill the form as shown below with your application `ChainID`. Network` button and fill the form as shown below with your application `ChainID`.
![metamask networks settings](./img/metamask_network_settings.png) ![metamask networks settings](./../img/metamask_network_settings.png)
## Import Account to Metamask ## Import Account to Metamask
Then close the settings, and go to `My Accounts` (top right circle) and select `Import Account`. You should see and image like the following one: Then close the settings, and go to `My Accounts` (top right circle) and select `Import Account`. You should see and image like the following one:
![metamask import account page](./img/metamask_import.png) ![metamask import account page](./../img/metamask_import.png)
Now you can export your private key from the terminal using the following command. Again, make sure Now you can export your private key from the terminal using the following command. Again, make sure
to replace `mykey` with the name of the key that you want to export: to replace `mykey` with the name of the key that you want to export:
@ -60,7 +42,3 @@ Network` (or any other than `Localhost 8545` or `Ethermint`) and then switch bac
## Downloading State ## Downloading State
to see metamask logs, go to top right circle -> settings -> advanced -> download state logs. if you search through the json file for the account address you'll find the tx history to see metamask logs, go to top right circle -> settings -> advanced -> download state logs. if you search through the json file for the account address you'll find the tx history
## Known issues
Currently, it's not possible to add custom tokens (even for APhotons) unless you deploy a token contract (eg: ERC20).

13
docs/intro/README.md
View File

@ -8,13 +8,14 @@ parent:
This folder contains introduction material for Ethermint. This folder contains introduction material for Ethermint.
1. [Overview](./overview.md) 1. [Overview](./overview)
1. [Architecture](./architecture.md) 1. [Architecture](./architecture)
1. [Use Cases](./use_cases.md) 1. [Clients](./clients)
1. [Resources](./resources.md) 1. [Use Cases](./use_cases)
1. [Resources](./resources)
After reading the introduction material, head over to the [basics](../basics/README.md) to learn more. After reading the introduction material, head over to the [basics](../basics/README) to learn more.
## Next {hide} ## Next {hide}
Get an high-level [overview](./overview.md) of Ethermint {hide} Get an high-level [overview](./overview) of Ethermint {hide}

2
docs/intro/architecture.md
View File

@ -8,7 +8,7 @@ Learn how Ethermint's architecture leverages the Cosmos SDK Proof-of-Stake funct
## Cosmos SDK ## Cosmos SDK
Ethermint enables the full composability and modularity of the [Cosmos SDK](https://docs.cosmos.network/) Ethermint enables the full composability and modularity of the [Cosmos SDK](https://docs.cosmos.network/).
## Tendermint Core & the Application Blockchain Interface (ABCI) ## Tendermint Core & the Application Blockchain Interface (ABCI)

4
docs/quickstart/clients.md → docs/intro/clients.md
View File

@ -1,5 +1,5 @@
<!-- <!--
order: 6 order: 3
--> -->
# Clients # Clients
@ -29,7 +29,7 @@ APIs](https://eth.wiki/json-rpc/API) to connect with existing web3 tooling.
See the list of supported JSON-RPC API [namespaces](https://geth.ethereum.org/docs/rpc/server) and endpoints. 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`). To connect to the JSON-PRC server, start the node with the `--evm-rpc.enable=true` flag and define the namespaces that you would like to run using the `--evm.rpc.api` flag (e.g. `"txpool,eth,web3,net,personal"`. 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} ## Next {hide}

559
docs/package-lock.json generated
View File

File diff suppressed because it is too large Load Diff

5
docs/package.json
View File

@ -7,6 +7,7 @@
"preserve": "./pre.sh", "preserve": "./pre.sh",
"serve": "vuepress dev", "serve": "vuepress dev",
"build": "vuepress build", "build": "vuepress build",
"docs:build": "vuepress build docs",
"postserve": "./post.sh", "postserve": "./post.sh",
"prebuild": "./pre.sh", "prebuild": "./pre.sh",
"postbuild": "./post.sh" "postbuild": "./post.sh"
@ -16,13 +17,15 @@
"cosmos", "cosmos",
"ethereum", "ethereum",
"blockchain", "blockchain",
"cryptocurrency" "cryptocurrency",
"evm"
], ],
"author": "Tharsis", "author": "Tharsis",
"license": "ISC", "license": "ISC",
"dependencies": { "dependencies": {
"entities": "^2.0.3", "entities": "^2.0.3",
"markdown-it": "^12.0.6", "markdown-it": "^12.0.6",
"markdown-it-katex": "^2.0.3",
"vuepress-theme-cosmos": "^1.0.182" "vuepress-theme-cosmos": "^1.0.182"
}, },
"devDependencies": { "devDependencies": {

15
docs/quickstart/README.md
View File

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

148
docs/quickstart/binary.md Normal file
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 | |

20
docs/quickstart/installation.md
View File

@ -4,7 +4,15 @@ order: 1
# Installation # 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`: Clone and build Ethermint using `git`:
@ -17,7 +25,7 @@ make install
Check that the binaries have been successfully installed: Check that the binaries have been successfully installed:
```bash ```bash
ethermintd -h ethermintd version
``` ```
## Docker ## Docker
@ -32,7 +40,7 @@ This will install the binaries on the `./build` directory. Now, check that the b
successfully installed: successfully installed:
```bash ```bash
ethermintd -h ethermintd version
``` ```
## Releases ## 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. 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} ## Next {hide}

223
docs/quickstart/interact_node.md Normal file
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}

9
docs/quickstart/run_node.md
View File

@ -1,15 +1,20 @@
<!-- <!--
order: 2 order: 3
--> -->
# Run a Node # 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 ## Pre-requisite Readings
- [Installation](./installation.md) {prereq} - [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 ## Automated deployment
Run the local node Run the local node

15
docs/testnet/README.md Normal file
View File

@ -0,0 +1,15 @@
<!--
order: false
parent:
order: 5
-->
# API
This section contains different client and API reference document.
1. [Join Testnet](./join)
1. [Cloud Providers](./cloud_providers)
1. [Testnet](./testnet)
1. [Validator Setup](./validator-setup)
1. [Security Checklist](./security)

12
docs/guides/cloud_testnet.md → docs/testnet/cloud_providers.md
View File

@ -2,13 +2,9 @@
order: 4 order: 4
--> -->
# Deploy Testnet on Cloud Provider # Deploy Node on Cloud
Learn how to deploy testnet to different cloud providers. {synopsis} Learn how to deploy a node to different cloud providers. {synopsis}
## Pre-requisite Readings
- [Testnet Quickstart](./../quickstart/testnet.md) {prereq}
## Digital Ocean ## Digital Ocean
@ -81,7 +77,3 @@ scp -3 root@<TESTNET_IP_ADDRESS>:$HOME/.ethermintd/config/genesis.json root@<NOD
### Start the Node ### Start the Node
Once the genesis file is copied over run `ethermind start` inside the node droplet. Once the genesis file is copied over run `ethermind start` inside the node droplet.
## Next {hide}
Follow [Deploy node to public testnet](./deploy_node_on_public_testnet.md)

12
docs/guides/join_network.md → docs/testnet/join.md
View File

@ -17,16 +17,16 @@ This document outlines the steps to join an existing testnet
2. Create an Ethermint account 2. Create an Ethermint account
```bash ```bash
ethermintd keys add <keyname> ethermintd keys add <keyname> --keyring-backend=test
``` ```
3. Copy genesis file 3. Copy genesis file
Follow this [link](https://gist.github.com/araskachoi/43f86f3edff23729b817e8b0bb86295a) and copy it over to the directory ~/.ethermintd/config/genesis.json Follow this [link](https://gist.github.com/araskachoi/43f86f3edff23729b817e8b0bb86295a) and copy it over to the directory `~/.ethermintd/config/genesis.json`
4. Add peers 4. Add peers
Edit the file located in ~/.ethermintd/config/config.toml and edit line 350 (persistent_peers) to the following Edit the file located in `~/.ethermintd/config/config.toml` and the `persistent_peers` to the following:
```toml ```toml
"05aa6587f07a0c6a9a8213f0138c4a76d476418a@18.204.206.179:26656,13d4a1c16d1f427988b7c499b6d150726aaf3aa0@3.86.104.251:26656,a00db749fa51e485c8376276d29d599258052f3e@54.210.246.165:26656" "05aa6587f07a0c6a9a8213f0138c4a76d476418a@18.204.206.179:26656,13d4a1c16d1f427988b7c499b6d150726aaf3aa0@3.86.104.251:26656,a00db749fa51e485c8376276d29d599258052f3e@54.210.246.165:26656"
@ -37,5 +37,9 @@ This document outlines the steps to join an existing testnet
```bash ```bash
ethermintd validate-genesis ethermintd validate-genesis
ethermintd start --pruning=nothing --rpc.unsafe --log_level "main:info,state:info,mempool:info" --trace ethermintd start --pruning=nothing --rpc.unsafe --log_level "main:info,state:info,mempool:info"
``` ```
## Next {hide}
Learn how to deploy a testnet node on a [cloud provider](./cloud_providers) {hide}

48
docs/testnet/security.md Normal file
View File

@ -0,0 +1,48 @@
<!--
order: 5
-->
# Validator Security
## Checklist
## Conduct Survey on General Controls of Hosting Data Centre
Perform a survey on the hosting data centre, and compare your result with the best practice suggested below
For example, your hosting data centre should have following features
| Controls Category | Description of Best Practice |
|-------------------|---------------------------------|
| Data Center | Redundant Power |
| Data Center | Redundant Cooling |
| Data Center | Redundant Networking |
| Data Center | Physical Cage/Gated Access |
| Data Center | Remote Alerting Security Camera |
## Current Status of Node Setup
Perform a survey on your current status of node setup, and compare your result with the best practice suggested below
| Controls Category | Description of Best Practice |
|----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| General System Security | Operating system appropriately patched. Kernel is updated to latest stable version. The node should be operated in x86_64 environment |
| General System Security | Auto-updates for operation system is configured. Toolkit for automatic upgrades exists (e.g. auter, yum-cron, dnf-automatic, unattended-upgrades) |
| General System Security | Security framework enabled and enforcing. SELinux / AppArmor / Tomoyo / Grsecurity Enabled. |
| General System Security | No insecure and unnecessary services Installed. (e.g. telnet, rsh, inetd, etc ...) |
| General System Security | GRUB boot loader password is configured. Grub2 configured with password |
| General System Security | Only root permissions on core system files |
| File Directory Security | Secure the directory `~/.ethermintd` to be accessible by owner only |
| Binary Configuration | Recommend the following settings in config.toml for both performance and security - For **sentry nodes**: `max_num_inbound_peers = 500, max_num_outbound_peers = 50, flush_throttle_timeout = "300ms"` - For **validator node**: `max_num_inbound_peers = 100, max_num_outbound_peers = 10, flush_throttle_timeout = "100ms"` |
| Account Security & Remote Access | Following Password policies are enforced: No Blank Passwords; Weak Passwords Not Allowed |
| Account Security & Remote Access | Following SSH configurations are enabled: PermitRootLogin: `no`; PasswordAuthentication `no`; ChallengeResponseAuthentication `no`; UsePAM `yes`; AllowUsers `Necessary user only`; AllowGroups `Necessary group only`. |
| Networking | Network throughput test using speedtest. Recommend to have at least 5 Mbps upload, 5 Mbps download) |
| Networking | Host-based (e.g. iptables) or cloud-based (e.g. AWS Security Group) firewall is enabled to protect all the involved nodes. Remote management ports (e.g. SSH - TCP 22) should only be exposed to selected IP instead of the internet. No overly permissive rules (e.g. wide range of allowed ports 1-65535) should be set. For internal communication channels between nodes, they should be set with specific source and destination addresses. For internet reachable nodes, set TCP 26656 to be the only incoming port, if possible. |
| Networking | Intrusion Detection / Prevention System (e.g. Fail2Ban, Snort, OSSEC) is installed and enforcing |
| Networking | Setup sentry node architecture to protect validator node, and set firewall rules to restrict direct internet access to it. |
| Networking | The Remote Procedure Call (RPC) provides sensitive operations and information that is not supposed to be exposed to the Internet. By default, RPC is on and allow connection from 127.0.0.1 only. Please be extremely careful if you need to allow RPC from other IP addresses. |
| Redundancy | Hot standby node is setup with the same configuration as main node |
| Redundancy | System monitoring and alerting is setup to alert owners on anomalies |
| Key Management | Setup Tendermint KMS with HSM or equivalent online service, which should replace the static key file. |
| DDOS | Setup validator in accordance with sentry architecture. Kindly refer to the setup [instruction](https://docs.tendermint.com/master/nodes/validators.html#setting-up-a-validator) and [detailed description](https://forum.cosmos.network/t/sentry-node-architecture-overview/454). |

59
docs/testnet/testnet.md Normal file
View File

@ -0,0 +1,59 @@
<!--
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}
### Supported OS
We officially support macOS, Windows and Linux only. Other platforms may work but there is no
guarantee. We will extend our support to other platforms after we have stabilized our current
architecture.
### Minimum Requirements
To run testnet nodes, you will need a machine with the following minimum requirements:
- 4-core, x86_64 architecture processor;
- 16 GB RAM;
- 1 TB of storage space.
## 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}

0
docs/quickstart/validator-setup.md → docs/testnet/validator-setup.md
View File

2744
docs/yarn.lock
View File

File diff suppressed because it is too large Load Diff

2
scripts/protocgen.sh
View File

@ -34,7 +34,7 @@ done
buf protoc \ buf protoc \
-I "proto" \ -I "proto" \
-I "third_party/proto" \ -I "third_party/proto" \
--doc_out=./docs/core \ --doc_out=./docs/api \
--doc_opt=./docs/protodoc-markdown.tmpl,proto-docs.md \ --doc_opt=./docs/protodoc-markdown.tmpl,proto-docs.md \
$(find "$(pwd)/proto" -maxdepth 5 -name '*.proto') $(find "$(pwd)/proto" -maxdepth 5 -name '*.proto')
# go mod tidy # go mod tidy