expanding the go-kosu readme

packages/go-kosu/README.md

@@ -1,40 +1,150 @@
-# go-kosu
+# Go Kosu (`go-kosu`)
 
-## Running
+Golang reference implementation of the Kosu protocol, built on [Tendermint Consensus.](https://github.com/tendermint/tendermint)
 
-Run the server:
+Automated per-commit builds are available for `Linux/amd64` architectures, published with each update to the `master` branch.
+
+Stable release builds will be available from the GitHub releases page after an initial beta release.
+
+## Building from source
+
+Binaries from `go-kosu` must be build alongside the rest of the `kosu-monorepo` due to the Kosu client implementation's dependency on contract system build artifacts. See [the top-level README for full build instructions.](https://github.com/ParadigmFoundation/kosu-monorepo/blob/master/README.md#install-instructions)
+
+### Prerequisites
+
+In order to build the full monorepo, the following is required:
+
+-   [Node.js](https://nodejs.org/en/download/) (`^10`)
+-   [Yarn](https://yarnpkg.com/lang/en/docs/install/#mac-stable) (`^1.15`)
+-   [jq](https://stedolan.github.io/jq/download/) (`^1.6`)
+-   [golang](https://golang.org/dl/) (`^1.12`)
+-   [go-ethereum](https://github.com/ethereum/go-ethereum/wiki/Building-Ethereum) (`^1.8`)
+
+### Clone monorepo
+
+Clone the full `kosu-monorepo` with the following command:
+
+```bash
+# over SSH (recommended)
+git clone git@github.com:ParadigmFoundation/kosu-monorepo.git
+
+# over HTTPS
+git clone https://github.com/ParadigmFoundation/kosu-monorepo.git
+```
+
+### Install package dependencies
+
+Build and link all package dependencies with `yarn` (do not use `npm`):
 
 ```
-export KOSU_HOME=./my_node
-tendermint init --home=$KOSU_HOME
-go run ./cmd/kosud/main.go
+yarn 
 ```
 
-Execute a transaction:
+### Build all packages
+The following command will build all packages, including the Kosu contract system and the `kosud` binary:
 
 ```
-go run ./cmd/kosu-cli/main.go tx rebalance 1 1 11
+yarn build
 ```
 
-Execute queries:
+After building, all `go-kosu` binaries will be available in the `packages/go-kosu` folder.
+
+### Rebuilding
 
+After a full monorepo build, `go-kosu` can be subsequently rebuilt (during development) with:
+
+```bash
+cd packages/go-kosu
+make
 ```
-$ go run ./cmd/kosu-cli/main.go query round
-ok: < number:3 starts_at:21 ends_at:31 >
 
-$ go run ./cmd/kosu-cli/main.go query consensus
-ok: < PeriodLength:10 >
+## Executables
+
+The `go-kosu` project includes several executeables, found in the `cmd` folder. See the [binaries](#binaries) section for download and install instructions.
+
+- [`kosud`](#binary-kosud) - Kosu reference implementation validator and full-node client.
+- [`kosu-cli`](#binary-kosu-cli) - Command-line interface for `kosud` and other tools.
+- [`kosu-rpc`](#binary-kosu-rpc) - RPC server for `kosud` serving a JSONRPC-API over WebSockets and/or HTTP.
 
-go run ./cmd/kosu-cli/main.go query poster 0x08FA21AF985591E775523eF161F023764175A932
-ok: < balance:<value:"\r\340\266\263\247d\000\000" > >
+### Downloads
+
+Pre-built binaries for `go-kosu` are available (per-commit CD builds are currently Linux/amd64 only, build locally for other targets).
+
+#### Binary: `kosud`
+
+Kosu network client reference implementation, built on Tendermint consensus. Run `kosud --help` for usage.
+
+```bash
+wget https://storage.googleapis.com/kosud/linux_amd64/kosud
+chmod +x kosud
+install kosud /usr/local/bin
 ```
 
-## Running the testnet
+#### Binary: `kosu-cli`
+
+Command-line interface for `kosud` (run `kosu-cli` for usage).
+
+```bash
+wget https://storage.googleapis.com/kosu-cli/linux_amd64/kosu-cli
+chmod +x kosu-cli
+install kosu-cli /usr/local/bin
+```
+
+#### Binary: `kosu-rpc`
+
+RPC server for `kosud` (JSONRPC available over WebSockets or HTTP).
+
+```bash
+wget https://storage.googleapis.com/kosu-cli/linux_amd64/kosu-rpc
+chmod +x kosu-rpc
+install kosu-rpc /usr/local/bin
+```
+
+## Usage
+
+Each binary has a `help` command or `--help` flag which should be used for full command reference.
+
+### Start a node
+You can start a single-node Kosu development network with the following command:
+
+```bash
+kosud --init --home=$HOME/.kosu
+```
+
+### Sending transactions
+Force a rebalance transaction (must be parameterized correctly):
+
+```bash
+kosu-cli tx rebalance [round_number] [period_start] [period_end]
+```
+
+### Querying state
+The `kosu-cli` executable provides the ability to query the node's and network's current state (see `kosu-cli query --help` for all commands).
+
+```bash
+# view consensus parameters
+kosu-cli query consensus
+
+# view current round information
+kosu-cli query round
+
+# view a poster account
+kosu-cli query poster [ethereum_address]
+```
+
+### Running test-network
+
+A four-node test network can be started with `docker-compose` for testing and development. It expects an Ethereum JSONRPC-API to be available at `localhost:8545` with the Kosu system contracts deployed. 
 
-The testnet will start 4 nodes using the configuration from `./testnet/node{0-4}`, it uses `docker-compose` to orchestrate the nodes.
+The test-net will expose the Tendermint ABCI RPC-API on ports `8000` to `8003` for nodes `0` through `3` respectively.
 
-To start the testnet run `make testnet`. You can selectively stop and restart nodes using `docker-compose` cli tool.
+```bash
+# start (foreground)
+docker-compose up --build
 
-To test transactions, you can use `go run ./cmd/client/main.go <node> <number>` where `<node>` is a node endpoint like: `http://192.167.10.3:26657` and `<n>` is the Round number, you should start with `"1"` and increase by one every time you run the command.
+# start (background)
+docker-compose up -d --build
 
-To restart the testnet and clean the stored state run `docker-compose rm -f`
+# stop and remove containers
+docker-compose down
+```