added a toml configuration file with comments describing each flag (#607)

* added a toml configuration file with comments describing each flag

* internal/cli/server: update flag description

* docs/cli: update example config and description of flags

* docs: update new-cli docs

Co-authored-by: Manav Darji <manavdarji.india@gmail.com>

docs/README.md

@@ -1,9 +1,7 @@
 
 # Documentation
 
-- [Command-line-interface](./cli)
+- [The new command line interface](./cli)
-
-- [Configuration file](./config.md)
 
 ## Additional notes
 
@@ -13,8 +11,14 @@
   $ bor server <flags>
   ```
 
-- Toml files used earlier just to configure static/trusted nodes are being deprecated. Instead, a toml file now can be used instead of flags and can contain all configuration for the node to run. The link to a sample config file is given above. To simply run bor with a configuration file, the following command can be used. 
+- The `bor dumpconfig` sub-command prints the default configurations, in the TOML format, on the terminal. One can `pipe (>)` this to a file (say `config.toml`) and use it to start bor. 
+
+- A toml file now can be used instead of flags and can contain all configuration for the node to run. To simply run bor with a configuration file, the following command can be used. 
 
   ```
   $ bor server --config <path_to_config.toml>
   ```
+
+- You can find an example config file [here](./cli/example_config.toml) to know more about what each flag is used for, what are the defaults and recommended values for different networks. 
+
+- Toml files used earlier (with `--config` flag) to configure additional fields (like static and trusted nodes) are being deprecated and have been converted to flags. 

docs/cli/example_config.toml

@@ -0,0 +1,141 @@
+# This configuration file is for reference and learning purpose only.
+# The default value of the flags is provided below (except a few flags which has custom defaults which are explicitly mentioned).
+# Recommended values for mainnet and/or mumbai are also provided.
+
+chain = "mainnet"            # Name of the chain to sync ("mumbai", "mainnet") or path to a genesis file
+identity = "Annon-Identity"  # Name/Identity of the node (default = OS hostname)
+log-level = "INFO"           # Set log level for the server
+datadir = "var/lib/bor"      # Path of the data directory to store information
+keystore = ""                # Path of the directory where keystores are located
+syncmode = "full"            # Blockchain sync mode (only "full" sync supported)
+gcmode = "full"              # Blockchain garbage collection mode ("full", "archive")
+snapshot = true              # Enables the snapshot-database mode
+"bor.logs" = false           # Enables bor log retrieval
+ethstats = ""                # Reporting URL of a ethstats service (nodename:secret@host:port)
+
+["eth.requiredblocks"]  # Comma separated block number-to-hash mappings to require for peering (<number>=<hash>) (default = empty map)
+  "31000000" = "0x2087b9e2b353209c2c21e370c82daa12278efd0fe5f0febe6c29035352cf050e"
+  "32000000" = "0x875500011e5eecc0c554f95d07b31cf59df4ca2505f4dbbfffa7d4e4da917c68"
+
+[p2p]
+  maxpeers = 50       # Maximum number of network peers (network disabled if set to 0)
+  maxpendpeers = 50   # Maximum number of pending connection attempts
+  bind = "0.0.0.0"    # Network binding address
+  port = 30303        # Network listening port
+  nodiscover = false  # Disables the peer discovery mechanism (manual peer addition)
+  nat = "any"         # NAT port mapping mechanism (any|none|upnp|pmp|extip:<IP>)
+  [p2p.discovery]
+    v5disc = false      # Enables the experimental RLPx V5 (Topic Discovery) mechanism
+    bootnodes = []      # Comma separated enode URLs for P2P discovery bootstrap
+    bootnodesv4 = []    # List of initial v4 bootnodes
+    bootnodesv5 = []    # List of initial v5 bootnodes
+    static-nodes = []   # List of static nodes
+    trusted-nodes = []  # List of trusted nodes
+    dns = []            # List of enrtree:// URLs which will be queried for nodes to connect to
+
+[heimdall]
+  url = "http://localhost:1317"  # URL of Heimdall service
+  "bor.without" = false          # Run without Heimdall service (for testing purpose)
+  grpc-address = ""              # Address of Heimdall gRPC service
+
+[txpool]
+  locals = []                   # Comma separated accounts to treat as locals (no flush, priority inclusion)
+  nolocals = false              # Disables price exemptions for locally submitted transactions
+  journal = "transactions.rlp"  # Disk journal for local transaction to survive node restarts
+  rejournal = "1h0m0s"          # Time interval to regenerate the local transaction journal
+  pricelimit = 1                # Minimum gas price limit to enforce for acceptance into the pool (mainnet = 30000000000)
+  pricebump = 10                # Price bump percentage to replace an already existing transaction
+  accountslots = 16             # Minimum number of executable transaction slots guaranteed per account
+  globalslots = 32768           # Maximum number of executable transaction slots for all accounts
+  accountqueue = 16             # Maximum number of non-executable transaction slots permitted per account
+  globalqueue = 32768           # Maximum number of non-executable transaction slots for all accounts
+  lifetime = "3h0m0s"           # Maximum amount of time non-executable transaction are queued
+
+[miner]
+  mine = false             # Enable mining
+  etherbase = ""           # Public address for block mining rewards
+  extradata = ""           # Block extra data set by the miner (default = client version)
+  gaslimit = 30000000      # Target gas ceiling for mined blocks
+  gasprice = "1000000000"  # Minimum gas price for mining a transaction (recommended for mainnet = 30000000000, default suitable for mumbai/devnet)
+
+[jsonrpc]
+  ipcdisable = false                               # Disable the IPC-RPC server
+  ipcpath = ""                                     # Filename for IPC socket/pipe within the datadir (explicit paths escape it)
+  gascap = 50000000                                # Sets a cap on gas that can be used in eth_call/estimateGas (0=infinite)
+  txfeecap = 5.0                                   # Sets a cap on transaction fee (in ether) that can be sent via the RPC APIs (0 = no cap)
+  [jsonrpc.http]
+    enabled = false                                # Enable the HTTP-RPC server
+    port = 8545                                    # http.port
+    prefix = ""                                    # http.rpcprefix
+    host = "localhost"                             # HTTP-RPC server listening interface
+    api = ["eth", "net", "web3", "txpool", "bor"]  # API's offered over the HTTP-RPC interface
+    vhosts = ["localhost"]                         # Comma separated list of virtual hostnames from which to accept requests (server enforced). Accepts '*' wildcard.
+    corsdomain = ["localhost"]                     # Comma separated list of domains from which to accept cross origin requests (browser enforced)
+  [jsonrpc.ws]
+    enabled = false          # Enable the WS-RPC server
+    port = 8546              # WS-RPC server listening port
+    prefix = ""              # HTTP path prefix on which JSON-RPC is served. Use '/' to serve on all paths.
+    host = "localhost"       # ws.addr
+    api = ["net", "web3"]    # API's offered over the WS-RPC interface
+    origins = ["localhost"]  # Origins from which to accept websockets requests
+  [jsonrpc.graphql]
+    enabled = false             # Enable GraphQL on the HTTP-RPC server. Note that GraphQL can only be started if an HTTP server is started as well.
+    port = 0                    # 
+    prefix = ""                 # 
+    host = ""                   # 
+    vhosts = ["localhost"]      # Comma separated list of virtual hostnames from which to accept requests (server enforced). Accepts '*' wildcard.
+    corsdomain = ["localhost"]  # Comma separated list of domains from which to accept cross origin requests (browser enforced)
+
+[gpo]
+  blocks = 20                 # Number of recent blocks to check for gas prices
+  percentile = 60             # Suggested gas price is the given percentile of a set of recent transaction gas prices
+  maxprice = "5000000000000"  # Maximum gas price will be recommended by gpo
+  ignoreprice = "2"           # Gas price below which gpo will ignore transactions (recommended for mainnet = 30000000000, default suitable for mumbai/devnet)
+
+[telemetry]
+  metrics = false                            # Enable metrics collection and reporting
+  expensive = false                          # Enable expensive metrics collection and reporting
+  prometheus-addr = "127.0.0.1:7071"         # Address for Prometheus Server
+  opencollector-endpoint = "127.0.0.1:4317"  # OpenCollector Endpoint (host:port)
+  [telemetry.influx]
+    influxdb = false    # Enable metrics export/push to an external InfluxDB database (v1)
+    endpoint = ""       # InfluxDB API endpoint to report metrics to
+    database = ""       # InfluxDB database name to push reported metrics to
+    username = ""       # Username to authorize access to the database
+    password = ""       # Password to authorize access to the database
+    influxdbv2 = false  # Enable metrics export/push to an external InfluxDB v2 database
+    token = ""          # Token to authorize access to the database (v2 only)
+    bucket = ""         # InfluxDB bucket name to push reported metrics to (v2 only)
+    organization = ""   # InfluxDB organization name (v2 only)
+    [telemetry.influx.tags]  # Comma-separated InfluxDB tags (key/values) attached to all measurements
+      cloud = "aws"
+      host = "annon-host"
+      ip = "99.911.221.66"
+      region = "us-north-1"
+
+[cache]
+  cache = 1024             # Megabytes of memory allocated to internal caching (recommended for mainnet = 4096, default suitable for mumbai/devnet)
+  gc = 25                  # Percentage of cache memory allowance to use for trie pruning (default = 25% full mode, 0% archive mode)
+  snapshot = 10            # Percentage of cache memory allowance to use for snapshot caching (default = 10% full mode, 20% archive mode)
+  database = 50            # Percentage of cache memory allowance to use for database io
+  trie = 15                # Percentage of cache memory allowance to use for trie caching (default = 15% full mode, 30% archive mode)
+  journal = "triecache"    # Disk journal directory for trie cache to survive node restarts
+  rejournal = "1h0m0s"     # Time interval to regenerate the trie cache journal
+  noprefetch = false       # Disable heuristic state prefetch during block import (less CPU and disk IO, more time waiting for data)
+  preimages = false        # Enable recording the SHA3/keccak preimages of trie keys
+  txlookuplimit = 2350000  # Number of recent blocks to maintain transactions index for (default = about 56 days, 0 = entire chain)
+  triesinmemory = 128      # Number of block states (tries) to keep in memory
+
+[accounts]
+  unlock = []                    # Comma separated list of accounts to unlock
+  password = ""                  # Password file to use for non-interactive password input
+  allow-insecure-unlock = false  # Allow insecure account unlocking when account-related RPCs are exposed by http
+  lightkdf = false               # Reduce key-derivation RAM & CPU usage at some expense of KDF strength
+  disable-bor-wallet = true      # Disable the personal wallet endpoints
+
+[grpc]
+  addr = ":3131" # Address and port to bind the GRPC server
+
+[developer]
+  dev = false  # Enable developer mode with ephemeral proof-of-authority network and a pre-funded developer account, mining enabled
+  period = 0   # Block period to use in developer mode (0 = mine only if transaction pending)

docs/cli/server.md

@@ -4,7 +4,7 @@ The ```bor server``` command runs the Bor client.
 
 ## Options
 
-- ```chain```: Name of the chain to sync
+- ```chain```: Name of the chain to sync ('mumbai', 'mainnet') or path to a genesis file
 
 - ```identity```: Name/Identity of the node
 
@@ -12,7 +12,7 @@ The ```bor server``` command runs the Bor client.
 
 - ```datadir```: Path of the data directory to store information
 
-- ```keystore```: Path of the directory to store keystores
+- ```keystore```: Path of the directory where keystores are located
 
 - ```config```: File for the config file
 
@@ -30,8 +30,6 @@ The ```bor server``` command runs the Bor client.
 
 - ```bor.withoutheimdall```: Run without Heimdall service (for testing purpose)
 
-- ```bor.heimdallgRPC```: Address of Heimdall gRPC service
-
 - ```ethstats```: Reporting URL of a ethstats service (nodename:secret@host:port)
 
 - ```gpo.blocks```: Number of recent blocks to check for gas prices
@@ -80,8 +78,6 @@ The ```bor server``` command runs the Bor client.
 
 - ```cache.preimages```: Enable recording the SHA3/keccak preimages of trie keys
 
-- ```cache.triesinmemory```: Number of block states (tries) to keep in memory (default = 128)
-
 - ```txlookuplimit```: Number of recent blocks to maintain transactions index for (default = about 56 days, 0 = entire chain)
 
 ### JsonRPC Options
@@ -136,7 +132,7 @@ The ```bor server``` command runs the Bor client.
 
 - ```maxpeers```: Maximum number of network peers (network disabled if set to 0)
 
-- ```maxpendpeers```: Maximum number of pending connection attempts (defaults used if set to 0)
+- ```maxpendpeers```: Maximum number of pending connection attempts
 
 - ```nat```: NAT port mapping mechanism (any|none|upnp|pmp|extip:<IP>)
 
@@ -148,11 +144,11 @@ The ```bor server``` command runs the Bor client.
 
 - ```mine```: Enable mining
 
-- ```miner.etherbase```: Public address for block mining rewards (default = first account)
+- ```miner.etherbase```: Public address for block mining rewards
 
 - ```miner.extradata```: Block extra data set by the miner (default = client version)
 
-- ```miner.gaslimit```: Target gas ceiling for mined blocks
+- ```miner.gaslimit```: Target gas ceiling (gas limit) for mined blocks
 
 - ```miner.gasprice```: Minimum gas price for mining a transaction
 

docs/config.md

@@ -1,146 +0,0 @@
-
-# Config
-
-- The `bor dumpconfig` command prints the default configurations, in the TOML format, on the terminal.
-    - One can `pipe (>)` this to a file (say `config.toml`) and use it to start bor.
-        - Command to provide a config file: `bor server -config config.toml`
-- Bor uses TOML, HCL, and JSON format config files.
-- This is the format of the config file in TOML:
-    - **NOTE: The values of these following flags are just for reference**
-    - `config.toml` file:
-```
-chain = "mainnet"
-identity = "myIdentity"
-log-level = "INFO"
-datadir = "/var/lib/bor/data"
-keystore = "path/to/keystore"
-syncmode = "full"
-gcmode = "full"
-snapshot = true
-ethstats = ""
-
-["eth.requiredblocks"]
-
-[p2p]
-maxpeers = 50
-maxpendpeers = 50
-bind = "0.0.0.0"
-port = 30303
-nodiscover = false
-nat = "any"
-
-[p2p.discovery]
-v5disc = false
-bootnodes = ["enode://d860a01f9722d78051619d1e2351aba3f43f943f6f00718d1b9baa4101932a1f5011f16bb2b1bb35db20d6fe28fa0bf09636d26a87d31de9ec6203eeedb1f666@18.138.108.67:30303", "enode://22a8232c3abc76a16ae9d6c3b164f98775fe226f0917b0ca871128a74a8e9630b458460865bab457221f1d448dd9791d24c4e5d88786180ac185df813a68d4de@3.209.45.79:30303"]
-bootnodesv4 = []
-bootnodesv5 = ["enr:-KG4QOtcP9X1FbIMOe17QNMKqDxCpm14jcX5tiOE4_TyMrFqbmhPZHK_ZPG2Gxb1GE2xdtodOfx9-cgvNtxnRyHEmC0ghGV0aDKQ9aX9QgAAAAD__________4JpZIJ2NIJpcIQDE8KdiXNlY3AyNTZrMaEDhpehBDbZjM_L9ek699Y7vhUJ-eAdMyQW_Fil522Y0fODdGNwgiMog3VkcIIjKA", "enr:-KG4QDyytgmE4f7AnvW-ZaUOIi9i79qX4JwjRAiXBZCU65wOfBu-3Nb5I7b_Rmg3KCOcZM_C3y5pg7EBU5XGrcLTduQEhGV0aDKQ9aX9QgAAAAD__________4JpZIJ2NIJpcIQ2_DUbiXNlY3AyNTZrMaEDKnz_-ps3UUOfHWVYaskI5kWYO_vtYMGYCQRAR3gHDouDdGNwgiMog3VkcIIjKA"]
-static-nodes = ["enode://8499da03c47d637b20eee24eec3c356c9a2e6148d6fe25ca195c7949ab8ec2c03e3556126b0d7ed644675e78c4318b08691b7b57de10e5f0d40d05b09238fa0a@52.187.207.27:30303"]
-trusted-nodes = ["enode://2b252ab6a1d0f971d9722cb839a42cb81db019ba44c08754628ab4a823487071b5695317c8ccd085219c3a03af063495b2f1da8d18218da2d6a82981b45e6ffc@65.108.70.101:30303"]
-dns = []
-
-[heimdall]
-url = "http://localhost:1317"
-"bor.without" = false
-
-[txpool]
-locals = ["$ADDRESS1", "$ADDRESS2"]
-nolocals = false
-journal = ""
-rejournal = "1h0m0s"
-pricelimit = 30000000000
-pricebump = 10
-accountslots = 16
-globalslots = 32768
-accountqueue = 16
-globalqueue = 32768
-lifetime = "3h0m0s"
-
-[miner]
-mine = false
-etherbase = ""
-extradata = ""
-gaslimit = 20000000
-gasprice = "30000000000"
-
-[jsonrpc]
-ipcdisable = false
-ipcpath = "/var/lib/bor/bor.ipc"
-gascap = 50000000
-txfeecap = 5e+00
-
-[jsonrpc.http]
-enabled = false
-port = 8545
-prefix = ""
-host = "localhost"
-api = ["eth", "net", "web3", "txpool", "bor"]
-vhosts = ["*"]
-corsdomain = ["*"]
-
-[jsonrpc.ws]
-enabled = false
-port = 8546
-prefix = ""
-host = "localhost"
-api = ["web3", "net"]
-vhosts = ["*"]
-corsdomain = ["*"]
-
-[jsonrpc.graphql]
-enabled = false
-port = 0
-prefix = ""
-host = ""
-api = []
-vhosts = ["*"]
-corsdomain = ["*"]
-
-[gpo]
-blocks = 20
-percentile = 60
-maxprice = "5000000000000"
-ignoreprice = "2"
-
-[telemetry]
-metrics = false
-expensive = false
-prometheus-addr = ""
-opencollector-endpoint = ""
-
-[telemetry.influx]
-influxdb = false
-endpoint = ""
-database = ""
-username = ""
-password = ""
-influxdbv2 = false
-token = ""
-bucket = ""
-organization = ""
-
-[cache]
-cache = 1024
-gc = 25
-snapshot = 10
-database = 50
-trie = 15
-journal = "triecache"
-rejournal = "1h0m0s"
-noprefetch = false
-preimages = false
-txlookuplimit = 2350000
-
-[accounts]
-unlock = ["$ADDRESS1", "$ADDRESS2"]
-password = "path/to/password.txt"
-allow-insecure-unlock = false
-lightkdf = false
-disable-bor-wallet = false
-
-[grpc]
-addr = ":3131"
-
-[developer]
-dev = false
-period = 0
-```

internal/cli/server/flags.go

@@ -11,7 +11,7 @@ func (c *Command) Flags() *flagset.Flagset {
 
 	f.StringFlag(&flagset.StringFlag{
 		Name:    "chain",
-		Usage:   "Name of the chain to sync",
+		Usage:   "Name of the chain to sync ('mumbai', 'mainnet') or path to a genesis file",
 		Value:   &c.cliConfig.Chain,
 		Default: c.cliConfig.Chain,
 	})
@@ -35,7 +35,7 @@ func (c *Command) Flags() *flagset.Flagset {
 	})
 	f.StringFlag(&flagset.StringFlag{
 		Name:  "keystore",
-		Usage: "Path of the directory to store keystores",
+		Usage: "Path of the directory where keystores are located",
 		Value: &c.cliConfig.KeyStoreDir,
 	})
 	f.StringFlag(&flagset.StringFlag{
@@ -176,7 +176,7 @@ func (c *Command) Flags() *flagset.Flagset {
 	})
 	f.StringFlag(&flagset.StringFlag{
 		Name:    "miner.etherbase",
-		Usage:   "Public address for block mining rewards (default = first account)",
+		Usage:   "Public address for block mining rewards",
 		Value:   &c.cliConfig.Sealer.Etherbase,
 		Default: c.cliConfig.Sealer.Etherbase,
 		Group:   "Sealer",
@@ -190,7 +190,7 @@ func (c *Command) Flags() *flagset.Flagset {
 	})
 	f.Uint64Flag(&flagset.Uint64Flag{
 		Name:    "miner.gaslimit",
-		Usage:   "Target gas ceiling for mined blocks",
+		Usage:   "Target gas ceiling (gas limit) for mined blocks",
 		Value:   &c.cliConfig.Sealer.GasCeil,
 		Default: c.cliConfig.Sealer.GasCeil,
 		Group:   "Sealer",
@@ -485,7 +485,7 @@ func (c *Command) Flags() *flagset.Flagset {
 	})
 	f.Uint64Flag(&flagset.Uint64Flag{
 		Name:    "maxpendpeers",
-		Usage:   "Maximum number of pending connection attempts (defaults used if set to 0)",
+		Usage:   "Maximum number of pending connection attempts",
 		Value:   &c.cliConfig.P2P.MaxPendPeers,
 		Default: c.cliConfig.P2P.MaxPendPeers,
 		Group:   "P2P",