Initial draft of RFC-003 #13

LLFourn · 2019-01-15T04:02:52Z

Please review.

Fixes #7

LLFourn · 2019-01-15T04:20:24Z

RFC-003-SWAP-basic.md

+In this RFC, the expiry activation returns the asset to the original owner while a secret activation transfers it to the other party.
+Therefore this document will refer to these paths as *refund* and *redeem* respectively.
+
+The HTLCs defined in this specification use *absolute time locks* where the expiry is set at a specific time in the future.


ℹ️ the motivation for this is that it's an attack vector if we use relative timelocks on the beta ledger. If Alice has the capability to delay Bob's HTLC from getting confirmed she essentially changes beta_expiry to a later point such that she may be able to redeem and then refund.

What do you guys think? Do you think this is worth explaining in this RFC?

Definitely!

I think stuff like that is actually pretty important. Documenting the downsides and weaknesses of protocols is a sign of maturity IMO :)

LLFourn · 2019-01-15T04:21:21Z

RFC-003-SWAP-basic.md

+The identity on β that **B** will be transferred to when the β-HTLC is activated with the correct secret.
+
+#### `secret_hash`
+Type: `HexString` <!-- Where to define this. I guess it should be RawBytes and in the JSON encoding it's Hex -->


Where to hang these definitions? In the registry also? Or can we add some primitive types to RFC001 and how to encode them in JSON.

I don't think there is a need to "normalize" or "DRY" too much here. Just say it is a hex-string.

LLFourn · 2019-01-15T04:21:58Z

RFC-003-SWAP-basic.md

+
+This RFC describes a basic atomic swap protocol and the related parameters required to use it as a COMIT [RFC002](./RFC-002-SWAP.md#protocol) SWAP protocol.
+It uses Hash Time Locked Contracts to swap ownership of two assets on different ledgers between two parties.
+It is a simplified version of the protocol originally described by TierNolan[^fn1].


This citation thing didn't work at all XD

thomaseizinger

Very good work! I like the way you wrote this RFC.

thomaseizinger · 2019-01-15T04:32:37Z

RFC-003-SWAP-basic.md

+
+### Identity
+
+This RFC introduces the notion of a "identity".


Typo?

Suggested change

This RFC introduces the notion of a "identity".

This RFC introduces the notion of an "identity".

thomaseizinger · 2019-01-15T04:45:11Z

RFC-003-SWAP-basic.md

+The protocol begins with a SWAP request with the `protocol` header's value set to `COMIT-RFC-003` and the following header parameters:
+
+#### `hash_function`
+Type: [Hash Function](./COMIT-registry.md#Hash Functions)


❌ This link doesn't render correctly.

thomaseizinger · 2019-01-15T04:46:47Z

RFC-003-SWAP-basic.md

+### SWAP Request Body
+When `COMIT-RFC-003` is used as the value for `protocol` for a `SWAP REQUEST` message the body must have the following fields:
+
+#### `alpha_expiry`


🔧 I think these would be more readable in the form of a table.

thomaseizinger · 2019-01-15T04:47:39Z

RFC-003-SWAP-basic.md

+This indicates to the sender that the difference between `alpha_expiry` and `beta_expiry` is too small and the receiver may accept the swap if they are given more time.
+
+parameters:
+| Name          | JSON Type     |  Description                                                                       |


❌ The table doesn't render correctly.

RFC-003-SWAP-basic.md

thomaseizinger · 2019-01-15T04:48:52Z

RFC-003-SWAP-basic.md

+The protocol is described below as if both parties had immediate access to the most recent state of the ledger and are able to effect persistent actions to it immediately.
+
+For Ledgers with a probabilistic notion of the latest state such as the Bitcoin and Etheruem networks, parties must wait until they have confidence that their counterparty's transactions will not be reverted before they take any action.
+Parties must also take this into account when choosing or accepting the `alpha_expiry` and `beta_expiry` parameters (see [Security Considerations](#Security Considerations)).


❌ Link doesn't render correctly.

thomaseizinger · 2019-01-15T04:49:15Z

RFC-003-SWAP-basic.md

+
+The HTLC definitions for particular ledgers will be included in subsequent RFCs
+
+### Alice deploys α-HTLC


🔧 Maybe have a 1. in front of this?

RFC-003-SWAP-basic.md

thomaseizinger · 2019-01-15T04:53:48Z

RFC-003-SWAP-basic.md

+An identity belongs to a user and represents the minimal information required to transfer an asset to that user on a particular ledger.
+On blockchain based ledgers a user's identity is usually some function of a public key where the private key is only known to the user.
+
+This RFC extends the [COMIT-registry](./COMIT-registry.md) to include a section specifying the identity for each supported ledger and any subsequent RFCs adding support for a ledger must include an identity specification.


❌ I think all these extensions should go in a combined section (# Registry extensions) at the end. This would help to not forget anything.

RFC-003-SWAP-basic.md

Co-Authored-By: LLFourn <LLFourn@users.noreply.github.com>

thomaseizinger · 2019-01-16T05:04:00Z

Pretty good work! I like it :)

COMIT-registry.md

D4nte · 2019-01-16T06:25:58Z

RFC-003-SWAP-basic.md

+| `beta_expiry`           | `u32`               | The UNIX timestamp of the time-lock of the beta HTLC                                                      |
+| `alpha_refund_identity` | `α::Identity`       | The identity on α that **A** can be transferred to after `alpha_expiry`                                   |
+| `beta_redeem_identity`  | `β::Identity`       | The identity on β that **B** will be transferred to when the β-HTLC is activated with the correct secret. |
+| `secret_hash`           | `hex-encoded-bytes` | The output by calling `hash_function` with the secret as input                                            |


I'd clarify whether it's prefixed with 0x

Maybe we could have an example column?

I'll make an examples section at the end.

We should definitely clarify what exactly hex-encoded-bytes means somewhere but doing it everywhere we use it will be a pain. I still think RFC1 which defines the JSON encoding is the right place to define these primitive types we can reuse.

@LLFourn can you correct in RFC-001 now or open an issue then?

RFC-003-SWAP-basic.md

Co-Authored-By: LLFourn <LLFourn@users.noreply.github.com>

And s/must/MUST/ everywhere

RFC-003-SWAP-basic.md

D4nte

vendu!

luckysori

Mostly nitpicks, I like it a lot 🥇

RFC-003-SWAP-basic.md

luckysori · 2019-01-17T23:22:47Z

RFC-003-SWAP-basic.md

+The Hash Time Locked Contract (HTLC) is the primary construct used in this protocol. An HTLC locks an asset until one of two possible paths are activated:
+
+- **Activation with secret**: The contract is activated with a *secret*. The hash of the secret MUST match the hash in the contract.
+- **Activation after expiry**: The contract is activated after a time fixed in the contract.


🙃 May just be me, but this could be misinterpreted as the contract activating the refund path on its own after the time lock has expired.

RFC-003-SWAP-basic.md

luckysori · 2019-01-18T00:07:21Z

RFC-003-SWAP-basic.md

+This protocol offers an application the following functionality:
+
+- **Up for Sale**: Alice puts an asset **A** up for sale until `alpha_expiry`
+- **Give Option**: Bob can give Alice an *option* to exchange for **A** for his asset **B** until `beta_expiry`


Suggested change

- **Give Option**: Bob can give Alice an *option* to exchange for **A** for his asset **B** until `beta_expiry`

- **Give Option**: Bob can give Alice an *option* to exchange **A** for his asset **B** until `beta_expiry`.

RFC-003-SWAP-basic.md

Co-Authored-By: LLFourn <LLFourn@users.noreply.github.com>

- Clear up that *someone* must activate the HTLC - Clear up section about absolute time locks

Co-Authored-By: LLFourn <LLFourn@users.noreply.github.com>

bonomat · 2019-01-18T02:55:25Z

RFC-003-SWAP-basic.md

+
+This RFC describes a basic atomic swap protocol and the related parameters required to use it as a COMIT [RFC002](./RFC-002-SWAP.md#protocol) SWAP protocol.
+It uses Hash Time Locked Contracts to swap ownership of two assets on different ledgers between two parties.
+It is a simplified version of the protocol originally described by TierNolan [\[1\]][1].


Suggested change

It is a simplified version of the protocol originally described by TierNolan [\[1\]][1].

It is a simplified version of the protocol originally described by TierNolan [\[1\]](1).

Initial draft of RFC-003

0b89c60

LLFourn commented Jan 15, 2019

View reviewed changes

[RFC-003] Fix footnotes

7988815

thomaseizinger suggested changes Jan 15, 2019

View reviewed changes

thomaseizinger and others added 17 commits January 15, 2019 16:16

Fix typo

384480e

Co-Authored-By: LLFourn <LLFourn@users.noreply.github.com>

s/a/an/ "identity"

1e95e50

Expand on HTLC absolute time locks and secret length checking

2c3b7dc

Fix Hash Function link

7c6bbf8

less DRY (for now)

49e5b91

Add ## Status

2699362

Fix RFC003 link in registry

5d34b41

Add JSON encoding section to the identity table

1fef954

Add timeouts-too-tight reason to the reason header in registry

303734b

Add ## Registry Extensions section

f5b48e4

Put body values into tables

7a13f65

Fix Security Considerations link

66c4318

Add numbering to Execution Phase headings

d6fa8a6

Expand on "he cannot cancel this option sentence".

fb542fc

Remove redundant "respectively"

388738f

Simplify wording around reverting transactions

184461d

Clarify how to verify HTLCs

2aa8624

thomaseizinger approved these changes Jan 16, 2019

View reviewed changes

D4nte reviewed Jan 16, 2019

View reviewed changes

D4nte and others added 4 commits January 17, 2019 13:44

Apply Franck's suggestions

9f1d8e9

Co-Authored-By: LLFourn <LLFourn@users.noreply.github.com>

Lowercase comit-rfc-003

8217bd4

use SWAP REQUEST consistently

1541261

Improve identity section

5c24ca2

Make definition of redeem_identity use clearer language

a5a9128

LLFourn force-pushed the RFC-003 branch from 1adcd30 to a5a9128 Compare January 17, 2019 03:44

D4nte and others added 3 commits January 17, 2019 14:45

Apply more of Franck's suggestions

24a8e34

Co-Authored-By: LLFourn <LLFourn@users.noreply.github.com>

Add an example

f43e06c

Improved wording of protocol execution

a62158c

And s/must/MUST/ everywhere

bonomat reviewed Jan 17, 2019

View reviewed changes

RFC-003-SWAP-basic.md Outdated Show resolved Hide resolved

D4nte reviewed Jan 17, 2019

View reviewed changes

RFC-003-SWAP-basic.md Show resolved Hide resolved

D4nte approved these changes Jan 17, 2019

View reviewed changes

Remove extra "for" in sentence

4cc0cbc

luckysori reviewed Jan 18, 2019

View reviewed changes

Lucas Soriano and others added 5 commits January 18, 2019 11:29

Apply Lucas' suggestions from code review

984d6fc

Co-Authored-By: LLFourn <LLFourn@users.noreply.github.com>

Improve HTLC section

c4d07c5

- Clear up that *someone* must activate the HTLC - Clear up section about absolute time locks

s/of/on

5a545e9

Remove redundant sentence

67db5a5

Try Phillip's link suggestion

e528e6f

Co-Authored-By: LLFourn <LLFourn@users.noreply.github.com>

bonomat reviewed Jan 18, 2019

View reviewed changes

Add references section

bb67f46

LLFourn force-pushed the RFC-003 branch from 766fab5 to bb67f46 Compare January 18, 2019 03:34

LLFourn added 4 commits January 18, 2019 14:38

Make first reference work

23a8666

Capitalise start of a sentence

2ae7077

Add Concepts heading around Identity and HTLC

b4c974b

Add TOC

5254cbd

LLFourn merged commit 9589c48 into master Jan 18, 2019

LLFourn deleted the RFC-003 branch January 18, 2019 03:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Initial draft of RFC-003 #13

Initial draft of RFC-003 #13

LLFourn commented Jan 15, 2019 •

edited by D4nte

LLFourn Jan 15, 2019

thomaseizinger Jan 15, 2019

LLFourn Jan 15, 2019

thomaseizinger Jan 15, 2019

LLFourn Jan 15, 2019

thomaseizinger left a comment

thomaseizinger Jan 15, 2019

thomaseizinger Jan 15, 2019

thomaseizinger Jan 15, 2019

thomaseizinger Jan 15, 2019

thomaseizinger Jan 15, 2019

thomaseizinger Jan 15, 2019

thomaseizinger Jan 15, 2019

thomaseizinger commented Jan 16, 2019

D4nte Jan 16, 2019

thomaseizinger Jan 17, 2019

LLFourn Jan 17, 2019

D4nte Jan 17, 2019

D4nte left a comment

luckysori left a comment

luckysori Jan 17, 2019

luckysori Jan 18, 2019

bonomat Jan 18, 2019

	This RFC introduces the notion of a "identity".
	This RFC introduces the notion of an "identity".


		The HTLC definitions for particular ledgers will be included in subsequent RFCs

		### Alice deploys α-HTLC

	- Give Option: Bob can give Alice an option to exchange for A for his asset B until `beta_expiry`
	- Give Option: Bob can give Alice an option to exchange A for his asset B until `beta_expiry`.

	It is a simplified version of the protocol originally described by TierNolan [\[1\]][1].
	It is a simplified version of the protocol originally described by TierNolan [\[1\]](1).

Initial draft of RFC-003 #13

Initial draft of RFC-003 #13

Conversation

LLFourn commented Jan 15, 2019 • edited by D4nte

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thomaseizinger left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thomaseizinger commented Jan 16, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

D4nte left a comment

Choose a reason for hiding this comment

luckysori left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

LLFourn commented Jan 15, 2019 •

edited by D4nte