Fixup: Specification

bsip-0000.md

@@ -56,7 +56,7 @@ Two parties must be defined within each HTLC: the `depositor` and the `recipient
 
 ### **Escrow Asset**
 
-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.
+An HTLC involves a conditional transfer of the defined `asset symbol` in the amount of `assets 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**
 
@@ -100,9 +100,9 @@ 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 `fee` for each operations is based on the standards set for blocks, and is 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 operation 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.
+**TODO:** Discuss fees may be variable, as it is possible to store a variable length preimage hash.
 
 ## **Existing Escrow Proposals**
 
@@ -114,7 +114,7 @@ This section describes various escrow concepts that have been proposed either fo
 
 ### **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.
+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.
 
@@ -130,35 +130,37 @@ One of the existing features of BitShares is the ability to have a proposal that
 
 ## **Possible Concepts to Implement**
 
-The following will describe possible concepts that could be implemented in BitShares.
+The following will describe possible concepts that could be implemented within the BitShares protocol.
 
 ### **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 a swap of two distinct `escrow assets` at a set price (defined exchange ratio), without using an exchange such as the BitShares DEX. This will require two (2) HTLC contracts containing the identical `preimage hash` within each to "link" them together and facilitate the execution of an "atomic swap" of these "locked" `escrow assets` between the party's accounts resulting in a trustless value exchange.
 
 #### **Business Approach**
 
-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.
+Alice begins by generating a distinct `preimage` of her choosing, notes the `preimage length` and calculates the `preimage hash`. She retains the `preimage` in secret, then creates a new HTLC stipulating that the `depositor` account "alice" will transfer `quantity` "100" "bitUSD" `asset` into the `recipient` account "bob" if a `preimage` is presented matching the `preimage hash` before the `timelock threshold` of 10AM tomorrow. Upon consensus validation of the HTLC, the 100 bitUSD `escrow assets` are transferred from Alice's `depositor` account into the HTLC where they remain locked by the `preimage hash` and `timelock threshold`. She then shares the resulting `contract identifier` with Bob.
 
-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.
+Bob queries the blockchain for the `contract identifier` Alice provided. He examines to ensure it contains his desired `recipient` account, `asset` symbol, asset `quantity`, `preimage length`, and `timelock threshold`. Bob now creates his own HTLC that will deposit `quantity` "10,000" "BTS" `symbol` into the `recipient` account "alice" from `depositor` account "bob", if a `preimage` that generates the `preimage hash` Bob copied from Alice's HTLC before the `timelock threshold` of 5pm today. Upon consensus validation of Bob's HTLC, his 10,000 BTS `escrow assets` are transferred from his `depositor` account and "locked" into the contract. He then shares the resulting `contract identifier` with Alice. Notice Bob specified a `timelock threshold` much shorter than Alice defined in her contract. This ensures Bob will have enough time to observe and use the `preimage` Alice will publish to the blockchain next. 
 
-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.
+Alice now examines the HTLC Bob created, ensuring the `preimage hash` and `preimage length` both match the original values she used within her contract. She also verifies her desired `recipient` account "alice", the `quantity`, `symbol`, and the `timelock threshold` agree with her intentions. She now uses her `preimage` to "unlock" Bob's contract. Once consensus validation occurs, the HTLC will transfer the `escrow assets` 10,000 BTS into her `recipient` account "alice". This reveals the `preimage` on the BitShares blockchain for Bob to use next. NOTE: She must do this before 5PM. Otherwise, Bob may (and should) reclaim the funds in the contract he created.
 
-Bob can now see the preimage that Alice used to receive her bitshares, and he can use the same preimage to "unlock" the contract Alice created, and receive the 100 bitUSD. NOTE: He must do this before 10AM tomorrow. Otherwise, Alice may (and should) reclaim the funds in the contract she created.
+Bob can now observe the `preimage` Alice used to "unlock" his HTLC, and he will use it to "unlock" her HTLC to receive the 100 bitUSD `escrow assets` into his `recipient` account "bob". NOTE: He must do this before 10AM tomorrow. Otherwise, Alice may (and should) reclaim the funds in the contract she created.
 
 ### **Cross-Chain Swap**
 
-The set-price swap mentioned above works the same across chains that support HTLC. Bitcoin, as an example, supports HTLC.
+Similar to the set-price swap mentioned above, two parties may exchange tokens between distinct blockchains when both implement HTLC support. Bitcoin, Litecoin and many others support HTLC [cite].
 
 #### **Business Approach**
 
-Alice generates an HTLC on the BitShares blockchain with a preimage of her choice. The contract stipulates that she will deposit 1 bitBTC into the account of Bob, if he provides the preimage that generates the stored hash before 10AM tomorrow. She then shares the contract identifier with Bob.
+Alice and Bob intend to swap BTC (bitcoin token) and BTS (BitShares token). This will require both parties to define both a BTC deposit address and BTS deposit account. These addresses/accounts will be exchanged between the parties.
 
-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 an HTLC that will deposit 1 BTC into the Bitcoin address of Alice, if she provides the preimage that generates the same hash before 5pm today. He then shares the Bitcoin transaction identifier with Alice.
+Alice will initiate the first leg of the swap on the BitShares Network with her HTLC and Bob will follow up on the Bitcoin Network with his HTLC. Allice generates a distinct `preimage` of her choosing, notes the `preimage length` and calculates the `preimage hash`. She retains the `preimage` in secret, then creates a new HTLC stipulating that the `depositor` account "alice" will transfer `quantity` "10,000" "bitUSD" `asset` into the `recipient` account "bob" if a `preimage` is presented matching the `preimage hash` before the `timelock threshold` of 10AM tomorrow. Upon consensus validation of the HTLC on the BitShares Network, the 10,000 bitUSD `escrow assets` are transferred from Alice's `depositor` account into the HTLC where they remain locked by the `preimage hash` and `timelock threshold`. She then shares the resulting `contract identifier` with Bob.
 
-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 1 BTC into her Bitcoin wallet. This also posts the preimage on the Bitcoin blockchain. NOTE: She must do this before 5PM. Otherwise, Bob may (and should) reclaim the funds in the contract he created.
+Bob queries the BitShares Network for the `contract identifier` Alice provided. He examines to ensure it contains his desired `recipient` account, `asset` symbol, asset `quantity`, `preimage length`, and `timelock threshold`. Bob now creates and funds his own HTLC on the Bitcoin Network that will spend the `UTXO` of this contract to the `recipient address` Alice provided during their setup phase, of `amount` 1 BTC if a `preimage` that generates the `preimage hash` Bob copied from Alice's HTLC before the `timelock threshold` of 5pm today. Upon consensus validation of Bob's HTLC on the Bitcoin Network, 1 BTC he controlled are spent into the contract and "locked". He then shares the resulting `contract identifier` with Alice. Notice Bob specified a `timelock threshold` much shorter than Alice defined in her contract. This ensures Bob will have enough time to observe and use the `preimage` Alice will publish to the blockchain next. 
 
-Bob can now see the preimage that Alice used to receive her Bitcoin, and he can use the same preimage to "unlock" the contract Alice created, and receive the 1 bitBTC. NOTE: He must do this before 10AM tomorrow. Otherwise, Alice may (and should) reclaim the funds in the contract she created.
+Alice now examines the HTLC Bob created on the Bitcoin Network, ensuring the `preimage hash` and `preimage length` both match the original values she used within her contract. She also verifies her desired `recipient address`, `quantity`, and `timelock threshold` agree with her intentions. She now uses her `preimage` to "unlock" Bob's contract. Once consensus validation occurs on the Bitcoin Network, the HTLC will spend 1 BTC to Alice's `recipient address`. This reveals the `preimage` on the Bitcoin Network for Bob to use next. NOTE: She must do this before 5PM. Otherwise, Bob may (and should) reclaim the funds in the contract he created.
+
+Bob has now observed the `preimage` Alice used to "unlock" his HTLC, and he will use it to "unlock" her HTLC to receive the 10,000 bitUSD `escrow assets` into his `recipient` account "bob". NOTE: He must do this before 10AM tomorrow. Otherwise, Alice may (and should) reclaim the funds in the contract she created.
 
 # **Discussion**