0g-chain/internal/x/paychan/README.md

# Unidrectional 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.

# Usage

## Create a channel

	kvcli paychan create --from <your account name> --to <receivers address> --amount 100KVA --chain-id <your chain ID>

## Send an off-chain payment
Send a payment for 10 KVA.

	kvcli paychan pay --from <your account name> --sen-amt 90KVA --rec-amt 10KVA --chan-id <ID of channel> --filename payment.json --chain-id <your chain ID>

Send the file `payment.json` to your receiver. Then they run the following to verify.

	kvcli paychan verify --filename payment.json

## Close a channel
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.

	kvcli paychan submit --from <receiver's account name> --payment payment.json --chain-id <your chain ID>

>Note: The dispute period on the testnet is 30 seconds for ease of testing.

## Get info on a channel

	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
-												add usage instructions

											
										
										
											2018-09-02 02:57:42 +00:00
+								# Unidrectional Payment Channels
-												initial sketch

											
										
										
											2018-07-08 22:09:07 +00:00
-												add usage instructions

											
										
										
											2018-09-02 02:57:42 +00:00
+								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.
-												initial sketch

											
										
										
											2018-07-08 22:09:07 +00:00
-												print out update from get pachan command

											
										
										
											2018-09-03 20:38:51 +00:00
+								>Note: This module is still a bit rough around the edges. More feature planned. More test cases needed.
-												initial sketch

											
										
										
											2018-07-08 22:09:07 +00:00
-												add usage instructions

											
										
										
											2018-09-02 02:57:42 +00:00
+								# Usage
 								## Create a channel
 									kvcli paychan create --from <your account name> --to <receivers address> --amount 100KVA --chain-id <your chain ID>
 								## Send an off-chain payment
 								Send a payment for 10 KVA.
 									kvcli paychan pay --from <your account name> --sen-amt 90KVA --rec-amt 10KVA --chan-id <ID of channel> --filename payment.json --chain-id <your chain ID>
-												print out update from get pachan command

											
										
										
											2018-09-03 20:38:51 +00:00
+								Send the file `payment.json` to your receiver. Then they run the following to verify.
-												add usage instructions

											
										
										
											2018-09-02 02:57:42 +00:00
 									kvcli paychan verify --filename payment.json
 								## Close a channel
 								The receiver can close immediately at any time.
 									kvcli paychan submit --from <receiver's account name> --payment payment.json --chain-id <your chain ID>
-												print out update from get pachan command

											
										
										
											2018-09-03 20:38:51 +00:00
+								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.
-												add usage instructions

											
										
										
											2018-09-02 02:57:42 +00:00
 									kvcli paychan submit --from <receiver's account name> --payment payment.json --chain-id <your chain ID>
-												print out update from get pachan command

											
										
										
											2018-09-03 20:38:51 +00:00
+								>Note: The dispute period on the testnet is 30 seconds for ease of testing.
-												add usage instructions

											
										
										
											2018-09-02 02:57:42 +00:00
+								## Get info on a channel
 									kvcli get --chan-id <ID of channel>
-												print out update from get pachan command

											
										
										
											2018-09-03 20:38:51 +00:00
+								This will print out a channel, if it exists, and any submitted close requests.
-												add usage instructions

											
										
										
											2018-09-02 02:57:42 +00:00
 								# TODOs
-												initial sketch

											
										
										
											2018-07-08 22:09:07 +00:00
-												prioritise todos

											
										
										
											2018-09-01 18:37:10 +00:00
+								 - in code TODOs
 								 - Tidy up - method descriptions, heading comments, remove uneccessary comments, README/docs
-												fill out rough implementation

											
										
										
											2018-08-27 21:58:58 +00:00
+								 - Find a better name for Queue - clarify distinction between int slice and abstract queue concept
-												prioritise todos

											
										
										
											2018-09-01 18:37:10 +00:00
+								 - write some sort of integration test
-												improve command UX

											
										
										
											2018-09-02 02:22:50 +00:00
+								 	- possible bug in submitting same update repeatedly
-												add validation and signature checks

also expands test cases

											
										
										
											2018-09-01 17:16:56 +00:00
+								 - find nicer name for payout
-												prioritise todos

											
										
										
											2018-09-01 18:37:10 +00:00
+								 - add Gas usage
 								 - add tags (return channel id on creation)
-												add commands

											
										
										
											2018-09-01 20:41:40 +00:00
+								 - refactor cmds to be able to test them, then test them
-												improve command UX

											
										
										
											2018-09-02 02:22:50 +00:00
+								 	- 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
-												prioritise todos

											
										
										
											2018-09-01 18:37:10 +00:00
+								 - 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
-												add validation and signature checks

also expands test cases

											
										
										
											2018-09-01 17:16:56 +00:00
+								 - consider removing pubKey from UpdateSignature - instead let channel module access accountMapper
-												prioritise todos

											
										
										
											2018-09-01 18:37:10 +00:00
+								 - refactor queue into one object
-												add usage instructions

											
										
										
											2018-09-02 02:57:42 +00:00
+								 - remove printout during tests caused by mock app initialisation