Skip to main content

CLI Commands

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

Startup Commands

CommandDescription
serverThe default command that starts the blockchain client, by bootstrapping all modules together
dev"Bypasses" consensus and networking and starts a blockchain locally. It starts a local node and mines every transaction in a separate block
genesisGenerates a genesis.json file, which is used to set predefined chain state before starting the client. The structure of the genesis file is described below

server flags

seal

server [--seal SHOULD_SEAL]

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


data-dir

server [--data-dir DATA_DIRECTORY]

Specifies the data directory used for storing Polygon SDK client data. Default: `./test-chain.


jsonrpc

server [--jsonrpc JSONRPC_ADDRESS]

Sets the address and port for the JSON-RPC service address:port. Default address: 127.0.0.1:8545.


grpc

server [--grpc GRPC_ADDRESS]

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


libp2p

server [--libp2p LIBP2P_ADDRESS]

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


prometheus

server [--prometheus PROMETHEUS_ADDRESS]

Sets the address and port for the prometheus server address:port.


block-gas-target

server [--block-gas-target BLOCK_GAS_TARGET]

Sets the target block gas limit for the chain. Default: 8000000.

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


max-peers

server [--max-peers PEER_COUNT]

Sets the client's max peer count. Default: 20.


log-level

server [--log-level LOG_LEVEL]

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


chain

server [--chain GENESIS_FILE]

Specifies the genesis file used for starting the chain. Default: test.


join

server [--join JOIN_ADDRESS]

Specifies the address of the peer that should be joined.


nat

server [--nat NAT_ADDRESS]

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


dns

server [--dns DNS_ADDRESS]

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


locals

server [--locals LOCALS]

Sets comma separated accounts whose transactions are treated as locals


nolocals

server [--nolocals]

Sets flag to disable price exemptions for locally submitted transactions


price-limit

server [--price-limit PRICE_LIMIT]

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


max-slots

server [--max-slots MAX_SLOTS]

Sets maximum slots in the pool. Default: 4096.


config

server [--config CLI_CONFIG_PATH]

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


secrets-config

server [--secrets-config SECRETS_CONFIG]

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


dev

server [--dev DEV_MODE]

Sets the client to dev mode. Default: false.


dev-interval

server [--dev-interval DEV_INTERVAL]

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


no-discover

server [--no-discover NO_DISCOVER]

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

dev flags

log-level

dev [--log-level LOG_LEVEL]

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


premine

dev [--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.


block-gas-target

server [--block-gas-target BLOCK_GAS_TARGET]

Sets the target block gas limit for the chain. Default: 8000000.

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


dev-interval

dev [--dev-interval DEV_INTERVAL]

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


block-gas-limit

dev [--block-gas-limit BLOCK_GAS_LIMIT]

Sets the gas limit of each block. Default: 5000.


chainid

dev [--chainid CHAIN_ID]

Sets the ID of the chain. Default: 100.


locals

dev [--locals LOCALS]

Sets comma separated accounts whose transactions are treated as locals


nolocals

dev [--nolocals]

Sets flag to disable price exemptions for locally submitted transactions


price-limit

dev [--price-limit PRICE_LIMIT]

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


max-slots

dev [--max-slots MAX_SLOTS]

Sets maximum slots in the pool. Default: 4096.


genesis flags

dir

genesis [--dir DIRECTORY]

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


name

genesis [--name NAME]

Sets the name for the chain. Default: example.


premine

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

genesis [--chainid CHAIN_ID]

Sets the ID of the chain. Default: 100.


ibft-validators-prefix-path

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

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

genesis [--block-gas-limit BLOCK_GAS_LIMIT]

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


consensus

genesis [--consensus CONSENSUS_PROTOCOL]

Sets consensus protocol. Default: pow.


bootnode

genesis [--bootnode BOOTNODE_URL]

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


Operator Commands

Peer Commands

CommandDescription
peers addAdds a new peer using their libp2p address
peers listLists all the peers the client is connected to through libp2p
peers statusReturns the status of a specific peer from the peers list, using the libp2p address

peers add flags

addr

peers add --addr PEER_ADDRESS

Peer's libp2p address in the multiaddr format.


grpc-address

peers add [--grpc-address GRPC_ADDRESS]

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

peers list flags

grpc-address

peers list [--grpc-address GRPC_ADDRESS]

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

peers status flags

peer-id

peers status --peer-id PEER_ID

Libp2p node ID of a specific peer within p2p network.


grpc-address

peers status [--grpc-address GRPC_ADDRESS]

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

IBFT Commands

CommandDescription
ibft snapshotReturns the IBFT snapshot
ibft candidatesQueries the current set of proposed candidates, as well as candidates that have not been included yet
ibft proposeProposes a new candidate to be added / removed from the validator set
ibft statusReturns the overall status of the IBFT client

ibft snapshot flags

number

ibft snapshot [--number BLOCK_NUMBER]

The block height (number) for the snapshot.


grpc-address

ibft snapshot [--grpc-address GRPC_ADDRESS]

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

ibft candidates flags

grpc-address

ibft candidates [--grpc-address GRPC_ADDRESS]

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

ibft propose flags

vote

ibft propose --vote VOTE

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


addr

ibft propose --addr ETH_ADDRESS

Address of the account to be voted for.


grpc-address

ibft candidates [--grpc-address GRPC_ADDRESS]

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

ibft status flags

grpc-address

ibft status [--grpc-address GRPC_ADDRESS]

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

Transaction Pool Commands

CommandDescription
txpool addAdds a transaction to the transaction pool, using different flags
txpool statusReturns the number of transactions in the pool

txpool add flags

from

txpool add --from ADDRESS

The sender address.


to

txpool add --to ADDRESS

The receiver address.


value

txpool add --value VALUE

The value of the transaction in wei.


gasPrice

txpool add --gasPrice GASPRICE

The gas price in wei.


nonce

txpool add [--nonce NONCE]

The nonce of the transaction.


gasLimit

txpool add [--gasLimit LIMIT]

The specified gas limit in wei.


grpc-address

txpool add [--grpc-address GRPC_ADDRESS]

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

txpool status flags

grpc-address

txpool status [--grpc-address GRPC_ADDRESS]

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

Blockchain commands

CommandDescription
statusReturns the status of the client. The detailed response can be found below
monitorSubscribes to a blockchain event stream. The detailed response can be found below
versionReturns the current version of the client

status flags

grpc-address

status [--grpc-address GRPC_ADDRESS]

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

monitor flags

grpc-address

monitor [--grpc-address GRPC_ADDRESS]

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


Secrets Commands

CommandDescription
secrets initInitializes the private keys to the corresponding secrets manager
secrets generateGenerates a secrets manager configuration file which can be parsed by the Polygon SDK

secrets init flags

config

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

secrets init [--data-dir DATA_DIRECTORY]

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

secrets generate flags

dir

secrets generate [--dir DATA_DIRECTORY]

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


type

secrets generate [--type TYPE]

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


token

secrets generate [--token TOKEN]

Specifies the access token for the service


server-url

secrets generate [--server-url SERVER_URL]

Specifies the server URL for the service


name

secrets generate [--name NODE_NAME]

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

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

loadbot flags

tps

loadbot [--tps NUMBER_OF_TXNS_PER_SECOND]

Number of transactions per second to send. Default: 100.


account

loadbot [--account ADDRESS]

One of the addresses to use when running the stress test.


gasLimit

loadbot [--gasLimit GAS_LIMIT]

The transaction gas limit used when creating transaction objects. Default: 1000000.


gasPrice

loadbot [--gasPrice GAS_PRICE]

The transaction gas price used when creating transaction objects. Default: 0x100000.


url

loadbot [--url ENDPOINT]

A JSON RPC endpoint used to send transactions. You can specify more to send transactions to many nodes during the stress test.


chainId

loadbot [--chainId CHAIN_ID]

The chain ID endpoint used to send transactions. Default: 100.


count

loadbot [--count COUNT]

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


value

loadbot [--value VALUE]

The value to send in each transaction.


grpc

loadbot [--grpc GRPC_ADDRESS]

The gRPC address of a node, used to verify if the TxPool is empty after the stress test.


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