CLI Commands

CLI Commands

This section details the present commands, command flags in the Polygon 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​

Command	Description
server	The default command that starts the blockchain client, by bootstrapping all modules together
genesis	Generates a genesis.json file, which is used to set a predefined chain state before starting the client. The structure of the genesis file is described below
genesis predeploy	Predeploys a Smart Contract for fresh networks

server flags​

All server flags
data-dir	jsonrpc
json-rpc-block-range-limit	json-rpc-batch-request-limit
grpc	libp2p
prometheus	block-gas-target
max-peers	max-inbound-peers
max-outbound-peers	max-enqueued
log-level	log-to
chain	join
nat	dns
price-limit	max-slots
config	secrets-config
dev	dev-interval
no-discover	restore
block-time	access-control-allow-origins

data-dir

​

• Syntax

• Example

server [--data-dir DATA_DIRECTORY]

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

---

jsonrpc

​

• Syntax

• Example

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.

---

json-rpc-block-range-limit

​

• Syntax

• Example

server [--json-rpc-block-range-limit BLOCK_RANGE]

Sets the maximum block range to be considered when executing json-rpc requests that include fromBlock/toBlock values (e.g. eth_getLogs). Default:1000.

---

json-rpc-batch-request-limit

​

• Syntax

• Example

server [--json-rpc-batch-request-limit MAX_LENGTH]

Sets the maximum length to be considered when handling json-rpc batch requests. Default: 20.

---

grpc

​

• Syntax

• Example

server [--grpc-address GRPC_ADDRESS]

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

---

libp2p

​

• Syntax

• Example

server [--libp2p LIBP2P_ADDRESS]

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

---

prometheus

​

• Syntax

• Example

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

​

• Syntax

• Example

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

​

• Syntax

• Example

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

​

• Syntax

• Example

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

​

• Syntax

• Example

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.

---

max-enqueued

​

• Syntax

• Example

server [--max-enqueued ENQUEUED_TRANSACTIONS]

Sets the maximum number of enqueued transactions per account. Default:128.

---

log-level

​

• Syntax

• Example

server [--log-level LOG_LEVEL]

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

---

log-to

​

• Syntax

• Example

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

​

• Syntax

• Example

server [--chain GENESIS_FILE]

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

---

join

​

• Syntax

• Example

server [--join JOIN_ADDRESS]

Specifies the address of the peer that should be joined.

---

nat

​

• Syntax

• Example

server [--nat NAT_ADDRESS]

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

---

dns

​

• Syntax

• Example

server [--dns DNS_ADDRESS]

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

---

price-limit

​

• Syntax

• Example

server [--price-limit PRICE_LIMIT]

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

---

max-slots

​

• Syntax

• Example

server [--max-slots MAX_SLOTS]

Sets maximum slots in the pool. Default: 4096.

---

config

​

• Syntax

• Example

server [--config CLI_CONFIG_PATH]

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

---

secrets-config

​

• Syntax

• Example

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

​

• Syntax

• Example

server [--dev DEV_MODE]

Sets the client to dev mode. Default: false. In dev mode, peer discovery is disabled by default.

---

dev-interval

​

• Syntax

• Example

server [--dev-interval DEV_INTERVAL]

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

---

no-discover

​

• Syntax

• Example

server [--no-discover NO_DISCOVER]

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

---

restore

​

• Syntax

• Example

server [--restore RESTORE]

Restore blocks from the specified archive file

---

block-time

​

• Syntax

• Example

server [--block-time BLOCK_TIME]

Sets block production time in seconds. Default: 2

---

access-control-allow-origins

​

• Syntax

• Example

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​

All genesis flags
dir	name
pos	epoch-size
premine	chainid
ibft-validator-type	ibft-validators-prefix-path
ibft-validator	block-gas-limit
consensus	bootnode
max-validator-count	min-validator-count

dir

​

• Syntax

• Example

genesis [--dir DIRECTORY]

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

---

name

​

• Syntax

• Example

genesis [--name NAME]

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

---

pos

​

• Syntax

• Example

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

​

• Syntax

• Example

genesis [--epoch-size EPOCH_SIZE]

Sets the epoch size for the chain. Default 100000.

---

premine

​

• Syntax

• Example

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: 0xD3C21BCECCEDA1000000(1 million native currency tokens).

---

chainid

​

• Syntax

• Example

genesis [--chain-id CHAIN_ID]

Sets the ID of the chain. Default: 100.

---

ibft-validator-type

​

• Syntax

• Example

genesis [--ibft-validator-type IBFT_VALIDATOR_TYPE]

Specifies the validation mode of block headers. Possible values: [ecdsa, bls]. Default: bls.

---

ibft-validators-prefix-path

​

• Syntax

• Example

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

​

• Syntax

• Example

genesis [--ibft-validator IBFT_VALIDATOR_LIST]

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

1. If the network is running with ECDSA, the format is --ibft-validator [ADDRESS].

2. If the network is running with BLS, the format is --ibft-validator [ADDRESS]:[BLS_PUBLIC_KEY].

---

block-gas-limit

​

• Syntax

• Example

genesis [--block-gas-limit BLOCK_GAS_LIMIT]

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

---

consensus

​

• Syntax

• Example

genesis [--consensus CONSENSUS_PROTOCOL]

Sets consensus protocol. Default: pow.

---

bootnode

​

• Syntax

• Example

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

​

• Syntax

• Example

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

​

• Syntax

• Example

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.

---

genesis predeploy flags​

artifacts-path

• Syntax

• Example

genesis predeploy [--artifacts-path PATH_TO_ARTIFACTS]

Sets the path to the contract artifacts JSON that contains the abi, bytecode and deployedBytecode.

---

chain

• Syntax

• Example

genesis predeploy [--chain PATH_TO_GENESIS]

Sets the path to the genesis.json file that should be updated. Default ./genesis.json.

---

constructor-args

• Syntax

• Example

genesis predeploy [--constructor-args CONSTRUCTOR_ARGUMENT]

Sets the Smart Contract constructor arguments, if any. For a detailed guide on how these arguments should look like, please reference predeployment article.

---

predeploy-address

• Syntax

• Example

genesis predeploy [--predeploy-address PREDEPLOY_ADDRESS]

Sets the address to predeploy to. Default 0x0000000000000000000000000000000000001100.

---

Operator Commands​

Peer Commands​

Command	Description
peers add	Adds a new peer using their libp2p address
peers list	Lists all the peers the client is connected to through libp2p
peers status	Returns the status of a specific peer from the peers list, using the libp2p address

peers add flags

addr

• Syntax

• Example

peers add --addr PEER_ADDRESS

Peer's libp2p address in the multiaddr format.

---

grpc-address

• Syntax

• Example

peers add [--grpc-address GRPC_ADDRESS]

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

peers list flags

grpc-address

• Syntax

• Example

peers list [--grpc-address GRPC_ADDRESS]

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

peers status flags

peer-id

• Syntax

• Example

peers status --peer-id PEER_ID

Libp2p node ID of a specific peer within p2p network.

---

grpc-address

• Syntax

• Example

peers status [--grpc-address GRPC_ADDRESS]

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

IBFT Commands​

Command	Description
ibft snapshot	Returns the IBFT snapshot
ibft candidates	Queries the current set of proposed candidates, as well as candidates that have not been included yet
ibft propose	Proposes a new candidate to be added/removed from the validator set
ibft status	Returns the overall status of the IBFT client
ibft switch	Add fork configurations into genesis.json file to switch IBFT type
ibft quorum	Specifies the block number after which the optimal quorum size method will be used for reaching consensus

ibft snapshot flags

number

• Syntax

• Example

ibft snapshot [--number BLOCK_NUMBER]

The block height (number) for the snapshot.

---

grpc-address

• Syntax

• Example

ibft snapshot [--grpc-address GRPC_ADDRESS]

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

ibft candidates flags

grpc-address

• Syntax

• Example

ibft candidates [--grpc-address GRPC_ADDRESS]

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

ibft propose flags

vote

• Syntax

• Example

ibft propose --vote VOTE

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

---

addr

• Syntax

• Example

ibft propose --addr ETH_ADDRESS

Address of the account to be voted for.

---

bls

• Syntax

• Example

ibft propose --bls BLS_PUBLIC_KEY

BLS Public Key of the account to be voted for, necessary only in BLS mode.

---

grpc-address

• Syntax

• Example

ibft candidates [--grpc-address GRPC_ADDRESS]

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

ibft status flags

grpc-address

• Syntax

• Example

ibft status [--grpc-address GRPC_ADDRESS]

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

ibft switch flags

chain

• Syntax

• Example

ibft switch [--chain GENESIS_FILE]

Specifies the genesis file to update. Default: ./genesis.json.

---

type

• Syntax

• Example

ibft switch [--type TYPE]

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

---

deployment

• Syntax

• Example

ibft switch [--deployment DEPLOYMENT]

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

---

from

• Syntax

• Example

ibft switch [--from FROM]

---

ibft-validator-type

• Syntax

• Example

 ibft switch [--ibft-validator-type IBFT_VALIDATOR_TYPE]

Specifies the validation mode of block headers. Possible values: [ecdsa, bls]. Default: bls.

---

ibft-validators-prefix-path

• Syntax

• Example

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

Prefix path for the directories of new validators. Needs to be present if the flag ibft-validator is omitted. Available only when the IBFT mode is PoA (--pos flag is omitted).

---

ibft-validator

• Syntax

• Example

 ibft switch [--ibft-validator IBFT_VALIDATOR_LIST]

Sets passed in addresses as IBFT validators used after the fork. Needs to be present if the flag ibft-validators-prefix-path is omitted. Available only in PoA mode.

1. If the network is running with ECDSA, the format is --ibft-validator [ADDRESS].

2. If the network is running with BLS, the format is --ibft-validator [ADDRESS][BLS_PUBLIC_KEY].

---

max-validator-count

• Syntax

• Example

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

• Syntax

• Example

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.

---

ibft quorum flags

from

• Syntax

• Example

ibft quorum [--from your_quorum_switch_block_num]

The height to switch the quorum calculation to QuorumOptimal, which uses the formula (2/3 * N), N being the number of validator nodes. Please note that this is for backwards compatibility, ie. only for chains that used a Quorum legacy calculation up to a certain block height.

---

chain

• Syntax

• Example

ibft quorum [--chain GENESIS_FILE]

Specifies the genesis file to update. Default: ./genesis.json.

Transaction Pool Commands​

Command	Description
txpool status	Returns the number of transactions in the pool
txpool subscribe	Subscribes for events in the transaction pool

txpool status flags

grpc-address

• Syntax

• Example

txpool status [--grpc-address GRPC_ADDRESS]

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

txpool subscribe flags

grpc-address

• Syntax

• Example

txpool subscribe [--grpc-address GRPC_ADDRESS]

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

---

promoted

• Syntax

• Example

txpool subscribe [--promoted LISTEN_PROMOTED]

Subscribes for promoted tx events in the TxPool.

---

dropped

• Syntax

• Example

txpool subscribe [--dropped LISTEN_DROPPED]

Subscribes for dropped tx events in the TxPool.

---

demoted

• Syntax

• Example

txpool subscribe [--demoted LISTEN_DEMOTED]

Subscribes for demoted tx events in the TxPool.

---

added

• Syntax

• Example

txpool subscribe [--added LISTEN_ADDED]

Subscribes for added tx events to the TxPool.

---

enqueued

• Syntax

• Example

txpool subscribe [--enqueued LISTEN_ENQUEUED]

Subscribes for enqueued tx events in the account queues.

---

Blockchain commands​

Command	Description
status	Returns the status of the client. The detailed response can be found below
monitor	Subscribes to a blockchain event stream. The detailed response can be found below
version	Returns the current version of the client

status flags

grpc-address

• Syntax

• Example

status [--grpc-address GRPC_ADDRESS]

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

monitor flags

grpc-address

• Syntax

• Example

monitor [--grpc-address GRPC_ADDRESS]

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

---

version command

• Syntax

version

Displays release version, git branch, commit hash and build time.

Secrets Commands​

Command	Description
secrets init	Initializes the private keys to the corresponding secrets manager
secrets generate	Generates a secrets manager configuration file which can be parsed by the Polygon Edge
secrets output	Prints the BLS public key address, validator public key address, and node id for reference

secrets init flags​

config

• Syntax

• Example

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

• Syntax

• Example

secrets init [--data-dir DATA_DIRECTORY]

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

---

ecdsa

• Syntax

• Example

secrets init [--ecdsa FLAG]

Sets the flag indicating whether to generate an ECDSA key. Default: true.

---

network

• Syntax

• Example

secrets init [--network FLAG]

Sets the flag indicating whether to generate a Libp2p Network key. Default: true.

---

bls

• Syntax

• Example

secrets init [--bls FLAG]

Sets the flag indicating whether to generate a BLS key. Default: true.

secrets generate flags​

dir

• Syntax

• Example

secrets generate [--dir DATA_DIRECTORY]

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

---

type

• Syntax

• Example

secrets generate [--type TYPE]

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

---

token

• Syntax

• Example

secrets generate [--token TOKEN]

Specifies the access token for the service

---

server-url

• Syntax

• Example

secrets generate [--server-url SERVER_URL]

Specifies the server URL for the service

---

name

• Syntax

• Example

secrets generate [--name NODE_NAME]

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

---

namespace

• Syntax

• Example

secrets generate [--namespace NAMESPACE]

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

secrets output flags​

bls

• Syntax

• Example

secrets output [--bls FLAG]

Sets the flag indicating whether to only output the BLS public key. Default: true

---

config

• Syntax

• Example

secrets output [--config SECRETS_CONFIG]

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

---

data-dir

• Syntax

• Example

secrets output [--data-dir DATA_DIRECTORY]

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

---

node-id

• Syntax

• Example

secrets output [--node-id FLAG]

Sets the flag indicating whether to only output the network node ID. Default: true

---

validator

• Syntax

• Example

secrets output [--validator FLAG]

Sets the flag indicating whether to only output the validator address. Default: true

---

Responses​

Status Response​

The response object is defined using Protocol Buffers.

minimal/proto/system.proto

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

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​

whitelist commands​

Command	Description
whitelist show	Displays whitelist information
whitelist deployment	Updates the smart contract deployment whitelist

whitelist show

• Syntax

whitelist show

Displays whitelist information.

---

• Syntax

• Example

whitelist show [--chain GENESIS_FILE]

Specifies the genesis file to update. Default: ./genesis.json.

---

whitelist deployment

chain

• Syntax

• Example

whitelist deployment [--chain GENESIS_FILE]

Specifies the genesis file to update. Default: ./genesis.json.

---

add

• Syntax

• Example

whitelist deployment [--add ADDRESS]

Adds a new address to the contract deployment whitelist. Only the addresses in the contract deployment whitelist can deploy contracts. If empty, any address can execute the contract deployment

---

remove

• Syntax

• Example

whitelist deployment [--remove ADDRESS]

Removes an address from the contract deployment whitelist. Only the addresses in the contract deployment whitelist can deploy contracts. If empty, any address can execute the contract deployment

---

backup flags​

grpc-address

• Syntax

• Example

backup [--grpc-address GRPC_ADDRESS]

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

---

out

• Syntax

• Example

backup [--out OUT]

Path of archive file to save.

---

from

• Syntax

• Example

from [--from FROM]

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

---

to

• Syntax

• Example

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:

{
    "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