From c9777e163248e4fbf73de122acc7deb2301f12c3 Mon Sep 17 00:00:00 2001 From: rhuairahrighairigh Date: Tue, 18 Sep 2018 17:05:47 -0400 Subject: [PATCH 1/3] redo readme --- README.md | 150 +++--------------- .../x/paychan/README.md => docs/paychans.md | 0 docs/setup.md | 126 +++++++++++++++ docs/usage.md | 0 4 files changed, 147 insertions(+), 129 deletions(-) rename internal/x/paychan/README.md => docs/paychans.md (100%) create mode 100644 docs/setup.md create mode 100644 docs/usage.md diff --git a/README.md b/README.md index 12d1deb7..3a447074 100644 --- a/README.md +++ b/README.md @@ -3,137 +3,29 @@ A decentralized fast-finality blockchain for interoperable payment channel networks. -Building on the work of Tendermint and Interledger. -Project status: We're currently in a very early public testnet. With future features being implemented. +Providing a base layer currency to settle interoperable payments at high throughput. Leveraging fast finality to allow short cross currency channel timeouts. Proof of stake to provide performance and effective light clients. Payment channels to enable high volume low value transfers at realistic throughput. Streaming credit payments for effective routing and interoperability across chains. -Try it out - run a full node to sync to the testnet, [send some off chain payments](internal/x/paychan/README.md), or set up as a validator. +Proudly building on the work of [Cosmos](https://github.com/cosmos/cosmos-sdk) and [Interledger](https://github.com/interledger/rfcs). + +# Project Status +[![Testnet](https://img.shields.io/badge/testnet-live-brightgreen.svg)](http://validator.connector.kava.io:26657/abci_info) +[![Go Report Card](https://goreportcard.com/badge/github.com/kava-labs/kava)](https://goreportcard.com/report/github.com/kava-labs/kava) +![GitHub](https://img.shields.io/github/license/mashape/apistatus.svg) + +We're currently in a very early public testnet, with future features being implemented. + +If you're interested in being a validator join the chat and checkout the setup instructions below. + +## Community + + - [Telegram](https://t.me/kavalabs) + - [Medium](https://medium.com/kava-labs) + - [Validator Chat](https://riot.im/app/#/room/#kava-validators:matrix.org) -## Install +# Find Out More - - -Requirements: go installed and set up (version 1.10+). - - 0. If installing from a new Ubuntu server (16.04 or 18.04), here's how to setup go: - - sudo apt update - sudo apt upgrade -y - sudo apt install git gcc make wget -y - wget https://dl.google.com/go/go1.10.3.linux-amd64.tar.gz - sudo tar -xvf go1.10.3.linux-amd64.tar.gz - sudo mv go /usr/local - - cat >> ~/.profile < - - - - -## Run a Full Node - - kvd init --name --chain-id kava-test-2 - -This will generate config and keys in `$HOME/.kvd` and `$HOME/.kvcli`. The default password is 'password'. - -> Note: Make sure `GOBIN` is set and added to your path if you want to be able to run installed go programs from any folder. - -Copy the testnet genesis file (from https://raw.githubusercontent.com/Kava-Labs/kava/master/testnets/kava-test-2/genesis.json) into `$HOME/.kvd/config/`, replacing the existing one. - -Add the kava node address, `5c2bc5a95b014e4b2897791565398ee6bfd0a04a@validator.connector.kava.io:26656`, to `seeds` in `$HOME/.kvd/config/config.toml` - -Start your full node - - kvd start - -Or, to start in background and send to log: - - kvd start &> kvd.log & - -To see the output of the log: - - tail -f kvd.log -> Note: It might take a while to fully sync. Check the latest block height [here](http://validator.connector.kava.io:26657/abci_info). - - -## Run a Validator -Join the [validator chat](https://riot.im/app/#/room/#kava-validators:matrix.org). Follow setup for a full node above. - -Get you address with `kvcli keys list`. Should look something like `cosmosaccaddr10jpp289accvkhsvrpz4tlj9zhqdaey2tl9m4rg`. - -Ask @rhuairahrighairidh in the chat to give you some coins. - -Get your validator pubkey with `kvd tendermint show_validator` - -Then, your full running in the background or separate window, run: - - kvcli stake create-validator \ - --amount 900KVA \ - --pubkey \ - --address-validator \ - --moniker "" \ - --chain-id kava-test-2 \ - --from \ - --gas 1000000 - -> Note You'll need to type in the default password "password" - -Now your full node should be participating in consensus and validating blocks! - -Running a validator requires that you keep validating blocks. If you stop, your stake will be slashed. -In order to stop validating, first remove yourself as validator, then you can stop your node. - - kvcli stake unbond begin \ - --address-delegator \ - --address-validator \ - --chain-id kava-test-2 \ - --shares-percent 1 \ - --from \ - --gas 1000000 + - [Installation and Setup](docs/setup.md) + - [Basic Usage](docs/usage.md) + - [Payment Channels](docs/paychans.md) diff --git a/internal/x/paychan/README.md b/docs/paychans.md similarity index 100% rename from internal/x/paychan/README.md rename to docs/paychans.md diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 00000000..eea7d206 --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,126 @@ + +## Install + +Requirements: go installed and set up (version 1.10+). + + 0. If installing from a new Ubuntu server (16.04 or 18.04), here's how to setup go: + + sudo apt update + sudo apt upgrade -y + sudo apt install git gcc make wget -y + wget https://dl.google.com/go/go1.10.3.linux-amd64.tar.gz + sudo tar -xvf go1.10.3.linux-amd64.tar.gz + sudo mv go /usr/local + + cat >> ~/.profile < + + + + +## Run a Full Node + + kvd init --name --chain-id kava-test-2 + +This will generate config and keys in `$HOME/.kvd` and `$HOME/.kvcli`. The default password is 'password'. + +> Note: Make sure `GOBIN` is set and added to your path if you want to be able to run installed go programs from any folder. + +Copy the testnet genesis file (from https://raw.githubusercontent.com/Kava-Labs/kava/master/testnets/kava-test-2/genesis.json) into `$HOME/.kvd/config/`, replacing the existing one. + +Add the kava node address, `5c2bc5a95b014e4b2897791565398ee6bfd0a04a@validator.connector.kava.io:26656`, to `seeds` in `$HOME/.kvd/config/config.toml` + +Start your full node + + kvd start + +Or, to start in background and send to log: + + kvd start &> kvd.log & + +To see the output of the log: + + tail -f kvd.log +> Note: It might take a while to fully sync. Check the latest block height [here](http://validator.connector.kava.io:26657/abci_info). + + +## Run a Validator +Join the [validator chat](https://riot.im/app/#/room/#kava-validators:matrix.org). Follow setup for a full node above. + +Get you address with `kvcli keys list`. Should look something like `cosmosaccaddr10jpp289accvkhsvrpz4tlj9zhqdaey2tl9m4rg`. + +Ask @rhuairahrighairidh in the chat to give you some coins. + +Get your validator pubkey with `kvd tendermint show_validator` + +Then, your full running in the background or separate window, run: + + kvcli stake create-validator \ + --amount 900KVA \ + --pubkey \ + --address-validator \ + --moniker "" \ + --chain-id kava-test-2 \ + --from \ + --gas 1000000 + +> Note You'll need to type in the default password "password" + +Now your full node should be participating in consensus and validating blocks! + +Running a validator requires that you keep validating blocks. If you stop, your stake will be slashed. +In order to stop validating, first remove yourself as validator, then you can stop your node. + + kvcli stake unbond begin \ + --address-delegator \ + --address-validator \ + --chain-id kava-test-2 \ + --shares-percent 1 \ + --from \ + --gas 1000000 diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 00000000..e69de29b From 9802450a0841e01e4b1714546b3f06f04d9d3bcc Mon Sep 17 00:00:00 2001 From: rhuairahrighairigh Date: Tue, 18 Sep 2018 19:14:46 -0400 Subject: [PATCH 2/3] fill out docs --- docs/paychans.md | 30 ++++++-------------------- docs/setup.md | 44 +++++++++++++-------------------------- docs/usage.md | 19 +++++++++++++++++ internal/x/paychan/doc.go | 29 +++++++++++++++++++++++++- 4 files changed, 68 insertions(+), 54 deletions(-) diff --git a/docs/paychans.md b/docs/paychans.md index 463f495c..aa5f19ec 100644 --- a/docs/paychans.md +++ b/docs/paychans.md @@ -1,10 +1,12 @@ -# Unidrectional Payment Channels +# Payment Channels -This module implements simple but feature complete unidirectional payment channels. Channels can be opened by a sender and closed immediately by the receiver, or by the sender subject to a dispute period. There are no top-ups or partial withdrawals (yet). Channels support multiple currencies. +Payment channels are designed to enable high speed and throughput for transactions while requiring no counter-party risk. + +This initial implementation is for unidirectional channels. Channels can be opened by a sender and closed immediately by the receiver, or by the sender subject to a dispute period. There are no top-ups or partial withdrawals (yet). ->Note: This module is still a bit rough around the edges. More feature planned. More test cases needed. # Usage +>The following commands require communication with a full node. By default they expect one to be running locally (accessible on localhost), but a remote can be provided with the `--node` flag. ## Create a channel @@ -24,7 +26,7 @@ The receiver can close immediately at any time. kvcli paychan submit --from --payment payment.json --chain-id -The sender can submit a close request, causing the channel will close automatically after a dispute period. During this period a receiver can still close immediately. +The sender can submit a close request, causing the channel will close automatically after a dispute period. During this period a receiver can still close immediately, overruling the sender's request. kvcli paychan submit --from --payment payment.json --chain-id @@ -35,23 +37,3 @@ The sender can submit a close request, causing the channel will close automatica kvcli get --chan-id This will print out a channel, if it exists, and any submitted close requests. - -# TODOs - - - in code TODOs - - Tidy up - method descriptions, heading comments, remove uneccessary comments, README/docs - - Find a better name for Queue - clarify distinction between int slice and abstract queue concept - - write some sort of integration test - - possible bug in submitting same update repeatedly - - find nicer name for payout - - add Gas usage - - add tags (return channel id on creation) - - refactor cmds to be able to test them, then test them - - verify doesn’t throw json parsing error on invalid json - - can’t submit an update from an unitialised account - - pay without a --from returns confusing error - - use custom errors instead of using sdk.ErrInternal - - split off signatures from update as with txs/msgs - testing easier, code easier to use, doesn't store sigs unecessarily on chain - - consider removing pubKey from UpdateSignature - instead let channel module access accountMapper - - refactor queue into one object - - remove printout during tests caused by mock app initialisation diff --git a/docs/setup.md b/docs/setup.md index eea7d206..d67ae78e 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -1,4 +1,15 @@ +# Installation and Setup + +#### Who this guide is for +The blockchain code currently consists of a full node daemon (`kvd`) and it's command line interface (`kvcli`). + +Full nodes are fairly resource intensive and are designed to be run continuously on servers, primarily by people validating the network. While it is possible to run locally it is not recommended unless for development purposes. In the future light clients will enable secure transactions for clients. + +A **full node** syncs with the blockchain and processes transactions. A **validator** is a full node that has declared itself to be a "validator" on chain. This obligates it to participate in consensus by proposing and signing blocks and maintaining uptime. By not following the protocol, the validator's stake will be slashed. + +Use the following instructions to set up a full node, and to optionally declare yourself as a validator. + ## Install Requirements: go installed and set up (version 1.10+). @@ -32,38 +43,13 @@ Requirements: go installed and set up (version 1.10+). mkdir $GOPATH/bin curl https://raw.githubusercontent.com/golang/dep/master/install.sh | sh - dep ensure + dep ensure -vendor-only 3. Install the code go install ./cmd/kvd go install ./cmd/kvcli - - - - - ## Run a Full Node kvd init --name --chain-id kava-test-2 @@ -80,7 +66,7 @@ Start your full node kvd start -Or, to start in background and send to log: +Or, to start in background and capture output in a log file: kvd start &> kvd.log & @@ -90,10 +76,10 @@ To see the output of the log: > Note: It might take a while to fully sync. Check the latest block height [here](http://validator.connector.kava.io:26657/abci_info). -## Run a Validator +## Become a Validator Join the [validator chat](https://riot.im/app/#/room/#kava-validators:matrix.org). Follow setup for a full node above. -Get you address with `kvcli keys list`. Should look something like `cosmosaccaddr10jpp289accvkhsvrpz4tlj9zhqdaey2tl9m4rg`. +Get you address with `kvcli keys list`. Ask @rhuairahrighairidh in the chat to give you some coins. diff --git a/docs/usage.md b/docs/usage.md index e69de29b..6fb1f6f8 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -0,0 +1,19 @@ +# Basic Usage +>The following commands require communication with a full node. By default they expect one to be running locally (accessible on localhost), but a remote can be provided with the `--node` flag. +## View Your Address +This lists locally stored account addresses and their names. The name is used to indicate which address to sign transactions from in other commands. + + kvcli keys list + +## View Account Balances + + kvcli account
+ +## Send Some KVA + + kvcli send --from \ + --to
\ + --amount 100KVA \ + --chain-id kava-test- + + diff --git a/internal/x/paychan/doc.go b/internal/x/paychan/doc.go index 2b063b08..b0778b2f 100644 --- a/internal/x/paychan/doc.go +++ b/internal/x/paychan/doc.go @@ -1,5 +1,32 @@ /* -High level package documentation. +Package paychan provides unidirectional payment channels. + +This module implements simple but feature complete unidirectional payment channels. Channels can be opened by a sender and closed immediately by the receiver, or by the sender subject to a dispute period. There are no top-ups or partial withdrawals (yet). Channels support multiple currencies. + +>Note: This module is still a bit rough around the edges. More feature planned. More test cases needed. + + TODO Explain how the payment channels are implemented. + +# TODOs + + - in code TODOs + - Tidy up - method descriptions, heading comments, remove uneccessary comments, README/docs + - Find a better name for Queue - clarify distinction between int slice and abstract queue concept + - write some sort of integration test + - possible bug in submitting same update repeatedly + - find nicer name for payout + - add Gas usage + - add tags (return channel id on creation) + - refactor cmds to be able to test them, then test them + - verify doesn’t throw json parsing error on invalid json + - can’t submit an update from an unitialised account + - pay without a --from returns confusing error + - use custom errors instead of using sdk.ErrInternal + - split off signatures from update as with txs/msgs - testing easier, code easier to use, doesn't store sigs unecessarily on chain + - consider removing pubKey from UpdateSignature - instead let channel module access accountMapper + - refactor queue into one object + - remove printout during tests caused by mock app initialisation + */ package paychan From 747fc6843b82400ca5c29cec5dfb295241cf534c Mon Sep 17 00:00:00 2001 From: rhuairahrighairigh Date: Tue, 18 Sep 2018 19:27:26 -0400 Subject: [PATCH 3/3] minor edits --- docs/setup.md | 6 +++--- docs/usage.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/setup.md b/docs/setup.md index d67ae78e..f015ba07 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -2,13 +2,13 @@ # Installation and Setup #### Who this guide is for -The blockchain code currently consists of a full node daemon (`kvd`) and it's command line interface (`kvcli`). +The code currently consists of a full node daemon (`kvd`) and it's command line interface (`kvcli`). Full nodes are fairly resource intensive and are designed to be run continuously on servers, primarily by people validating the network. While it is possible to run locally it is not recommended unless for development purposes. In the future light clients will enable secure transactions for clients. A **full node** syncs with the blockchain and processes transactions. A **validator** is a full node that has declared itself to be a "validator" on chain. This obligates it to participate in consensus by proposing and signing blocks and maintaining uptime. By not following the protocol, the validator's stake will be slashed. -Use the following instructions to set up a full node, and to optionally declare yourself as a validator. +Use these instructions to set up a full node, and to optionally declare yourself as a validator. ## Install @@ -66,7 +66,7 @@ Start your full node kvd start -Or, to start in background and capture output in a log file: +Or, to start in the background and capture output to a log file: kvd start &> kvd.log & diff --git a/docs/usage.md b/docs/usage.md index 6fb1f6f8..a24287fd 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,7 +1,7 @@ # Basic Usage >The following commands require communication with a full node. By default they expect one to be running locally (accessible on localhost), but a remote can be provided with the `--node` flag. ## View Your Address -This lists locally stored account addresses and their names. The name is used to indicate which address to sign transactions from in other commands. +List locally stored account addresses and their names. The name is used in other commands to specify which address to use to sign the transaction. kvcli keys list