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

Commit ba3f45a

Browse files
halfalicioushalfalicious
authored
Documentation for creating a private network with 2 nodes (#5546)
Author documentation for creating a private network with 2 nodes
1 parent 7f2a79a commit ba3f45a

File tree

3 files changed

+307
-1
lines changed

3 files changed

+307
-1
lines changed

‎doc/index.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,5 @@ Internal documentation
55
2. `Database Layout <database_layout.rst>`_
66
3. `Generating Consensus Tests <generating_tests.rst>`_
77
4. `Using snapshot sync <snapshot_sync.rst>`_
8-
5. `Creating a private network and deploying a contract with Remix <private_net.rst>`_
8+
5. `Creating a single-node private network and deploying a contract with Remix <private_net_remix.rst>`_
9+
6. `Creating a private network with two syncing nodes <private_net_sync.rst>`_

doc/private_net.rst renamed to doc/private_net_remix.rst

File renamed without changes.

‎doc/private_net_sync.rst‎

Lines changed: 305 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,305 @@
1+
Creating A Private Network With Two Syncing Nodes
2+
==================================================
3+
These instructions cover creating an Ethereum private network consisting of two nodes - one 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 run a private chain configuration.
4+
5+
6+
What is a Private Network?
7+
--------------------------
8+
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.
9+
10+
What is a Private Chain?
11+
-------------------------
12+
An Ethereum chain is some state (e.g. accounts and balances and/or contract code) and a set of rules for interacting with that state. **Private chain** is used in this documentation to refer to an Ethereum chain whose configuration is only available on your physical machine.
13+
14+
Mining
15+
------
16+
- Mining will be done using the Aleth CPU miner (Aleth doesn't include a GPU miner because of the high maintenance and support costs. Please see `EthMiner <https://github.com/ethereum-mining/ethminer>`_ for GPU mining support).
17+
- We will only start mining for one node to keep your machine responsive.
18+
- If mining slows down your system too much or you'd like to have both nodes mine, you can tune the number of mining threads via ``-t <thread count>``.
19+
20+
Chain Configuration
21+
-------------------
22+
- You typically initialize a private chain using a chain configuration json file (this isn't strictly required, but it makes testing easier since you can do things like lower the difficulty rate and pre-fund addresses).
23+
- Here's an example file:
24+
25+
::
26+
27+
{
28+
"sealEngine": "Ethash",
29+
"params": {
30+
"accountStartNonce": "0x00",
31+
"maximumExtraDataSize": "0x20",
32+
"homesteadForkBlock": "0x00",
33+
"EIP150ForkBlock": "0x00",
34+
"EIP158ForkBlock": "0x00",
35+
"byzantiumForkBlock": "0x00",
36+
"constantinopleForkBlock": "0x00",
37+
"constantinopleFixForkBlock": "0x00",
38+
"minGasLimit": "0x5208",
39+
"maxGasLimit": "0x7fffffffffffffff",
40+
"tieBreakingGas": false,
41+
"gasLimitBoundDivisor": "0x0400",
42+
"minimumDifficulty": "0x100000",
43+
"difficultyBoundDivisor": "0x0800",
44+
"durationLimit": "0x0d",
45+
"blockReward": "0x4563918244F40000",
46+
"networkID" : "0x42",
47+
"chainID": "0x42",
48+
"allowFutureBlocks" : false
49+
},
50+
"genesis": {
51+
"nonce": "0x0000000000000042",
52+
"difficulty": "0x100000",
53+
"mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
54+
"author": "0x0000000000000000000000000000000000000000",
55+
"timestamp": "0x5A5B92D7",
56+
"parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
57+
"extraData": "0x655741534d2074657374206e6574776f726b2030",
58+
"gasLimit": "0x989680"
59+
},
60+
"accounts": {
61+
"0000000000000000000000000000000000000001": { "precompiled": { "name": "ecrecover", "linear": { "base": 3000, "word": 0 } }, "balance": "0x01" },
62+
"0000000000000000000000000000000000000002": { "precompiled": { "name": "sha256", "linear": { "base": 60, "word": 12 } }, "balance": "0x01" },
63+
"0000000000000000000000000000000000000003": { "precompiled": { "name": "ripemd160", "linear": { "base": 600, "word": 120 } }, "balance": "0x01" },
64+
"0000000000000000000000000000000000000004": { "precompiled": { "name": "identity", "linear": { "base": 15, "word": 3 } }, "balance": "0x01" },
65+
"0000000000000000000000000000000000000005": { "precompiled": { "name": "modexp" }, "balance": "0x01" },
66+
"0000000000000000000000000000000000000006": { "precompiled": { "name": "alt_bn128_G1_add", "linear": { "base": 500, "word": 0 } }, "balance": "0x01" },
67+
"0000000000000000000000000000000000000007": { "precompiled": { "name": "alt_bn128_G1_mul", "linear": { "base": 40000, "word": 0 } }, "balance": "0x01" },
68+
"0000000000000000000000000000000000000008": { "precompiled": { "name": "alt_bn128_pairing_product" }, "balance": "0x01" },
69+
"00fd4aaf9713f5bb664c20a462acc4ebc363d1a6": { "balance" : "0x200000000000000000000000000000000000000000000000000000000000000" },
70+
"004d5baf9ab6a9c29c73725ec35023e330af2bc8": { "balance" : "0x200000000000000000000000000000000000000000000000000000000000000" }
71+
}
72+
}
73+
74+
- **Both nodes must use the same chain configuration file:** The chain configuration is used to create the chain's genesis state, so using a different configuration for each node means that they won't be able to peer with each other. An example of this is shown in the `Common Problems`_ section.
75+
76+
Instructions
77+
============
78+
*The output in this section was generated on Windows 10 running aleth 1.6.0-alpha.1-31+commit.ad7204c9*
79+
80+
1. Create a key pair for each node:
81+
82+
::
83+
84+
aleth.exe account new
85+
86+
87+
Enter the desired password when prompted
88+
89+
**Example:**
90+
::
91+
92+
aleth account new
93+
[2019-04-02 19:59:42.515684] [0x000041f0] [info] ReadingC:\Users\nilse\AppData\Roaming\Web3\keys\4f04a5ed-87e4-1e4d-4367-604db42bdcff.json
94+
[2019-04-02 19:59:42.520265] [0x000041f0] [info] ReadingC:\Users\nilse\AppData\Roaming\Web3\keys\84258fde-b0d9-747e-b70f-f55e14831192.json
95+
[2019-04-02 19:59:42.520265] [0x000041f0] [info] ReadingC:\Users\nilse\AppData\Roaming\Web3\keys\9067d973-1c8d-fa86-a312-14c90188f610.json
96+
Enter a passphrase with which to secure this account:Please confirm the passphrase by entering it again: Created key 623b80dd-d008-4cd4-dd06-c36f0f64296c
97+
Address: 007e13502a8b226b0f19e7412db75352dc1d0760
98+
99+
aleth account new
100+
[2019-04-02 19:59:53.847216] [0x000011b4] [info] ReadingC:\Users\nilse\AppData\Roaming\Web3\keys\4f04a5ed-87e4-1e4d-4367-604db42bdcff.json
101+
[2019-04-02 19:59:53.849343] [0x000011b4] [info] ReadingC:\Users\nilse\AppData\Roaming\Web3\keys\623b80dd-d008-4cd4-dd06-c36f0f64296c.json
102+
[2019-04-02 19:59:53.850400] [0x000011b4] [info] ReadingC:\Users\nilse\AppData\Roaming\Web3\keys\84258fde-b0d9-747e-b70f-f55e14831192.json
103+
[2019-04-02 19:59:53.850400] [0x000011b4] [info] ReadingC:\Users\nilse\AppData\Roaming\Web3\keys\9067d973-1c8d-fa86-a312-14c90188f610.json
104+
Enter a passphrase with which to secure this account:Please confirm the passphrase by entering it again: Created key ab921356-8c9e-54ff-e3e7-da5c2f7aa685
105+
Address: 002c73acd4bc217998966964d27f0ee79a47befb
106+
107+
108+
2. Add each address generated in the previous step to the ``accounts`` section of your chain configuration file (we'll refer to this as ``config.json``) along with the desired balance in wei. For example, the following initializes each account with 2 ether (2000000000000000000 wei):
109+
110+
::
111+
112+
"accounts": {
113+
"0000000000000000000000000000000000000001": { "precompiled": { "name": "ecrecover", "linear": { "base": 3000, "word": 0 } }, "balance": "0x01" },
114+
"0000000000000000000000000000000000000002": { "precompiled": { "name": "sha256", "linear": { "base": 60, "word": 12 } }, "balance": "0x01" },
115+
"0000000000000000000000000000000000000003": { "precompiled": { "name": "ripemd160", "linear": { "base": 600, "word": 120 } }, "balance": "0x01" },
116+
"0000000000000000000000000000000000000004": { "precompiled": { "name": "identity", "linear": { "base": 15, "word": 3 } }, "balance": "0x01" },
117+
"0000000000000000000000000000000000000005": { "precompiled": { "name": "modexp" }, "balance": "0x01" },
118+
"0000000000000000000000000000000000000006": { "precompiled": { "name": "alt_bn128_G1_add", "linear": { "base": 500, "word": 0 } }, "balance": "0x01" },
119+
"0000000000000000000000000000000000000007": { "precompiled": { "name": "alt_bn128_G1_mul", "linear": { "base": 40000, "word": 0 } }, "balance": "0x01" },
120+
"0000000000000000000000000000000000000008": { "precompiled": { "name": "alt_bn128_pairing_product" }, "balance": "0x01" },
121+
"007e13502a8b226b0f19e7412db75352dc1d0760": {
122+
"balance" : "2000000000000000000"
123+
},
124+
"002c73acd4bc217998966964d27f0ee79a47befb": {
125+
"balance" : "2000000000000000000"
126+
}
127+
}
128+
129+
130+
3. Start the first node:
131+
132+
::
133+
134+
aleth -m on --config <file> -a <addr> --no-discovery --unsafe-transactions --listen <port>
135+
136+
-m on Enable CPU mining
137+
--config Set chain configuration
138+
-a Set recipient of mining block reward
139+
--no-discovery Disable devp2p discovery protocol (it's unnecessary in a two-node network, we'll be adding a peer manually)
140+
--unsafe-transactions Don't require approval before sending each transaction (unnecessary for testing purposes)
141+
--listen Set TCP port to listen on for incoming peer connections
142+
143+
144+
**Example:**
145+
146+
::
147+
148+
aleth -m on --config config.json -a 00fd4aaf9713f5bb664c20a462acc4ebc363d1a6 --no-discovery --unsafe-transactions --listen 30303
149+
150+
151+
Make note of the node's URL (which starts with ``enode://``) since you'll need to supply it when starting the second node. The URL should be logged within the first few lines of console output.
152+
153+
**Example:**
154+
155+
::
156+
157+
aleth, a C++ Ethereum client
158+
INFO 04-01 20:34:38 main net Id: ##fb867844…
159+
aleth 1.6.0-alpha.1-28+commit.32bb833e.dirty
160+
Mining Beneficiary: 84258fde-b0d9-747e-b70f-f55e14831192 - 00fd4aaf9713f5bb664c20a462acc4ebc363d1a6
161+
INFO 04-01 20:34:40 p2p info UPnP device not found.
162+
WARN 04-01 20:34:40 p2p warn "_enabled" parameter is false, discovery is disabled
163+
Node ID: enode://fb867844056920bbf0dd0945faff8a7a249d33726786ec367461a6c023cae62d7b2bb725a07e2f9832eb05be89e71cf81acf22022215b51a561929c37419531a@0.0.0.0:0
164+
165+
166+
The node should start mining blocks after a minute or two:
167+
168+
::
169+
170+
INFO 04-01 20:38:59 main rpc JSON-RPC socket path: \\.\pipe\\geth.ipc
171+
JSONRPC Admin Session Key: 2C/gbvE/pxQ=
172+
INFO 04-01 20:38:59 main client Mining Beneficiary: @00fd4aaf…
173+
INFO 04-01 20:40:36 miner2 client Block sealed #1
174+
INFO 04-01 20:40:36 eth client Tried to seal sealed block...
175+
INFO 04-01 20:40:36 eth client 1 blocks imported in 1 ms (515.198 blocks/s) in #1
176+
INFO 04-01 20:40:37 miner0 client Block sealed #2
177+
INFO 04-01 20:40:37 eth client 1 blocks imported in 3 ms (316.056 blocks/s) in #2
178+
INFO 04-01 20:40:39 miner1 client Block sealed #3
179+
INFO 04-01 20:40:39 eth client 1 blocks imported in 3 ms (300.842 blocks/s) in #3
180+
181+
182+
4. Start the second node:
183+
184+
::
185+
186+
aleth --config <file> --no-discovery --unsafe-transactions --listen <port> --peerset required:<url> --db-path <path>
187+
188+
--config Specify the same chain config file
189+
--listen Specify a different port
190+
--peerset Update the IP address in the node URL to ``127.0.0.1:<listen port>``
191+
--db-path Path to save sync'd blocks. Aleth saves blocks by default to ``%APPDATA%\Ethereum`` on Windows and ``$HOME/.ethereum`` on Linux. You need to specify a different path for your second node otherwise you'll run into database access issues. See the `Common Problems`_ section for an example of this error.
192+
193+
194+
**Example:**
195+
196+
::
197+
198+
aleth --config config.json --no-discovery --unsafe-transactions --listen 30305 --db-path %APPDATA%\EthereumPrivate_01 --peerset required:enode://fb867844056920bbf0dd0945faff8a7a249d33726786ec367461a6c023cae62d7b2bb725a07e2f9832eb05be89e71cf81acf22022215b51a561929c37419531a@127.0.0.1:30303
199+
200+
201+
5. The node should connect to the first node and start syncing blocks:
202+
203+
::
204+
205+
aleth, a C++ Ethereum client
206+
INFO 04-01 20:47:55 main net Id: ##d4a0335d…
207+
aleth 1.6.0-alpha.1-28+commit.32bb833e.dirty
208+
Mining Beneficiary: 84258fde-b0d9-747e-b70f-f55e14831192 - 00fd4aaf9713f5bb664c20a462acc4ebc363d1a6
209+
INFO 04-01 20:47:59 p2p info UPnP device not found.
210+
WARN 04-01 20:47:59 p2p warn "_enabled" parameter is false, discovery is disabled
211+
Node ID: enode://d4a0335d481fe816a7d580a298870066c3c24af60cd1c2875bd2598befedfbd5a43942f41e04f6e92d1081de72843f15ff5fb9c8f65cb31bdce1357514f02491@0.0.0.0:0
212+
INFO 04-01 20:47:59 main rpc JSON-RPC socket path: \\.\pipe\\geth.ipc
213+
JSONRPC Admin Session Key: rtsy5ehS1JA=
214+
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
215+
INFO 04-01 20:48:01 eth client 26 blocks imported in 177 ms (146.424 blocks/s) in #26
216+
INFO 04-01 20:48:02 eth client 50 blocks imported in 262 ms (190.531 blocks/s) in #76
217+
INFO 04-01 20:48:02 eth client 56 blocks imported in 300 ms (186.602 blocks/s) in #132
218+
INFO 04-01 20:48:02 eth client 59 blocks imported in 265 ms (222.067 blocks/s) in #191
219+
220+
221+
Common Problems
222+
===============
223+
"Unrecognized peerset" error
224+
---------------------------------
225+
**Example:**
226+
227+
::
228+
229+
Unrecognized peerset: required:enode://5def584369536c059df3cd86280200beb51829319e4bd1a8bb19df885babe215db30eafa548861b558ae4ac65d546a2d96a5664fade83ba3605c45b6bd88cc51@0.0.0.0:0
230+
231+
232+
Your ``peerset`` string is formatted incorrectly. You probably need to update the IP address in the node URL to ``127.0.0.1:<port>``, where ``<port>`` is the port number you supplied to node 1 via ``--listen``.
233+
234+
"Database already open" error
235+
-------------------------------
236+
**Example:**
237+
238+
::
239+
240+
aleth, a C++ Ethereum client
241+
INFO 04-01 20:50:31 main net Id: ##a7dbe409…
242+
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.
243+
244+
245+
Both of your Aleth nodes are trying to use the same location for their block databases. Set one of your nodes' database paths to a different location (``--db-path``).
246+
247+
248+
Node 2 doesn't sync with node 1
249+
-------------------------------
250+
This means that node 2 couldn't successfully peer with node 1. A possible reason for this when running a private network is using a different chain config for each node. To see if this is the issue, enable verbose logging on node 1 (``-v4 --log-channels net sync``) to get helpful logs for debugging.
251+
252+
**Example**: Here are the node 1 logs when node 1 and node 2 use different chain configuration files (note the ``Peer not suitable for sync: Invalid genesis hash.`` error):
253+
254+
::
255+
256+
TRACE 04-01 20:57:53 p2p net p2p.connect.ingress receiving auth from 127.0.0.1:61309
257+
TRACE 04-01 20:57:53 p2p net Listening on local port 30303
258+
TRACE 04-01 20:57:53 p2p net p2p.connect.ingress sending ack to 127.0.0.1:61309
259+
TRACE 04-01 20:57:53 p2p net p2p.connect.ingress sending capabilities handshake
260+
TRACE 04-01 20:57:53 p2p net p2p.connect.ingress recvd hello header
261+
TRACE 04-01 20:57:53 p2p net p2p.connect.ingress hello frame: success. starting session.
262+
DEBUG 04-01 20:57:53 p2p net Hello: aleth/1.6.0-alpha.1-28+commit.32bb833e.dirty/windows/msvc19.0.24215.1/debug V[4] ##8b7b78e1… (eth,63) 30305
263+
DEBUG 04-01 20:57:53 p2p net New session for capability eth; idOffset: 16
264+
TRACE 04-01 20:57:53 p2p net <- [ 0x3F, 0x42, 0x179D6F06, 0x9A610A1C26FFF584E79421406D77ABF46E9FDE72E11D2F6E8B880D3F5E84EDE8, 0xDDCE0F53ABB8348FDF758C4DABBD9C0A7BBD359CBE6E74AC60A2F12F6B9BAA74 ]
265+
TRACE 04-01 20:57:53 p2p net <- [ ]
266+
DEBUG 04-01 20:57:53 p2p net p2p.host.peer.register ##8b7b78e1…
267+
TRACE 04-01 20:57:53 p2p net 8b7b78e1…|aleth/1.6.0-alpha.1-28+commit.32bb833e.dirty/windows/msvc19.0.24215.1/debug Error reading: An established connection was aborted by the software in your host machine
268+
TRACE 04-01 20:57:53 p2p net 8b7b78e1…|aleth/1.6.0-alpha.1-28+commit.32bb833e.dirty/windows/msvc19.0.24215.1/debug Closing 127.0.0.1:61309 (Low-level TCP communication error.)
269+
DEBUG 04-01 20:57:53 p2p net 8b7b78e1…|aleth/1.6.0-alpha.1-28+commit.32bb833e.dirty/windows/msvc19.0.24215.1/debug Closing peer session :-(
270+
TRACE 04-01 20:57:58 p2p net p2p.connect.ingress receiving auth from 127.0.0.1:61323
271+
TRACE 04-01 20:57:58 p2p net Listening on local port 30303
272+
TRACE 04-01 20:57:58 p2p net p2p.connect.ingress sending ack to 127.0.0.1:61323
273+
TRACE 04-01 20:57:58 p2p net p2p.connect.ingress sending capabilities handshake
274+
TRACE 04-01 20:57:58 p2p net p2p.connect.ingress recvd hello header
275+
TRACE 04-01 20:57:58 p2p net p2p.connect.ingress hello frame: success. starting session.
276+
DEBUG 04-01 20:57:58 p2p net Hello: aleth/1.6.0-alpha.1-28+commit.32bb833e.dirty/windows/msvc19.0.24215.1/debug V[4] ##8b7b78e1… (eth,63) 30305
277+
DEBUG 04-01 20:57:58 p2p net New session for capability eth; idOffset: 16
278+
TRACE 04-01 20:57:58 p2p net <- [ 0x3F, 0x42, 0x179D6F06, 0x9A610A1C26FFF584E79421406D77ABF46E9FDE72E11D2F6E8B880D3F5E84EDE8, 0xDDCE0F53ABB8348FDF758C4DABBD9C0A7BBD359CBE6E74AC60A2F12F6B9BAA74 ]
279+
TRACE 04-01 20:57:58 p2p net <- [ ]
280+
DEBUG 04-01 20:57:58 p2p net p2p.host.peer.register ##8b7b78e1…
281+
TRACE 04-01 20:57:58 p2p net 8b7b78e1…|aleth/1.6.0-alpha.1-28+commit.32bb833e.dirty/windows/msvc19.0.24215.1/debug -> 16 [ 0x3F, 0x42, 0x100000, 0xD8600904A41043A4E81D23863F178E7DC8B3C2CBAFA94EB4BBF5DC46BCCCE176, 0xD8600904A41043A4E81D23863F178E7DC8B3C2CBAFA94EB4BBF5DC46BCCCE176 ]
282+
DEBUG 04-01 20:57:58 p2p sync 8b7b78e1…|aleth/1.6.0-alpha.1-28+commit.32bb833e.dirty/windows/msvc19.0.24215.1/debug Peer not suitable for sync: Invalid genesis hash.
283+
TRACE 04-01 20:57:58 p2p net 8b7b78e1…|aleth/1.6.0-alpha.1-28+commit.32bb833e.dirty/windows/msvc19.0.24215.1/debug Disconnecting (our reason: Subprotocol reason.)
284+
TRACE 04-01 20:57:58 p2p net 8b7b78e1…|aleth/1.6.0-alpha.1-28+commit.32bb833e.dirty/windows/msvc19.0.24215.1/debug <- [ 0x10 ]
285+
TRACE 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 127.0.0.1:61323 (Subprotocol reason.)
286+
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 :-(
287+
288+
289+
"Couldn't start accepting connections on host. Failed to accept socket on <IP address>" error
290+
--------------------------------------------------------------------------------------------------
291+
**Example:**
292+
293+
::
294+
295+
aleth, a C++ Ethereum client
296+
INFO 04-01 21:01:18 main net Id: ##ac459be1…
297+
aleth 1.6.0-alpha.1-28+commit.32bb833e.dirty
298+
Mining Beneficiary: 84258fde-b0d9-747e-b70f-f55e14831192 - 00fd4aaf9713f5bb664c20a462acc4ebc363d1a6
299+
WARN 04-01 21:01:20 p2p warn Couldn't start accepting connections on host. Failed to accept socket on 0.0.0.0:30303.
300+
Throw location unknown (consider using BOOST_THROW_EXCEPTION)
301+
Dynamic exception type: class boost::exception_detail::clone_impl<struct boost::exception_detail::error_info_injector<class boost::system::system_error> >
302+
std::exception::what: bind: Only one usage of each socket address (protocol/network address/port) is normally permitted
303+
304+
You're running both nodes on the same listen port. Specify different ports when launching each node via ``--listen``.
305+

0 commit comments

Comments
 (0)