Networking

There are 2 networking modules: Simple Network and P2P Network.

Simple Network

Used for testing (eg running multiple clusters on a single machine), or in a controlled environment where number of clusters is limited.

Each cluster queries bootstrap for connected peers and connects to all of them, forming a fully connected network.

P2P Network

Discovery is more complex and robust - the discovery protocol forms a Kademlia-like network. The network layer tries to maintain up to max_peer number of connections. The implementation is heavily based on py-evm's p2p module.

A huge difference from simple network is all traffic is encrypted.

Note there is a legacy p2p module based on pydevp2p (which is no longer being maintained), and it is being phased out or completely removed.

Commandline Flags Explained

--p2p

turns on p2p module, otherwise simple network is used

--max_peers

after this number of peers are connected, refuse more connections note that nodes will only dial out to a portion of this number, to keep connections available for incoming requests.

--bootnodes

Comma separated enodes in the format: enode://PUBKEY@IP:PORT

if there is no bootnodes, the p2p module will NOT be able to connect to other peers

example: --bootnodes=enode://c571e0db93d17cc405cb57640826b70588a6a28785f38b21be471c609ca12fcb06cb306ac44872908f5bed99046031a5af82072d484e3ef9029560c1707193a0@127.0.0.1:38291

--upnp

turns on upnp module which automatically searches for router that supports upnp and setup appropriate port forwarding using upnp protocol

NOTE this is not needed if you are running the cluster on a machine with public IP address

If you are on a private network (eg running QuarkChain cluster from a laptop which connects to a router and then internet), your can:

1. run with --upnp to set up the port forwarding automatically, but there are chances that your router does not support upnp

2. setup port forwarding manually according to the router's instructions, you will need access to the router control. Like ethereum, QuarkChain requires a UDP port for node discovery and a TCP port for peer connections, normally they would be the same port number

NOTE if you run QuarkChain on AWS, you don't need this, because AWS assigns public IP to its instances. However you do need to allow traffic to the port in security group settings, and both TCP and UDP need to be open

--privkey

This is the private key for identifying nodes in the discovery protocol and for encrypting communications between peers. The best practice is to generate one and keep it at a safe place. Run the following command to generate one:

python quarkchain/tools/newkey.py

If you leave this empty, a random privkey will be generated, but will be different each time your node is rebooted, and other nodes will think that you are a new node that just joined the network.