From e9703c7e3fc292f674a4aa09f9a08dce2225ebc1 Mon Sep 17 00:00:00 2001
From: Ferran Borreguero <ferranbt@protonmail.com>
Date: Tue, 26 Oct 2021 14:09:11 +0200
Subject: [PATCH] Add docs for cli and config file (#218)
* Initial docs cli
---
docs/README.md | 36 +++++++
docs/cli/README.md | 18 ++++
docs/cli/account.md | 10 ++
docs/cli/account_import.md | 4 +
docs/cli/account_list.md | 4 +
docs/cli/account_new.md | 4 +
docs/cli/debug.md | 30 ++++++
docs/cli/server.md | 192 +++++++++++++++++++++++++++++++++++++
docs/cli/version.md | 11 +++
docs/config.md | 133 +++++++++++++++++++++++++
10 files changed, 442 insertions(+)
create mode 100644 docs/README.md
create mode 100644 docs/cli/README.md
create mode 100644 docs/cli/account.md
create mode 100644 docs/cli/account_import.md
create mode 100644 docs/cli/account_list.md
create mode 100644 docs/cli/account_new.md
create mode 100644 docs/cli/debug.md
create mode 100644 docs/cli/server.md
create mode 100644 docs/cli/version.md
create mode 100644 docs/config.md
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 000000000..b5d7993d2
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,36 @@
+
+# Documentation
+
+- [Command-line-interface](./cli)
+
+- [Configuration file](./config.md)
+
+## Deprecation notes
+
+- The new entrypoint to run the Bor client is ```server```.
+
+```
+$ bor server
+```
+
+- Toml files to configure nodes are being deprecated. Currently, we only allow for static and trusted nodes to be configured using toml files.
+
+```
+$ bor server --config ./legacy.toml
+```
+
+- Modules, vhost and Cors configuration are common for all jsonrpc endpoints.
+
+Before:
+
+```
+$ bor --http --http.modules "eth,web" --ws --ws.modules "eth,web"
+```
+
+Now:
+
+```
+$ bor server --http --ws --jsonrpc.modules "eth,web"
+```
+
+- ```Admin```, ```Personal``` and account related endpoints in ```Eth``` are being removed from the JsonRPC interface. Some of this functionality will be moved to the new GRPC server for operational tasks.
diff --git a/docs/cli/README.md b/docs/cli/README.md
new file mode 100644
index 000000000..c82bbbe04
--- /dev/null
+++ b/docs/cli/README.md
@@ -0,0 +1,18 @@
+
+# Command line interface
+
+## Commands
+
+- [```server```](./server.md)
+
+- [```debug```](./debug.md)
+
+- [```account```](./account.md)
+
+- [```account new```](./account_new.md)
+
+- [```account list```](./account_list.md)
+
+- [```account import```](./account_import.md)
+
+- [```version```](./version.md)
diff --git a/docs/cli/account.md b/docs/cli/account.md
new file mode 100644
index 000000000..00fd6cbe6
--- /dev/null
+++ b/docs/cli/account.md
@@ -0,0 +1,10 @@
+
+# Account
+
+The ```account``` command groups actions to interact with accounts:
+
+- [```account new```](./account_new.md): Create a new account in the Bor client.
+
+- [```account list```](./account_list.md): List the wallets in the Bor client.
+
+- [```account import```](./account_import.md): Import an account to the Bor client.
diff --git a/docs/cli/account_import.md b/docs/cli/account_import.md
new file mode 100644
index 000000000..2a515866c
--- /dev/null
+++ b/docs/cli/account_import.md
@@ -0,0 +1,4 @@
+
+# Account import
+
+The ```account import``` command imports an account in Json format to the Bor data directory.
diff --git a/docs/cli/account_list.md b/docs/cli/account_list.md
new file mode 100644
index 000000000..4a2d28de9
--- /dev/null
+++ b/docs/cli/account_list.md
@@ -0,0 +1,4 @@
+
+# Account list
+
+The ```account list``` command lists all the accounts in the Bor data directory.
diff --git a/docs/cli/account_new.md b/docs/cli/account_new.md
new file mode 100644
index 000000000..41e53767a
--- /dev/null
+++ b/docs/cli/account_new.md
@@ -0,0 +1,4 @@
+
+# Account new
+
+The ```account new``` command creates a new local account file on the Bor data directory. Bor should not be running to execute this command.
diff --git a/docs/cli/debug.md b/docs/cli/debug.md
new file mode 100644
index 000000000..c75ae79e4
--- /dev/null
+++ b/docs/cli/debug.md
@@ -0,0 +1,30 @@
+
+# Debug
+
+The ```bor debug``` command takes a debug dump of the running client.
+
+## Options
+
+- ```seconds```: Number of seconds to trace cpu and traces.
+
+- ```output```: Output directory for the data dump.
+
+## Examples
+
+By default it creates a tar.gz file with the output:
+
+```
+$ bor debug
+Starting debugger...
+
+Created debug archive: bor-debug-2021-10-26-073819Z.tar.gz
+```
+
+Send the output to a specific directory:
+
+```
+$ bor debug --output data
+Starting debugger...
+
+Created debug directory: data/bor-debug-2021-10-26-075437Z
+```
diff --git a/docs/cli/server.md b/docs/cli/server.md
new file mode 100644
index 000000000..e2d961579
--- /dev/null
+++ b/docs/cli/server.md
@@ -0,0 +1,192 @@
+
+# Server
+
+The ```bor server``` command runs the Bor client.
+
+## General Options
+
+- ```chain```: Name of the chain to sync (mainnet or mumbai).
+
+- ```log-level```: Set log level for the server (info, warn, debug, trace).
+
+- ```datadir```: Path of the data directory to store information (defaults to $HOME).
+
+- ```config```: List of files that contain the configuration.
+
+- ```syncmode```: Blockchain sync mode ("fast", "full", "snap" or "light").
+
+- ```gcmode```: Blockchain garbage collection mode ("full", "archive").
+
+- ```whitelist```: Comma separated block number-to-hash mappings to enforce (<number>=<hash>).
+
+- ```snapshot```: Enables snapshot-database mode (default = enable).
+
+- ```bor.heimdall```: URL of Heimdall service.
+
+- ```bor.withoutheimdall```: Run without Heimdall service (for testing purpose).
+
+- ```ethstats```: Reporting URL of a ethstats service (nodename:secret@host:port).
+
+- ```gpo.blocks```: Number of recent blocks to check for gas prices.
+
+- ```gpo.percentile```: Suggested gas price is the given percentile of a set of recent transaction gas prices.
+
+- ```gpo.maxprice```: Maximum gas price will be recommended by gpo.
+
+- ```gpo.ignoreprice```: Gas price below which gpo will ignore transactions.
+
+- ```grpc.addr```: Address and port to bind the GRPC server.
+
+### Transaction Pool Options
+
+- ```txpool.locals```: Comma separated accounts to treat as locals (no flush, priority inclusion).
+
+- ```txpool.nolocals```: Disables price exemptions for locally submitted transactions
+
+- ```txpool.journal```: Disk journal for local transaction to survive node restarts
+
+- ```txpool.rejournal```: Time interval to regenerate the local transaction journal
+
+- ```txpool.pricelimit```: Minimum gas price limit to enforce for acceptance into the pool
+
+- ```txpool.pricebump```: Price bump percentage to replace an already existing transaction
+
+- ```txpool.accountslots```: Minimum number of executable transaction slots guaranteed per account
+
+- ```txpool.globalslots```: Maximum number of executable transaction slots for all accounts
+
+- ```txpool.accountqueue```: Maximum number of non-executable transaction slots permitted per account
+
+- ```txpool.globalqueue```: Maximum number of non-executable transaction slots for all accounts
+
+- ```txpool.lifetime```: Maximum amount of time non-executable transaction are queued
+
+### Sealer Options
+
+- ```mine```: Enable sealing.
+
+- ```miner.etherbase```: Public address for block mining rewards (default = first account)
+
+- ```miner.extradata```: Block extra data set by the miner (default = client version).
+
+- ```miner.gaslimit```: Target gas ceiling for mined blocks.
+
+- ```miner.gasprice```: Minimum gas price for mining a transaction.
+
+### Cache Options
+
+- ```cache```: Megabytes of memory allocated to internal caching (default = 4096 mainnet full node).
+
+- ```cache.database```: Percentage of cache memory allowance to use for database io.
+
+- ```cache.trie```: Percentage of cache memory allowance to use for trie caching (default = 15% full mode, 30% archive mode).
+
+- ```cache.trie.journal```: Disk journal directory for trie cache to survive node restarts.
+
+- ```cache.trie.rejournal```: Time interval to regenerate the trie cache journal.
+
+- ```cache.gc```: Percentage of cache memory allowance to use for trie pruning (default = 25% full mode, 0% archive mode).
+
+- ```cache.snapshot```: Percentage of cache memory allowance to use for snapshot caching (default = 10% full mode, 20% archive mode).
+
+- ```cache.noprefetch```: Disable heuristic state prefetch during block import (less CPU and disk IO, more time waiting for data).
+
+- ```cache.preimages```: Enable recording the SHA3/keccak preimages of trie keys.
+
+- ```txlookuplimit```: Number of recent blocks to maintain transactions index for (default = about one year, 0 = entire chain).
+
+### JsonRPC Options
+
+- ```rpc.gascap```: Sets a cap on gas that can be used in eth_call/estimateGas (0=infinite).
+
+- ```rpc.txfeecap```: Sets a cap on transaction fee (in ether) that can be sent via the RPC APIs (0 = no cap).
+
+- ```ipcdisable```: Disable the IPC-RPC server.
+
+- ```ipcpath```: Filename for IPC socket/pipe within the datadir (explicit paths escape it).
+
+- ```jsonrpc.corsdomain```: Comma separated list of domains from which to accept cross.
+
+- ```jsonrpc.vhosts```: Comma separated list of virtual hostnames from which to accept requests (server enforced). Accepts '*' wildcard.
+
+- ```jsonrpc.modules```: API's offered over the HTTP-RPC interface.
+
+- ```http```: Enable the HTTP-RPC server.
+
+- ```http.addr```: HTTP-RPC server listening interface.
+
+- ```http.port```: HTTP-RPC server listening port.
+
+- ```http.rpcprefix```: HTTP path path prefix on which JSON-RPC is served. Use '/' to serve on all paths.
+
+- ```ws```: Enable the WS-RPC server.
+
+- ```ws.addr```: WS-RPC server listening interface.
+
+- ```ws.port```: WS-RPC server listening port.
+
+- ```ws.rpcprefix```: HTTP path prefix on which JSON-RPC is served. Use '/' to serve on all paths.
+
+- ```graphql```: Enable GraphQL on the HTTP-RPC server. Note that GraphQL can only be started if an HTTP server is started as well.
+
+### P2P Options
+
+- ```bind```: Network binding address
+
+- ```port```: Network listening port
+
+- ```bootnodes```: Comma separated enode URLs for P2P discovery bootstrap
+
+- ```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)
+
+- ```nat```: "NAT port mapping mechanism (any|none|upnp|pmp|extip:<IP>)
+
+- ```nodiscover```: "Disables the peer discovery mechanism (manual peer addition)
+
+- ```v5disc```: "Enables the experimental RLPx V5 (Topic Discovery) mechanism
+
+### Telemetry Options
+
+- ```metrics```: Enable metrics collection and reporting.
+
+- ```metrics.expensive```: Enable expensive metrics collection and reporting.
+
+- ```metrics.influxdb```: Enable metrics export/push to an external InfluxDB database (v1).
+
+- ```metrics.influxdb.endpoint```: InfluxDB API endpoint to report metrics to.
+
+- ```metrics.influxdb.database```: InfluxDB database name to push reported metrics to.
+
+- ```metrics.influxdb.username```: Username to authorize access to the database.
+
+- ```metrics.influxdb.password```: Password to authorize access to the database.
+
+- ```metrics.influxdb.tags```: Comma-separated InfluxDB tags (key/values) attached to all measurements.
+
+- ```metrics.influxdbv2```: Enable metrics export/push to an external InfluxDB v2 database.
+
+- ```metrics.influxdb.token```: Token to authorize access to the database (v2 only).
+
+- ```metrics.influxdb.bucket```: InfluxDB bucket name to push reported metrics to (v2 only).
+
+- ```metrics.influxdb.organization```: InfluxDB organization name (v2 only).
+
+### Account Management Options
+
+- ```unlock```: "Comma separated list of accounts to unlock.
+
+- ```password```: Password file to use for non-interactive password input.
+
+- ```allow-insecure-unlock```: Allow insecure account unlocking when account-related RPCs are exposed by http.
+
+- ```lightkdf```: Reduce key-derivation RAM & CPU usage at some expense of KDF strength.
+
+## Usage
+
+Use multiple files to configure the client:
+
+```
+$ bor server --config ./legacy-config.toml --config ./config2.hcl
+```
diff --git a/docs/cli/version.md b/docs/cli/version.md
new file mode 100644
index 000000000..156bdf607
--- /dev/null
+++ b/docs/cli/version.md
@@ -0,0 +1,11 @@
+
+# Version
+
+The ```bor version``` command outputs the version of the binary.
+
+## Usage
+
+```
+$ bor version
+0.2.9-stable
+```
diff --git a/docs/config.md b/docs/config.md
new file mode 100644
index 000000000..4f4dec157
--- /dev/null
+++ b/docs/config.md
@@ -0,0 +1,133 @@
+
+# Config
+
+Toml files format used in geth are being deprecated.
+
+Bor uses uses JSON and [HCL](https://github.com/hashicorp/hcl) formats to create configuration files. This is the format in HCL alongside the default values:
+
+```
+chain = "mainnet"
+log-level = "info"
+data-dir = ""
+sync-mode = "fast"
+gc-mode = "full"
+snapshot = true
+ethstats = ""
+whitelist = {}
+
+p2p {
+ max-peers = 30
+ max-pend-peers = 50
+ bind = "0.0.0.0"
+ port = 30303
+ no-discover = false
+ nat = "any"
+ discovery {
+ v5-enabled = false
+ bootnodes = []
+ bootnodesv4 = []
+ bootnodesv5 = []
+ staticNodes = []
+ trustedNodes = []
+ dns = []
+ }
+}
+
+heimdall {
+ url = "http://localhost:1317"
+ without = false
+}
+
+txpool {
+ locals = []
+ no-locals = false
+ journal = ""
+ rejournal = "1h"
+ price-limit = 1
+ price-bump = 10
+ account-slots = 16
+ global-slots = 4096
+ account-queue = 64
+ global-queue = 1024
+ lifetime = "3h"
+}
+
+sealer {
+ enabled = false
+ etherbase = ""
+ gas-ceil = 8000000
+ extra-data = ""
+}
+
+gpo {
+ blocks = 20
+ percentile = 60
+}
+
+jsonrpc {
+ ipc-disable = false
+ ipc-path = ""
+ modules = ["web3", "net"]
+ cors = ["*"]
+ vhost = ["*"]
+
+ http {
+ enabled = false
+ port = 8545
+ prefix = ""
+ host = "localhost"
+ }
+
+ ws {
+ enabled = false
+ port = 8546
+ prefix = ""
+ host = "localhost"
+ }
+
+ graphqh {
+ enabled = false
+ }
+}
+
+telemetry {
+ enabled = false
+ expensive = false
+
+ influxdb {
+ v1-enabled = false
+ endpoint = ""
+ database = ""
+ username = ""
+ password = ""
+ v2-enabled = false
+ token = ""
+ bucket = ""
+ organization = ""
+ }
+}
+
+cache {
+ cache = 1024
+ perc-database = 50
+ perc-trie = 15
+ perc-gc = 25
+ perc-snapshot = 10
+ journal = "triecache"
+ rejournal = "60m"
+ no-prefetch = false
+ preimages = false
+ tx-lookup-limit = 2350000
+}
+
+accounts {
+ unlock = []
+ password-file = ""
+ allow-insecure-unlock = false
+ use-lightweight-kdf = false
+}
+
+grpc {
+ addr = ":3131"
+}
+```
--
GitLab