ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-20 03:35:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add escrow state diagram

Browse Source
This commit is contained in:
mDuo13
2019-03-11 18:28:58 -07:00
parent b348e42b31
commit bc290e7f08
3 changed files with 509 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

487
content/_img-sources/escrow-states.uxf Normal file
View File

@@ -0,0 +1,487 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<diagram program="umlet" version="14.2">
<zoom_level>10</zoom_level>
<element>
<id>UMLClass</id>
<coordinates>
<x>210</x>
<y>160</y>
<w>170</w>
<h>60</h>
</coordinates>
<panel_attributes>*Held*
No one can finish or cancel the Escrow.
style=wordwrap</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLSpecialState</id>
<coordinates>
<x>230</x>
<y>80</y>
<w>20</w>
<h>20</h>
</coordinates>
<panel_attributes>type=initial</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>230</x>
<y>80</y>
<w>210</w>
<h>100</h>
</coordinates>
<panel_attributes>lt=&lt;-
EscrowCreate transaction</panel_attributes>
<additional_attributes>10.0;80.0;10.0;10.0</additional_attributes>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>230</x>
<y>210</y>
<w>30</w>
<h>80</h>
</coordinates>
<panel_attributes>lt=&lt;-
</panel_attributes>
<additional_attributes>10.0;60.0;10.0;10.0</additional_attributes>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>210</x>
<y>270</y>
<w>170</w>
<h>80</h>
</coordinates>
<panel_attributes>*Ready*
Anyone can finish the Escrow.
style=wordwrap</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLSpecialState</id>
<coordinates>
<x>510</x>
<y>300</y>
<w>20</w>
<h>20</h>
</coordinates>
<panel_attributes>type=final</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>370</x>
<y>290</y>
<w>160</w>
<h>50</h>
</coordinates>
<panel_attributes>lt=&lt;-
EscrowFinish
transaction</panel_attributes>
<additional_attributes>140.0;20.0;10.0;20.0</additional_attributes>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>230</x>
<y>340</y>
<w>30</w>
<h>110</h>
</coordinates>
<panel_attributes>lt=&lt;-
</panel_attributes>
<additional_attributes>10.0;90.0;10.0;10.0</additional_attributes>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>210</x>
<y>430</y>
<w>170</w>
<h>80</h>
</coordinates>
<panel_attributes>*Expired*
Anyone can cancel the Escrow.
No one can finish it.
style=wordwrap</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>370</x>
<y>450</y>
<w>160</w>
<h>50</h>
</coordinates>
<panel_attributes>lt=&lt;-
EscrowCancel
transaction</panel_attributes>
<additional_attributes>140.0;20.0;10.0;20.0</additional_attributes>
</element>
<element>
<id>UMLSpecialState</id>
<coordinates>
<x>510</x>
<y>460</y>
<w>20</w>
<h>20</h>
</coordinates>
<panel_attributes>type=flow_final</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLSpecialState</id>
<coordinates>
<x>990</x>
<y>80</y>
<w>20</w>
<h>20</h>
</coordinates>
<panel_attributes>type=initial</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>990</x>
<y>90</y>
<w>210</w>
<h>200</h>
</coordinates>
<panel_attributes>lt=&lt;-
r2=EscrowCreate transaction
</panel_attributes>
<additional_attributes>10.0;180.0;10.0;10.0</additional_attributes>
</element>
<element>
<id>UMLSpecialState</id>
<coordinates>
<x>1270</x>
<y>300</y>
<w>20</w>
<h>20</h>
</coordinates>
<panel_attributes>type=final</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>1130</x>
<y>290</y>
<w>160</w>
<h>50</h>
</coordinates>
<panel_attributes>lt=&lt;-
EscrowFinish
transaction</panel_attributes>
<additional_attributes>140.0;20.0;10.0;20.0</additional_attributes>
</element>
<element>
<id>Text</id>
<coordinates>
<x>210</x>
<y>20</y>
<w>180</w>
<h>30</h>
</coordinates>
<panel_attributes>*FinishAfter time only*</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Text</id>
<coordinates>
<x>980</x>
<y>20</y>
<w>180</w>
<h>30</h>
</coordinates>
<panel_attributes>*Condition only*</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLSpecialState</id>
<coordinates>
<x>610</x>
<y>80</y>
<w>20</w>
<h>20</h>
</coordinates>
<panel_attributes>type=initial</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>610</x>
<y>80</y>
<w>210</w>
<h>100</h>
</coordinates>
<panel_attributes>lt=&lt;-
EscrowCreate transaction</panel_attributes>
<additional_attributes>10.0;80.0;10.0;10.0</additional_attributes>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>610</x>
<y>210</y>
<w>30</w>
<h>80</h>
</coordinates>
<panel_attributes>lt=&lt;-
</panel_attributes>
<additional_attributes>10.0;60.0;10.0;10.0</additional_attributes>
</element>
<element>
<id>UMLSpecialState</id>
<coordinates>
<x>890</x>
<y>300</y>
<w>20</w>
<h>20</h>
</coordinates>
<panel_attributes>type=final</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>750</x>
<y>290</y>
<w>160</w>
<h>50</h>
</coordinates>
<panel_attributes>lt=&lt;-
EscrowFinish
transaction</panel_attributes>
<additional_attributes>140.0;20.0;10.0;20.0</additional_attributes>
</element>
<element>
<id>Text</id>
<coordinates>
<x>590</x>
<y>20</y>
<w>180</w>
<h>40</h>
</coordinates>
<panel_attributes>*Both Condition and FinishAfter time*
style=wordwrap</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>970</x>
<y>270</y>
<w>170</w>
<h>80</h>
</coordinates>
<panel_attributes>*Conditionally Ready*
Anyone with the correct fulfillment can finish the Escrow.
style=wordwrap</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>970</x>
<y>430</y>
<w>170</w>
<h>80</h>
</coordinates>
<panel_attributes>*Expired*
Anyone can cancel the Escrow.
No one can finish it.
style=wordwrap</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>990</x>
<y>340</y>
<w>30</w>
<h>110</h>
</coordinates>
<panel_attributes>lt=&lt;-</panel_attributes>
<additional_attributes>10.0;90.0;10.0;10.0</additional_attributes>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>610</x>
<y>340</y>
<w>30</w>
<h>110</h>
</coordinates>
<panel_attributes>lt=&lt;-</panel_attributes>
<additional_attributes>10.0;90.0;10.0;10.0</additional_attributes>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>590</x>
<y>160</y>
<w>170</w>
<h>60</h>
</coordinates>
<panel_attributes>*Held*
No one can finish or cancel the Escrow.
style=wordwrap</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>590</x>
<y>430</y>
<w>170</w>
<h>80</h>
</coordinates>
<panel_attributes>*Expired*
Anyone can cancel the Escrow.
No one can finish it.
style=wordwrap</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>110</x>
<y>40</y>
<w>30</w>
<h>560</h>
</coordinates>
<panel_attributes>lt=&lt;-</panel_attributes>
<additional_attributes>10.0;540.0;10.0;10.0</additional_attributes>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>590</x>
<y>270</y>
<w>170</w>
<h>80</h>
</coordinates>
<panel_attributes>*Conditionally Ready*
Anyone with the correct fulfillment can finish the Escrow.
style=wordwrap</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>90</x>
<y>380</y>
<w>1230</w>
<h>30</h>
</coordinates>
<panel_attributes>lt=.</panel_attributes>
<additional_attributes>10.0;10.0;1210.0;10.0</additional_attributes>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>90</x>
<y>230</y>
<w>840</w>
<h>30</h>
</coordinates>
<panel_attributes>lt=.</panel_attributes>
<additional_attributes>10.0;10.0;820.0;10.0</additional_attributes>
</element>
<element>
<id>Text</id>
<coordinates>
<x>10</x>
<y>210</y>
<w>110</w>
<h>50</h>
</coordinates>
<panel_attributes>FinishAfter time
style=wordwrap</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Text</id>
<coordinates>
<x>10</x>
<y>360</y>
<w>110</w>
<h>70</h>
</coordinates>
<panel_attributes>CancelAfter time
(if specified)
style=wordwrap</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>750</x>
<y>450</y>
<w>160</w>
<h>50</h>
</coordinates>
<panel_attributes>lt=&lt;-
EscrowCancel
transaction</panel_attributes>
<additional_attributes>140.0;20.0;10.0;20.0</additional_attributes>
</element>
<element>
<id>UMLSpecialState</id>
<coordinates>
<x>890</x>
<y>460</y>
<w>20</w>
<h>20</h>
</coordinates>
<panel_attributes>type=flow_final</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>1130</x>
<y>450</y>
<w>160</w>
<h>50</h>
</coordinates>
<panel_attributes>lt=&lt;-
EscrowCancel
transaction</panel_attributes>
<additional_attributes>140.0;20.0;10.0;20.0</additional_attributes>
</element>
<element>
<id>UMLSpecialState</id>
<coordinates>
<x>1270</x>
<y>460</y>
<w>20</w>
<h>20</h>
</coordinates>
<panel_attributes>type=flow_final</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Text</id>
<coordinates>
<x>100</x>
<y>20</y>
<w>60</w>
<h>30</h>
</coordinates>
<panel_attributes>Time
style=wordwrap</panel_attributes>
<additional_attributes/>
</element>
</diagram>

24
content/concepts/complex-payment-types/escrow.md
View File

@@ -1,6 +1,6 @@
# Escrow
Escrow is a feature of the XRP Ledger that allows you to send conditional XRP payments. These conditional payments, called _escrows_, set aside XRP and deliver it later when certain conditions are met. Conditions to successfully finish an escrow include time-based unlocks and [crypto-conditions][]. Escrows can also be set to expire if not finished in time. Conditional held payments are a key feature for full [Interledger Protocol][] support, which enables chains of payments to cross any number of ledgers.
Escrow is a feature of the XRP Ledger that allows you to send conditional XRP payments. These conditional payments, called _escrows_, set aside XRP and deliver it later when certain conditions are met. Conditions to successfully finish an escrow include time-based unlocks and [crypto-conditions][]. Escrows can also be set to expire if not finished in time.
The XRP set aside in an escrow is locked up. No one can use or destroy the XRP until the escrow has been successfully finished or canceled. Before the expiration time, only the intended receiver can get the XRP. After the expiration time, the XRP can only be returned to the sender.
@@ -33,12 +33,32 @@ Escrow is designed as a feature to enable the XRP Ledger to be used in the [Inte
- Escrow only works with XRP, not issued currencies.
- Escrow requires sending at least two transactions: one to create the escrow, and one to finish or cancel it. Thus, it may not be financially sensible to escrow payments for very small amounts, because the participants must destroy the [transaction cost](transaction-cost.html) of the two transactions.
- When using Crypto-Conditions, the [cost of the transaction to finish the escrow](#escrowfinish-transaction-cost) is higher than usual.
- All escrows must have a "finish-after" time, an expiration time, or both. Neither time can be in the past when the transaction to create the escrow executes.
- All escrows must be created with a "finish-after" time or a [crypto-condition][]. If the escrow does not have a finish-after time, it must have an expiration time.
**Note:** The [fix1571 amendment][] changed the requirements for creating an escrow. Escrows created before that amendment could provide an expiration time with no condition or finish-after time. Anyone can finish such escrows immediately (sending the funds to the intended recipient).
- None of the time values can be in the past when the escrow-creating transaction executes.
- Timed releases and expirations are limited to the resolution of XRP Ledger closes. This means that, in practice, times may be rounded to approximately 5 second intervals, depending on exactly when the ledgers close.
- The only supported [crypto-condition][] type is PREIMAGE-SHA-256.
Escrow provides strong guarantees that are best suited for high-value, low-quantity payments. [Payment Channels](use-payment-channels.html) are better suited for fast, low-value payments. Of course, unconditional [Payments](payment.html) are also preferable for many use cases.
## State Diagram
The following diagram shows the states an Escrow can progress through:
[![State diagram showing escrows going from Held → Ready/Conditionally Ready → Expired](img/escrow-states.png)](img/escrow-states.png)
The diagram shows three different cases for three possible combinations of the escrow's "finish-after" time (`FinishAfter` field), crypto-condition (`Condition` field), and expiration time (`CancelAfter` field):
- **Time-based Escrow (left):** With only a finish-after time, the escrow is created in the **Held** state. After the specified time has passed, it becomes **Ready** and anyone can finish it. If the escrow has an expiration time and no one finishes it before that time passes, then the escrow becomes **Expired**. In the expired state, an escrow cannot be finished, and anyone can cancel it.
- **Combination Escrow (center):** If the escrow specifies both a crypto-condition (`Condition` field) _and_ a "finish-after" time (`FinishAfter` field), the escrow is **Held** until its finish-after time has passed. Then it becomes **Conditionally Ready**, and can finish it if they supply the correct fulfillment to the crypto-condition. If the escrow has an expiration time (`CancelAfter` field), and no one finishes it before that time passes, then the escrow becomes **Expired**. In the expired state, an escrow cannot be finished, and anyone can cancel it.
- **Conditional Escrow (right):** If the escrow specifies a crypto-condition (`Condition` field) and not a finish-after time, the escrow becomes **Conditionally Ready** immediately when it is created. During this time, anyone can finish the escrow, but only if they supply the correct fulfillment to the crypto-condition. If no one finishes the escrow before its expiration time (`CancelAfter` field), the escrow becomes **Expired**. (An escrow without a finish-after time _must_ have an expiration time.) In the expired state, the escrow can no longer be finished, and anyone can cancel it.
## Availability of Escrow
Conditional payments have been enabled by the ["Escrow" Amendment](known-amendments.html#escrow) to the XRP Ledger Consensus Protocol since 2017-03-31. A previous version of the same functionality was available on the [Ripple Test Net](https://ripple.com/build/ripple-test-net/) by the name "Suspended Payments" (SusPay) in 2016.

BIN
img/escrow-states.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB