Update README

README.md

@@ -2,36 +2,70 @@
 
 Go implementation of the Hermez node.
 
-## Test
+## Developing
 
-- First run a docker instance of the PostgresSQL (where `yourpasswordhere` should be your password)
+### Unit testing
+
+Running the unit tests requires a connection to a PostgreSQL database.  You can
+start PostgreSQL with docker easily this way (where `yourpasswordhere` should
+be your password):
 
 ```
-POSTGRES_PASS=yourpasswordhere; sudo docker run --rm --name hermez-db-test -p 5432:5432 -e POSTGRES_DB=hermez -e POSTGRES_USER=hermez -e POSTGRES_PASSWORD="$POSTGRES_PASS" -d postgres
+POSTGRES_PASS=yourpasswordhere sudo docker run --rm --name hermez-db-test -p 5432:5432 -e POSTGRES_DB=hermez -e POSTGRES_USER=hermez -e POSTGRES_PASSWORD="$POSTGRES_PASS" -d postgres
 ```
 
-- Then, run the tests with the password as env var
+Afterwards, run the tests with the password as env var:
 
 ```
 POSTGRES_PASS=yourpasswordhere go test -p 1 ./...
 ```
 
 NOTE: `-p 1` forces execution of package test in serial.  Otherwise they may be
-executed in paralel and the test may find unexpected entries in the SQL
-databse because it's shared among all tests.
+executed in paralel and the test may find unexpected entries in the SQL databse
+because it's shared among all tests.
+
+There is an extra temporary option that allows you to run the API server using
+the Go tests. This will be removed once the API can be properly initialized,
+with data from the synchronizer and so on. To use this, run:
+
+```
+FAKE_SERVER=yes POSTGRES_PASS=yourpasswordhere go test -timeout 0  ./api -p 1 -count 1 -v`
+```
 
-- There is an extra temporal option that allows to run the API server through the Go tests. This should be removed once the API can be properly initialized, with data from the synchronizer and so on. To use this, run `FAKE_SERVER=yes POSTGRES_PASS=yourpasswordhere go test -timeout 0  ./api -p 1 -count 1 -v`
+### Lint
 
-## Lint
+All Pull Requests need to pass the configured linter.
 
-- Install [golangci-lint](https://golangci-lint.run)
-- Once installed, to check the lints
+To run the linter locally, first install [golangci-lint](https://golangci-lint.run).  Afterwards you can check the lints with this command:
 
 ```
 golangci-lint run --timeout=5m -E whitespace -E gosec -E gci -E misspell -E gomnd -E gofmt -E goimports -E golint --exclude-use-default=false --max-same-issues 0
 ```
 
-## Usage Details
+## Usage
+
+### Node
+
+See [cli/node/README.md](cli/node/README.md)
+
+### Proof Server
+
+The node in mode coordinator requires a proof server (a server that is capable
+of calculating proofs from the zkInputs). For testing purposes there is a mock
+proof server cli at `test/proofserver/cli`.
+
+Usage of `test/proofserver/cli`:
+
+```
+USAGE:
+    go run ./test/proofserver/cli OPTIONS
+
+OPTIONS:
+  -a string
+        listen address (default "localhost:3000")
+  -d duration
+        proving time duration (default 2s)
+```
 
 ### `/tmp` as tmpfs
 
@@ -43,5 +77,3 @@ can be done by mounting `/tmp` as tmpfs; for example, by having this line in
 ```
 tmpfs			/tmp		tmpfs		defaults,noatime,mode=1777	0 0
 ```
-
-

cli/node/README.md

@@ -16,6 +16,7 @@ VERSION:
 
 COMMANDS:
    importkey  Import ethereum private key
+   genbjj     Generate a new BabyJubJub key
    wipesql    Wipe the SQL DB (HistoryDB and L2DB), leaving the DB in a clean state
    run        Run the hermez-node in the indicated mode
    help, h    Shows a list of commands or help for one command
@@ -27,11 +28,66 @@ GLOBAL OPTIONS:
    --version, -v  print the version (default: false)
 ```
 
+The node has two main modes of running:
+- `sync`: Synchronizer mode.  In this mode the node will only synchronize the
+  state of the hermez smart contracts, mainly processing the transactions in
+  the batches.
+- `coord`: Coordinator mode.  In this mode, apart from doing all the
+  synchronization work, the node will also act as a coordinator, accepting L2
+  transactions in the pool, and trying to forge batches when the proper
+  conditions arise.
+
 ## Configuration
 
+The node requires a single configuration file to run.
+
 You can find a testing working configuration example at
 [cfg.buidler.toml](./cfg.buidler.toml)
 
 To read the documentation of each configuration parameter, please check the
 `type Node` and `type Coordinator` at
-[config/config.go](../../config/config.go)
+[config/config.go](../../config/config.go).  All the sections that are prefixed
+with `Coordinator` are only used in coord mode, and don't need to be defined
+when running the coordinator in sync mode
+
+### Notes
+
+- The private key corresponding to the parameter `Coordinator.ForgerAddress` needs to be imported in the ethereum keystore
+- The private key corresponding to the parameter `Coordinator.FeeAccount.Address` needs to be imported in the ethereum keystore
+- The public key corresponding to the parameter `Coordinator.FeeAccount.BJJ` can be generated with the command `genbjj`
+- There are two sets of debug parameters (`Debug` for all modes, and
+  `Coordinator.Debug` for `coord` mode).  Some of these parameters may not be
+  suitable for production.
+- The parameter `Coordinator.Debug.BatchPath`, when set, causes the coordinator
+  to store dumps of a lot of information related to batches in json files.
+  This files can be around 2MB big.  If this parameter is set, be careful to
+  monitor the size of the folder to avoid running out of space.
+- The node requires a PostgreSQL database.  The parameters of the server and
+  database must be set in the `PostgreSQL` section.
+
+## Usage Examples
+
+Run the node in mode synchronizer:
+```
+go run . --mode sync --cfg cfg.buidler.toml run
+```
+
+Run the node in mode coordinator:
+```
+go run . --mode coord --cfg cfg.buidler.toml run
+```
+
+Import an ethereum private key into the keystore:
+```
+go run . --mode coord --cfg cfg.buidler.toml importkey --privatekey  0x618b35096c477aab18b11a752be619f0023a539bb02dd6c813477a6211916cde
+```
+
+Generate a new BabyJubJub key pair:
+```
+go run . --mode coord --cfg cfg.buidler.toml genbjj
+```
+
+Wipe the entier SQL database (this will destroy all synchronized and pool data):
+```
+go run . --mode coord --cfg cfg.buidler.toml wipesql
+```