1# node cli
  2
  3This is the main cli for the node
  4
  5## Go version
  6
  7The `hermez-node` has been tested with go version 1.14
  8
  9## Usage
 10
 11```shell
 12NAME:
 13   hermez-node - A new cli application
 14
 15USAGE:
 16   node [global options] command [command options] [arguments...]
 17
 18VERSION:
 19   v0.1.0-6-gd8a50c5
 20
 21COMMANDS:
 22   version    Show the application version
 23   importkey  Import ethereum private key
 24   genbjj     Generate a new BabyJubJub key
 25   wipesql    Wipe the SQL DB (HistoryDB and L2DB) and the StateDBs, leaving the DB in a clean state
 26   run        Run the hermez-node in the indicated mode
 27   serveapi   Serve the API only
 28   discard    Discard blocks up to a specified block number
 29   help, h    Shows a list of commands or help for one command
 30
 31GLOBAL OPTIONS:
 32   --help, -h     show help (default: false)
 33   --version, -v  print the version (default: false)
 34```
 35
 36The node has two main modes of running:
 37- `sync`: Synchronizer mode.  In this mode the node will only synchronize the
 38  state of the hermez smart contracts, mainly processing the transactions in
 39  the batches.
 40- `coord`: Coordinator mode.  In this mode, apart from doing all the
 41  synchronization work, the node will also act as a coordinator, accepting L2
 42  transactions in the pool, and trying to forge batches when the proper
 43  conditions arise.
 44
 45## Configuration
 46
 47The node requires a single configuration file to run.
 48
 49You can find a testing working configuration example at
 50[cfg.buidler.toml](./cfg.buidler.toml)
 51
 52To read the documentation of each configuration parameter, please check the
 53`type Node` and `type Coordinator` at
 54[config/config.go](../../config/config.go).  All the sections that are prefixed
 55with `Coordinator` are only used in coord mode, and don't need to be defined
 56when running the coordinator in sync mode
 57
 58When running the API in standalone mode, the required configuration is a subset
 59of the node configuration.  Please, check the `type APIServer` at
 60[config/config.go](../../config/config.go) to learn about all the parametes.
 61
 62### Notes
 63
 64- The private key corresponding to the parameter `Coordinator.ForgerAddress` needs to be imported in the ethereum keystore
 65- The private key corresponding to the parameter `Coordinator.FeeAccount.Address` needs to be imported in the ethereum keystore
 66- The public key corresponding to the parameter `Coordinator.FeeAccount.BJJ` can be generated with the command `genbjj`
 67- There are two sets of debug parameters (`Debug` for all modes, and
 68  `Coordinator.Debug` for `coord` mode).  Some of these parameters may not be
 69  suitable for production.
 70- The parameter `Coordinator.Debug.BatchPath`, when set, causes the coordinator
 71  to store dumps of a lot of information related to batches in json files.
 72  This files can be around 2MB big.  If this parameter is set, be careful to
 73  monitor the size of the folder to avoid running out of space.
 74- The node requires a PostgreSQL database.  The parameters of the server and
 75  database must be set in the `PostgreSQL` section.
 76- The node requires a web3 RPC server to work.  The node has only been tested
 77  with geth and may not work correctly with other ethereum nodes
 78  implementations.
 79
 80## Building
 81
 82*All commands assume you are at the `cli/node` directory.*
 83
 84Building the node requires using the packr utility to bundle the database
 85migrations inside the resulting binary.  Install the packr utility with:
 86```shell
 87cd /tmp && go get -u github.com/gobuffalo/packr/v2/packr2 && cd -
 88```
 89
 90Make sure your `$PATH` contains `$GOPATH/bin`, otherwise the packr utility will
 91not be found.
 92
 93Now build the node executable:
 94```shell
 95cd ../../db && packr2 && cd -
 96go build .
 97cd ../../db && packr2 clean && cd -
 98```
 99
100The executable is `node`.
101
102## Usage Examples
103
104The following commands assume you have built the node previously.  You can also
105run the following examples by replacing `./node` with `go run .` and executing
106them in the `cli/node` directory to build from source and run at the same time.
107
108Run the node in mode synchronizer:
109```shell
110./node run --mode sync --cfg cfg.buidler.toml
111```
112
113Run the node in mode coordinator:
114```shell
115./node run --mode coord --cfg cfg.buidler.toml
116```
117
118Serve the API in standalone mode.  This command allows serving the API just
119with access to the PostgreSQL database that a node is using.  Several instances
120of `serveapi` can be running at the same time with a single PostgreSQL
121database:
122```shell
123./node serveapi --mode coord --cfg cfg.buidler.toml
124```
125
126Import an ethereum private key into the keystore:
127```shell
128./node importkey --mode coord --cfg cfg.buidler.toml --privatekey  0x618b35096c477aab18b11a752be619f0023a539bb02dd6c813477a6211916cde
129```
130
131Generate a new BabyJubJub key pair:
132```shell
133./node genbjj
134```
135
136Check the binary version:
137```shell
138./node version
139```
140
141Wipe the entier SQL database (this will destroy all synchronized and pool
142data):
143```shell
144./node wipesql --mode coord --cfg cfg.buidler.toml 
145```
146
147Discard all synchronized blocks and associated state up to a given block
148number.  This command is useful in case the synchronizer reaches an invalid
149state and you want to roll back a few blocks and try again (maybe with some
150fixes in the code).
151```shell
152./node discard --mode coord --cfg cfg.buidler.toml --block 8061330
153```