mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-21 12:15:50 +00:00
Fix links in check, escrow tutorials etc.
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# RippleAPI Beginners Guide
|
||||
|
||||
This tutorial guides you through the basics of building an XRP Ledger-connected application using [Node.js](http://nodejs.org/) and [RippleAPI](reference-rippleapi.html), a JavaScript API for accessing the XRP Ledger.
|
||||
This tutorial guides you through the basics of building an XRP Ledger-connected application using [Node.js](http://nodejs.org/) and [RippleAPI](rippleapi-reference.html), a JavaScript API for accessing the XRP Ledger.
|
||||
|
||||
The scripts and configuration files used in this guide are [available in the Ripple Dev Portal GitHub Repository](https://github.com/ripple/ripple-dev-portal/tree/master/content/code_samples/rippleapi_quickstart).
|
||||
|
||||
@@ -131,10 +131,10 @@ const api = new RippleAPI({
|
||||
|
||||
This section creates a new instance of the RippleAPI class, assigning it to the variable `api`. (The [`const` keyword](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const) means you can't reassign the value `api` to some other value. The internal state of the object can still change, though.)
|
||||
|
||||
The one argument to the constructor is an options object, which has [a variety of options](reference-rippleapi.html#parameters). The `server` parameter tells it where it should connect to a `rippled` server.
|
||||
The one argument to the constructor is an options object, which has [a variety of options](rippleapi-reference.html#parameters). The `server` parameter tells it where it should connect to a `rippled` server.
|
||||
|
||||
* The example `server` setting uses a secure WebSocket connection to connect to one of the public servers that Ripple (the company) operates.
|
||||
* If you don't include the `server` option, RippleAPI runs in [offline mode](reference-rippleapi.html#offline-functionality) instead, which only provides methods that don't need network connectivity.
|
||||
* If you don't include the `server` option, RippleAPI runs in [offline mode](rippleapi-reference.html#offline-functionality) instead, which only provides methods that don't need network connectivity.
|
||||
* You can specify a [Ripple Test Net](https://ripple.com/build/ripple-test-net/) server instead to connect to the parallel-world Test Network instead of the production XRP Ledger.
|
||||
* If you [run your own `rippled`](install-rippled.html), you can instruct it to connect to your local server. For example, you might say `server: 'ws://localhost:5005'` instead.
|
||||
|
||||
@@ -144,7 +144,7 @@ The one argument to the constructor is an options object, which has [a variety o
|
||||
api.connect().then(() => {
|
||||
```
|
||||
|
||||
The [connect() method](reference-rippleapi.html#connect) is one of many RippleAPI methods that returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), which is a special kind of JavaScript object. A Promise is designed to do an asynchronous operation that returns a value later, such as querying the XRP Ledger.
|
||||
The [connect() method](rippleapi-reference.html#connect) is one of many RippleAPI methods that returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), which is a special kind of JavaScript object. A Promise is designed to do an asynchronous operation that returns a value later, such as querying the XRP Ledger.
|
||||
|
||||
When you get a Promise back from some expression (like `api.connect()`), you call the Promise's `then` method and pass in a callback function. Passing a function as an argument is conventional in JavaScript, taking advantage of how JavaScript functions are [first-class objects](https://en.wikipedia.org/wiki/First-class_function).
|
||||
|
||||
@@ -174,7 +174,7 @@ The example code looks up an XRP Ledger account by its address. Try running the
|
||||
|
||||
The `console.log()` function is built into both Node.js and web browsers, and writes out to the console. This example includes lots of console output to make it easier to understand what the code is doing.
|
||||
|
||||
Keep in mind that the example code starts in the middle of a callback function (called when RippleAPI finishes connecting). That function calls RippleAPI's [`getAccountInfo`](reference-rippleapi.html#getaccountinfo) method, and returns the results.
|
||||
Keep in mind that the example code starts in the middle of a callback function (called when RippleAPI finishes connecting). That function calls RippleAPI's [`getAccountInfo`](rippleapi-reference.html#getaccountinfo) method, and returns the results.
|
||||
|
||||
The `getAccountInfo` API method returns another Promise, so the line `}).then( info => {` defines another anonymous callback function to run when this Promise's asynchronous work is done. Unlike the previous case, this callback function takes one argument, called `info`, which holds the asynchronous return value from the `getAccountInfo` API method. The rest of this callback function outputs that return value to the console.
|
||||
|
||||
@@ -188,7 +188,7 @@ The `getAccountInfo` API method returns another Promise, so the line `}).then( i
|
||||
}).catch(console.error);
|
||||
```
|
||||
|
||||
The rest of the sample code is mostly more [boilerplate code](reference-rippleapi.html#boilerplate). The first line ends the previous callback function, then chains to another callback to run when it ends. That method disconnects cleanly from the XRP Ledger, and has yet another callback which writes to the console when it finishes. If your script waits on [RippleAPI events](reference-rippleapi.html#api-events), do not disconnect until you are done waiting for events.
|
||||
The rest of the sample code is mostly more [boilerplate code](rippleapi-reference.html#boilerplate). The first line ends the previous callback function, then chains to another callback to run when it ends. That method disconnects cleanly from the XRP Ledger, and has yet another callback which writes to the console when it finishes. If your script waits on [RippleAPI events](rippleapi-reference.html#api-events), do not disconnect until you are done waiting for events.
|
||||
|
||||
The `catch` method ends this Promise chain. The callback provided here runs if any of the Promises or their callback functions encounters an error. In this case, we pass the standard `console.error` function, which writes to the console, instead of defining a custom callback. You could define a smarter callback function here to intelligently catch certain error types.
|
||||
|
||||
|
||||
@@ -401,7 +401,7 @@ As discussed in step 2, transmitting your master private key is dangerous. It is
|
||||
|
||||
### Sign Your Transaction
|
||||
|
||||
The most secure way to sign a transaction is to do it offline with a signing library, such as [RippleAPI](reference-rippleapi.html#offline-functionality). Alternatively, you can sign the transaction using the [`sign`](reference-rippled.html#sign) command, but this must be done through a trusted and encrypted connection, or through a local connection, and only to a server you control.
|
||||
The most secure way to sign a transaction is to do it offline with a signing library, such as [RippleAPI](rippleapi-reference.html#offline-functionality). Alternatively, you can sign the transaction using the [`sign`](reference-rippled.html#sign) command, but this must be done through a trusted and encrypted connection, or through a local connection, and only to a server you control.
|
||||
|
||||
Populate the request fields with the following values:
|
||||
|
||||
@@ -664,7 +664,7 @@ An example of a successful response:
|
||||
Now that you're familiar with the benefits of assigning a regular key pair to an account, consider taking a look at these related topics and tutorials:
|
||||
|
||||
- [Change or Remove a Regular Key Pair](change-or-remove-a-regular-key-pair.html)
|
||||
- [How to Multi-Sign](tutorial-multisign.html)
|
||||
- [Set Up Multi-Signing](set-up-multi-signing.html)
|
||||
- [Issuing and Operational Addresses](issuing-and-operational-addresses.html)
|
||||
- [Listing XRP as an Exchange](tutorial-listing-xrp.html)
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ When removing a regular key pair to your account, the `SetRegularKey` transactio
|
||||
|
||||
### Sign Your Transaction
|
||||
|
||||
The most secure way to sign a transaction is to do it offline with a signing library, such as [RippleAPI](reference-rippleapi.html#offline-functionality). Alternatively, you can sign the transaction using the [`sign`](reference-rippled.html#sign) command, but this must be done through a trusted and encrypted connection, or through a local connection, and only to a server you control.
|
||||
The most secure way to sign a transaction is to do it offline with a signing library, such as [RippleAPI](rippleapi-reference.html#offline-functionality). Alternatively, you can sign the transaction using the [`sign`](reference-rippled.html#sign) command, but this must be done through a trusted and encrypted connection, or through a local connection, and only to a server you control.
|
||||
|
||||
Populate the request fields with the following values:
|
||||
|
||||
|
||||
@@ -30,7 +30,7 @@ Figure out the values of the [CheckCancel transaction][] fields. The following f
|
||||
| `Account` | String (Address) | The address of the sender who is canceling the Check. (In other words, your address.) |
|
||||
| `CheckID` | String | The ID of the Check object in the ledger to cancel. You can get this information by looking up the metadata of the CheckCreate transaction using the [tx method][] or by looking for Checks using the [account_objects method][]. |
|
||||
|
||||
If you are using [RippleAPI](reference-rippleapi.html), you can use the `prepareCheckCancel()` helper method.
|
||||
If you are using [RippleAPI](rippleapi-reference.html), you can use the `prepareCheckCancel()` helper method.
|
||||
|
||||
**Note:** RippleAPI supports Checks in versions 0.19.0 and up.
|
||||
|
||||
@@ -191,7 +191,7 @@ Look for a `DeletedNode` object in the transaction metadata with `"LedgerEntryTy
|
||||
<!-- MULTICODE_BLOCK_END -->
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
[RippleAPI]: rippleapi.html
|
||||
[RippleAPI]: rippleapi-reference.html
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
|
||||
@@ -6,7 +6,7 @@ As long as the Check is in the ledger and not expired, the specified recipient c
|
||||
|
||||
You might cash a Check for a flexible amount if you just want to get as much as possible from the Check.
|
||||
|
||||
The specified recipient can also [cash the check for an exact amount](tutorial-checks-cash-flex.html).
|
||||
The specified recipient can also [cash the check for an exact amount](cash-a-check-for-a-flexible-amount.html).
|
||||
|
||||
{% set cash_flex_n = cycler(* range(1,99)) %}
|
||||
|
||||
@@ -146,7 +146,7 @@ Use the [tx method][] with the CheckCash transaction's identifying hash to check
|
||||
|
||||
### Handling Errors
|
||||
|
||||
If cashing the Check failed with a `tec`-class code, look up the code in the [Full Transaction Response List](reference-transaction-format.html#full-transaction-response-list) and respond accordingly. Some common possibilities for CheckCash transactions:
|
||||
If cashing the Check failed with a `tec`-class code, look up the code in the [Full Transaction Response List](transaction-results.html) and respond accordingly. Some common possibilities for CheckCash transactions:
|
||||
|
||||
| Result Code | Meaning | How to Respond |
|
||||
|-------------|---------|----------------|
|
||||
@@ -204,6 +204,6 @@ If the Check was cashed for a flexible `DeliverMin` amount and succeeded, you ca
|
||||
- If the issued currency has a [transfer fee](transfer-fees.html), the Check's sender may be debited more than the recipient is credited. (The difference is the transfer fee, which is returned to the issuer as a decreased net obligation.)
|
||||
|
||||
<!--{# common links #}-->
|
||||
[RippleAPI]: reference-rippleapi.html
|
||||
[RippleAPI]: rippleapi-reference.html
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
|
||||
@@ -4,7 +4,7 @@ _Requires the [Checks Amendment](known-amendments.html#checks)._
|
||||
|
||||
As long as the Check is in the ledger and not expired, the specified recipient can cash it to receive any exact amount up to the amount specified in the Check by sending a [CheckCash transaction][] with an `Amount` field. You would cash a Check this way if you want to receive a specific amount, for example to pay off an invoice or bill exactly.
|
||||
|
||||
The specified recipient can also [cash the check for a flexible amount](tutorial-checks-cash-flex.html).
|
||||
The specified recipient can also [cash the check for a flexible amount](cash-a-check-for-a-flexible-amount.html).
|
||||
|
||||
{% set cash_exact_n = cycler(* range(1,99)) %}
|
||||
|
||||
@@ -120,7 +120,7 @@ Use the [tx method][] with the CheckCash transaction's identifying hash to check
|
||||
|
||||
If the check was cashed for an exact `Amount` and succeeded, you can assume that the recipient was credited for exactly that amount (with possible rounding for very large or very small amounts of issued currencies).
|
||||
|
||||
If cashing the Check failed, the Check remains in the ledger so you can try cashing again later. You may want to [cash the Check for a flexible amount](tutorial-checks-cash-flex.html) instead.
|
||||
If cashing the Check failed, the Check remains in the ledger so you can try cashing again later. You may want to [cash the Check for a flexible amount](cash-a-check-for-a-flexible-amount.html) instead.
|
||||
|
||||
### Example Request
|
||||
|
||||
@@ -148,6 +148,6 @@ If cashing the Check failed, the Check remains in the ledger so you can try cash
|
||||
<!-- MULTICODE_BLOCK_END -->
|
||||
|
||||
<!--{# common links #}-->
|
||||
[RippleAPI]: reference-rippleapi.html
|
||||
[RippleAPI]: rippleapi-reference.html
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
_Requires the [Checks Amendment](known-amendments.html#checks)._
|
||||
|
||||
This tutorial shows how to look up [Checks](checks.html) by their recipient. You may also want to [look up Checks by sender](tutorial-checks-lookup-by-sender.html).
|
||||
This tutorial shows how to look up [Checks](checks.html) by their recipient. You may also want to [look up Checks by sender](look-up-checks-by-sender.html).
|
||||
|
||||
## 1. Look up all Checks for the address
|
||||
|
||||
@@ -74,6 +74,6 @@ for (i=0; i < account_objects_response.account_objects.length; i++) {
|
||||
```
|
||||
|
||||
<!--{# common links #}-->
|
||||
[RippleAPI]: reference-rippleapi.html
|
||||
[RippleAPI]: rippleapi-reference.html
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
|
||||
@@ -75,6 +75,6 @@ for (i=0; i < account_objects_response.account_objects.length; i++) {
|
||||
```
|
||||
|
||||
<!--{# common links #}-->
|
||||
[RippleAPI]: reference-rippleapi.html
|
||||
[RippleAPI]: rippleapi-reference.html
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
|
||||
@@ -34,7 +34,7 @@ Decide how much money the Check is for and who can cash it. Figure out the value
|
||||
| `Destination` | String (Address) | The address of the intended recipient who can cash the Check. |
|
||||
| `SendMax` | String or Object (Amount) | The maximum amount the sender can be debited when this Check gets cashed. For XRP, use a string representing drops of XRP. For issued currencies, use an object with `currency`, `issuer`, and `value` fields. See [Specifying Currency Amounts][] for details. If you want the recipient to be able to cash the Check for an exact amount of a non-XRP currency with a [transfer fee](transfer-fees.html), remember to include an extra percentage to pay for the transfer fee. (For example, for the recipient to cash a Check for 100 CAD from an issuer with a 2% transfer fee, you must set the `SendMax` to 102 CAD from that issuer.) |
|
||||
|
||||
If you are using [RippleAPI](reference-rippleapi.html), you can use the `prepareCheckCreate()` helper method.
|
||||
If you are using [RippleAPI](rippleapi-reference.html), you can use the `prepareCheckCreate()` helper method.
|
||||
|
||||
**Note:** RippleAPI supports Checks in versions 0.19.0 and up.
|
||||
|
||||
@@ -234,7 +234,7 @@ Look for a `CreatedNode` object in the transaction metadata to indicate that the
|
||||
<!-- MULTICODE_BLOCK_END -->
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
[RippleAPI]: reference-rippleapi.html
|
||||
[RippleAPI]: rippleapi-reference.html
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
|
||||
@@ -2,4 +2,4 @@
|
||||
|
||||
Checks in the XRP Ledger authorize another account to claim funds later, similar to how personal paper checks work.
|
||||
|
||||
**Caution:** As of 2018-05-03, the [Checks amendment](known-amendments.html#checks) is not enabled on the XRP Ledger. You can use Checks on the [XRP Test Net](TODO:link) only.
|
||||
**Caution:** As of 2018-05-11, the [Checks amendment](known-amendments.html#checks) is not enabled on the XRP Ledger. You can use Checks on the [XRP Test Net](xrp-test-net-faucet.html) only.
|
||||
|
||||
@@ -2,11 +2,11 @@
|
||||
|
||||
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`](reference-rippled.html#account-objects) method.
|
||||
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`](reference-rippled.html#account-objects) method to look up escrow objects 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.
|
||||
|
||||
@@ -41,7 +41,7 @@ _Websocket_
|
||||
|
||||
## Look up escrows by destination address
|
||||
|
||||
You can use the [`account_objects`](reference-rippled.html#account-objects) method to look up escrow objects by destination address.
|
||||
You can use the [account_objects method][] to look up escrow objects by destination address.
|
||||
|
||||
**Note:** You can only look up pending escrow objects by destination address if those escrows were created after the [fix1523 amendment](known-amendments.html#fix1523) was enabled on 2017-11-14.
|
||||
|
||||
|
||||
@@ -126,7 +126,7 @@ Response:
|
||||
|
||||
**Note:** If you included a `FinishAfter` field in the EscrowCreate transaction, you cannot execute it before that time has passed, even if you provide the correct fulfillment for the Escrow's condition. The EscrowFinish transaction fails with the [result code](reference-transaction-format.html#transaction-results) `tecNO_PERMISSION` if the previously-closed ledger's close time is before the `FinishAfter` time.
|
||||
|
||||
If the escrow has expired, you can only [cancel the escrow](#cancel-an-expired-escrow) instead.
|
||||
If the escrow has expired, you can only [cancel the escrow](cancel-an-expired-escrow.html) instead.
|
||||
|
||||
{% include '_snippets/secret-key-warning.md' %} <!--#{ fix md highlighting_ #}-->
|
||||
|
||||
|
||||
@@ -102,7 +102,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](reference-ledger-format.html#header-format) that is later than the Escrow node's `FinishAfter` 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.
|
||||
|
||||
You can check the close time of the most recently-validated ledger with the [ledger method][]:
|
||||
|
||||
@@ -137,7 +137,7 @@ Response:
|
||||
|
||||
**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) instead.
|
||||
If the escrow has expired, you can only [cancel the escrow](cancel-an-expired-escrow.html) instead.
|
||||
|
||||
{% include '_snippets/secret-key-warning.md' %} <!--#{ fix md highlighting_ #}-->
|
||||
|
||||
|
||||
@@ -153,7 +153,7 @@ Response:
|
||||
In the response from the JSON-RPC, the payer should look for the following:
|
||||
|
||||
- In the transaction's `meta` field, confirm that the `TransactionResult` is `tesSUCCESS`.
|
||||
- Confirm that the response has `"validated":true` to indicate the data comes from a validated ledger. (The result `tesSUCCESS` is only [final](reference-transaction-format.html#finality-of-results) if it appears in a validated ledger version.)
|
||||
- Confirm that the response has `"validated":true` to indicate the data comes from a validated ledger. (The result `tesSUCCESS` is only [final](finality-of-results.html) if it appears in a validated ledger version.)
|
||||
- In the `AffectedNodes` array of the transaction's `meta` field, look for a `CreatedNode` object with the `LedgerEntryType` of `PayChannel`. The `LedgerIndex` field of the `CreatedNode` object indicates the Channel ID. (In the above example, this is a hex string starting with "5DB0...") The Channel ID is necessary later to sign claims.
|
||||
For more information on the PayChannel ledger object type, see [PayChannel ledger object](paychannel.html).
|
||||
|
||||
|
||||
@@ -2,10 +2,15 @@
|
||||
|
||||
An important and intentional feature of the XRP Ledger is that a transaction is final as soon as it has been incorporated in a validated ledger.
|
||||
|
||||
However, if a transaction has not yet been included in a validated ledger, you can effectively cancel it by rendering it invalid. Typically, this means sending another transaction with the same `Sequence` value from the same account. If you do not want the replacement transaction to do anything, send an [AccountSet](#accountset) transaction with no options.
|
||||
However, if a transaction has not yet been included in a validated ledger, you can effectively cancel it by rendering it invalid. Typically, this means sending another transaction with the same `Sequence` value from the same account. If you do not want the replacement transaction to do anything, send an [AccountSet transaction][] with no options.
|
||||
|
||||
For example, if you try to submit 3 transactions with sequence numbers 11, 12, and 13, but transaction 11 gets lost somehow or does not have a high enough [transaction cost](#transaction-cost) to be propagated to the network, then you can cancel transaction 11 by submitting an AccountSet transaction with no options and sequence number 11. This does nothing (except destroying the transaction cost for the new transaction 11), but it allows transactions 12 and 13 to become valid.
|
||||
For example, if you try to submit 3 transactions with sequence numbers 11, 12, and 13, but transaction 11 gets lost somehow or does not have a high enough [transaction cost](transaction-cost.html) to be propagated to the network, then you can cancel transaction 11 by submitting an AccountSet transaction with no options and sequence number 11. This does nothing (except destroying the transaction cost for the new transaction 11), but it allows transactions 12 and 13 to become valid.
|
||||
|
||||
This approach is preferable to renumbering and resubmitting transactions 12 and 13, because it prevents transactions from being effectively duplicated under different sequence numbers.
|
||||
|
||||
In this way, an AccountSet transaction with no options is the canonical "[no-op](http://en.wikipedia.org/wiki/NOP)" transaction.
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
|
||||
@@ -28,7 +28,7 @@ If a power or network outage occurs, applications face more challenges finding t
|
||||
|
||||
### Transaction Timeline
|
||||
|
||||
The XRP Ledger provides several APIs for submitting transactions, including [`rippled`](reference-rippled.html), and [RippleAPI](reference-rippleapi.html). Regardless of the API used, the transaction is applied to the ledger as follows.
|
||||
The XRP Ledger provides several APIs for submitting transactions, including [`rippled`](reference-rippled.html), and [RippleAPI](rippleapi-reference.html). Regardless of the API used, the transaction is applied to the ledger as follows.
|
||||
|
||||
1. An account owner creates and signs a transaction.
|
||||
2. The owner submits the transaction to the network as a candidate transaction.
|
||||
@@ -60,7 +60,7 @@ Use the `LastLedgerSequence` parameter to prevent undesirable cases where a tran
|
||||
|
||||
Applications using `rippled` APIs should explicitly specify a `LastLedgerSequence` when submitting transactions.
|
||||
|
||||
RippleAPI uses the `maxLedgerVersion` field of [Transaction Instructions](reference-rippleapi.html#transaction-instructions) to specify the `LastLedgerSequence`. RippleAPI automatically provides an appropriate value by default. You can specify `maxLedgerVersion` as `null` to intentionally omit `LastLedgerSequence`, in case you want a transaction that can be executed after an unlimited amount of time (this is strongly discouraged).
|
||||
RippleAPI uses the `maxLedgerVersion` field of [Transaction Instructions](rippleapi-reference.html#transaction-instructions) to specify the `LastLedgerSequence`. RippleAPI automatically provides an appropriate value by default. You can specify `maxLedgerVersion` as `null` to intentionally omit `LastLedgerSequence`, in case you want a transaction that can be executed after an unlimited amount of time (this is strongly discouraged).
|
||||
|
||||
|
||||
|
||||
@@ -168,7 +168,7 @@ To implement the transaction submission and verification best practices, applica
|
||||
How the application does these actions depends on the API the application uses. An application may use any of the following interfaces:
|
||||
|
||||
1. [`rippled`'s internal APIs](reference-rippled.html)
|
||||
2. [RippleAPI](reference-rippleapi.html)
|
||||
2. [RippleAPI](rippleapi-reference.html)
|
||||
3. Any number of other software APIs layered on top of `rippled`
|
||||
|
||||
|
||||
|
||||
@@ -48,7 +48,7 @@ The XRP Ledger contains a currency exchange, where any user can place and fulfil
|
||||
|
||||
Currency traders who hold a gateway's issuances can provide liquidity to other popular currencies, without the gateway needing to float a large reserve in various destination currencies. The gateway also does not need to take on the risk of financial exchange. However, a gateway may still want to provide liquidity to XRP or other popular currencies at a baseline rate, especially when the gateway is new to the exchange. If you do provide liquidity, use a different address for trading than your issuing address.
|
||||
|
||||
Third-party liquidity providers can use the [`rippled` APIs](reference-rippled.html), [RippleAPI JavaScript Library](reference-rippleapi.html), or a third-party client application to access the distributed exchange. Some client applications look up the addresses associated with a gateway using [ripple.txt](#rippletxt), so it can be helpful to publish a good ripple.txt.
|
||||
Third-party liquidity providers can use the [`rippled` APIs](reference-rippled.html), [RippleAPI JavaScript Library](rippleapi-reference.html), or a third-party client application to access the distributed exchange. Some client applications look up the addresses associated with a gateway using [ripple.txt](#rippletxt), so it can be helpful to publish a good ripple.txt.
|
||||
|
||||
Contact [partners@ripple.com](mailto:partners@ripple.com) for help establishing liquidity between your gateway and others.
|
||||
|
||||
@@ -282,7 +282,7 @@ Processing payments to and from the XRP Ledger naturally comes with some risks,
|
||||
- Before sending a payment into the XRP Ledger, double check the cost of the payment. A payment from your operational address to a customer should not cost more than the destination amount plus any [transfer fee](#transferrate) you have set.
|
||||
- Before processing a payment out of Ripple, make sure you know the customer's identity. This makes it harder for anonymous attackers to scam you. Most anti-money-laundering regulations require this anyway. This is especially important because the users sending money from the XRP Ledger could be different than the ones that initially received the money in the XRP Ledger.
|
||||
- Follow the guidelines for [reliable transaction submission](#reliable-transaction-submission) when sending XRP Ledger transactions.
|
||||
- [Robustly monitor for incoming payments](#robustly-monitoring-for-payments), and read the correct amount. Don't mistakenly credit someone the full amount if they only sent a [partial payment](reference-transaction-format.html#partial-payments).
|
||||
- [Robustly monitor for incoming payments](#robustly-monitoring-for-payments), and read the correct amount. Don't mistakenly credit someone the full amount if they only sent a [partial payment](partial-payments.html).
|
||||
- Track your obligations and balances within the XRP Ledger, and compare with the assets in your collateral account. If they do not match up, stop processing withdrawals and deposits until you resolve the discrepancy.
|
||||
- Avoid ambiguous situations. We recommend the following:
|
||||
- Enable the [`DisallowXRP` flag](#disallowxrp) for the issuing address and all operational addresses, so customers do not accidentally send you XRP. (Private exchanges should *not* set this flag, since they trade XRP normally.)
|
||||
@@ -375,14 +375,14 @@ Contact [partners@ripple.com](mailto:partners@ripple.com) to see how Ripple can
|
||||
There are several interfaces you can use to connect to the XRP Ledger, depending on your needs and your existing software:
|
||||
|
||||
* [`rippled`](reference-rippled.html) provides JSON-RPC and WebSocket APIs that can be used as a low-level interface to all core XRP Ledger functionality.
|
||||
* [RippleAPI](reference-rippleapi.html) provides a simplified API for JavaScript applications.
|
||||
* [RippleAPI](rippleapi-reference.html) provides a simplified API for JavaScript applications.
|
||||
|
||||
|
||||
## Tool Security
|
||||
|
||||
Any time you submit an XRP Ledger transaction, it must be signed using your secret key. The secret key gives full control over your XRP Ledger address. **Never** send your secret key to a server operated by someone else. Either use your own `rippled` server, or sign the transactions locally before sending them to a `rippled` server.
|
||||
|
||||
The examples in this document show API methods that include a secret key. This is only safe if you control `rippled` server yourself, *and* you connect to it over a connection that is secure from outside listeners. (For example, you could connect over a loopback (localhost) network, a private subnet, or an encrypted VPN.) Alternatively, you could use [RippleAPI](reference-rippleapi.html) to sign transactions locally before submitting them to a third-party server.
|
||||
The examples in this document show API methods that include a secret key. This is only safe if you control `rippled` server yourself, *and* you connect to it over a connection that is secure from outside listeners. (For example, you could connect over a loopback (localhost) network, a private subnet, or an encrypted VPN.) Alternatively, you could use [RippleAPI](rippleapi-reference.html) to sign transactions locally before submitting them to a third-party server.
|
||||
|
||||
|
||||
## DefaultRipple
|
||||
@@ -654,7 +654,7 @@ To make things simpler for your customers, we recommend accepting payments to ei
|
||||
|
||||
As an added precaution, we recommend comparing the balances of your issuing address with the collateral funds in your internal accounting system as of each new XRP Ledger ledger version. The issuing address's negative balances should match the assets you have allocated to XRP Ledger outside the network. If the two do not match up, then you should suspend processing payments into and out of the XRP Ledger until you have resolved the discrepancy.
|
||||
|
||||
* Use [`rippled`'s `gateway_balances` command](reference-rippled.html#gateway-balances) or [RippleAPI's `getTrustlines` method](reference-rippleapi.html#gettrustlines) to check your balances.
|
||||
* Use [`rippled`'s `gateway_balances` command](reference-rippled.html#gateway-balances) or [RippleAPI's `getTrustlines` method](rippleapi-reference.html#gettrustlines) to check your balances.
|
||||
* If you have a [TransferRate](#transferrate) set, then your obligations within the XRP Ledger decrease slightly whenever other XRP Ledger addresses transfer your issuances among themselves.
|
||||
|
||||
|
||||
@@ -714,7 +714,7 @@ Response:
|
||||
|
||||
All XRP Ledger addresses, including operational and standby addresses, are subject to the transfer fee. If you set a nonzero transfer fee, then you must send extra (to pay the TransferRate) when making payments from your operational address or standby address. In other words, your addresses must pay back a little of the balance your issuing address created, each time you make a payment.
|
||||
|
||||
* In `rippled`'s APIs, you should set the [`SendMax` transaction parameter](reference-transaction-format.html#payment) higher than the destination `Amount` parameter.
|
||||
* In `rippled`'s APIs, you should set the [`SendMax` transaction parameter][Payment] higher than the destination `Amount` parameter.
|
||||
* In RippleAPI, you should set the `source.maxAmount` parameter higher than the `destination.amount` parameter; or, set the `source.amount` parameter higher than the `destination.minAmount` parameter.
|
||||
|
||||
**Note:** The TransferRate does not apply when sending issuances directly to the issuing address. The issuing address must always accept its issuances at face value in the XRP Ledger. This means that customers don't have to pay the TransferRate if they send payments to the issuing address directly, but they do when sending to an operational address. If you accept payments at both addresses, you may want to adjust the amount you credit customers in your system of record when customers send payments to the operational address, to compensate for the TransferRate the customer pays.
|
||||
@@ -794,7 +794,7 @@ Response:
|
||||
}
|
||||
```
|
||||
|
||||
In particular, note the following features of the [Payment Transaction](reference-transaction-format.html#payment):
|
||||
In particular, note the following features of the [Payment transaction][]:
|
||||
|
||||
- No `Paths` field. The payment only succeeds if it can use a [default path](paths.html#default-paths), which is preferable. Using less direct paths can become much more expensive.
|
||||
- The `issuer` of both the `SendMax` and the `Amount` is the issuing address. This ensures that the transaction sends and delivers issuances from the issuing address, and not from some other gateway.
|
||||
@@ -809,8 +809,8 @@ The first requirement to bouncing payments is [robustly monitoring for incoming
|
||||
|
||||
Second, you should send bounced payments as Partial Payments. Since third parties can manipulate the cost of pathways between addresses, Partial Payments allow you to divest yourself of the full amount without being concerned about exchange rates within the XRP Ledger. You should publicize your bounced payments policy as part of your terms of use. Send the bounced payment from either an operational address or a standby address.
|
||||
|
||||
* To send a Partial Payment using `rippled`, enable the [tfPartialPayment flag](reference-transaction-format.html#payment-flags) on the transaction. Set the `Amount` field to the amount you received and omit the `SendMax` field.
|
||||
* To send a Partial Payment using RippleAPI, set the `allowPartialPayment` field of the [Payment object](reference-rippleapi.html#payment) to `true`. Set the `source.maxAmount` and `destination.amount` both equal to the amount you received.
|
||||
* To send a Partial Payment using `rippled`, enable the [tfPartialPayment flag](payment.html#payment-flags) on the transaction. Set the `Amount` field to the amount you received and omit the `SendMax` field.
|
||||
* To send a Partial Payment using RippleAPI, set the `allowPartialPayment` field of the [Payment object](rippleapi-reference.html#payment) to `true`. Set the `source.maxAmount` and `destination.amount` both equal to the amount you received.
|
||||
|
||||
You should use the `SourceTag` value (`source.tag` in RippleAPI) from the incoming payment as the `DestinationTag` value (`destination.tag` in RippleAPI) for the return payment.
|
||||
|
||||
|
||||
@@ -34,21 +34,21 @@ To support XRP, Alpha Exchange must:
|
||||
|
||||
See also:
|
||||
|
||||
* [Gateway Compliance](tutorial-gateway-guide.html#gateway-compliance) — Gateways and exchanges are different, but exchanges should also ensure that they are complying with local regulations and reporting to the appropriate agencies.
|
||||
* [Gateway Compliance](become-an-xrp-ledger-gateway.html#gateway-compliance) — Gateways and exchanges are different, but exchanges should also ensure that they are complying with local regulations and reporting to the appropriate agencies.
|
||||
|
||||
* [Requirements for Sending to XRP Ledger](tutorial-gateway-guide.html#requirements-for-sending-to-xrp-ledger)
|
||||
* [Requirements for Sending to XRP Ledger](become-an-xrp-ledger-gateway.html#requirements-for-sending-to-xrp-ledger)
|
||||
|
||||
* [Requirements for Receiving from XRP Ledger](tutorial-gateway-guide.html#requirements-for-receiving-from-xrp-ledger)
|
||||
* [Requirements for Receiving from XRP Ledger](become-an-xrp-ledger-gateway.html#requirements-for-receiving-from-xrp-ledger)
|
||||
|
||||
* [Gateway Precautions](tutorial-gateway-guide.html#precautions)
|
||||
* [Gateway Precautions](become-an-xrp-ledger-gateway.html#precautions)
|
||||
|
||||
### Partial Payments
|
||||
|
||||
Before integrating, exchanges should be aware of the [partial payments](reference-transaction-format.html#partial-payments) feature. This feature allows XRP Ledger users to send successful payments that reduce the amount received instead of increasing the `SendMax`. This feature can be useful for [returning payments](tutorial-gateway-guide.html#bouncing-payments) without incurring additional cost as the sender.
|
||||
Before integrating, exchanges should be aware of the [partial payments](partial-payments.html) feature. This feature allows XRP Ledger users to send successful payments that reduce the amount received instead of increasing the `SendMax`. This feature can be useful for [returning payments](become-an-xrp-ledger-gateway.html#bouncing-payments) without incurring additional cost as the sender.
|
||||
|
||||
#### Partial Payments Warning
|
||||
|
||||
When the [tfPartialPayment flag](reference-transaction-format.html#payment-flags) is enabled, the `Amount` field **_is not guaranteed to be the amount received_**. The `delivered_amount` field of a payment's metadata indicates the amount of currency actually received by the destination account. When receiving a payment, use `delivered_amount` instead of the Amount field to determine how much your account received instead.
|
||||
When the [tfPartialPayment flag](payment.html#payment-flags) is enabled, the `Amount` field **_is not guaranteed to be the amount received_**. The `delivered_amount` field of a payment's metadata indicates the amount of currency actually received by the destination account. When receiving a payment, use `delivered_amount` instead of the Amount field to determine how much your account received instead.
|
||||
|
||||
**Warning:** Be aware that malicious actors could exploit this. For more information, see [Partial Payments](partial-payments.html).
|
||||
|
||||
@@ -80,18 +80,18 @@ To follow Ripple's recommended best practices, Alpha Exchange should create at l
|
||||
|
||||
For more information about the possible consequences of a compromised hot wallet, see [Operational Account Compromise](issuing-and-operational-addresses.html#operational-address-compromise).
|
||||
|
||||
* Optionally, one or more warm wallets to provide an additional layer of security between the cold and hot wallets. Unlike a hot wallet, the secret key of a warm wallet does not need to be online. Additionally, you can distribute the secret keys for the warm wallet to several different people and implement [multisigning](tutorial-multisign.html) to increase security.
|
||||
* Optionally, one or more warm wallets to provide an additional layer of security between the cold and hot wallets. Unlike a hot wallet, the secret key of a warm wallet does not need to be online. Additionally, you can distribute the secret keys for the warm wallet to several different people and implement [multi-signing](multi-signing.html) to increase security.
|
||||
|
||||
For more information about the possible consequences of a compromised warm wallet, see [Standby Account Compromise](issuing-and-operational-addresses.html#standby-address-compromise).
|
||||
|
||||
|
||||
See also:
|
||||
|
||||
* ["Suggested Business Practices" in the _Gateway Guide_](tutorial-gateway-guide.html#suggested-business-practices)
|
||||
* ["Suggested Business Practices" in the _Gateway Guide_](become-an-xrp-ledger-gateway.html#suggested-business-practices)
|
||||
|
||||
* [Issuing and Operational Addresses](issuing-and-operational-addresses.html)
|
||||
|
||||
* [Creating Accounts](reference-transaction-format.html#creating-accounts)
|
||||
* [Creating Accounts](accounts.html#creating-accounts)
|
||||
|
||||
* [Reserves](reserves.html)
|
||||
|
||||
@@ -193,7 +193,7 @@ For more information, see [Specifying Currency Amounts][].
|
||||
|
||||
With exchanges like _Alpha Exchange_, XRP can be "on-ledger" or "off-ledger":
|
||||
|
||||
* **On-Ledger XRP**: XRP that can be queried through the public XRP Ledger by specifying the public [address](accounts.html#addresses) of the XRP holder. The counterparty to these balances is the XRP Ledger. For more information, see [Currencies](reference-rippled.html#currencies).
|
||||
* **On-Ledger XRP**: XRP that can be queried through the public XRP Ledger by specifying the public [address](accounts.html#addresses) of the XRP holder. The counterparty to these balances is the XRP Ledger. For more information, see [XRP](xrp.html).
|
||||
|
||||
* **Off-Ledger XRP**: XRP that is held by the accounting system of an exchange and can be queried through the exchange interface. Off-ledger XRP balances are credit-based. The counterparty is the exchange holding the XRP.
|
||||
|
||||
@@ -304,9 +304,9 @@ To track [off-ledger XRP balances](#on-ledger-and-off-ledger), exchanges need to
|
||||
|
||||
A user named Charlie wants to deposit 50,000 XRP to Alpha Exchange. Doing this involves the following steps:
|
||||
|
||||
1. Charlie submits a payment of 50,000 XRP (by using [RippleAPI](reference-rippleapi.html) or similar software) to Alpha Exchange's [cold wallet](#accounts).
|
||||
1. Charlie submits a payment of 50,000 XRP (by using [RippleAPI](rippleapi-reference.html) or similar software) to Alpha Exchange's [cold wallet](#accounts).
|
||||
|
||||
a. Charlie adds an identifier (in this case, `789`) to the payment to associate it with his account at Alpha Exchange. This is called a [_destination tag_](tutorial-gateway-guide.html#source-and-destination-tags). (To use this, Alpha Exchange should have set the asfRequireDest flag on all of its accounts to require all incoming payments to have a destination tag like Charlie's. For more information, see [AccountSet Flags](reference-transaction-format.html#accountset-flags)).
|
||||
a. Charlie adds an identifier (in this case, `789`) to the payment to associate it with his account at Alpha Exchange. This is called a [_destination tag_](become-an-xrp-ledger-gateway.html#source-and-destination-tags). (To use this, Alpha Exchange should have set the asfRequireDest flag on all of its accounts to require all incoming payments to have a destination tag like Charlie's. For more information, see [AccountSet Flags](reference-transaction-format.html#accountset-flags)).
|
||||
|
||||
2. The software at Alpha Exchange detects the incoming payment, and recognizes `789` as the destination tag for Charlie’s account.
|
||||
|
||||
@@ -407,14 +407,14 @@ XRP Balances</i></b></td>
|
||||
|
||||
Alpha Exchange users (like Charlie) can trade credit-based balances on Alpha Exchange. Alpha Exchange should keep track of user balances on its new balance sheet as these trades are made. These trades are _off-ledger_ and independent from the XRP Ledger, so the balance changes are not recorded on the XRP Ledger.
|
||||
|
||||
Customers who hold XRP in their own XRP Ledger accounts can also use the distributed exchange built into the XRP Ledger to trade currencies issued by gateways. For more information about trading _on_ the XRP Ledger, see [Lifecycle of an Offer](reference-transaction-format.html#lifecycle-of-an-offer).
|
||||
Customers who hold XRP in their own XRP Ledger accounts can also use the distributed exchange built into the XRP Ledger to trade currencies issued by gateways. For more information about trading _on_ the XRP Ledger, see [Lifecycle of an Offer](offers.html#lifecycle-of-an-offer).
|
||||
|
||||
|
||||
### Rebalance XRP Holdings
|
||||
|
||||
Exchanges can adjust the balances between their hot and cold wallets at any time. Each balance adjustment consumes a [transaction cost](transaction-cost.html), but does not otherwise affect the aggregate balance of all the accounts. The aggregate, on-ledger balance should always exceed the total balance available for trade on the exchange. (The excess should be enough to cover the XRP Ledger's transaction costs.)
|
||||
|
||||
The following table demonstrates a balance adjustment of 80,000 XRP (via a [_payment_](reference-transaction-format.html#payment) on the XRP Ledger) between Alpha Exchange's cold wallet and its hot wallet, where the cold wallet was debited and the hot wallet was credited. If the payment were reversed (debiting the hot wallet and crediting the cold wallet), the hot wallet balance would decrease. Balance adjustments like these allow an exchange to limit the risks associated with holding XRP in online hot wallets.
|
||||
The following table demonstrates a balance adjustment of 80,000 XRP (via a [Payment transaction][] on the XRP Ledger) between Alpha Exchange's cold wallet and its hot wallet, where the cold wallet was debited and the hot wallet was credited. If the payment were reversed (debiting the hot wallet and crediting the cold wallet), the hot wallet balance would decrease. Balance adjustments like these allow an exchange to limit the risks associated with holding XRP in online hot wallets.
|
||||
|
||||
|
||||
<table>
|
||||
|
||||
Reference in New Issue
Block a user