Prerequisites
To follow the tutorial on this page it is necessary to have a working Parallax client installation (instructions here). It is also helpful to understand the Parallax client fundamentals (see Getting Started).Private Networks
A private network is composed of multiple Parallax nodes that can only connect to each other. In order to run multiple nodes locally, each one requires a separate data directory (--datadir). The nodes must also know about each other and be able to exchange information, share an initial state and a common consensus algorithm. The remainder of this page will explain how to configure the Parallax client so that these basic requirements are met, enabling a private network to be started.
Choosing A Network ID
The Parallax mainnet has Network ID = 2110. There are also many other networks that the Parallax client can connect to by providing alternative Chain IDs, some are testnets and others are alternative networks built from forks of the Parallax client source code. Providing a network ID that is not already being used by an existing network or testnet means the nodes using that network ID can only connect to each other, creating a private network. A list of current network IDs is available at Chainlist.org. The network ID is controlled using thenetworkid flag, e.g.
Choosing A Consensus Algorithm
XHash
Parallax’s PoW algorithm, XHash, is a system that allows open participation by anyone willing to dedicate resources to mining. While this is a critical property for a public network, the overall security of the blockchain strictly depends on the total amount of resources used to secure it. As such, PoW is a poor choice for private networks with few miners. The XHash mining ‘difficulty’ is adjusted automatically so that new blocks are created approximately 12 seconds apart. As more mining resources are deployed on the network, creating a new block becomes harder so that the average block time matches the target block time.Clique
Clique consensus is a PoA system where new blocks can be created by authorized ‘signers’ only. The clique consensus protocol is specified in EIP-225. The initial set of authorized signers is configured in the genesis block. Signers can be authorized and de-authorized using a voting mechanism, thus allowing the set of signers to change while the blockchain operates. Clique can be configured to target any block time (within reasonable limits) since it isn’t tied to the difficulty adjustment.Creating The Genesis Block
Every blockchain starts with a genesis block. When the Parallax client is run with default settings for the first time, it commits the Mainnet genesis to the database. For a private network, it is generally preferable to use a different genesis block. The genesis block is configured using agenesis.json file whose path must be provided to the Parallax client on start-up. When creating a genesis block, a few initial parameters for the private blockchain must be defined:
- Parallax platform features enabled at launch (config). Enabling and disabling features once the blockchain is running requires scheduling a hard fork.
- Initial block gas limit (gasLimit). This impacts how much EVM computation can happen within a single block. Mirroring the main Parallax network is generally a good choice. The block gas limit can be adjusted after launch using the
--miner.gastargetcommand-line flag. - Initial allocation of LAX (alloc). This determines how much Laxes is available to the addresses listed in the genesis block. Additional Laxes can be created through mining as the chain progresses.
Clique Example
Below is an example of agenesis.json file for a PoA network. The config section ensures that all known protocol changes are available and configures the ‘clique’ engine to be used for consensus. Note that the initial signer set must be configured through the extradata field. This field is required for Clique to work.
The signer account keys can be generated using the Parallax account command (this command can be run multiple times to create more than one signer key).
extradata, concatenate 32 zero bytes, all signer addresses and 65 further zero bytes. The result of this concatenation is then used as the value accompanying the extradata key in genesis.json. In the example below, extradata contains a single initial signer address, 0x7df9a875a174b3bc565e6424a0050ebc1b2d1d82.
The period configuration option sets the target block time of the chain.
XHash Example
Since XHash is the default consensus algorithm, no additional parameters need to be configured in order to use it. The initial mining difficulty is influenced using the difficulty parameter, but note that the difficulty adjustment algorithm will quickly adapt to the amount of mining resources deployed on the chain.Initialising the Parallax Client Database
To create a blockchain node that uses this genesis block, first useprlx init to import and sets the canonical genesis block for the new chain. This requires the path to genesis.json to be passed as an argument.
--datadir data the genesis block defined in genesis.json will be used. For example:
Scheduling Hard Forks
As the Parallax protocol development progresses, new features become available. To enable these features on an existing private network, a hard fork must be scheduled. To do this, a future block number must be chosen which determines precisely when the hard fork will activate. Continuing thegenesis.json example above and assuming the current block number is 35421, a hard fork might be scheduled for block 40000. This hard fork might upgrade the network to conform to the ‘London’ specs. First, all the Parallax client instances on the private network must be recent enough to support the specific hard fork. If so, genesis.json can be updated so that the londonBlock key gets the value 40000. The Parallax client instances are then shut down and prlx init is run to update their configuration. When the nodes are restarted they will pick up where they left off and run normally until block 40000, at which point they will automatically upgrade.
The modification to genesis.json is as follows:
Setting Up Networking
With the node configured and initialised, the next step is to set up a peer-to-peer network. This requires a bootstrap node. The bootstrap node is a normal node that is designated to be the entry point that other nodes use to join the network. Any node can be chosen to be the bootstrap node. To configure a bootstrap node, the IP address of the machine the bootstrap node will run on must be known. The bootstrap node needs to know its own IP address so that it can broadcast it to other nodes. On a local machine this can be found using tools such asifconfig and on cloud instances such as Amazon EC2 the IP address of the virtual machine can be found in the management console. Any firewalls must allow UDP and TCP traffic on port 32110.
The bootstrap node IP is set using the --nat flag (the command below contains an example address - replace it with the correct one).
--netrestrict flag to configure a whitelist of IP networks:
Running Member Nodes
Before running a member node, it must be initialized with the same genesis file as used for the bootstrap node. With the bootnode operational and externally reachable (telnet <ip> <port> will confirm that it is indeed reachable), more Parallax nodes can be started and connected to them via the bootstrap node using the --bootnodes flag. The process is to start the Parallax client on the same machine as the bootnode, with a separate data directory and listening port and the bootnode node record provided as an argument:
For example, using data directory (example: data2) and listening port (example: 30305):
admin.peers. It may take up to a few seconds for the nodes to get connected.
Running A Signer (Clique)
To set up the Parallax client for signing blocks in Clique, a signer account must be available. The account must already be available as a keyfile in the keystore. To use it for signing blocks, it must be unlocked. The following command, for address0x7df9a875a174b3bc565e6424a0050ebc1b2d1d82 will prompt for the account password, then start signing blocks:
--miner.gastarget) and the price transactions are accepted at (with --miner.gasprice).
Running A Miner (XHash)
For PoW in a simple private network, a single CPU miner instance is enough to create a stable stream of blocks at regular intervals. To start a Parallax client instance for mining, it can be run with all the usual flags plus the following to configure mining:--miner.etherbase.
End-to-end example
This section will run through the commands for setting up a simple private network of two nodes. Both nodes will run on the local machine using the same genesis block and network ID. The data directories for each node will be named node1 and node2.keystore directory in node1 and node2 data directories. In order to unlock the accounts later the passwords for each account should be saved to a text file in each node’s data directory.
In each data directory save a copy of the following genesis.json to the top level project directory. The account addresses in the alloc field should be replaced with those created for each node in the previous step (without the leading 0x).
prlx init as follows:
bootnode will be used to quickly and easily configure a dedicated bootnode. First the bootnode requires a key, which can be created with the following command, which will save a key to boot.key:
-addr is arbitrary, but public Parallax networks use 32110, so this is best avoided. The bootnode command returns the following logs to the terminal, confirming that it is running:
node1 with node2 where appropriate, and giving each node different --port and authrpc.port IDs). The account address and password file for node 1 must also be provided:
eth.getBalance():