diff --git a/packages/go-kosu/README.md b/packages/go-kosu/README.md index 7f9680b6..a74c0c5f 100644 --- a/packages/go-kosu/README.md +++ b/packages/go-kosu/README.md @@ -1,40 +1,143 @@ -# 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`): + +``` +yarn +``` + +### Build all packages + +The following command will build all packages, including the Kosu contract system and the `kosud` binary: + +``` +yarn build +``` + +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 ``` -export KOSU_HOME=./my_node -tendermint init --home=$KOSU_HOME -go run ./cmd/kosud/main.go + +## 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. + +### 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 ``` -Execute a transaction: +#### 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 ``` -go run ./cmd/kosu-cli/main.go tx rebalance 1 1 11 + +## 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 ``` -Execute queries: +### Sending transactions + +Force a rebalance transaction (must be parameterized correctly): +```bash +kosu-cli tx rebalance [round_number] [period_start] [period_end] ``` -$ 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 > +### Querying state -go run ./cmd/kosu-cli/main.go query poster 0x08FA21AF985591E775523eF161F023764175A932 -ok: < balance: > +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 the testnet +### Running test-network -The testnet will start 4 nodes using the configuration from `./testnet/node{0-4}`, it uses `docker-compose` to orchestrate the nodes. +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. -To start the testnet run `make testnet`. You can selectively stop and restart nodes using `docker-compose` cli tool. +The test-net will expose the Tendermint ABCI RPC-API on ports `8000` to `8003` for nodes `0` through `3` respectively. -To test transactions, you can use `go run ./cmd/client/main.go ` where `` is a node endpoint like: `http://192.167.10.3:26657` and `` is the Round number, you should start with `"1"` and increase by one every time you run the command. +```bash +# start (foreground) +docker-compose up --build -To restart the testnet and clean the stored state run `docker-compose rm -f` +# start (background) +docker-compose up -d --build + +# stop and remove containers +docker-compose down +```