Please refer to the installation method more applicable to you.

Our recommendation is to use the pre-built releases and verify the provided checksums.

Building from source

Prior to using go install make sure that you have Go >=1.17 installed and properly configured.

The stable branch is develop.

Copy

git clone https://github.com/ZChain-168168/ZChain-Blockchain/polygon-edge.git
cd polygon-edge/
go build main.go -o polygon-edge
sudo mv polygon-edge /usr/local/bin

Using go install

Prior to using go install make sure that you have Go >=1.17 installed and properly configured.

go install github.com/ZChain-168168/ZChain-Blockchain/polygon-edge@develop

The binary will be available in your GOBIN environment variable, and will include the latest changes from the mainline develop branch.

Genesis files

Test-net and Main-net file in: https://github.com/ZChain-168168/ZChain-Blockchain

:::info This guide is for mainnet or testnet setups

The below guide will instruct you on how to set up a ZChains network on a cloud provider for a production setup of your testnet or mainnet.

If you would like to setup a ZChains network locally to quickly test the polygon-edge before doing a production-like setup, please refer to Local Setup :::

Requirements

Refer to Installation to install ZChains.

Setting up the VM connectivity

Depending on your choice of cloud provider, you may set up connectivity and rules between the VMs using a firewall, security groups, or access control lists.

As the only part of the polygon-edge that needs to be exposed to other VMs is the libp2p server, simply allowing all communication between VMs on the default libp2p port 1478 is enough.

Overview

In this guide, our goal is to establish a working polygon-edge blockchain network working with IBFT consensus protocol. The blockchain network will consist of 4 nodes of whom all 4 are validator nodes, and as such are eligible for both proposing block, and validating blocks that came from other proposers. Each of the 4 nodes will run on their own VM, as the idea of this guide is to give you a fully functional ZChains network while keeping the validator keys private to ensure a trustless network setup.

To achieve that, we will guide you through 4 easy steps:

1. Take a look at the list of Requirements above

2. Generate the private keys for each of the validators, and initialize the data directory

3. Prepare the connection string for the bootnode to be put into the shared genesis.json

4. Create the genesis.json on your local machine, and send/transfer it to each of the nodes

5. Start all the nodes

:::info Number of validators

There is no minimum to the number of nodes in a cluster, which means clusters with only 1 validator node are possible. Keep in mind that with a single node cluster, there is no crash tolerance and no BFT guarantee.

The minimum recommended number of nodes for achieving a BFT guarantee is 4 - since in a 4 node cluster, the failure of 1 node can be tolerated, with the remaining 3 functioning normally.

:::

Step 1: Initialize data folders and generate validator keys

To get up and running with ZChains, you need to initialize the data folders, on each node:

node-1> polygon-edge secrets init --data-dir data-dir

node-2> polygon-edge secrets init --data-dir data-dir

node-3> polygon-edge secrets init --data-dir data-dir

node-4> polygon-edge secrets init --data-dir data-dir

Each of these commands will print the node ID. You will need that information for the next step.

:::warning Keep your data directory to yourself!

The data directories generated above, besides initializing the directories for holding the blockchain state, will also generate your validator's private keys. This key should be kept as a secret, as stealing it would render somebody capable of impersonating you as the validator in the network! :::

Step 2: Prepare the multiaddr connection string for the bootnode

For a node to successfully establish connectivity, it must know which bootnode server to connect to gain information about all the remaining nodes on the network. The bootnode is sometimes also known as the rendezvous server in p2p jargon.

bootnode is not a special instance of a Polygon Edge node. Every Polygon Edge node can serve as a bootnode and every Polygon Edge node needs to have a set of bootnodes specified which will be contacted to provide information on how to connect with all remaining nodes in the network.

To create the connection string for specifying the bootnode, we will need to conform to the multiaddr format:

/ip4/<ip_address>/tcp/<port>/p2p/<node_id>

In this guide, we will treat the first and second nodes as the bootnodes for all other nodes. What will happen in this scenario is that nodes that connect to the node 1 or node 2 will get information on how to connect to one another through the mutually contacted bootnode.

:::info You need to specify at least one bootnode to start a node

At least one bootnode is required, so other nodes in the network can discover each other. More bootnodes are recommended, as they provide resilience to the network in case of outages. In this guide we will list two nodes, but this can be changed on the fly, with no impact on the validity of the genesis.json file. :::

As the first part of the multiaddr connection string is the <ip_address>, here you will need to enter the IP address as reachable by other nodes, depending on your setup this might be a private or a public IP address, not 127.0.0.1.

For the <port> we will use 1478, since it is the default libp2p port.

And lastly, we need the <node_id> which we can get from the output of the previously ran command polygon-edge secrets init --data-dir data-dir command (which was used to generate keys and data directories for the node 1)

After the assembly, the multiaddr connection string to the node 1 which we will use as the bootnode will look something like this (only the <node_id> which is at the end should be different):

/ip4/<public_or_private_ip>/tcp/1478/p2p/16Uiu2HAmJxxH1tScDX2rLGSU9exnuvZKNM9SoK3v315azp68DLPW

Similarly, we construct multiaddr for the second bootnode as shown below

/ip4/<public_or_private_ip>/tcp/1478/p2p/16Uiu2HAmS9Nq4QAaEiogE4ieJFUYsoH28magT7wSvJPpfUGBj3Hq 

Step 3: Generate the genesis file with the 4 nodes as validators

This step can be run on your local machine, but you will need the public validator keys for each of the 4 validators.

Validators can safely share the Public key (address) as displayed below in the output to their secrets init commands, so that you may securely generate the genesis.json with those validators in the initial validator set, identified by their public keys:

[SECRETS INIT]
Public key (address) = 0xC12bB5d97A35c6919aC77C709d55F6aa60436900
Node ID              = 16Uiu2HAmVZnsqvTwuzC9Jd4iycpdnHdyVZJZTpVC8QuRSKmZdUrf

Given that you have received all 4 of the validators' public keys, you can run the following command to generate the genesis.json

polygon-edge genesis --consensus ibft --ibft-validator=0xC12bB5d97A35c6919aC77C709d55F6aa60436900 --ibft-validator=<2nd_validator_pubkey> --ibft-validator=<3rd_validator_pubkey> --ibft-validator=<4th_validator_pubkey> --bootnode=<first_bootnode_multiaddr_connection_string_from_step_2> --bootnode <second_bootnode_multiaddr_connection_string_from_step_2> --bootnode <optionally_more_bootnodes>

What this command does:

• The --ibft-validator sets the public key of the validator that should be included in the initial validator set in the genesis block. There can be many initial validators.

• The --bootnode sets the address of the bootnode that will enable the nodes to find each other. We will use the multiaddr string of the node 1, as mentioned in step 2, although you can add as many bootnodes as you want, as displayed above.

:::info Premining account balances

You will probably want to set up your blockchain network with some addresses having "premined" balances.

To achieve this, pass as many --premine flags as you want per address that you want to be initialized with a certain balance on the blockchain.

For example, if we would like to premine 1000 ETH to address 0x3956E90e632AEbBF34DEB49b71c28A83Bc029862 in our genesis block, then we would need to supply the following argument:

--premine=0x3956E90e632AEbBF34DEB49b71c28A83Bc029862:1000000000000000000000

Note that the premined amount is in WEI, not ETH.

:::

:::info Set the block gas limit

The default gas limit for each block is 5242880. This value is written in the genesis file, but you may want to increase / decrease it.

const (
	GenesisFileName       = "./genesis.json"
	DefaultChainName      = "example"
	DefaultChainID        = 100
	DefaultPremineBalance = "0x3635C9ADC5DEA00000"
	DefaultConsensus      = "pow"
	GenesisGasUsed        = 458752
	GenesisGasLimit       = 5242880 // The default block gas limit
)

To do so, you can use the flag --block-gas-limit followed by the desired value as shown below :

--block-gas-limit 1000000000

:::

:::info Set system file descriptor limit

The default file descriptor limit ( maximum number of open files ) on some operating systems is pretty small. If the nodes are expected to have high throughput, you might consider increasing this limit on the OS level.

For Ubuntu distro the procedure is as follows ( if you're not using Ubuntu/Debian distro, check the official docs for your OS ) :

• Check current os limits ( open files )

ubuntu@ubuntu:~$ ulimit -a
core file size          (blocks, -c) 0
data seg size           (kbytes, -d) unlimited
scheduling priority             (-e) 0
file size               (blocks, -f) unlimited
pending signals                 (-i) 15391
max locked memory       (kbytes, -l) 65536
max memory size         (kbytes, -m) unlimited
open files                      (-n) 1024
pipe size            (512 bytes, -p) 8
POSIX message queues     (bytes, -q) 819200
real-time priority              (-r) 0
stack size              (kbytes, -s) 8192
cpu time               (seconds, -t) unlimited
max user processes              (-u) 15391
virtual memory          (kbytes, -v) unlimited
file locks                      (-x) unlimited

• Increase open files limit

  • Localy - affects only current session:

  Copy

  ulimit -u 65535

  • Globaly or per user ( add limits at the end of /etc/security/limits.conf file ) :

  Copy

  sudo vi /etc/security/limits.conf  # we use vi, but you can use your favorite text editor

  Copy

  # /etc/security/limits.conf
  #
  #Each line describes a limit for a user in the form:
  #
  #<domain>        <type>  <item>  <value>
  #
  #Where:
  #<domain> can be:
  #        - a user name
  #        - a group name, with @group syntax
  #        - the wildcard *, for default entry
  #        - the wildcard %, can be also used with %group syntax,
  #                 for maxlogin limit
  #        - NOTE: group and wildcard limits are not applied to root.
  #          To apply a limit to the root user, <domain> must be
  #          the literal username root.
  #
  #<type> can have the two values:
  #        - "soft" for enforcing the soft limits
  #        - "hard" for enforcing hard limits
  #
  #<item> can be one of the following:
  #        - core - limits the core file size (KB)
  #        - data - max data size (KB)
  #        - fsize - maximum filesize (KB)
  #        - memlock - max locked-in-memory address space (KB)
  #        - nofile - max number of open file descriptors
  #        - rss - max resident set size (KB)
  #        - stack - max stack size (KB)
  #        - cpu - max CPU time (MIN)
  #        - nproc - max number of processes
  #        - as - address space limit (KB)
  #        - maxlogins - max number of logins for this user
  
  #        - maxsyslogins - max number of logins on the system
  #        - priority - the priority to run user process with
  #        - locks - max number of file locks the user can hold
  #        - sigpending - max number of pending signals
  #        - msgqueue - max memory used by POSIX message queues (bytes)
  #        - nice - max nice priority allowed to raise to values: [-20, 19]
  #        - rtprio - max realtime priority
  #        - chroot - change root to directory (Debian-specific)
  #
  #<domain>      <type>  <item>         <value>
  #
  
  #*               soft    core            0
  #root            hard    core            100000
  #*               hard    rss             10000
  #@student        hard    nproc           20
  #@faculty        soft    nproc           20
  #@faculty        hard    nproc           50
  #ftp             hard    nproc           0
  #ftp             -       chroot          /ftp
  #@student        -       maxlogins       4
  
  *               soft    nofile          65535
  *               hard    nofile          65535
  
  # End of file

  Optionaly, modify additional parameters, save the file and restart the system. After restart check file descriptor limit again. It should be set to the value you defined in limits.conf file. :::

After specifying the:

1. Public keys of the validators to be included in the genesis block as the validator set

2. Bootnode multiaddr connection strings

3. Premined accounts and balances to be included in the genesis block

and generating the genesis.json, you should copy it over to all of the VMs in the network. Depending on your setup you may copy/paste it, send it to the node operator, or simply SCP/FTP it over.

The structure of the genesis file is covered in the CLI Commands section.

Step 4: Run all the clients

:::note Networking on Cloud providers

Most cloud providers don't expose the IP addresses (especially public ones) as a direct network interface on your VM but rather setup an invisible NAT proxy.

To allow the nodes to connect to each other in this case you would need to listen on the 0.0.0.0 IP address to bind on all interfaces, but you would still need to specify the IP address or DNS address which other nodes can use to connect to your instance. This is achieved either by using the --nat or --dns argument where you can specify your external IP or DNS address respectively.

Example

The associated IP address that you wish to listen on is 192.0.2.1, but it is not directly bound to any of your network interfaces.

To allow the nodes to connect you would pass the following parameters:

polygon-edge ... --libp2p 0.0.0.0:10001 --nat 192.0.2.1

Or, if you wish to specify a DNS address dns/example.io, pass the following parameters:

polygon-edge ... --libp2p 0.0.0.0:10001 --dns dns/example.io

This would make your node listen on all interfaces, but also make it aware that the clients are connecting to it through the specified --nat or --dns address.

:::

To run the first client:

node-1> polygon-edge server --data-dir ./data-dir --chain genesis.json  --libp2p 0.0.0.0:1478 --nat <public_or_private_ip> --seal

To run the second client:

node-2> polygon-edge server --data-dir ./data-dir --chain genesis.json --libp2p 0.0.0.0:1478 --nat <public_or_private_ip> --seal

To run the third client:

node-3> polygon-edge server --data-dir ./data-dir --chain genesis.json --libp2p 0.0.0.0:1478 --nat <public_or_private_ip> --seal

To run the fourth client:

node-4> polygon-edge server --data-dir ./data-dir --chain genesis.json --libp2p 0.0.0.0:1478 --nat <public_or_private_ip> --seal

After running the previous commands, you have set up a 4 node Polygon Edge network, capable of sealing blocks and recovering from node failure.

:::info Start the client using config file

Instead of specifying all configuration parameters as CLI arguments, the Client can also be started using a config file by executing the following command:

polygon-edge server --config <config_file_path>

Example :

polygon-edge server --config ./test/config-node1.json

Currently, we only support json based configuration file, sample config file can be found here

:::

:::info Steps to run a non-validator node

A Non-validator will always sync the latest blocks received from the validator node, you can start a non-validator node by running the following command.

polygon-edge server --data-dir <directory_path> --chain <genesis_filename>  --libp2p <IPAddress:PortNo> --nat <public_or_private_ip>

For example, you can add fifth Non-validator client by executing the following command :

polygon-edge server --data-dir ./data-dir --chain genesis.json --libp2p 0.0.0.0:1478 --nat<public_or_private_ip>

:::

:::info Specify the price limit A Zchains e node can be started with a set price limit for incoming transactions.

The unit for the price limit is wei.

Setting a price limit means that any transaction processed by the current node will need to have a gas price higher than the set price limit, otherwise it will not be included into a block.

Having the majority of nodes respect a certain price limit enforces the rule that transactions in the network cannot be below a certain price threshold.

The default value for the price limit is 0, meaning it is not enforced at all by default.

Example of using the --price-limit flag:

polygon-edge server --price-limit 100000 ...

It is worth noting that price limits are enforced only on non-local transactions, meaning that the price limit does not apply to transactions added locally on the node. :::

This section details the present commands, command flags in the EVMBuilder Edge, and how they're used.

JSON OUTPUT SUPPORT

The --json flag is supported on some commands. This flag instructs the command to print the output in JSON format

Startup Commands

server flags

seal

SyntaxExample

server [--seal SHOULD_SEAL]

Sets the flag indicating that the client should seal blocks. Default: true.

data-dir

SyntaxExample

server [--data-dir DATA_DIRECTORY]

Used to specify the data directory used for storing EVMBuilder Edge client data. Default: ./test-chain.

jsonrpc

SyntaxExample

server [--jsonrpc JSONRPC_ADDRESS]

Sets the address and port for the JSON-RPC service address:port. If only port is defined :10001 it will bind to all interfaces 0.0.0.0:10001. If omitted the service will bind to the default address:port. Default address: 0.0.0.0:8545.

grpc

SyntaxExample

server [--grpc-address GRPC_ADDRESS]

Sets the address and port for the gRPC service address:port. Default address: 127.0.0.1:9632.

libp2p

SyntaxExample

server [--libp2p LIBP2P_ADDRESS]

Sets the address and port for the libp2p service address:port. Default address: 127.0.0.1:1478.

prometheus

SyntaxExample

server [--prometheus PROMETHEUS_ADDRESS]

Sets the address and port for the prometheus server address:port. If only port is defined :5001 the service will bind to all interfaces 0.0.0.0:5001. If omitted the service will not be started.

block-gas-target

SyntaxExample

server [--block-gas-target BLOCK_GAS_TARGET]

Sets the target block gas limit for the chain. Default (not enforced): 0.

A more detailed explanation on the block gas target can be found in the TxPool section.

max-peers

SyntaxExample

server [--max-peers PEER_COUNT]

Sets the client's maximum peer count. Default: 40.

Peer limit should be specified either by using max-peers or max-inbound/outbound-peers flag.

max-inbound-peers

SyntaxExample

server [--max-inbound-peers PEER_COUNT]

Sets the client's maximum inbound peer count. If max-peers is set, max-inbound-peer limit is calculated using the following formulae.

max-inbound-peer = InboundRatio * max-peers, where InboundRatio is 0.8.

max-outbound-peers

SyntaxExample

server [--max-outbound-peers PEER_COUNT]

Sets the client's maximum outbound peer count. If max-peers is set, max-outbound-peer count is calculated using the following formulae.

max-outbound-peer = OutboundRatio * max-peers, where OutboundRatio is 0.2.

log-level

SyntaxExample

server [--log-level LOG_LEVEL]

Sets the log level for console output. Default: INFO.

log-to

SyntaxExample

server [--log-to LOG_FILE]

Defines log file name that will hold all log output from the server command. By default, all server logs will be outputted to console (stdout), but if the flag is set, there will be no output to the console when running server command.

chain

SyntaxExample

server [--chain GENESIS_FILE]

Specifies the genesis file used for starting the chain. Default: ./genesis.json.

join

SyntaxExample

server [--join JOIN_ADDRESS]

Specifies the address of the peer that should be joined.

nat

SyntaxExample

server [--nat NAT_ADDRESS]

Sets the external IP address without the port, as it can be seen by peers.

dns

SyntaxExample

server [--dns DNS_ADDRESS]

Sets the host DNS address. This can be used to advertise an external DNS. Supports dns,dns4,dns6.

price-limit

SyntaxExample

server [--price-limit PRICE_LIMIT]

Sets minimum gas price limit to enforce for acceptance into the pool. Default: 1.

max-slots

SyntaxExample

server [--max-slots MAX_SLOTS]

Sets maximum slots in the pool. Default: 4096.

config

SyntaxExample

server [--config CLI_CONFIG_PATH]

Specifies the path to the CLI config. Supports .json.

secrets-config

SyntaxSecond Tab

server [--secrets-config SECRETS_CONFIG]

Sets the path to the SecretsManager config file. Used for Hashicorp Vault, AWS SSM and GCP Secrets Manager. If omitted, the local FS secrets manager is used.

dev

SyntaxExample

server [--dev DEV_MODE]

Sets the client to dev mode. Default: false.

dev-interval

SyntaxExample

server [--dev-interval DEV_INTERVAL]

Sets the client's dev notification interval in seconds. Default: 0.

no-discover

SyntaxExample

server [--no-discover NO_DISCOVER]

Prevents the client from discovering other peers. Default: false.

restore

SyntaxExample

server [--restore RESTORE]

Restore blocks from the specified archive file

block-time

SyntaxExample

server [--block-time BLOCK_TIME]

Sets block production time in seconds. Default: 2

ibft-base-timeout

SyntaxExample

server [--ibft-base-timeout IBFT_BASE_TIMEOUT]

Sets the base value of timeout on IBFT consensus. IBFT consensus timeout is calculated by BaseTimeout + 2^(round), or BaseTimeout * 30 where round exceeds 8. It needs to be larger than block time and BlockTime * 5 is set if it's not specified.

access-control-allow-origins

SyntaxExample

server [--access-control-allow-origins ACCESS_CONTROL_ALLOW_ORIGINS]

Sets the authorized domains to be able to share responses from JSON-RPC requests. Add multiple flags --access-control-allow-origins "https://example1.com" --access-control-allow-origins "https://example2.com" to authorize multiple domains. If omitted Access-Control-Allow-Origins header will be set to * and all domains will be authorized.

genesis flags

dir

SyntaxExample

genesis [--dir DIRECTORY]

Sets the directory for the EVMBuilder Edge genesis data. Default: ./genesis.json.

name

SyntaxExample

genesis [--name NAME]

Sets the name for the chain. Default: polyton-edge.

pos

SyntaxExample

genesis [--pos IS_POS]

Sets the flag indicating that the client should use Proof of Stake IBFT. Defaults to Proof of Authority if flag is not provided or false.

epoch-size

SyntaxExample

genesis [--epoch-size EPOCH_SIZE]

Sets the epoch size for the chain. Default 100000.

premine

SyntaxExample

genesis [--premine ADDRESS:VALUE]

Sets the premined accounts and balances in the format address:amount. The amount can be in either decimal or hex. Default premined balance: 0x3635C9ADC5DEA00000.

chainid

SyntaxExample

genesis [--chain-id CHAIN_ID]

Sets the ID of the chain. Default: 100.

ibft-validators-prefix-path

SyntaxExample

genesis [--ibft-validators-prefix-path IBFT_VALIDATORS_PREFIX_PATH]

Prefix path for validator folder directory. Needs to be present if the flag ibft-validator is omitted.

ibft-validator

SyntaxExample

genesis [--ibft-validator IBFT_VALIDATOR_LIST]

Sets passed in addresses as IBFT validators. Needs to be present if the flag ibft-validators-prefix-path is omitted.

block-gas-limit

SyntaxExample

genesis [--block-gas-limit BLOCK_GAS_LIMIT]

Refers to the maximum amount of gas used by all operations in a block. Default: 5242880.

consensus

SyntaxExample

genesis [--consensus CONSENSUS_PROTOCOL]

Sets consensus protocol. Default: pow.

bootnode

SyntaxExample

genesis [--bootnode BOOTNODE_URL]

Multiaddr URL for p2p discovery bootstrap. This flag can be used multiple times. Instead of an IP address, the DNS address of the bootnode can be provided.

max-validator-count

SyntaxExample

genesis [--max-validator-count MAX_VALIDATOR_COUNT]

The maximum number of stakers able to join the validator set in a PoS consensus. This number cannot exceed the value of MAX_SAFE_INTEGER (2^53 - 2).

min-validator-count

SyntaxExample

genesis [--min-validator-count MIN_VALIDATOR_COUNT]

The minimum number of stakers needed to join the validator set in a PoS consensus. This number cannot exceed the value of max-validator-count. Defaults to 1.

Operator Commands

Peer Commands

peers add flags

addr

SyntaxExample

peers add --addr PEER_ADDRESS

Peer's libp2p address in the multiaddr format.

grpc-address

SyntaxExample

peers add [--grpc-address GRPC_ADDRESS]

Address of the gRPC API. Default: 127.0.0.1:9632.

peers list flags

grpc-address

SyntaxExample

peers list [--grpc-address GRPC_ADDRESS]

Address of the gRPC API. Default: 127.0.0.1:9632.

peers status flags

peer-id

SyntaxExample

peers status --peer-id PEER_ID

Libp2p node ID of a specific peer within p2p network.

grpc-address

SyntaxExample

peers status [--grpc-address GRPC_ADDRESS]

Address of the gRPC API. Default: 127.0.0.1:9632.

IBFT Commands

ibft snapshot flags

number

SyntaxExample

ibft snapshot [--number BLOCK_NUMBER]

The block height (number) for the snapshot.

grpc-address

SyntaxExample

ibft snapshot [--grpc-address GRPC_ADDRESS]

Address of the gRPC API. Default: 127.0.0.1:9632.

ibft candidates flags

grpc-address

SyntaxExample

ibft candidates [--grpc-address GRPC_ADDRESS]

Address of the gRPC API. Default: 127.0.0.1:9632.

ibft propose flags

vote

SyntaxExample

ibft propose --vote VOTE

Proposes a change to the validator set. Possible values: [auth, drop].

addr

SyntaxExample

ibft propose --addr ETH_ADDRESS

Address of the account to be voted for.

grpc-address

SyntaxExample

peers add [--grpc-address GRPC_ADDRESS]

Address of the gRPC API. Default: 127.0.0.1:9632.

ibft status flags

grpc-address

SyntaxExample

peers list [--grpc-address GRPC_ADDRESS]

Address of the gRPC API. Default: 127.0.0.1:9632.

ibft switch flags

chain

SyntaxExample

ibft switch [--chain GENESIS_FILE]

Specifies the genesis file to update. Default: test.

type

SyntaxExample

ibft switch [--type TYPE]

Specifies the IBFT type to switch. Possible values: [PoS].

deployment

SyntaxExample

ibft switch [--deployment DEPLOYMENT]

Specifies the height of contract deployment. Only available with PoS.

from

SyntaxExample

ibft switch [--from FROM]

max-validator-count

SyntaxExample

ibft switch [--max-validator-count MAX_VALIDATOR_COUNT]

The maximum number of stakers able to join the validator set in a PoS consensus. This number cannot exceed the value of MAX_SAFE_INTEGER (2^53 - 2).

min-validator-count

SyntaxExample

ibft switch [--min-validator-count MIN_VALIDATOR_COUNT]

The minimum number of stakers needed to join the validator set in a PoS consensus. This number cannot exceed the value of max-validator-count. Defaults to 1.

Specifies the beginning height of the fork.

Transaction Pool Commands

txpool status flags

grpc-address

SyntaxExample

txpool status [--grpc-address GRPC_ADDRESS]

Address of the gRPC API. Default: 127.0.0.1:9632.

txpool subscribe flags

grpc-address

SyntaxExample

txpool subscribe [--grpc-address GRPC_ADDRESS]

Address of the gRPC API. Default: 127.0.0.1:9632.

promoted

SyntaxExample

txpool subscribe [--promoted LISTEN_PROMOTED]

Subscribes for promoted tx events in the TxPool.

dropped

SyntaxExample

txpool subscribe [--dropped LISTEN_DROPPED]

Subscribes for dropped tx events in the TxPool.

demoted

SyntaxExample

txpool subscribe [--demoted LISTEN_DEMOTED]

Subscribes for demoted tx events in the TxPool.

added

SyntaxExample

txpool subscribe [--added LISTEN_ADDED]

Subscribes for added tx events to the TxPool.

enqueued

SyntaxExample

txpool subscribe [--enqueued LISTEN_ENQUEUED]

Subscribes for enqueued tx events in the account queues.

Blockchain commands

status flags

grpc-address

SyntaxExample

status [--grpc-address GRPC_ADDRESS]

Address of the gRPC API. Default: 127.0.0.1:9632.

monitor flags

grpc-address

SyntaxExample

monitor [--grpc-address GRPC_ADDRESS]

Address of the gRPC API. Default: 127.0.0.1:9632.

Secrets Commands

secrets init flags

config

SyntaxExample

secrets init [--config SECRETS_CONFIG]

Sets the path to the SecretsManager config file. Used for Hashicorp Vault. If omitted, the local FS secrets manager is used.

data-dir

SyntaxExample

secrets init [--data-dir DATA_DIRECTORY]

Sets the directory for the EVMBuilder Edge data if the local FS is used.

secrets generate flags

dir

SyntaxExample

secrets generate [--dir DATA_DIRECTORY]

Sets the directory for the secrets manager configuration file Default: ./secretsManagerConfig.json

type

SyntaxExample

secrets generate [--type TYPE]

Specifies the type of the secrets manager [hashicorp-vault]. Default: hashicorp-vault

token

SyntaxExample

secrets generate [--token TOKEN]

Specifies the access token for the service

server-url

SyntaxExample

secrets generate [--server-url SERVER_URL]

Specifies the server URL for the service

name

SyntaxExample

secrets generate [--name NODE_NAME]

Specifies the name of the node for on-service record keeping. Default: z-edge-node

namespace

SyntaxExample

secrets generate [--namespace NAMESPACE]

Specifies the namespace used for the Hashicorp Vault secrets manager. Default: admin

Responses

Status Response

The response object is defined using Protocol Buffers.

minimal/proto/system.proto

Copy

message ServerStatus {
    int64 network = 1;

    string genesis = 2;

    Block current = 3;

    string p2pAddr = 4;

    message Block {
        int64 number = 1;
        string hash = 2;
    }
}

Monitor Response

minimal/proto/system.proto

Copy

message BlockchainEvent {
    // The "repeated" keyword indicates an array
    repeated Header added = 1;
    repeated Header removed = 2;

    message Header {
        int64 number = 1;
        string hash = 2;
    }
}

Utilities

loadbot flags

tps

SyntaxExample

loadbot [--tps NUMBER_OF_TXNS_PER_SECOND]

The number of transactions per second to send. Default: 100.

mode

SyntaxExample

loadbot [--mode MODE]

Sets the loadbot run mode [transfer, deploy]. Default: transfer.

chain-id

SyntaxExample

loadbot [--chain-id CHAIN_ID]

Sets the network chain ID for transactions. Default: 100.

gas-price

SyntaxExample

loadbot [--gas-price GAS_PRICE]

The gas price that should be used for the transactions. If omitted, the average gas price is fetched from the network.

gas-limit

SyntaxExample

loadbot [--gas-limit GAS_LIMIT]

The gas limit that should be used for the transactions. If omitted, the gas limit is estimated before starting the loadbot.

grpc-address

SyntaxExample

loadbot --grpc-address GRPC_ADDRESS

The GRPC endpoint used to send transactions

detailed

SyntaxExample

loadbot [--detailed DETAILED]

Flag indicating if the error logs should be shown. Default: false.

contract

SyntaxExample

loadbot [--contract CONTRACT_PATH]

The path to the contract JSON artifact containing the bytecode. If omitted, a default contract is used.

sender

SyntaxExample

loadbot [--sender ADDRESS]

Address of the sender account.

receiver

SyntaxExample

loadbot [--receiver ADDRESS]

Address of the receiver account.

jsonrpc

SyntaxExample

loadbot [--jsonrpc ENDPOINT]

A JSON RPC endpoint used to send transactions.

count

SyntaxExample

loadbot [--count COUNT]

The total number of transactions to send. Default: 1000.

value

SyntaxExample

loadbot [--value VALUE]

The value to send in each transaction.

max-conns

SyntaxExample

loadbot [--max-conns MAX_CONNECTIONS_COUNT]

Sets the maximum no.of connections allowed per host. Default: 2*tps.

backup flags

grpc-address

SyntaxExample

backup [--grpc-address GRPC_ADDRESS]

Address of the gRPC API. Default: 127.0.0.1:9632.

out

SyntaxExample

backup [--out OUT]

Path of archive file to save.

from

SyntaxExample

from [--from FROM]

The beginning height of blocks in archive. Default: 0.

to

SyntaxExample

to [--to TO]

The end height of blocks in archive.

Genesis Template

The genesis file should be used to set the initial state of the blockchain (ex. if some accounts should have a starting balance).

The following ./genesis.json file is generated:

Copy

{
    "name": "example",
    "genesis": {
        "nonce": "0x0000000000000000",
        "gasLimit": "0x0000000000001388",
        "difficulty": "0x0000000000000001",
        "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "coinbase": "0x0000000000000000000000000000000000000000",
        "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000"
    },
    "params": {
        "forks": {},
        "chainID": 100,
        "engine": {
            "pow": {}
        }
    },
    "bootnodes": []
}

Data Directory

When executing the data-dir flag, a test-chain folder is generated. The folder structure consists of the following sub-folders:

• blockchain - Stores the LevelDB for blockchain objects

• trie - Stores the LevelDB for the Merkle tries

• keystore - Stores private keys for the client. This includes the libp2p private key and the sealing/validator private key

• consensus - Stores any consensus information that the client might need while working

Resources

• Protocol Buffers

:::caution This guide is for testing purposes only

The below guide will instruct you on how to set up a ZChains network on your local machine for testing and development purposes.

The procedure differs greatly from the way you would want to set up ZChains network for a real use scenario on a cloud provider: Cloud Setup

:::

Requirements

Refer to Installation to install ZChains.

Overview

In this guide, our goal is to establish a working polygon-edge blockchain network working with IBFT consensus protocol. The blockchain network will consist of 4 nodes of whom all 4 are validator nodes, and as such are eligible for both proposing block, and validating blocks that came from other proposers. All 4 nodes will run on the same machine, as the idea of this guide is to give you a fully functional IBFT cluster in the least amount of time.

To achieve that, we will guide you through 4 easy steps:

1. Initializing data directories will generate both the validator keys for each of the 4 nodes, and initialize empty blockchain data directories. The validator keys are important as we need to bootstrap the genesis block with the initial set of validators using these keys.

2. Preparing the connection string for the bootnode will be the vital information for every node we will run as to which node to connect to when starting for the first time.

3. Generating the genesis.json file will require as input both the validator keys generated in step 1 used for setting the initial validators of the network in the genesis block and the bootnode connection string from step 2.

4. Running all the nodes is the end goal of this guide and will be the last step we do, we will instruct the nodes which data directory to use and where to find the genesis.json which bootstraps the initial network state.

As all four nodes will be running on localhost, during the setup process it is expected that all the data directories for each of the nodes are in the same parent directory.

:::info Number of validators

There is no minimum to the number of nodes in a cluster, which means clusters with only 1 validator node are possible. Keep in mind that with a single node cluster, there is no crash tolerance and no BFT guarantee.

The minimum recommended number of nodes for achieving a BFT guarantee is 4 - since in a 4 node cluster, the failure of 1 node can be tolerated, with the remaining 3 functioning normally.

:::

Step 1: Initialize data folders for IBFT and generate validator keys

In order to get up and running with IBFT, you need to initialize the data folders, one for each node:

polygon-edge secrets init --data-dir test-chain-1

polygon-edge secrets init --data-dir test-chain-2

polygon-edge secrets init --data-dir test-chain-3

polygon-edge secrets init --data-dir test-chain-4

Each of these commands will print the validator key and the node ID. You will need the Node ID of the first node for the next step.

Step 2: Prepare the multiaddr connection string for the bootnode

For a node to successfully establish connectivity, it must know which bootnode server to connect to in order to gain information about all the remaining nodes on the network. The bootnode is sometimes also known as the rendezvous server in p2p jargon.

bootnode is not a special instance of the polygon-edge node. Every polygon-edge node can serve as a bootnode, but every polygon-edge node needs to have a set of bootnodes specified which will be contacted to provide information on how to connect with all remaining nodes in the network.

To create the connection string for specifying the bootnode, we will need to conform to the multiaddr format:

/ip4/<ip_address>/tcp/<port>/p2p/<node_id>

In this guide, we will treat the first and second nodes as the bootnodes for all other nodes. What will happen in this scenario is that nodes that connect to the node 1 or node 2 will get information on how to connect to one another through the mutually contacted bootnode.

:::info You need to specify at least one bootnode to start a node

At least one bootnode is required, so other nodes in the network can discover each other. More bootnodes are recommended, as they provide resilience to the network in case of outages. In this guide we will list two nodes, but this can be changed on the fly, with no impact on the validity of the genesis.json file. :::

Since we are running on localhost, it is safe to assume that the <ip_address> is 127.0.0.1.

For the <port> we will use 10001 since we will configure the libp2p server for node 1 to listen on this port later.

And lastly, we need the <node_id> which we can get from the output of the previously ran command polygon-edge secrets init --data-dir test-chain-1 command (which was used to generate keys and data directories for the node1)

After the assembly, the multiaddr connection string to the node 1 which we will use as the bootnode will look something like this (only the <node_id> which is at the end should be different):

/ip4/127.0.0.1/tcp/10001/p2p/16Uiu2HAmJxxH1tScDX2rLGSU9exnuvZKNM9SoK3v315azp68DLPW

Similarly, we construct the multiaddr for second bootnode as shown below

/ip4/127.0.0.1/tcp/20001/p2p/16Uiu2HAmS9Nq4QAaEiogE4ieJFUYsoH28magT7wSvJPpfUGBj3Hq 

Step 3: Generate the genesis file with the 4 nodes as validators

polygon-edge genesis --consensus ibft --ibft-validators-prefix-path test-chain- --bootnode /ip4/127.0.0.1/tcp/10001/p2p/16Uiu2HAmJxxH1tScDX2rLGSU9exnuvZKNM9SoK3v315azp68DLPW --bootnode /ip4/127.0.0.1/tcp/20001/p2p/16Uiu2HAmS9Nq4QAaEiogE4ieJFUYsoH28magT7wSvJPpfUGBj3Hq 

What this command does:

• The --ibft-validators-prefix-path sets the prefix folder path to the one specified which IBFT in Zchains can use. This directory is used to house the consensus/ folder, where the validator's private key is kept. The validator's public key is needed in order to build the genesis file - the initial list of bootstrap nodes. This flag only makes sense when setting up the network on localhost, as in a real-world scenario we cannot expect all the nodes' data directories to be on the same filesystem from where we can easily read their public keys.

• The --bootnode sets the address of the bootnode that will enable the nodes to find each other. We will use the multiaddr string of the node 1, as mentioned in step 2.

The result of this command is the genesis.json file which contains the genesis block of our new blockchain, with the predefined validator set and the configuration for which node to contact first in order to establish connectivity.

:::info Premining account balances

You will probably want to set up your blockchain network with some addresses having "premined" balances.

To achieve this, pass as many --premine flags as you want per address that you want to be initialized with a certain balance on the blockchain.

For example, if we would like to premine 1000 ETH to address 0x3956E90e632AEbBF34DEB49b71c28A83Bc029862 in our genesis block, then we would need to supply the following argument:

--premine=0x3956E90e632AEbBF34DEB49b71c28A83Bc029862:1000000000000000000000

Note that the premined amount is in WEI, not ETH.

:::

:::info Set the block gas limit

The default gas limit for each block is 5242880. This value is written in the genesis file, but you may want to increase / decrease it.

const (
	GenesisFileName       = "./genesis.json"
	DefaultChainName      = "example"
	DefaultChainID        = 100
	DefaultPremineBalance = "0x3635C9ADC5DEA00000"
	DefaultConsensus      = "pow"
	GenesisGasUsed        = 458752
	GenesisGasLimit       = 5242880 // The default block gas limit
)

To do so, you can use the flag --block-gas-limit followed by the desired value as shown below :

--block-gas-limit 1000000000

:::

:::info Set system file descriptor limit

The default file descriptor limit ( maximum number of open files ) on some operating systems is pretty small. If the nodes are expected to have high throughput, you might consider increasing this limit on the OS level.

For Ubuntu distro the procedure is as follows ( if you're not using Ubuntu/Debian distro, check the official docs for your OS ) :

• Check current os limits ( open files )

ubuntu@ubuntu:~$ ulimit -a
core file size          (blocks, -c) 0
data seg size           (kbytes, -d) unlimited
scheduling priority             (-e) 0
file size               (blocks, -f) unlimited
pending signals                 (-i) 15391
max locked memory       (kbytes, -l) 65536
max memory size         (kbytes, -m) unlimited
open files                      (-n) 1024
pipe size            (512 bytes, -p) 8
POSIX message queues     (bytes, -q) 819200
real-time priority              (-r) 0
stack size              (kbytes, -s) 8192
cpu time               (seconds, -t) unlimited
max user processes              (-u) 15391
virtual memory          (kbytes, -v) unlimited
file locks                      (-x) unlimited

• Increase open files limit

  • Localy - affects only current session:

  Copy

  ulimit -u 65535

  • Globaly or per user ( add limits at the end of /etc/security/limits.conf file ) :

  Copy

  sudo vi /etc/security/limits.conf  # we use vi, but you can use your favorite text editor

  Copy

  # /etc/security/limits.conf
  #
  #Each line describes a limit for a user in the form:
  #
  #<domain>        <type>  <item>  <value>
  #
  #Where:
  #<domain> can be:
  #        - a user name
  #        - a group name, with @group syntax
  #        - the wildcard *, for default entry
  #        - the wildcard %, can be also used with %group syntax,
  #                 for maxlogin limit
  #        - NOTE: group and wildcard limits are not applied to root.
  #          To apply a limit to the root user, <domain> must be
  #          the literal username root.
  #
  #<type> can have the two values:
  #        - "soft" for enforcing the soft limits
  #        - "hard" for enforcing hard limits
  #
  #<item> can be one of the following:
  #        - core - limits the core file size (KB)
  #        - data - max data size (KB)
  #        - fsize - maximum filesize (KB)
  #        - memlock - max locked-in-memory address space (KB)
  #        - nofile - max number of open file descriptors
  #        - rss - max resident set size (KB)
  #        - stack - max stack size (KB)
  #        - cpu - max CPU time (MIN)
  #        - nproc - max number of processes
  #        - as - address space limit (KB)
  #        - maxlogins - max number of logins for this user
  
  #        - maxsyslogins - max number of logins on the system
  #        - priority - the priority to run user process with
  #        - locks - max number of file locks the user can hold
  #        - sigpending - max number of pending signals
  #        - msgqueue - max memory used by POSIX message queues (bytes)
  #        - nice - max nice priority allowed to raise to values: [-20, 19]
  #        - rtprio - max realtime priority
  #        - chroot - change root to directory (Debian-specific)
  #
  #<domain>      <type>  <item>         <value>
  #
  
  #*               soft    core            0
  #root            hard    core            100000
  #*               hard    rss             10000
  #@student        hard    nproc           20
  #@faculty        soft    nproc           20
  #@faculty        hard    nproc           50
  #ftp             hard    nproc           0
  #ftp             -       chroot          /ftp
  #@student        -       maxlogins       4
  
  *               soft    nofile          65535
  *               hard    nofile          65535
  
  # End of file

  Optionaly, modify additional parameters, save the file and restart the system. After restart check file descriptor limit again. It should be set to the value you defined in limits.conf file. :::

Step 4: Run all the clients

Because we are attempting to run a Polygon Edge network consisting of 4 nodes all on the same machine, we need to take care to avoid port conflicts. This is why we will use the following reasoning for determining the listening ports of each server of a node:

• 10000 for the gRPC server of node 1, 20000 for the GRPC server of node 2, etc.

• 10001 for the libp2p server of node 1, 20001 for the libp2p server of node 2, etc.

• 10002 for the JSON-RPC server of node 1, 20002 for the JSON-RPC server of node 2, etc.

To run the first client (note the port 10001 since it was used as a part of the libp2p multiaddr in step 2 alongside node 1's Node ID):

polygon-edge server --data-dir ./test-chain-1 --chain genesis.json --grpc-address :10000 --libp2p :10001 --jsonrpc :10002 --seal

To run the second client:

polygon-edge server --data-dir ./test-chain-2 --chain genesis.json --grpc-address :20000 --libp2p :20001 --jsonrpc :20002 --seal

To run the third client:

polygon-edge server --data-dir ./test-chain-3 --chain genesis.json --grpc-address :30000 --libp2p :30001 --jsonrpc :30002 --seal

To run the fourth client:

polygon-edge server --data-dir ./test-chain-4 --chain genesis.json --grpc-address :40000 --libp2p :40001 --jsonrpc :40002 --seal

To briefly go over what has been done so far:

• The directory for the client data has been specified to be ./test-chain-*

• The GRPC servers have been started on ports 10000, 20000, 30000 and 40000, for each node respectively

• The libp2p servers have been started on ports 10001, 20001, 30001 and 40001, for each node respectively

• The JSON-RPC servers have been started on ports 10002, 20002, 30002 and 40002, for each node respectively

• The seal flag means that the node which is being started is going to participate in block sealing

• The chain flag specifies which genesis file should be used for chain configuration

The structure of the genesis file is covered in the CLI Commands section.

After running the previous commands, you have set up a 4 node Polygon Edge network, capable of sealing blocks and recovering from node failure.

:::info Start the client using config file

Instead of specifying all configuration parameters as CLI arguments, the Client can also be started using a config file by executing the following command:

polygon-edge server --config <config_file_path>

Example:

polygon-edge server --config ./test/config-node1.json

Currently, we only support json based configuration file, sample config file can be found here

:::

:::info Steps to run a non-validator node

A Non-validator will always sync the latest blocks received from the validator node, you can start a non-validator node by running the following command.

polygon-edge server --data-dir <directory_path> --chain <genesis_filename> --grpc-address <portNo> --libp2p <portNo> --jsonrpc <portNo>

For example, you can add fifth Non-validator client by executing the following command :

polygon-edge server --data-dir ./test-chain --chain genesis.json --grpc-address :50000 --libp2p :50001 --jsonrpc :50002 

:::

:::info Specify the price limit A Polygon Edge node can be started with a set price limit for incoming transactions.

The unit for the price limit is wei.

Setting a price limit means that any transaction processed by the current node will need to have a gas price higher then the set price limit, otherwise it will not be included in a block.

Having the majority of nodes respect a certain price limit enforces the rule that transactions in the network cannot be below a certain price threshold.

The default value for the price limit is 0, meaning it is not enforced at all by default.

Example of using the --price-limit flag:

polygon-edge server --price-limit 100000 ...

It is worth noting that price limits are enforced only on non-local transactions, meaning that the price limit does not apply to transactions added locally on the node. :::

Step 5: Interact with the polygon-edge network

Now that you've set up at least 1 running client, you can go ahead and interact with the blockchain using the account you premined above and by specifying the JSON-RPC URL to any of the 4 nodes:

• Node 1: http://localhost:10002

• Node 2: http://localhost:20002

• Node 3: http://localhost:30002

• Node 4: http://localhost:40002

Follow this guide to issue operator commands to the newly built cluster: How to query operator information (the GRPC ports for the cluster we have built are 10000/20000/30000/40000 for each node respectively)