From 81df8f37d41d11f7d52ee043d9ab15a8af045c48 Mon Sep 17 00:00:00 2001
From: Jennifer Hasegawa <jennifer.hasegawa@gmail.com>
Date: Wed, 6 Feb 2019 09:40:56 -0800
Subject: [PATCH] still working

---
 .../create-a-smart-contract-using-escrow.md   | 83 ++++++++++---------
 1 file changed, 43 insertions(+), 40 deletions(-)

diff --git a/content/use-cases/create-a-smart-contract-using-escrow.md b/content/use-cases/create-a-smart-contract-using-escrow.md
index a591bbe743..a013c7d540 100644
--- a/content/use-cases/create-a-smart-contract-using-escrow.md
+++ b/content/use-cases/create-a-smart-contract-using-escrow.md
@@ -1,17 +1,18 @@
-# Create a Smart Contract Using Escrows
+# Use an Escrow as a Smart Contract
 
-<ul>A smart contract is a blockchain-based program that encodes the conditions and fulfillment of an agreement between two or more parties and automatically fulfills the terms of the agreement once conditions are met.</u>
+***TODO: fix references to escrow and smart contract. figure out how to reference both -- without confusing things and using them interchangeably***
 
-<ul>A smart contract can help you exchange anything of value in a transparent, traceable, tamper-resistant, and irreversible way.</ul>
+A smart contract is a blockchain-based program that encodes the conditions and fulfillment of an agreement between two or more parties and automatically fulfills the terms of the agreement once conditions are met.
 
-<ul>The benefit of encoding a smart contract into a blockchain is that it enables the contract to be securely performed without traditional third-parties, like financial or legal institutions, which can result in lower costs. Instead, the contract is supervised by the distributed, decentralized network of computers that run the blockchain.</ul>
+A smart contract can help you exchange anything of value in a transparent, traceable, tamper-resistant, and irreversible way.
 
-<ul>You can use the XRP Ledger escrow feature to provide smart contracts that release XRP after a certain time has passed or after a cryptographic condition has been fulfilled. In this case, we'll create a smart contract using a conditionally held escrow that releases XRP after a cryptographic condition has been fulfilled.</ul>
+The benefit of encoding a smart contract into a blockchain is that it enables the contract to be securely performed without traditional third-parties, like financial or legal institutions, which can result in lower costs. Instead, the contract is supervised by the distributed, decentralized network of computers that run the blockchain.
 
-<ul>Consider this scenario that we'll use to frame this use case: A party planner uses smart contracts to manage payments from their clients (party hosts) to party vendors, such as caterers and bands. Specifically, the party planner wants to use a smart contract to enable its party host to pay their party band 2000 XRP once it finishes playing its set.</ul>
+You can use XRP Ledger escrows as smart contracts that release XRP after a certain time has passed or after a cryptographic condition has been fulfilled. In this case, we'll use an escrow as a smart contract that releases XRP after a cryptographic condition has been fulfilled.
 
-<ul>Here’s a roadmap to the high-level tasks that the participants need to complete to implement this smart contract using an XRP Ledger escrow.</ul>
+Let's use this scenario to help illustrate this use case: A party planner uses smart contracts to manage payments from party hosts to party vendors. Specifically, the party planner wants to use a smart contract to enable the party host to pay the party band 2000 XRP once they are done with their set.
 
+Here’s a roadmap to the high-level tasks that these participants need to complete to provide this smart contract using an XRP Ledger escrow.
 
 
 {% set n = cycler(* range(1,99)) %}
@@ -20,21 +21,23 @@
 <!-- <span class="use-case-step-length">(1 hour)</span> -->
 ## Meet the prerequisites
 
-The party host must have:
+The party host (sender) must have:
 
-- An XRP Ledger account to pay XRP into the escrow.
+- An XRP Ledger account that holds enough XRP to pay for escrow and any fees incurred.
 
 - Access to a `rippled` server that they can use to create the escrow and, if necessary, cancel it.
 
-The party band must have:
+The party band (receiver) must have:
 
-- An XRP Ledger account to receive XRP paid by the escrow.
+- An XRP Ledger account that can receive the XRP paid by the escrow.
 
-- The ability to look up an XRP Ledger transaction hash. For example, they can use the [RPC Tool](https://developers.ripple.com/xrp-ledger-rpc-tool.html) or have access to a `rippled` server that they can use to send transactions.
+- The ability to look up the details of an XRP Ledger transaction hash. For example, they can use the [RPC Tool](https://developers.ripple.com/xrp-ledger-rpc-tool.html) or access a `rippled` server that they can use to look up the transaction hash.
 
-The party planner must have:
+The party planner (third-party oracle) must have:
 
-- Access to a `rippled` server that they can use to finish the escrow.
+- The ability to generate a condition and a fulfillment.
+
+- Access to a `rippled` server that they can use to submit the fulfillment value and finish the escrow.
 
 
 
@@ -46,29 +49,31 @@ Before the party host can create the smart contract, the participants must clear
 
 - Should the smart contract be fulfilled after a specific time has passed or after a cryptographic condition has been fulfilled?
 
-  Because the smart contract must be fulfilled only after the party band has completed their set, the participants should use a smart contract that is fulfilled after a cryptographic condition has been fulfilled.
+  Because the smart contract must be fulfilled only after the party band has completed their set, the participants agree to use a smart contract that is fulfilled after a cryptographic condition has been fulfilled.
 
   Even if the party band agrees to show up and complete their set at a designated time, the participants shouldn't use a time-based contract because of the possibility that the party band won't show up.
 
-- Should the participants be able to cancel the smart contract after a specific time period if the condition is not fulfilled?
-
-  The participants agree that the escrow can be canceled after 11:00 pm the night of the party, which is when the party band is scheduled to complete their set. After cancellation, the locked XRP will then return to the party host's account.
-
 - Should the smart contract disallow fulfillment until a specific time?
 
   The participants agree to disallow the smart contract from being fulfilled until 11:00 pm the night of the party, which is when the party band is scheduled to complete their set. ***TODO: not necessary, but just an extra precaution? Or just unnecessary?***
 
-- How much XRP should the smart contract to hold and potentially pay?
+- Should the participants be able to cancel the smart contract after a specific time period if the condition is not fulfilled?
 
-  The participants agree that the smart contract should hold and potentially pay 2000 XRP, which is the party band's fee.
+  The participants agree that the escrow can be canceled after 12 noon the day after the party. This gives the party planner enough time to finish the escrow, if the party band fulfills their end of the contract. After cancellation, the locked XRP returns to the party host's account.
 
-- Which XRP Ledger account should the smart contract pay XRP out of?
+  This timing also prevents the party host from maliciously cancelling the escrow before the party planner finishes the fulfilled contract.
 
-  The participants agree that the smart contract should pay XRP out of the party host's XRP Ledger account.
+- How much XRP should the smart contract to lock up and potentially pay?
 
-- Which XRP Ledger account should the smart contract pay XRP into?
+  The participants agree that the smart contract should lock up and potentially pay 2000 XRP, which is the party band's fee.
 
-  The participants agree that the smart contract should pay XRP to the party band's XRP Ledger account.
+- Which XRP Ledger account should the smart contract lock up and potentially pay XRP out of?
+
+  The participants agree that the smart contract should lock up and potentially pay XRP out of the party host's XRP Ledger account.
+
+- Which XRP Ledger account should the smart contract lock up and potentially pay XRP into?
+
+  The participants agree that the smart contract should lock up and potentially pay XRP to the party band's XRP Ledger account.
 
 
 
@@ -76,27 +81,25 @@ Before the party host can create the smart contract, the participants must clear
 <!-- <span class="use-case-step-length">(1 hour)</span> -->
 ## [Generate a condition and a fulfillment](send-a-conditionally-held-escrow.html#1-generate-condition-and-fulfillment) (party planner)
 
-Because participants want to create a conditionally held escrow to provide the smart contract, the party planner must generate a condition and a fulfillment.
-
-The party planner provides the condition value to the party host, who will create the escrow that provides the smart contract.
-
-The party planner keeps the fulfillment value a secret until it is time to fulfill the contract.
+Because participants want to create a conditionally held escrow to provide the smart contract, they need a condition value and a fulfillment value. The participant that creates these values must be a neutral party, such as the party planner.
 
 In this use case, the party planner is playing the role of an _oracle_. In the context of smart contracts, an oracle is a third-party agent that can verify real-world events to either fulfill or invalidate a smart contract. This use case uses a human oracle for illustrative purposes, but in real-life, a software application would more likely play the role of the oracle to automate the process.
 
 Using an XRP Ledger escrow to provide this smart contract is a great arrangement because the party planner, as the third-party oracle, never "holds" the funds as one might in a traditional escrow arrangement, and can't possibly take the funds for themselves.
 
+The party planner generates the condition and fulfillment values and provides the condition value to the party host, who creates the escrow that provides the smart contract.
+
+The party planner keeps the fulfillment value a secret until it is time to finish the contract.
+
 
 
 <span class="use-case-step-num">{{n.next()}}</span>
 <!-- <span class="use-case-step-length">(1 hour)</span> -->
-## [Calculate times needed for the contract](send-a-conditionally-held-escrow.html#2-calculate-release-or-cancel-time) (party planner)
+## [Calculate times needed for the contract](send-a-conditionally-held-escrow.html#2-calculate-release-or-cancel-time) (party host)
 
-Because the participants want the smart contract to be eligible for cancellation the day after the party if the contact is not fulfilled, the party host must calculate a `CancelAfter` value to include in the escrow definition.
+Because the participants want the smart contract to be eligible for cancellation after 11:00 pm the night of the party (the time when the party band is scheduled to finish its set) if the contract is not fulfilled, the party host must calculate a `CancelAfter` value to include in the escrow definition.
 
-Because the participants want to disallow the smart contact from being fulfilled until the time at which the party band is scheduled to finish its set at the party, the party host must calculate a `FinishAfter` value to include in the escrow definition.
-
-The party band can validate these values after the party host creates the escrow.
+Because the participants want to disallow the smart contact from being fulfilled after 11:00 pm the night of the party (the time when the party band is scheduled to finish its set), the party host must calculate a `FinishAfter` value to include in the escrow definition.
 
 
 
@@ -104,7 +107,7 @@ The party band can validate these values after the party host creates the escrow
 <!-- <span class="use-case-step-length">(1 hour)</span> -->
 ## [Create the escrow](send-a-conditionally-held-escrow.html#3-submit-escrowcreate-transaction) (party host)
 
-Create the escrow to provide the smart contract. The party host must create the escrow because they are the only participant that can authorize the lock up and potential payout of XRP from their XRP Ledger account.
+The party host creates the escrow to provide the smart contract. The party host must create the escrow because they are the only participant that can authorize the lock up and potential payout of XRP from their XRP Ledger account.
 
 
 
@@ -112,9 +115,9 @@ Create the escrow to provide the smart contract. The party host must create the
 <!-- <span class="use-case-step-length">(1 hour)</span> -->
 ## [Wait for validation](send-a-conditionally-held-escrow.html#4-wait-for-validation) and [confirm escrow creation](send-a-conditionally-held-escrow.html#5-confirm-that-the-escrow-was-created) (party host and party band)
 
-Wait for validation of the ledger that contains the escrow creation transaction and then confirm that the escrow was created.
+The party host waits for validation of the ledger that contains the escrow creation transaction and then confirms that the escrow was created.
 
-At this time, the party host provides the escrow transaction's `hash` value to the party band. The party band can use the `hash` value to look up the escrow transaction on the XRP Ledger to ensure that it is been created correctly.
+The party host then provides the escrow transaction's `hash` value to the party band. The party band can use the `hash` value to look up the escrow transaction on the XRP Ledger to ensure that it has been created using the agreed upon values.
 
 
 
@@ -126,14 +129,14 @@ The party band shows up and plays their set as defined in the smart contract.
 
 The party planner finishes the escrow using the fulfillment value they generated and kept secret.
 
-If the party band is a no-show, the party planner does not finish the escrow, but rather [cancels the escrow](cancel-an-expired-escrow.html) to return the held XRP to the party host's account.
+Alternatively, if the party band is a no-show, the party planner does not finish the escrow. In this case, any participant can [cancel the escrow](cancel-an-expired-escrow.html) to return the held XRP to the party host's account.
 
 
 <span class="use-case-step-num">{{n.next()}}</span>
 <!-- <span class="use-case-step-length">(1 hour)</span> -->
 ## [Wait for validation](send-a-conditionally-held-escrow.html#7-wait-for-validation) and [confirm escrow finish](send-a-conditionally-held-escrow.html#8-confirm-final-result) (party planner, party host, and party band)
 
-Wait for validation of the ledger that contains the escrow finish transaction and then confirm that the escrow was finished.
+The party planner waits for validation of the ledger that contains the escrow finish transaction and then confirms that the escrow was finished.
 
 At this time, the party planner provides the transaction's `hash` value to the party host and party band. The party host and party band can use the `hash` value to look up the escrow transaction on the XRP Ledger to ensure that it is been finished correctly. The party host and band can also just check their XRP Ledger account balances to ensure that the balances have decreased and increased by 2000 XRP accordingly.