Merge pull request #3157 from filecoin-project/docs/paych

Payment channel lotu.sh docs

documentation/en/.library.json

@@ -143,6 +143,13 @@
       "value": null,
       "posts": []
     },
+    {
+      "title": "Payment Channels",
+      "slug": "en+payment-channels",
+      "github": "en/payment-channels.md",
+      "value": null,
+      "posts": []
+    },
     {
       "title": "Command Line Interface",
       "slug": "en+cli",

documentation/en/payment-channels.md

@@ -0,0 +1,86 @@
+# Payment Channels
+
+Payment channels are used to transfer funds between two actors.
+
+For example in lotus a payment channel is created when a client wants to fetch data from a provider.
+The client sends vouchers for the payment channel, and the provider sends data in response.
+
+The payment channel is created on-chain with an initial amount.
+Vouchers allow the client and the provider to exchange funds incrementally off-chain.
+The provider can submit vouchers to chain at any stage.
+Either party to the payment channel can settle the payment channel on chain.
+After a settlement period (currently 12 hours) either party to the payment channel can call collect on chain.
+Collect sends the value of submitted vouchers to the channel recipient (the provider), and refunds the remaining channel balance to the channel creator (the client).
+
+Vouchers have a lane, a nonce and a value, where vouchers with a higher nonce supersede vouchers with a lower nonce in the same lane.
+Each deal is created on a different lane. 
+
+Note that payment channels and vouchers can be used for any situation in which two parties need to incrementally transfer value between each other off-chain.
+
+## Using the CLI
+
+For example a client creates a payment channel to a provider with value 10 FIL.
+
+```sh
+$ lotus paych get <client addr> <provider addr> 10
+<channel addr>
+```
+
+The client creates a voucher in lane 0 (implied) with nonce 1 (implied) and value 2.
+
+```sh
+$ lotus paych voucher create <channel addr> 2
+<voucher>
+```
+
+The client sends the voucher to the provider and the provider adds the voucher to their local store.
+
+```sh
+$ lotus paych voucher add <channel addr> <voucher>
+```
+
+The provider sends some data to the client.
+
+The client creates a voucher in lane 0 (implied) with nonce 2 (implied) and value 4.
+
+```sh
+$ lotus paych voucher create <channel addr> 4
+<voucher>
+```
+
+The client sends the voucher to the provider and the provider adds the voucher and sends back more data.
+etc.
+
+The client can add value to the channel after it has been created by calling `paych get` with the same client and provider addresses.
+
+```sh
+$ lotus paych get <client addr> <provider addr> 5
+<channel addr> # Same address as above. Channel now has 15
+```
+
+Once the client has received all their data, they may settle the channel.
+Note that settlement doesn't have to be done immediately.
+For example the client may keep the channel open as long as it wants to continue making deals with the provider.
+
+```sh
+$ lotus paych settle <channel addr>
+```
+
+The provider can submit vouchers to chain (note that lotus does this automatically when it sees a settle message appear on chain).
+The provider may have received many vouchers with incrementally higher values.
+The provider should submit the best vouchers. Note that there will be one best voucher for each lane.
+
+```sh
+$ lotus paych voucher best-spendable <channel addr>
+<voucher>
+<voucher>
+<voucher>
+
+$ lotus paych voucher submit <channel addr> <voucher>
+```
+
+Once the settlement period is over, either the client or provider can call collect to disburse funds.
+
+```sh
+$ lotus paych collect <channel addr>
+```