Merge pull request #96 from clearmatics/fix-client-readme-2

Update some instructions in the README

client/README.md

@@ -30,50 +30,48 @@ Ensure that the following are installed:
 - [venv](https://docs.python.org/3/library/venv.html#module-venv) module.
 - gcc
 
-First, make sure to setup the Zeth dependency in order to generate the
-API files and be able to use the Zeth CLIs:
+First, ensure that the Zeth client has been setup as described in the [Zeth client setup documentation](https://github.com/clearmatics/zeth/blob/master/client/README.md).  (This step is required since the Zeth client setup process includes some code generation).  If this has not already been done, it can be performed as follows (assuming the current working directory is the Zecale repository root):
 ```console
-$ cd $ZECALE/depends/zeth/client
+$ pushd depends/zeth/client
 $ python -m venv env
 $ source env/bin/activate
 (env)$ make setup
+(env)$ deactivate
+$ popd
 ```
 
-Then, execute the following inside the `client` directory:
+For encapsulation, we suggest creating a Python virtualenv specific to the Zecale client tools.  The Zeth client will be installed as an editable package (a reference to, rather than a copy of, the package in `depends/zeth/client`) in this virtualenv. Setup is performed as follows:
 ```console
-$ cd $ZECALE/client
+$ cd client
+$ python -m venv env
+$ source env/bin/activate
 (env)$ make setup
 ```
 
-We assume all further commands described here are executed from within the
-Python virtualenv. To enter the virtualenv from a new terminal, re-run
+Unless otherwise stated, we assume that all further commands are executed from within the Python virtualenv (indicated by the `(env)` prefix to the command prompt), and in the `client` directory. To enter the virtualenv from a new terminal, run the following:
 ```console
-$ source $ZECALE/depends/zeth/client/env/bin/activate
+$ source env/bin/activate
 ```
+(Alternatively, specify the full path to `client/env/bin/activate` to execute from outside the `client` directory).
 
 ## Execute unit tests
 
+Unit tests for the client code can be executed as follows:
 ```console
 (env)$ make check
 ```
 
 ## Launch a local Ethereum testnet
 
-In order for Zecale to work, it is necessary for the blockchain to support
-BW6-761 arithmetic. As such, we assume below that the smart contracts are
-deployed on an Ethereum testnet that supports BW6-761 precompiled contracts.
-
-To do so, you can start a ganache-cli instance via docker by running:
+Zecale smart contracts require support for BW6-761 arithmetic, via precompiled contracts. A modified version of ganache-cli (which includes such support) can be launched from a docker image as follows (note that this should be run in its own terminal instance, from the repo root, and does not require the Python virtualenv to be active):
 ```console
-docker run -ti -p 8545:8545 ghcr.io/clearmatics/ganache-cli --hardfork istanbul --gasLimit 0x3FFFFFFFFFFFF --gasPrice 1 --defaultBalanceEther 90000000000
+$ depends/zeth/scripts/ganache-start
 ```
+(See [Zeth](https://github.com/clearmatics/zeth/) for more information)
 
 ## Execute testing scripts
 
-Once the `aggregator_server` and a custom `ganache-cli` instance are
-running, several scripts can be executed to test the CLIs as well as
-various aspects of the client and the contracts. You can run such tests
-by doing:
+Once the `aggregator_server` and a custom `ganache-cli` instance are running, several scripts can be executed to test the CLIs as well as various aspects of the client and the contracts:
 
 ```console
 (env)$ python test_commands/<script-name> <script-arguments>
@@ -84,7 +82,7 @@ for instance:
 (env)$ python test_commands/test_bw6_761_groth16_contract.py
 ```
 
-Moreover, the CLIs are tested using the following script:
+A fuller integration test for the CLIs can also be executed:
 
 ```console
 (env)$ cd ..
@@ -93,10 +91,7 @@ Moreover, the CLIs are tested using the following script:
 
 # The `zecale` command line interface
 
-The `zecale` command exposes Zecale operations via a command line interface. A
-brief description is given in this section. More details are available via
-`zecale --help`, and example usage can be seen in the [client test
-script](../scripts/test-client).
+The `zecale` command exposes Zecale operations via a command line interface. A brief description is given in this section. More details are available via `zecale --help`, and example usage can be seen in the [client test script](../scripts/test-client).  Note that `zecale` can be invoked from any directory, as long as the Python virtualenv is activated.
 
 ## Environment
 
@@ -160,4 +155,3 @@ zecale_dummy_app deploy
 
 For a more comprehensive overview on how to use Zecale with a base
 application, please refer to the [zeth-zecale integration test script](../scripts/test-zeth-zecale).
-