From 41541ac9a4e3b9074a00e69dbb82f8ebc5ceef41 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Tue, 11 Apr 2017 18:53:27 -0700 Subject: [PATCH] Ledger format: added Escrow node [WIP] --- content/reference-ledger-format.md | 36 ++++++++++++ reference-ledger-format.html | 89 ++++++++++++++++++++++++++++++ 2 files changed, 125 insertions(+) diff --git a/content/reference-ledger-format.md b/content/reference-ledger-format.md index 9416440cf2..260c12b288 100644 --- a/content/reference-ledger-format.md +++ b/content/reference-ledger-format.md @@ -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]
](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]
](https://github.com/ripple/rippled/blob/5d2d88209f1732a0f8d592012094e345cbe3e675/src/ripple/protocol/impl/LedgerFormats.cpp#L57 "Source") diff --git a/reference-ledger-format.html b/reference-ledger-format.html index 30717f9a4c..a1633c1f83 100644 --- a/reference-ledger-format.html +++ b/reference-ledger-format.html @@ -145,6 +145,7 @@
  • AccountRoot Index Format
  • DirectoryNode
  • Directory Index Formats
    • +
  • Escrow
  • Offer
  • Offer Flags
  • Offer Index Format
    • @@ -272,6 +273,7 @@ +

    Escrow

    +

    [Source]

    +

    (Requires the Escrow Amendment.)

    +

    The Escrow node type represents a held payment of XRP waiting to be executed or canceled. An EscrowCreate transaction creates an Escrow node in the ledger. A successful EscrowFinish or 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:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameJSON TypeInternal TypeDescription
    AccountStringAccountIDThe 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.
    DestinationStringAccountIDThe destination address where the XRP is paid if the held payment is successful.
    AmountStringAmountThe amount of XRP, in drops, to be delivered by the held payment.
    ConditionStringVariableLength(Optional) A SHA-256 hash, as a hexadecimal string. If present, the EscrowFinish transaction must contain a fulfillment that hashes to this value.
    CancelAfterNumberUInt32(Optional) The time, in seconds since the Ripple epoch, after which this held payment can only be canceled. (Specifically, this is compared with the close time of the previous validated ledger.)
    FinishAfterNumberUInt32(Optional) The time, in seconds since the Ripple epoch, 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.)
    SourceTagNumberUInt32(Optional) An arbitrary tag to further specify the source for this held payment, such as a hosted recipient at the owner's address.
    DestinationTagNumberUInt32(Optional) An arbitrary tag to further specify the destination for this held payment, such as a hosted recipient at the destination address.
    OwnerNodeStringUInt64A 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.
    PreviousTxnIDStringHash256The identifying hash of the transaction that most recently modified this node.
    PreviousTxnLgrSeqNumberUInt32The index of the ledger that contains the transaction that most recently modified this node.

    Offer

    [Source]

    The Offer node type describes an offer to exchange currencies, more traditionally known as an order, in Ripple's distributed exchange. An OfferCreate transaction only creates an Offer node in the ledger when the offer cannot be fully executed immediately by consuming other offers already in the ledger.