From 2b1583167227d0bfa29a63ccdc7e809ebeed4b2c Mon Sep 17 00:00:00 2001 From: Dirk McCormick Date: Tue, 18 Aug 2020 16:07:04 -0400 Subject: [PATCH 1/2] docs: payment channels --- documentation/en/.library.json | 7 +++ documentation/en/payment-channels.md | 82 ++++++++++++++++++++++++++++ 2 files changed, 89 insertions(+) create mode 100644 documentation/en/payment-channels.md diff --git a/documentation/en/.library.json b/documentation/en/.library.json index 4d348c145..85282779c 100644 --- a/documentation/en/.library.json +++ b/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", diff --git a/documentation/en/payment-channels.md b/documentation/en/payment-channels.md new file mode 100644 index 000000000..b1729dc47 --- /dev/null +++ b/documentation/en/payment-channels.md @@ -0,0 +1,82 @@ +# Payment Channels + +Payment channels are used to transfer funds between two actors. + +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. + +## Using the CLI + +For example a client creates a payment channel to a provider with value 10. + +```sh +$ lotus paych get 10 + +``` + +The client creates a voucher in lane 0 (implied) with nonce 1 (implied) and value 2. + +```sh +$ lotus paych voucher create 2 + +``` + +The client sends the voucher to the provider and the provider adds the voucher to their local store. + +```sh +$ lotus paych voucher add +``` + +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 4 + +``` + +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 5 + # Same address as above. Channel now has 15 +``` + +Once the client has received all their data, they settle the channel. + +```sh +$ lotus paych settle +``` + +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 + + + + +$ lotus paych voucher submit +``` + +Once the settlement period is over, either the client or provider can call collect to disburse funds. + +```sh +$ lotus paych collect +``` From 20cb9425cce830f4a53fd4d399b661d6a5bf6951 Mon Sep 17 00:00:00 2001 From: Dirk McCormick Date: Wed, 19 Aug 2020 08:43:06 -0400 Subject: [PATCH 2/2] docs: paych edits --- documentation/en/payment-channels.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/documentation/en/payment-channels.md b/documentation/en/payment-channels.md index b1729dc47..44f9affd9 100644 --- a/documentation/en/payment-channels.md +++ b/documentation/en/payment-channels.md @@ -2,7 +2,7 @@ Payment channels are used to transfer funds between two actors. -In lotus a payment channel is created when a client wants to fetch data from a provider. +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. @@ -15,9 +15,11 @@ Collect sends the value of submitted vouchers to the channel recipient (the prov 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. +For example a client creates a payment channel to a provider with value 10 FIL. ```sh $ lotus paych get 10 @@ -56,7 +58,9 @@ $ lotus paych get 5 # Same address as above. Channel now has 15 ``` -Once the client has received all their data, they settle the channel. +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