Fixup: HTLC

bsip-0000.md

@@ -1,10 +1,10 @@
 BSIP: xxxx\
-Title: Hashed Time-Lock Contract\
+Title: Hashed Time-Locked Contract\
 Authors: John M. Jones, Ryan R. Fox, taconator\
 Status: Draft\
 Type: Informational\
 Created: 2018-08-22\
-Discussion: TBD\
+Discussion: TBD
 
 # **Abstract**
 
@@ -12,11 +12,11 @@ This BSIP describes an implementation of a Hashed Time-Locked Contract (HTLC) op
 
 # **Motivation**
 
-The ability to securely hold tokenized assets within a Hashed Time-Locked Contract (HTLC) on the BitShares blockchain is a desirable feature that could be used by many persons, services, and businesses to mitigate risks between participants. HTLC implement conditional transfers, whereby a designated party (the "recipient") will reveal the preimage of a hash in order to execute the asset transfers from a second party (the "depositor"), else after time lock expiry "depositor" may retrieve their assets. No third-party escrow agent is required, rather the HTLC operation enforces execution through the BitShares consensus protocol.
+The ability to securely hold tokenized assets within a hashed time-locked contract on the BitShares blockchain is a desirable feature that could be used by many persons, services, and businesses to mitigate risks between participants during asset transfer. HTLC implement conditional transfers, whereby a designated party (the "recipient") will reveal the preimage of a hash in order to execute the asset transfers from a second party (the "depositor"), else after time lock expiry "depositor" may retrieve their assets. No third-party escrow agent is required, rather the HTLC operation enforces conditions, evaluations and transfers through the BitShares consensus protocol.
 
 # **Rational**
 
-## **Elements of an HTLC**
+## **Elements of a Hashed Time-Locked Contract (HTLC)**
 
 An HTLC is defined to have the following components:
 
@@ -40,7 +40,7 @@ An HTLC is defined to have the following components:
 
         * Preimage hash (hash of the preimage)
 
-        * Length of the preimage hash
+        * Length of the preimage
 
     * Time lock
 
@@ -52,29 +52,29 @@ An HTLC is defined to have the following components:
 
 ### **Parties**
 
-Two parties must be defined for an HTLC: one `depositor`, and one `recipient`. Note that a proposal transaction may be used for tasks such as multi-signature, but the end result at approval is still one `depositor` and one `recipient`.
+Two parties must be defined within each HTLC: the `depositor` and the `recipient`. The `depositor` will escrow their assets within the HTLC and designate the `recipient` to receive them. Note that a proposal transaction may be used for tasks such as multi-signature, but the end result at approval remains a single `depositor` and a single `recipient`.
 
 ### **Escrow Asset**
 
-An HTLC involves a conditional transfer of ownership of a `quantity` of an `asset` from a designated party (the "`depositor`") to the second party (the "`recipient`"). The HTLC holds the designated `escrow assets` from `depositor` on the blockchain and will continue to enforce the specified `conditions` until one is satisfied.
+An HTLC involves a conditional transfer of the defined `asset symbol` in the amount of `assest quantity` from the `depositor` to the `recipient`. The HTLC holds these designated `escrow assets` from `depositor` on the blockchain and will continue to enforce the specified `conditions` until one is satisfied.
 
 ### **Conditions**
 
 There are two competing conditions within an HTLC, the `hash lock` and the `time lock`.
 
-The HTLC contains a `hash lock` condition, which are both the `preimage hash` and its `length`, barring the transfer of held `escrow assets` unless satisfied. If a `preimage` of requisite `length` is provided to the HTLC which generates a hash matching the `preimage hash`, the `preimage` is then stored within the blockchain, and the `escrow assets` are transferred to the `recipient`.
+The HTLC contains a `hash lock` condition, which comprise both the `preimage hash` and `length of the preimage`, barring the transfer of held `escrow assets` unless satisfied. If a `preimage` of requisite `length` is provided to the HTLC which generates a hash matching the `preimage hash`, the `preimage` is then stored within the blockchain, and the `escrow assets` are transferred to the `recipient`.
 
 If a satisfactory `preimage` is not provided to the HTLC before the stipulated `time lock` expires, the `depositor` may request the return of `escrow assets`. The HTLC will only evaluate transfer request from `depositor` and after `timeout threshold`, then return `escrow assets` to `depositor`.
 
 ### **Condition Evaluators**
 
-The `preimage` can be thought of a secret key, that will eventually be shared with the `recipient`. This can be a word, a phrase, or even a random series of bytes. The `length` of the `preimage` must be shared and stored within the HTLC at creation.
+The `preimage` can be thought of a secret key, that will eventually be shared with the `recipient`. This can be a word, a phrase, or even a random series of bytes. The `length` of the `preimage` must be specified within the HTLC at creation.
 
 Upon presentation of a `preimage`, the HTLC `condition evaluator` validates:
 
 1. That the `timeout threshold` has not yet occurred.
 
-2. That the `preimage length` matches the specified `length`. 
+2. That the length of the `preimage` matches the specified `preimage length`. 
 
 3. That the `hash of the preimage` matches the specified `preimage hash`. 
 
@@ -100,13 +100,13 @@ Code _could_ be added to automate the return of funds. This could be part of blo
 
 ### **Fee**
 
-Creating and fulfillment are two operations that add data to the blockchain. The fees for these operations are based on the standards set for blocks, and are similar to costs of other items stored on-chain.
+Creating and fulfillment are two operations that add data to the blockchain. The `fee` for each operations is based on the standards set for blocks, and is similar to costs of other items stored on-chain.
 
 **TODO:** Discuss fees may be variable it is possible to store variable length preimage hash.
 
 ## **Existing Escrow Proposals**
 
-The section describes various escrow concepts that have been proposed either for BitShares or for other blockchains or services in terms of the elements that have been defined above. This is intended to provide some background and comparison to the concepts that follow.
+This section describes various escrow concepts that have been proposed either for BitShares or for other blockchains or services in terms of the elements that have been defined above. This is intended to provide some background and comparison to the concepts that follow.
 
 **TODO:** Elaborate Interledger
 
@@ -114,7 +114,7 @@ The section describes various escrow concepts that have been proposed either for
 
 ### **BitShares Escrow**
 
-A separate BSIP is currently being discussed that provides a more traditional escrow service. This involves parties, agents, and a more complex evaluation. HTLC shares some similarities, and could be considered a thin subset of Bitshares Escrow.
+A separate BSIP [cite] is currently being discussed that provides a more traditional escrow service. This involves parties, agents, and a more complex evaluation. HTLC shares some similarities, and could be considered a thin subset of Bitshares Escrow.
 
 The smaller, well-defined nature of HTLC provides a major advantage for applications that want to attempt tasks such as cross chain atomic swaps.
 
@@ -134,13 +134,13 @@ The following will describe possible concepts that could be implemented in BitSh
 
 ### **Set-Price Swap**
 
-Two parties may agree on an asset swap at a set price, without using the exchange. Two HTLC contracts with the same hash can provide a trustless exchange of assets
+Two parties may agree on an asset swap at a set price, without using the exchange. Two HTLC contracts with the same hash can provide a trustless exchange of assets.
 
 #### **Business Approach**
 
-Party A (Alice) generates an HTLC with a preimage of her choice. The contract stipulates that she will deposit 100 bitUSD into the account of Party B (Bob), if he provides the preimage that generates the stored hash before 10AM tomorrow. She then shares the contract identifier with Bob.
+Alice (the `depositor`) generates an HTLC with a preimage of her choosing. The contract stipulates that she will deposit 100 bitUSD into the account of Bob (the `recipient`), if he provides the preimage that generates the stored hash before 10AM tomorrow. She then shares the contract identifier with Bob.
 
-Bob examines the contract Alice created, being sure to examine that the receiving account, the amount, and the timeout agrees with his desires. He then generates another HTLC that will deposit 10,000 bitshares into the account of Alice, if she provides the preimage that generates the same hash before 5pm today. He then shares the contract identifier with Alice.
+Bob examines the contract Alice created, being sure to examine that it contains his desired receiving account, asset symbol, asset quantity, preimage length, and the timelock threshold agrees with his desires. He then generates another HTLC that will deposit 10,000 bitshares into the account of Alice, if she provides the preimage that generates the same hash before 5pm today. He then shares the contract identifier with Alice.
 
 Alice now examines the contract Bob created, being sure to examine that the receiving account, the amount, and the timeout agrees with her desires. She also verifies that the hash matches the hash of her contract. She now uses her preimage to "unlock" Bob's contract, which puts 10,000 bitshares into her account. This also posts the preimage on the BitShares blockchain. NOTE: She must do this before 5PM. Otherwise, Bob may (and should) reclaim the funds in the contract he created.