Skip to content
This repository was archived by the owner on Oct 28, 2021. It is now read-only.

Documentation for creating a private network with 2 nodes #5546

Merged
halfalicious merged 12 commits into from
Apr 8, 2019
Merged

Documentation for creating a private network with 2 nodes #5546

Changes from 1 commit
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
9a0ada4
Rename existing private network documentation
halfalicious Apr 2, 2019
98409f3
Initial (extremely rough) version of new private docs
halfalicious Apr 2, 2019
0d1ea37
Lots of revisions. Still need to add proper formatting
halfalicious Apr 3, 2019
515cf26
More edits
halfalicious Apr 3, 2019
d672288
First round of formatting changes
halfalicious Apr 4, 2019
119b719
More formatting changes and minor language tweaks
halfalicious Apr 5, 2019
ab56949
More formatting changes/edits
halfalicious Apr 5, 2019
8b9983d
More minor tweaks
halfalicious Apr 5, 2019
d918c99
More updates
halfalicious Apr 5, 2019
0f37479
Yet more edits
halfalicious Apr 5, 2019
ad8787b
Update index
halfalicious Apr 5, 2019
48eead6
Address PR feedback
halfalicious Apr 6, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
First round of formatting changes
  • Loading branch information
@halfalicious
halfalicious committed Apr 4, 2019
commit d6722883c196b7ff5419742f042e329cbf5d2c28
192 changes: 119 additions & 73 deletions doc/private_net_sync.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,58 +2,65 @@ Creating a private network with 2 syncing nodes
===============================================
These instructions cover creating an Ethereum private network consisting of 2 nodes - 1 node will mine blocks and the other node will connect to the first node and sync the mined blocks to its own block database. Both nodes will use (the same) private chain configuration.

Before we start
===============

What is a private network?
=========================
--------------------------
For the purposes of this documentation, a "private network" can be thought of as a network of Ethereum nodes only accessible on your physical machine.

What is a private chain?
========================
-------------------------
An Ethereum chain is some state (e.g. accounts and balances and/or contract code) and a set of rules a set of rules for interacting with that state. For the purposes of this documentation, a private chain is an Ethereum chain is one whose configuration is only available on your physical machine.

Mining
===========
* Mining will be done using the Aleth CPU miner (Aleth doesn't include a GPU miner because of the high support costs)
* Only 1 node will be mining to keep your machine responsive (since both nodes are running on the same physical system, having both mine will slow your system down significantly).
* If you find your system being sluggish or if you'd like to have both nodes mine, you can tune the number of mining threads via the -t <thread count> flag
------
- Mining will be done using the Aleth CPU miner (Aleth doesn't include a GPU miner because of the high support costs).
- Only 1 node will be mining to keep your machine responsive (since both nodes are running on the same physical system, having both mine will slow your system down significantly).
- If you find your system being sluggish or if you'd like to have both nodes mine, you can tune the number of mining threads via the ``-t <thread count>`` flag

Chain configuration
===================
* You typically run a private chain using a chain configuration json file - this isn't strictly required, but it makes testing a lot easier since you can do things like lower the difficulty rate and pre-fund addresses with Ether.
* The chain configuration json file format is defined here: TODO
* Here's an example file:
* Since the configuration file is used to create the chain's genesis state, both nodes must use the same configuration file otherwise they will have different genesis states and consequently won't be able to peer with each other. An example of this is shown in the "Common Problems" section (TODO)
-------------------
- You typically run a private chain using a chain configuration json file - this isn't strictly required, but it makes testing a lot easier since you can do things like lower the difficulty rate and pre-fund addresses with Ether.
- The chain configuration json file format is defined here: https://github.com/ethereum/wiki/wiki/Ethereum-Chain-Spec-Format
Copy link
Member

@gumb0 gumb0 Apr 5, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we really follow that spec? It might be outdated.

Copy link
Contributor Author

@halfalicious halfalicious Apr 6, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good question! I assumed we did, Ill investigate

Copy link
Contributor Author

@halfalicious halfalicious Apr 6, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right, the spec is either deprecated or we don't fully implement the spec (for example it lists a "nodes" key which we don't support). I'll remove the link.

- Here's an example file: TODO
- Since the configuration file is used to create the chain's genesis state, both nodes must use the same configuration file otherwise they will have different genesis states and consequently won't be able to peer with each other. An example of this is shown in the "Common Problems" section (TODO)

Instructions
============
Note: The examples in this section were generated on Windows 10 running aleth 1.6.0-alpha.1-31+commit.ad7204c9
*The examples in this section were generated on Windows 10 running aleth 1.6.0-alpha.1-31+commit.ad7204c9*

1. Create a key pair for each node:

1. Create a key pair for each node
Execute the following command and enter the desired password when prompted
::

aleth.exe account new

aleth.exe account new

Enter the desired password when prompted

C:\Users\nilse\Documents\Code\aleth_ref\build\aleth\Debug>aleth account new

**Example:**
::

aleth account new
[2019-04-02 19:59:42.515684] [0x000041f0] [info] ReadingC:\Users\nilse\AppData\Roaming\Web3\keys\4f04a5ed-87e4-1e4d-4367-604db42bdcff.json
[2019-04-02 19:59:42.520265] [0x000041f0] [info] ReadingC:\Users\nilse\AppData\Roaming\Web3\keys\84258fde-b0d9-747e-b70f-f55e14831192.json
[2019-04-02 19:59:42.520265] [0x000041f0] [info] ReadingC:\Users\nilse\AppData\Roaming\Web3\keys\9067d973-1c8d-fa86-a312-14c90188f610.json
Enter a passphrase with which to secure this account:Please confirm the passphrase by entering it again: Created key 623b80dd-d008-4cd4-dd06-c36f0f64296c
Address: 007e13502a8b226b0f19e7412db75352dc1d0760

C:\Users\nilse\Documents\Code\aleth_ref\build\aleth\Debug>aleth account new
aleth account new
[2019-04-02 19:59:53.847216] [0x000011b4] [info] ReadingC:\Users\nilse\AppData\Roaming\Web3\keys\4f04a5ed-87e4-1e4d-4367-604db42bdcff.json
[2019-04-02 19:59:53.849343] [0x000011b4] [info] ReadingC:\Users\nilse\AppData\Roaming\Web3\keys\623b80dd-d008-4cd4-dd06-c36f0f64296c.json
[2019-04-02 19:59:53.850400] [0x000011b4] [info] ReadingC:\Users\nilse\AppData\Roaming\Web3\keys\84258fde-b0d9-747e-b70f-f55e14831192.json
[2019-04-02 19:59:53.850400] [0x000011b4] [info] ReadingC:\Users\nilse\AppData\Roaming\Web3\keys\9067d973-1c8d-fa86-a312-14c90188f610.json
Enter a passphrase with which to secure this account:Please confirm the passphrase by entering it again: Created key ab921356-8c9e-54ff-e3e7-da5c2f7aa685
Address: 002c73acd4bc217998966964d27f0ee79a47befb

2. Add each address (these are the public keys generated in the previous step) into the "accounts" section of your chain configuration json file (we'll refer to this as config.json from now on) along with the desired balance in wei.

For example, the following initializes each account created in step 1 with 2 ether:

2. Add each address (these are the public keys generated in the previous step) into the "accounts" section of your chain configuration json file (we'll refer to this as ``config.json`` from now on) along with the desired balance in wei. For example, the following initializes each account created in step 1 with 2 ether:

::

"accounts": {
"0000000000000000000000000000000000000001": { "precompiled": { "name": "ecrecover", "linear": { "base": 3000, "word": 0 } }, "balance": "0x01" },
Expand All @@ -72,22 +79,31 @@ Enter the desired password when prompted
}
}


3. Start the first node (each of the command-line options are explained below):

::

Aleth -m on --config <file> -a <addr> --no-discovery --unsafe-transactions --listen <port>

○ -m on: Enables CPU mining
○ --config: Path to chain configuration json file
○ -a: Sets recipient of mining block reward
○ --no-discovery: Disables the devp2p discovery protocol (it's unnecessary in a 2-node configuration, we'll be adding a peer manually)
○ --unsafe-transactions: Don't require approval before sending each transaction (unnecessary for testing purposes)
* --listen: TCP port to listen for incoming peer connections
-m on Enables CPU mining
--config Path to chain configuration json file
-a Sets recipient of mining block reward
--no-discovery Disables the devp2p discovery protocol (it's unnecessary in a 2-node configuration, we'll be adding a peer manually)
--unsafe-transactions Don't require approval before sending each transaction (unnecessary for testing purposes)
--listen TCP port to listen for incoming peer connections

**Example:**

::

Example:
aleth -m on --config %CODE%\config.json -a 00fd4aaf9713f5bb664c20a462acc4ebc363d1a6 --no-discovery --unsafe-transactions --listen 30303

aleth -m on --config %CODE%\config.json -a 00fd4aaf9713f5bb664c20a462acc4ebc363d1a6 --no-discovery --unsafe-transactions --listen 30303
Make note of the node's enode URL since you'll need to reference it when launching the second node. The enode URL should be logged within the first few lines of log output.

Make note of the node's enode URL since you'll need to reference it when launching the second node. The enode URL should be logged within the first few lines of log output. For example:
**Example:**

::

aleth, a C++ Ethereum client
INFO 04-01 20:34:38 main net Id: ##fb867844…
Expand All @@ -100,8 +116,11 @@ Make note of the node's enode URL since you'll need to reference it when launchi
JSONRPC Admin Session Key: 7BPb1cysJuQ=
INFO 04-01 20:34:40 main client Mining Beneficiary: @00fd4aaf…


If everything goes smoothly you should see the node start mining (empty) blocks after a minute or two:

::

INFO 04-01 20:38:59 main rpc JSON-RPC socket path: \\.\pipe\\geth.ipc
JSONRPC Admin Session Key: 2C/gbvE/pxQ=
INFO 04-01 20:38:59 main client Mining Beneficiary: @00fd4aaf…
Expand All @@ -113,63 +132,85 @@ If everything goes smoothly you should see the node start mining (empty) blocks
INFO 04-01 20:40:39 miner1 client Block sealed #3
INFO 04-01 20:40:39 eth client 1 blocks imported in 3 ms (300.842 blocks/s) in #3

4. Start the second node:

Aleth --config <file> --no-discovery --unsafe-transactions --listen <port> --peerset required:<enode URL> --db-path <path>

Notes:
* --config: You need to specify the same chain config file
§ --listen: You need to specify a different port
§ --peerset: Be sure to update the IP address in the enode URL to 127.0.0.1:<listen port>
* This node won't mine so there's no mining options.
* --db-path: Path to save sync'd blocks. Aleth saves blocks by default to %APPDATA%\Ethereum on Windows and TODO on Linux. You need to specify a different path for your second node otherwise you'll run into database concurrency issues. An example of this error is in the TODO section.

For example:

aleth --config %CODE%\config.json --no-discovery --unsafe-transactions --listen 30305 --db-path %APPDATA%\EthereumPrivate_01 --peerset required:enode://5def584369536c059df3cd86280200beb51829319e4bd1a8bb19df885babe215db30eafa548861b558ae4ac65d546a2d96a5664fade83ba3605c45b6bd88cc51@127.0.0.1:30303

5. If all goes well the second node will connect to the first node and start syncing blocks:

aleth, a C++ Ethereum client
INFO 04-01 20:47:55 main net Id: ##d4a0335d…
aleth 1.6.0-alpha.1-28+commit.32bb833e.dirty
Mining Beneficiary: 84258fde-b0d9-747e-b70f-f55e14831192 - 00fd4aaf9713f5bb664c20a462acc4ebc363d1a6
INFO 04-01 20:47:59 p2p info UPnP device not found.
WARN 04-01 20:47:59 p2p warn "_enabled" parameter is false, discovery is disabled
Node ID: enode://d4a0335d481fe816a7d580a298870066c3c24af60cd1c2875bd2598befedfbd5a43942f41e04f6e92d1081de72843f15ff5fb9c8f65cb31bdce1357514f02491@0.0.0.0:0
INFO 04-01 20:47:59 main rpc JSON-RPC socket path: \\.\pipe\\geth.ipc
JSONRPC Admin Session Key: rtsy5ehS1JA=
INFO 04-01 20:47:59 p2p sync 5def5843…|aleth/1.6.0-alpha.1-28+commit.32bb833e.dirty/windows/msvc19.0.24215.1/debug Starting full sync
INFO 04-01 20:48:01 eth client 26 blocks imported in 177 ms (146.424 blocks/s) in #26
INFO 04-01 20:48:02 eth client 50 blocks imported in 262 ms (190.531 blocks/s) in #76
INFO 04-01 20:48:02 eth client 56 blocks imported in 300 ms (186.602 blocks/s) in #132
INFO 04-01 20:48:02 eth client 59 blocks imported in 265 ms (222.067 blocks/s) in #191

4. Start the second node:

::

aleth --config <file> --no-discovery --unsafe-transactions --listen <port> --peerset required:<enode URL> --db-path <path>


--config You need to specify the same chain config file
--listen You need to specify a different port
--peerset Be sure to update the IP address in the enode URL to ``127.0.0.1:<listen port>``
--db-path Path to save sync'd blocks. Aleth saves blocks by default to ``%APPDATA%\Ethereum`` on Windows and TODO on Linux. You need to specify a different path for your second node otherwise you'll run into database concurrency issues. An example of this error is in the TODO section.


**Example:**

::

aleth --config %CODE%\config.json --no-discovery --unsafe-transactions --listen 30305 --db-path %APPDATA%\EthereumPrivate_01 --peerset required:enode://5def584369536c059df3cd86280200beb51829319e4bd1a8bb19df885babe215db30eafa548861b558ae4ac65d546a2d96a5664fade83ba3605c45b6bd88cc51@127.0.0.1:30303


5. If all goes well the second node will connect to the first node and start syncing blocks:

::

aleth, a C++ Ethereum client
INFO 04-01 20:47:55 main net Id: ##d4a0335d…
aleth 1.6.0-alpha.1-28+commit.32bb833e.dirty
Mining Beneficiary: 84258fde-b0d9-747e-b70f-f55e14831192 - 00fd4aaf9713f5bb664c20a462acc4ebc363d1a6
INFO 04-01 20:47:59 p2p info UPnP device not found.
WARN 04-01 20:47:59 p2p warn "_enabled" parameter is false, discovery is disabled
Node ID: enode://d4a0335d481fe816a7d580a298870066c3c24af60cd1c2875bd2598befedfbd5a43942f41e04f6e92d1081de72843f15ff5fb9c8f65cb31bdce1357514f02491@0.0.0.0:0
INFO 04-01 20:47:59 main rpc JSON-RPC socket path: \\.\pipe\\geth.ipc
JSONRPC Admin Session Key: rtsy5ehS1JA=
INFO 04-01 20:47:59 p2p sync 5def5843…|aleth/1.6.0-alpha.1-28+commit.32bb833e.dirty/windows/msvc19.0.24215.1/debug Starting full sync
INFO 04-01 20:48:01 eth client 26 blocks imported in 177 ms (146.424 blocks/s) in #26
INFO 04-01 20:48:02 eth client 50 blocks imported in 262 ms (190.531 blocks/s) in #76
INFO 04-01 20:48:02 eth client 56 blocks imported in 300 ms (186.602 blocks/s) in #132
INFO 04-01 20:48:02 eth client 59 blocks imported in 265 ms (222.067 blocks/s) in #191


Common Problems
===============
"Unrecognized peerset" error
Example:
Unrecognized peerset: required:enode://5def584369536c059df3cd86280200beb51829319e4bd1a8bb19df885babe215db30eafa548861b558ae4ac65d546a2d96a5664fade83ba3605c45b6bd88cc51@0.0.0.0:0
``Unrecognized peerset`` error
---------------------------------
**Example:**

::

Unrecognized peerset: required:enode://5def584369536c059df3cd86280200beb51829319e4bd1a8bb19df885babe215db30eafa548861b558ae4ac65d546a2d96a5664fade83ba3605c45b6bd88cc51@0.0.0.0:0


You need to update the IP address in the enode URL to 127.0.0.1:<port> where <port> is the port number you supplied to node 1 via --listen

"Database already open" error
Example:
aleth, a C++ Ethereum client
INFO 04-01 20:50:31 main net Id: ##a7dbe409…
WARN 04-01 20:50:31 main warn Database "C:\Users\nilse\AppData\Roaming\EthereumPrivate_00\ddce0f53\blocks"or "C:\Users\nilse\AppData\Roaming\EthereumPrivate_00\ddce0f53\12041\extras"already open. You appear to have another instance of ethereum running. Bailing.
``Database already open`` error
-------------------------------
**Example:**

::

aleth, a C++ Ethereum client
INFO 04-01 20:50:31 main net Id: ##a7dbe409…
WARN 04-01 20:50:31 main warn Database "C:\Users\nilse\AppData\Roaming\EthereumPrivate_00\ddce0f53\blocks"or "C:\Users\nilse\AppData\Roaming\EthereumPrivate_00\ddce0f53\12041\extras"already open. You appear to have another instance of ethereum running. Bailing.


Both of your Aleth nodes are trying to use the same database location. You need to set one of your nodes' database path (--db-path) to a different location.


Node 2 doesn't sync with node 1
-------------------------------
Example:
TODO:

This means that node 2 couldn't successfully peer with node 1. This typically happens because you used a different chain config file for each node. You can enable verbose logging on node 1 (-v4 --log-channels net sync) to get helpful logs for debugging.
This means that node 2 couldn't successfully peer with node 1. This typically happens because you used a different chain config file for each node. You can enable verbose logging on node 1 (``-v4 --log-channels net sync``) to get helpful logs for debugging.

For example, here are the node 1 logs when node 1 and node 2 use different chain configuration files:

::

TRACE 04-01 20:57:53 p2p net p2p.connect.ingress receiving auth from 127.0.0.1:61309
TRACE 04-01 20:57:53 p2p net Listening on local port 30303
TRACE 04-01 20:57:53 p2p net p2p.connect.ingress sending ack to 127.0.0.1:61309
Expand Down Expand Up @@ -203,8 +244,12 @@ For example, here are the node 1 logs when node 1 and node 2 use different chain
DEBUG 04-01 20:57:58 p2p net 8b7b78e1…|aleth/1.6.0-alpha.1-28+commit.32bb833e.dirty/windows/msvc19.0.24215.1/debug Closing peer session :-(


"Couldn't start accepting connections on host. Failed to accept socket on <IP address>" error
Example:
``Couldn't start accepting connections on host. Failed to accept socket on <IP address>`` error
--------------------------------------------------------------------------------------------------
**Example:**

::

aleth, a C++ Ethereum client
INFO 04-01 21:01:18 main net Id: ##ac459be1…
aleth 1.6.0-alpha.1-28+commit.32bb833e.dirty
Expand All @@ -217,5 +262,6 @@ Example:
INFO 04-01 21:01:20 p2p info UPnP device not found.
WARN 04-01 21:01:20 p2p warn "_enabled" parameter is false, discovery is disabled

This means that you're running both nodes on the same listen port. Be sure to specify different ports via --listen.

You're running both nodes on the same listen port. Be sure to specify different ports via ``--listen``.