fill out docs

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 <receiver's account name> --payment payment.json --chain-id <your 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 <receiver's account name> --payment payment.json --chain-id <your chain ID>
 
@@ -35,23 +37,3 @@ The sender can submit a close request, causing the channel will close automatica
 	kvcli get --chan-id <ID of channel>
 
 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

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
 
-<!--### Docker
-
-Requirements: docker installed.
-
-No installation necessary, just prepend commands with `docker run kava/kava`.  TODO name necessary to avoid new contianer being created each time?
-
-This will use our docker container `kava/kava` and store all blockchain data and keys within the container. -->
-
-<!-- To store this data outisde the conatiner, attach volumes to the container:
-
-    docker run --rm -v $HOME/.kvd:/root/.kvd -v $HOME/.kvcli:/root/.kvcli kava/kava <further commands>
-
-Now blockchain data will be stored in `$HOME/.kvd` and keys in `$HOME/.kvcli`. Also the `--rm` flag removes the contianer after each run.
-
- -->
-<!-- ## Send Transactions
-
-You can send transactions on the testnet using our node without yncing a local node.
-Requirements
-
-TODO users need to set up keys first?
-
-    kvcli <args> --node validator.connector.kava.io:26657 --chain-id kava-test-<current version>
- -->
-
 ## Run a Full Node
 
     kvd init --name <your-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.
 

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 <address>
+
+## Send Some KVA
+
+    kvcli send --from <your key name> \
+               --to <address> \
+               --amount 100KVA \
+               --chain-id kava-test-<current testnet #>
+
+

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