From 0a1eb913dbee71aba7fdf0b424ed1ab222e2eabe Mon Sep 17 00:00:00 2001 From: Zach Ramsay Date: Fri, 18 Aug 2017 13:56:33 -0400 Subject: [PATCH 1/4] docs: connecting to testnets --- docs/connecting-to-testnets.md | 206 +++++++++++++++++++++++++++++++++ 1 file changed, 206 insertions(+) create mode 100644 docs/connecting-to-testnets.md diff --git a/docs/connecting-to-testnets.md b/docs/connecting-to-testnets.md new file mode 100644 index 0000000000..fcd4f53ff8 --- /dev/null +++ b/docs/connecting-to-testnets.md @@ -0,0 +1,206 @@ +# Connect to a testnet + +Join the ethermint testnet with a few commands. This guide is based on the [original Medium article](https://blog.cosmos.network/join-venus-the-new-ethermint-testnet-part-3-8e30c7d5abcf). + +## Pre-requisits + +You'll need the `ethermint` and `tendermint` binaries installed with the correct version. Ensure you are using compatible versions (how?). See their respective repos for install instructions. + +Check that everything is installed correctly: + +``` +tendermint version +v0.10.3 + +ethermint version +v0.3.0 +``` + +First, we need some directories for our files: + +``` +mkdir --parents ~/.venus/tendermint +mkdir ~/.venus/ethermint +``` + +Second, we're going to need the required initialization files. These consist of a `genesis.json` for each ethermint and tendermint and a `config.toml` for tendermint. These can be got using the `--testnets` flag on each respective program or by cloning the testnets repo. The `genesis.json` for tendermint will look like: + +``` +{ + "genesis_time":"2017-06-28T13:39:18Z", + "chain_id":"venus", + "validators": + [ + + { + "pub_key": { + "data": "E24396CFDCBAF3BD0F2C5CF510551F70B4634E4E5EBF9655B1FB57F451ABB344", + "type": "ed25519" + }, + "amount":10, + "name":"venus-node3" + } + , + { + "pub_key": { + "data": "2C97BEA0B5A4D9EAE04C242C7AD2A6D2BA989E3C4A7B276AB137300C37EB22F7", + "type": "ed25519" + }, + "amount":10, + "name":"venus-node4" + } + , + { + "pub_key": { + "data": "CA53D568F6EDC245D80D887F068F8FE7E03D540B2F7D2212CA436FC962394EA3", + "type": "ed25519" + }, + "amount":10, + "name":"venus-node0" + } + , + { + "pub_key": { + "data": "CE4877B1E25EDF845EC8F13FAC3B74E0B3A863EBA5B24D10FCDA4A239065E86A", + "type": "ed25519" + }, + "amount":10, + "name":"venus-node5" + } + , + { + "pub_key": { + "data": "8A825277C6A71C89B1F3E9AE5C3853E282F73B6F77A4798C03291EDB1F1F5CA5", + "type": "ed25519" + }, + "amount":10, + "name":"venus-node2" + } + , + { + "pub_key": { + "data": "AF8D2B55E6FAD5DCF6000752E2A05A19B3F42E3072B75BBB2217C43B574ACE99", + "type": "ed25519" + }, + "amount":10, + "name":"venus-node1" + } + , + { + "pub_key": { + "data": "B127402B86C673807AF407B15E324C4565B1A1DC77C85881E7D8D8640C17EBBB", + "type": "ed25519" + }, + "amount":10, + "name":"venus-node6" + } + ], + "app_hash":"", + "app_options": {} +} +``` + +which shows the validators each with 10 bonded tokens. The name of each validator can be used to view the node's information at, for example: http://venus-node0.testnets.interblock.io/ + +Let's take a look at the `config.toml` for tendermint: + +``` +# This is a TOML config file. +# For more information, see https://github.com/toml-lang/toml + +proxy_app = "tcp://127.0.0.1:46658" +moniker = "bob_the_farmer" +fast_sync = true +db_backend = "leveldb" +log_level = "debug" + +[rpc] +laddr = "tcp://0.0.0.0:46657" + +[p2p] +laddr = "tcp://0.0.0.0:46656" +seeds = "138.197.113.220:46656,138.68.12.252:46656,128.199.179.178:46656,139.59.184.2:46656,207.154.246.77:46656,138.197.175.237:46656" +``` + +The main relevant part is the `seeds =` field which has the peers to we'll be dialing to join the network. These IPs should match the URL of each node. The `moniker =` can be anything you'd like to name your node. + +Finally, we have a `genesis.json` for `ethermint`. It looks pretty much like a `genesis.json` for ethereum: + +``` +{ + "config": { + "chainId": 15, + "homesteadBlock": 0, + "eip155Block": 0, + "eip158Block": 0 + }, + "nonce": "0xdeadbeefdeadbeef", + "timestamp": "0x00", + "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000", + "mixhash": "0x0000000000000000000000000000000000000000000000000000000000000000", + "difficulty": "0x40", + "gasLimit": "0x8000000", + "alloc": { + "0x7eff122b94897ea5b0e2a9abf47b86337fafebdc": { "balance": "100000000000000" }, + "0xc6713982649D9284ff56c32655a9ECcCDA78422A": { "balance": "10000000000000000000000000000000000" } + } +} +``` + +At this point you should have a `genesis.json` and `config.toml` in `~/.venus/tendermint` and a `genesis.json` in `~/.venus/ethermint`. + +Next, we will initialize ethermint: + +``` +ethermint --datadir ~/.venus/ethermint init ~/.venus/ethermint/genesis.json +``` + +where the `--datadir` specifies the correct directory and `init` takes a path to the `genesis.json`. Look inside `~/.venus/ethermint/ethermint` to see the files that were created. + +Next, we'll start up the tendermint node: + +``` +tendermint --home ~/.venus/tendermint node +``` + +where `--home` is basically like the `--datadir` flag from running ethermint, and `node` is command that starts up the node. You'll see the following output: + +``` +I[08-18|17:13:25.880] Generated PrivValidator module=node file=/home/zach/.venus/tendermint/priv_validator.json +I[08-18|17:13:26.100] Starting multiAppConn module=proxy impl=multiAppConn +I[08-18|17:13:26.101] Starting socketClient module=abci-client connection=query impl=socketClient +E[08-18|17:13:26.102] abci.socketClient failed to connect to tcp://127.0.0.1:46658. Retrying... module=abci-client connection=query +E[08-18|17:13:29.102] abci.socketClient failed to connect to tcp://127.0.0.1:46658. Retrying... module=abci-client connection=query +``` + +with the last two lines in red. You'll see a steady stream of that error message every three seconds. Notice the first line; you should now have a `priv_validator.json` written to disk. + +Now you can start the ethermint process: + +``` +ethermint --datadir ~/.venus/ethermint/ --rpc --rpcaddr=0.0.0.0 --ws --wsaddr=0.0.0.0 --rpcapi eth,net,web3,personal,admin +``` + +There will be about a dozen lines of initialization information, then the output will look similar to: + +``` +INFO [08-18|13:35:40] Accepted a new connection module=abci-server +INFO [08-18|13:35:40] Waiting for new connection... module=abci-server +INFO [08-18|13:35:40] Info +INFO [08-18|13:35:40] BeginBlock +INFO [08-18|13:35:40] EndBlock +INFO [08-18|13:35:40] Commit +INFO [08-18|13:35:40] Committing block stateHash=fbccc1…f0e986 blockHash=3cddd3…97eb13 +INFO [08-18|13:35:40] Imported new chain segment blocks=1 txs=0 mgas=0.000 elapsed=2.516ms mgasps=0.000 number=3404 hash=3cddd3…97eb13 +INFO [08-18|13:35:40] Mapped network port proto=tcp extport=30303 intport=30303 interface="UPNP IGDv1-PPP1" +INFO [08-18|13:35:41] BeginBlock +INFO [08-18|13:35:41] EndBlock +INFO [08-18|13:35:41] Commit +INFO [08-18|13:35:41] Committing block stateHash=2eb09c…58f60f blockHash=df0411…8c7321 +INFO [08-18|13:35:41] Imported new chain segment blocks=1 txs=0 mgas=0.000 elapsed=1.315ms mgasps=0.000 number=3405 hash=df0411…8c7321 +INFO [08-18|13:35:41] BeginBlock +``` + +The above is output after the syncing had been stopped at block height 3403 (by terminating the process). Look at `Imported new chain segment` => `number=3404`, which increases by one as your node syncs with the testnet. Your output will start from number 1 unless you have been starting and stopping the nodes. + +Congratulation! You are currently syncing up with the testnet. Next, you'll need testnet coins, then try using `geth` to create contracts on the testnet. From 2d73287aabc6555017a559d042d80a0c2e6b5b97 Mon Sep 17 00:00:00 2001 From: Zach Ramsay Date: Wed, 23 Aug 2017 08:45:43 -0400 Subject: [PATCH 2/4] docs: format rst --- docs/getting-started.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/getting-started.rst b/docs/getting-started.rst index 6ff2c5ef84..170aba6a3c 100644 --- a/docs/getting-started.rst +++ b/docs/getting-started.rst @@ -1,3 +1,6 @@ +Getting Started +=============== + # Getting Started with Ethermint Running Ethermint requires both `ethermint` and `tendermint` installed. See [the README](../README.md) for installation information. From f29b9b0168f15e316c30c7070de6bb15b7e5d3f4 Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Wed, 16 Aug 2017 20:34:47 -0400 Subject: [PATCH 3/4] add docs/architecture/ibc --- docs/architecture/ibc.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 docs/architecture/ibc.md diff --git a/docs/architecture/ibc.md b/docs/architecture/ibc.md new file mode 100644 index 0000000000..4938690756 --- /dev/null +++ b/docs/architecture/ibc.md @@ -0,0 +1,36 @@ +# IBC Support in Ethermint + +Goals: + +- Ethermint can send and receive native and ERC20 tokens via IBC +- No changes to native Ethereum transaction format +- Use cosmos-sdk implementation of IBC + + +Design: + +- a native contract at address 0x00...000494243 (ie. "IBC") +- contains its own independent merkle IAVL tree +- hash of the IAVL tree is appended to ethereum block hash in return value of abci Commit message +- contract has functions for: + - registering a blockchain (stored in iavl tree) + - updating blockchain headers (stored in iavl tree) + - sending outgoing IBC (stored in iavl tree) + - receiving incoming IBC (validated against data in iavl tree) +- contract has the ability to inflate token supply and send to ethereum accounts in the trie +- receiving: + - serialized IBC packet received in transaction data + - deserialize, validate against known state of chain + - if valid, new tokens created and sent to destination address + - NOTE we need to be able to inflate both native token and erc20 tokens! +- sending: + - send function is called by some ethereum account with tokens + - IBC packet is formed and serialized and stored in the iavl tree + + + +Additional Notes: + +We want to support more general extensions to Ethermint, for instance a native contract that handles validators. +If we reuse cosmos-sdk libs, we may want to use just one IAVL tree for all extensions. +Thus all native contracts would be accounts in the one exstension IAVL tree, and this one trees root would be appended to the Tendermint AppHash. From daab0040b5caade28d2c17b6dd38ef44bc6ad758 Mon Sep 17 00:00:00 2001 From: Zach Ramsay Date: Wed, 23 Aug 2017 09:16:53 -0400 Subject: [PATCH 4/4] docs: fmt rst --- docs/connecting-to-testnets.md | 206 ------------------------------ docs/connecting-to-testnets.rst | 217 ++++++++++++++++++++++++++++++++ docs/getting-started.rst | 204 +++++++++++++++--------------- docs/index.rst | 1 + 4 files changed, 322 insertions(+), 306 deletions(-) delete mode 100644 docs/connecting-to-testnets.md create mode 100644 docs/connecting-to-testnets.rst diff --git a/docs/connecting-to-testnets.md b/docs/connecting-to-testnets.md deleted file mode 100644 index fcd4f53ff8..0000000000 --- a/docs/connecting-to-testnets.md +++ /dev/null @@ -1,206 +0,0 @@ -# Connect to a testnet - -Join the ethermint testnet with a few commands. This guide is based on the [original Medium article](https://blog.cosmos.network/join-venus-the-new-ethermint-testnet-part-3-8e30c7d5abcf). - -## Pre-requisits - -You'll need the `ethermint` and `tendermint` binaries installed with the correct version. Ensure you are using compatible versions (how?). See their respective repos for install instructions. - -Check that everything is installed correctly: - -``` -tendermint version -v0.10.3 - -ethermint version -v0.3.0 -``` - -First, we need some directories for our files: - -``` -mkdir --parents ~/.venus/tendermint -mkdir ~/.venus/ethermint -``` - -Second, we're going to need the required initialization files. These consist of a `genesis.json` for each ethermint and tendermint and a `config.toml` for tendermint. These can be got using the `--testnets` flag on each respective program or by cloning the testnets repo. The `genesis.json` for tendermint will look like: - -``` -{ - "genesis_time":"2017-06-28T13:39:18Z", - "chain_id":"venus", - "validators": - [ - - { - "pub_key": { - "data": "E24396CFDCBAF3BD0F2C5CF510551F70B4634E4E5EBF9655B1FB57F451ABB344", - "type": "ed25519" - }, - "amount":10, - "name":"venus-node3" - } - , - { - "pub_key": { - "data": "2C97BEA0B5A4D9EAE04C242C7AD2A6D2BA989E3C4A7B276AB137300C37EB22F7", - "type": "ed25519" - }, - "amount":10, - "name":"venus-node4" - } - , - { - "pub_key": { - "data": "CA53D568F6EDC245D80D887F068F8FE7E03D540B2F7D2212CA436FC962394EA3", - "type": "ed25519" - }, - "amount":10, - "name":"venus-node0" - } - , - { - "pub_key": { - "data": "CE4877B1E25EDF845EC8F13FAC3B74E0B3A863EBA5B24D10FCDA4A239065E86A", - "type": "ed25519" - }, - "amount":10, - "name":"venus-node5" - } - , - { - "pub_key": { - "data": "8A825277C6A71C89B1F3E9AE5C3853E282F73B6F77A4798C03291EDB1F1F5CA5", - "type": "ed25519" - }, - "amount":10, - "name":"venus-node2" - } - , - { - "pub_key": { - "data": "AF8D2B55E6FAD5DCF6000752E2A05A19B3F42E3072B75BBB2217C43B574ACE99", - "type": "ed25519" - }, - "amount":10, - "name":"venus-node1" - } - , - { - "pub_key": { - "data": "B127402B86C673807AF407B15E324C4565B1A1DC77C85881E7D8D8640C17EBBB", - "type": "ed25519" - }, - "amount":10, - "name":"venus-node6" - } - ], - "app_hash":"", - "app_options": {} -} -``` - -which shows the validators each with 10 bonded tokens. The name of each validator can be used to view the node's information at, for example: http://venus-node0.testnets.interblock.io/ - -Let's take a look at the `config.toml` for tendermint: - -``` -# This is a TOML config file. -# For more information, see https://github.com/toml-lang/toml - -proxy_app = "tcp://127.0.0.1:46658" -moniker = "bob_the_farmer" -fast_sync = true -db_backend = "leveldb" -log_level = "debug" - -[rpc] -laddr = "tcp://0.0.0.0:46657" - -[p2p] -laddr = "tcp://0.0.0.0:46656" -seeds = "138.197.113.220:46656,138.68.12.252:46656,128.199.179.178:46656,139.59.184.2:46656,207.154.246.77:46656,138.197.175.237:46656" -``` - -The main relevant part is the `seeds =` field which has the peers to we'll be dialing to join the network. These IPs should match the URL of each node. The `moniker =` can be anything you'd like to name your node. - -Finally, we have a `genesis.json` for `ethermint`. It looks pretty much like a `genesis.json` for ethereum: - -``` -{ - "config": { - "chainId": 15, - "homesteadBlock": 0, - "eip155Block": 0, - "eip158Block": 0 - }, - "nonce": "0xdeadbeefdeadbeef", - "timestamp": "0x00", - "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000", - "mixhash": "0x0000000000000000000000000000000000000000000000000000000000000000", - "difficulty": "0x40", - "gasLimit": "0x8000000", - "alloc": { - "0x7eff122b94897ea5b0e2a9abf47b86337fafebdc": { "balance": "100000000000000" }, - "0xc6713982649D9284ff56c32655a9ECcCDA78422A": { "balance": "10000000000000000000000000000000000" } - } -} -``` - -At this point you should have a `genesis.json` and `config.toml` in `~/.venus/tendermint` and a `genesis.json` in `~/.venus/ethermint`. - -Next, we will initialize ethermint: - -``` -ethermint --datadir ~/.venus/ethermint init ~/.venus/ethermint/genesis.json -``` - -where the `--datadir` specifies the correct directory and `init` takes a path to the `genesis.json`. Look inside `~/.venus/ethermint/ethermint` to see the files that were created. - -Next, we'll start up the tendermint node: - -``` -tendermint --home ~/.venus/tendermint node -``` - -where `--home` is basically like the `--datadir` flag from running ethermint, and `node` is command that starts up the node. You'll see the following output: - -``` -I[08-18|17:13:25.880] Generated PrivValidator module=node file=/home/zach/.venus/tendermint/priv_validator.json -I[08-18|17:13:26.100] Starting multiAppConn module=proxy impl=multiAppConn -I[08-18|17:13:26.101] Starting socketClient module=abci-client connection=query impl=socketClient -E[08-18|17:13:26.102] abci.socketClient failed to connect to tcp://127.0.0.1:46658. Retrying... module=abci-client connection=query -E[08-18|17:13:29.102] abci.socketClient failed to connect to tcp://127.0.0.1:46658. Retrying... module=abci-client connection=query -``` - -with the last two lines in red. You'll see a steady stream of that error message every three seconds. Notice the first line; you should now have a `priv_validator.json` written to disk. - -Now you can start the ethermint process: - -``` -ethermint --datadir ~/.venus/ethermint/ --rpc --rpcaddr=0.0.0.0 --ws --wsaddr=0.0.0.0 --rpcapi eth,net,web3,personal,admin -``` - -There will be about a dozen lines of initialization information, then the output will look similar to: - -``` -INFO [08-18|13:35:40] Accepted a new connection module=abci-server -INFO [08-18|13:35:40] Waiting for new connection... module=abci-server -INFO [08-18|13:35:40] Info -INFO [08-18|13:35:40] BeginBlock -INFO [08-18|13:35:40] EndBlock -INFO [08-18|13:35:40] Commit -INFO [08-18|13:35:40] Committing block stateHash=fbccc1…f0e986 blockHash=3cddd3…97eb13 -INFO [08-18|13:35:40] Imported new chain segment blocks=1 txs=0 mgas=0.000 elapsed=2.516ms mgasps=0.000 number=3404 hash=3cddd3…97eb13 -INFO [08-18|13:35:40] Mapped network port proto=tcp extport=30303 intport=30303 interface="UPNP IGDv1-PPP1" -INFO [08-18|13:35:41] BeginBlock -INFO [08-18|13:35:41] EndBlock -INFO [08-18|13:35:41] Commit -INFO [08-18|13:35:41] Committing block stateHash=2eb09c…58f60f blockHash=df0411…8c7321 -INFO [08-18|13:35:41] Imported new chain segment blocks=1 txs=0 mgas=0.000 elapsed=1.315ms mgasps=0.000 number=3405 hash=df0411…8c7321 -INFO [08-18|13:35:41] BeginBlock -``` - -The above is output after the syncing had been stopped at block height 3403 (by terminating the process). Look at `Imported new chain segment` => `number=3404`, which increases by one as your node syncs with the testnet. Your output will start from number 1 unless you have been starting and stopping the nodes. - -Congratulation! You are currently syncing up with the testnet. Next, you'll need testnet coins, then try using `geth` to create contracts on the testnet. diff --git a/docs/connecting-to-testnets.rst b/docs/connecting-to-testnets.rst new file mode 100644 index 0000000000..0c28e0c190 --- /dev/null +++ b/docs/connecting-to-testnets.rst @@ -0,0 +1,217 @@ +Connect to a testnet +==================== + +Join the ethermint testnet with a few commands. This guide is based on the `original Medium article `_. + +Pre-requisites +------------- + +You'll need the ``ethermint`` and ``tendermint`` binaries installed with the correct version. Ensure you are using compatible versions (how?). See their respective repos for install instructions. + +Check that everything is installed correctly: + +:: + + tendermint version + v0.10.3 + + ethermint version + v0.3.0 + +First, we need some directories for our files: + +:: + + mkdir --parents ~/.venus/tendermint + mkdir ~/.venus/ethermint + +Second, we're going to need the required initialization files. These consist of a ``genesis.json`` for each ethermint and tendermint and a ``config.toml`` for tendermint. These can be got using the ``--testnet`` flag on each respective program or by cloning the testnets repo. The ``genesis.json`` for tendermint will look like: + +:: + + { + "genesis_time":"2017-06-28T13:39:18Z", + "chain_id":"venus", + "validators": + [ + + { + "pub_key": { + "data": "E24396CFDCBAF3BD0F2C5CF510551F70B4634E4E5EBF9655B1FB57F451ABB344", + "type": "ed25519" + }, + "amount":10, + "name":"venus-node3" + } + , + { + "pub_key": { + "data": "2C97BEA0B5A4D9EAE04C242C7AD2A6D2BA989E3C4A7B276AB137300C37EB22F7", + "type": "ed25519" + }, + "amount":10, + "name":"venus-node4" + } + , + { + "pub_key": { + "data": "CA53D568F6EDC245D80D887F068F8FE7E03D540B2F7D2212CA436FC962394EA3", + "type": "ed25519" + }, + "amount":10, + "name":"venus-node0" + } + , + { + "pub_key": { + "data": "CE4877B1E25EDF845EC8F13FAC3B74E0B3A863EBA5B24D10FCDA4A239065E86A", + "type": "ed25519" + }, + "amount":10, + "name":"venus-node5" + } + , + { + "pub_key": { + "data": "8A825277C6A71C89B1F3E9AE5C3853E282F73B6F77A4798C03291EDB1F1F5CA5", + "type": "ed25519" + }, + "amount":10, + "name":"venus-node2" + } + , + { + "pub_key": { + "data": "AF8D2B55E6FAD5DCF6000752E2A05A19B3F42E3072B75BBB2217C43B574ACE99", + "type": "ed25519" + }, + "amount":10, + "name":"venus-node1" + } + , + { + "pub_key": { + "data": "B127402B86C673807AF407B15E324C4565B1A1DC77C85881E7D8D8640C17EBBB", + "type": "ed25519" + }, + "amount":10, + "name":"venus-node6" + } + ], + "app_hash":"", + "app_options": {} + } + +which shows the validators each with 10 bonded tokens. The name of each validator can be used to view the node's information at, for example: http://venus-node0.testnets.interblock.io/ + +Let's take a look at the ``config.toml`` for tendermint: + +:: + + # This is a TOML config file. + # For more information, see https://github.com/toml-lang/toml + + proxy_app = "tcp://127.0.0.1:46658" + moniker = "bob_the_farmer" + fast_sync = true + db_backend = "leveldb" + log_level = "debug" + + [rpc] + laddr = "tcp://0.0.0.0:46657" + + [p2p] + laddr = "tcp://0.0.0.0:46656" + seeds = "138.197.113.220:46656,138.68.12.252:46656,128.199.179.178:46656,139.59.184.2:46656,207.154.246.77:46656,138.197.175.237:46656" + +The main relevant part is the ``seeds =`` field which has the peers to we'll be dialing to join the network. These IPs should match the URL of each node. The ``moniker =`` can be anything you'd like to name your node. + +Finally, we have a ``genesis.json`` for ``ethermint``. It looks pretty much like a ``genesis.json`` for ethereum: + +:: + + { + "config": { + "chainId": 15, + "homesteadBlock": 0, + "eip155Block": 0, + "eip158Block": 0 + }, + "nonce": "0xdeadbeefdeadbeef", + "timestamp": "0x00", + "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000", + "mixhash": "0x0000000000000000000000000000000000000000000000000000000000000000", + "difficulty": "0x40", + "gasLimit": "0x8000000", + "alloc": { + "0x7eff122b94897ea5b0e2a9abf47b86337fafebdc": { "balance": "100000000000000" }, + "0xc6713982649D9284ff56c32655a9ECcCDA78422A": { "balance": "10000000000000000000000000000000000" } + } + } + +At this point you should have a ``genesis.json`` and ``config.toml`` in ``~/.venus/tendermint`` and a ``genesis.json`` in ``~/.venus/ethermint``. + +Initialize +---------- + +Next, we will initialize ethermint: + +:: + + ethermint --datadir ~/.venus/ethermint init ~/.venus/ethermint/genesis.json + +where the ``--datadir`` specifies the correct directory and ``init`` takes a path to the ``genesis.json``. Look inside ``~/.venus/ethermint/ethermint`` to see the files that were created. + +Run Tendermint +-------------- + +Then we start up the tendermint node: + +:: + + tendermint --home ~/.venus/tendermint node + +where ``--home`` is basically like the ``--datadir`` flag from running ethermint, and ``node`` is command that starts up the node. You'll see the following output: + +:: + + I[08-18|17:13:25.880] Generated PrivValidator module=node file=/home/zach/.venus/tendermint/priv_validator.json + I[08-18|17:13:26.100] Starting multiAppConn module=proxy impl=multiAppConn + I[08-18|17:13:26.101] Starting socketClient module=abci-client connection=query impl=socketClient + E[08-18|17:13:26.102] abci.socketClient failed to connect to tcp://127.0.0.1:46658. Retrying... module=abci-client connection=query + E[08-18|17:13:29.102] abci.socketClient failed to connect to tcp://127.0.0.1:46658. Retrying... module=abci-client connection=query + +with the last two lines in red. You'll see a steady stream of that error message every three seconds. Notice the first line; you should now have a ``priv_validator.json`` written to disk. + +Run Ethermint +------------- + +Now you can start the ethermint process: + +:: + + ethermint --datadir ~/.venus/ethermint/ --rpc --rpcaddr=0.0.0.0 --ws --wsaddr=0.0.0.0 --rpcapi eth,net,web3,personal,admin + +There will be about a dozen lines of initialization information, then the output will look similar to: + +:: + + INFO [08-18|13:35:40] Accepted a new connection module=abci-server + INFO [08-18|13:35:40] Waiting for new connection... module=abci-server + INFO [08-18|13:35:40] Info + INFO [08-18|13:35:40] BeginBlock + INFO [08-18|13:35:40] EndBlock + INFO [08-18|13:35:40] Commit + INFO [08-18|13:35:40] Committing block stateHash=fbccc1…f0e986 blockHash=3cddd3…97eb13 + INFO [08-18|13:35:40] Imported new chain segment blocks=1 txs=0 mgas=0.000 elapsed=2.516ms mgasps=0.000 number=3404 hash=3cddd3…97eb13 + INFO [08-18|13:35:40] Mapped network port proto=tcp extport=30303 intport=30303 interface="UPNP IGDv1-PPP1" + INFO [08-18|13:35:41] BeginBlock + INFO [08-18|13:35:41] EndBlock + INFO [08-18|13:35:41] Commit + INFO [08-18|13:35:41] Committing block stateHash=2eb09c…58f60f blockHash=df0411…8c7321 + INFO [08-18|13:35:41] Imported new chain segment blocks=1 txs=0 mgas=0.000 elapsed=1.315ms mgasps=0.000 number=3405 hash=df0411…8c7321 + INFO [08-18|13:35:41] BeginBlock + +The above is output after the syncing had been stopped at block height 3403 (by terminating the process). Look at ``Imported new chain segment`` => ``number=3404``, which increases by one as your node syncs with the testnet. Your output will start from number 1 unless you have been starting and stopping the nodes. + +Congratulation! You are currently syncing up with the testnet. Next, you'll need testnet coins, then try using ``geth`` to create contracts on the testnet. diff --git a/docs/getting-started.rst b/docs/getting-started.rst index 170aba6a3c..8077e39be4 100644 --- a/docs/getting-started.rst +++ b/docs/getting-started.rst @@ -1,167 +1,171 @@ Getting Started =============== -# Getting Started with Ethermint +Running Ethermint requires both ``ethermint`` and ``tendermint`` installed. Review the installation instructions below: -Running Ethermint requires both `ethermint` and `tendermint` installed. See [the README](../README.md) for installation information. +.. toctree:: + :maxdepth: 2 -## Starting Ethermint + installation.rst + +Setup Ethermint +------------------ -### Initialisation To get started, you need to initialise the genesis block for tendermint core and go-ethereum. We provide initialisation files with reasonable defaults and money allocated into a predefined account. If you installed from binary or docker -please download [the default files here](https://github.com/tendermint/ethermint/tree/develop/setup). +please download `the default files here `_. -You can choose where to store the ethermint files with `--datadir`. For this guide, we will use `~/.ethermint`, which is a reasonable default in most cases. +You can choose where to store the ethermint files with ``--datadir``. For this guide, we will use ``~/.ethermint``, which is a reasonable default in most cases. Before you can run ethermint you need to initialise tendermint and ethermint with their respective genesis states. Please switch into the folder where you have the initialisation files. If you installed from source you can just follow these instructions. -```bash -tendermint init --home ~/.ethermint/tendermint - -cd $GOPATH/src/github.com/tendermint/ethermint +:: -ethermint --datadir ~/.ethermint init setup/genesis.json - -cp -r setup/keystore ~/.ethermint -``` + tendermint init --home ~/.ethermint/tendermint + + cd $GOPATH/src/github.com/tendermint/ethermint + + ethermint --datadir ~/.ethermint init setup/genesis.json + + cp -r setup/keystore ~/.ethermint In the last step we copy the private key from the initialisation folder into the actual ethereum folder. -### Running +Run Ethermint +------------- + To execute ethermint we need to start two processes. The first one is for tendermint, which handles the P2P communication as well as the consensus process, while the second one is actually ethermint, which provides the go-ethereum functionality. -```bash -tendermint --home ~/.ethermint/tendermint node +:: -ethermint --datadir ~/.ethermint --rpc --rpcaddr=0.0.0.0 --ws --wsaddr=0.0.0.0 --rpcapi eth,net,web3,personal,admin -``` + tendermint --home ~/.ethermint/tendermint node + + ethermint --datadir ~/.ethermint --rpc --rpcaddr=0.0.0.0 --ws --wsaddr=0.0.0.0 --rpcapi eth,net,web3,personal,admin The **password** for the default account is *1234*, which we'll need below. -## Connecting to Geth +Connect to Geth +--------------- + +First, install `geth `_, then: -First, install [geth](https://github.com/ethereum/go-ethereum), then: +:: -``` -geth attach http://localhost:8545 -``` + geth attach http://localhost:8545 which drops you into a web3 console. Now we have access to all the functions from web3 at our fingertips, try: -``` -> eth -``` +:: + + > eth to see all the options. Let's start by looking at our default accounts with: -``` -> eth.accounts -``` +:: + + > eth.accounts There will be only one account and it should match the account given with: -``` -cat ~/.ethermint/keystore/UTC--2016-10-21T22-30-03.071787745Z--7eff122b94897ea5b0e2a9abf47b86337fafebdc -``` +:: + + cat ~/.ethermint/keystore/UTC--2016-10-21T22-30-03.071787745Z--7eff122b94897ea5b0e2a9abf47b86337fafebdc -and note that the last portion of that file name is your account (save for `0x`) as with the first field of the file itself. +and note that the last portion of that file name is your account (except for ``0x``) as with the first field of the file itself. We can also view the block number: -``` -> eth.blockNumber -``` - -which will be in sync with the logs of `ethermint`: +:: + + > eth.blockNumber -``` -INFO [08-07|22:32:30] Imported new chain segment blocks=1 txs=0 mgas=0.000 elapsed=1.705ms mgasps=0.000 number=248 hash=7fbd05…a231a8 +which will be in sync with the logs of ``ethermint``: -INFO [08-07|22:32:31] BeginBlock -INFO [08-07|22:32:31] EndBlock -INFO [08-07|22:32:31] Commit -INFO [08-07|22:32:31] Committing block stateHash=c0d88d…3a474a blockHash=83b9df…5fc4cb -``` +:: + + INFO [08-07|22:32:30] Imported new chain segment blocks=1 txs=0 mgas=0.000 elapsed=1.705ms mgasps=0.000 number=248 hash=7fbd05…a231a8 + INFO [08-07|22:32:31] BeginBlock + INFO [08-07|22:32:31] EndBlock + INFO [08-07|22:32:31] Commit + INFO [08-07|22:32:31] Committing block stateHash=c0d88d…3a474a blockHash=83b9df…5fc4cb -and of `tendermint`: +and of ``tendermint``: -``` -I[08-08|02:32:30.000] Executed block module=state height=248 validTxs=0 invalidTxs=0 -I[08-08|02:32:30.042] Committed state module=state height=248 txs=0 hash=A524F17E9E1EDE3438B2B8DB231B719BCA8A38B5872C48E43A6B29BB189FA749 - -``` +:: + + I[08-08|02:32:30.000] Executed block module=state height=248 validTxs=0 invalidTxs=0 + I[08-08|02:32:30.042] Committed state module=state height=248 txs=0 hash=A524F17E9E1EDE3438B2B8DB231B719BCA8A38B5872C48E43A6B29BB189FA749 note that the block height is increasing approximately once per second. Next, we can see the balance of our accounts with: -``` -> eth.getBalance("0x7eff122b94897ea5b0e2a9abf47b86337fafebdc") -``` +:: + + > eth.getBalance("0x7eff122b94897ea5b0e2a9abf47b86337fafebdc") -which should be `this amount` if you haven't yet sent a transaction or deployed a contract +which should ``1e+34`` if you haven't yet sent a transaction or deployed a contract Before deploying a contract, we must unlock the key. First, note that it is locked: -``` -> web3.personal -``` +:: + + > web3.personal -and you'll see `status: "Locked"` a few lines down. But wait, why did we go from `eth` to `web3`? We're not sure but that's how it works so follow along. +and you'll see ``status: "Locked"`` a few lines down. But wait, why did we go from ``eth`` to ``web3``? We're not sure but that's how it works so follow along. -``` -> web3.personal.unlockAccount("0x7eff122b94897ea5b0e2a9abf47b86337fafebdc", "1234", 100000) -``` +:: + + > web3.personal.unlockAccount("0x7eff122b94897ea5b0e2a9abf47b86337fafebdc", "1234", 100000) where the first argument is your account, the second your password (see above), and the third - the amount of time in seconds to keep key unlocked. -Now we can deploy a contract. Since `eth.compile` wasn't quite working (dbl check) for me, we can use [browser solidity](https://ethereum.github.io/browser-solidity). Let's use a short contract like: - -``` -pragma solidity ^0.4.0; - -contract Test { - function double(int a) constant returns(int) { - return 2*a; - } -} -``` - -then look for the `Contract details (bytecode, interface etc.)` on the right sidebar. Copy the code from the "Web3 deploy" section, which will be similar to: - -``` -var browser_double_sol_testContract = web3.eth.contract([{"constant":true,"inputs":[{"name":"a","type":"int256"}],"name":"double","outputs":[{"name":"","type":"int256"}],"payable":false,"type":"function"}]); -var browser_double_sol_test = browser_double_sol_testContract.new( - { - from: web3.eth.accounts[0], - data: '0x6060604052341561000f57600080fd5b5b60ab8061001e6000396000f30060606040526000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff1680636ffa1caa14603d575b600080fd5b3415604757600080fd5b605b60048080359060200190919050506071565b6040518082815260200191505060405180910390f35b60008160020290505b9190505600a165627a7a72305820c5fd101c8bd62761d1803c865fd4af5c57f3752e6212d7ccebd5b4a23fcd23180029', - gas: '4300000' - }, function (e, contract){ - console.log(e, contract); - if (typeof contract.address !== 'undefined') { - console.log('Contract mined! address: ' + contract.address + ' transactionHash: ' + contract.transactionHash); - } - }) -``` - -and paste it directly in the `geth` console. A handful of dots will accrue on each line but the code should run and deploy the contract. You'll see something like: - -``` -null [object Object] -undefined -Contract mined! address: 0xab119259ff325f845f8ce59de8ccf63e597a74cd transactionHash: 0xf3031c975ef55d14a0382df748b3e66a22c61922b80075ee244c493db5f80c5c -``` +Now we can deploy a contract. Since ``eth.compile`` wasn't quite working for me, we can use `browser solidity `_. Let's use a short contract like: + +:: + + pragma solidity ^0.4.0; + + contract Test { + function double(int a) constant returns(int) { + return 2*a; + } + } + +then look for the ``Contract details (bytecode, interface etc.)`` on the right sidebar. Copy the code from the "Web3 deploy" section, which will be similar to: + +:: + + var browser_double_sol_testContract = web3.eth.contract([{"constant":true,"inputs":[{"name":"a","type":"int256"}],"name":"double","outputs":[{"name":"","type":"int256"}],"payable":false,"type":"function"}]); + var browser_double_sol_test = browser_double_sol_testContract.new( + { + from: web3.eth.accounts[0], + data: '0x6060604052341561000f57600080fd5b5b60ab8061001e6000396000f30060606040526000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff1680636ffa1caa14603d575b600080fd5b3415604757600080fd5b605b60048080359060200190919050506071565b6040518082815260200191505060405180910390f35b60008160020290505b9190505600a165627a7a72305820c5fd101c8bd62761d1803c865fd4af5c57f3752e6212d7ccebd5b4a23fcd23180029', + gas: '4300000' + }, function (e, contract){ + console.log(e, contract); + if (typeof contract.address !== 'undefined') { + console.log('Contract mined! address: ' + contract.address + ' transactionHash: ' + contract.transactionHash); + } + }) + +and paste it directly in the ``geth`` console. A handful of dots will accrue on each line but the code should run and deploy the contract. You'll see something like: + +:: + + null [object Object] + undefined + Contract mined! address: 0xab119259ff325f845f8ce59de8ccf63e597a74cd transactionHash: 0xf3031c975ef55d14a0382df748b3e66a22c61922b80075ee244c493db5f80c5c which has the information you need to call this contract on the chain. -From the `ethermint` logs we'll see a big stream of data while the `tendermint` logs will show the `validTxs` and `txs` fields increase from 0 to 1. +From the ``ethermint`` logs we'll see a big stream of data while the ``tendermint`` logs will show the ``validTxs`` and ``txs`` fields increase from 0 to 1. That's it, you've deployed a contract to ethermint! Next, we can call a contract or setup a testnet. diff --git a/docs/index.rst b/docs/index.rst index 0082158116..8d40ca7e73 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,6 +14,7 @@ Contents: introduction installation getting-started + connecting-to-testnets architecture