ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-26 22:55:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'IA.v2' of github.com:XRPLF/xrpl-dev-portal into IA.v2

Browse Source 
Update for parity.
This commit is contained in:
ddawson
2022-12-01 14:41:14 -08:00
parent a48a0471b2 acbce49c0e
commit 00781cc3ec
5 changed files with 29 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
content/tutorials/use-specialized-payment-types/use-escrows/cancel-an-expired-escrow.md
View File

@@ -8,9 +8,11 @@ labels:
---
# Cancel an Expired Escrow
## 1. Confirm the expired escrow
An escrow in the XRP Ledger is expired when its `CancelAfter` time is lower than the `close_time` of the latest validated ledger. Escrows without a `CancelAfter` time never expire.
An escrow in the XRP Ledger is expired when its `CancelAfter` time is lower than the `close_time` of a validated ledger version. (If the escrow does not have a `CancelAfter` time, it never expires.) You can look up the close time of the latest validated ledger with the [ledger method][]:
## 1. Get the latest validated ledger
Use the [ledger method][] to look up the latest validated ledger and get the `close_time` value.
Request:
@@ -36,8 +38,10 @@ _Websocket_
<!-- MULTICODE_BLOCK_END -->
## 2. Look up the escrow
You can look up the escrow and compare to the `CancelAfter` time using the [account_objects method][]:
<!--> Note to Dennis: Maybe include the look up escrows info here and remove the corresponding page entirely? <-->
Use the [account_objects method][] and compare `CancelAfter` to `close_time`:
Request:
@@ -63,7 +67,7 @@ _Websocket_
<!-- MULTICODE_BLOCK_END -->
## 2. Submit EscrowCancel transaction
## 3. Submit EscrowCancel transaction
***Anyone*** can cancel an expired escrow in the XRP Ledger by [signing and submitting](transaction-basics.html#signing-and-submitting-transactions) an [EscrowCancel transaction][]. Set the `Owner` field of the transaction to the `Account` of the `EscrowCreate` transaction that created this escrow. Set the `OfferSequence` field to the `Sequence` of the `EscrowCreate` transaction.
@@ -95,13 +99,13 @@ _Websocket_
Take note of the transaction's identifying `hash` value so you can check its final status when it is included in a validated ledger version.
## 3. Wait for validation
## 4. Wait for validation
{% include '_snippets/wait-for-validation.md' %} <!--#{ fix md highlighting_ #}-->
## 4. Confirm final result
## 5. Confirm final result
Use the [tx method][] with the EscrowCancel transaction's identifying hash to check its final status. Look in the transaction metadata for a `DeletedNode` with `LedgerEntryType` of `Escrow`. Also look for a `ModifiedNode` of type `AccountRoot` for the sender of the escrowed payment. The `FinalFields` of the object should show the increase in XRP in the `Balance` field for the returned XRP.
Use the [tx method][] with the `EscrowCancel` transaction's identifying hash to check its final status. Look in the transaction metadata for a `DeletedNode` with `LedgerEntryType` of `Escrow`. Also look for a `ModifiedNode` of type `AccountRoot` for the sender of the escrowed payment. The `FinalFields` of the object should show the increase in XRP in the `Balance` field for the returned XRP.
Request:
@@ -129,7 +133,7 @@ _Websocket_
<!-- MULTICODE_BLOCK_END -->
In the above example, `r3wN3v2vTUkr5qd6daqDc2xE4LSysdVjkT` is the sender of the escrow, and the increase in `Balance` from 99999**8**9990 drops to 99999**9**9990 drops represents the return of the escrowed 10,000 drops of XRP (0.01 XRP).
***TODO: Figure out why EscrowFinish is mentioned here. I'm not seeing how it relates to canceling escrows.***
**Tip:** If you don't know what `OfferSequence` to use in the [EscrowFinish transaction][] to execute an escrow, use the [tx method][] to look up the transaction that created the escrow, using the identifying hash of the transaction in the Escrow's `PreviousTxnID` field. Use the `Sequence` value of that transaction as the `OfferSequence` value when finishing the escrow.

53
content/tutorials/use-specialized-payment-types/use-escrows/look-up-escrows.md
View File

@@ -6,54 +6,14 @@ labels:
- Escrow
- Smart Contracts
---
# Look up escrows
# Look up Escrows
All pending escrows are stored in the ledger as [Escrow objects](escrow.html).
You can look up escrow objects by the [sender's address](#look-up-escrows-by-sender-address) or the [destination address](#look-up-escrows-by-destination-address) using the [account_objects method][].
## Look up escrows by sender address
You can use the [account_objects method][] to look up escrow objects by sender address.
Let's say that you want to look up all pending escrow objects with a sender address of `rfztBskAVszuS3s5Kq7zDS74QtHrw893fm`. You can do this using the following example request, where the sender address is the `account` value.
Request:
<!-- MULTICODE_BLOCK_START -->
_Websocket_
```json
{% include '_code-samples/escrow/websocket/account_objects-request.json' %}
```
<!-- MULTICODE_BLOCK_END -->
The response resembles the following example. Note that the response includes all pending escrow objects with `rfztBskAVszuS3s5Kq7zDS74QtHrw893fm` as the sender or destination address, where the sender address is the `Account` value and the destination address is the `Destination` value.
In this example, the second and fourth escrow objects meet our lookup criteria because their `Account` (sender address) values are set to `rfztBskAVszuS3s5Kq7zDS74QtHrw893fm`.
Response:
<!-- MULTICODE_BLOCK_START -->
_Websocket_
```json
{% include '_code-samples/escrow/websocket/account_objects-response.json' %}
```
<!-- MULTICODE_BLOCK_END -->
## Look up escrows by destination address
You can use the [account_objects method][] to look up escrow objects by destination address.
All pending escrows are stored in the ledger as [Escrow objects](escrow.html), and you can look them up by the sender's address or the destination address.
<!--> Note to Dennis: Is anyone going to be looking up escrows created before 2017? Seems like an extremely niche case to be taking up page space. Remove this maybe? <-->
**Note:** You can only look up pending escrow objects by destination address if those escrows were created after the [fix1523 amendment][] was enabled on 2017-11-14.
Let's say that you want to look up all pending escrow objects with a destination address of `rfztBskAVszuS3s5Kq7zDS74QtHrw893fm`. You can do this using the following example request, where the destination address is the `account` value.
Use the [account_objects][] method, where the sender or destination address is the `account` value.
Request:
@@ -67,10 +27,7 @@ _Websocket_
<!-- MULTICODE_BLOCK_END -->
The response resembles the following example. Note that the response includes all pending escrow objects with `rfztBskAVszuS3s5Kq7zDS74QtHrw893fm` as the destination or sender address, where the destination address is the `Destination` value and the sender address is the `Account` value.
In this example, the first and third escrow objects meet our lookup criteria because their `Destination` (destination address) values are set to `rfztBskAVszuS3s5Kq7zDS74QtHrw893fm`.
The response includes all pending escrow objects with `rfztBskAVszuS3s5Kq7zDS74QtHrw893fm`, where the sender address is the `Account` value, or the destination address is the `Destination` value.
Response:

2
content/tutorials/use-specialized-payment-types/use-escrows/send-a-conditionally-held-escrow.md
View File

@@ -7,7 +7,7 @@ labels:
- Smart Contracts
---
# Send a Conditionally Held Escrow
<!--> Note to Dennis: This topic is very similar to the use an escrow as a smart contract tutorial. I think the 2 pages can be merged. <-->
## 1. Generate condition and fulfillment
XRP Ledger escrows require PREIMAGE-SHA-256 [crypto-conditions][]. To calculate a condition and fulfillment in the proper format, you should use a crypto-conditions library such as [five-bells-condition](https://github.com/interledgerjs/five-bells-condition). To generate the fulfillment:

22
content/tutorials/use-specialized-payment-types/use-escrows/send-a-time-held-escrow.md
View File

@@ -8,18 +8,20 @@ labels:
---
# Send a Time-Held Escrow
The [EscrowCreate transaction][] type can create an escrow whose only condition for release is that a specific time has passed. To do this, use the `FinishAfter` field and omit the `Condition` field.
You can configure an escrow to release funds after a specific time has passed.
## 1. Calculate release time
You must specify the time as whole **[seconds since the Ripple Epoch][]**, which is 946684800 seconds after the UNIX epoch. For example, to release funds at midnight UTC on November 13, 2017:
You must specify the release time as whole seconds since **[the Ripple Epoch][]**, which you can calculate using this formula:
(Release_Time = Date_in_Unix_Time - 946684800)
***TODO: Format this properly.***
<!-- MULTICODE_BLOCK_START -->
*JavaScript*
```js
// JavaScript Date() is natively expressed in milliseconds; convert to seconds
// JavaScript Date() is natively expressed in milliseconds; convert to seconds.
const release_date_unix = Math.floor( new Date("2017-11-13T00:00:00Z") / 1000 );
const release_date_ripple = release_date_unix - 946684800;
console.log(release_date_ripple);
@@ -41,11 +43,9 @@ print(release_date_ripple)
<!-- MULTICODE_BLOCK_END -->
**Warning:** If you use a UNIX time in the `FinishAfter` field without converting to the equivalent Ripple time first, that sets the unlock time to an extra **30 years** in the future!
## 2. Submit EscrowCreate transaction
[Sign and submit](transaction-basics.html#signing-and-submitting-transactions) an [EscrowCreate transaction][]. Set the `FinishAfter` field of the transaction to the time when the held payment should be released. Omit the `Condition` field to make time the only condition for releasing the held payment. Set the `Destination` to the recipient, which may be the same address as the sender. Set the `Amount` to the total amount of [XRP, in drops][], to escrow.
<!--> Note to Dennis: I'd like to remove most links taking people out of the tutorial. It breaks the flow of thought and, like you've said earlier, it forces them to think when we're supposed to be doing most of the heavy lifting here. However most of these steps are includes from other pages, so it'd requiring modifying those and I'm not sure how that will affect the other pages they're being referenced. <-->
[Sign and submit](transaction-basics.html#signing-and-submitting-transactions) an [EscrowCreate transaction][]. Set the `FinishAfter` field to the calcualted release time. Set the `Amount` to the total [XRP, in drops][], to escrow.
{% include '_snippets/secret-key-warning.md' %} <!--#{ fix md highlighting_ #}-->
@@ -110,7 +110,7 @@ Response:
## 5. Wait for the release time
Held payments with a `FinishAfter` time cannot be finished until a ledger has already closed with a [`close_time` header field](ledger-header.html) that is later than the Escrow node's `FinishAfter` time.
Held payments release when a ledger closes with a [`close_time` header field](ledger-header.html) that is later than the Escrow node's `FinishAfter` time.
You can check the close time of the most recently-validated ledger with the [ledger method][]:
@@ -141,11 +141,9 @@ Response:
## 6. Submit EscrowFinish transaction
[Sign and submit](transaction-basics.html#signing-and-submitting-transactions) an [EscrowFinish transaction][] to execute the release of the funds after the `FinishAfter` time has passed. Set the `Owner` field of the transaction to the `Account` address from the EscrowCreate transaction, and the `OfferSequence` to the `Sequence` number from the EscrowCreate transaction. For an escrow held only by time, omit the `Condition` and `Fulfillment` fields.
[Sign and submit](transaction-basics.html#signing-and-submitting-transactions) an [EscrowFinish transaction][] to execute the release of the funds. Set the `Owner` field of the transaction to the `Account` address from the EscrowCreate transaction, and the `OfferSequence` to the `Sequence` number from the `EscrowCreate` transaction. The sender of this transaction can be any XRP Ledger address.
**Tip:** The EscrowFinish transaction is necessary because the XRP Ledger's state can only be modified by transactions. The sender of this transaction may be the recipient of the escrow, the original sender of the escrow, or any other XRP Ledger address.
If the escrow has expired, you can only [cancel the escrow](cancel-an-expired-escrow.html) instead.
If the escrow expires, you can only [cancel the escrow](cancel-an-expired-escrow.html).
{% include '_snippets/secret-key-warning.md' %} <!--#{ fix md highlighting_ #}-->