From 215bf8dd81ffbf62cc3ce7bff1c113845e1b99e8 Mon Sep 17 00:00:00 2001 From: Henry Harder Date: Thu, 18 Jul 2019 12:53:29 -0700 Subject: [PATCH 1/3] expanding the go-kosu readme --- packages/go-kosu/README.md | 150 ++++++++++++++++++++++++++++++++----- 1 file changed, 130 insertions(+), 20 deletions(-) diff --git a/packages/go-kosu/README.md b/packages/go-kosu/README.md index 7f9680b6..f1cd951a 100644 --- a/packages/go-kosu/README.md +++ b/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: > +### 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 ` 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. +# 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 +``` \ No newline at end of file From b452bd94404393e56e965258a6dbb323119063c8 Mon Sep 17 00:00:00 2001 From: Henry Harder Date: Thu, 18 Jul 2019 13:03:44 -0700 Subject: [PATCH 2/3] running prettier --- packages/go-kosu/README.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/packages/go-kosu/README.md b/packages/go-kosu/README.md index f1cd951a..60bee2e8 100644 --- a/packages/go-kosu/README.md +++ b/packages/go-kosu/README.md @@ -37,10 +37,11 @@ git clone https://github.com/ParadigmFoundation/kosu-monorepo.git Build and link all package dependencies with `yarn` (do not use `npm`): ``` -yarn +yarn ``` ### Build all packages + The following command will build all packages, including the Kosu contract system and the `kosud` binary: ``` @@ -62,9 +63,9 @@ make 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. +- [`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. ### Downloads @@ -105,6 +106,7 @@ install kosu-rpc /usr/local/bin 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 @@ -112,6 +114,7 @@ kosud --init --home=$HOME/.kosu ``` ### Sending transactions + Force a rebalance transaction (must be parameterized correctly): ```bash @@ -119,6 +122,7 @@ 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 @@ -134,7 +138,7 @@ 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. +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 test-net will expose the Tendermint ABCI RPC-API on ports `8000` to `8003` for nodes `0` through `3` respectively. @@ -147,4 +151,4 @@ docker-compose up -d --build # stop and remove containers docker-compose down -``` \ No newline at end of file +``` From bd06442d2f2005414c9da028bf96c0b51e35e2d1 Mon Sep 17 00:00:00 2001 From: Henry Harder Date: Fri, 19 Jul 2019 16:58:34 -0700 Subject: [PATCH 3/3] remove references to a kosu-rpc binary --- packages/go-kosu/README.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/packages/go-kosu/README.md b/packages/go-kosu/README.md index 60bee2e8..a74c0c5f 100644 --- a/packages/go-kosu/README.md +++ b/packages/go-kosu/README.md @@ -65,7 +65,6 @@ The `go-kosu` project includes several executeables, found in the `cmd` folder. - [`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. ### Downloads @@ -91,16 +90,6 @@ 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.