ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2026-08-23 11:10:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Ledger format: added Escrow node [WIP]

Browse Source
This commit is contained in:
mDuo13
2017-04-11 18:53:27 -07:00
parent 6ffc5e69ae
commit 41541ac9a4
2 changed files with 125 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
content/reference-ledger-format.md
View File

@@ -65,6 +65,7 @@ There are several different kinds of nodes that can appear in the ledger's state
* [**AccountRoot** - The settings, XRP balance, and other metadata for one account.](#accountroot)
* [**DirectoryNode** - Contains links to other nodes.](#directorynode)
* [**Escrow** - Contains XRP held for a conditional payment](#escrow)
* [**Offer** - An offer to exchange currencies, known in finance as an _order_.](#offer)
* [**PayChannel** - A channel for asynchronous XRP payments.](#paychannel)
* [**RippleState** - Links two accounts, tracking the balance of one currency between them. The concept of a _trust line_ is really an abstraction of this node type.](#ripplestate)
@@ -239,6 +240,41 @@ The lower 64 bits of an Offer Directory's index represent the TakerPays amount d
* The page number of this node. (Since 0 is the root DirectoryNode, this value is an integer 1 or higher.)
## Escrow
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/impl/LedgerFormats.cpp#L90-L101 "Source")
_(Requires the [Escrow Amendment](concept-amendments.html#paychan).)_
The `Escrow` node type represents a held payment of XRP waiting to be executed or canceled. An [EscrowCreate transaction](reference-transaction-format.html#escrowcreate) creates an Escrow node in the ledger. A successful [EscrowFinish](reference-transaction-format.html#escrowfinish) or [EscrowCancel](reference-transaction-format.html#escrowcancel) transaction deletes the node.
An Escrow node is associated with two addresses: the owner, who provides the XRP when creating the Escrow node; and the destination, where the XRP is paid when the held payment succeeds. If the held payment is canceled, the XRP returns to the owner. If the Escrow node has a _condition_ (a 256-bit hexadecimal value), the payment can only succeed if an EscrowFinish transaction provides the corresponding _fulfillment_ in the form of a 32-byte value whose SHA-256 hash matches the condition. (In other words, the fulfillment is the SHA-256 preimage of the condition.)
Example Escrow node:
```
TODO
```
An Escrow node has the following fields:
| Name | JSON Type | [Internal Type][] | Description |
|-------------------|-----------|---------------|-------------|
| Account | String | AccountID | The address of the owner (sender) of this held payment. This is the account that provided the XRP, and gets it back if the held payment is canceled. |
| Destination | String | AccountID | The destination address where the XRP is paid if the held payment is successful. |
| Amount | String | Amount | The amount of XRP, in drops, to be delivered by the held payment. |
| Condition | String | VariableLength | _(Optional)_ A SHA-256 hash, as a hexadecimal string. If present, the [EscrowFinish transaction][] must contain a fulfillment that hashes to this value. |
| CancelAfter | Number | UInt32 | _(Optional)_ The time, in [seconds since the Ripple epoch](reference-rippled.html#specifying-time), after which this held payment can only be canceled. (Specifically, this is compared with the close time of the previous validated ledger.) |
| FinishAfter | Number | UInt32 | _(Optional)_ The time, in [seconds since the Ripple epoch](reference-rippled.html#specifying-time), after which this held payment can be finished. Any [EscrowFinish transaction][] before this time fails. (Specifically, this is compared with the close time of the previous validated ledger.) |
| SourceTag | Number | UInt32 | _(Optional)_ An arbitrary tag to further specify the source for this held payment, such as a hosted recipient at the owner's address. |
| DestinationTag | Number | UInt32 | _(Optional)_ An arbitrary tag to further specify the destination for this held payment, such as a hosted recipient at the destination address. |
| OwnerNode | String | UInt64 | A hint indicating which page of the owner directory links to this node, in case the directory consists of multiple pages. **Note:** The node does not contain a direct link to the owner directory containing it, since that value can be derived from the `Account`. |
| PreviousTxnID | String | Hash256 | The identifying hash of the transaction that most recently modified this node. |
| PreviousTxnLgrSeq | Number | UInt32 | The [index of the ledger](#ledger-index) that contains the transaction that most recently modified this node. |
[EscrowFinish transaction]: reference-transaction-format.html#escrowfinish
## Offer ##
[[Source]<br>](https://github.com/ripple/rippled/blob/5d2d88209f1732a0f8d592012094e345cbe3e675/src/ripple/protocol/impl/LedgerFormats.cpp#L57 "Source")

89
reference-ledger-format.html
View File

@@ -145,6 +145,7 @@
<li class="level-3"><a href="#accountroot-index-format">AccountRoot Index Format</a></li>
<li class="level-2"><a href="#directorynode">DirectoryNode</a></li>
<li class="level-3"><a href="#directory-index-formats">Directory Index Formats</a></li>
<li class="level-2"><a href="#escrow">Escrow</a></li>
<li class="level-2"><a href="#offer">Offer</a></li>
<li class="level-3"><a href="#offer-flags">Offer Flags</a></li>
<li class="level-3"><a href="#offer-index-format">Offer Index Format</a></li>
@@ -272,6 +273,7 @@
<ul>
<li><a href="#accountroot"><strong>AccountRoot</strong> - The settings, XRP balance, and other metadata for one account.</a></li>
<li><a href="#directorynode"><strong>DirectoryNode</strong> - Contains links to other nodes.</a></li>
<li><a href="#escrow"><strong>Escrow</strong> - Contains XRP held for a conditional payment</a></li>
<li><a href="#offer"><strong>Offer</strong> - An offer to exchange currencies, known in finance as an <em>order</em>.</a></li>
<li><a href="#paychannel"><strong>PayChannel</strong> - A channel for asynchronous XRP payments.</a></li>
<li><a href="#ripplestate"><strong>RippleState</strong> - Links two accounts, tracking the balance of one currency between them. The concept of a <em>trust line</em> is really an abstraction of this node type.</a></li>
@@ -642,6 +644,93 @@
<li>The <code>index</code> of the root DirectoryNode</li>
<li>The page number of this node. (Since 0 is the root DirectoryNode, this value is an integer 1 or higher.)</li>
</ul>
<h2 id="escrow">Escrow</h2>
<p><a href="https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/impl/LedgerFormats.cpp#L90-L101" title="Source">[Source]<br/></a></p>
<p><em>(Requires the <a href="concept-amendments.html#paychan">Escrow Amendment</a>.)</em></p>
<p>The <code>Escrow</code> node type represents a held payment of XRP waiting to be executed or canceled. An <a href="reference-transaction-format.html#escrowcreate">EscrowCreate transaction</a> creates an Escrow node in the ledger. A successful <a href="reference-transaction-format.html#escrowfinish">EscrowFinish</a> or <a href="reference-transaction-format.html#escrowcancel">EscrowCancel</a> transaction deletes the node.</p>
<p>An Escrow node is associated with two addresses: the owner, who provides the XRP when creating the Escrow node; and the destination, where the XRP is paid when the held payment succeeds. If the held payment is canceled, the XRP returns to the owner. If the Escrow node has a <em>condition</em> (a 256-bit hexadecimal value), the payment can only succeed if an EscrowFinish transaction provides the corresponding <em>fulfillment</em> in the form of a 32-byte value whose SHA-256 hash matches the condition. (In other words, the fulfillment is the SHA-256 preimage of the condition.)</p>
<p>Example Escrow node:</p>
<pre><code>TODO
</code></pre>
<p>An Escrow node has the following fields:</p>
<table>
<thead>
<tr>
<th>Name</th>
<th>JSON Type</th>
<th><a href="https://github.com/ripple/rippled/blob/master/src/ripple/protocol/impl/SField.cpp">Internal Type</a></th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>Account</td>
<td>String</td>
<td>AccountID</td>
<td>The address of the owner (sender) of this held payment. This is the account that provided the XRP, and gets it back if the held payment is canceled.</td>
</tr>
<tr>
<td>Destination</td>
<td>String</td>
<td>AccountID</td>
<td>The destination address where the XRP is paid if the held payment is successful.</td>
</tr>
<tr>
<td>Amount</td>
<td>String</td>
<td>Amount</td>
<td>The amount of XRP, in drops, to be delivered by the held payment.</td>
</tr>
<tr>
<td>Condition</td>
<td>String</td>
<td>VariableLength</td>
<td><em>(Optional)</em> A SHA-256 hash, as a hexadecimal string. If present, the <a href="reference-transaction-format.html#escrowfinish">EscrowFinish transaction</a> must contain a fulfillment that hashes to this value.</td>
</tr>
<tr>
<td>CancelAfter</td>
<td>Number</td>
<td>UInt32</td>
<td><em>(Optional)</em> The time, in <a href="reference-rippled.html#specifying-time">seconds since the Ripple epoch</a>, after which this held payment can only be canceled. (Specifically, this is compared with the close time of the previous validated ledger.)</td>
</tr>
<tr>
<td>FinishAfter</td>
<td>Number</td>
<td>UInt32</td>
<td><em>(Optional)</em> The time, in <a href="reference-rippled.html#specifying-time">seconds since the Ripple epoch</a>, after which this held payment can be finished. Any <a href="reference-transaction-format.html#escrowfinish">EscrowFinish transaction</a> before this time fails. (Specifically, this is compared with the close time of the previous validated ledger.)</td>
</tr>
<tr>
<td>SourceTag</td>
<td>Number</td>
<td>UInt32</td>
<td><em>(Optional)</em> An arbitrary tag to further specify the source for this held payment, such as a hosted recipient at the owner's address.</td>
</tr>
<tr>
<td>DestinationTag</td>
<td>Number</td>
<td>UInt32</td>
<td><em>(Optional)</em> An arbitrary tag to further specify the destination for this held payment, such as a hosted recipient at the destination address.</td>
</tr>
<tr>
<td>OwnerNode</td>
<td>String</td>
<td>UInt64</td>
<td>A hint indicating which page of the owner directory links to this node, in case the directory consists of multiple pages. <strong>Note:</strong> The node does not contain a direct link to the owner directory containing it, since that value can be derived from the <code>Account</code>.</td>
</tr>
<tr>
<td>PreviousTxnID</td>
<td>String</td>
<td>Hash256</td>
<td>The identifying hash of the transaction that most recently modified this node.</td>
</tr>
<tr>
<td>PreviousTxnLgrSeq</td>
<td>Number</td>
<td>UInt32</td>
<td>The <a href="#ledger-index">index of the ledger</a> that contains the transaction that most recently modified this node.</td>
</tr>
</tbody>
</table>
<h2 id="offer">Offer</h2>
<p><a href="https://github.com/ripple/rippled/blob/5d2d88209f1732a0f8d592012094e345cbe3e675/src/ripple/protocol/impl/LedgerFormats.cpp#L57" title="Source">[Source]<br/></a></p>
<p>The <code>Offer</code> node type describes an offer to exchange currencies, more traditionally known as an <em>order</em>, in Ripple's distributed exchange. An <a href="reference-transaction-format.html#offercreate">OfferCreate transaction</a> only creates an Offer node in the ledger when the offer cannot be fully executed immediately by consuming other offers already in the ledger.</p>