ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-12-02 17:45:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #369 from mDuo13/tutorial_link_fixes

Browse Source 
Tutorials link fixing and related
This commit is contained in:
Rome Reginelli
2018-05-11 19:31:15 -07:00
committed by GitHub
parent 1bc1cffae2 88c0279ece
commit 44a56ce130
38 changed files with 257 additions and 226 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
content/_snippets/checkcash-prereqs.md
View File

@@ -4,7 +4,7 @@ The prerequisites for cashing a check are the same whether you are cashing it fo
- For example, the ID of one Check in these examples is `838766BA2B995C00744175F69A1B11E32C3DBC40E64801A4056FCBD657F57334`, although you must use a different ID to go through these steps yourself.
- The **address** and **secret key** of the Check's stated recipient. The address must match the `Destination` address in the Check object.
- If the Check is for an issued currency, you (the recipient) must have a trust line to the issuer. Your limit on that trust line must be enough higher than the balance to add the amount you would receive.
- For more information on trust lines and limits, see [Issued Currencies](money.html#issued-currencies) and [Trust Limits](reference-transaction-format.html#trust-limits).
- A secure way to sign transactions, such as [RippleAPI][] or your own [`rippled` server](tutorial-rippled-setup.html).
- For more information on trust lines and limits, see [Issued Currencies](issued-currencies.html) and [Trust Lines and Issuing](trust-lines-and-issuing.html).
- A secure way to sign transactions, such as [RippleAPI][] or your own [`rippled` server](install-rippled.html).
- A client library that can connect to a `rippled` server, such as [RippleAPI][] or any HTTP or WebSocket library.
- For more information, see [Connecting to `rippled`](reference-rippled.html#connecting-to-rippled).
- For more information, see [Get Started with the `rippled` API](get-started-with-the-rippled-api.html).

2
content/_snippets/data_types/account_sequence.md
View File

@@ -2,4 +2,4 @@ A Sequence number is a 32-bit unsigned integer used to identify a transaction or
Every [account in the XRP Ledger](accounts.html) has a Sequence number, which starts at 1. For a transaction to be relayed to the network and possibly included in a validated ledger, it must have a `Sequence` field that matches the sending account's current `Sequence` number. An account's Sequence field is incremented whenever a transaction from that account is included in a validated ledger (regardless of whether the transaction succeeded or failed). This preserves the order of transactions submitted by an account, and differentiates transactions that would otherwise be the same.
Every [Offer in the XRP Ledger's decentralized exchange](offers.html) is marked with the sending `Account` [Address][] and the `Sequence` value of the [OfferCreate transaction](reference-transaction-format.html#offercreate) that created it. These two fields, together, uniquely identify the Offer.
Every [Offer in the XRP Ledger's decentralized exchange](offers.html) is marked with the sending `Account` [Address][] and the `Sequence` value of the [OfferCreate transaction](offercreate.html) that created it. These two fields, together, uniquely identify the Offer.

1
content/_snippets/rippled-api-links.md
View File

@@ -12,6 +12,7 @@
[seconds since the Ripple Epoch]: basic-data-types.html#specifying-time
[Sequence Number]: basic-data-types.html#account-sequence
[SHA-512Half]: ledger-data-formats.html#sha512half
[Specifying Currency Amounts]: basic-data-types.html#specifying-currency-amounts
[Specifying Ledgers]: basic-data-types.html#specifying-ledgers
[Specifying Time]: basic-data-types.html#specifying-time
[standard format]: response-formatting.html

2
content/_snippets/tutorial-sign-step.md
View File

@@ -1,3 +1,3 @@
The most secure way to sign a transaction is to do it locally with a signing library, such as [RippleAPI](reference-rippleapi.html). 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 locally with a signing library, such as [RippleAPI](rippleapi-reference.html). Alternatively, you can sign the transaction using the [sign method](sign.html) command, but this must be done through a trusted and encrypted connection, or through a local connection, and only to a server you control.
In all cases, note the signed transaction's identifying hash for later.

2
content/_snippets/tutorial-submit-step.md
View File

@@ -1,3 +1,3 @@
Take the signed transaction blob from the previous step and submit it to a `rippled` server. You can do this safely even if you do not operate the `rippled` server. The response contains a provisional result, which should be `tesSUCCESS`, but this result is [usually not final](reference-transaction-format.html#finality-of-results). A provisional response of `terQUEUED` is also OK, since [queued transactions](transaction-cost.html#queued-transactions) are generally included in the next open ledger version (usually about 10 seconds after submission).
Take the signed transaction blob from the previous step and submit it to a `rippled` server. You can do this safely even if you do not operate the `rippled` server. The response contains a provisional result, which should be `tesSUCCESS`, but this result is [usually not final](finality-of-results.html). A provisional response of `terQUEUED` is also OK, since [queued transactions](transaction-cost.html#queued-transactions) are generally included in the next open ledger version (usually about 10 seconds after submission).
**Tip:** If the preliminary result is `tefMAX_LEDGER`, the transaction has failed permanently because its `LastLedgerSequence` parameter is lower than the current ledger. This happens when you take longer than the expected number of ledger versions between preparing and submitting the transaction. If this occurs, [start over from step 1]({{step_1_link}}) with a higher `LastLedgerSequence` value.

3
content/tutorials/manage-issued-currencies/set-up-issuing-and-operational-addresses.md → content/concepts/issued-currencies/issuing-and-operational-addresses.md
View File

@@ -1,6 +1,7 @@
# Issuing and Operational Addresses
{% include '_snippets/issuing-and-operational-addresses-intro.md' %}
<!--{#_ #}-->
## Funds Lifecycle
@@ -10,7 +11,7 @@ All non-XRP currency balances (issuances) in the XRP Ledger are tied to accounti
When the issuing address sends payments, it creates balances in the accounting relationships in the XRP Ledger. Within the XRP Ledger, users can exchange balances across different accounting relationships, so we use the term _issuances_ to describe any non-XRP balance. Issuances have negative value from the perspective of the issuing address, since they represent obligations. The same issuances have positive value from the perspective of the issuing address's counterparties. When the issuing address receives a payment, this reduces its obligations, erasing the issuances that were sent.
The issuing address sends issuances to a standby address, or directly to an operational address. The standby addresses send those issuances to operational addresses. Operational addresses send payments to other counterparties, such as liquidity providers, partners, and other customers. Because all issuances are tied to accounting relationships with the issuing address, payments and exchanges of issuances "ripple through" the issuing address. The payment debits the sender's balance in its accounting relationship with the issuing address and credits the recipient's balance in the recipient's accounting relationship with the issuing address. The XRP Ledger also supports more complicated [paths](paths.html) that connect multiple issuers through order books and [liquidity providers who allow their funds to ripple](noripple.html).
The issuing address sends issuances to a standby address, or directly to an operational address. The standby addresses send those issuances to operational addresses. Operational addresses send payments to other counterparties, such as liquidity providers, partners, and other customers. Because all issuances are tied to accounting relationships with the issuing address, payments and exchanges of issuances "ripple through" the issuing address. The payment debits the sender's balance in its accounting relationship with the issuing address and credits the recipient's balance in the recipient's accounting relationship with the issuing address. The XRP Ledger also supports more complicated [paths](paths.html) that connect multiple issuers through order books and [liquidity providers who allow their funds to ripple](rippling.html).
## Issuing Address

20
content/tutorials/get-started/get-started-with-rippleapi-for-javascript.md
View File

@@ -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,12 +131,12 @@ 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`](tutorial-rippled-setup.html), you can instruct it to connect to your local server. For example, you might say `server: 'ws://localhost:5005'` instead.
* 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.
### Connecting and Promises
@@ -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,13 +188,13 @@ 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.
# Waiting for Validation
One of the biggest challenges in using the XRP Ledger (or any decentralized system) is knowing the final, immutable transaction results. Even if you [follow the best practices](tutorial-reliable-transaction-submission.html) you still have to wait for the [consensus process](https://ripple.com/build/ripple-ledger-consensus-process/) to finally accept or reject your transaction. The following example code demonstrates how to wait for the final outcome of a transaction:
One of the biggest challenges in using the XRP Ledger (or any decentralized system) is knowing the final, immutable transaction results. Even if you [follow the best practices](reliable-transaction-submission.html) you still have to wait for the [consensus process](https://ripple.com/build/ripple-ledger-consensus-process/) to finally accept or reject your transaction. The following example code demonstrates how to wait for the final outcome of a transaction:
```
{% include '_code-samples/rippleapi_quickstart/submit-and-verify.js' %}
@@ -204,9 +204,9 @@ This code creates and submits an order transaction, although the same principles
In rare cases (particularly with a large delay or a loss of power), the `rippled` server may be missing a ledger version between when you submitted the transaction and when you determined that the network has passed the `maxLedgerVersion`. In this case, you cannot be definitively sure whether the transaction has failed, or has been included in one of the missing ledger versions. RippleAPI returns `MissingLedgerHistoryError` in this case.
If you are the administrator of the `rippled` server, you can [manually request the missing ledger(s)](reference-rippled.html#ledger-request). Otherwise, you can try checking the ledger history using a different server. (Ripple runs a public full-history server at `s2.ripple.com` for this purpose.)
If you are the administrator of the `rippled` server, you can [manually request the missing ledger(s)](ledger_request.html). Otherwise, you can try checking the ledger history using a different server. (Ripple runs a public full-history server at `s2.ripple.com` for this purpose.)
See [Reliable Transaction Submission](tutorial-reliable-transaction-submission.html) for a more thorough explanation.
See [Reliable Transaction Submission](reliable-transaction-submission.html) for a more thorough explanation.
# RippleAPI in Web Browsers

2
content/tutorials/get-started/get-started-with-the-rippled-api.md
View File

@@ -2,7 +2,7 @@
Before you can run any commands against a `rippled` server, you must know which server you are connecting to. Most servers are configured not to accept API requests directly from the outside network.
Alternatively, you can [run your own local copy of `rippled`](tutorial-rippled-setup.html). This is required if you want to access any of the [Admin Commands](#list-of-admin-commands). In this case, you should use whatever IP and port you configured the server to bind. (For example, `127.0.0.1:54321`) Additionally, to access admin functionality, you must connect from a port/IP address marked as admin in the config file.
Alternatively, you can [run your own local copy of `rippled`](install-rippled.html). This is required if you want to access any of the [Admin Commands](#list-of-admin-commands). In this case, you should use whatever IP and port you configured the server to bind. (For example, `127.0.0.1:54321`) Additionally, to access admin functionality, you must connect from a port/IP address marked as admin in the config file.
The [example config file](https://github.com/ripple/rippled/blob/release/doc/rippled-example.cfg#L907-L930) listens for connections on the local loopback network (127.0.0.1), with JSON-RPC (HTTP) on port 5005 and WebSocket (WS) on port 6006, and treats all connected clients as admin.

6
content/tutorials/manage-account-settings/assign-a-regular-key-pair.md
View File

@@ -14,7 +14,7 @@ This tutorial walks through the steps required to assign a regular key pair to y
## 1. Generate a Key Pair
Use the [`wallet_propose`](reference-rippled.html#wallet-propose) method to generate the key pair that you'll assign to your account as a regular key pair.
Use the [wallet_propose method][] to generate the key pair that you'll assign to your account as a regular key pair.
### Request Format
@@ -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)

2
content/tutorials/manage-account-settings/change-or-remove-a-regular-key-pair.md
View File

@@ -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:

4
content/tutorials/manage-account-settings/set-up-multi-signing.md
View File

@@ -21,7 +21,7 @@ You need an XRP Ledger address that can send transactions, and has enough XRP av
If you started `rippled` in [stand-alone mode](stand-alone-mode.html) with a new genesis ledger, you must:
1. Generate keys for a new address, or reuse keys you already have.
2. Submit a Payment transaction to fund the new address from the genesis account. (Send at least 100,000,000 [drops of XRP](reference-rippled.html#specifying-currency-amounts).)
2. Submit a Payment transaction to fund the new address from the genesis account. (Send at least 100,000,000 [drops of XRP][].)
3. Manually close the ledger.
@@ -50,7 +50,7 @@ Take note of the `account_id` (XRP Ledger Address) and `master_seed` (secret key
## 3. Send SignerListSet transaction
[Sign and submit](reference-transaction-format.html#signing-and-submitting-transactions) a [SignerListSet transaction](reference-transaction-format.html#signerlistset) in the normal (single-signature) way. This associates a SignerList with your XRP Ledger address, so that a combination of signatures from the members of that SignerList can multi-sign later transactions on your behalf.
[Sign and submit](transaction-basics.html#signing-and-submitting-transactions) a [SignerListSet transaction][] in the normal (single-signature) way. This associates a SignerList with your XRP Ledger address, so that a combination of signatures from the members of that SignerList can multi-sign later transactions on your behalf.
In this example, the SignerList has 3 members, with the weights and quorum set up such that multi-signed transactions need a signature from rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW plus at least one signature from the other two members of the list.

8
content/tutorials/manage-the-rippled-server/advance-the-ledger-in-stand-alone-mode.md
View File

@@ -8,4 +8,10 @@ rippled ledger_accept --conf=/path/to/rippled.cfg
In stand-alone mode, `rippled` makes no distinction between a "closed" ledger version and a "validated" ledger version. (For more information about the difference, see [The XRP Ledger Consensus Process](consensus.html).)
Whenever `rippled` closes a ledger, it reorders the transactions according to a deterministic but hard-to-game algorithm. (This is an important part of consensus, since transactions may arrive at different parts of the network in different order.) When using `rippled` in stand-alone mode, you should manually advance the ledger before submitting a transaction that depends on the result of a transaction from a different address. Otherwise, the two transactions might be executed in reverse order when the ledger is closed. **Note:** You can safely submit multiple transactions from a single address to a single ledger, because `rippled` sorts transactions from the same address in ascending order by [`Sequence` number](reference-transaction-format.html#common-fields).
Whenever `rippled` closes a ledger, it reorders the transactions according to a deterministic but hard-to-game algorithm. (This is an important part of consensus, since transactions may arrive at different parts of the network in different order.) When using `rippled` in stand-alone mode, you should manually advance the ledger before submitting a transaction that depends on the result of a transaction from a different address. Otherwise, the two transactions might be executed in reverse order when the ledger is closed. **Note:** You can safely submit multiple transactions from a single address to a single ledger, because `rippled` sorts transactions from the same address in ascending order by [`Sequence` number](transaction-common-fields.html).
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

8
content/tutorials/manage-the-rippled-server/build-run-rippled-ubuntu.md
View File

@@ -2,7 +2,7 @@
`rippled` is the core peer-to-peer server that manages the XRP Ledger. A `rippled` server can connect to a network of peers, relay cryptographically signed transactions, and maintain a local copy of the complete shared global ledger.
For an overview of `rippled`, see [Operating rippled Servers](tutorial-rippled-setup.html).
For an overview of `rippled`, see [Operating rippled Servers](install-rippled.html).
Use these instructions to build a `rippled` executable from source version 0.90.0 or higher on Ubuntu Linux 16.04 or higher. These instructions were tested on Ubuntu 16.04 LTS.
@@ -17,7 +17,7 @@ You need a **minimum** of 8GB of RAM.
**_To run `rippled`:_**
Meet these [system requirements](tutorial-rippled-setup.html#minimum-system-requirements).
Meet these [system requirements](install-rippled.html#minimum-system-requirements).
## 1. Build `rippled`
@@ -182,9 +182,9 @@ Watchdog: Launching child 1
## Explore Next Steps
* Now that you have a stock `rippled` server running, you may want to consider running it as a validating server. For information about validating servers and why you might want to run one, see the [rippled Setup Tutorial](tutorial-rippled-setup.html).
* Now that you have a stock `rippled` server running, you may want to consider running it as a validating server. For information about validating servers and why you might want to run one, see the [rippled Setup Tutorial](install-rippled.html).
* For information about communicating with your `rippled` server using the `rippled` API, see the [`rippled` API reference](reference-rippled.html).
* For information about communicating with your `rippled` server using the `rippled` API, see the [`rippled` API reference](rippled-api.html).
* As a development best practice, you may want to build a `rippled` `.deb` file. For more information, see _Ubuntu Packaging Guide_: [Packaging New Software](http://packaging.ubuntu.com/html/packaging-new-software.html).

5
content/tutorials/manage-the-rippled-server/cluster-rippled-servers.md
View File

@@ -17,3 +17,8 @@ To enable clustering, change the following sections of your [config file](https:
* Generate a unique seed (using the [validation_create method][]) for each of your servers, and configure it under the `[node_seed]` section. The `rippled` server uses this key to sign its messages to other servers in the peer-to-peer network.
* Add the public keys (for peer communication) of each of your other servers under the `[cluster_nodes]` section.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

17
content/tutorials/manage-the-rippled-server/install-rippled.md
View File

@@ -1,9 +1,13 @@
# Install rippled
For development, you can [compile `rippled` from source](https://wiki.ripple.com/Rippled_build_instructions).
Production `rippled` instances can [use Ripple's binary executable](#installation-on-centosred-hat-with-yum), available from the Ripple [yum](https://en.wikipedia.org/wiki/Yellowdog_Updater,_Modified) repository.
For development, you can compile `rippled` from source:
- See [Build and Run `rippled` on Ubuntu](build-run-rippled-ubuntu.html) for Ubuntu Linux 16.04 and higher.
- For other platforms, see the [rippled repository](https://github.com/ripple/rippled/tree/develop/Builds) for instructions.
## Minimum System Requirements
A `rippled` server should run comfortably on commodity hardware, to make it inexpensive to participate in the network. At present, we recommend the following mimimum requirements:
@@ -19,7 +23,8 @@ A `rippled` server should run comfortably on commodity hardware, to make it inex
Amazon EC2's `m3.large` VM size may be appropriate depending on your workload. A fast network connection is preferable. Any increase in a server's client-handling load increases resources needs.
**Tip:** For recommendations beyond the minimum requirements, see [Capacity Planning](#capacity-planning).
**Tip:** For recommendations beyond the minimum requirements, see [Capacity Planning](capacity-planning.html).
## Installation on CentOS/Red Hat with yum
@@ -78,6 +83,8 @@ This section assumes that you are using Ubuntu 15.04 or later.
It can take several minutes for `rippled` to sync with the rest of the network, during which time it outputs warnings about missing ledgers. After that, you have a fully functional stock `rippled` server that you can use for local signing and API access to the XRP Ledger.
[rippled commands](reference-rippled.html#list-of-public-commands) can be run with:
You can use the [rippled commandline interface](get-started-with-the-rippled-api.html#commandline) as follows:
$ /opt/ripple/bin/rippled <command>
$ /opt/ripple/bin/rippled <METHOD>
For a full list of available methods, see the [rippled API reference](rippled-api.html).

9
content/tutorials/manage-the-rippled-server/load-a-saved-ledger-in-stand-alone-mode.md
View File

@@ -1,6 +1,6 @@
# Load a Saved Ledger in Stand-Alone Mode
You can start with a ledger version that was saved to disk if your `rippled` server was previously synced with the XRP Ledger peer-to-peer network (either the production network or the [Test Net](tutorial-rippled-setup.html#parallel-networks)).
You can start with a ledger version that was saved to disk if your `rippled` server was previously synced with the XRP Ledger peer-to-peer network (either the production network or the [Test Net](parallel-networks.html)).
## 1. Start `rippled` normally.
@@ -18,7 +18,7 @@ Use the [server_info method][] to check the state of your server relative to the
* `proposing`
* `validating`
For more information, see [Possible Server States](reference-rippled.html#possible-server-states).
For more information, see [Possible Server States](rippled-server-states.html).
## 3. (Optional) Retrieve specific ledger versions.
@@ -57,3 +57,8 @@ When you load a ledger with `--ledger` in stand-alone mode, it goes to the curre
```
rippled ledger_accept --conf=/path/to/rippled.cfg
```
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

3
content/tutorials/manage-the-rippled-server/manage-the-rippled-server.md
View File

@@ -1,3 +0,0 @@
# Manage the rippled Server
This category encompasses various procedures for running stable and effective `rippled` servers.

4
content/tutorials/manage-the-rippled-server/rippled-setup.md
View File

@@ -1,6 +1,6 @@
# Operating rippled Servers
The core server of the XRP Ledger peer-to-peer network is [`rippled`](reference-rippled.html). Anyone can run their own `rippled` server that follows the network and keeps a complete copy of the XRP Ledger. You can even have your server take part in the consensus process.
The core server of the XRP Ledger peer-to-peer network is [`rippled`](the-rippled-server.html). Anyone can run their own `rippled` server that follows the network and keeps a complete copy of the XRP Ledger. You can even have your server take part in the consensus process.
This page contains instructions for:
@@ -21,4 +21,4 @@ Changes to the `[debug_logfile]` or `[database_path]` sections may require you t
Restart `rippled` for any configuration changes to take effect:
$ sudo service rippled restart
$ sudo service rippled restart

12
content/tutorials/manage-the-rippled-server/run-rippled-as-a-validator.md
View File

@@ -2,18 +2,18 @@
Running a `rippled` validator that participates in the Consensus process is simple:
1. [Enable validation](#validator-setup) on your `rippled` server.
1. [Enable validation](run-rippled-as-a-validator.html) on your `rippled` server.
* At first, your server is an _untrusted validator_. Others can see the validations your server issues, but they disregard them in the consensus process.
2. Share the public key with the public, especially other `rippled` operators.
3. When other `rippled` operators add your public key to their list of trusted servers, you have become a _trusted validator_.
* Also see [Properties of a Good Validator](#properties-of-a-good-validator) for best practices.
* Also see [Properties of a Good Validator](the-rippled-server.html#properties-of-a-good-validator) for best practices.
## Validator Setup
The `validator-keys` tool (included in the `rippled` RPM) is the recommended means to securely generate and manage your validator keys.
1. [Install a `rippled` server.](#installing-rippled)
1. [Install a `rippled` server.](install-rippled.html)
2. Generate a validator key pair:
@@ -38,11 +38,11 @@ See [the `validator-keys-tool` GitHub repository](https://github.com/ripple/vali
To protect a production validator from [DDoS](https://en.wikipedia.org/wiki/Denial-of-service_attack) attacks, you can use a stock `rippled` server as a proxy between the validator and the outside network.
1. [Set up the `rippled` validator.](#validator-setup)
1. [Set up the `rippled` validator.](run-rippled-as-a-validator.html)
2. [Set up one or more stock `rippled` servers.](#installing-rippled)
2. [Set up one or more stock `rippled` servers.](install-rippled.html)
3. Configure the validator and stock `rippled` servers to be [clustered](#clustering) with each other.
3. Configure the validator and stock `rippled` servers to be [clustered](cluster-rippled-servers.html) with each other.
4. Make the following configuration changes to your validator:
* Copy the `[ips_fixed]` list and paste it under `[ips]`. These fields should contain only the IP addresses and ports of the public-facing rippled(s). The validator connects to only these peers.

27
content/tutorials/tutorials.md
View File

@@ -1,27 +0,0 @@
# Tutorials
These tutorials walk you step-by-step through performing key and common tasks with the XRP Ledger.
* **[Get Started](x)**
Get up and running with some of the resources you'll use to work with the XRP Ledger, such as the `rippled` API, the `ripple-lib` API for JavaScript, and the XRP Ledger Test Net.
* **[Manage Account Settings](x)**
<!--{# TODO: this text below is written to reflect that we've moved "Create an Account" from the "Send the Receive Money" section below - to this section. If this section is called "Manage Account Settings" - I think the first tutorial needs to be creating an account, so that you can then configure settings for it. #}-->
Create an XRP Ledger account and configure it to send and receive payments the way you want it to.
* **[Send and Receive Money](x)**
After you have a configured XRP Ledger account, learn how to sign, submit, and receive transactions using your account.
* **[Work with Exchanges](x)**
<!--{# TODO: the title of this tutorial group may change. May be clearer to surface the two tutorial types separately? #}-->
Learn how to list XRP in your exchange. Also, learn how to use the decentralized exchange functionality provided by the XRP Ledger.
* **[Manage the `rippled` Server](x)**
Build or install and run a `rippled` server. Configure `rippled` to run in various modes, such as validator, stock, and standalone. Also, learn how to troubleshoot `rippled`.
Want a tutorial about a task not covered here? [Contact us >](mailto:docs@ripple.com)

20
content/tutorials/use-complex-payment-types/use-checks/cancel-a-check.md
View File

@@ -15,14 +15,14 @@ To cancel a Check with this tutorial, you need the following:
- You need the ID of a Check object currently in the ledger.
- For example, this tutorial includes examples that cancel a Check with the ID `49647F0D748DC3FE26BDACBC57F251AADEFFF391403EC9BF87C97F67E9977FB0`, although you must use a different ID to go through these steps yourself.
- The **address** and **secret key** of a funded account to send the CheckCancel transaction. This address must be either the sender or the recipient of the Check, unless the Check is expired.
- A secure way to sign transactions, such as [RippleAPI][] or your own [`rippled` server](tutorial-rippled-setup.html).
- A secure way to sign transactions, such as [RippleAPI][] or your own [`rippled` server](install-rippled.html).
- A client library that can connect to a `rippled` server, such as [RippleAPI][] or any HTTP or WebSocket library.
- For more information, see [Connecting to `rippled`](reference-rippled.html#connecting-to-rippled).
- For more information, see [Get Started with the `rippled` API](get-started-with-the-rippled-api.html).
## {{cancel_n.next()}}. Prepare the CheckCancel transaction
Figure out the values of the [CheckCancel transaction][] fields. The following fields are the bare minimum; everything else is either optional or can be [auto-filled](reference-transaction-format.html#auto-fillable-fields) when signing:
Figure out the values of the [CheckCancel transaction][] fields. The following fields are the bare minimum; everything else is either optional or can be [auto-filled](transaction-common-fields.html#auto-fillable-fields) when signing:
| Field | Value | Description |
|:------------------|:-----------------|:--------------------------------------|
@@ -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.
@@ -151,7 +151,7 @@ The following examples demonstrate how to cancel a Check.
Use the [tx method][] with the CheckCancel transaction's identifying hash to check its status. Look for a `"TransactionResult": "tesSUCCESS"` field in the transaction's metadata, indicating that the transaction succeeded, and the field `"validated": true` in the result, indicating that this result is final.
Look for a `DeletedNode` object in the transaction metadata with `"LedgerEntryType": "Check"` to indicate that the transaction removed a [Check ledger object](reference-ledger-format.html#check). The `LedgerIndex` of this object should match the ID of the Check.
Look for a `DeletedNode` object in the transaction metadata with `"LedgerEntryType": "Check"` to indicate that the transaction removed a [Check ledger object](check.html). The `LedgerIndex` of this object should match the ID of the Check.
### Example Request
@@ -190,8 +190,8 @@ Look for a `DeletedNode` object in the transaction metadata with `"LedgerEntryTy
<!-- MULTICODE_BLOCK_END -->
<!--{# common links #}-->
[Specifying Currency Amounts]: reference-rippled.html#specifying-currency-amounts
[RippleAPI]: reference-rippleapi.html
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled-api-links.md' %}
<!--{# common link defs #}-->
[RippleAPI]: rippleapi-reference.html
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

11
content/tutorials/use-complex-payment-types/use-checks/cash-a-check-for-a-flexible-amount.md
View File

@@ -1,12 +1,12 @@
# Cash a Check for a Flexible Amount
_Requires the [Checks Amendment](reference-amendments.html#checks)._
_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 a flexible amount by sending a [CheckCash transaction][] with a `DeliverMin` field. When cashing a Check in this way, the receiver gets as much as is possible to deliver, debiting the Check's sender for the Check's full `SendMax` amount or as much as is available. Cashing fails if it doesn't deliver at least the `DeliverMin` amount to the Check's recipient.
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)) %}
@@ -17,7 +17,7 @@ The specified recipient can also [cash the check for an exact amount](tutorial-c
## {{cash_flex_n.next()}}. Prepare the CheckCash transaction
Figure out the values of the [CheckCash transaction][] fields. To cash a check for a flexible amount, the following fields are the bare minimum; everything else is either optional or can be [auto-filled](reference-transaction-format.html#auto-fillable-fields) when signing:
Figure out the values of the [CheckCash transaction][] fields. To cash a check for a flexible amount, the following fields are the bare minimum; everything else is either optional or can be [auto-filled](transaction-common-fields.html#auto-fillable-fields) when signing:
| Field | Value | Description |
|:------------------|:--------------------------|:-----------------------------|
@@ -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,7 +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 #}-->
[Specifying Currency Amounts]: reference-rippled.html#specifying-currency-amounts
[RippleAPI]: reference-rippleapi.html
[RippleAPI]: rippleapi-reference.html
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled-api-links.md' %}

11
content/tutorials/use-complex-payment-types/use-checks/cash-a-check-for-an-exact-amount.md
View File

@@ -1,10 +1,10 @@
# Cash a Check for an Exact Amount
_Requires the [Checks Amendment](reference-amendments.html#checks)._
_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)) %}
@@ -14,7 +14,7 @@ The specified recipient can also [cash the check for a flexible amount](tutorial
## {{cash_exact_n.next()}}. Prepare the CheckCash transaction
Figure out the values of the [CheckCash transaction][] fields. To cash a check for an exact amount, the following fields are the bare minimum; everything else is either optional or can be [auto-filled](reference-transaction-format.html#auto-fillable-fields) when signing:
Figure out the values of the [CheckCash transaction][] fields. To cash a check for an exact amount, the following fields are the bare minimum; everything else is either optional or can be [auto-filled](transaction-common-fields.html#auto-fillable-fields) when signing:
| Field | Value | Description |
|:------------------|:--------------------------|:-----------------------------|
@@ -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,7 +148,6 @@ If cashing the Check failed, the Check remains in the ledger so you can try cash
<!-- MULTICODE_BLOCK_END -->
<!--{# common links #}-->
[Specifying Currency Amounts]: reference-rippled.html#specifying-currency-amounts
[RippleAPI]: reference-rippleapi.html
[RippleAPI]: rippleapi-reference.html
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled-api-links.md' %}

7
content/tutorials/use-complex-payment-types/use-checks/look-up-checks-by-recipient.md
View File

@@ -1,8 +1,8 @@
# Look Up Checks by Recipient
_Requires the [Checks Amendment](reference-amendments.html#checks)._
_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,7 +74,6 @@ for (i=0; i < account_objects_response.account_objects.length; i++) {
```
<!--{# common links #}-->
[Specifying Currency Amounts]: reference-rippled.html#specifying-currency-amounts
[RippleAPI]: reference-rippleapi.html
[RippleAPI]: rippleapi-reference.html
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled-api-links.md' %}

5
content/tutorials/use-complex-payment-types/use-checks/look-up-checks-by-sender.md
View File

@@ -1,6 +1,6 @@
# Look Up Checks by Sender
_Requires the [Checks Amendment](reference-amendments.html#checks)._
_Requires the [Checks Amendment](known-amendments.html#checks)._
This tutorial shows how to look up [Checks](checks.html) by their sender. You may also want to [look up Checks by recipient](tutorial-checks-lookup-by-recipient.html).
@@ -75,7 +75,6 @@ for (i=0; i < account_objects_response.account_objects.length; i++) {
```
<!--{# common links #}-->
[Specifying Currency Amounts]: reference-rippled.html#specifying-currency-amounts
[RippleAPI]: reference-rippleapi.html
[RippleAPI]: rippleapi-reference.html
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled-api-links.md' %}

26
content/tutorials/use-complex-payment-types/use-checks/send-a-check.md
View File

@@ -1,8 +1,8 @@
# Send a Check
_Requires the [Checks Amendment](reference-amendments.html#checks)._
_Requires the [Checks Amendment](known-amendments.html#checks)._
Sending a Check is like writing permission for an intended recipient to pull a payment from you. The outcome of this process is a [Check object in the ledger](reference-ledger-format.html#check) which the recipient can cash later.
Sending a Check is like writing permission for an intended recipient to pull a payment from you. The outcome of this process is a [Check object in the ledger](check.html) which the recipient can cash later.
In many cases, you want to send a [Payment][] instead of a Check, since that delivers the money directly to the recipient in one step. However, if your intended recipient uses [DepositAuth](depositauth.html), you cannot send them Payments directly, so a Check is a good alternative.
@@ -19,13 +19,13 @@ To send a Check with this tutorial, you need the following:
- The **address** and **secret key** of a funded account to send the Check from.
- You can use the [XRP Ledger Test Net Faucet](https://ripple.com/build/xrp-test-net/) to get a funded address and secret with 10,000 Test Net XRP.
- The **address** of a funded account to receive the Check.
- A secure way to sign transactions, such as [RippleAPI][] or your own [`rippled` server](tutorial-rippled-setup.html).
- A secure way to sign transactions, such as [RippleAPI][] or your own [`rippled` server](install-rippled.html).
- A client library that can connect to a `rippled` server, such as [RippleAPI][] or any HTTP or WebSocket library.
- For more information, see [Connecting to `rippled`](reference-rippled.html#connecting-to-rippled).
- For more information, see [Get Started with the `rippled` API](get-started-with-the-rippled-api.html).
## {{send_n.next()}}. Prepare the CheckCreate transaction
Decide how much money the Check is for and who can cash it. Figure out the values of the [CheckCreate transaction][] fields. The following fields are the bare minimum; everything else is either optional or can be [auto-filled](reference-transaction-format.html#auto-fillable-fields) when signing:
Decide how much money the Check is for and who can cash it. Figure out the values of the [CheckCreate transaction][] fields. The following fields are the bare minimum; everything else is either optional or can be [auto-filled](transaction-common-fields.html#auto-fillable-fields) when signing:
| Field | Value | Description |
|:------------------|:--------------------------|:-----------------------------|
@@ -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.
@@ -67,6 +67,7 @@ The following example shows a prepared Check from BoxSend SG (rBXsgNkPcDN2runsvW
## {{send_n.next()}}. Sign the CheckCreate transaction
{% include '_snippets/tutorial-sign-step.md' %}
<!--{#_ #}-->
### Example Request
@@ -120,6 +121,7 @@ The following example shows a prepared Check from BoxSend SG (rBXsgNkPcDN2runsvW
{% set step_1_link = "#1-prepare-the-checkcreate-transaction" %}
{% include '_snippets/tutorial-submit-step.md' %}
<!--{#_ #}-->
### Example Request
@@ -173,12 +175,13 @@ The following example shows a prepared Check from BoxSend SG (rBXsgNkPcDN2runsvW
## {{send_n.next()}}. Wait for validation
{% include '_snippets/wait-for-validation.md' %}
<!--{#_ #}-->
## {{send_n.next()}}. Confirm final result
Use the [tx method][] with the CheckCreate transaction's identifying hash to check its status. Look for a `"TransactionResult": "tesSUCCESS"` field in the transaction's metadata, indicating that the transaction succeeded, and the field `"validated": true` in the result, indicating that this result is final.
Look for a `CreatedNode` object in the transaction metadata to indicate that the transaction created a [Check ledger object](reference-ledger-format.html#check). The `LedgerIndex` of this object is the ID of the Check. In the following example, the Check's ID is `49647F0D748DC3FE26BDACBC57F251AADEFFF391403EC9BF87C97F67E9977FB0`.
Look for a `CreatedNode` object in the transaction metadata to indicate that the transaction created a [Check ledger object](check.html). The `LedgerIndex` of this object is the ID of the Check. In the following example, the Check's ID is `49647F0D748DC3FE26BDACBC57F251AADEFFF391403EC9BF87C97F67E9977FB0`.
**Note:** RippleAPI does not report the Check's ID when you look up a CheckCreate transaction. You can work around this by calculating the Check's ID from the [Check ID format](reference-ledger-format.html#check-id-format), as in the example RippleAPI code below. <!--{# TODO: Remove this and update the code samples if ripple-lib #876 gets fixed. #}-->
@@ -230,7 +233,8 @@ Look for a `CreatedNode` object in the transaction metadata to indicate that the
<!-- MULTICODE_BLOCK_END -->
<!--{# common links #}-->
[Specifying Currency Amounts]: reference-rippled.html#specifying-currency-amounts
[RippleAPI]: reference-rippleapi.html
{% include '_snippets/tx-type-links.md' %}
<!--{# common link defs #}-->
[RippleAPI]: rippleapi-reference.html
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

2
content/tutorials/use-complex-payment-types/use-checks/use-checks.md
View File

@@ -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](reference-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
content/tutorials/use-complex-payment-types/use-complex-payment-types.md
View File

@@ -1,3 +1,3 @@
# Use Complex Payment Types
In addition to [simple, direct XRP Payments](TODO:link), the XRP Ledger supports a variety of more complex payments for building smart apps on the decentralized ledger.
In addition to simple, direct XRP Payments, <!--{# TODO:link tutorial or concept (DOC-1560) for simple XRP payments #}--> the XRP Ledger supports a variety of more complex payments for building smart apps on the decentralized ledger.

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

@@ -122,7 +122,7 @@ _Websocket_
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).
**Tip:** If you don't know what `OfferSequence` to use in the [EscrowFinish transaction][] to execute an escrow, use the [`tx` method](reference-rippled.html) 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.
**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.
{% include '_snippets/tx-type-links.md' %}

10
content/tutorials/use-complex-payment-types/use-escrows/look-up-escrows.md
View File

@@ -1,12 +1,12 @@
# Look up escrows
All pending escrows are stored in the ledger as [Escrow objects](reference-ledger-format.html#escrow).
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,9 +41,9 @@ _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](reference-amendments.html#fix1523) was enabled on 2017-11-14.
**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.
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.

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

@@ -60,7 +60,7 @@ print(cancel_after)
## 3. Submit EscrowCreate transaction
[Sign and submit](reference-transaction-format.html#signing-and-submitting-transactions) an [EscrowCreate transaction][]. Set the `Condition` field of the transaction to the time when the held payment should be released. Set the `Destination` to the recipient, which can be the same address as the sender. Include the `CancelAfter` or `FinishAfter` time you calculated in the previous step. Set the `Amount` to the total amount of [XRP, in drops](reference-rippled.html#specifying-currency-amounts), to escrow.
[Sign and submit](reference-transaction-format.html#signing-and-submitting-transactions) an [EscrowCreate transaction][]. Set the `Condition` field of the transaction to the time when the held payment should be released. Set the `Destination` to the recipient, which can be the same address as the sender. Include the `CancelAfter` or `FinishAfter` time you calculated in the previous step. Set the `Amount` to the total amount of [XRP, in drops][], to escrow.
{% include '_snippets/secret-key-warning.md' %} <!--#{ fix md highlighting_ #}-->
@@ -94,7 +94,7 @@ Response:
## 5. Confirm that the escrow was created
Use the [tx method][] with the transaction's identifying hash to check its final status. In particular, look for a `CreatedNode` in the transaction metadata to indicate that it created an [Escrow ledger object](reference-ledger-format.html#escrow).
Use the [tx method][] with the transaction's identifying hash to check its final status. In particular, look for a `CreatedNode` in the transaction metadata to indicate that it created an [Escrow ledger object](escrow.html).
Request:
@@ -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_ #}-->
@@ -175,6 +175,7 @@ Response:
```
{% include '_snippets/tx-type-links.md' %}
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}

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

@@ -4,7 +4,7 @@ The [EscrowCreate transaction][] type can create an escrow whose only condition
## 1. Calculate release time
You must [specify the time](reference-rippled.html#specifying-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 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:
<!-- MULTICODE_BLOCK_START -->
@@ -37,7 +37,7 @@ print(release_date_ripple)
## 2. Submit EscrowCreate transaction
[Sign and submit](reference-transaction-format.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](reference-rippled.html#specifying-currency-amounts), to escrow.
[Sign and submit](reference-transaction-format.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.
{% include '_snippets/secret-key-warning.md' %} <!--#{ fix md highlighting_ #}-->
@@ -74,7 +74,7 @@ Take note of the transaction's identifying `hash` value so you can check its fin
## 4. Confirm that the escrow was created
Use the [tx method][] with the transaction's identifying hash to check its final status. Look for a `CreatedNode` in the transaction metadata to indicate that it created an [Escrow ledger object](reference-ledger-format.html#escrow).
Use the [tx method][] with the transaction's identifying hash to check its final status. Look for a `CreatedNode` in the transaction metadata to indicate that it created an [Escrow ledger object](escrow.html).
Request:
@@ -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][]:
@@ -133,11 +133,11 @@ Response:
## 6. Submit EscrowFinish transaction
[Sign and submit](reference-transaction-format.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 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.
**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_ #}-->
@@ -200,6 +200,8 @@ Response:
<!-- MULTICODE_BLOCK_END -->
{% include '_snippets/tx-type-links.md' %}
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}

18
content/tutorials/use-complex-payment-types/use-payment-channels.md
View File

@@ -1,6 +1,6 @@
# Use Payment Channels
Payment Channels are an advanced feature for sending "asynchronous" XRP payments that can be divided into very small increments and settled later. This tutorial walks through the entire process of using a [payment channel](payment-channels.html), with examples using the [JSON-RPC API](reference-rippled.html) of a local `rippled` server.
Payment Channels are an advanced feature for sending "asynchronous" XRP payments that can be divided into very small increments and settled later. This tutorial walks through the entire process of using a [payment channel](payment-channels.html), with examples using the [JSON-RPC API](rippled-api.html) of a local `rippled` server.
Ideally, to step through this tutorial, you would have two people, each with the keys to a [funded XRP Ledger account](accounts.html). However, you can also step through the tutorial as one person managing two XRP Ledger addresses.
@@ -153,9 +153,9 @@ 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](reference-ledger-format.html#paychannel).
For more information on the PayChannel ledger object type, see [PayChannel ledger object](paychannel.html).
## 2. The payee checks specifics of the payment channel.
@@ -418,7 +418,7 @@ Response:
}
}
The payee should confirm that this transaction is successful in a validated ledger. For the full details, see [Reliable Transaction Submission](tutorial-reliable-transaction-submission.html).
The payee should confirm that this transaction is successful in a validated ledger. For the full details, see [Reliable Transaction Submission](reliable-transaction-submission.html).
## 9. When the payer and payee are done doing business, the payer requests for the channel to be closed.
@@ -471,7 +471,7 @@ Example `account_channels` response:
}
}
In this example, the `expiration` value 547073182 in [seconds since the Ripple Epoch](reference-rippled.html#specifying-time) maps to 2017-05-02T20:46:22Z, so any claims not redeemed by that time are no longer valid.
In this example, the `expiration` value 547073182 in [seconds since the Ripple Epoch][] maps to 2017-05-02T20:46:22Z, so any claims not redeemed by that time are no longer valid.
## 10. Anyone can close the expired channel.
@@ -481,7 +481,7 @@ The channel can remain on the ledger in an expired state indefinitely. This is b
Ripple recommends that the payer sends a second [PaymentChannelClaim transaction][] with the `tfClose` flag for this purpose. However, other accounts, even those not involved in the payment channel, can cause an expired channel to close.
The command to submit the transaction is the same as the previous example requesting channel expiration. (However, its resulting [auto-filled](reference-transaction-format.html#auto-fillable-fields) `Sequence` number, signature, and identifying hash are unique.)
The command to submit the transaction is the same as the previous example requesting channel expiration. (However, its resulting [auto-filled](transaction-common-fields.html#auto-fillable-fields) `Sequence` number, signature, and identifying hash are unique.)
Example of [submitting](reference-rippled.html#sign-and-submit-mode) a transaction to close an expired channel:
@@ -601,5 +601,7 @@ This concludes the tutorial of Payment Channel usage. Ripple encourages users to
{% include '_snippets/tx-type-links.md' %}
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

9
content/tutorials/use-simple-xrp-payments/cancel-or-skip-a-transaction.md
View File

@@ -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' %}

8
content/tutorials/use-simple-xrp-payments/reliable-transaction-submission.md
View File

@@ -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` API](rippled-api.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).
@@ -167,8 +167,8 @@ 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)
1. The [`rippled` API](rippled-api.html)
2. [RippleAPI](rippleapi-reference.html)
3. Any number of other software APIs layered on top of `rippled`

33
content/tutorials/xrp-ledger-businesses/become-an-xrp-ledger-gateway.md
View File

@@ -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](rippled-api.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.)
@@ -374,20 +374,20 @@ 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.
* [`rippled`](rippled-api.html) provides JSON-RPC and WebSocket APIs that can be used as a low-level interface to all core XRP Ledger functionality.
* [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
The DefaultRipple flag controls whether the balances in an accounting relationship [allowed to ripple](noripple.html) by default. Rippling is what allows customers to trade issuances, so a gateway must allow rippling on all the accounting relationships to its issuing address.
The DefaultRipple flag controls whether the balances in an accounting relationship [allowed to ripple](rippling.html) by default. Rippling is what allows customers to trade issuances, so a gateway must allow rippling on all the accounting relationships to its issuing address.
Before asking customers to create accounting relationships to its issuing address, a gateway should enable the DefaultRipple flag on that address. Otherwise, the gateway must individually disable the NoRipple flag for each accounting relationship that other addresses have created.
@@ -441,7 +441,7 @@ Response:
}
```
To confirm that an address has DefaultRipple enabled, look up the address using the [account_info command](reference-rippled.html#account-info), specifying a validated ledger version. Use [a bitwise-AND operator](https://en.wikipedia.org/wiki/Bitwise_operation#AND) to compare the `Flags` field with 0x00800000 (the [ledger flag lsfDefaultRipple](reference-ledger-format.html#accountroot-flags)). If the result of the bitwise-AND operation is nonzero, then the address has DefaultRipple enabled.
To confirm that an address has DefaultRipple enabled, look up the address using the [account_info command](reference-rippled.html#account-info), specifying a validated ledger version. Use [a bitwise-AND operator](https://en.wikipedia.org/wiki/Bitwise_operation#AND) to compare the `Flags` field with 0x00800000 (the [ledger flag lsfDefaultRipple](accountroot.html#accountroot-flags)). If the result of the bitwise-AND operation is nonzero, then the address has DefaultRipple enabled.
## Generating Source and Destination Tags
@@ -607,7 +607,7 @@ POST http://localhost:5005/
If you are using the [Authorized Trust Lines](authorized-trust-lines.html) feature, customers cannot hold balances you issue unless you first authorize their accounting relationships to you in the XRP Ledger.
To authorize an accounting relationship, submit a TrustSet transaction from your issuing address, with the user to trust as the `issuer` of the `LimitAmount`. Leave the `value` (the amount to trust them for) as **0**, and enable the [tfSetfAuth](reference-transaction-format.html#trustset-flags) flag for the transaction.
To authorize an accounting relationship, submit a TrustSet transaction from your issuing address, with the user to trust as the `issuer` of the `LimitAmount`. Leave the `value` (the amount to trust them for) as **0**, and enable the [tfSetfAuth](trustset.html#trustset-flags) flag for the transaction.
The following is an example of using a locally-hosted `rippled`'s [submit method][] to send a TrustSet transaction authorizing the customer address rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn to hold issuances of USD from the issuing address rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW:
@@ -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 method][] 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.
@@ -830,7 +830,7 @@ To submit transactions reliably, follow these guidelines:
* Use the `LastLedgerSequence` parameter. (RippleAPI does this by default.)
* Resubmit a transaction if it has not appeared in a validated ledger whose sequence number is less than or equal to the transaction's `LastLedgerSequence` parameter.
For more information, see [Reliable Transaction Submission](tutorial-reliable-transaction-submission.html).
For more information, see [Reliable Transaction Submission](reliable-transaction-submission.html).
## ripple.txt
@@ -840,3 +840,8 @@ The [ripple.txt](https://wiki.ripple.com/Ripple.txt) standard provides a way to
For example, if you run a validating `rippled` server, you can use ripple.txt to publish the public key of your validating server. You can also publish information about what currencies your gateway issues, and which XRP Ledger addresses you control, to protect against impostors or confusion.
<!-- STYLE_OVERRIDE: gateway, gateways -->
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

35
content/tutorials/xrp-ledger-businesses/list-xrp-as-an-exchange.md
View File

@@ -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)
@@ -187,13 +187,13 @@ Amounts of XRP are represented on the XRP Ledger as an unsigned integer count of
One drop (.000001 XRP) cannot be further subdivided. Keep this in mind when calculating and displaying FX rates between XRP and other assets.
For more information, see [Specifying Currency Amounts](reference-rippled.html#specifying-currency-amounts).
For more information, see [Specifying Currency Amounts][].
#### On-Ledger and Off-Ledger
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](accountset.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>
@@ -599,4 +599,7 @@ Off-Ledger Balances</td>
</table>
{% include '_snippets/tx-type-links.md' %}
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

112
dactyl-config.yml
View File

@@ -330,6 +330,15 @@ pages:
targets:
- local
- md: concepts/issued-currencies/issuing-and-operational-addresses.md
html: issuing-and-operational-addresses.html
funnel: Docs
doc_type: Concepts
category: Issued Currencies
blurb: Businesses sending transactions on the XRP Ledger automatically should set up separate addresses for different purposes to minimize risk.
targets:
- local
- md: concepts/issued-currencies/paths.md
html: paths.html
funnel: Docs
@@ -493,7 +502,7 @@ pages:
# Tutorials --------------------------------------------------------------------
- md: tutorials/tutorials.md
- name: Tutorials
html: tutorials.html
funnel: Docs
doc_type: Tutorials
@@ -508,6 +517,7 @@ pages:
doc_type: Tutorials
category: Get Started
template: template-landing-children.html
blurb: Get up and running with some of the resources you'll use to work with the XRP Ledger.
targets:
- local
@@ -516,6 +526,7 @@ pages:
funnel: Docs
doc_type: Tutorials
category: Get Started
blurb: Connect to the rippled API and get data about the shared ledger state.
targets:
- local
@@ -526,6 +537,7 @@ pages:
funnel: Docs
doc_type: Tutorials
category: Get Started
blurb: Build an entry-level JavaScript application for querying the XRP Ledger.
targets:
- local
@@ -537,6 +549,7 @@ pages:
doc_type: Tutorials
category: Use Simple XRP Payments
template: template-landing-children.html
blurb: Send and receive XRP Ledger transactions securely and robustly.
targets:
- local
@@ -547,6 +560,7 @@ pages:
funnel: Docs
doc_type: Tutorials
category: Use Simple XRP Payments
blurb: Build a system that can submit transactions to the XRP Ledger and get their final results safely and quickly.
targets:
- local
@@ -555,6 +569,7 @@ pages:
funnel: Docs
doc_type: Tutorials
category: Use Simple XRP Payments
blurb: Replace a pending transaction if it gets stuck from paying too low a transaction cost.
targets:
- local
@@ -563,6 +578,7 @@ pages:
funnel: Docs
doc_type: Tutorials
category: Use Simple XRP Payments
blurb: Find the results of previously-submitted transactions.
targets:
- local
@@ -608,12 +624,13 @@ pages:
# TODO: "Use Deposit Authorization to Block Unwanted Payments" (DOC-1555)
- md: tutorials/use-complex-payment-types/use-complex-payment-types.md
- name: Use Complex Payment Types
html: use-complex-payment-types.html
funnel: Docs
doc_type: Tutorials
category: Use Complex Payment Types
template: template-landing-children.html
blurb: Use advanced features like Escrow and Payment Channels to build smart applications on the XRP Ledger.
targets:
- local
@@ -741,14 +758,16 @@ pages:
# TODO: "Send a Cross-Currency Payment"
- md: tutorials/manage-issued-currencies/manage-issued-currencies.md
html: manage-issued-currencies.html
funnel: Docs
doc_type: Tutorials
category: Manage Issued Currencies
template: template-landing-children.html
targets:
- local
## This category commented out until DOC-1562 gets done
# - md: tutorials/manage-issued-currencies/manage-issued-currencies.md
# html: manage-issued-currencies.html
# funnel: Docs
# doc_type: Tutorials
# category: Manage Issued Currencies
# blurb: Use issued currencies for cross-currency payments, trading in the decentralized exchange, or as natively digital tokens.
# template: template-landing-children.html
# targets:
# - local
# TODO: Set up issuing/operational addresses, monitor changes to balances,
# freeze, enable/disable rippling, set transfer fees, use auth'd trust lines
@@ -758,6 +777,7 @@ pages:
funnel: Docs
doc_type: Tutorials
category: XRP Ledger Businesses
blurb: Follow best practices for businesses that use the XRP Ledger, such as exchanges and gateways.
template: template-landing-children.html
targets:
- local
@@ -780,11 +800,12 @@ pages:
# TODO: identify your accounts with ripple.txt (to come later)
- md: tutorials/manage-the-rippled-server/manage-the-rippled-server.md
- name: Manage the rippled Server
html: manage-the-rippled-server.html
funnel: Docs
doc_type: Tutorials
category: Manage the rippled Server
blurb: Build, install, and run the rippled server. Configure it to your use case and troubleshoot problems.
template: template-landing-children.html
targets:
- local
@@ -862,8 +883,7 @@ pages:
- local
# TODO: troubleshoot rippled,
# run a validator, run in stand-alone mode, set up private peers, run in
# a cluster
# run a validator, run in stand-alone mode, set up private peers
# References -------------------------------------------------------------------
@@ -2206,41 +2226,39 @@ pages:
# --------------- end "rippled API" section --------------------------------
# # Temporarily commented out to make building the dev portal faster
# - name: RippleAPI Reference # name is required for remote-sourced files
# md: https://raw.githubusercontent.com/ripple/ripple-lib/0.21.0/docs/index.md
# html: rippleapi-reference.html
# funnel: Docs
# doc_type: References
# category: RippleAPI for JavaScript
# blurb: Official client library to the XRP Ledger. Available for JavaScript only.
# curated_anchors:
# - name: Transactions
# anchor: "#transaction-overview"
# - name: Basic Types
# anchor: "#basic-types"
# - name: Methods
# anchor: "#api-methods"
# filters:
# - remove_doctoc
# - add_version
# targets:
# - local
- name: RippleAPI Reference # name is required for remote-sourced files
md: https://raw.githubusercontent.com/ripple/ripple-lib/0.21.0/docs/index.md
html: rippleapi-reference.html
funnel: Docs
doc_type: References
category: RippleAPI for JavaScript
blurb: Official client library to the XRP Ledger. Available for JavaScript only.
curated_anchors:
- name: Transactions
anchor: "#transaction-overview"
- name: Basic Types
anchor: "#basic-types"
- name: Methods
anchor: "#api-methods"
filters:
- remove_doctoc
- add_version
targets:
- local
# # Temporarily commented out to make building the dev portal faster
# - md: references/data-api.md
# html: data-api.html
# funnel: Docs
# doc_type: References
# category: Data API
# blurb: Access more XRP Ledger data, including transaction history and analytics.
# curated_anchors:
# - name: Methods
# anchor: "#api-method-reference"
# - name: API Conventions
# anchor: "#api-conventions"
# targets:
# - local
- md: references/data-api.md
html: data-api.html
funnel: Docs
doc_type: References
category: Data API
blurb: Access more XRP Ledger data, including transaction history and analytics.
curated_anchors:
- name: Methods
anchor: "#api-method-reference"
- name: API Conventions
anchor: "#api-conventions"
targets:
- local
# --------------- end "Docs" section -------------------------------------------