From af3866e409c01ab13288e8cb4ce9db3823835773 Mon Sep 17 00:00:00 2001 From: Philipp Hoenisch Date: Wed, 24 Apr 2019 16:51:30 +1000 Subject: [PATCH 01/22] Add spike for LN as alpha ledger --- 0003-lightning-as-alpha-ledger.md | 146 ++++++++++++++++++++++++++++++ index.md | 3 + 2 files changed, 149 insertions(+) create mode 100644 0003-lightning-as-alpha-ledger.md diff --git a/0003-lightning-as-alpha-ledger.md b/0003-lightning-as-alpha-ledger.md new file mode 100644 index 0000000..543e565 --- /dev/null +++ b/0003-lightning-as-alpha-ledger.md @@ -0,0 +1,146 @@ +# LND as Alpha Ledger as decribed in RFC003 + +* Authors: Philipp Hoenisch +* Date: 2019-04-24 + +Tracking issue: TBA + +## Context + +The **Hold invoice feature** was introduced in the following PR: [lightningnetwork/lnd/pull/2022](https://github.com/lightningnetwork/lnd/pull/2022). +> A hold invoice is a new type of invoice that triggers a different flow at the receiver end. +> Instead of immediately locking in and settling the htlc when the payment arrives, the htlc for a hold invoice is only locked in and not yet settled. +> At that point, it is not possible anymore for the sender to revoke the payment, but the receiver still can choose whether to settle or cancel the htlc and invoice. + +This allows us to trade Bitcoin on the Lightning Network (LN) for an asset _X_ on a different ledger where LN is the _alpha ledger_ as per the definition in [RFC003](https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md). +For the other way around, Bitcoin on the Lightning Network is the _beta asset/ledger_, we can make use of `createinvoice`. + +### Standard _hold invoice_ process + +> Assumption: Alice wants to pay Bob _X_ Bitcoin using the LN but Bob does not generate the preimage - Alice does it. +1) Alice generates a secret preimage `p` and sends the hash of it `h(p)` to Bob. +2) Bob calls `addholdinvoice` with an amount `X` and the hashed preimage `h(p)` ([more details](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L142)). +3) Bob sends the generated invoice to Alice. +4) Alice now can pay the invoice using `sendpayment`. +5) As soon as Alice is happy (because she is in a good mode), she tells Bob the secret (or he learns it otherwise, see below). +6) Bob settles the payment by calling `settleInvoice` ([more details](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L53)). + +The payment is complete. + +## Research + +> Assumption: Bob wants to receive _X_ Bitcoin (**A** Asset) on the LN (**alpha** Ledger) for _Y_ Ether (**B** Asset) on Ethereum (**beta** Ledger) +> Alice magically finds out about this _whish_ or using a [COMIT link](fill in some link). +> +> * Alpha Ledger: Lightning Network +> * Alpha Asset: Bitcoin on the Lighting Network +> * Beta Ledger: Ethereum +> * Beta Asset: Ether + +### Step-by-step description + +1) Alice generates a secret preimage `p` and sends a swap request to Bob, this includes (assets with amounts are emitted): + +| Name | JSON Encoding | Description | +|:-------------------------|:---------------------|:--------------------------------------------------------------------------------------------------------------| +| `alpha_expiry` | `u32` | The UNIX timestamp of the time-lock for LN (alpha Ledger) | +| `beta_expiry` | `u32` | The UNIX timestamp of the time-lock on the beta HTLC | +| `alpha_refund_identity` | `α::Identity` | This can be empty as the refund identity will be handled by LN. | +| `beta_redeem_identity` | `β::Identity` | The identity on beta that **B** will be transferred to when the beta-HTLC is activated with the correct secret | +| `secret_hash` | `hex-encoded-bytes` | The output of calling `hash_function` on the secret | + +2) Bob _accepts_ the request and performs the following step: + * Create a hold incoice using `addholdinvoice` with the amount `X` and the hashed preimage `secret_hash` ([more details](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L142)). + * Bob _subscribes_ to the invoice and waits for the payment either using + * `SubscribeSingleInvoice` - this is not available through the CLI but as RPC; or + * `LookupInvoice` - this is available trough the CLI but needs to be polled regularly. +3) Bob response to Alice's request with the following information: + +| Name | JSON Encoding | Description | +|-------------------------|---------------|-----------------------------------------------------------------------------------------------------------| +| `alpha_redeem_identity` | `α::Identity` | The identity on alpha that **A**, this is the LN `invoice` | +| `beta_refund_identity` | `β::Identity` | The identity on beta that **B** will be transferred to when the beta-HTLC is activated after `beta_expiry` | + +4) Alice now starts the [exection phase](https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md#1-alice-deploys-%CE%B1-htlc) by paying the invoice using the LND command `sendpayment`. +5) Bob gets notified about funding of alpha (i.e. the invoice has been paid but cannot be settled yet), and continues with [deploying beta-HTLC](https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md#2-bob-deploys-%CE%B2-htlc), i.e. he deploys a HTLC on Ethereum. +6) As soon as beta has enough confirmations for Alice, she redeems the beta-HTLC using her secret. +7) Bob gets notified about this, learns the secret and can now settle the LND invoice by invoking the LND command `settleInvoice` ([more details](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L53)). + +The trade is complete. + +### Considerations and limitations + +#### Lightning Network: a new ledger +Similiar to the ledger definitions for [Bitcoin](https://github.com/comit-network/RFCs/blob/master/RFC-004-Bitcoin.md) and [Ethereum](https://github.com/comit-network/RFCs/blob/master/RFC-006-Ethereum.md) we need to handle the Lightning Network differently. +This is required because the comit-node and btsieve need to perform different actions accordingly. +We are always talking about Ledgers and Assets, (e.g. _Bitcoin_ Asset on the _Bitcoin_ Ledger, _Ether_ Asset on the _Ethereum_ Ledger, _Erc20_ on the _Ethereum_ Ledger, ...), Hence, +if we follow this approach, for supporting LN (through LND) we will need to introduce a new pair of Ledger and Asset: + +* Ledger: the **Lightning Network**. _Ledgers_ are used as _settlement layers_ for our HTLCs. In the case of LND, this layer is the Lightning Network. +* Asset: **Bitcoin**. Since LN is a layer-2 network on top of Bitcoin, the asset should also be Bitcoin. + +#### Timeouts +When calling `addholdinvoice` an [`expiry`](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L142) (in seconds) can be given. However, this timeout is relative and will get accumulated across the payment path. +Hence, Alice will need to know the path and this value in advance before sending a swap request to Bob as she won't (or should not) be able to change neither `alpha_expiry` nor `beta_expiry` after the swap request. + +#### Responsabilitites + +A main goal of COMIT is to keep the autonomy to the user and let him/her decide when to deploy a HTLC, redeem or refund a HTLC, etc. +If a trade involves LN using LND we can aproach these things differently: + + +* Action + * Create hold invoice +* Responsibility + * LND +* Invoker + * User, comit-i, comit-node +* Description + * `addholdinvoice` is available as a RPC command or through the LND CLI. Althoug dealing with this is rather cumbersome, to keep the autonomy with the user, and to not introduce LND dependency into the comit-node, we this should be possible through comit-i. +* Conclusion: + * comit-i needs LND support + + +* Action + * Pay invoice +* Responsibility: + * LND or LN Wallet +* Invoker + * User, comit-i +* Description + * To keep the autonomy to the user when to initiate a trade, we should return the invoice information through our API to the user (e.g. expose it through comit-i ) and let him/her pay the invoice. +* Conclusion + * comit-i needs LND support + + +* Action: + * Settle Invoice +* Responsibility + * LND or LN Wallet +* Invoker + * User, comit-i, comit-node +* Description + * As soon as the secret has been learned, the HTLC on the LN should be settled using the command `settleinvoice`, this can either be done by the user (and exposed through comit-i) or done automatically through the comit-node. Since we have the extra _redeem_ step for Bitcoin and Ethereum (as well for Erc20) which needs to be performed from the user, we should leave the settlement of the invoice to the user (e.g. expose this information through comit-i). +* Conclusion + * comit-i needs LND support + +* Action + * Monitor LN +* Responsibility + * LND +* Invoker + * Btsieve +* Description + * Similar to other Ledgers we need to monitor LN for the payment (and later on settlement) of an invoice. To keep our current abstraction layer, this should be done through btsieve +* Conclusion + * btsieve needs LND support + + +# COMIT link relation +Assumption: Bob is the creator of the link and is willing to receive Bitcoin for Ether for 1:10. + +Bob cannot yet create a hold invoice, i.e. `addholdinvoice` as he does not know the secret yet, hence, all he can add in the link is the information about Ledgers, Assets and exchange rates. + +## Fall-back mechanism of LN +LN allows to specificy a fallback address (_fallback_addr_) in when creating calling `addholdinvoice`. +We could use this information to fall back to an on-chain HTLC trade if no route can be found between Alice and Bob. diff --git a/index.md b/index.md index 1248f0d..6d65fab 100644 --- a/index.md +++ b/index.md @@ -4,5 +4,8 @@ List of spike outcomes for COMIT network. [spike-0000](0000-use-madr-like-solution-for-spike-outcomes.md) - Use MADR-like solution for spike outcomes - coblox/docs#36 [spike-0001](0001-basic-expiry-model.md) - Propose basic model to calculate expiry times - comit-network/RFCs#14 +[spike-0002](0002-ether-htlc-dynamic-final-addresses.md) - Ether HTLC with dynamic final addresses +[spike-0003](0003-hodl-invoice.md) - Allow trading assets against Bitcoin on the Lightning Network. + For new spike outcomes, please use [template.md](template.md) as basis. From 5ed5191759a73b4293303c855dfd9eff609572ac Mon Sep 17 00:00:00 2001 From: Philipp Hoenisch Date: Wed, 24 Apr 2019 17:03:16 +1000 Subject: [PATCH 02/22] Added some formatting --- 0003-lightning-as-alpha-ledger.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/0003-lightning-as-alpha-ledger.md b/0003-lightning-as-alpha-ledger.md index 543e565..b567c01 100644 --- a/0003-lightning-as-alpha-ledger.md +++ b/0003-lightning-as-alpha-ledger.md @@ -101,6 +101,9 @@ If a trade involves LN using LND we can aproach these things differently: * comit-i needs LND support +--- + + * Action * Pay invoice * Responsibility: @@ -113,6 +116,10 @@ If a trade involves LN using LND we can aproach these things differently: * comit-i needs LND support + +--- + + * Action: * Settle Invoice * Responsibility @@ -124,6 +131,11 @@ If a trade involves LN using LND we can aproach these things differently: * Conclusion * comit-i needs LND support + + +--- + + * Action * Monitor LN * Responsibility From 9a08f67a0dab2d6ff4e684b5b1cb43dd5cf0367b Mon Sep 17 00:00:00 2001 From: Philipp Hoenisch Date: Wed, 24 Apr 2019 17:05:45 +1000 Subject: [PATCH 03/22] Add more formatting --- 0003-lightning-as-alpha-ledger.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/0003-lightning-as-alpha-ledger.md b/0003-lightning-as-alpha-ledger.md index b567c01..3f22f37 100644 --- a/0003-lightning-as-alpha-ledger.md +++ b/0003-lightning-as-alpha-ledger.md @@ -148,11 +148,11 @@ If a trade involves LN using LND we can aproach these things differently: * btsieve needs LND support -# COMIT link relation +#### COMIT link relation Assumption: Bob is the creator of the link and is willing to receive Bitcoin for Ether for 1:10. Bob cannot yet create a hold invoice, i.e. `addholdinvoice` as he does not know the secret yet, hence, all he can add in the link is the information about Ledgers, Assets and exchange rates. -## Fall-back mechanism of LN +#### Fall-back mechanism of LN LN allows to specificy a fallback address (_fallback_addr_) in when creating calling `addholdinvoice`. We could use this information to fall back to an on-chain HTLC trade if no route can be found between Alice and Bob. From 12f46f0dc622959cd663618aa846b96c9b25348e Mon Sep 17 00:00:00 2001 From: Philipp Hoenisch Date: Wed, 24 Apr 2019 17:41:24 +1000 Subject: [PATCH 04/22] Formatiing --- 0003-lightning-as-alpha-ledger.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/0003-lightning-as-alpha-ledger.md b/0003-lightning-as-alpha-ledger.md index 3f22f37..98b6851 100644 --- a/0003-lightning-as-alpha-ledger.md +++ b/0003-lightning-as-alpha-ledger.md @@ -68,9 +68,9 @@ The payment is complete. The trade is complete. -### Considerations and limitations +## Spike Outcome -#### Lightning Network: a new ledger +### Lightning Network: a new ledger Similiar to the ledger definitions for [Bitcoin](https://github.com/comit-network/RFCs/blob/master/RFC-004-Bitcoin.md) and [Ethereum](https://github.com/comit-network/RFCs/blob/master/RFC-006-Ethereum.md) we need to handle the Lightning Network differently. This is required because the comit-node and btsieve need to perform different actions accordingly. We are always talking about Ledgers and Assets, (e.g. _Bitcoin_ Asset on the _Bitcoin_ Ledger, _Ether_ Asset on the _Ethereum_ Ledger, _Erc20_ on the _Ethereum_ Ledger, ...), Hence, @@ -79,11 +79,11 @@ if we follow this approach, for supporting LN (through LND) we will need to intr * Ledger: the **Lightning Network**. _Ledgers_ are used as _settlement layers_ for our HTLCs. In the case of LND, this layer is the Lightning Network. * Asset: **Bitcoin**. Since LN is a layer-2 network on top of Bitcoin, the asset should also be Bitcoin. -#### Timeouts +### Dealing with timeouts When calling `addholdinvoice` an [`expiry`](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L142) (in seconds) can be given. However, this timeout is relative and will get accumulated across the payment path. Hence, Alice will need to know the path and this value in advance before sending a swap request to Bob as she won't (or should not) be able to change neither `alpha_expiry` nor `beta_expiry` after the swap request. -#### Responsabilitites +### Responsabilitites A main goal of COMIT is to keep the autonomy to the user and let him/her decide when to deploy a HTLC, redeem or refund a HTLC, etc. If a trade involves LN using LND we can aproach these things differently: @@ -148,11 +148,11 @@ If a trade involves LN using LND we can aproach these things differently: * btsieve needs LND support -#### COMIT link relation +### COMIT link relation Assumption: Bob is the creator of the link and is willing to receive Bitcoin for Ether for 1:10. Bob cannot yet create a hold invoice, i.e. `addholdinvoice` as he does not know the secret yet, hence, all he can add in the link is the information about Ledgers, Assets and exchange rates. -#### Fall-back mechanism of LN +### Fall-back mechanism of LN LN allows to specificy a fallback address (_fallback_addr_) in when creating calling `addholdinvoice`. We could use this information to fall back to an on-chain HTLC trade if no route can be found between Alice and Bob. From c4a86dfaeab83964aae6f57d62b5f1dbec846cb8 Mon Sep 17 00:00:00 2001 From: Philipp Hoenisch Date: Fri, 26 Apr 2019 08:36:06 +1000 Subject: [PATCH 05/22] Added review feedback --- 0003-lightning-as-alpha-ledger.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/0003-lightning-as-alpha-ledger.md b/0003-lightning-as-alpha-ledger.md index 98b6851..28f8878 100644 --- a/0003-lightning-as-alpha-ledger.md +++ b/0003-lightning-as-alpha-ledger.md @@ -13,7 +13,7 @@ The **Hold invoice feature** was introduced in the following PR: [lightningnetwo > At that point, it is not possible anymore for the sender to revoke the payment, but the receiver still can choose whether to settle or cancel the htlc and invoice. This allows us to trade Bitcoin on the Lightning Network (LN) for an asset _X_ on a different ledger where LN is the _alpha ledger_ as per the definition in [RFC003](https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md). -For the other way around, Bitcoin on the Lightning Network is the _beta asset/ledger_, we can make use of `createinvoice`. +For the other way around, Bitcoin on the Lightning Network is the _beta asset/ledger_, we can make use of `createinvoice` as Alice would instantly release the secret by settling Bob's LN payment. ### Standard _hold invoice_ process @@ -22,7 +22,7 @@ For the other way around, Bitcoin on the Lightning Network is the _beta asset/le 2) Bob calls `addholdinvoice` with an amount `X` and the hashed preimage `h(p)` ([more details](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L142)). 3) Bob sends the generated invoice to Alice. 4) Alice now can pay the invoice using `sendpayment`. -5) As soon as Alice is happy (because she is in a good mode), she tells Bob the secret (or he learns it otherwise, see below). +5) As soon as Alice is happy (because she is in a good mood), she tells Bob the secret (or he learns it otherwise, see below). 6) Bob settles the payment by calling `settleInvoice` ([more details](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L53)). The payment is complete. @@ -30,10 +30,10 @@ The payment is complete. ## Research > Assumption: Bob wants to receive _X_ Bitcoin (**A** Asset) on the LN (**alpha** Ledger) for _Y_ Ether (**B** Asset) on Ethereum (**beta** Ledger) -> Alice magically finds out about this _whish_ or using a [COMIT link](fill in some link). +> Alice magically finds out about this _wish_ or using a [COMIT link](fill in some link). > > * Alpha Ledger: Lightning Network -> * Alpha Asset: Bitcoin on the Lighting Network +> * Alpha Asset: Bitcoin > * Beta Ledger: Ethereum > * Beta Asset: Ether @@ -61,7 +61,7 @@ The payment is complete. | `alpha_redeem_identity` | `α::Identity` | The identity on alpha that **A**, this is the LN `invoice` | | `beta_refund_identity` | `β::Identity` | The identity on beta that **B** will be transferred to when the beta-HTLC is activated after `beta_expiry` | -4) Alice now starts the [exection phase](https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md#1-alice-deploys-%CE%B1-htlc) by paying the invoice using the LND command `sendpayment`. +4) Alice now starts the [execution phase](https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md#1-alice-deploys-%CE%B1-htlc) by paying the invoice using the LND command `sendpayment`. 5) Bob gets notified about funding of alpha (i.e. the invoice has been paid but cannot be settled yet), and continues with [deploying beta-HTLC](https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md#2-bob-deploys-%CE%B2-htlc), i.e. he deploys a HTLC on Ethereum. 6) As soon as beta has enough confirmations for Alice, she redeems the beta-HTLC using her secret. 7) Bob gets notified about this, learns the secret and can now settle the LND invoice by invoking the LND command `settleInvoice` ([more details](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L53)). @@ -80,13 +80,19 @@ if we follow this approach, for supporting LN (through LND) we will need to intr * Asset: **Bitcoin**. Since LN is a layer-2 network on top of Bitcoin, the asset should also be Bitcoin. ### Dealing with timeouts -When calling `addholdinvoice` an [`expiry`](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L142) (in seconds) can be given. However, this timeout is relative and will get accumulated across the payment path. -Hence, Alice will need to know the path and this value in advance before sending a swap request to Bob as she won't (or should not) be able to change neither `alpha_expiry` nor `beta_expiry` after the swap request. +When calling `addholdinvoice` an [`expiry`](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L142) (in seconds) can be given. However, this expiry is only related to the invoice itself and has nothing to do with the expiry times on the HTLCs later on. +However, timeouts on the HTLCs are relative and will get accumulated across the payment path, which makes it harder to predict. +Hence, Alice will need to know the path in advance before sending a swap request to Bob as she won't (or should not) be able to change neither `alpha_expiry` nor `beta_expiry` after the swap request. + +Timeouts on the HTLCs are configured globally for the payee node and can optionally be defined when paying by the payer node (`--final_cltv_delta=T`). + +> TODO: we should investigate this topic more in detail. + ### Responsabilitites A main goal of COMIT is to keep the autonomy to the user and let him/her decide when to deploy a HTLC, redeem or refund a HTLC, etc. -If a trade involves LN using LND we can aproach these things differently: +If a trade involves LN using LND we can approach these things differently: * Action From 1738f726e041807f628ab9f2fbbd84f8938f24f6 Mon Sep 17 00:00:00 2001 From: Philipp Hoenisch Date: Fri, 26 Apr 2019 10:22:21 +1000 Subject: [PATCH 06/22] Fix typo --- 0003-lightning-as-alpha-ledger.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/0003-lightning-as-alpha-ledger.md b/0003-lightning-as-alpha-ledger.md index 28f8878..3e1f7a4 100644 --- a/0003-lightning-as-alpha-ledger.md +++ b/0003-lightning-as-alpha-ledger.md @@ -89,7 +89,7 @@ Timeouts on the HTLCs are configured globally for the payee node and can optiona > TODO: we should investigate this topic more in detail. -### Responsabilitites +### Responsibilities A main goal of COMIT is to keep the autonomy to the user and let him/her decide when to deploy a HTLC, redeem or refund a HTLC, etc. If a trade involves LN using LND we can approach these things differently: From 3f8347d798cdf9b467dcf355a9d5a60332cd4946 Mon Sep 17 00:00:00 2001 From: Franck Royer Date: Fri, 26 Apr 2019 20:07:30 +1000 Subject: [PATCH 07/22] Update 0003-lightning-as-alpha-ledger.md Co-Authored-By: bonomat --- 0003-lightning-as-alpha-ledger.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/0003-lightning-as-alpha-ledger.md b/0003-lightning-as-alpha-ledger.md index 3e1f7a4..9c27ebf 100644 --- a/0003-lightning-as-alpha-ledger.md +++ b/0003-lightning-as-alpha-ledger.md @@ -102,7 +102,7 @@ If a trade involves LN using LND we can approach these things differently: * Invoker * User, comit-i, comit-node * Description - * `addholdinvoice` is available as a RPC command or through the LND CLI. Althoug dealing with this is rather cumbersome, to keep the autonomy with the user, and to not introduce LND dependency into the comit-node, we this should be possible through comit-i. + * `addholdinvoice` is available as a RPC command or through the LND CLI. Although dealing with this is rather cumbersome, to keep the autonomy with the user, and to not introduce LND dependency into the comit-node, we this should be possible through comit-i. * Conclusion: * comit-i needs LND support From b203b8ff2c5b35e563834262e8d0bff61ee3f4ec Mon Sep 17 00:00:00 2001 From: Philipp Hoenisch Date: Mon, 29 Apr 2019 13:18:08 +1000 Subject: [PATCH 08/22] Move to ascii doc --- README.adoc | 1 + README.md | 1 - template.adoc | 16 ++++++++++++++++ template.md | 14 -------------- 4 files changed, 17 insertions(+), 15 deletions(-) create mode 100644 README.adoc delete mode 100644 README.md create mode 100644 template.adoc delete mode 100644 template.md diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..9f38df6 --- /dev/null +++ b/README.adoc @@ -0,0 +1 @@ += COMIT research outcomes diff --git a/README.md b/README.md deleted file mode 100644 index d6bbad8..0000000 --- a/README.md +++ /dev/null @@ -1 +0,0 @@ -COMIT research outcomes diff --git a/template.adoc b/template.adoc new file mode 100644 index 0000000..6085cd5 --- /dev/null +++ b/template.adoc @@ -0,0 +1,16 @@ += [short title describing spike] + +NOTE: Authors: [list everyone involved in the research] + +Date: [YYYY-MM-DD when the spike outcome was last updated] + +Tracking issue: [link to corresponding spike] + +:toc: + +== Context + +[Short description of the context] + +== Research + +[Documentation of steps followed and findings] diff --git a/template.md b/template.md deleted file mode 100644 index 9ad2191..0000000 --- a/template.md +++ /dev/null @@ -1,14 +0,0 @@ -# [short title describing spike] - -* Authors: [list everyone involved in the research] -* Date: [YYYY-MM-DD when the spike outcome was last updated] - -Tracking issue: [link to corresponding spike] - -## Context - -[Short description of the context] - -## Research - -[Documentation of steps followed and findings] From 278cd84855177588f91f876d876ddd70e3f4a609 Mon Sep 17 00:00:00 2001 From: Philipp Hoenisch Date: Mon, 29 Apr 2019 13:31:49 +1000 Subject: [PATCH 09/22] Move to ascii doc for ln --- 0003-lightning-as-alpha-ledger.adoc | 207 ++++++++++++++++++++++++++++ 0003-lightning-as-alpha-ledger.md | 164 ---------------------- template.adoc | 3 +- 3 files changed, 208 insertions(+), 166 deletions(-) create mode 100644 0003-lightning-as-alpha-ledger.adoc delete mode 100644 0003-lightning-as-alpha-ledger.md diff --git a/0003-lightning-as-alpha-ledger.adoc b/0003-lightning-as-alpha-ledger.adoc new file mode 100644 index 0000000..1158c89 --- /dev/null +++ b/0003-lightning-as-alpha-ledger.adoc @@ -0,0 +1,207 @@ += LND as Alpha Ledger as described in RFC003 + +NOTE: Authors: Philipp Hoenisch + +Date: 2019-04-24 + +Tracking issue: TBA + +== Context + +The **Hold invoice feature** was introduced in the following PR: [lightningnetwork/lnd/pull/2022](https://github.com/lightningnetwork/lnd/pull/2022). +____ +A hold invoice is a new type of invoice that triggers a different flow at the receiver end. +Instead of immediately locking in and settling the htlc when the payment arrives, the htlc for a hold invoice is only locked in and not yet settled. +At that point, it is not possible anymore for the sender to revoke the payment, but the receiver still can choose whether to settle or cancel the htlc and invoice. +____ + +This allows us to trade Bitcoin on the Lightning Network (LN) for an asset _X_ on a different ledger where LN is the _alpha ledger_ as per the definition in [RFC003](https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md). +For the other way around, Bitcoin on the Lightning Network is the _beta asset/ledger_, we can make use of `createinvoice` as Alice would instantly release the secret by settling Bob's LN payment. + +=== Standard _hold invoice_ process + +____ +Assumption: Alice wants to pay Bob _X_ Bitcoin using the LN but Bob does not generate the preimage - Alice does it. +____ + +1) Alice generates a secret preimage `p` and sends the hash of it `h(p)` to Bob. +2) Bob calls `addholdinvoice` with an amount `X` and the hashed preimage `h(p)` ([more details](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L142)). +3) Bob sends the generated invoice to Alice. +4) Alice now can pay the invoice using `sendpayment`. +5) As soon as Alice is happy (because she is in a good mood), she tells Bob the secret (or he learns it otherwise, see below). +6) Bob settles the payment by calling `settleInvoice` ([more details](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L53)). + +The payment is complete. + +== Research + +____ +Assumption: Bob wants to receive _X_ Bitcoin (**A** Asset) on the LN (**alpha** Ledger) for _Y_ Ether (**B** Asset) on Ethereum (**beta** Ledger) +Alice magically finds out about this _wish_ or using a [COMIT link](fill in some link). + +* Alpha Ledger: Lightning Network +* Alpha Asset: Bitcoin +* Beta Ledger: Ethereum +* Beta Asset: Ether +____ + +=== Step-by-step description + +. Alice generates a secret preimage `p` and sends a swap request to Bob, this includes (assets with amounts are emitted): + +[cols=3*,options=header] +|=== +| Name +| JSON Encoding +| Description + +| `alpha_expiry` +| `u32` +| The UNIX timestamp of the time-lock for LN (alpha Ledger) + +| `beta_expiry` +| `u32` +| The UNIX timestamp of the time-lock on the beta HTLC + +| `alpha_refund_identity` +| `α::Identity` +| This can be empty as the refund identity will be handled by LN. + +| `beta_redeem_identity` +| `β::Identity` +| The identity on beta that **B** will be transferred to when the beta-HTLC is activated with the correct secret + +| `secret_hash` +| `hex-encoded-bytes` +| The output of calling `hash_function` on the secret + +|=== + +[start=2] +2. Bob _accepts_ the request and performs the following step: + .. Create a hold incoice using `addholdinvoice` with the amount `X` and the hashed preimage `secret_hash` ([more details](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L142)). + .. Bob _subscribes_ to the invoice and waits for the payment either using + ... `SubscribeSingleInvoice` - this is not available through the CLI but as RPC; or + ... `LookupInvoice` - this is available trough the CLI but needs to be polled regularly. +3. Bob response to Alice's request with the following information: + +[cols=3*,options=header] +|=== +| Name +| JSON Encoding +| Description + +| `alpha_redeem_identity` +| `α::Identity` +| The identity on alpha that **A**, this is the LN `invoice` + +| `beta_refund_identity` +| `β::Identity` +| The identity on beta that **B** will be transferred to when the beta-HTLC is activated after `beta_expiry` +|=== + +[start=4] +4. Alice now starts the [execution phase](https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md#1-alice-deploys-%CE%B1-htlc) by paying the invoice using the LND command `sendpayment`. +5. Bob gets notified about funding of alpha (i.e. the invoice has been paid but cannot be settled yet), and continues with [deploying beta-HTLC](https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md#2-bob-deploys-%CE%B2-htlc), i.e. he deploys a HTLC on Ethereum. +6. As soon as beta has enough confirmations for Alice, she redeems the beta-HTLC using her secret. +7. Bob gets notified about this, learns the secret and can now settle the LND invoice by invoking the LND command `settleInvoice` ([more details](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L53)). + +The trade is complete. + +== Spike Outcome + +=== Lightning Network: a new ledger +Similiar to the ledger definitions for [Bitcoin](https://github.com/comit-network/RFCs/blob/master/RFC-004-Bitcoin.md) and [Ethereum](https://github.com/comit-network/RFCs/blob/master/RFC-006-Ethereum.md) we need to handle the Lightning Network differently. +This is required because the comit-node and btsieve need to perform different actions accordingly. +We are always talking about Ledgers and Assets, (e.g. _Bitcoin_ Asset on the _Bitcoin_ Ledger, _Ether_ Asset on the _Ethereum_ Ledger, _Erc20_ on the _Ethereum_ Ledger, ...), Hence, +if we follow this approach, for supporting LN (through LND) we will need to introduce a new pair of Ledger and Asset: + +* Ledger: the **Lightning Network**. _Ledgers_ are used as _settlement layers_ for our HTLCs. In the case of LND, this layer is the Lightning Network. +* Asset: **Bitcoin**. Since LN is a layer-2 network on top of Bitcoin, the asset should also be Bitcoin. + +=== Dealing with timeouts +When calling `addholdinvoice` an [`expiry`](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L142) (in seconds) can be given. However, this expiry is only related to the invoice itself and has nothing to do with the expiry times on the HTLCs later on. +However, timeouts on the HTLCs are relative and will get accumulated across the payment path, which makes it harder to predict. +Hence, Alice will need to know the path in advance before sending a swap request to Bob as she won't (or should not) be able to change neither `alpha_expiry` nor `beta_expiry` after the swap request. + +Timeouts on the HTLCs are configured globally for the payee node and can optionally be defined when paying by the payer node (`--final_cltv_delta=T`). + + +IMPORTANT: TODO: we should investigate this topic more in detail. + +=== Responsibilities + +A main goal of COMIT is to keep the autonomy to the user and let him/her decide when to deploy a HTLC, redeem or refund a HTLC, etc. +If a trade involves LN using LND we can approach these things differently: + + +* Action + ** Create hold invoice +* Responsibility + ** LND +* Invoker + ** User, comit-i, comit-node +* Description + ** `addholdinvoice` is available as a RPC command or through the LND CLI. Althoug dealing with this is rather cumbersome, to keep the autonomy with the user, and to not introduce LND dependency into the comit-node, we this should be possible through comit-i. +* Conclusion: + ** comit-i needs LND support + + +--- + + +* Action + ** Pay invoice +* Responsibility: + ** LND or LN Wallet +* Invoker + ** User, comit-i +* Description + ** To keep the autonomy to the user when to initiate a trade, we should return the invoice information through our API to the user (e.g. expose it through comit-i ) and let him/her pay the invoice. +* Conclusion + ** comit-i needs LND support + + + +--- + + +* Action: + ** Settle Invoice +* Responsibility + ** LND or LN Wallet +* Invoker + ** User, comit-i, comit-node +* Description + ** As soon as the secret has been learned, the HTLC on the LN should be settled using the command `settleinvoice`, this can either be done by the user (and exposed through comit-i) or done automatically through the comit-node. Since we have the extra _redeem_ step for Bitcoin and Ethereum (as well for Erc20) which needs to be performed from the user, we should leave the settlement of the invoice to the user (e.g. expose this information through comit-i). +* Conclusion + ** comit-i needs LND support + + + +--- + + +* Action + ** Monitor LN +* Responsibility + ** LND +* Invoker + ** Btsieve +* Description + ** Similar to other Ledgers we need to monitor LN for the payment (and later on settlement) of an invoice. To keep our current abstraction layer, this should be done through btsieve +* Conclusion + ** btsieve needs LND support + + +=== COMIT link relation +Assumption: Bob is the creator of the link and is willing to receive Bitcoin for Ether for 1:10. + +Bob cannot yet create a hold invoice, i.e. `addholdinvoice` as he does not know the secret yet, hence, all he can add in the link is the information about Ledgers, Assets and exchange rates. + +=== Fall-back mechanism of LN +LN allows to specify a fallback address (_fallback_addr_) in when creating calling `addholdinvoice`. +We could use this information to fall back to an on-chain HTLC trade if no route can be found between Alice and Bob. + + +== Appendix + +=== Commands for call diff --git a/0003-lightning-as-alpha-ledger.md b/0003-lightning-as-alpha-ledger.md deleted file mode 100644 index 3e1f7a4..0000000 --- a/0003-lightning-as-alpha-ledger.md +++ /dev/null @@ -1,164 +0,0 @@ -# LND as Alpha Ledger as decribed in RFC003 - -* Authors: Philipp Hoenisch -* Date: 2019-04-24 - -Tracking issue: TBA - -## Context - -The **Hold invoice feature** was introduced in the following PR: [lightningnetwork/lnd/pull/2022](https://github.com/lightningnetwork/lnd/pull/2022). -> A hold invoice is a new type of invoice that triggers a different flow at the receiver end. -> Instead of immediately locking in and settling the htlc when the payment arrives, the htlc for a hold invoice is only locked in and not yet settled. -> At that point, it is not possible anymore for the sender to revoke the payment, but the receiver still can choose whether to settle or cancel the htlc and invoice. - -This allows us to trade Bitcoin on the Lightning Network (LN) for an asset _X_ on a different ledger where LN is the _alpha ledger_ as per the definition in [RFC003](https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md). -For the other way around, Bitcoin on the Lightning Network is the _beta asset/ledger_, we can make use of `createinvoice` as Alice would instantly release the secret by settling Bob's LN payment. - -### Standard _hold invoice_ process - -> Assumption: Alice wants to pay Bob _X_ Bitcoin using the LN but Bob does not generate the preimage - Alice does it. -1) Alice generates a secret preimage `p` and sends the hash of it `h(p)` to Bob. -2) Bob calls `addholdinvoice` with an amount `X` and the hashed preimage `h(p)` ([more details](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L142)). -3) Bob sends the generated invoice to Alice. -4) Alice now can pay the invoice using `sendpayment`. -5) As soon as Alice is happy (because she is in a good mood), she tells Bob the secret (or he learns it otherwise, see below). -6) Bob settles the payment by calling `settleInvoice` ([more details](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L53)). - -The payment is complete. - -## Research - -> Assumption: Bob wants to receive _X_ Bitcoin (**A** Asset) on the LN (**alpha** Ledger) for _Y_ Ether (**B** Asset) on Ethereum (**beta** Ledger) -> Alice magically finds out about this _wish_ or using a [COMIT link](fill in some link). -> -> * Alpha Ledger: Lightning Network -> * Alpha Asset: Bitcoin -> * Beta Ledger: Ethereum -> * Beta Asset: Ether - -### Step-by-step description - -1) Alice generates a secret preimage `p` and sends a swap request to Bob, this includes (assets with amounts are emitted): - -| Name | JSON Encoding | Description | -|:-------------------------|:---------------------|:--------------------------------------------------------------------------------------------------------------| -| `alpha_expiry` | `u32` | The UNIX timestamp of the time-lock for LN (alpha Ledger) | -| `beta_expiry` | `u32` | The UNIX timestamp of the time-lock on the beta HTLC | -| `alpha_refund_identity` | `α::Identity` | This can be empty as the refund identity will be handled by LN. | -| `beta_redeem_identity` | `β::Identity` | The identity on beta that **B** will be transferred to when the beta-HTLC is activated with the correct secret | -| `secret_hash` | `hex-encoded-bytes` | The output of calling `hash_function` on the secret | - -2) Bob _accepts_ the request and performs the following step: - * Create a hold incoice using `addholdinvoice` with the amount `X` and the hashed preimage `secret_hash` ([more details](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L142)). - * Bob _subscribes_ to the invoice and waits for the payment either using - * `SubscribeSingleInvoice` - this is not available through the CLI but as RPC; or - * `LookupInvoice` - this is available trough the CLI but needs to be polled regularly. -3) Bob response to Alice's request with the following information: - -| Name | JSON Encoding | Description | -|-------------------------|---------------|-----------------------------------------------------------------------------------------------------------| -| `alpha_redeem_identity` | `α::Identity` | The identity on alpha that **A**, this is the LN `invoice` | -| `beta_refund_identity` | `β::Identity` | The identity on beta that **B** will be transferred to when the beta-HTLC is activated after `beta_expiry` | - -4) Alice now starts the [execution phase](https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md#1-alice-deploys-%CE%B1-htlc) by paying the invoice using the LND command `sendpayment`. -5) Bob gets notified about funding of alpha (i.e. the invoice has been paid but cannot be settled yet), and continues with [deploying beta-HTLC](https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md#2-bob-deploys-%CE%B2-htlc), i.e. he deploys a HTLC on Ethereum. -6) As soon as beta has enough confirmations for Alice, she redeems the beta-HTLC using her secret. -7) Bob gets notified about this, learns the secret and can now settle the LND invoice by invoking the LND command `settleInvoice` ([more details](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L53)). - -The trade is complete. - -## Spike Outcome - -### Lightning Network: a new ledger -Similiar to the ledger definitions for [Bitcoin](https://github.com/comit-network/RFCs/blob/master/RFC-004-Bitcoin.md) and [Ethereum](https://github.com/comit-network/RFCs/blob/master/RFC-006-Ethereum.md) we need to handle the Lightning Network differently. -This is required because the comit-node and btsieve need to perform different actions accordingly. -We are always talking about Ledgers and Assets, (e.g. _Bitcoin_ Asset on the _Bitcoin_ Ledger, _Ether_ Asset on the _Ethereum_ Ledger, _Erc20_ on the _Ethereum_ Ledger, ...), Hence, -if we follow this approach, for supporting LN (through LND) we will need to introduce a new pair of Ledger and Asset: - -* Ledger: the **Lightning Network**. _Ledgers_ are used as _settlement layers_ for our HTLCs. In the case of LND, this layer is the Lightning Network. -* Asset: **Bitcoin**. Since LN is a layer-2 network on top of Bitcoin, the asset should also be Bitcoin. - -### Dealing with timeouts -When calling `addholdinvoice` an [`expiry`](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L142) (in seconds) can be given. However, this expiry is only related to the invoice itself and has nothing to do with the expiry times on the HTLCs later on. -However, timeouts on the HTLCs are relative and will get accumulated across the payment path, which makes it harder to predict. -Hence, Alice will need to know the path in advance before sending a swap request to Bob as she won't (or should not) be able to change neither `alpha_expiry` nor `beta_expiry` after the swap request. - -Timeouts on the HTLCs are configured globally for the payee node and can optionally be defined when paying by the payer node (`--final_cltv_delta=T`). - -> TODO: we should investigate this topic more in detail. - - -### Responsibilities - -A main goal of COMIT is to keep the autonomy to the user and let him/her decide when to deploy a HTLC, redeem or refund a HTLC, etc. -If a trade involves LN using LND we can approach these things differently: - - -* Action - * Create hold invoice -* Responsibility - * LND -* Invoker - * User, comit-i, comit-node -* Description - * `addholdinvoice` is available as a RPC command or through the LND CLI. Althoug dealing with this is rather cumbersome, to keep the autonomy with the user, and to not introduce LND dependency into the comit-node, we this should be possible through comit-i. -* Conclusion: - * comit-i needs LND support - - ---- - - -* Action - * Pay invoice -* Responsibility: - * LND or LN Wallet -* Invoker - * User, comit-i -* Description - * To keep the autonomy to the user when to initiate a trade, we should return the invoice information through our API to the user (e.g. expose it through comit-i ) and let him/her pay the invoice. -* Conclusion - * comit-i needs LND support - - - ---- - - -* Action: - * Settle Invoice -* Responsibility - * LND or LN Wallet -* Invoker - * User, comit-i, comit-node -* Description - * As soon as the secret has been learned, the HTLC on the LN should be settled using the command `settleinvoice`, this can either be done by the user (and exposed through comit-i) or done automatically through the comit-node. Since we have the extra _redeem_ step for Bitcoin and Ethereum (as well for Erc20) which needs to be performed from the user, we should leave the settlement of the invoice to the user (e.g. expose this information through comit-i). -* Conclusion - * comit-i needs LND support - - - ---- - - -* Action - * Monitor LN -* Responsibility - * LND -* Invoker - * Btsieve -* Description - * Similar to other Ledgers we need to monitor LN for the payment (and later on settlement) of an invoice. To keep our current abstraction layer, this should be done through btsieve -* Conclusion - * btsieve needs LND support - - -### COMIT link relation -Assumption: Bob is the creator of the link and is willing to receive Bitcoin for Ether for 1:10. - -Bob cannot yet create a hold invoice, i.e. `addholdinvoice` as he does not know the secret yet, hence, all he can add in the link is the information about Ledgers, Assets and exchange rates. - -### Fall-back mechanism of LN -LN allows to specificy a fallback address (_fallback_addr_) in when creating calling `addholdinvoice`. -We could use this information to fall back to an on-chain HTLC trade if no route can be found between Alice and Bob. diff --git a/template.adoc b/template.adoc index 6085cd5..56f8487 100644 --- a/template.adoc +++ b/template.adoc @@ -1,8 +1,7 @@ = [short title describing spike] NOTE: Authors: [list everyone involved in the research] + -Date: [YYYY-MM-DD when the spike outcome was last updated] - +Date: [YYYY-MM-DD when the spike outcome was last updated] + Tracking issue: [link to corresponding spike] :toc: From dfa73c001998aa52a59216abbd2fe74345131751 Mon Sep 17 00:00:00 2001 From: Philipp Hoenisch Date: Mon, 29 Apr 2019 14:34:33 +1000 Subject: [PATCH 10/22] Convert links --- 0003-lightning-as-alpha-ledger.adoc | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/0003-lightning-as-alpha-ledger.adoc b/0003-lightning-as-alpha-ledger.adoc index 49bc27a..c9c02c2 100644 --- a/0003-lightning-as-alpha-ledger.adoc +++ b/0003-lightning-as-alpha-ledger.adoc @@ -6,14 +6,14 @@ Tracking issue: TBA == Context -The **Hold invoice feature** was introduced in the following PR: [lightningnetwork/lnd/pull/2022](https://github.com/lightningnetwork/lnd/pull/2022). +The **Hold invoice feature** was introduced in the following PR: https://github.com/lightningnetwork/lnd/pull/2022[lightningnetwork/lnd/pull/2022]. ____ A hold invoice is a new type of invoice that triggers a different flow at the receiver end. Instead of immediately locking in and settling the htlc when the payment arrives, the htlc for a hold invoice is only locked in and not yet settled. At that point, it is not possible anymore for the sender to revoke the payment, but the receiver still can choose whether to settle or cancel the htlc and invoice. ____ -This allows us to trade Bitcoin on the Lightning Network (LN) for an asset _X_ on a different ledger where LN is the _alpha ledger_ as per the definition in [RFC003](https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md). +This allows us to trade Bitcoin on the Lightning Network (LN) for an asset _X_ on a different ledger where LN is the _alpha ledger_ as per the definition in https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md[RFC003]. For the other way around, Bitcoin on the Lightning Network is the _beta asset/ledger_, we can make use of `createinvoice` as Alice would instantly release the secret by settling Bob's LN payment. === Standard _hold invoice_ process @@ -23,11 +23,11 @@ Assumption: Alice wants to pay Bob _X_ Bitcoin using the LN but Bob does not gen ____ 1) Alice generates a secret preimage `p` and sends the hash of it `h(p)` to Bob. -2) Bob calls `addholdinvoice` with an amount `X` and the hashed preimage `h(p)` ([more details](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L142)). +2) Bob calls `addholdinvoice` with an amount `X` and the hashed preimage `h(p)` (https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L142[more details]). 3) Bob sends the generated invoice to Alice. 4) Alice now can pay the invoice using `sendpayment`. 5) As soon as Alice is happy (because she is in a good mood), she tells Bob the secret (or he learns it otherwise, see below). -6) Bob settles the payment by calling `settleInvoice` ([more details](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L53)). +6) Bob settles the payment by calling `settleInvoice` (https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L53[more details]). The payment is complete. @@ -77,7 +77,7 @@ ____ [start=2] 2. Bob _accepts_ the request and performs the following step: - .. Create a hold incoice using `addholdinvoice` with the amount `X` and the hashed preimage `secret_hash` ([more details](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L142)). + .. Create a hold incoice using `addholdinvoice` with the amount `X` and the hashed preimage `secret_hash` (https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L142[more details]). .. Bob _subscribes_ to the invoice and waits for the payment either using ... `SubscribeSingleInvoice` - this is not available through the CLI but as RPC; or ... `LookupInvoice` - this is available trough the CLI but needs to be polled regularly. @@ -99,17 +99,17 @@ ____ |=== [start=4] -4. Alice now starts the [execution phase](https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md#1-alice-deploys-%CE%B1-htlc) by paying the invoice using the LND command `sendpayment`. -5. Bob gets notified about funding of alpha (i.e. the invoice has been paid but cannot be settled yet), and continues with [deploying beta-HTLC](https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md#2-bob-deploys-%CE%B2-htlc), i.e. he deploys a HTLC on Ethereum. +4. Alice now starts the https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md#1-alice-deploys-%CE%B1-htlc[execution phase] by paying the invoice using the LND command `sendpayment`. +5. Bob gets notified about funding of alpha (i.e. the invoice has been paid but cannot be settled yet), and continues with https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md#2-bob-deploys-%CE%B2-htlc[deploying beta-HTLC], i.e. he deploys a HTLC on Ethereum. 6. As soon as beta has enough confirmations for Alice, she redeems the beta-HTLC using her secret. -7. Bob gets notified about this, learns the secret and can now settle the LND invoice by invoking the LND command `settleInvoice` ([more details](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L53)). +7. Bob gets notified about this, learns the secret and can now settle the LND invoice by invoking the LND command `settleInvoice` (https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L53[more details]). The trade is complete. == Spike Outcome === Lightning Network: a new ledger -Similiar to the ledger definitions for [Bitcoin](https://github.com/comit-network/RFCs/blob/master/RFC-004-Bitcoin.md) and [Ethereum](https://github.com/comit-network/RFCs/blob/master/RFC-006-Ethereum.md) we need to handle the Lightning Network differently. +Similiar to the ledger definitions for https://github.com/comit-network/RFCs/blob/master/RFC-004-Bitcoin.md[Bitcoin] and https://github.com/comit-network/RFCs/blob/master/RFC-006-Ethereum.md[Ethereum] we need to handle the Lightning Network differently. This is required because the comit-node and btsieve need to perform different actions accordingly. We are always talking about Ledgers and Assets, (e.g. _Bitcoin_ Asset on the _Bitcoin_ Ledger, _Ether_ Asset on the _Ethereum_ Ledger, _Erc20_ on the _Ethereum_ Ledger, ...), Hence, if we follow this approach, for supporting LN (through LND) we will need to introduce a new pair of Ledger and Asset: @@ -118,7 +118,7 @@ if we follow this approach, for supporting LN (through LND) we will need to intr * Asset: **Bitcoin**. Since LN is a layer-2 network on top of Bitcoin, the asset should also be Bitcoin. === Dealing with timeouts -When calling `addholdinvoice` an [`expiry`](https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L142) (in seconds) can be given. However, this expiry is only related to the invoice itself and has nothing to do with the expiry times on the HTLCs later on. +When calling `addholdinvoice` an https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L142[`expiry`] (in seconds) can be given. However, this expiry is only related to the invoice itself and has nothing to do with the expiry times on the HTLCs later on. However, timeouts on the HTLCs are relative and will get accumulated across the payment path, which makes it harder to predict. Hence, Alice will need to know the path in advance before sending a swap request to Bob as she won't (or should not) be able to change neither `alpha_expiry` nor `beta_expiry` after the swap request. From fcf0ef93df32ae2ed679585781d3c2fde3bfa966 Mon Sep 17 00:00:00 2001 From: Philipp Hoenisch Date: Mon, 29 Apr 2019 14:41:51 +1000 Subject: [PATCH 11/22] Add some comments for reproducability --- 0003-lightning-as-alpha-ledger.adoc | 67 +++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/0003-lightning-as-alpha-ledger.adoc b/0003-lightning-as-alpha-ledger.adoc index c9c02c2..3fba19e 100644 --- a/0003-lightning-as-alpha-ledger.adoc +++ b/0003-lightning-as-alpha-ledger.adoc @@ -205,3 +205,70 @@ We could use this information to fall back to an on-chain HTLC trade if no route == Appendix === Commands for call + +I can confirm, the following works: + +[source,bash] +---- +secret=0000000000000000000000000000000000000000000000000000000000000001 +sha256=ec4916dd28fc4c10d78e287ca5d9cc51ee1ae73cbfde08c6b37324cbfaac8bc5 +---- + +[source] +---- +$bob: lncli --network=simnet addholdinvoice ec4916dd28fc4c10d78e287ca5d9cc51ee1ae73cbfde08c6b37324cbfaac8bc5 --amt 10 +---- + + + +[source] +---- +$alice: lncli --network=simnet payinvoice lnsb100n.... +---- + +[source] +---- +$bob: `lncli --network=simnet lookupinvoice 4146873... +{ + "memo": "", + "receipt": null, + "r_preimage": null, + ... + "amt_paid_msat": "10000", + "state": "ACCEPTED" +} +---- + +[source] +---- +$bob: lncli --network=simnet settleinvoice 0000000000000000000000000000000000000000000000000000000000000001 +---- + +[source] +---- +$bob: `lncli --network=simnet lookupinvoice ec4916dd28fc4c10d78e287ca5d9cc51ee1ae73cbfde08c6b37324cbfaac8bc5 +{ + "memo": "", + "receipt": null, + "r_preimage": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAE=", + "r_hash": "7EkW3Sj8TBDXjih8pdnMUe4a5zy/3gjGs3Mky/qsi8U=", + "value": "10", + "settled": true, + "creation_date": "1556272625", + "settle_date": "1556272661", + "payment_request": "lnsb100n1pwv9403pp5a3y3dhfgl3xpp4uw9p72tkwv28hp4eeuhl0q334nwvjvh74v30zsdqqcqzpgjemg8uy8y7ej0q6lmxvkfhwfrjnesv6jryk46m5kcfcd2drykskq97c2ad9lvp9d6mmyt0r6rhp26e2cmrqd9qgc88rf5l58hz6ntxgqc3azkn", + "description_hash": null, + "expiry": "3600", + "fallback_addr": "", + "cltv_expiry": "40", + "route_hints": [ + ], + "private": false, + "add_index": "7", + "settle_index": "1", + "amt_paid": "10000", + "amt_paid_sat": "10", + "amt_paid_msat": "10000", + "state": "SETTLED" +} +---- From 9e126213a6b568630901521db02d08274a92ec4f Mon Sep 17 00:00:00 2001 From: Philipp Hoenisch Date: Mon, 29 Apr 2019 15:37:54 +1000 Subject: [PATCH 12/22] Update description about spike outcome --- 0003-lightning-as-alpha-ledger.adoc | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/0003-lightning-as-alpha-ledger.adoc b/0003-lightning-as-alpha-ledger.adoc index 3fba19e..91dd024 100644 --- a/0003-lightning-as-alpha-ledger.adoc +++ b/0003-lightning-as-alpha-ledger.adoc @@ -77,7 +77,7 @@ ____ [start=2] 2. Bob _accepts_ the request and performs the following step: - .. Create a hold incoice using `addholdinvoice` with the amount `X` and the hashed preimage `secret_hash` (https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L142[more details]). + .. Create a hold invoice using `addholdinvoice` with the amount `X` and the hashed preimage `secret_hash` (https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L142[more details]). .. Bob _subscribes_ to the invoice and waits for the payment either using ... `SubscribeSingleInvoice` - this is not available through the CLI but as RPC; or ... `LookupInvoice` - this is available trough the CLI but needs to be polled regularly. @@ -142,8 +142,11 @@ If a trade involves LN using LND we can approach these things differently: * Description ** `addholdinvoice` is available as a RPC command or through the LND CLI. Although dealing with this is rather cumbersome, to keep the autonomy with the user, and to not introduce LND dependency into the comit-node, we this should be possible through comit-i. * Conclusion: - ** comit-i needs LND support - + ** comit-i needs LND support. However, in order to do this, we will need to introduce a new action which is meant to be executed prior accepting a swap request: + *** Bob receives a swap request from Alice (an learns about the hashed secret) + *** *Action 1:* Bob creates a hold invoice through comit-i + *** *Action 2:* Bob accepts the swap requests by posting the newly generated invoice ID back to comit-rs + A quick research showed that LN payments can be done with the browser extension: https://lightningjoule.com/[Joule] and requests to a LND node can be done through the browser. --- @@ -157,7 +160,7 @@ If a trade involves LN using LND we can approach these things differently: * Description ** To keep the autonomy to the user when to initiate a trade, we should return the invoice information through our API to the user (e.g. expose it through comit-i ) and let him/her pay the invoice. * Conclusion - ** comit-i needs LND support + ** comit-i needs LND support. @@ -173,7 +176,7 @@ If a trade involves LN using LND we can approach these things differently: * Description ** As soon as the secret has been learned, the HTLC on the LN should be settled using the command `settleinvoice`, this can either be done by the user (and exposed through comit-i) or done automatically through the comit-node. Since we have the extra _redeem_ step for Bitcoin and Ethereum (as well for Erc20) which needs to be performed from the user, we should leave the settlement of the invoice to the user (e.g. expose this information through comit-i). * Conclusion - ** comit-i needs LND support + ** comit-i needs LND support. @@ -189,7 +192,7 @@ If a trade involves LN using LND we can approach these things differently: * Description ** Similar to other Ledgers we need to monitor LN for the payment (and later on settlement) of an invoice. To keep our current abstraction layer, this should be done through btsieve * Conclusion - ** btsieve needs LND support + ** btsieve needs LND support. === COMIT link relation @@ -208,7 +211,7 @@ We could use this information to fall back to an on-chain HTLC trade if no route I can confirm, the following works: -[source,bash] +[source] ---- secret=0000000000000000000000000000000000000000000000000000000000000001 sha256=ec4916dd28fc4c10d78e287ca5d9cc51ee1ae73cbfde08c6b37324cbfaac8bc5 From 343f2baebebf7daf2d92d989892aa9f1b5240b35 Mon Sep 17 00:00:00 2001 From: Philipp Hoenisch Date: Tue, 30 Apr 2019 09:50:49 +1000 Subject: [PATCH 13/22] Minor changes --- 0003-lightning-as-alpha-ledger.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/0003-lightning-as-alpha-ledger.adoc b/0003-lightning-as-alpha-ledger.adoc index 91dd024..932fa83 100644 --- a/0003-lightning-as-alpha-ledger.adoc +++ b/0003-lightning-as-alpha-ledger.adoc @@ -3,7 +3,7 @@ NOTE: Authors: Philipp Hoenisch + Date: 2019-04-24 + Tracking issue: TBA - +:toc: == Context The **Hold invoice feature** was introduced in the following PR: https://github.com/lightningnetwork/lnd/pull/2022[lightningnetwork/lnd/pull/2022]. @@ -45,7 +45,7 @@ ____ === Step-by-step description -. Alice generates a secret preimage `p` and sends a swap request to Bob, this includes (assets with amounts are emitted): +1. Alice generates a secret preimage `p` and sends a swap request to Bob, this includes (assets with amounts are emitted): [cols=3*,options=header] |=== From bbba06e2517254f59cc3883649e3441dfe870beb Mon Sep 17 00:00:00 2001 From: Philipp Hoenisch Date: Tue, 30 Apr 2019 10:16:55 +1000 Subject: [PATCH 14/22] Unchange the change or it's being changed unchanged --- 0003-lightning-as-alpha-ledger.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/0003-lightning-as-alpha-ledger.adoc b/0003-lightning-as-alpha-ledger.adoc index 932fa83..b04f5d4 100644 --- a/0003-lightning-as-alpha-ledger.adoc +++ b/0003-lightning-as-alpha-ledger.adoc @@ -3,7 +3,9 @@ NOTE: Authors: Philipp Hoenisch + Date: 2019-04-24 + Tracking issue: TBA + :toc: + == Context The **Hold invoice feature** was introduced in the following PR: https://github.com/lightningnetwork/lnd/pull/2022[lightningnetwork/lnd/pull/2022]. From 4640334ab193ced0de726669b5c608fe3fc042fc Mon Sep 17 00:00:00 2001 From: Philipp Hoenisch Date: Tue, 30 Apr 2019 11:43:54 +1000 Subject: [PATCH 15/22] Remove link part --- 0003-lightning-as-alpha-ledger.adoc | 5 ----- 1 file changed, 5 deletions(-) diff --git a/0003-lightning-as-alpha-ledger.adoc b/0003-lightning-as-alpha-ledger.adoc index b04f5d4..90048b5 100644 --- a/0003-lightning-as-alpha-ledger.adoc +++ b/0003-lightning-as-alpha-ledger.adoc @@ -197,11 +197,6 @@ If a trade involves LN using LND we can approach these things differently: ** btsieve needs LND support. -=== COMIT link relation -Assumption: Bob is the creator of the link and is willing to receive Bitcoin for Ether for 1:10. - -Bob cannot yet create a hold invoice, i.e. `addholdinvoice` as he does not know the secret yet, hence, all he can add in the link is the information about Ledgers, Assets and exchange rates. - === Fall-back mechanism of LN LN allows to specify a fallback address (_fallback_addr_) in when creating calling `addholdinvoice`. We could use this information to fall back to an on-chain HTLC trade if no route can be found between Alice and Bob. From 0e2dec0a1895ebef9908060082fbd2e0984817f5 Mon Sep 17 00:00:00 2001 From: Philipp Hoenisch Date: Thu, 2 May 2019 11:04:53 +1000 Subject: [PATCH 16/22] Updated hodl invoice --- 0003-lightning-as-alpha-ledger.adoc | 138 ++++++++++++++++++++++------ 1 file changed, 109 insertions(+), 29 deletions(-) diff --git a/0003-lightning-as-alpha-ledger.adoc b/0003-lightning-as-alpha-ledger.adoc index 90048b5..0b0ee36 100644 --- a/0003-lightning-as-alpha-ledger.adoc +++ b/0003-lightning-as-alpha-ledger.adoc @@ -1,4 +1,4 @@ -= LND as Alpha Ledger as described in RFC003 += LND as Alpha Ledger as described in RFC003 NOTE: Authors: Philipp Hoenisch + Date: 2019-04-24 + @@ -10,13 +10,17 @@ Tracking issue: TBA The **Hold invoice feature** was introduced in the following PR: https://github.com/lightningnetwork/lnd/pull/2022[lightningnetwork/lnd/pull/2022]. ____ -A hold invoice is a new type of invoice that triggers a different flow at the receiver end. +A hold invoice is a new type of invoice that triggers a different flow at the receiver's end. Instead of immediately locking in and settling the htlc when the payment arrives, the htlc for a hold invoice is only locked in and not yet settled. At that point, it is not possible anymore for the sender to revoke the payment, but the receiver still can choose whether to settle or cancel the htlc and invoice. ____ This allows us to trade Bitcoin on the Lightning Network (LN) for an asset _X_ on a different ledger where LN is the _alpha ledger_ as per the definition in https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md[RFC003]. -For the other way around, Bitcoin on the Lightning Network is the _beta asset/ledger_, we can make use of `createinvoice` as Alice would instantly release the secret by settling Bob's LN payment. +For the other way around, Bitcoin on the Lightning Network is the _beta asset/ledger_, we can make use of `createinvoice` as Alice would instantly release the secret by settling Bob's LN payment, or we can follow the same approach as described below. + +NOTE: Within this spike we only focus on LN as the Alpha Ledger using https://github.com/lightningnetwork/lnd/[LND]. + +== Research === Standard _hold invoice_ process @@ -33,11 +37,11 @@ ____ The payment is complete. -== Research +== Lightning Network as Alpha Ledger within the bounds of RFC003 ____ Assumption: Bob wants to receive _X_ Bitcoin (**A** Asset) on the LN (**alpha** Ledger) for _Y_ Ether (**B** Asset) on Ethereum (**beta** Ledger) -Alice magically finds out about this _wish_ or using a [COMIT link](fill in some link). +Alice magically finds out about this _wish_ or using a COMIT link. * Alpha Ledger: Lightning Network * Alpha Asset: Bitcoin @@ -45,9 +49,7 @@ Alice magically finds out about this _wish_ or using a [COMIT link](fill in some * Beta Asset: Ether ____ -=== Step-by-step description - -1. Alice generates a secret preimage `p` and sends a swap request to Bob, this includes (assets with amounts are emitted): +According to https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md[RFC003], Alice needs to send the following information to Bob for initiating a swap. [cols=3*,options=header] |=== @@ -57,7 +59,7 @@ ____ | `alpha_expiry` | `u32` -| The UNIX timestamp of the time-lock for LN (alpha Ledger) +| The UNIX timestamp of the time-lock on the alpha HTLC | `beta_expiry` | `u32` @@ -65,7 +67,91 @@ ____ | `alpha_refund_identity` | `α::Identity` -| This can be empty as the refund identity will be handled by LN. +| The identity on α that A can be transferred to after `alpha_expiry` + +| `beta_redeem_identity` +| `β::Identity` +| The identity on beta that **B** will be transferred to when the beta-HTLC is activated with the correct secret + +| `secret_hash` +| `hex-encoded-bytes` +| The output of calling `hash_function` on the secret +|=== + +And Bob would respond with the following: + +[cols=3*,options=header] +|=== +| Name +| JSON Encoding +| Description + +| `alpha_redeem_identity` +| `α::Identity` +| The identity on alpha that **A**, this is the LN `invoice` + +| `beta_refund_identity` +| `β::Identity` +| The identity on beta that **B** will be transferred to when the beta-HTLC is activated after `beta_expiry` +|=== + + +However, using LND, various complication need to be tackled: + +* `alpha_expiry` -> Similar to other RFC003 implementations, for LND `alpha_expiry` will need to be set when sending the payment, i.e. by adding `--final_cltv_delta=T`. +The caveat here is that Alice can not set the actual `cltv_expiry` on the last hop but only the delta. +The LN node calculates what the `cltv_expiry` will be based on `final_cltv_delta` and what it perceives to be the current block height. +* `alpha_refund_identity` -> When using LN (or LND), one is not in direct control of the refund path. If a channel update expires, the refund path is handled automatically by the LN implementation. +* `alpha_redeem_identity` -> Similar to `alpha_refund_identity`, the `alpha_redeem_identity` on the actual HTLC cannot be directly configured as this is done by the LN implementation. However, this field is still required as it should specify the final reciepient, i.e. the final node. + +Because of these limitations, we should introduce a new protocol for using LN as Alpha Ledger. + + +== Proposal: A new protocol for LN as Alpha Ledger + +=== Step-by-step description + +1. Alice generates a secret preimage `p` and sends a swap request to Bob, this includes (assets with amounts are emitted): + +[cols=3*,options=header] +|=== +| Name +| Proposed Value.footnote:[This will only be finalized in the RFCs later on.] +| Description + +| `alpha_ledger` +| lightning-network-mainnet +| The ledger on which the Sender sells and the Receiver buys. + +| `beta_ledger` +| e.g. Bitcoin +| The ledger on which the Sender buys and the Receiver sells. + +| `alpha_asset` +| Bitcoin +| The asset that the Sender sells and the Receiver buys. + +| `beta_asset` +| Bitcoin +| The asset that the Sender buys and the Receiver sells. + +| `protocol` +| RFC00X +| The new protocol specifying LN Swaps + +[cols=3*,options=header] +|=== +| Name +| JSON Encoding +| Description + +| `final_cltv_delta` +| `u32` +| The `final_cltv_delta` Alice will use when paying the invoice. + +| `beta_expiry` +| `u32` +| The UNIX timestamp of the time-lock on the beta HTLC. | `beta_redeem_identity` | `β::Identity` @@ -91,9 +177,9 @@ ____ | JSON Encoding | Description -| `alpha_redeem_identity` +| `receiving_node_identity` | `α::Identity` -| The identity on alpha that **A**, this is the LN `invoice` +| The receiving node id which should be in the invoice paid by Alice. | `beta_refund_identity` | `β::Identity` @@ -101,7 +187,7 @@ ____ |=== [start=4] -4. Alice now starts the https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md#1-alice-deploys-%CE%B1-htlc[execution phase] by paying the invoice using the LND command `sendpayment`. +4. Alice now starts the https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md#1-alice-deploys-%CE%B1-htlc[execution phase] by first creating an invoice and then paying the invoice using the LND command `sendpayment`. 5. Bob gets notified about funding of alpha (i.e. the invoice has been paid but cannot be settled yet), and continues with https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md#2-bob-deploys-%CE%B2-htlc[deploying beta-HTLC], i.e. he deploys a HTLC on Ethereum. 6. As soon as beta has enough confirmations for Alice, she redeems the beta-HTLC using her secret. 7. Bob gets notified about this, learns the secret and can now settle the LND invoice by invoking the LND command `settleInvoice` (https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L53[more details]). @@ -111,7 +197,7 @@ The trade is complete. == Spike Outcome === Lightning Network: a new ledger -Similiar to the ledger definitions for https://github.com/comit-network/RFCs/blob/master/RFC-004-Bitcoin.md[Bitcoin] and https://github.com/comit-network/RFCs/blob/master/RFC-006-Ethereum.md[Ethereum] we need to handle the Lightning Network differently. +Similar to the ledger definitions for https://github.com/comit-network/RFCs/blob/master/RFC-004-Bitcoin.md[Bitcoin] and https://github.com/comit-network/RFCs/blob/master/RFC-006-Ethereum.md[Ethereum] we need to handle the Lightning Network differently. This is required because the comit-node and btsieve need to perform different actions accordingly. We are always talking about Ledgers and Assets, (e.g. _Bitcoin_ Asset on the _Bitcoin_ Ledger, _Ether_ Asset on the _Ethereum_ Ledger, _Erc20_ on the _Ethereum_ Ledger, ...), Hence, if we follow this approach, for supporting LN (through LND) we will need to introduce a new pair of Ledger and Asset: @@ -120,14 +206,9 @@ if we follow this approach, for supporting LN (through LND) we will need to intr * Asset: **Bitcoin**. Since LN is a layer-2 network on top of Bitcoin, the asset should also be Bitcoin. === Dealing with timeouts -When calling `addholdinvoice` an https://github.com/lightningnetwork/lnd/blob/aa1cd04dbf07a9195d5ada752f383988d8d01fa7/cmd/lncli/invoicesrpc_active.go#L142[`expiry`] (in seconds) can be given. However, this expiry is only related to the invoice itself and has nothing to do with the expiry times on the HTLCs later on. -However, timeouts on the HTLCs are relative and will get accumulated across the payment path, which makes it harder to predict. -Hence, Alice will need to know the path in advance before sending a swap request to Bob as she won't (or should not) be able to change neither `alpha_expiry` nor `beta_expiry` after the swap request. +As mentioned above, Alice specifies `final_cltv_delta` when paying the invoice. Bob's node must be configured in a way that it will not automatically reject this value. +Additionally, timeouts on the HTLCs in LN are absolute values expressed in https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#cltv_expiry_delta-selection[block height]. -Timeouts on the HTLCs are configured globally for the payee node and can optionally be defined when paying by the payer node (`--final_cltv_delta=T`). - - -IMPORTANT: TODO: we should investigate this topic more in detail. === Responsibilities @@ -140,7 +221,7 @@ If a trade involves LN using LND we can approach these things differently: * Responsibility ** LND * Invoker - ** User, comit-i, comit-node + ** User through comit-i (or another user-facing tool) * Description ** `addholdinvoice` is available as a RPC command or through the LND CLI. Although dealing with this is rather cumbersome, to keep the autonomy with the user, and to not introduce LND dependency into the comit-node, we this should be possible through comit-i. * Conclusion: @@ -158,14 +239,13 @@ If a trade involves LN using LND we can approach these things differently: * Responsibility: ** LND or LN Wallet * Invoker - ** User, comit-i + ** User through comit-i * Description ** To keep the autonomy to the user when to initiate a trade, we should return the invoice information through our API to the user (e.g. expose it through comit-i ) and let him/her pay the invoice. * Conclusion ** comit-i needs LND support. - --- @@ -174,14 +254,13 @@ If a trade involves LN using LND we can approach these things differently: * Responsibility ** LND or LN Wallet * Invoker - ** User, comit-i, comit-node + ** User through comit-i (or another tool) * Description - ** As soon as the secret has been learned, the HTLC on the LN should be settled using the command `settleinvoice`, this can either be done by the user (and exposed through comit-i) or done automatically through the comit-node. Since we have the extra _redeem_ step for Bitcoin and Ethereum (as well for Erc20) which needs to be performed from the user, we should leave the settlement of the invoice to the user (e.g. expose this information through comit-i). + ** As soon as the secret has been learned, the HTLC on the LN should be settled using the command `settleinvoice`, this can either be done by the user (and exposed through comit-i) or done automatically through the comit-node. Since we have the extra _redeem_ step for Bitcoin and Ethereum (as well for Erc20) which needs to be performed by the user, we should leave the settlement of the invoice to the user (e.g. expose this information through comit-i). * Conclusion ** comit-i needs LND support. - --- @@ -190,7 +269,7 @@ If a trade involves LN using LND we can approach these things differently: * Responsibility ** LND * Invoker - ** Btsieve + ** comit-rs * Description ** Similar to other Ledgers we need to monitor LN for the payment (and later on settlement) of an invoice. To keep our current abstraction layer, this should be done through btsieve * Conclusion @@ -200,13 +279,14 @@ If a trade involves LN using LND we can approach these things differently: === Fall-back mechanism of LN LN allows to specify a fallback address (_fallback_addr_) in when creating calling `addholdinvoice`. We could use this information to fall back to an on-chain HTLC trade if no route can be found between Alice and Bob. +Note: this should be handled with care, as someone could trick a LN node into using the fallback address automatically and issuing an on-chain transaction which does not involve a htlc. == Appendix === Commands for call -I can confirm, the following works: +The following works: [source] ---- From a9c52ba2bc4d0cf9b60c82d5c81cbd00baf4ed1f Mon Sep 17 00:00:00 2001 From: Philipp Hoenisch Date: Fri, 3 May 2019 10:34:46 +1000 Subject: [PATCH 17/22] Minor correction --- 0003-lightning-as-alpha-ledger.adoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/0003-lightning-as-alpha-ledger.adoc b/0003-lightning-as-alpha-ledger.adoc index 0b0ee36..3739e2e 100644 --- a/0003-lightning-as-alpha-ledger.adoc +++ b/0003-lightning-as-alpha-ledger.adoc @@ -37,7 +37,9 @@ ____ The payment is complete. -== Lightning Network as Alpha Ledger within the bounds of RFC003 +== Lightning Network as Alpha Ledger within the bounds of RFC003? + +Below, we try if Lightning Network as Alpha Ledger _fits_ into the definition of RFC003: ____ Assumption: Bob wants to receive _X_ Bitcoin (**A** Asset) on the LN (**alpha** Ledger) for _Y_ Ether (**B** Asset) on Ethereum (**beta** Ledger) From 82a47842906de6074cee788dc424e4dd21657fa4 Mon Sep 17 00:00:00 2001 From: Philipp Hoenisch Date: Fri, 3 May 2019 11:24:52 +1000 Subject: [PATCH 18/22] Spike formatting updated --- 0003-lightning-as-alpha-ledger.adoc | 9 +++++---- template.adoc | 7 ++++--- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/0003-lightning-as-alpha-ledger.adoc b/0003-lightning-as-alpha-ledger.adoc index 3739e2e..52596e6 100644 --- a/0003-lightning-as-alpha-ledger.adoc +++ b/0003-lightning-as-alpha-ledger.adoc @@ -1,8 +1,9 @@ -= LND as Alpha Ledger as described in RFC003 += LND as Alpha Ledger as described in RFC003 +Philipp Hoenisch -NOTE: Authors: Philipp Hoenisch + -Date: 2019-04-24 + -Tracking issue: TBA +NOTE: * Author: {authors} +* Date: {docdate} +* Tracking issue: TBA :toc: diff --git a/template.adoc b/template.adoc index 56f8487..3787ea1 100644 --- a/template.adoc +++ b/template.adoc @@ -1,8 +1,9 @@ = [short title describing spike] +Satoshi Nakamoto ; -NOTE: Authors: [list everyone involved in the research] + -Date: [YYYY-MM-DD when the spike outcome was last updated] + -Tracking issue: [link to corresponding spike] +NOTE: * Author: {authors} +* Date: {docdate} +* Tracking issue: TBA :toc: From 0a9ea5bd313923ffe592d3ac49176b3058cc8232 Mon Sep 17 00:00:00 2001 From: Philipp Hoenisch Date: Fri, 3 May 2019 11:31:04 +1000 Subject: [PATCH 19/22] Rev date tryout --- 0003-lightning-as-alpha-ledger.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/0003-lightning-as-alpha-ledger.adoc b/0003-lightning-as-alpha-ledger.adoc index 52596e6..29fbeb6 100644 --- a/0003-lightning-as-alpha-ledger.adoc +++ b/0003-lightning-as-alpha-ledger.adoc @@ -1,8 +1,8 @@ = LND as Alpha Ledger as described in RFC003 -Philipp Hoenisch +Philipp Hoenisch , 2019-04-24 NOTE: * Author: {authors} -* Date: {docdate} +* Date: {revdate} * Tracking issue: TBA :toc: From dd0dd88109a0e5b6b62117351f9966395a68abec Mon Sep 17 00:00:00 2001 From: Philipp Hoenisch Date: Fri, 3 May 2019 11:33:27 +1000 Subject: [PATCH 20/22] v2 --- 0003-lightning-as-alpha-ledger.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/0003-lightning-as-alpha-ledger.adoc b/0003-lightning-as-alpha-ledger.adoc index 29fbeb6..17263d9 100644 --- a/0003-lightning-as-alpha-ledger.adoc +++ b/0003-lightning-as-alpha-ledger.adoc @@ -1,5 +1,6 @@ = LND as Alpha Ledger as described in RFC003 -Philipp Hoenisch , 2019-04-24 +Philipp Hoenisch +:revdate: 2019-04-24 NOTE: * Author: {authors} * Date: {revdate} From 5420a45acff4f956f5a6ffa44b6d82167a505755 Mon Sep 17 00:00:00 2001 From: Philipp Hoenisch Date: Fri, 3 May 2019 11:35:14 +1000 Subject: [PATCH 21/22] v3 --- 0003-lightning-as-alpha-ledger.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/0003-lightning-as-alpha-ledger.adoc b/0003-lightning-as-alpha-ledger.adoc index 17263d9..5d5d401 100644 --- a/0003-lightning-as-alpha-ledger.adoc +++ b/0003-lightning-as-alpha-ledger.adoc @@ -2,9 +2,9 @@ Philipp Hoenisch :revdate: 2019-04-24 -NOTE: * Author: {authors} -* Date: {revdate} -* Tracking issue: TBA +NOTE: Author: {authors} + +Date: {revdate} + +Tracking issue: TBA :toc: From 649accb21f158577608384bdd35e832b367ff044 Mon Sep 17 00:00:00 2001 From: Philipp Hoenisch Date: Fri, 3 May 2019 11:36:21 +1000 Subject: [PATCH 22/22] Fix template --- template.adoc | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/template.adoc b/template.adoc index 3787ea1..d933a5b 100644 --- a/template.adoc +++ b/template.adoc @@ -1,9 +1,10 @@ = [short title describing spike] Satoshi Nakamoto ; +:revdate: 2009-01-03 -NOTE: * Author: {authors} -* Date: {docdate} -* Tracking issue: TBA +NOTE: Author: {authors} + +Date: {revdate} + +Tracking issue: TBA :toc: