diff --git a/content/concept-fees.md b/content/concept-fees.md index 81edf08bbe..3fd6c68516 100644 --- a/content/concept-fees.md +++ b/content/concept-fees.md @@ -1,26 +1,26 @@ -# Fees (Disambiguation) # +# Fees (Disambiguation) The XRP Ledger is a decentralized ledger, secured by cryptography and operated by a distributed peer-to-peer network of servers. This means that no one party, not even Ripple, can require a fee for access to the network. However, the rules of the XRP Ledger include several types of fees, including neutral fees which protect the ledger against abuse. These neutral fees are not paid to anyone. There are also several optional ways that users can collect fees from each other, both inside and outside the XRP Ledger. -## In the Ledger ## +## In the Ledger -### Neutral Fees ### +### Neutral Fees The _**transaction cost**_ (sometimes called the transaction fee) is a miniscule amount of XRP destroyed to send a transaction. This cost scales with the load of the network, which protects the peer-to-peer network from spam. See [Transaction Cost](concept-transaction-cost.html) for more information. The _**reserve requirement**_ is a minimum amount of XRP that an account must hold. It increases with the number of objects the account owns in the ledger. This disincentivizes users from increasing the size of the ledger carelessly or maliciously. See [Reserves](concept-reserves.html) for more information. -### Optional Fees ### +### Optional Fees _**Transfer fees**_ are optional percentage fees that issuers can charge to transfer the currencies they issue to other addresses within the XRP Ledger. See [Transfer Fees](concept-transfer-fees.html) for more information. _**Trust line quality**_ is a setting that allows an account to value balances on a trust line at higher or lower than face value. This can lead to situations that are like charging a fee. Trust line quality does not apply to XRP, which is not tied to a trust line. -## Outside the Ledger ## +## Outside the Ledger Although the fees described above are the only fees built into the XRP Ledger, people can still invent ways to charge fees associated with the ledger. For example, financial institutions commonly charge their customers to send money into and out of the XRP Ledger. diff --git a/content/concept-issuing-and-operational-addresses.md b/content/concept-issuing-and-operational-addresses.md index 820067b1eb..6bf7b81f45 100644 --- a/content/concept-issuing-and-operational-addresses.md +++ b/content/concept-issuing-and-operational-addresses.md @@ -1,8 +1,8 @@ -# Issuing and Operational Addresses # +# Issuing and Operational Addresses {% include 'snippets/issuing-and-operational-addresses-intro.md' %} -## Funds Lifecycle ## +## Funds Lifecycle All non-XRP currency balances (issuances) in the XRP Ledger are tied to accounting relationships between two XRP Ledger addresses. When a financial institution uses Ripple's recommended separation of roles, funds relating to that institution tend to flow in a cycle. @@ -12,33 +12,33 @@ When the issuing address sends payments, it creates balances in the accounting r 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](concept-paths.html) that connect multiple issuers through order books and [liquidity providers who allow their funds to ripple](concept-noripple.html). -## Issuing Address ## +## Issuing Address The issuing address is like a vault. Partners, customers, and operational addresses create accounting relationships (trust lines) to the issuing address, but this address sends as few transactions as possible. Periodically, a human operator creates and signs a transaction from the issuing address to refill the balances of a standby or operational address. Ideally, the secret key used to sign these transactions should never be accessible from any internet-connected computer. Unlike a vault, the issuing address can receive payments directly from customers and partners. Since all transactions in the XRP Ledger are public, automated systems can monitor for payments to the issuing address without needing a secret key. -### Issuing Address Compromise ### +### Issuing Address Compromise If a malicious actor learns the secret key behind a institution's issuing address, that actor can create new issuances without limit and trade them in the decentralized exchange. This would make it difficult for the financial institution to distinguish legitimately-obtained issuances and redeem them fairly. If a financial institution loses control of its issuing address, the institution must create a new issuing address, and all users who have accounting relationships with the old issuing address must create new accounting relationships with the new address. -### Multiple Issuing Addresses ### +### Multiple Issuing Addresses A financial institution can issue more than one currency in the XRP Ledger from a single issuing address. However, there are some settings that apply equally to all currencies issued from an address, including the percentage for [transfer fees](concept-transfer-fees.html) and the [global freeze](concept-freeze.html) status. If the financial institution wants the flexibility to manage settings differently for each currency, the institution must use a different issuing address for each currency. -## Operational Addresses ## +## Operational Addresses An operational address is like a cash register. It makes payments on behalf of the institution by transferring issuances to customers and partners. To sign transactions automatically, the secret key for an operational address must be stored on a server that is connected to the internet. (The secret key can be stored encrypted, but the server must decrypt it to sign transactions.) Customers and partners do not, and should not, create accounting relationships with an operational address. Each operational address has a limited balance of issuances. When the balance of an operational address gets low, the financial institution refills it by sending a payment from the issuing address or a standby address. -### Operational Address Compromise ### +### Operational Address Compromise If a malicious actor learns the secret key behind an operational address, the financial institution can only lose as much currency as that operational address holds. The institution can switch to a new operational address with no action from customers and partners. -## Standby Addresses ## +## Standby Addresses Another optional step that an institution can take to balance risk and convenience is to use "standby addresses" as an intermediate step between the issuing address and operational addresses. The institution can fund additional XRP Ledger addresses as standby addresses, whose keys are not stored online, but are entrusted to different trusted users. @@ -46,6 +46,6 @@ When an operational address is running low on funds, a trusted user can use a st As with operational addresses, a standby address must have an accounting relationship with the issuing address, and not with customers or partners. All precautions that apply to operational addresses also apply to standby addresses. -### Standby Address Compromise ### +### Standby Address Compromise If a standby address is compromised, the consequences are like an operational address being compromised. A malicious actor can steal any balances possessed by the standby address, and the financial institution can change to a new standby address with no action from customers and partners. diff --git a/content/concept-noripple.md b/content/concept-noripple.md index 8ca8c83dd3..7f8210e3fe 100644 --- a/content/concept-noripple.md +++ b/content/concept-noripple.md @@ -2,7 +2,7 @@ In the XRP Ledger, the "NoRipple" flag is a setting on a trust line. When an address enables the NoRipple flag on two trust lines, payments from third parties cannot "ripple" through that address on those trust lines. This protects liquidity providers from having balances shift unexpectedly between different issuers of the same currency. -## Background ## +## Background "Rippling" occurs when more than one trust line is adjusted to make a payment. For example, if Alice owes Charlie money, and Alice also owes Bob money, then you could represent that in the XRP Ledger with trust lines like so: @@ -14,7 +14,7 @@ If Bob wants to pay $3 to Charlie, then he could say, "Alice, take $3 of the mon We call this process, where two addresses pay each other by adjusting the balances of trust lines in between them, "rippling". This is a useful and important feature of the XRP Ledger. Rippling occurs when addresses are linked by trust lines that use the same [currency code](reference-rippled.html#currency-codes). The issuer does not need to be the same: in fact, larger chains always involve changing issuers. -## Justification ## +## Justification Sometimes you do not want your balances to ripple. For example, imagine Emily has money issued by two different financial institutions, like so @@ -32,15 +32,15 @@ For example: Now the above scenario, where Charlie pays Daniel while rippling through Emily's address, is no longer possible. -## Specifics ## +## Specifics The NoRipple flag makes certain paths invalid, so that they cannot be used to make payments. A path is considered invalid if and only if it enters **and** exits an address node through trust lines where NoRipple has been enabled for that address. ![Diagram demonstrating that NoRipple has to be set on both trust lines by the same address to do anything](img/noripple-06.png) -## Technical Details ## +## Technical Details -### Enabling / Disabling NoRipple ### +### Enabling / Disabling NoRipple The NoRipple flag can only be enabled on a trust line if the address has a positive or zero balance on that trust line. This is so that the feature cannot be abused to default on the obligation the trust line balance represents. (Of course, you can still default by abandoning the address.) @@ -49,7 +49,7 @@ In the [`rippled` APIs](reference-rippled.html), you can enable the NoRipple fla In [RippleAPI](reference-rippleapi.html), you can enable the NoRipple flag by sending a [Trustline transaction](reference-rippleapi.html#preparetrustline) transaction with the `ripplingDisabled` field of the trust line set to `true`. -### Looking Up NoRipple Status ### +### Looking Up NoRipple Status In the case of two accounts that mutually trust each other, the NoRipple flag is tracked separately for each account. diff --git a/content/concept-paths.md b/content/concept-paths.md index 7eaa4913db..5245afea52 100644 --- a/content/concept-paths.md +++ b/content/concept-paths.md @@ -6,7 +6,7 @@ A single Payment transaction in the XRP Ledger can use multiple paths, combining Since XRP can be sent directly to any address, an XRP-to-XRP transaction does not use any paths. -## Path Steps ## +## Path Steps A path is made of steps that connect the sender to the receiver of the payment. Every step is either: @@ -23,9 +23,9 @@ In both types of steps, each intermediate address gains and loses approximately -# Technical Details # +# Technical Details -## Pathfinding ## +## Pathfinding The `rippled` API has two methods that can be used for pathfinding. The [`ripple_path_find` command](reference-rippled.html#ripple-path-find) does a one-time lookup of possible path sets. The [`path_find` command](reference-rippled.html#path-find) (WebSocket only) expands on the search with follow-up responses whenever a ledger closes or the server finds a better path. @@ -36,7 +36,7 @@ You can have `rippled` automatically fill in paths when you sign it, by includin Finding paths is a very challenging problem that changes slightly every few seconds as new ledgers are validated, so `rippled` is not designed to find the absolute best path. Still, you can find several possible paths and estimate the cost of delivering a particular amount. -## Implied Steps ## +## Implied Steps By convention, several steps of a path are implied by the [fields of the Payment transaction](reference-transaction-format.html#payment): specifically, the `Account` (sender), `Destination` (receiver), `Amount` (currency and amount to be delivered) and `SendMax` (currency and amount to be sent, if specified). The implied steps are as follows: @@ -47,7 +47,7 @@ By convention, several steps of a path are implied by the [fields of the Payment * Finally, last step of a path is always implied to be the receiver of a transaction, as defined by the transaction's `Destination` field. -## Default Paths ## +## Default Paths In addition to explicitly specified paths, a transaction can execute along the _default path_. The default path is the simplest possible way to connect the [implied steps](#implied-steps) of the transaction. @@ -64,7 +64,7 @@ The following diagram enumerates all possible default paths: You can use the [`tfNoDirectRipple` flag](reference-transaction-format.html#payment-flags) to disable the default path. In this case, the transaction can only execute using the paths explicitly included in the transaction. Traders can use this option to take arbitrage opportunities. -## Path Specifications ## +## Path Specifications A path set is an array. Each member of the path set is another array that represents an individual _path_. Each member of a path is an object that specifies the step. A step has the following fields: diff --git a/content/concept-reserves.md b/content/concept-reserves.md index cb9b21fcfe..a115a310b3 100644 --- a/content/concept-reserves.md +++ b/content/concept-reserves.md @@ -1,4 +1,4 @@ -# Reserves # +# Reserves The XRP Ledger applies _reserve requirements_, in XRP, to protect the shared global ledger from growing excessively large as the result of spam or malicious usage. The goal is to constrain the growth of the ledger to match improvements in technology so that a current commodity-level machine can always fit the current ledger in RAM and the full ledger history on disk. @@ -7,7 +7,7 @@ To submit transactions, an address must hold a minimum amount of XRP in the shar The current minimum reserve requirement is **20 XRP**. (This is the cost of an address that owns no other objects in the ledger.) -## Base Reserve and Owner Reserve ## +## Base Reserve and Owner Reserve The reserve requirement is divided into two parts: @@ -15,7 +15,7 @@ The reserve requirement is divided into two parts: * The **Owner Reserve** is an increase to the reserve requirement for each object that the address owns in the ledger. Currently, this is 5 XRP (`5000000` drops) per item. -### Owner Reserves ### +### Owner Reserves Many objects in the ledger are owned by a particular address, and count toward the reserve requirement of that address. When objects are removed from the ledger, they no longer count against their owner's reserve requirement. @@ -26,13 +26,13 @@ Many objects in the ledger are owned by a particular address, and count toward t - [Payment Channels](tutorial-paychan.html) are owned by the address that created them. - [Owner directories](reference-ledger-format.html#directorynode) list all the ledger objects that contribute to an address's owner reserve. However, the owner directory itself does not count towards the reserve. -#### Owner Reserve Edge Cases #### +#### Owner Reserve Edge Cases The XRP Ledger considers an [OfferCreate transaction][] to be an explicit statement of willingness to hold an asset. Consuming the offer automatically creates a trust line (with limit 0, and a balance above that limit) for the `taker_pays` currency if such a trust line does not exist. However, if the offer's owner does not hold enough XRP to also meet the owner reserve requirement of the new trust line, the offer is considered unfunded. See also: [Lifecycle of an Offer](reference-transaction-format.html#lifecycle-of-an-offer). -## Going Below the Reserve Requirement ## +## Going Below the Reserve Requirement During transaction processing, the [transaction cost](concept-transaction-cost.html) destroys some of the sending address's XRP balance. This can cause an address's XRP to go below the reserve requirement. @@ -40,7 +40,7 @@ When an address holds less XRP than its current reserve requirement, it cannot s **Tip:** When an address is below the reserve requirement, it can send new [OfferCreate transactions][] to acquire more XRP, or other currencies on its existing trust lines. These transactions cannot create new [trust lines](reference-ledger-format.html#ripplestate), or [Offer nodes in the ledger](reference-ledger-format.html#offer), so they can only execute trades that consume Offers that are already in the order books. -## Changing the Reserve Requirements ## +## Changing the Reserve Requirements The XRP Ledger has a mechanism to adjust the reserve requirements for long-term changes in the value of XRP. Any changes have to be approved by the consensus process. See [Fee Voting](concept-fee-voting.html) for more information. diff --git a/content/concept-stand-alone-mode.md b/content/concept-stand-alone-mode.md index f5bbf41cbb..8179588e8b 100644 --- a/content/concept-stand-alone-mode.md +++ b/content/concept-stand-alone-mode.md @@ -1,5 +1,4 @@ -Stand-Alone Mode -=============================================================================== +# Stand-Alone Mode You can run `rippled` in stand-alone mode without a consensus of trusted servers. In stand-alone mode, `rippled` does not communicate with any other servers in the XRP Ledger peer-to-peer network, but you can do most of the same actions on your local server only. Stand-alone provides a method for testing `rippled` behavior without being tied to the live network. For example, you can [test the effects of Amendments](concept-amendments.html#testing-amendments) before those Amendments have gone into effect across the decentralized network. @@ -11,8 +10,8 @@ When you run `rippled` in stand-alone mode, you have to tell it what ledger vers **Caution:** In stand-alone mode, you must [manually advance the ledger](#advancing-ledgers-in-stand-alone-mode). -New Genesis Ledger -------------------------------------------------------------------------------- +## New Genesis Ledger + In stand-alone mode, you can have `rippled` create a new genesis ledger. This provides a known state, with none of the ledger history from the production XRP Ledger. (This is very useful for unit tests, among other things.) * To start `rippled` in stand-alone mode with a new genesis ledger, use the [`-a`](https://wiki.ripple.com/Rippled#--standalone.2C_-a) and [`--start`](https://wiki.ripple.com/Rippled#--start) options: @@ -32,11 +31,11 @@ In a genesis ledger, the [genesis address](concept-accounts.html#special-address [New in: rippled 0.50.0][] If you start a new genesis ledger with `--start`, all The genesis ledger contains an [EnableAmendment pseudo-transaction](reference-transaction-format.html#enableamendment) to turn on all [Amendments](concept-amendments.html) natively supported by the `rippled` server, except for amendments that you explicitly disable in the configuration file. The effects of those amendments are available starting from the very next ledger version. -Load Saved Ledger -------------------------------------------------------------------------------- +## Load Saved Ledger + 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)). -### 1. Start `rippled` normally. ### +### 1. Start `rippled` normally. To load an existing ledger, you must first retrieve that ledger from the network. Start `rippled` in online mode as normal: @@ -44,7 +43,7 @@ To load an existing ledger, you must first retrieve that ledger from the network rippled --conf=/path/to/rippled.cfg ``` -### 2. Wait until `rippled` is synced. ### +### 2. Wait until `rippled` is synced. Use the [`server_info` command](reference-rippled.html#server-info) to check the state of your server relative to the network. Your server is synced when the `server_state` value shows any of the following values: @@ -54,7 +53,7 @@ Use the [`server_info` command](reference-rippled.html#server-info) to check the For more information, see [Possible Server States](reference-rippled.html#possible-server-states). -### 3. (Optional) Retrieve specific ledger versions. ### +### 3. (Optional) Retrieve specific ledger versions. If you only want the most recent ledger, you can skip this step. @@ -62,7 +61,7 @@ If you want to load a specific historical ledger version, use the [`ledger_reque If you want to replay a specific historical ledger version, you must fetch both the ledger version to replay and the ledger version before it. (The previous ledger version sets up the initial state upon which you apply the changes described by the ledger version you replay.) -### 4. Shut down `rippled`. ### +### 4. Shut down `rippled`. Use the [`stop` command](reference-rippled.html#stop): @@ -70,7 +69,7 @@ Use the [`stop` command](reference-rippled.html#stop): rippled stop --conf=/path/to/rippled.cfg ``` -### 5. Start `rippled` in stand-alone mode. ### +### 5. Start `rippled` in stand-alone mode. To load the most recent ledger version, you can use the [`-a`](https://wiki.ripple.com/Rippled#--standalone.2C_-a) and [`--load`](https://wiki.ripple.com/Rippled#--load) options when starting the server: @@ -84,7 +83,7 @@ To instead load a specific historical ledger, use the [`--load`](https://wiki.ri rippled -a --load --ledger 19860944 --conf=/path/to/rippled.cfg ``` -### 6. Manually advance the ledger. ### +### 6. Manually advance the ledger. When you load a ledger with `--ledger` in stand-alone mode, it goes to the current open ledger, so you must [manually advance the ledger](#advancing-ledgers-in-stand-alone-mode): @@ -93,8 +92,7 @@ rippled ledger_accept --conf=/path/to/rippled.cfg ``` -Advancing Ledgers in Stand-Alone Mode -------------------------------------------------------------------------------- +## Advancing Ledgers in Stand-Alone Mode In stand-alone mode, `rippled` does not communicate to other members of the peer-to-peer network or participate in a consensus process. Instead, you must manually advance the ledger index using the [`ledger_accept` command](reference-rippled.html#ledger-accept): diff --git a/content/concept-transaction-cost.md b/content/concept-transaction-cost.md index 9254207e3d..6a032daa85 100644 --- a/content/concept-transaction-cost.md +++ b/content/concept-transaction-cost.md @@ -1,17 +1,17 @@ -# Transaction Cost # +# Transaction Cost To protect the XRP Ledger from being disrupted by spam and denial-of-service attacks, each transaction must destroy a small amount of [XRP](https://ripple.com/xrp-portal/). This _transaction cost_ is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network. Every transaction must [specify how much XRP to destroy](#specifying-the-transaction-cost) to pay the transaction cost. -## Current Transaction Cost ## +## Current Transaction Cost The current minimum transaction cost required by the network for a standard transaction is **0.00001 XRP** (10 drops). It sometimes increases due to higher than usual load. You can also [query `rippled` for the current transaction cost](#querying-the-transaction-cost). -### Special Transaction Costs ### +### Special Transaction Costs Some transactions have different transaction costs: @@ -23,12 +23,12 @@ Some transactions have different transaction costs: | [EscrowFinish Transaction with Fulfillment](reference-transaction-format.html#escrowfinish) | 10 drops × (33 + (Fulfillment size in bytes ÷ 16)) | -## Beneficiaries of the Transaction Cost ## +## Beneficiaries of the Transaction Cost The transaction cost is not paid to any party: the XRP is irrevocably destroyed. Since no new XRP can ever be created, this makes XRP more scarce and benefits all holders of XRP by making XRP more valuable. -## Load Cost and Open Ledger Cost ## +## Load Cost and Open Ledger Cost When the [FeeEscalation amendment](concept-amendments.html#feeescalation) is enabled, there are two thresholds for the transaction cost: @@ -42,11 +42,11 @@ This divides transactions into roughly three categories: * Transactions in between, which get [queued for a later ledger version](#queued-transactions). -## Local Load Cost ## +## Local Load Cost Each `rippled` server maintains a cost threshold based on its current load. If you submit a transaction with a `Fee` value that is lower than current load-based transaction cost of the `rippled` server, that server neither applies nor relays the transaction. (**Note:** If you submit a transaction through an [admin connection](reference-rippled.html#connecting-to-rippled), the server applies and relays the transaction as long as the transaction meets the un-scaled minimum transaction cost.) A transaction is very unlikely to survive [the consensus process](https://ripple.com/build/ripple-ledger-consensus-process/) unless its `Fee` value meets the requirements of a majority of servers. -## Open Ledger Cost ## +## Open Ledger Cost The `rippled` server has a second mechanism for enforcing the transaction cost, called the _open ledger cost_. A transaction can only be included in the open ledger if it meets the open ledger cost requirement in XRP. Transactions that do not meet the open ledger cost may be [queued for a following ledger](#queued-transactions) instead. @@ -56,15 +56,15 @@ The open ledger cost requirement is [proportional to the normal cost of the tran See also: [Fee Escalation explanation in `rippled` repository](https://github.com/ripple/rippled/blob/release/src/ripple/app/misc/FeeEscalation.md). -### Queued Transactions ### +### Queued Transactions -When `rippled` receives a transaction that meet the server's local load cost but not the [open ledger cost](#open-ledger-cost), the server estimates whether the transaction is "likely to be included" in a later ledger. If so, the server adds the transaction to the transaction queue and relays the transaction to other members of the network. Otherwise, the server discards the transaction. The server tries to minimize the amount of network load caused by transactions that would not pay a transaction cost, since [the transaction cost only applies when a transaction is included in a validated ledger](#transaction-costs-and-failed-transactions). +When `rippled` receives a transaction that meets the server's local load cost but not the [open ledger cost](#open-ledger-cost), the server estimates whether the transaction is "likely to be included" in a later ledger. If so, the server adds the transaction to the transaction queue and relays the transaction to other members of the network. Otherwise, the server discards the transaction. The server tries to minimize the amount of network load caused by transactions that would not pay a transaction cost, since [the transaction cost only applies when a transaction is included in a validated ledger](#transaction-costs-and-failed-transactions). When the current open ledger closes and the server starts a new open ledger, the server starts taking transactions from the queue to include in the new open ledger. The transaction queue is sorted with the transactions that would pay the highest transaction cost first, proportional to the [reference cost](#reference-transaction-cost) of those transactions. Transactions that pay the same transaction cost are queued in the order the server receives them. **Note:** When `rippled` queues a transaction, the provisional [transaction response code](reference-transaction-format.html#transaction-results) is `terQUEUED`. This means that the transaction is likely to succeed in a future ledger version. As with all provisional response codes, the outcome of the transaction is not final until the transaction is either included in a validated ledger, or [rendered permanently invalid](reference-transaction-format.html#finality-of-results). -#### Queuing Restrictions #### +#### Queuing Restrictions The `rippled` server uses a variety of heuristics to estimate which transactions are "likely to be included in a ledger." The current implementation uses the following rules to decide which transactions to queue: @@ -74,7 +74,7 @@ The `rippled` server uses a variety of heuristics to estimate which transactions * If a transaction affects how the sending address authorizes transactions, no other transactions from the same address can be queued behind it. [New in: rippled 0.32.0][] * If the transaction includes a `LastLedgerSequence` field, the value of that field must be at least **the current ledger index + 2**. -#### Fee Averaging #### +#### Fee Averaging [New in: rippled 0.33.0][] @@ -89,11 +89,11 @@ This feature helps you work around a particular situation. If you submitted one If none of the above occur, transactions can stay in the queue for a theoretically unlimited amount of time, while other senders can "cut in line" by submitting transactions with higher transaction costs. Since signed transactions are immutable, you cannot increase the transaction cost of the queued transactions to increase their priority. If you do not want to invalidate the previously submitted transactions, fee averaging provides a workaround. If you increase the transaction cost of your new transaction to compensate, you can ensure the queued transactions are included in an open ledger right away. -## Reference Transaction Cost ## +## Reference Transaction Cost The "Reference Transaction" is the cheapest (non-free) transaction, in terms of the necessary [transaction cost](concept-transaction-cost.html) before load scaling. Most transactions have the same cost as the reference transaction. Some transactions, such as [multi-signed transactions](reference-transaction-format.html#multi-signing), require a multiple of this cost instead. When the open ledger cost escalates, the requirement is proportional to the basic cost of the transaction. -### Fee Levels ### +### Fee Levels _Fee levels_ represent the proportional difference between the minimum cost and the actual cost of a transaction. The [Open Ledger Cost](#open-ledger-cost) is measured in fee levels instead of absolute cost. See the following table for a comparison: @@ -105,20 +105,20 @@ _Fee levels_ represent the proportional difference between the minimum cost and | [EscrowFinish transaction](reference-transaction-format.html#escrowfinish) with 32-byte preimage. | 350 | 256 | 700 | 512 | -## Querying the Transaction Cost ## +## Querying the Transaction Cost The `rippled` APIs have two ways to query the local load-based transaction cost: the `server_info` command (intended for humans) and the `server_state` command (intended for machines). If the [FeeEscalation amendment](concept-amendments.html#feeescalation) is enabled, you can use the [`fee` command](reference-rippled.html#fee) to check the open ledger cost. -### server_info ### +### server_info The [`server_info` command](reference-rippled.html#server-info) reports the unscaled minimum XRP cost, as of the previous ledger, as `validated_ledger.base_fee_xrp`, in the form of decimal XRP. The actual cost necessary to relay a transaction is scaled by multiplying that `base_fee_xrp` value by the `load_factor` parameter in the same response, which represents the server's current load level. In other words: **Current Transaction Cost in XRP = `base_fee_xrp` × `load_factor`** -### server_state ### +### server_state The [`server_state` command](reference-rippled.html#server-state) returns a direct representation of `rippled`'s internal load calculations. In this case, the effective load rate is the ratio of the current `load_factor` to the `load_base`. The `validated_ledger.base_fee` parameter reports the minimum transaction cost in [drops of XRP](reference-rippled.html#specifying-currency-amounts). This design enables `rippled` to calculate the transaction cost using only integer math, while still allowing a reasonable amount of fine-tuning for server load. The actual calculation of the transaction cost is as follows: @@ -126,7 +126,7 @@ The [`server_state` command](reference-rippled.html#server-state) returns a dire -## Specifying the Transaction Cost ## +## Specifying the Transaction Cost Every signed transaction must include the transaction cost in the [`Fee` field](reference-transaction-format.html#common-fields). Like all fields of a signed transaction, this field cannot be changed without invalidating the signature. @@ -135,7 +135,7 @@ As a rule, the XRP Ledger executes transactions _exactly_ as they are signed. (T Before signing a transaction, we recommend [looking up the current load-based transaction cost](#querying-the-transaction-cost). If the transaction cost is high due to load scaling, you may want to wait for it to decrease. If you do not plan on submitting the transaction immediately, we recommend specifying a slightly higher transaction cost to account for future load-based fluctuations in the transaction cost. -### Automatically Specifying the Transaction Cost ### +### Automatically Specifying the Transaction Cost When you sign a transaction online, you can omit the `Fee` field. In this case, `rippled` or [RippleAPI](reference-rippleapi.html) checks the state of the peer-to-peer network for the current requirement and adds a `Fee` value before signing the transaction. However, there are several drawbacks and limitations to automatically filling in the transaction cost in this manner: @@ -148,7 +148,7 @@ When you sign a transaction online, you can omit the `Fee` field. In this case, -## Transaction Costs and Failed Transactions ## +## Transaction Costs and Failed Transactions Since the purpose of the transaction cost is to protect the XRP Ledger peer-to-peer network from excessive load, it should apply to any transaction that gets distributed to the network, regardless of whether or not that transaction succeeds. However, to affect the shared global ledger, a transaction must be included in a validated ledger. Thus, `rippled` servers try to include failed transactions in ledgers, with [`tec` status codes](reference-transaction-format.html#result-categories) ("tec" stands for "Transaction Engine - Claimed fee only"). @@ -156,14 +156,14 @@ The transaction cost is only debited from the sender's XRP balance when the tran If a transaction's failure is [final](reference-transaction-format.html#finality-of-results), the `rippled` server does not relay it to the network. The transaction does not get included in a validated ledger, so it cannot have any effect on anyone's XRP balance. -### Insufficient XRP ### +### Insufficient XRP When a `rippled` server initially evaluates a transaction, it rejects the transaction with the error code `terINSUF_FEE_B` if the sending account does not have a high enough XRP balance to pay the XRP transaction cost. Since this is a `ter` (Retry) code, the `rippled` server retries the transaction without relaying it to the network, until the transaction's outcome is [final](reference-transaction-format.html#finality-of-results). When a transaction has already been distributed to the network, but the account does not have enough XRP to pay the transaction cost, the result code `tecINSUFF_FEE` occurs instead. In this case, the account pays all the XRP it can, ending with 0 XRP. This can occur because `rippled` decides whether to relay the transaction to the network based on its in-progress ledger, but transactions may be dropped or reordered when building the consensus ledger. -## Key Reset Transaction ## +## Key Reset Transaction As a special case, an account can send a [SetRegularKey](reference-transaction-format.html#setregularkey) transaction with a transaction cost of `0`, as long as the account's [lsfPasswordSpent flag](reference-ledger-format.html#accountroot-flags) is disabled. This transaction must be signed by the account's _master key pair_. Sending this transaction enables the lsfPasswordSpent flag. @@ -174,7 +174,7 @@ The [lsfPasswordSpent flag](reference-ledger-format.html#accountroot-flags) star When the [FeeEscalation amendment](concept-amendments.html#feeescalation) is enabled, `rippled` prioritizes key reset transactions above other transactions even though the nominal transaction cost of a key reset transaction is zero. -## Changing the Transaction Cost ## +## Changing the Transaction Cost The XRP Ledger has a mechanism for changing the minimum transaction cost to account for long-term changes in the value of XRP. Any changes have to be approved by the consensus process. See [Fee Voting](concept-fee-voting.html) for more information. diff --git a/content/concept-transfer-fees.md b/content/concept-transfer-fees.md index 1077ccb86c..216edf0c33 100644 --- a/content/concept-transfer-fees.md +++ b/content/concept-transfer-fees.md @@ -1,4 +1,4 @@ -# Transfer Fees # +# Transfer Fees The `TransferRate` setting in the XRP Ledger allows [financial institutions that issue currency in the XRP Ledger](tutorial-gateway-guide.html) to charge users a _transfer fee_ for sending the currencies issued by that financial institution. The sender of the transfer is debited an extra percentage based on the transfer fee, while the recipient of the transfer is credited the intended amount. The difference is the transfer fee, which becomes the property of the issuing address, and is no longer tracked in the XRP Ledger. The transfer fee does not apply when sending or receiving _directly_ to and from the issuing account, but it does apply when transferring from an [operational address][] to another user. @@ -13,7 +13,7 @@ The following diagram shows an XRP Ledger payment of 2 EUR.ACME from Alice to Ch ![Alice sends 2,02€, Charlie receives 2,00€, and ACME owes 0,02€ less in the XRP Ledger](img/e2g-with_transferrate.png) -## Transfer Fees in Payment Paths ## +## Transfer Fees in Payment Paths @@ -33,7 +33,7 @@ The transfer fee is represented by a setting on the [issuing address][]. The tra **Note:** The [fix1201 amendment](concept-amendments.html), introduced in `rippled` v0.80.0 and enabled on 2017-11-14, lowered the maximum transfer fee to 100% from an effective limit of approximately 329% (based on the maximum size of a 32-bit integer). The ledger may still contain accounts with a transfer fee setting higher than 100% (a `TransferRate` of `2000000000`). Any transfer fees already set continue to operate at their stated rate. -## RippleAPI ## +## RippleAPI In RippleAPI, the transfer fee is specified in the `transferRate` field, as a decimal which represents the amount you must send for the recipient to get 1 unit of the same currency. A `transferRate` of `1.005` is equivalent to a transfer fee of 0.5%. By default, the `transferRate` is set to no fee. The value of `transferRate` cannot be less than `1.0` or more than `2.0`. The value `null` is a special case for no fee, equivalent to `1000000000`. @@ -41,7 +41,7 @@ A financial institution can send a [Settings transaction](reference-rippleapi.ht You can check an account's `transferRate` with the [getSettings method](reference-rippleapi.html#getsettings). -## rippled ## +## rippled In `rippled`'s JSON-RPC and WebSocket APIs, the transfer fee is specified in the `TransferRate` field, as an integer which represents the amount you must send for the recipient to get 1 billion units of the same currency. A `TransferRate` of `1005000000` is equivalent to a transfer fee of 0.5%. By default, the `TransferRate` is set to no fee. The value of `TransferRate` cannot be set to less than `1000000000` or more than `2000000000` (a "100%" fee). The value `0` is special case for no fee, equivalent to `1000000000`. diff --git a/content/reference-data-api.md b/content/reference-data-api.md index dc683dff88..4a54a289b7 100644 --- a/content/reference-data-api.md +++ b/content/reference-data-api.md @@ -1,5 +1,4 @@ -Ripple Data API v2 -================== +# Ripple Data API v2 The Ripple Data API v2 provides access to information about changes in the XRP Ledger, including transaction history and processed analytical data. This information is stored in a dedicated database, which frees `rippled` servers to keep fewer historical ledger versions. The Data API v2 also acts as data source for applications such as [XRP Charts](https://xrpcharts.ripple.com/) and [ripple.com](https://www.ripple.com). @@ -8,7 +7,7 @@ Ripple provides a live instance of the Data API with as complete a transaction r [**https://data.ripple.com**](https://data.ripple.com) -## More Information ## +## More Information The Ripple Data API v2 replaces the Historical Database v1 and the [Charts API](https://github.com/ripple/ripple-data-api/). * [API Methods](#api-method-reference) @@ -27,7 +26,7 @@ The Ripple Data API v2 replaces the Historical Database v1 and the [Charts API]( [v2.3.0]: https://github.com/ripple/rippled-historical-database/releases/tag/v2.3.0 -# API Method Reference # +# API Method Reference The Data API v2 provides a REST API with the following methods: @@ -97,12 +96,12 @@ Health Checks: * [Validations ETL Health Check - `GET /v2/health/validations_etl`](#health-check-validations-etl) -## Get Ledger ## +## Get Ledger [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/getLedger.js "Source") Retrieve a specific Ledger by hash, index, date, or latest validated. -#### Request Format #### +#### Request Format @@ -130,7 +129,7 @@ Optionally, you can provide the following query parameters: | `binary` | Boolean | If `true`, include all transactions from this ledger as hex-formatted binary data. (If provided, overrides `transactions`.) | | `expand` | Boolean | If `true`, include all transactions from this ledger as nested JSON objects. (If provided, overrides `binary` and `transactions`.) | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -139,7 +138,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `result` | String | The value `success` indicates that this is a successful response. | | `ledger` | [Ledger object](#ledger-objects) | The requested ledger. | -#### Example #### +#### Example Request: @@ -169,14 +168,14 @@ Response: -## Get Ledger Validations ## +## Get Ledger Validations [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/getLedger.js "Source") Retrieve a any validations recorded for a specific ledger hash. This dataset includes ledger versions that are outside the validated ledger chain. _(New in [v2.2.0][])_ **Note:** The Data API does not have a comprehensive record of all validations. The response only includes data that the Data API has recorded. Some ledger versions, especially older ledgers, may have no validations even if they were validated by consensus. -#### Request Format #### +#### Request Format @@ -204,7 +203,7 @@ Optionally, you can provide the following query parameters: | `marker` | String | [Pagination](#pagination) key from previously returned response. | | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -217,7 +216,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `validations` | Array of [Validation Objects][] | All known validation votes for the ledger version. | -#### Example #### +#### Example Request: @@ -259,14 +258,14 @@ Response: -## Get Ledger Validation ## +## Get Ledger Validation [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/getLedger.js "Source") Retrieve a validation vote recorded for a specific ledger hash by a specific validator. This dataset includes ledger versions that are outside the validated ledger chain. _(New in [v2.2.0][])_ **Note:** The Data API does not have a comprehensive record of all validations. The response only includes data that the Data API has recorded. Some ledger versions, especially older ledgers, may have no validations even if they were validated by consensus. -#### Request Format #### +#### Request Format @@ -289,7 +288,7 @@ This method requires the following URL parameters: This request takes no query parameters. -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body containing a **[Validation Object][]** with the following additional field: @@ -297,7 +296,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body containi |--------|-------|-------------| | `result` | String | The value `success` indicates that this is a successful response. | -#### Example #### +#### Example Request: @@ -323,12 +322,12 @@ Response: -## Get Transaction ## +## Get Transaction [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/getTransactions.js "Source") Retrieve a specific transaction by its identifying hash. -#### Request Format #### +#### Request Format @@ -354,7 +353,7 @@ Optionally, you can provide the following query parameters: |-------|-------|-------------| | `binary` | Boolean | If `true`, return transaction data in binary format, as a hex string. Otherwise, return transaction data as nested JSON. Defaults to false. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -363,7 +362,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `result` | String | The value `success` indicates that this is a successful response. | | `transaction` | [Transaction object](#transaction-objects) | The requested transaction. | -#### Example #### +#### Example Request: @@ -431,12 +430,12 @@ Response (trimmed for size): -## Get Transactions ## +## Get Transactions [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/getTransactions.js "Source") Retrieve transactions by time -#### Request Format #### +#### Request Format @@ -463,7 +462,7 @@ Optionally, you can provide the following query parameters: | `limit` | Integer | Maximum results per page. Defaults to 20. Cannot be more than 100. | | `marker` | String | [Pagination](#pagination) marker from a previous response. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: | Field | Value | Description | @@ -473,7 +472,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `marker` | String | (May be omitted) Pagination marker. | | `transactions` | Array of [Transaction object](#transaction-objects) | The requested transactions. | -#### Example #### +#### Example Request: @@ -588,14 +587,14 @@ Response: -## Get Payments ## +## Get Payments [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/getPayments.js "Source") Retrieve Payments over time, where Payments are defined as `Payment` type transactions where the sender of the transaction is not also the destination. _(New in [v2.0.4][])_ Results can be returned as individual payments, or aggregated to a specific list of intervals if currency and issuer are provided. -#### Request Format #### +#### Request Format @@ -634,7 +633,7 @@ Optionally, you can provide the following query parameters: | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -646,7 +645,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `payments` | Array of [Payment Objects][], or array of aggregate objects. | The requested payments. | -##### Aggregate Results ##### +##### Aggregate Results If the request specifies a `currency` and an `interval`, the result includes objects summarizing activity over a specific time period instead of listing individual payments. Each interval summary object has the following fields: @@ -659,7 +658,7 @@ If the request specifies a `currency` and an `interval`, the result includes obj | `total_amount` | Number | The amount of the `currency` delivered during this interval. | | `average_amount` | Number | The average amount of currency delivered by a single payment during this interval. | -#### Example #### +#### Example Request: @@ -741,12 +740,12 @@ Response: -## Get Exchanges ## +## Get Exchanges [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/getExchanges.js "Source") Retrieve Exchanges for a given currency pair over time. Results can be returned as individual exchanges or aggregated to a specific list of intervals -#### Request Format #### +#### Request Format @@ -781,7 +780,7 @@ Optionally, you can provide the following query parameters: | `autobridged` | Boolean | If true, filter results to autobridged exchanges only. | | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json` | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: | Field | Value | Description | @@ -791,7 +790,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `marker` | String | (May be omitted) [Pagination](#pagination) marker. | | `exchanges` | Array of [Exchange Objects][] | The requested exchanges. | -#### Example #### +#### Example Request: @@ -873,12 +872,12 @@ Response: -## Get Exchange Rates ## +## Get Exchange Rates [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/getExchangeRate.js "Source") Retrieve an exchange rate for a given currency pair at a specific time. -#### Request Format #### +#### Request Format @@ -908,7 +907,7 @@ Optionally, you can provide the following query parameters: | `strict` | Boolean | If false, allow rates derived from less than 10 exchanges. Defaults to true. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: | Field | Value | Description | @@ -920,7 +919,7 @@ All exchange rates are calcuated by converting the base currency and counter cur The rate is derived from the volume weighted average over the calendar day specified, averaged with the volume weighted average of the last 50 trades within the last 14 days. -#### Example #### +#### Example Request: @@ -941,12 +940,12 @@ Response: -## Normalize ## +## Normalize [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/normalize.js "Source") Convert an amount from one currency and issuer to another, using the network exchange rates. -#### Request Format #### +#### Request Format @@ -973,7 +972,7 @@ You must provide at least some of the following query parameters: | `strict` | Boolean | If `true`, do not use exchange rates that are determined by less than 10 exchanges. Defaults to `true`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: | Field | Value | Description | @@ -985,7 +984,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the All exchange rates are calculating by converting both currencies to XRP. -#### Example #### +#### Example Request: @@ -1008,12 +1007,12 @@ Response: -## Get Daily Reports ## +## Get Daily Reports [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/reports.js "Source") Retrieve per account per day aggregated payment summaries -#### Request Format #### +#### Request Format @@ -1043,7 +1042,7 @@ Optionally, you can provide the following query parameters: | `limit` | Integer | Maximum results per page. Defaults to 200. Cannot be more than 1000. | | `marker` | String | [Pagination](#pagination) key from previously returned response. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -1057,7 +1056,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the **Caution:** This method may return a very large amount of data (more than 1 megabyte), which may cause poor performance in your client application. -#### Example #### +#### Example Request: @@ -1172,12 +1171,12 @@ Response (trimmed for size): -## Get Stats ## +## Get Stats [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/stats.js "Source") Retrieve statistics about transaction activity in the XRP Ledger, divided into intervals of time. -#### Request Format #### +#### Request Format @@ -1205,7 +1204,7 @@ Optionally, you can provide the following query parameters: | `descending` | Boolean | If true, return results in reverse chronological order. Defaults to false. | | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -##### Families and Metrics ##### +##### Families and Metrics The `family` and `metrics` query parameters provide a way to filter results to a specific subset of all metrics available for transactions in any given interval. Each metric is tied to a specific family, as follows: @@ -1215,7 +1214,7 @@ The `family` and `metrics` query parameters provide a way to filter results to a | `result` | All [transaction result codes](reference-transaction-format.html#transaction-results) (string codes, not the numeric codes), including `tesSUCCESS`, `tecPATH_DRY`, and many others. | Number of transactions that resulted in the given code during the interval. | | `metric` | Data-API defined Special Transaction Metrics. | (Varies) | -##### Special Transaction Metrics ##### +##### Special Transaction Metrics The Data API derives the following values for every interval. These metrics are part of the `metric` family. @@ -1230,7 +1229,7 @@ The Data API derives the following values for every interval. These metrics are If any of the metrics have a value of 0, they are omitted from the results. -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: | Field | Value | Description | @@ -1240,7 +1239,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `marker` | String | (May be omitted) [Pagination](#pagination) marker. | | `stats` | Array of stats objects | The requested stats. Omits metrics with a value of 0, and intervals that have no nonzero metrics. | -#### Example #### +#### Example Request: @@ -1277,12 +1276,12 @@ Response: -## Get Capitalization ## +## Get Capitalization [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/capitalization.js "Source") Get the total amount of a single currency issued by a single issuer, also known as the [market capitalization](https://en.wikipedia.org/wiki/Market_capitalization). _(New in [v2.0.4][])_ -#### Request Format #### +#### Request Format @@ -1319,7 +1318,7 @@ Optionally, you can provide the following query parameters: If the request omits both `start` and `end`, the API returns only the most recent sample. -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: | Field | Value | Description | @@ -1338,7 +1337,7 @@ Each **issuer capitalization object** has the following fields: | `date` | String - [Timestamp][] | The start time of the interval this object represents. | | `amount` | [String - Number][] | The total amount of currency issued by the issuer as of the start of this interval. | -#### Example #### +#### Example Request: @@ -1403,12 +1402,12 @@ Response: -## Get Active Accounts ## +## Get Active Accounts [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/activeAccounts.js "Source") Get information on which accounts are actively trading in a specific currency pair. _(New in [v2.0.4][])_ -#### Request Format #### +#### Request Format @@ -1438,7 +1437,7 @@ Optionally, you can provide the following query parameters: | `include_exchanges` | Boolean | Include individual exchanges for each account in the results. | | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: | Field | Value | Description | @@ -1465,7 +1464,7 @@ Each "Account Trading Object" describes the activity of a single account during | `counter_volume` | Number | The total volume of the counter currency the account bought and sold in this period. | | `count` | Number | The total number of exchanges the account made during this period. | -#### Example #### +#### Example Request: @@ -1555,14 +1554,14 @@ Response: -## Get Exchange Volume ## +## Get Exchange Volume [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/getMetric.js "Source") Get aggregated exchange volume for a given time period. _(New in [v2.0.4][])_ The API returns results in units of a single _display currency_ rather than many different currencies. The conversion uses standard rates to and from XRP. -#### Request Format #### +#### Request Format @@ -1590,7 +1589,7 @@ Optionally, you can provide the following query parameters: | `marker` | String | [Pagination](#pagination) key from previously returned response. | | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: | Field | Value | Description | @@ -1610,7 +1609,7 @@ Each object in the `components` array of the Volume Objects represent the volume | `counter` | Object | The `currency` and `issuer` of the counter currency of this market. There is no `issuer` for XRP. | | `converted_amount` | Number | The total amount of volume in the market, converted to the display currency. _(Before [v2.1.0][], this was `convertedAmount`.)_ | -#### Example #### +#### Example Request: @@ -1705,14 +1704,14 @@ Response: -## Get Payment Volume ## +## Get Payment Volume [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/getMetric.js "Source") Get aggregated payment volume for a given time period. _(New in [v2.0.4][])_ The API returns results in units of a single _display currency_ rather than many different currencies. The conversion uses standard rates to and from XRP. -#### Request Format #### +#### Request Format @@ -1740,7 +1739,7 @@ Optionally, you can provide the following query parameters: | `marker` | String | [Pagination](#pagination) key from previously returned response. | | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: | Field | Value | Description | @@ -1760,7 +1759,7 @@ Each object in the `components` array of the Volume Objects represent the volume | `rate` | Number | The exchange rate between this currency and the display currency. | | `converted_amount` | Number | Total payment volume for this currency, converted to the display currency. _(Before [v2.1.0][], this was `convertedAmount`.)_ | -#### Example #### +#### Example Request: @@ -1836,14 +1835,14 @@ Response: -## Get Issued Value ## +## Get Issued Value [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/getMetric.js "Source") Get the total value of all currencies issued by major gateways over time. By default, returns only the most recent measurement. _(New in [v2.0.4][])_ The API returns results in units of a single _display currency_ rather than many different currencies. The conversion uses standard rates to and from XRP. -#### Request Format #### +#### Request Format @@ -1869,7 +1868,7 @@ Optionally, you can provide the following query parameters: | `marker` | String | [Pagination](#pagination) key from previously returned response. | | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -1889,7 +1888,7 @@ Each Issued Value Object represents the total value issued at one point in time, | `time` | String - [Timestamp][] | When this data was measured. | | `total` | Number | Total value of all issued assets at this time, in units of the display currency. | -#### Example #### +#### Example Request: @@ -1946,12 +1945,12 @@ Response: -## Get XRP Distribution ## +## Get XRP Distribution [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/xrpDistribution.js "Source") Get information on the total amount of XRP in existence and in circulation, by weekly intervals. _(New in [v2.2.0][])_ -#### Request Format #### +#### Request Format @@ -1976,7 +1975,7 @@ Optionally, you can provide the following query parameters: | `descending` | Boolean | If true, return results in reverse chronological order. Defaults to false. | | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -1995,7 +1994,7 @@ Each Distribution Object has the following fields: | `undistributed` | String | Aggregate amount of XRP held by Ripple (the company). | | `distributed` | String | Aggregate amount of XRP held by others. | -#### Example #### +#### Example Request: @@ -2024,13 +2023,13 @@ Response: -## Get Top Currencies ## +## Get Top Currencies [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/topCurrencies.js "Source") Returns the top currencies on the XRP Ledger, ordered from highest rank to lowest. The ranking is determined by the volume and count of transactions and the number of unique counterparties. By default, returns results for the 30-day rolling window ending on the current date. You can specify a date to get results for the 30-day window ending on that date. _(New in [v2.1.0][])_ -#### Request Format #### +#### Request Format @@ -2063,7 +2062,7 @@ Optionally, you can provide the following query parameters: | `limit` | Integer | Maximum results per page. Defaults to 1000. Cannot be more than 1000. | | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -2086,7 +2085,7 @@ Each Top Currency Object has the following fields: | `avg_payment_volume` | [String - Number][] | Daily average volume of payments, normalized to XRP | | `issued_value` | [String - Number][] | Total amount of this currency issued by this issuer, normalized to XRP | -#### Example #### +#### Example Request: @@ -2127,12 +2126,12 @@ Response: -## Get Top Markets ## +## Get Top Markets [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/topMarkets.js "Source") Returns the top exchange markets on the XRP Ledger, ordered from highest rank to lowest. The rank is determined by the number and volume of exchanges and the number of counterparties participating. By default, returns top markets for the 30-day rolling window ending on the current date. You can specify a date to get results for the 30-day window ending on that date. _(New in [v2.1.0][])_ -#### Request Format #### +#### Request Format @@ -2165,7 +2164,7 @@ Optionally, you can provide the following query parameters: | `limit` | Integer | Maximum results per page. Defaults to 1000. Cannot be more than 1000. | | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -2189,7 +2188,7 @@ Each Top Market object has the following fields: | `avg_exchange_count` | String | Daily average number of [exchanges](#exchange-objects) | | `avg_volume` | String | Daily average volume, normalized to XRP | -#### Example #### +#### Example Request: @@ -2231,12 +2230,12 @@ Response: -## Get Transaction Costs ## +## Get Transaction Costs [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/getFees.js "Source") Returns [transaction cost](concept-transaction-cost.html) stats per ledger, hour, or day. The data shows the average, minimum, maximum, and total transaction costs paid for the given interval or ledger. _(New in [v2.2.0][])_ -#### Request Format #### +#### Request Format @@ -2262,7 +2261,7 @@ Optionally, you can provide the following query parameters: | `marker` | String | [Pagination](#pagination) key from previously returned response. | | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -2285,7 +2284,7 @@ Each Fee Summary object has the following fields: | `date` | String - [Timestamp][] | The start time of this interval (time intervals), or the close time of this ledger (`ledger` interval). | | `ledger_index` | Integer - [Ledger Index][] | (Only present in `ledger` interval) The ledger this object describes. | -#### Example #### +#### Example Request: @@ -2332,13 +2331,13 @@ Response: -## Get Topology ## +## Get Topology [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/getTopology.js "Source") Get known `rippled` servers and peer-to-peer connections between them. _(New in [v2.2.0][])_ -#### Request Format #### +#### Request Format @@ -2359,7 +2358,7 @@ Optionally, you can provide the following query parameters: | `date` | String - [Timestamp][] | Date and time for historical query. By default, uses the most recent data available. | | `verbose` | Boolean | If `true`, include additional details about each server where available. Defaults to `false`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -2372,7 +2371,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `nodes` | Array of [Server Objects][] | Details of `rippled` servers in the peer-to-peer network. | | `links` | Array of [Link Objects][] | Network connections between `rippled` servers in the peer-to-peer network. | -#### Example #### +#### Example Request: @@ -2437,12 +2436,12 @@ Response: -## Get Topology Nodes ## +## Get Topology Nodes [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/getNodes.js "Source") Get known `rippled` nodes. (This is a subset of the data returned by the [Get Topology method](#get-topology).) _(New in [v2.2.0][])_ -#### Request Format #### +#### Request Format @@ -2464,7 +2463,7 @@ Optionally, you can provide the following query parameters: | `verbose` | Boolean | If `true`, return full details for each server. Defaults to `false`. | | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -2475,7 +2474,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `count` | Integer | Number of `rippled` servers described. | | `nodes` | Array of [Server Objects][] | Details of the `rippled` servers in the topology. | -#### Example #### +#### Example Request: @@ -2528,12 +2527,12 @@ Response: -## Get Topology Node ## +## Get Topology Node [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/getNodes.js "Source") Get information about a single `rippled` server by its [node public key](#public-keys) (not validator public key). _(New in [v2.2.0][])_ -#### Request Format #### +#### Request Format @@ -2555,7 +2554,7 @@ This method requires the following URL parameters: This method takes no query parameters. -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with a **[Server Object][]** in the response with the following additional field: @@ -2563,7 +2562,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with a * |--------|-------|-------------| | `result` | String | The value `success` indicates that this is a successful response. | -#### Example #### +#### Example Request: @@ -2600,12 +2599,12 @@ Response: -## Get Topology Links ## +## Get Topology Links [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/getLinks.js "Source") Get information on peer-to-peer connections between `rippled` servers. (This is a subset of the data returned by the [Get Topology method](#get-topology).) _(New in [v2.2.0][])_ -#### Request Format #### +#### Request Format @@ -2626,7 +2625,7 @@ Optionally, you can provide the following query parameters: | `date` | String - [Timestamp][] | Date and time for historical query. Defaults to most recent data available. | | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -2637,7 +2636,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `count` | Integer | Number of links returned. | | `links` | Array of [Link Objects][] | Links between `rippled` servers. | -#### Example #### +#### Example Request: @@ -2665,13 +2664,13 @@ Response: -## Get Validator ## +## Get Validator [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/getValidators.js "Source") Get details of a single validator in the [consensus network](https://ripple.com/build/ripple-ledger-consensus-process/). _(New in [v2.2.0][])_ -#### Request Format #### +#### Request Format @@ -2695,7 +2694,7 @@ Optionally, you can provide the following query parameters: |--------|---------|-------------| | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -2707,7 +2706,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `domain` | String | (May be omitted) The DNS domain associated with this validator. | | `domain_state` | String | The value `verified` indicates that this validator has a [verified domain](tutorial-rippled-setup.html#domain-verification) controlled by the same operator as the validator. The value `AccountDomainNotFound` indicates that the "Account Domain" part of Domain Verification is not set up properly. The value `RippleTxtNotFound` indicates that the ripple.txt step of Domain Verification is not set up properly. | -#### Example #### +#### Example Request: @@ -2730,13 +2729,13 @@ Response: -## Get Validators ## +## Get Validators [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/getValidators.js "Source") Get a list of known validators. _(New in [v2.2.0][])_ -#### Request Format #### +#### Request Format @@ -2756,7 +2755,7 @@ Optionally, you can provide the following query parameters: |--------|---------|-------------| | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -2767,7 +2766,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `validation_public_key` | String - Base-58 [Public Key][] | Validator public key of this validator. | -#### Example #### +#### Example Request: @@ -2788,14 +2787,14 @@ Response: -## Get Validator Validations ## +## Get Validator Validations [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/getValidations.js "Source") Retrieve validation votes signed by a specified validator, including votes for ledger versions that are outside the main ledger chain. _(New in [v2.2.0][])_ **Note:** The Data API does not have a comprehensive record of all validations. The response only includes data that the Data API has recorded. Some ledger versions, especially older ledgers, may have no validations even if they were validated by consensus. -#### Request Format #### +#### Request Format @@ -2825,7 +2824,7 @@ Optionally, you can provide the following query parameters: | `marker` | String | [Pagination](#pagination) key from previously returned response. | | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -2837,7 +2836,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `validations` | Array of [Validation Objects][] | The requested validations. | -#### Example #### +#### Example Request: @@ -2887,14 +2886,14 @@ Response: -## Get Validations ## +## Get Validations [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/getValidations.js "Source") Retrieve validation votes, including votes for ledger versions that are outside the main ledger chain. _(New in [v2.2.0][])_ **Note:** The Data API does not have a comprehensive record of all validations. The response only includes data that the Data API has recorded. Some ledger versions, especially older ledgers, may have no validations even if they were validated by consensus. -#### Request Format #### +#### Request Format @@ -2919,7 +2918,7 @@ Optionally, you can provide the following query parameters: | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | | `descending` | Boolean | If `true`, return results sorted with earliest first. Otherwise, return oldest results first. Defaults to `false`. -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -2930,7 +2929,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `marker` | String | (May be omitted) [Pagination](#pagination) marker. | | `validations` | Array of [Validation Objects][] | The requested validation votes. | -#### Example #### +#### Example Request: @@ -2980,12 +2979,12 @@ Response: -## Get Single Validator Reports ## +## Get Single Validator Reports [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/getValidatorReports.js "Source") Get a single validator's validation vote stats for 24-hour intervals. -#### Request Format #### +#### Request Format @@ -3013,7 +3012,7 @@ Optionally, you can provide the following query parameters: | `end` | String - [Timestamp][] | End date and time for historical query. Defaults to most recent data available. | | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -3035,7 +3034,7 @@ Each member in the `validators` array is a Single Validator Report Object with d | `alt_net_ledgers` | Integer | Number of consensus-validated [Test Network](tutorial-rippled-setup.html#parallel-networks) ledger versions this validator voted for. | | `other_ledgers` | Integer | Number of other ledger versions this validator voted for. If this number is high, that could indicate that this validator was running non-standard or out-of-date software. | -#### Example #### +#### Example Request: @@ -3077,12 +3076,12 @@ Response: -## Get Daily Validator Reports ## +## Get Daily Validator Reports [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/getValidatorReports.js "Source") Get a validation vote stats and validator information for all known validators in a 24-hour period. -#### Request Format #### +#### Request Format @@ -3103,7 +3102,7 @@ Optionally, you can provide the following query parameters: | `date` | String - [Timestamp][] | Date and time to query. By default, uses the most recent data available. | | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -3129,7 +3128,7 @@ Daily Validator Report Object fields: | `domain` | String | (May be omitted) The DNS domain associated with this validator. | | `domain_state` | String | The value `verified` indicates that this validator has a [verified domain](tutorial-rippled-setup.html#domain-verification) controlled by the same operator as the validator. The value `AccountDomainNotFound` indicates that the "Account Domain" part of Domain Verification is not set up properly. The value `RippleTxtNotFound` indicates that the ripple.txt step of Domain Verification is not set up properly. | -#### Example #### +#### Example Request: @@ -3178,12 +3177,12 @@ Response: ``` -## Get rippled Versions ## +## Get rippled Versions [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/getVersions.js "Source") Reports the latest versions of `rippled` available from the official Ripple Yum repositories. _(New in [v2.3.0][].)_ -#### Request Format #### +#### Request Format @@ -3198,7 +3197,7 @@ GET /v2/network/rippled_versions [Try it! >](data-api-v2-tool.html#get-rippled-versions) -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -3216,7 +3215,7 @@ Each Version Object contains the following fields: | `repo` | String | The Yum repository where this `rippled` is available. The `stable` repository has the latest production version. Other versions are for development and testing. | | `version` | String | The version string for this version of `rippled`. | -#### Example #### +#### Example Request: @@ -3253,12 +3252,12 @@ Response: -## Get All Gateways ## +## Get All Gateways [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/gateways.js "Source") Get information about [known gateways](https://github.com/ripple/rippled-historical-database/blob/v2.0.4/api/gateways/gateways.json). _(New in [v2.0.4][])_ -#### Request Format #### +#### Request Format @@ -3274,7 +3273,7 @@ GET /v2/gateways/ This method takes no query parameters. -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body. @@ -3288,7 +3287,7 @@ Each field in the top level JSON object is a [Currency Code][]. The content of e | `label` | String | (May be omitted) Only provided when the [Currency Code][] is a 40-character hexadecimal value. This is an alternate human-readable name for the currency issued by this gateway. | `assets` | Array of Strings | Graphics filenames available for this gateway, if any. (Mostly, these are logos used by XRP Charts.) | -#### Example #### +#### Example Request: @@ -3349,13 +3348,13 @@ Response: -## Get Gateway ## +## Get Gateway [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/gateways.js "Source") Get information about a specific gateway from [the Data API's list of known gateways](https://github.com/ripple/rippled-historical-database/blob/v2.0.4/api/gateways/gateways.json). _(New in [v2.0.4][])_ -#### Request Format #### +#### Request Format @@ -3377,7 +3376,7 @@ This method requires the following URL parameters: This method takes no query parameters. -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -3398,7 +3397,7 @@ Each object in the `accounts` field array has the following fields: | `address` | String | The [issuing address](concept-issuing-and-operational-addresses.html) used by this gateway. | | `currencies` | Object | Each field in this object is a [Currency Code][] corresponding to a currency issued from this address. Each value is an object with a `featured` boolean indicating whether that currency is featured. Ripple decides which currencies and gateways to feature based on responsible business practices, volume, and other measures. | -#### Example #### +#### Example Request: @@ -3441,13 +3440,13 @@ Response: -## Get Currency Image ## +## Get Currency Image [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/gateways.js#L199 "Source") Retrieve vector icons for various currencies. _(New in [v2.0.4][])_ -#### Request Format #### +#### Request Format @@ -3465,10 +3464,10 @@ This method requires the following URL parameter: |-------|-------|-------------| | `currencyimage` | String | An image file for a currency, such as `xrp.svg`. See [the source code](https://github.com/ripple/rippled-historical-database/tree/develop/api/gateways/currencyAssets) for a list of available images. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a **Content-Type** header of `image/svg+xml` to indicate that the contents are XML representing a file in [SVG format](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics). -#### Example #### +#### Example Request: @@ -3503,12 +3502,12 @@ Content-Type: image/svg+xml -## Get Accounts ## +## Get Accounts [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/accounts.js "Source") Retrieve information about the creation of new accounts in the XRP Ledger. -#### Request Format #### +#### Request Format @@ -3536,7 +3535,7 @@ Optionally, you can provide the following query parameters: | `reduce` | Boolean | Return a count of results only. | | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: | Field | Value | Description | @@ -3546,7 +3545,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `marker` | String | (May be omitted) [Pagination](#pagination) marker. | | `accounts` | Array | If the request used the `interval` query parameter, each member of the array is an interval object. Otherwise, this field is an array of [account creation objects](#account-creation-objects). | -##### Interval Objects ##### +##### Interval Objects If the request uses the `interval` query parameter, the response has an array of interval objects, each of which represents the number of accounts created during a single interval. Interval objects have the following fields: @@ -3555,7 +3554,7 @@ If the request uses the `interval` query parameter, the response has an array of | `date` | String - [Timestamp] | When this interval starts. (The length of the interval is determined by the request.) | | `count` | Number | How many accounts were created in this interval. | -#### Example #### +#### Example Request: @@ -3600,12 +3599,12 @@ Response: ``` -## Get Account ## +## Get Account [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/getAccount.js "Source") Get creation info for a specific ripple account -#### Request Format #### +#### Request Format @@ -3626,7 +3625,7 @@ This method requires the following URL parameters: |-----------|--------|-------------| | `address` | String | XRP Ledger address to query. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -3635,7 +3634,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `result` | String | The value `success` indicates that this is a successful response. | | `account` | Object - [Account Creation](#account-creation-objects) | The requested account. | -#### Example #### +#### Example Request: @@ -3662,7 +3661,7 @@ Response: -## Get Account Balances ## +## Get Account Balances [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/accountBalances.js "Source") Get all balances held or owed by a specific XRP Ledger account. @@ -3697,7 +3696,7 @@ Optionally, you can provide the following query parameters: | `limit` | Integer | Maximum results per page. Defaults to 200. Cannot be greater than 400, but you can use the value `all` to return all results. (Caution: When using limit=all to retrieve very many results, the request may time out. For large issuers, there can be several tens of thousands of results.) | | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: | Field | Value | Description | @@ -3709,7 +3708,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `marker` | String | (May be omitted) [Pagination](#pagination) marker. | | `balances` | Array of [Balance Object][]s | The requested balances. | -#### Example #### +#### Example Request: @@ -3747,12 +3746,12 @@ Response: ``` -## Get Account Orders ## +## Get Account Orders [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/accountOrders.js "Source") Get orders in the order books, placed by a specific account. This does not return orders that have already been filled. -#### Request Format #### +#### Request Format @@ -3784,7 +3783,7 @@ Optionally, you can provide the following query parameters: If none of `ledger_index`, `ledger_hash`, or `date` are specified, the API uses the most current data available. -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: | Field | Value | Description | @@ -3808,7 +3807,7 @@ Each order object has the following fields: | `properties.sequence` | Number | The sequence number of the transaction that placed this order. | | `properties.makerExchangeRate` | [String - Number][] | The exchange rate from the point of view of the account that submitted the order. | -#### Example #### +#### Example Request: @@ -3873,12 +3872,12 @@ Response: -## Get Account Transaction History ## +## Get Account Transaction History [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/accountTransactions.js "Source") Retrieve a history of transactions that affected a specific account. This includes all transactions the account sent, payments the account received, and payments that rippled through the account. -#### Request Format #### +#### Request Format @@ -3917,7 +3916,7 @@ Optionally, you can provide the following query parameters: **Note:** This method cannot return CSV format; only JSON results are supported for raw XRP Ledger transactions. -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -3928,7 +3927,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `marker` | String | (May be omitted) [Pagination](#pagination) marker. | | `transactions` | Array of [transaction objects](#transaction-objects) | All transactions matching the request. | -#### Example #### +#### Example Request: @@ -4005,12 +4004,12 @@ Response: -## Get Transaction By Account And Sequence ## +## Get Transaction By Account And Sequence [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/accountTxSeq.js "Source") Retrieve a specifc transaction originating from a specified account -#### Request Format #### +#### Request Format @@ -4039,7 +4038,7 @@ Optionally, you can provide the following query parameters: | `binary` | Boolean | If `true`, return transaction in binary format. Defaults to `false`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -4048,7 +4047,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `result` | String | The value `success` indicates that this is a successful response. | | `transaction` | [transaction object](#transaction-objects) | The requested transaction. | -#### Example #### +#### Example Request: @@ -4074,12 +4073,12 @@ Response: -## Get Account Payments ## +## Get Account Payments [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/accountPayments.js "Source") Retrieve a payments for a specified account -#### Request Format #### +#### Request Format @@ -4117,7 +4116,7 @@ Optionally, you can provide the following query parameters: | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: @@ -4128,7 +4127,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `marker` | String | (May be omitted) [Pagination](#pagination) marker. | | `payments` | Array of [payment objects][] | All payments matching the request. | -#### Example #### +#### Example Request: @@ -4180,12 +4179,12 @@ Response: -## Get Account Exchanges ## +## Get Account Exchanges [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/accountExchanges.js "Source") Retrieve Exchanges for a given account over time. -#### Request Format #### +#### Request Format There are two variations on this method: @@ -4228,7 +4227,7 @@ Optionally, you can provide the following query parameters: | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: | Field | Value | Description | @@ -4238,7 +4237,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `marker` | String | (May be omitted) [Pagination](#pagination) marker. | | `exchanges` | Array of [Exchange Objects][] | The requested exchanges. | -#### Example #### +#### Example Request: @@ -4300,12 +4299,12 @@ Response: -## Get Account Balance Changes ## +## Get Account Balance Changes [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/accountBalanceChanges.js "Source") Retrieve Balance changes for a given account over time. -#### Request Format #### +#### Request Format @@ -4340,7 +4339,7 @@ Optionally, you can provide the following query parameters: | `format` | String | Format of returned results: `csv` or`json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: | Field | Value | Description | @@ -4350,7 +4349,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `marker` | String | (May be omitted) [Pagination](#pagination) marker. | | `exchanges` | Array of [balance change descriptors][] | The requested balance changes. | -#### Example #### +#### Example Request: @@ -4405,7 +4404,7 @@ Response: -## Get Account Reports ## +## Get Account Reports [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/accountReports.js "Source") Retrieve daily summaries of payment activity for an account. @@ -4448,7 +4447,7 @@ Optionally, you can provide the following query parameters: | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: | Field | Value | Description | @@ -4457,7 +4456,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `count` | Integer | Number of reports in the `reports` field. | | `reports` | Array of [Reports Objects][] | Daily summaries of account activity for the given account and date range. | -#### Example #### +#### Example Request: @@ -4518,7 +4517,7 @@ Response: -## Get Account Transaction Stats ## +## Get Account Transaction Stats [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/accountStats.js "Source") Retrieve daily summaries of transaction activity for an account. _(New in [v2.1.0][].)_ @@ -4554,7 +4553,7 @@ Optionally, you can provide the following query parameters: | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: | Field | Value | Description | @@ -4572,7 +4571,7 @@ Each Transaction Stats Object has the following fields: | `result` | Object | Map of [transaction result codes](reference-transaction-format.html#transaction-results), indicating how many of each result code occurred in the transactions sent by this account on this date. | | `type` | Object | Map of [transaction types](reference-transaction-format.html), indicating how many of each transaction type the account sent on this date. | -#### Example #### +#### Example Request: @@ -4617,7 +4616,7 @@ Response: -## Get Account Value Stats ## +## Get Account Value Stats [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/accountStats.js "Source") Retrieve daily summaries of transaction activity for an account. _(New in [v2.1.0][].)_ @@ -4653,7 +4652,7 @@ Optionally, you can provide the following query parameters: | `format` | String | Format of returned results: `csv` or `json`. Defaults to `json`. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK** and has a JSON body with the following: | Field | Value | Description | @@ -4670,7 +4669,7 @@ Each Value Stats Object has the following fields: | `value` | [String - Number][] | The total of all currency held by this account, normalized to XRP. | | `balance_change_count` | Number | The number of times the account's balance changed on this date. | -#### Example #### +#### Example Request: @@ -4704,7 +4703,7 @@ Response: -## Health Check - API ## +## Health Check - API [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/checkHealth.js "Source") Check the health of the API service. @@ -4728,7 +4727,7 @@ Optionally, you can provide the following query parameters: | `threshold` | Integer | Consider the API unhealthy if the database does not respond within this amount of time, in seconds. Defaults to 5 seconds. | | `verbose` | Boolean | If true, return a JSON response with data points. By default, return an integer value only. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK**. By default, the response body is an **integer health value only**. @@ -4747,7 +4746,7 @@ If the request specifies `verbose=true` in the query parameters, the response bo | `response_time` | String - Human-readable time | The actual response time of the database. | | `response_time_threshold` | String - Human-readable time | The maximum response time to be considered healthy. | -#### Example #### +#### Example Request: @@ -4767,7 +4766,7 @@ Response: ``` -## Health Check - Ledger Importer ## +## Health Check - Ledger Importer [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/checkHealth.js "Source") Check the health of the Ledger Importer Service. @@ -4792,7 +4791,7 @@ Optionally, you can provide the following query parameters: | `threshold2` | Integer | Consider the Importer unhealthy if more than this amount of time, in seconds, has elapsed since the latest ledger of any kind was imported. Defaults to 60 seconds. | | `verbose` | Boolean | If true, return a JSON response with data points. By default, return an integer value only. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK**. By default, the response body is an **integer health value only**. @@ -4815,7 +4814,7 @@ If the request specifies `verbose=true` in the query parameters, the response bo | `valildation_gap` | String - Human-readable time | Difference between the close time of the last imported validated ledger and the current time. | | `validation_gap_threshold` | String - Human-readable time | Maximum validation gap to be considered healthy. | -#### Example #### +#### Example Request: @@ -4839,7 +4838,7 @@ Response: -## Health Check - Nodes ETL ## +## Health Check - Nodes ETL [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/checkHealth.js "Source") Check the health of the Topology Nodes Extract, Transform, Load (ETL) Service. @@ -4863,7 +4862,7 @@ Optionally, you can provide the following query parameters: | `threshold` | Integer | Consider the service unhealthy if more than this amount of time, in seconds, has elapsed since the latest data was imported. Defaults to 120 seconds. | | `verbose` | Boolean | If `true`, return a JSON response with data points. By default, return an integer value only. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK**. By default, the response body is an **integer health value only**. @@ -4884,7 +4883,7 @@ If the request specifies `verbose=true` in the query parameters, the response bo | `gap_threshold` | String - Human-readable time | Maximum gap to be considered healthy. | | `message` | String | Description of the reason for a non-zero score, if applicable. | -#### Example #### +#### Example Request: @@ -4905,7 +4904,7 @@ Response: -## Health Check - Validations ETL ## +## Health Check - Validations ETL [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/checkHealth.js "Source") Check the health of the Validations Extract, Transform, Load (ETL) Service. @@ -4929,7 +4928,7 @@ Optionally, you can provide the following query parameters: | `threshold` | Integer | Consider the service unhealthy if more than this amount of time, in seconds, has elapsed since the latest data was imported. Defaults to 120 seconds. | | `verbose` | Boolean | If true, return a JSON response with data points. By default, return an integer value only. | -#### Response Format #### +#### Response Format A successful response uses the HTTP code **200 OK**. By default, the response body is an **integer health value only**. @@ -4949,7 +4948,7 @@ If the request specifies `verbose=true` in the query parameters, the response bo | `gap_threshold` | String - Human-readable time | Maximum gap to be considered healthy. | | `message` | String | Description of the reason for a non-zero score, if applicable. | -#### Example #### +#### Example Request: @@ -4971,13 +4970,13 @@ Response: -# API Conventions # +# API Conventions -## Basic Types ## +## Basic Types As a REST API, the Data API v2 uses [JSON](http://json.org/)'s native datatypes to represent API fields, with some special cases. -### Numbers and Precision ### +### Numbers and Precision [String - Number]: #numbers-and-precision {% include 'snippets/string-number-formatting.md' %} @@ -4997,25 +4996,25 @@ The precision for amounts of **non-XRP currency** in the XRP Ledger is as follow In other words, XRP has the same precision as a 64-bit unsigned integer where each unit is equivalent to 0.000001 XRP. -### Addresses ### +### Addresses [Address]: #addresses {% include 'data_types/address.md' %} -### Public Keys ### +### Public Keys [Public Key]: #public-keys {% include 'data_types/public_key.md' %} -### Hashes ### +### Hashes [Hash]: #hashes {% include 'data_types/hash.md' %} -### Timestamps ### +### Timestamps [Timestamp]: #timestamps All dates and times are written in ISO 8601 Timestamp Format, using UTC. This format is summarized as: @@ -5032,22 +5031,22 @@ All dates and times are written in ISO 8601 Timestamp Format, using UTC. This fo (As of [v2.0.4][], the offset `+00:00` is no longer used.) -### Ledger Index ### +### Ledger Index [Ledger Index]: #ledger-index {% include 'data_types/ledger_index.md' %} -### Account Sequence ### +### Account Sequence [Sequence Number]: #account-sequence {% include 'data_types/account_sequence.md' %} -### Currency Code ### +### Currency Code [Currency Code]: #currency-code {% include 'data_types/currency_code.md' %} -## Pagination ## +## Pagination Many queries may return more data than is reasonable to return in a single HTTP response. The Data API uses a "limit and marker" system to control how much is returned in a single response ("page") and to query for additional content. @@ -5057,11 +5056,11 @@ When a query has additional objects that are not contained in the current respon When a `marker` is or would be present, the response contains a [`Link` header](https://tools.ietf.org/html/rfc5988#section-5) with `rel="next"`. This is a full URL to the next page of results. You can use this to paginate over results when the response is in `csv` format instead of `json`. _(New in [v2.0.4][])_ -## Transaction Objects ## +## Transaction Objects Transactions have two formats - a compact "binary" format where the defining fields of the transaction are encoded as strings of hex, and an expanded format where the defining fields of the transaction are nested as complete JSON objects. -### Full JSON Format ### +### Full JSON Format | Field | Value | Description | |-------|-------|-------------| @@ -5071,7 +5070,7 @@ Transactions have two formats - a compact "binary" format where the defining fie | `tx` | Object | The fields of this transaction object, as defined by the [Transaction Format](reference-transaction-format.html) | | `meta` | Object | Metadata about the results of this transaction. | -### Binary Format ### +### Binary Format | Field | Value | Description | |-------|-------|-------------| @@ -5081,7 +5080,7 @@ Transactions have two formats - a compact "binary" format where the defining fie | `tx` | String | The binary data that represents this transaction, as a hexadecimal string. | | `meta` | String | The binary data that represents this transaction's metadata, as a hex string. | -## Ledger Objects ## +## Ledger Objects A "ledger" is one version of the shared global ledger. Each ledger object has the following fields: @@ -5099,11 +5098,11 @@ A "ledger" is one version of the shared global ledger. Each ledger object has th **Note:** Ledger close times are approximate, typically rounded to about 10 seconds. Two ledgers could have the same `close_time` values, when their actual close times were several seconds apart. The sequence number (`ledger_index`) of the ledger makes it unambiguous which ledger closed first. -### Genesis Ledger ### +### Genesis Ledger Due to a mishap early in the XRP Ledger's history, ledgers 1 through 32569 were lost. Thus, ledger #32570 is the earliest ledger available anywhere. For purposes of the Data API v2, ledger #32570 is considered the _genesis ledger_. -## Account Creation Objects ## +## Account Creation Objects An account creation object represents the action of creating an account in the XRP Ledger. There are two variations, depending on whether the account was already present in ledger 32570, the earliest ledger available. Accounts that were already present in ledger 32570 are termed _genesis accounts_. @@ -5119,7 +5118,7 @@ An account creation object represents the action of creating an account in the X | `genesis_index` | Number - [Sequence Number][] | (Genesis accounts only) The transaction sequence number of the account as of ledger #32570. | -## Exchange Objects ## +## Exchange Objects [Exchange Objects]: #exchange-objects An exchange object represents an actual exchange of currency, which can occur in the XRP Ledger as the result of executing either an OfferCreate transaction or a Payment transaction. In order for currency to actually change hands, there must be a previously-unfilled Offer previously placed in the ledger with an OfferCreate transaction. @@ -5149,7 +5148,7 @@ A single transaction can cause several exchanges to occur. In this case, the sen | `tx_type` | String | The type of transaction that executed this exchange, either `Payment` or `OfferCreate`. | -## Reports Objects ## +## Reports Objects [Reports Objects]: #reports-objects Reports objects show the activity of a given account over a specific interval of time, typically a day. Reports have the following fields: @@ -5169,7 +5168,7 @@ Reports objects show the activity of a given account over a specific interval of | `total_value_received` | [String - Number][] | Sum value of all payments to this account, normalized to XRP (as closely as possible). | | `total_value_sent` | [String - Number][] | Sum value of all payments from this account, normalized to XRP (as closely as possible). -## Payment Summary Objects ## +## Payment Summary Objects [Payment Summary Objects]: #payment-summary-objects A Payment Summary Object contains a reduced amount of information about a single payment from the perspective of either the sender or receiver of that payment. @@ -5183,7 +5182,7 @@ A Payment Summary Object contains a reduced amount of information about a single | `type` | String | Either `sent` or `received`, indicating whether the perspective account is sender or receiver of this transaction. | -## Payment Objects ## +## Payment Objects [Payment Objects]: #payment-objects In the Data API, a Payment Object represents an event where one account sent value to another account. This mostly lines up with XRP Ledger transactions of the `Payment` [transaction type](reference-transaction-format.html), except that the Data API does not consider a transaction to be a payment if the sending `Account` and the `Destination` account are the same, or if the transaction failed. @@ -5208,7 +5207,7 @@ Payment objects have the following fields: | `tx_hash` | String - [Hash][] | The identifying hash of the transaction that caused the payment. | -## Balance Objects and Balance Change Objects ## +## Balance Objects and Balance Change Objects [balance change objects]: #balance-objects-and-balance-change-objects [Balance Object]: #balance-objects-and-balance-change-objects @@ -5225,7 +5224,7 @@ Balance objects and Balance Change objects have the same format, with the follow | `value` | [String - Number][] | The amount of the `currency` that the associated account gained or lost. In balance change objects, this value can be positive (for amounts gained) or negative (for amounts lost). In balance objects, this value can be positive (for amounts the counterparty owes the account) or negative (for amounts owed to the counterparty). | -## Balance Change Descriptors ## +## Balance Change Descriptors [Balance Change Descriptors]: #balance-change-descriptors Balance Change Descriptors are objects that describe and analyze a single balance change that occurs in transaction execution. They represent the same events as [balance change objects][], but in greater detail. @@ -5245,7 +5244,7 @@ Balance Change Descriptors have the following fields: | `ledger_index` | Number - [Ledger Index][] | The sequence number of the ledger that included the transaction that executed this balance change. | | `tx_hash` | String - [Hash][] | The identifying hash of the transaction that executed this balance change. | -### Change Types ### +### Change Types The following values are valid for the `change_type` field of a Balance Change Descriptor: @@ -5256,7 +5255,7 @@ The following values are valid for the `change_type` field of a Balance Change D | `payment_source` | This balance change reflects currency that was spent in a payment. | | `exchange` | This balance change reflects currency that was traded for other currency, or the same currency from a different issuer. This can occur in the middle of payment execution as well as from offers. | -## Volume Objects ## +## Volume Objects [Volume Objects]: #volume-objects Volume objects represent the total volumes of money moved, in either payments or exchanges, during a given period. @@ -5272,7 +5271,7 @@ Volume objects represent the total volumes of money moved, in either payments or | `total` | Number | Total volume of all recorded exchanges in the period. | -## Server Objects ## +## Server Objects [Server Object]: #server-objects [Server Objects]: #server-objects @@ -5306,7 +5305,7 @@ Server objects have the following fields, with some only appearing if the reques | `org` | String | (Verbose only) The organization that owns this server's public IP address. | -## Link Objects ## +## Link Objects [Link Object]: #link-objects [Link Objects]: #link-objects @@ -5318,7 +5317,7 @@ A Link Object represents a peer-to-peer network connection between two `rippled` | `target` | String - Base-58 [Public Key][] | The node public key of the `rippled` receiving the incoming connection. | -## Validation Objects ## +## Validation Objects [Validation Object]: #validation-objects [Validation Objects]: #validation-objects @@ -5340,13 +5339,13 @@ A Validation Object has the following fields: -# Running the Historical Database # +# Running the Historical Database You can also serve the Data API v2 from your own instance of the Historical Database software, and populate it with transactions from your own `rippled` instance. This is useful if you do not want to depend on Ripple to run the historical database indefinitely, or you want access to historical transactions from within your own intranet. -## Installation ## +## Installation -### Dependencies ### +### Dependencies The Historical Database requires the following software installed first: @@ -5357,7 +5356,7 @@ The Historical Database requires the following software installed first: Version 2 of the Historical Database requires HBase instead of [PostgreSQL](http://www.postgresql.org/). Postgres support is deprecated. -### Installation Process ### +### Installation Process To install the Data API v2: @@ -5381,7 +5380,7 @@ Reports, stats, and aggregated exchange data needs more processing before the AP At this point, the Data API is installed. See [Services](#services) for the different components that you can run. -### Tests ### +### Tests Dependencies: @@ -5393,7 +5392,7 @@ $ docker-compose up -d hbase $ docker-compose run --rm webapp npm test ``` -### Services ### +### Services The `rippled` Historical Database consists of several processes that can be run separately. @@ -5405,7 +5404,7 @@ The `rippled` Historical Database consists of several processes that can be run Command: `npm start` (restarts the server automatically when source files change), or `node api/server.js` (start once) -## Importing Data ## +## Importing Data In order to retrieve data from the `rippled` Historical Database, you must first populate it with data. Broadly speaking, there are two ways this can happen: @@ -5415,7 +5414,7 @@ In order to retrieve data from the `rippled` Historical Database, you must first In all cases, keep in mind that the integrity of the data is only as good as the original source. If you retrieve data from a public server, you are assuming that the operator of that server is trustworthy. If you load from a database dump, you are assuming that the provider of the dump has not corrupted or tampered with the data. -### Live Ledger Importer ### +### Live Ledger Importer The Live Ledger Importer is a service that connects to a `rippled` server using the WebSocket API, and listens for ledger close events. Each time a new ledger is closed, the Importer requests the latest validated ledger. Although this process has some fault tolerance built in to prevent ledgers from being skipped, the Importer may still miss ledgers. @@ -5430,7 +5429,7 @@ Example usage: $ node import/live ``` -### Backfiller ### +### Backfiller The Backfiller retrieves old ledgers from a `rippled` instance by moving backwards in time. You can optionally provide start and stop indexes to retrieve a specific range of ledgers, by their sequence number. diff --git a/content/reference-rippled.md b/content/reference-rippled.md index 557a2e2594..f91d0ab938 100755 --- a/content/reference-rippled.md +++ b/content/reference-rippled.md @@ -1,4 +1,4 @@ -# rippled # +# rippled The core peer-to-peer server that manages the XRP Ledger is called `rippled`. Each `rippled` server connects to a network of peers, relays cryptographically signed transactions, and maintains a local copy of the complete shared global ledger. The source code for `rippled` is written in C++, and is [available on GitHub under an open-source license](https://github.com/ripple/rippled). @@ -8,7 +8,7 @@ The core peer-to-peer server that manages the XRP Ledger is called `rippled`. Ea * JavaScript Client Library - [RippleAPI](reference-rippleapi.html) -# WebSocket and JSON-RPC APIs # +# WebSocket and JSON-RPC APIs If you want to communicate directly with a `rippled` server, you can use either the WebSocket API or the JSON-RPC API. Both APIs use the same list of commands, with almost entirely the same parameters in each command. Alternatively, you can use [RippleAPI](reference-rippleapi.html), which is a simplified JavaScript client library, which communicates directly with a `rippled` server from [Node.js](http://nodejs.org/) or a web browser. @@ -20,13 +20,13 @@ In general, we recommend using WebSocket, because WebSocket's push paradigm has **Note:** The `rippled` program can also be used as a quick commandline client to make JSON-RPC requests to a running `rippled` server. The commandline interface is intended for administrative purposes only and is _not a supported API_. -## Changes to the APIs ## +## Changes to the APIs The WebSocket and JSON-RPC APIs are still in development, and are subject to change. If you want to be notified of upcoming changes and future versions of `rippled`, subscribe to the Ripple Server mailing list: [https://groups.google.com/forum/#!forum/ripple-server](https://groups.google.com/forum/#!forum/ripple-server) -## Connecting to rippled ## +## Connecting to rippled 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. @@ -36,11 +36,11 @@ The [example config file](https://github.com/ripple/rippled/blob/release/doc/rip -### WebSocket API ### +### WebSocket API If you are looking to try out some methods on the XRP Ledger, you can skip writing your own WebSocket code and go straight to using the API at the [Ripple WebSocket API Tool](ripple-api-tool.html). Later on, when you want to connect to your own `rippled` server, you can [build your own client in the browser](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applications) or [in Node.js](https://www.npmjs.com/package/ws). -#### Request Formatting #### +#### Request Formatting After you open a WebSocket to the `rippled` server, you can send commands as a [JSON](https://en.wikipedia.org/wiki/JSON) object, with the following attributes: @@ -50,7 +50,7 @@ After you open a WebSocket to the `rippled` server, you can send commands as a [ The response comes as a JSON object. -#### Public Servers #### +#### Public Servers Currently Ripple (the company) maintains a set of public WebSocket servers at: @@ -62,11 +62,11 @@ Currently Ripple (the company) maintains a set of public WebSocket servers at: These public servers are not for sustained or business use, and they may become unavailable at any time. For regular use, you should run your own `rippled` server or contract someone you trust to do so. -### JSON-RPC ### +### JSON-RPC You can use any HTTP client (like [Poster for Firefox](https://addons.mozilla.org/en-US/firefox/addon/poster/) or [Postman for Chrome](https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en)) to make JSON-RPC calls a `rippled` server. Most programming languages have a library for making HTTP requests built in. -#### Request Formatting #### +#### Request Formatting To make a JSON-RPC request, send an HTTP **POST** request to the root path (`/`) on the port and IP where the `rippled` server is listening for JSON-RPC connections. You can use HTTP/1.0 or HTTP/1.1. If you use HTTPS, you should use TLS v1.2. For security reasons, `rippled` _does not support_ SSL v3 or earlier. @@ -81,7 +81,7 @@ Send request body as a [JSON](https://en.wikipedia.org/wiki/JSON) object with th The response is also a JSON object. -#### Public Servers #### +#### Public Servers Currently, Ripple (the company) maintains a set of public JSON-RPC servers at: @@ -93,7 +93,7 @@ Currently, Ripple (the company) maintains a set of public JSON-RPC servers at: These public servers are not for sustained or business use, and they may become unavailable at any time. For regular use, you should run your own `rippled` server or contract someone you trust to do so. -### Commandline ### +### Commandline The commandline interface connects to the same service as the JSON-RPC one, so the public servers and server configuration are the same. As a commandline client, `rippled` connects to the local instance. For example: @@ -104,11 +104,11 @@ rippled --conf=/etc/rippled.cfg server_info **Note:** The commandline interface is intended for administrative purposes only and is _not a supported API_. -#### Request Formatting #### +#### Request Formatting The commandline puts the command after any normal (dash-prefaced) commandline options, followed by a limited set of parameters, separated by spaces. For any parameter values that might contain spaces or other unusual characters, use single-quotes to encapsulate them. -## Example Request ## +## Example Request @@ -148,9 +148,9 @@ rippled account_info r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 validated true -## Response Formatting ## +## Response Formatting -#### Example Successful Response #### +#### Example Successful Response @@ -234,10 +234,10 @@ The fields of a successful response include: | `type` | String | (WebSocket only) The value `response` indicates a successful response to a command. [Asynchronous notifications](#subscriptions) use a different value such as `ledgerClosed` or `transaction`. | | `result` | Object | The result of the query; contents vary depending on the command. | -#### Commandline #### +#### Commandline The response format for commandline methods is the same as JSON-RPC responses, because they use the same interface. -## Error Responses ## +## Error Responses It is impossible to list all the possible ways an error can occur. Some may occur in the transport layer (for example, loss of network connectivity), in which case the results vary depending on what client and transport you are using. However, if the `rippled` server successfully receives your request, it tries to respond in a standardized error format. Some example errors: @@ -299,7 +299,7 @@ HTTP Status: 200 OK -#### WebSocket API Error Response Format #### +#### WebSocket API Error Response Format | `Field` | Type | Description | |:----------|:---------|:------------------------------------------------------| | `id` | (Varies) | ID provided in the Web Socket request that prompted this response | @@ -308,7 +308,7 @@ HTTP Status: 200 OK | `error` | String | A unique code for the type of error that occurred | | `request` | Object | A copy of the request that prompted this error, in JSON format. **Caution:** If the request contained any account secrets, they are copied here! | -#### JSON-RPC API Error Response Format #### +#### JSON-RPC API Error Response Format Some JSON-RPC request respond with an error code on the HTTP layer. In these cases, the response is a plain-text explanation in the response body. For example, if you forgot to specify the command in the `method` parameter, the response is like this: ``` @@ -325,11 +325,11 @@ For other errors that returned with HTTP status code 200 OK, the responses are f | `result.status` | String | `"error"` if the request caused an error | | `result.request` | Object | A copy of the request that prompted this error, in JSON format. **Caution:** If the request contained any account secrets, they are copied here! **Note:** The request is re-formatted in WebSocket format, regardless of the request made. | -### Caution on Errors ### +### Caution on Errors When your request results in an error, the entire request is copied back as part of the response, so that you can try to debug the error. However, this also includes any secrets that were passed as part of the request. When sharing error messages, be very careful not to accidentally expose important account secrets to others. -### Universal Errors ### +### Universal Errors All methods can potentially return any of the following values for the `error` code: @@ -344,13 +344,13 @@ All methods can potentially return any of the following values for the `error` c * `noClosed` - The server does not have a closed ledger, typically because it has not finished starting up. * `wsTextRequired` - (WebSocket only) The request's [opcode](https://tools.ietf.org/html/rfc6455#section-5.2) is not text. -## Formatting Conventions ## +## Formatting Conventions The WebSocket and JSON-RPC APIs generally take the same arguments, although they're provided in a different way (See [Request Formatting](#request-formatting) for details). Many similar parameters appear throughout the APIs, and there are conventions for how to specify these parameters. All field names are case-sensitive. In responses, fields that are taken directly from ledger objects or transaction instructions start with upper-case letters. Other fields, including ones that are dynamically generated for a response, are lower case. -## Basic Data Types ## +## Basic Data Types Different types of objects are uniquely identified in different ways: @@ -360,31 +360,31 @@ Different types of objects are uniquely identified in different ways: Each closed [Ledger](reference-ledger-format.html) has a [Ledger Index][] and a [Hash][] value. When [Specifying a Ledger Instance](#specifying-ledgers) you can use either one. -### Addresses ### +### Addresses [Address]: #addresses {% include 'data_types/address.md' %} -### Hashes ### +### Hashes [Hash]: #hashes {% include 'data_types/hash.md' %} -### Account Sequence ### +### Account Sequence [Sequence Number]: #account-sequence {% include 'data_types/account_sequence.md' %} -### Ledger Index ### +### Ledger Index [Ledger Index]: #ledger-index {% include 'data_types/ledger_index.md' %} -### Specifying Ledgers ### +### Specifying Ledgers Many API methods require you to specify an instance of the ledger, with the data retrieved being considered up-to-date as of that particular version of the shared ledger. The commands that accept a ledger version all work the same way. There are three ways you can specify which ledger you want to use: @@ -402,7 +402,7 @@ If you do not specify a ledger, the `current` (in-progress) ledger is chosen by **Note:** Do not rely on this default behavior for specifying a ledger; it is subject to change. Always specify a ledger version in the request if you can. -## Currencies ## +## Currencies There are two kinds of currencies in the XRP Ledger: XRP, and everything else. There are many differences between the two: @@ -417,11 +417,11 @@ There are two kinds of currencies in the XRP Ledger: XRP, and everything else. T **Caution:** The XRP Ledger uses decimal math with different precision than typical floating-point numbers, so currency amounts are always presented as strings. -### Specifying Currency Amounts ### +### Specifying Currency Amounts Some API methods require you to specify an amount of currency. Depending on whether you are dealing in the network's native XRP currency or other currency units (called _issuances_), the style for specifying it is very different. -#### XRP #### +#### XRP [drops of XRP]: #xrp [XRP, in drops]: #xrp @@ -435,7 +435,7 @@ Amounts of XRP are represented as strings. (XRP has precision equivalent to a 64 Unit tests are permitted to submit values of XRP (not drops) with a decimal point - for example, "1.23" meaning 1.23 XRP. All other cases should always specify XRP in drops, with no decimal point: e.g. "1230000" meaning 1.23 XRP. -#### Non-XRP #### +#### Non-XRP If you are specifying non-XRP currency (including fiat dollars, precious metals, cryptocurrencies, or other custom currency) you must specify it with a currency specification object. This is a JSON object with three fields: @@ -459,7 +459,7 @@ For example, to represent $153.75 US dollars issued by account `r9cZA1mLK5R5Am25 Unit tests are permitted to submit amounts of non-XRP currencies as a slash-separated string in the format `"amount/currency/issuer"`. All other cases should use the JSON object format above. -#### Specifying Currencies Without Amounts #### +#### Specifying Currencies Without Amounts If you are specifying a non-XRP currency without an amount (typically for defining an order book of currency exchange offers) you should specify it as above, but omit the `value` field. @@ -467,19 +467,19 @@ If you are specifying XRP without an amount (typically for defining an order boo Finally, if the recipient account of the payment trusts multiple issuers for a currency, you can indicate that the payment should be made in any combination of issuers that the recipient accepts. To do this, specify the recipient account's address as the `issuer` value in the JSON object. -### Currency Codes ### +### Currency Codes [Currency Code]: #currency-codes {% include 'data_types/currency_code.md' %} -## Specifying Time ## +## Specifying Time The `rippled` server and its APIs represent time as an unsigned integer. This number measures the number of seconds since the "Ripple Epoch" of January 1, 2000 (00:00 UTC). This is like the way the [Unix epoch](http://en.wikipedia.org/wiki/Unix_time) works, except the Ripple Epoch is 946684800 seconds after the Unix Epoch. Don't convert Ripple Epoch times to UNIX Epoch times in 32-bit variables: this could lead to integer overflows. -## Possible Server States ## +## Possible Server States Depending on how the `rippled` server is configured, how long it has been running, and other factors, a server may be participating in the global XRP Ledger peer-to-peer network to different degrees. This is represented as the `server_state` field in the responses to the [`server_info`](#server-info) and [`server_state`](#server-state) commands. The possible responses follow a range of ascending interaction, with each later value superseding the previous one. Their definitions are as follows (in order of increasing priority): @@ -495,14 +495,14 @@ Depending on how the `rippled` server is configured, how long it has been runnin **Note:** The distinction between `full`, `validating`, and `proposing` is based on synchronization with the rest of the global network, and it is normal for a server to fluctuate between these states as a course of general operation. -## Markers and Pagination ## +## Markers and Pagination Some methods return more data than can efficiently fit into one response. When there are more results than contained, the response includes a `marker` field. You can use this to retrieve more pages of data across multiple calls. In each request, pass the `marker` value from the previous response to resume from the point where you left off. If the `marker` is omitted from a response, then you have reached the end of the data set. The format of the `marker` field is intentionally undefined. Each server can define a `marker` field as desired, so it may take the form of a string, a nested object, or another type. Different servers, and different methods provided by the same server, can have different `marker` definitions. Each `marker` is ephemeral, and may not work as expected after 10 minutes. -## Modifying the Ledger ## +## Modifying the Ledger All changes to the XRP Ledger happen as the result of transactions. The only API methods that can change the contents of the XRP Ledger are the commands that submit transactions. Even then, changes only apply permanently if the transactions are approved by the [consensus process](concept-consensus.html). Most other public methods represent different ways to view the data represented in the XRP Ledger, or request information about the state of the server. @@ -515,12 +515,12 @@ For more information on the various transactions you can submit, see the [Transa -# API Methods # +# API Methods API methods for the Websocket and JSON-RPC APIs are defined by command names, and are divided into Public Commands and Admin Commands. Public Commands are not necessarily meant for the general public, but they are used by any client attached to the server. (Think of Public Commands as being for members or customers of the organization running the server, while the Admin Commands are for the personnel in charge of keeping the server operational.) Public Commands include operations such as checking the state of the ledger, finding a path to connecting users, and submitting a transaction, among others. Admin Commands, on the other hand, are meant only for trusted server operators, and include commands for managing, monitoring, and debugging the server. -## List of Public Commands ## +## List of Public Commands * [`account_currencies` - Get a list of currencies an account can send or receive](#account-currencies) * [`account_channels` - Get a list of payment channels where the account is the source of the channel](#account-channels) @@ -558,7 +558,7 @@ API methods for the Websocket and JSON-RPC APIs are defined by command names, an The `owner_info` command is deprecated. Use [`account_objects`](#account-objects) instead. -## List of Admin Commands ## +## List of Admin Commands Admin commands are only available if you [connect to `rippled`](#connecting-to-rippled) on a host and port that the config file identifies as admin. (By default, the commandline client uses an admin connection.) @@ -589,7 +589,7 @@ The following admin commands are deprecated and may be removed without further n * `wallet_seed` - Use [`wallet_propose`](#wallet-propose) instead. -## Commandline Access ## +## Commandline Access You can use the `rippled` application (as a separate instance) as a JSON-RPC client. In this mode, it has syntax for triggering most API methods with a single line from the command prompt, as described in each method. However, some methods or options don't have commandline syntax. For otherwise unsupported syntax, you can use the following method: @@ -598,16 +598,16 @@ You can use the `rippled` application (as a separate instance) as a JSON-RPC cli **Note:** The commandline interface is intended for administrative purposes only and is _not a supported API_. -# Account Information # +# Account Information An "Account" in the XRP Ledger represents a holder of XRP and a sender of transactions. Accounts can send and receive XRP and issued assets, participate in the decentralized exchange, and change their own settings. Creating an account involves generating keys and then receiving XRP from another account. For more information, see [Accounts](concept-accounts.html). -## account_currencies ## +## account_currencies [[Source]
](https://github.com/ripple/rippled/blob/df966a9ac6dd986585ecccb206aff24452e41a30/src/ripple/rpc/handlers/AccountCurrencies.cpp "Source") The `account_currencies` command retrieves a list of currencies that an account can send or receive, based on its trust lines. (This is not a thoroughly confirmed list, but it can be used to populate user interfaces.) -#### Request Format #### +#### Request Format An example of the request format: @@ -654,7 +654,7 @@ The request includes the following parameters: The following field is deprecated and should not be provided: `account_index`. -#### Response Format #### +#### Response Format An example of a successful response: @@ -744,7 +744,7 @@ The response follows the [standard format](#response-formatting), with a success **Note:** The currencies that an account can send or receive are defined based on a check of its trust lines. If an account has a trust line for a currency and enough room to increase its balance, it can receive that currency. If the trust line's balance can go down, the account can send that currency. This method _doesn't_ check whether the trust line is [frozen](concept-freeze.html) or authorized. -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. @@ -928,12 +928,12 @@ Each Channel Object has the following fields: -## account_info ## +## account_info [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/AccountInfo.cpp "Source") The `account_info` command retrieves information about an account, its activity, and its XRP balance. All information retrieved is relative to a particular version of the ledger. -#### Request Format #### +#### Request Format An example of an account_info request: @@ -992,7 +992,7 @@ The request contains the following parameters: The following fields are deprecated and should not be provided: `ident`, `ledger`. -#### Response Format #### +#### Response Format An example of a successful response: @@ -1130,7 +1130,7 @@ Each object in the `transactions` array, if present, may contain any or all of t | `max_spend_drops` | String | The maximum amount of XRP, [in drops](#specifying-currency-amounts), this transaction could send or destroy. | | `seq` | Integer | The [Sequence Number][] of this transaction. | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. For example, the request specified `queue` as `true` but specified a `ledger_index` that is not the current open ledger. @@ -1139,12 +1139,12 @@ Each object in the `transactions` array, if present, may contain any or all of t -## account_lines ## +## account_lines [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/AccountLines.cpp "Source") The `account_lines` method returns information about an account's trust lines, including balances in all non-XRP currencies and assets. All information retrieved is relative to a particular version of the ledger. -#### Request Format #### +#### Request Format An example of the request format: @@ -1192,7 +1192,7 @@ The request accepts the following paramters: The following parameters are deprecated and may be removed without further notice: `ledger` and `peer_index`. -#### Response Format #### +#### Response Format An example of a successful response: @@ -1316,7 +1316,7 @@ Each trust line object has some combination of the following fields: | `freeze` | Boolean | (May be omitted) `true` if this account has [frozen](concept-freeze.html) this trust line. If omitted, that is the same as `false`. | | `freeze_peer` | Boolean | (May be omitted) `true` if the peer account has [frozen](concept-freeze.html) this trust line. If omitted, that is the same as `false`. | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. @@ -1325,12 +1325,12 @@ Each trust line object has some combination of the following fields: * `actMalformed` - If the `marker` field provided is not acceptable. -## account_offers ## +## account_offers [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/AccountOffers.cpp "Source") The `account_offers` method retrieves a list of offers made by a given account that are outstanding as of a particular ledger version. -#### Request Format #### +#### Request Format An example of the request format: @@ -1385,7 +1385,7 @@ A request can include the following parameters: The following parameter is deprecated and may be removed without further notice: `ledger`. -#### Response Format #### +#### Response Format An example of a successful response: @@ -1505,7 +1505,7 @@ Each offer object contains the following fields: | `quality` | Number | The exchange rate of the offer, as the ratio of the original `taker_pays` divided by the original `taker_gets`. When executing offers, the offer with the most favorable (lowest) quality is consumed first; offers with the same quality are executed from oldest to newest. [New in: rippled 0.29.0][] | | `expiration` | Unsigned integer | (May be omitted) A time after which this offer is considered unfunded, as [the number of seconds since the Ripple Epoch](#specifying-time). See also: [Offer Expiration](reference-transaction-format.html#expiration). [New in: rippled 0.30.1][] | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. @@ -1514,7 +1514,7 @@ Each offer object contains the following fields: * `actMalformed` - If the `marker` field provided is not acceptable. -## account_objects ## +## account_objects [[Source]
](https://github.com/ripple/rippled/blob/399c43cae6e90a428e9ce6a988123972b0f03c99/src/ripple/rpc/handlers/AccountObjects.cpp "Source") The `account_objects` command returns the raw [ledger format][] for all objects owned by an account. For a higher-level view of an account's trust lines and balances, see [`account_lines`](#account-lines) instead. @@ -1530,7 +1530,7 @@ The types of objects that may appear in the `account_objects` response for an ac - [PayChannel objects](reference-ledger-format.html#paychannel) for open payment channels. -#### Request Format #### +#### Request Format An example of the request format: @@ -1585,7 +1585,7 @@ The request includes the following parameters: | `limit` | Unsigned Integer | _(Optional)_ The maximum number of objects to include in the results. Must be within the inclusive range 10 to 400 on non-admin connections. Defaults to 200. | | `marker` | [(Not Specified)](#markers-and-pagination) | _(Optional)_ Value from a previous paginated response. Resume retrieving data where that response left off. | -#### Response Format #### +#### Response Format An example of a successful response: @@ -2125,7 +2125,7 @@ The response follows the [standard format](#response-formatting), with a success | `marker` | [(Not Specified)](#markers-and-pagination) | Server-defined value indicating the response is paginated. Pass this to the next call to resume where this call left off. Omitted when there are no additional pages after this one. | | `validated` | Boolean | If `true`, this information comes from ledger version that has been validated by consensus. | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. @@ -2134,12 +2134,12 @@ The response follows the [standard format](#response-formatting), with a success -## account_tx ## +## account_tx [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/AccountTx.cpp "Source") The `account_tx` method retrieves a list of transactions that involved the specified account. -#### Request Format #### +#### Request Format An example of the request format: @@ -2209,13 +2209,13 @@ While each of these fields is marked as optional, **you must use at least one** **Note:** For WebSocket and JSON-RPC, there is also a deprecated legacy variation of the `account_tx` method. For that reason, Ripple recommends *not using any of the following fields*: `offset`, `count`, `descending`, `ledger_max`, and `ledger_min`. If you use any of these deprecated fields, the method does not support pagination. -##### **Iterating over queried data** ###### +##### **Iterating over queried data** As with other paginated methods, you can use the `marker` field to return multiple pages of data. In the time between requests, `"ledger_index_min": -1` and `"ledger_index_max": -1` may change to refer to different ledger versions than they did before. The `marker` field can safely paginate even if there are changes in the ledger range from the request, so long as the marker does not indicate a point outside the range of ledgers specified in the request. -#### Response Format #### +#### Response Format An example of a successful response: @@ -2718,7 +2718,7 @@ Each transaction object includes the following fields, depending on whether it w | `tx_blob` | String | (Binary mode only) Unique hashed String representing the transaction. | | `validated` | Boolean | Whether or not the transaction is included in a validated ledger. Any transaction not yet in a validated ledger is subject to change. | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. @@ -2727,12 +2727,12 @@ Each transaction object includes the following fields, depending on whether it w * `lgrIdxsInvalid` - The ledger specified by the `ledger_index_min` or `ledger_index_max` does not exist, or if it does exist but the server does not have it. -## noripple_check ## +## noripple_check [[Source]
](https://github.com/ripple/rippled/blob/9111ad1a9dc37d49d085aa317712625e635197c0/src/ripple/rpc/handlers/NoRippleCheck.cpp "Source") The `noripple_check` command provides a quick way to check the status of [the DefaultRipple field for an account and the NoRipple flag of its trust lines](concept-noripple.html), compared with the recommended settings. -#### Request Format #### +#### Request Format An example of the request format: @@ -2783,7 +2783,7 @@ The request includes the following parameters: | `ledger_hash` | String | _(Optional)_ A 20-byte hex string for the ledger version to use. (See [Specifying a Ledger](#specifying-ledgers)) | | `ledger_index` | String or Unsigned Integer | _(Optional)_ The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying a Ledger](#specifying-ledgers)) | -#### Response Format #### +#### Response Format An example of a successful response: @@ -2902,7 +2902,7 @@ The response follows the [standard format](#response-formatting), with a success | `problems` | Array | Array of strings with human-readable descriptions of the problems. This includes up to one entry if the account's DefaultRipple setting is not as recommended, plus up to `limit` entries for trust lines whose NoRipple setting is not as recommended. | | `transactions` | Array | (May be omitted) If the request specified `transactions` as `true`, this is an array of JSON objects, each of which is the JSON form of a [transaction](reference-transaction-format.html) that should fix one of the described problems. The length of this array is the same as the `problems` array, and each entry is intended to fix the problem described at the same index into that array. | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. @@ -2910,12 +2910,12 @@ The response follows the [standard format](#response-formatting), with a success * `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it. -## gateway_balances ## +## gateway_balances [[Source]
](https://github.com/ripple/rippled/blob/9111ad1a9dc37d49d085aa317712625e635197c0/src/ripple/rpc/handlers/GatewayBalances.cpp "Source") The `gateway_balances` command calculates the total balances issued by a given account, optionally excluding amounts held by [operational addresses](concept-issuing-and-operational-addresses.html). [New in: rippled 0.28.2][] -#### Request Format #### +#### Request Format An example of the request format: @@ -2964,7 +2964,7 @@ The request includes the following parameters: | `ledger_hash` | String | _(Optional)_ A 20-byte hex string for the ledger version to use. (See [Specifying a Ledger](#specifying-ledgers)) | | `ledger_index` | String or Unsigned Integer | _(Optional)_ The sequence number of the ledger version to use, or a shortcut string to choose a ledger automatically. (See [Specifying a Ledger](#specifying-ledgers)) | -#### Response Format #### +#### Response Format An example of a successful response: @@ -3120,7 +3120,7 @@ The response follows the [standard format](#response-formatting), with a success | `ledger_index` | Number | (May be omitted) The sequence number of the ledger version that was used to generate this response. | | `ledger_current_index` | Number | (May be omitted) The sequence number of the current in-progress ledger version that was used to generate this response. | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. @@ -3130,7 +3130,7 @@ The response follows the [standard format](#response-formatting), with a success -## wallet_propose ## +## wallet_propose [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/WalletPropose.cpp "Source") Use the `wallet_propose` method to generate a key pair and XRP Ledger address. This command only generates keys, and does not affect the XRP Ledger itself in any way. To become a funded address stored in the ledger, the address must [receive a Payment transaction](reference-transaction-format.html#creating-accounts) that provides enough XRP to meet the [reserve requirement](concept-reserves.html). @@ -3139,7 +3139,7 @@ Use the `wallet_propose` method to generate a key pair and XRP Ledger address. T [Updated in: rippled 0.31.0][New in: rippled 0.31.0] -#### Request Format #### +#### Request Format An example of the request format: @@ -3213,7 +3213,7 @@ You must provide **at most one** of the following fields: `passphrase`, `seed`, **Note:** [Ed25519](https://ed25519.cr.yp.to/) support is experimental. The commandline version of this command cannot generate Ed25519 keys. -##### Specifying a Seed ##### +##### Specifying a Seed For most cases, you should use a seed value generated from a strong source of randomness. Anyone who knows the seed value for an address has full power to [send transactions signed by that address](reference-transaction-format.html#authorizing-transactions). Generally, running this command with no parameters is a good way to generate a random seed. @@ -3233,7 +3233,7 @@ If you do specify a seed, you can specify it in any of the following formats: [RFC-1751]: https://tools.ietf.org/html/rfc1751 [hexadecimal]: https://en.wikipedia.org/wiki/Hexadecimal -#### Response Format #### +#### Response Format An example of a successful response: @@ -3310,7 +3310,7 @@ The response follows the [standard format](#response-formatting), with a success The key generated by this method can also be used as a regular key for an account if you use the [SetRegularKey transaction type](reference-transaction-format.html#setregularkey) to do so. -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly. @@ -3318,7 +3318,7 @@ The key generated by this method can also be used as a regular key for an accoun -# Ledger Information # +# Ledger Information Each `rippled` server keeps a complete copy of the XRP Ledger's current state, which contains all the accounts, transactions, offers, and other data in the network in an optimized tree format. As transactions and offers are proposed, each server incorporates them into its current copy of the ledger, closes it periodically, and (if configured) participates in advancing the globally-validated version. After the network reaches consensus, that ledger version is validated and becomes permanently immutable. Any transactions that were not included in one ledger version become candidates to be included in the next validated version. @@ -3327,7 +3327,7 @@ Each `rippled` server keeps a complete copy of the XRP Ledger's current state, w Retrieve information about the public ledger. -#### Request Format #### +#### Request Format An example of the request format: @@ -3394,7 +3394,7 @@ The request can contain the following parameters: The `ledger` field is deprecated and may be removed without further notice. -#### Response Format #### +#### Response Format An example of a successful response: @@ -3510,7 +3510,7 @@ If the request specified `"owner_funds": true` and expanded transactions, the re |:--------------|:-------|:----------------------------------------------------| | `owner_funds` | String | Numeric amount of the `TakerGets` currency that the `Account` sending this OfferCreate transaction has after the execution of all transactions in this ledger. This does not check whether the currency amount is [frozen](concept-freeze.html). | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. @@ -3518,12 +3518,12 @@ If the request specified `"owner_funds": true` and expanded transactions, the re * `noPermission` - If you specified `full` or `accounts` as true, but are not connected to the server as an admin (usually, admin requires connecting on a local port). -## ledger_closed ## +## ledger_closed [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/LedgerClosed.cpp "Source") The `ledger_closed` method returns the unique identifiers of the most recently closed ledger. (This ledger is not necessarily validated and immutable yet.) -#### Request Format #### +#### Request Format An example of the request format: @@ -3561,7 +3561,7 @@ rippled ledger_closed This method accepts no parameters. -#### Response Format #### +#### Response Format An example of a successful response: @@ -3602,17 +3602,17 @@ The response follows the [standard format](#response-formatting), with a success | `ledger_hash` | String | 20-byte hex string with a unique hash of the ledger | | `ledger_index` | Unsigned Integer | Sequence number of this ledger | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). -## ledger_current ## +## ledger_current [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/LedgerCurrent.cpp "Source") The `ledger_current` method returns the unique identifiers of the current in-progress ledger. This command is mostly useful for testing, because the ledger returned is still in flux. -#### Request Format #### +#### Request Format An example of the request format: @@ -3652,7 +3652,7 @@ rippled ledger_current The request contains no parameters. -#### Response Format #### +#### Response Format An example of a successful response: @@ -3692,17 +3692,17 @@ The response follows the [standard format](#response-formatting), with a success A `ledger_hash` field is not provided, because the hash of the current ledger is constantly changing along with its contents. -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). -## ledger_data ## +## ledger_data [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/LedgerData.cpp "Source") The `ledger_data` method retrieves contents of the specified ledger. You can iterate through several calls to retrieve the entire contents of a single ledger version. -#### Request Format #### +#### Request Format An example of the request format: @@ -3751,7 +3751,7 @@ A request can include the following fields: The `ledger` field is deprecated and may be removed without further notice. -#### Response Format #### +#### Response Format An example of a successful response: @@ -3949,21 +3949,21 @@ The format of each object in the `state` array depends on whether `binary` was s | (Additional fields) | (Various) | (Only included if `"binary":false`) Additional fields describing this object, depending on which LedgerEntryType it is. | | `index` | String | Unique identifier for this ledger entry, as hex. | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors) * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. * `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it. -## ledger_entry ## +## ledger_entry [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/LedgerEntry.cpp "Source") The `ledger_entry` method returns a single ledger object from the XRP Ledger in its raw format. See [ledger format][] for information on the different types of objects you can retrieve. **Note:** There is no commandline version of this method. You can use the [`json` command](#json) to access this method from the commandline instead. -#### Request Format #### +#### Request Format An example of the request format: @@ -4032,7 +4032,7 @@ The full list of parameters recognized by this method is as follows: The `generator` and `ledger` parameters are deprecated and may be removed without further notice. -#### Response Format #### +#### Response Format An example of a successful response: @@ -4098,21 +4098,21 @@ The response follows the [standard format](#response-formatting), with a success | `node` | Object | (Omitted if `"binary": true` specified.) Object containing the data of this ledger object, according to the [ledger format][]. | | `node_binary` | String | (Omitted unless `"binary":true` specified) Binary data of the ledger object, as hex. | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. * `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it. -## ledger_request ## +## ledger_request [[Source]
](https://github.com/ripple/rippled/blob/e980e69eca9ea843d200773eb1f43abe3848f1a0/src/ripple/rpc/handlers/LedgerRequest.cpp "Source") The `ledger_request` command tells server to fetch a specific ledger version from its connected peers. This only works if one of the server's immediately-connected peers has that ledger. You may need to run the command several times to completely fetch a ledger. *The `ledger_request` request is an [admin command](#connecting-to-rippled) that cannot be run by unprivileged users!* -#### Request Format #### +#### Request Format An example of the request format: @@ -4144,7 +4144,7 @@ The request includes the following parameters: You must provide either `ledger_index` or `ledger_hash` but not both. -#### Response Format #### +#### Response Format The response follows the [standard format](#response-formatting). However, the request returns a failure response if it does not have the specified ledger _even if it successfully instructed the `rippled` server to start retrieving the ledger_. @@ -4263,7 +4263,7 @@ The three possible response formats are as follows: 2. When the response shows the server is currently fetching the ledger, the body of the result is a [Ledger Request Object](#ledger-request-object) indicating the progress of fetching the ledger from the peer-to-peer network. 3. When the ledger is fully available, the response is a representation of the [ledger header](reference-ledger-format.html#header-format). -#### Ledger Request Object #### +#### Ledger Request Object When the server is in the progress of fetching a ledger, but has not yet finished, the `rippled` server returns a ledger request object indicating its progress towards fetching the ledger. This object has the following fields: @@ -4278,21 +4278,21 @@ When the server is in the progress of fetching a ledger, but has not yet finishe | `peers` | Number | How many peers the server is querying to find this ledger. | | `timeouts` | Number | Number of times fetching this ledger has timed out so far. | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. This error can also occur if you specify a ledger index equal or higher than the current in-progress ledger. * `lgrNotFound` - If the ledger is not yet available. This indicates that the server has started fetching the ledger, although it may fail if none of its connected peers have the requested ledger. (Previously, this error used the code `ledgerNotFound` instead.) [Updated in: rippled 0.30.1][New in: rippled 0.30.1] -## ledger_accept ## +## ledger_accept [[Source]
](https://github.com/ripple/rippled/blob/a61ffab3f9010d8accfaa98aa3cacc7d38e74121/src/ripple/rpc/handlers/LedgerAccept.cpp "Source") The `ledger_accept` method forces the server to close the current-working ledger and move to the next ledger number. This method is intended for testing purposes only, and is only available when the `rippled` server is running stand-alone mode. *The `ledger_accept` method is an [admin command](#connecting-to-rippled) that cannot be run by unprivileged users!* -#### Request Format #### +#### Request Format An example of the request format: @@ -4318,7 +4318,7 @@ rippled ledger_accept The request accepts no parameters. -#### Response Format #### +#### Response Format An example of a successful response: ```js @@ -4340,25 +4340,25 @@ The response follows the [standard format](#response-formatting), with a success **Note:** When you close a ledger, `rippled` determines the canonical order of transactions in that ledger and replays them. This can change the outcome of transactions that were provisionally applied to the current ledger. -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `notStandAlone` - If the `rippled` server is not currently running in stand-alone mode. -# Transactions # +# Transactions Transactions are the only thing that can modify the shared state of the XRP Ledger. All business on the XRP Ledger takes the form of transactions, which include not only payments, but also currency-exchange offers, account settings, and changes to the properties of the ledger itself (like adopting new features). There are several sources of complication in transactions. Unlike traditional banking, where a trusted third party (the bank, or the [ACH](http://en.wikipedia.org/wiki/Automated_Clearing_House)) verifies the participants' identities and ensures their balances are adjusted accurately, Ripple uses cryptography and decentralized computing power to do the same thing. Sending XRP requires no third party aside from the distributed network itself. However, the XRP Ledger also supports issuing balances in any currency and trading them in a decentralized exchange. This brings far more power, but it also means that the system must account for [counterparty risk](http://en.wikipedia.org/wiki/Counterparty_risk#Counterparty_risk), currency conversions, and other issues. The XRP Ledger must be robust to keep track of which transactions have been completely validated, even when subject to hardware failures, attacks, or natural disasters. -## tx ## +## tx [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/Tx.cpp "Source") The `tx` method retrieves information on a single transaction. -#### Request Format #### +#### Request Format An example of the request format: @@ -4405,7 +4405,7 @@ The request includes the following parameters: | `transaction` | String | The 256-bit hash of the transaction, as hex. | | `binary` | Boolean | (Optional, defaults to false) If true, return transaction data and metadata as hex strings instead of JSON | -#### Response Format #### +#### Response Format An example of a successful response: @@ -4552,7 +4552,7 @@ The response follows the [standard format](#response-formatting), with a success | `validated` | Boolean | True if this data is from a validated ledger version; if omitted or set to false, this data is not final. | | (Various) | (Various) | Other fields from the [Transaction object](reference-transaction-format.html) | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. @@ -4560,12 +4560,12 @@ The response follows the [standard format](#response-formatting), with a success -## transaction_entry ## +## transaction_entry [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/TransactionEntry.cpp "Source") The `transaction_entry` method retrieves information on a single transaction from a specific ledger version. (The [`tx`](#tx) command, by contrast, searches all ledgers for the specified transaction. We recommend using that method instead.) -#### Request Format #### +#### Request Format An example of the request format: @@ -4617,7 +4617,7 @@ The request includes the following parameters: **Note:** This method does not support retrieving information from the current in-progress ledger. You must specify a ledger version in either `ledger_index` or `ledger_hash`. -#### Response Format #### +#### Response Format An example of a successful response: @@ -4770,7 +4770,7 @@ There are a couple possible reasons the server may fail to find the transaction: * The transaction exists, but not in the specified ledger version * The server does not have the specified ledger version available. Another server that has the correct version on hand may have a different response. -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `fieldNotFoundTransaction` - The `tx_hash` field was omitted from the request @@ -4781,14 +4781,14 @@ There are a couple possible reasons the server may fail to find the transaction: -## tx_history ## +## tx_history [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/TxHistory.cpp "Source") The `tx_history` method retrieves some of the most recent transactions made. **Caution:** This method is deprecated, and may be removed without further notice. -#### Request Format #### +#### Request Format An example of the request format: @@ -4833,7 +4833,7 @@ The request includes the following parameters: |:--------|:-----------------|:-------------------------------------| | `start` | Unsigned Integer | Number of transactions to skip over. | -#### Response Format #### +#### Response Format An example of a successful response: @@ -5670,14 +5670,14 @@ The response follows the [standard format](#response-formatting), with a success The fields included in each transaction object vary slightly depending on the type of transaction. See [Transaction Format](reference-transaction-format.html) for details. -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. * `noPermission` - The `start` field specified was greater than 10000, but you are not connected to the server as an admin. -## path_find ## +## path_find [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp "Source") *WebSocket API only!* The `path_find` method searches for a [path](concept-paths.html) along which a transaction can possibly be made, and periodically sends updates when the path changes over time. For a simpler version that is supported by JSON-RPC, see [`ripple_path_find`](#ripple-path-find). For payments occurring strictly in XRP, it is not necessary to find a path, because XRP can be sent directly to any account. @@ -5690,14 +5690,14 @@ There are three different modes, or sub-commands, of the path_find command. Spec Although the `rippled` server tries to find the cheapest path or combination of paths for making a payment, it is not guaranteed that the paths returned by this method are, in fact, the best paths. Due to server load, pathfinding may not find the best results. Additionally, you should be careful with the pathfinding results from untrusted servers. A server could be modified to return less-than-optimal paths to earn money for its operators. If you do not have your own server that you can trust with pathfinding, you should compare the results of pathfinding from multiple servers run by different parties, to minimize the risk of a single server returning poor results. (**Note:** A server returning less-than-optimal results is not necessarily proof of malicious behavior; it could also be a symptom of heavy server load.) -### path_find create ### +### path_find create [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp#L38 "Source") The `create` subcommand of `path_find` creates an ongoing request to find possible paths along which a payment transaction could be made from one specified account such that another account receives a desired amount of some currency. The initial response contains a suggested path between the two addresses that would result in the desired amount being received. After that, the server sends additional messages, with `"type": "path_find"`, with updates to the potential paths. The frequency of updates is left to the discretion of the server, but it usually means once every few seconds when there is a new ledger version. A client can only have one pathfinding request open at a time. If another pathfinding request is already open on the same connection, the old request is automatically closed and replaced with the new request. -#### Request Format #### +#### Request Format An example of the request format: @@ -5736,7 +5736,7 @@ The request includes the following parameters: The server also recognizes the following fields, but the results of using them are not guaranteed: `source_currencies`, `bridges`. These fields should be considered reserved for future use. -#### Response Format #### +#### Response Format An example of a successful response: @@ -6130,13 +6130,13 @@ Each element in the `alternatives` array is an object that represents a path fro | `paths_computed` | Array | Array of arrays of objects defining [payment paths](concept-paths.html) | | `source_amount` | String or Object | [Currency amount](#specifying-currency-amounts) that the source would have to send along this path for the destination to receive the desired amount | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. * `noEvents` - You are using a protocol that does not support asynchronous callbacks, for example JSON-RPC. (See [ripple\_path\_find](#ripple-path-find) for a pathfinding method that _is_ compatible with JSON-RPC.) -#### Asynchronous Follow-ups #### +#### Asynchronous Follow-ups In addition to the initial response, the server sends more messages in a similar format to update on the status of [payment paths](concept-paths.html) over time. These messages include the `id` of the original WebSocket request so you can tell which request prompted them, and the field `"type": "path_find"` at the top level to indicate that they are additional responses. The other fields are defined in the same way as the initial response. @@ -6167,12 +6167,12 @@ Here is an example of an asychronous follow-up from a path_find create request: -### path_find close ### +### path_find close [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp#L46 "Source") The `close` subcommand of `path_find` instructs the server to stop sending information about the current open pathfinding request. -#### Request Format #### +#### Request Format An example of the request format: @@ -6195,7 +6195,7 @@ The request includes the following parameters: |:-------------|:-------|:-------------------------------------------| | `subcommand` | String | Use `"close"` to send the close subcommand | -#### Response Format #### +#### Response Format If a pathfinding request was successfully closed, the response follows the same format as the initial response to [`path_find create`](#path-find-create), plus the following field: @@ -6205,19 +6205,19 @@ If a pathfinding request was successfully closed, the response follows the same If there was no outstanding pathfinding request, an error is returned instead. -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - If any fields are specified incorrectly, or any required fields are missing. * `noEvents` - If you tried to use this method on a protocol that does not support asynchronous callbacks, for example JSON-RPC. (See [ripple\_path\_find](#ripple-path-find) for a pathfinding method that _is_ compatible with JSON-RPC.) * `noPathRequest` - You tried to close a pathfinding request when there is not an open one. -### path_find status ### +### path_find status [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp#L57 "Source") The `status` subcommand of `path_find` requests an immediate update about the client's currently-open pathfinding request. -#### Request Format #### +#### Request Format An example of the request format: @@ -6240,7 +6240,7 @@ The request includes the following parameters: |:-------------|:-------|:---------------------------------------------| | `subcommand` | String | Use `"status"` to send the status subcommand | -#### Response Format #### +#### Response Format If a pathfinding request is open, the response follows the same format as the initial response to [`path_find create`](#path-find-create), plus the following field: @@ -6250,7 +6250,7 @@ If a pathfinding request is open, the response follows the same format as the in If there was no outstanding pathfinding request, an error is returned instead. -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. @@ -6258,7 +6258,7 @@ If there was no outstanding pathfinding request, an error is returned instead. * `noPathRequest` - You tried to check the status of a pathfinding request when there is not an open one. -## ripple_path_find ## +## ripple_path_find [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/RipplePathFind.cpp "Source") The `ripple_path_find` method is a simplified version of [`path_find`](#path-find) that provides a single response with a [payment path](concept-paths.html) you can use right away. It is available in both the WebSocket and JSON-RPC APIs. However, the results tend to become outdated as time passes. Instead of making multiple calls to stay updated, you should use [`path_find`](#path-find) instead where possible. @@ -6267,7 +6267,7 @@ Although the `rippled` server tries to find the cheapest path or combination of **Caution:** Be careful with the pathfinding results from untrusted servers. A server could be modified to return less-than-optimal paths to earn money for its operators. A server may also return poor results when under heavy load. If you do not have your own server that you can trust with pathfinding, you should compare the results of pathfinding from multiple servers run by different parties, to minimize the risk of a single server returning poor results. -#### Request Format #### +#### Request Format An example of the request format: @@ -6346,7 +6346,7 @@ The request includes the following parameters: | `ledger_hash` | String | _(Optional)_ A 20-byte hex string for the ledger version to use. (See [Specifying a Ledger](#specifying-ledgers)) | | `ledger_index` | String or Unsigned Integer | _(Optional)_ The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying a Ledger](#specifying-ledgers)) | -#### Response Format #### +#### Response Format An example of a successful response: @@ -6588,7 +6588,7 @@ Each element in the `alternatives` array is an object that represents a path fro The following fields are deprecated, and may be omitted: `paths_canonical`, and `paths_expanded`. If they appear, you should disregard them. -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `tooBusy` - The server is under too much load to calculate paths. Not returned if you are connected as an admin. @@ -6603,14 +6603,14 @@ The following fields are deprecated, and may be omitted: `paths_canonical`, and -## sign ## +## sign [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/SignHandler.cpp "Source") The `sign` method takes a [transaction in JSON format](reference-transaction-format.html) and a secret key, and returns a signed binary representation of the transaction. The result is always different, even when you provide the same transaction JSON and secret key. To contribute one signature to a multi-signed transaction, use the [`sign_for` command](#sign-for) instead. **Caution:** Unless you run the `rippled` server yourself, you should do [local signing with RippleAPI](reference-rippleapi.html#sign) instead of using this command. An untrustworthy server could change the transaction before signing it, or use your secret key to sign additional arbitrary transactions as if they came from you. -#### Request Format #### +#### Request Format An example of the request format: @@ -6693,7 +6693,7 @@ The request includes the following parameters: | `fee_mult_max` | Integer | (Optional, defaults to 10; recommended value 1000) Limits how high the [automatically-provided `Fee` field](reference-transaction-format.html#auto-fillable-fields) can be. Signing fails with the error `rpcHIGH_FEE` if the current [load multiplier on the transaction cost](concept-transaction-cost.html#local-load-cost) is greater than (`fee_mult_max` ÷ `fee_div_max`). Ignored if you specify the `Fee` field of the transaction ([transaction cost](concept-transaction-cost.html)). | | `fee_div_max` | Integer | (Optional, defaults to 1) Signing fails with the error `rpcHIGH_FEE` if the current [load multiplier on the transaction cost](concept-transaction-cost.html#local-load-cost) is greater than (`fee_mult_max` ÷ `fee_div_max`). Ignored if you specify the `Fee` field of the transaction ([transaction cost](concept-transaction-cost.html)). [New in: rippled 0.30.1][] | -### Auto-Fillable Fields ### +### Auto-Fillable Fields The server automatically tries to fill in certain fields in `tx_json` (the [Transaction object](reference-transaction-format.html)) automatically if you omit them. The server provides the following fields before signing, unless the request specified `offline` as `true`: @@ -6705,7 +6705,7 @@ The server automatically tries to fill in certain fields in `tx_json` (the [Tran * **Caution:** A malicious server can specify an excessively high transaction cost, ignoring the values of `fee_mult_max` and `fee_div_max`. * `Paths` - For Payment-type transactions (excluding XRP-to-XRP transfers), the Paths field can be automatically filled, as if you did a [ripple_path_find](#ripple-path-find). Only filled if `build_path` is provided. -#### Response Format #### +#### Response Format An example of a successful response: @@ -6812,7 +6812,7 @@ The response follows the [standard format](#response-formatting), with a success * Do not paste this error to a public place for debugging. * Do not display the error message on a website, even by accident. -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. @@ -6821,14 +6821,14 @@ The response follows the [standard format](#response-formatting), with a success * `noPath` - The transaction did not include paths, and the server was unable to find a path by which this payment can occur. -## sign_for ## +## sign_for [[Source]
](https://github.com/ripple/rippled/blob/release/src/ripple/rpc/handlers/SignFor.cpp "Source") The `sign_for` command provides one signature for a [multi-signed transaction](reference-transaction-format.html#multi-signing). This command requires the [MultiSign amendment](concept-amendments.html#multisign) to be enabled. [New in: rippled 0.31.0][] -#### Request Format #### +#### Request Format An example of the request format: @@ -6920,7 +6920,7 @@ The request includes the following parameters: You must provide exactly 1 field with the secret key. You can use any of the following fields: `secret`, `passphrase`, `seed`, or `seed_hex`. -#### Response Format #### +#### Response Format An example of a successful response: @@ -7042,7 +7042,7 @@ The response follows the [standard format](#response-formatting), with a success | `tx_blob` | String | Hexadecimal representation of the signed transaction, including the newly-added signature. If it has enough signatures, you can [submit this string using the `submit` command](#submit-only-mode). | | `tx_json` | Object | The [transaction specification](reference-transaction-format.html) in JSON format, with the newly-added signature in the `Signers` array. If it has enough signatures, you can submit this object using the [`submit_multisigned` command](#submit-multisigned). | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. @@ -7053,7 +7053,7 @@ The response follows the [standard format](#response-formatting), with a success -## submit ## +## submit [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/Submit.cpp "Source") The `submit` method applies a [transaction](reference-transaction-format.html) and sends it to the network to be confirmed and included in future ledgers. @@ -7065,7 +7065,7 @@ This command has two modes: To send a transaction as robustly as possible, you should construct and [`sign`](#sign) it in advance, persist it somewhere that you can access even after a power outage, then `submit` it as a `tx_blob`. After submission, monitor the network with the [`tx`](#tx) command to see if the transaction was successfully applied; if a restart or other problem occurs, you can safely re-submit the `tx_blob` transaction: it won't be applied twice since it has the same sequence number as the old transaction. -### Submit-Only Mode ### +### Submit-Only Mode A submit-only request includes the following parameters: @@ -7074,7 +7074,7 @@ A submit-only request includes the following parameters: | `tx_blob` | String | Hex representation of the signed transaction to submit. This can be a [multi-signed transaction](reference-transaction-format.html#multi-signing). | | `fail_hard` | Boolean | (Optional, defaults to false) If true, and the transaction fails locally, do not retry or relay the transaction to other servers | -#### Request Format #### +#### Request Format @@ -7113,7 +7113,7 @@ submit 1200002280000000240000000361D4838D7EA4C6800000000000000000000000000055534 [Try it! >](ripple-api-tool.html#submit) -### Sign-and-Submit Mode ### +### Sign-and-Submit Mode This mode signs a transaction and immediately submits it. This mode is intended to be used for testing. You cannot use this mode for [multi-signed transactions](reference-transaction-format.html#multi-signing). @@ -7140,7 +7140,7 @@ The request includes the following parameters: See the [sign command](#sign) for detailed information on how the server automatically fills in certain fields. -#### Request Format #### +#### Request Format An example of the request format: @@ -7203,7 +7203,7 @@ rippled submit s█████████████████████ [Try it! >](ripple-api-tool.html#submit) -#### Response Format #### +#### Response Format An example of a successful response: @@ -7324,7 +7324,7 @@ The response follows the [standard format](#response-formatting), with a success * Do not display an error message including your secret key on a website, even by accident. -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidTransaction` - The transaction is malformed or otherwise invalid. @@ -7337,14 +7337,14 @@ The response follows the [standard format](#response-formatting), with a success * `internalJson` - An internal error occurred when serializing the transaction to JSON. This could be caused by many aspects of the transaction, including a bad signature or some fields being malformed. -## submit_multisigned ## +## submit_multisigned [[Source]
](https://github.com/ripple/rippled/blob/release/src/ripple/rpc/handlers/SubmitMultiSigned.cpp "Source") The `submit_multisigned` command applies a [multi-signed](reference-transaction-format.html#multi-signing) transaction and sends it to the network to be included in future ledgers. (You can also submit multi-signed transactions in binary form using the [`submit` command in submit-only mode](#submit-only-mode).) This command requires the [MultiSign amendment](concept-amendments.html#multisign) to be enabled. [New in: rippled 0.31.0][] -#### Request Format #### +#### Request Format An example of the request format: @@ -7472,7 +7472,7 @@ The request includes the following parameters: | `tx_json` | Object | [Transaction in JSON format](reference-transaction-format.html) with an array of `Signers`. To be successful, the weights of the signatures must be equal or higher than the quorum of the [SignerList](reference-ledger-format.html#signerlist). | | `fail_hard` | Boolean | (Optional, defaults to false) If true, and the transaction fails locally, do not retry or relay the transaction to other servers. | -#### Response Format #### +#### Response Format An example of a successful response: @@ -7581,7 +7581,7 @@ The response follows the [standard format](#response-formatting), with a success | `tx_blob` | String | The complete [transaction](reference-transaction-format.html) in hex string format | | `tx_json` | Object | The complete [transaction](reference-transaction-format.html) in JSON format | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. @@ -7590,12 +7590,12 @@ The response follows the [standard format](#response-formatting), with a success -## book_offers ## +## book_offers [[Source]
](https://github.com/ripple/rippled/blob/develop/src/ripple/rpc/handlers/BookOffers.cpp "Source") The `book_offers` method retrieves a list of offers, also known as the [order book](http://www.investopedia.com/terms/o/order-book.asp), between two currencies. If the results are very large, a partial result is returned with a marker so that later requests can resume from where the previous one left off. -#### Request Format #### +#### Request Format An example of the request format: @@ -7661,7 +7661,7 @@ The request includes the following parameters: | `taker_gets` | Object | Specification of which currency the account taking the offer would receive, as an object with `currency` and `issuer` fields (omit issuer for XRP), like [currency amounts](#specifying-currency-amounts). | | `taker_pays` | Object | Specification of which currency the account taking the offer would pay, as an object with `currency` and `issuer` fields (omit issuer for XRP), like [currency amounts](#specifying-currency-amounts). | -#### Response Format #### +#### Response Format An example of a successful response: @@ -7762,7 +7762,7 @@ In addition to the standard Offer fields, the following fields may be included i | `taker_pays_funded` | String (XRP) or Object (non-XRP) | (Only included in partially-funded offers) The maximum amount of currency that the taker would pay, given the funding status of the offer. | | `quality` | Number | The exchange rate, as the ratio `taker_pays` divided by `taker_gets`. For fairness, offers that have the same quality are automatically taken first-in, first-out. (In other words, if multiple people offer to exchange currency at the same rate, the oldest offer is taken first.) | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. @@ -7900,7 +7900,7 @@ _(Requires the [PayChan amendment](concept-amendments.html#paychan) to be enable The `channel_verify` method checks the validity of a signature that can be used to redeem a specific amount of XRP from a payment channel. -#### Request Format #### +#### Request Format An example of the request format: @@ -7953,7 +7953,7 @@ The request includes the following parameters: | `public_key` | String | The public key of the channel and the key pair that was used to create the signature, in base58 format. (One way to get the public key in base58 format is to use the [`wallet_propose` command](#wallet-propose).) | | `signature` | String | The signature to verify, in hexadecimal. | -#### Response Format #### +#### Response Format An example of a successful response: @@ -8006,7 +8006,7 @@ The response follows the [standard format](#response-formatting), with a success **Caution:** This does not indicate check that the channel has enough XRP allocated to it. Before considering a claim valid, you should look up the channel in the latest validated ledger and confirm that the channel is open and its `amount` value is equal or greater than the `amount` of the claim. To do so, use the [`account_channels` method](#account-channels). -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. @@ -8017,18 +8017,18 @@ The response follows the [standard format](#response-formatting), with a success -# Subscriptions # +# Subscriptions Using subscriptions, you can have the server push updates to your client when various events happen, so that you can know and react right away. Subscriptions are only supported in the WebSocket API, where you can receive additional responses in the same channel. JSON-RPC support for subscription callbacks is deprecated and may not work as expected. -## subscribe ## +## subscribe [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/Subscribe.cpp "Source") The `subscribe` method requests periodic notifications from the server when certain events happen. -#### Request Format #### +#### Request Format An example of the request format: @@ -8112,7 +8112,7 @@ Each member of the `books` array, if provided, is an object with the following f | `snapshot` | Boolean | (Optional, defaults to false) If true, return the current state of the order book once when you subscribe before sending updates | | `both` | Boolean | (Optional, defaults to false) If true, return both sides of the order book. | -#### Response Format #### +#### Response Format An example of a successful response: @@ -8139,7 +8139,7 @@ The response follows the [standard format](#response-formatting). The fields con * *Stream: ledger* - Information about the ledgers on hand and current fee schedule, such as `fee_base` (current base fee for transactions in XRP), `fee_ref` (current base fee for transactions in fee units), `ledger_hash` (hash of the latest validated ledger), `reserve_base` (minimum reserve for accounts), and more. * `books` - No fields returned by default. If `"snapshot": true` is set in the request, returns `offers` (an array of offer definition objects defining the order book) -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. @@ -8155,7 +8155,7 @@ The response follows the [standard format](#response-formatting). The fields con When you subscribe to a particular stream, you receive periodic responses on that stream until you unsubscribe or close the WebSocket connection. The content of those responses depends on what you subscribed to. Here are some examples: -### Ledger Stream ### +### Ledger Stream The `ledger` stream only sends `ledgerClosed` messages when [the consensus process](https://ripple.com/build/ripple-ledger-consensus-process/) declares a new validated ledger. The message identifies the ledger and provides some information about its contents. @@ -8190,7 +8190,7 @@ The fields from a ledger stream message are as follows: | `validated_ledgers` | String | (May be omitted) Range of ledgers that the server has available. This may be discontiguous. This field is not returned if the server is not connected to the network, or if it is connected but has not yet obtained a ledger from the network. | -### Validations Stream ### +### Validations Stream [New in: rippled 0.29.0][] @@ -8240,7 +8240,7 @@ The fields from a validations stream message are as follows: -### Transaction Streams ### +### Transaction Streams Many subscriptions result in messages about transactions, including the following: @@ -8378,7 +8378,7 @@ Transaction stream messages have the following fields: | `validated` | Boolean | If true, this transaction is included in a validated ledger. Responses from the `transaction` stream should always be validated. | -### Peer Status Stream ### +### Peer Status Stream The admin-only `peer_status` stream reports a large amount of information on the activities of other `rippled` servers to which this server is connected, in particular their status in the consensus process. @@ -8408,7 +8408,7 @@ Peer Status stream messages represent some event where the status of the peer `r | `ledger_index_max` | Number | (May be omitted) The largest [Ledger Index][] the peer has currently available. | | `ledger_index_min` | Number | (May be omitted) The smallest [Ledger Index][] the peer has currently available. | -#### Peer Status Events #### +#### Peer Status Events The `action` field of a Peer Status stream message can have the following values: @@ -8420,7 +8420,7 @@ The `action` field of a Peer Status stream message can have the following values | `LOST_SYNC` | The peer fell behind the rest of the network in tracking which ledger versions are validated and which are undergoing consensus. | -### Order Book Streams ### +### Order Book Streams When you subscribe to one or more order books with the `books` field, you get back any transactions that affect those order books. @@ -8558,12 +8558,12 @@ The format of an order book stream message is the same as that of [transaction s | `transaction.owner_funds` | String | Numeric amount of the `TakerGets` currency that the `Account` sending this OfferCreate transaction has after executing this transaction. This does not check whether the currency amount is [frozen](concept-freeze.html). | -## unsubscribe ## +## unsubscribe [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/Unsubscribe.cpp "Source") The `unsubscribe` command tells the server to stop sending messages for a particular subscription or set of subscriptions. -#### Request Format #### +#### Request Format An example of the request format: @@ -8615,7 +8615,7 @@ The objects in the `books` array are defined almost like the ones from subscribe | `taker_pays` | Object | Specification of which currency the account taking the offer would pay, as an object with `currency` and `issuer` fields (omit issuer for XRP), like [currency amounts](#specifying-currency-amounts). | | `both` | Boolean | (Optional, defaults to false) If true, remove a subscription for both sides of the order book. | -#### Response Format #### +#### Response Format An example of a successful response: @@ -8636,7 +8636,7 @@ An example of a successful response: The response follows the [standard format](#response-formatting), with a successful result containing no fields. -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. @@ -8654,16 +8654,16 @@ The response follows the [standard format](#response-formatting), with a success -# Server Information # +# Server Information There are also commands that retrieve information about the current state of the server. These may be useful for monitoring the health of the server, or in preparing for making other API methods. For example, you may query for the current fee schedule before sending a transaction, or you may check which ledger versions are available before digging into the ledger history for a specific record. -## server_info ## +## server_info [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/ServerInfo.cpp "Source") The `server_info` command asks the server for a human-readable version of various information about the `rippled` server being queried. -#### Request Format #### +#### Request Format An example of the request format: @@ -8701,7 +8701,7 @@ rippled server_info The request does not takes any parameters. -#### Response Format #### +#### Response Format An example of a successful response: @@ -8978,18 +8978,18 @@ The `info` object may have some arrangement of the following fields: [transaction cost]: concept-transaction-cost.html -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). -## server_state ## +## server_state [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/ServerState.cpp "Source") The `server_state` command asks the server for various machine-readable information about the `rippled` server's current state. The results are almost the same as [`server_info`](#server-info), but using units that are easier to process instead of easier to read. (For example, XRP values are given in integer drops instead of scientific notation or decimal values, and time is given in milliseconds instead of seconds.) -#### Request Format #### +#### Request Format An example of the request format: @@ -9027,7 +9027,7 @@ rippled server_state The request does not takes any parameters. -#### Response Format #### +#### Response Format An example of a successful response: @@ -9269,19 +9269,19 @@ The `state` object may have some arrangement of the following fields: [fee levels]: concept-transaction-cost.html#fee-levels -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). -## can_delete ## +## can_delete [[Source]
](https://github.com/ripple/rippled/blob/develop/src/ripple/rpc/handlers/CanDelete.cpp "Source") With `online_delete` and `advisory_delete` configuration options enabled, the `can_delete` method informs the rippled server of the latest ledger which may be deleted. _The `can_delete` method is an [admin command](#connecting-to-rippled) that cannot be run by unprivileged users._ -#### Request Format #### +#### Request Format An example of the request format: @@ -9336,7 +9336,7 @@ a successful result containing the following fields: Use this command with no parameter to query the existing `can_delete` setting. -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `notEnabled` - Not enabled in configuration. @@ -9345,14 +9345,14 @@ Use this command with no parameter to query the existing `can_delete` setting. * `invalidParams` - Invalid parameters. -## consensus_info ## +## consensus_info [[Source]
](https://github.com/ripple/rippled/blob/a61ffab3f9010d8accfaa98aa3cacc7d38e74121/src/ripple/rpc/handlers/ConsensusInfo.cpp "Source") The `consensus_info` command provides information about the consensus process for debugging purposes. _The `consensus_info` method is an [admin command](#connecting-to-rippled) that cannot be run by unprivileged users._ -#### Request Format #### +#### Request Format An example of the request format: @@ -9388,7 +9388,7 @@ rippled consensus_info The request has no parameters. -#### Response Format #### +#### Response Format An example of a successful response: @@ -9570,19 +9570,19 @@ It is also normal to get a minimal result where the only field in `info` is `"co The results of the `consensus_info` command can vary dramatically if you run it several times, even in short succession. -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). -## fetch_info ## +## fetch_info [[Source]
](https://github.com/ripple/rippled/blob/315a8b6b602798a4cff4d8e1911936011e12abdb/src/ripple/rpc/handlers/FetchInfo.cpp "Source") The `fetch_info` command returns information about objects that this server is currently fetching from the network, and how many peers have that information. It can also be used to reset current fetches. _The `fetch_info` method is an [admin command](#connecting-to-rippled) that cannot be run by unprivileged users._ -#### Request Format #### +#### Request Format An example of the request format: @@ -9625,7 +9625,7 @@ The request includes the following parameters: |:--------|:--------|:---------------------------------------------------------| | `clear` | Boolean | If `true`, reset current fetches. Otherwise, only get status of fetches in progress. | -#### Response Format #### +#### Response Format An example of a successful response: @@ -9728,12 +9728,12 @@ The fields describing a fetch in progress are subject to change without notice. | `peers` | Number | The number of peers who have this item available. | | `timeouts` | Number | The number of times that fetching this item has resulted in a timeout (2.5 seconds). | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). -## feature ## +## feature [[Source]
](https://github.com/ripple/rippled/blob/develop/src/ripple/rpc/handlers/Feature1.cpp "Source") The `feature` command returns information about [amendments](concept-amendments.html) this server knows about, including whether they are enabled and whether the server is voting in favor of those amendments in the [amendment process](concept-amendments.html#amendment-process). [New in: rippled 0.31.0][] @@ -9742,7 +9742,7 @@ You can use the `feature` command to temporarily configure the server to vote ag _The `feature` method is an [admin command](#connecting-to-rippled) that cannot be run by unprivileged users._ -#### Request Format #### +#### Request Format An example of the request format: @@ -9799,7 +9799,7 @@ The request includes the following parameters: **Note:** You can configure your server to vote in favor of a new amendment, even if the server does not currently know how to apply that amendment, by specifying the amendment ID in the `feature` field. For example, you might want to do this if you plan to upgrade soon to a new `rippled` version that _does_ support the amendment. -#### Response Format #### +#### Response Format An example of a successful response: @@ -9917,21 +9917,21 @@ The response follows the [standard format](#response-formatting), with a success **Caution:** The `name` for an amendment does not strictly indicate what that amendment does. The name is not guaranteed to be unique or consistent across servers. -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `badFeature` - The `feature` specified was invalidly formatted, or the server does not know an amendment with that name. -## fee ## +## fee [[Source]
](https://github.com/ripple/rippled/blob/release/src/ripple/rpc/handlers/Fee1.cpp "Source") The `fee` command reports the current state of the open-ledger requirements for the [transaction cost](concept-transaction-cost.html). This requires the [FeeEscalation amendment](concept-amendments.html#feeescalation) to be enabled. [New in: rippled 0.31.0][] This is a public command available to unprivileged users. [Updated in: rippled 0.32.0][New in: rippled 0.32.0] -#### Request Format #### +#### Request Format An example of the request format: @@ -9965,7 +9965,7 @@ rippled fee The request does not include any parameters. -#### Response Format #### +#### Response Format An example of a successful response: @@ -10079,20 +10079,20 @@ The response follows the [standard format](#response-formatting), with a success | `levels.reference_level` | String (Integer) | The equivalent of the minimum transaction cost, represented in [fee levels][]. | | `max_queue_size` | String (Integer) | The maximum number of transactions that the [transaction queue](concept-transaction-cost.html#queued-transactions) can currently hold. | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). -## get_counts ## +## get_counts [[Source]
](https://github.com/ripple/rippled/blob/c7118a183a660648aa88a3546a6b2c5bce858440/src/ripple/rpc/handlers/GetCounts.cpp "Source") The `get_counts` command provides various stats about the health of the server, mostly the number of objects of different types that it currently holds in memory. _The `get_counts` method is an [admin command](#connecting-to-rippled) that cannot be run by unprivileged users._ -#### Request Format #### +#### Request Format An example of the request format: @@ -10135,7 +10135,7 @@ The request includes the following parameters: |:------------|:--------------------------|:-----------------------------------| | `min_count` | Number (Unsigned Integer) | Only return fields with a value at least this high. | -#### Response Format #### +#### Response Format An example of a successful response: @@ -10229,20 +10229,20 @@ The response follows the [standard format](#response-formatting). The list of fi For most other entries, the value indicates the number of objects of that type currently in memory. -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. -## ledger_cleaner ## +## ledger_cleaner [[Source]
](https://github.com/ripple/rippled/blob/df54b47cd0957a31837493cd69e4d9aade0b5055/src/ripple/rpc/handlers/LedgerCleaner.cpp "Source") The `ledger_cleaner` command controls the [Ledger Cleaner](https://github.com/ripple/rippled/blob/f313caaa73b0ac89e793195dcc2a5001786f916f/src/ripple/app/ledger/README.md#the-ledger-cleaner), an asynchronous maintenance process that can find and repair corruption in `rippled`'s database of ledgers. _The `ledger_cleaner` method is an [admin command](#connecting-to-rippled) that cannot be run by unprivileged users._ -#### Request Format #### +#### Request Format An example of the request format: @@ -10272,7 +10272,7 @@ The request includes the following parameters: | `check_nodes` | Boolean | _(Optional)_ If true, correct ledger state objects in the specified ledger(s). Overrides `full` if provided. | | `stop` | Boolean | _(Optional)_ If true, disable the ledger cleaner. | -#### Response Format #### +#### Response Format An example of a successful response: @@ -10299,20 +10299,20 @@ The response follows the [standard format](#response-formatting), with a success |:----------|:-------|:---------------------------------| | `message` | String | `Cleaner configured` on success. | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `internal` if one the parameters is specified incorrectly. (This is a bug; the intended error code is `invalidParams`.) -## log_level ## +## log_level [[Source]
](https://github.com/ripple/rippled/blob/155fcdbcd0b4927152892c8c8be01d9cf62bed68/src/ripple/rpc/handlers/LogLevel.cpp "Source") The `log_level` command changes the `rippled` server's logging verbosity, or returns the current logging level for each category (called a _partition_) of log messages. _The `log_level` method is an [admin command](#connecting-to-rippled) that cannot be run by unprivileged users._ -#### Request Format #### +#### Request Format An example of the request format: @@ -10344,7 +10344,7 @@ The request includes the following parameters: | `severity` | String | _(Optional)_ What level of verbosity to set logging at. Valid values are, in order from least to most verbose: `fatal`, `error`, `warn`, `info`, `debug`, and `trace`. If omitted, return current log verbosity for all categories. | | `partition` | String | _(Optional)_ Ignored unless `severity` is provided. Which logging category to modify. If omitted, or if provided with the value `base`, set logging level for all categories. | -#### Response Format #### +#### Response Format Examples of successful responses: @@ -10436,20 +10436,20 @@ Otherwise, the request contains the following field: |:--------|:-------|:----------------------------------------------------------| | `level` | Object | The current log levels of each category. This list of categories is subject to change without notice in future releases. You can use the field names as values to `partition` in requests to this command. | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. -## logrotate ## +## logrotate [[Source]
](https://github.com/ripple/rippled/blob/743bd6c9175c472814448ea889413be79dfd1c07/src/ripple/rpc/handlers/LogRotate.cpp "Source") The `logrotate` command closes and reopens the log file. This is intended to help with log rotation on Linux file systems. _The `logrotate` method is an [admin command](#connecting-to-rippled) that cannot be run by unprivileged users._ -#### Request Format #### +#### Request Format An example of the request format: @@ -10473,7 +10473,7 @@ rippled logrotate The request includes no parameters. -#### Response Format #### +#### Response Format An example of a successful response: @@ -10514,19 +10514,19 @@ The response follows the [standard format](#response-formatting), with a success |:----------|:-------|:--------------------------------------------------------| | `message` | String | On success, contains the message `The log file was closed and reopened.` | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). -## validation_create ## +## validation_create [[Source]
](https://github.com/ripple/rippled/blob/315a8b6b602798a4cff4d8e1911936011e12abdb/src/ripple/rpc/handlers/ValidationCreate.cpp "Source") Use the `validation_create` command to generate the keys for a rippled [validator](tutorial-rippled-setup.html#validator-setup). Similar to the [wallet_propose](#wallet-propose) command, this command makes no real changes, but only generates a set of keys in the proper format. _The `validation_create` method is an [admin command](#connecting-to-rippled) that cannot be run by unprivileged users._ -#### Request Format #### +#### Request Format An example of the request format: @@ -10571,7 +10571,7 @@ The request includes the following parameters: **Note:** The security of your validator depends on the entropy of your seed. Do not use a secret value for real business purposes unless it is generated with a strong source of randomness. Ripple recommends omitting the `secret` when generating new credentials for the first time. -#### Response Format #### +#### Response Format An example of a successful response: @@ -10615,20 +10615,20 @@ The response follows the [standard format](#response-formatting), with a success | `validation_public_key` | String | The public key for these validation credentials, in Ripple's [base58][] encoded string format. | | `validation_seed` | String | The secret key for these validation credentials, in Ripple's [base58][] encoded string format. | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `badSeed` - The request provided an invalid seed value. This usually means that the seed value appears to be a valid string of a different format, such as an account address or validation public key. -## validation_seed ## +## validation_seed [[Source]
](https://github.com/ripple/rippled/blob/a61ffab3f9010d8accfaa98aa3cacc7d38e74121/src/ripple/rpc/handlers/ValidationSeed.cpp "Source") The `validation_seed` command temporarily sets the secret value that rippled uses to sign validations. This value resets based on the config file when you restart the server. *The `validation_seed` request is an [admin command](#connecting-to-rippled) that cannot be run by unprivileged users!* -#### Request Format #### +#### Request Format An example of the request format: @@ -10658,7 +10658,7 @@ The request includes the following parameters: |:---------|:-------|:---------------------------------------------------------| | `secret` | String | _(Optional)_ If present, use this value as the secret value for the validating key pair. Valid formats include [base58][], [RFC-1751](https://tools.ietf.org/html/rfc1751), or as a passphrase. If omitted, disables proposing validations to the network. | -#### Response Format #### +#### Response Format An example of a successful response: @@ -10703,19 +10703,19 @@ The response follows the [standard format](#response-formatting), with a success | `validation_public_key` | String | (Omitted if proposing disabled) The public key for these validation credentials, in Ripple's [base58][] encoded string format. | | `validation_seed` | String | (Omitted if proposing disabled) The secret key for these validation credentials, in Ripple's [base58][] encoded string format. | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `badSeed` - The request provided an invalid secret value. This usually means that the secret value appears to be a valid string of a different format, such as an account address or validation public key. -## validators ## +## validators [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/Validators.cpp "Source") The `validators` command returns human readable information about the current list of published and trusted validators used by the server. [New in: rippled 0.80.1][] *The `validators` request is an [admin command](#connecting-to-rippled) that cannot be run by unprivileged users!* -#### Request Format #### +#### Request Format An example of the request format: @@ -10751,7 +10751,7 @@ rippled validators The request includes no parameters. -#### Response Format #### +#### Response Format An example of a successful response: @@ -10882,19 +10882,19 @@ Each member of the `publisher_lists` array is an object with the following field | `seq` | Unsigned Integer | The sequence number of this published list. | | `version` | Unsigned Integer | The version of the list format. | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). -## validator_list_sites ## +## validator_list_sites [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/ValidatorListSites.cpp "Source") The `validator_list_sites` command returns status information of sites serving validator lists. [New in: rippled 0.80.1][] *The `validator_list_sites` request is an [admin command](#connecting-to-rippled) that cannot be run by unprivileged users!* -#### Request Format #### +#### Request Format An example of the request format: @@ -10930,7 +10930,7 @@ rippled validator_list_sites The request includes no parameters. -#### Response Format #### +#### Response Format An example of a successful response: @@ -11013,19 +11013,19 @@ Each member of the `validator_sites` field array is an object with the following | `refresh_interval_min` | Unsigned Integer | The number of minutes between refresh attempts. | | `uri` | String | The URI of the site. | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). -## peers ## +## peers [[Source]
](https://github.com/ripple/rippled/blob/52f298f150fc1530d201d3140c80d3eaf781cb5f/src/ripple/rpc/handlers/Peers.cpp "Source") The `peers` command returns a list of all other `rippled` servers currently connected to this one, including information on their connection and sync status. *The `peers` request is an [admin command](#connecting-to-rippled) that cannot be run by unprivileged users!* -#### Request Format #### +#### Request Format An example of the request format: @@ -11049,7 +11049,7 @@ rippled peers The request includes no additional parameters. -#### Response Format #### +#### Response Format An example of a successful response: @@ -11424,19 +11424,19 @@ Each member of the `peers` array is a peer object with the following fields: | `uptime` | Number | The number of seconds that your `rippled` server has been continuously connected to this peer. [New in: rippled 0.30.1][] | | `version` | string | (May be omitted) The `rippled` version number of the peer server | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). -## print ## +## print [[Source]
](https://github.com/ripple/rippled/blob/315a8b6b602798a4cff4d8e1911936011e12abdb/src/ripple/rpc/handlers/Print.cpp "Source") The `print` command returns the current status of various internal subsystems, including peers, the ledger cleaner, and the resource manager. *The `print` request is an [admin command](#connecting-to-rippled) that cannot be run by unprivileged users!* -#### Request Format #### +#### Request Format An example of the request format: @@ -11460,7 +11460,7 @@ rippled print The request includes no parameters. -#### Response Format #### +#### Response Format An example of a successful response: @@ -11657,22 +11657,22 @@ Connecting to 127.0.0.1:5005 The response follows the [standard format](#response-formatting). Additional fields in the result depend on the internal state of the `rippled` server. The results of this command are subject to change without notice. -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). -# Convenience Functions # +# Convenience Functions The rippled server also provides a few commands purely for convenience. -## ping ## +## ping [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/Ping.cpp "Source") The `ping` command returns an acknowledgement, so that clients can test the connection status and latency. -#### Request Format #### +#### Request Format An example of the request format: @@ -11710,7 +11710,7 @@ rippled ping The request includes no parameters. -#### Response Format #### +#### Response Format An example of a successful response: @@ -11742,17 +11742,17 @@ An example of a successful response: The response follows the [standard format](#response-formatting), with a successful result containing no fields. The client can measure the round-trip time from request to response as latency. -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). -## random ## +## random [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/Random.cpp "Source") The `random` command provides a random number to be used as a source of entropy for random number generation by clients. -#### Request Format #### +#### Request Format An example of the request format: @@ -11788,7 +11788,7 @@ rippled random The request includes no parameters. -#### Response Format #### +#### Response Format An example of a successful response: @@ -11827,17 +11827,17 @@ The response follows the [standard format](#response-formatting), with a success |:---------|:-------|:--------------------------| | `random` | String | Random 256-bit hex value. | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `internal` - Some internal error occurred, possibly relating to the random number generator. -## json ## +## json The `json` method is a proxy to running other commands, and accepts the parameters for the command as a JSON value. It is *exclusive to the Commandline client*, and intended for cases where the commandline syntax for specifying parameters is inadequate or undesirable. -#### Request Format #### +#### Request Format An example of the request format: @@ -11851,7 +11851,7 @@ rippled -q json ledger_closed '{}' -#### Response Format #### +#### Response Format An example of a successful response: @@ -11874,14 +11874,14 @@ An example of a successful response: The response follows the [standard format](#response-formatting), with whichever fields are appropriate to the type of command made. -## connect ## +## connect [[Source]
](https://github.com/ripple/rippled/blob/a61ffab3f9010d8accfaa98aa3cacc7d38e74121/src/ripple/rpc/handlers/Connect.cpp "Source") The `connect` command forces the rippled server to connect to a specific peer rippled server. *The `connect` request is an [admin command](#connecting-to-rippled) that cannot be run by unprivileged users!* -#### Request Format #### +#### Request Format An example of the request format: @@ -11927,7 +11927,7 @@ The request includes the following parameters: | `ip` | String | IP address of the server to connect to | | `port` | Number | _(Optional)_ Port number to use when connecting. Defaults to 6561. | -#### Response Format #### +#### Response Format An example of a successful response: @@ -11965,21 +11965,21 @@ The response follows the [standard format](#response-formatting), with a success |:----------|:-------|:-------------------------------------------------------| | `message` | String | The value `connecting`, if the command was successful. | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. * Cannot connect in standalone mode - Network-related commands are disabled in stand-alone mode. -## stop ## +## stop [[Source]
](https://github.com/ripple/rippled/blob/develop/src/ripple/rpc/handlers/Stop.cpp "Source") Gracefully shuts down the server. *The `stop` request is an [admin command](#connecting-to-rippled) that cannot be run by unprivileged users!* -#### Request Format #### +#### Request Format An example of the request format: @@ -12014,7 +12014,7 @@ rippled stop The request includes no parameters. -#### Response Format #### +#### Response Format An example of a successful response: @@ -12052,18 +12052,18 @@ The response follows the [standard format](#response-formatting), with a success |:----------|:-------|:-------------------------------------| | `message` | String | `ripple server stopping` on success. | -#### Possible Errors #### +#### Possible Errors * Any of the [universal error types](#universal-errors). -# Peer Protocol # +# Peer Protocol Servers in the XRP Ledger communicate to each other using the XRP Ledger peer protocol, also known as RTXP. Peer servers connect via HTTPS and then do an [HTTP upgrade](https://tools.ietf.org/html/rfc7230#section-6.7) to switch to RTXP. (For more information, see the [Overlay Network](https://github.com/ripple/rippled/blob/906ef761bab95f80b0a7e0cab3b4c594b226cf57/src/ripple/overlay/README.md#handshake) article in the [`rippled` repository](https://github.com/ripple/rippled).) -## Configuring the Peer Protocol ## +## Configuring the Peer Protocol To participate in the XRP Ledger, `rippled` servers connects to arbitrary peers using the peer protocol. (All such peers are treated as untrusted, unless they are [clustered](tutorial-rippled-setup.html#clustering) with the current server.) @@ -12078,11 +12078,11 @@ ip = 0.0.0.0 protocol = peer ``` -## Peer Crawler ## +## Peer Crawler The Peer Crawler asks a `rippled` server to report information about the other `rippled` servers it is connected to as peers. The [`peers` command](#peers) in the [WebSocket and JSON-RPC APIs](#websocket-and-json-rpc-apis) also returns a similar, more comprehensive set of information, but requires [administrative access](#connecting-to-rippled) to the server. The Peer Crawler response is available to other servers on a non-privileged basis through the Peer Protocol (RTXP) port. -#### Request Format #### +#### Request Format To request the Peer Crawler information, make the following HTTP request: @@ -12093,7 +12093,7 @@ To request the Peer Crawler information, make the following HTTP request: * **Path:** `/crawl` * **Notes:** Most `rippled` servers use a self-signed certificate to respond to the request. By default, most tools (including web browsers) flag or block such responses for being untrusted. You must ignore the certificate checking (for example, if using cURL, add the `--insecure` flag) to display a response from those servers. -#### Response Format #### +#### Response Format The response has the status code **200 OK** and a JSON object in the message body. @@ -12114,7 +12114,7 @@ Each member of the `active` array is a Peer Object with the following fields: | `uptime` | Number | The number of seconds the server has been has been connected to this peer. | | `version` | String | The `rippled` version number the peer reports to be using. | -#### Example #### +#### Example Request: @@ -12215,7 +12215,7 @@ Response: } ``` -### Concealing Peer Information ### +### Concealing Peer Information You can use the `[peer_private]` stanza of the `rippled` config file to request that peer servers do not report your IP address in the Peer Crawler response. You cannot force peers you do not control to follow this request, if they run custom software. However, you can use this to hide the IP addresses of `rippled` servers you control that _only_ connect to peers you control (using `[ips_fixed]` and a firewall). This can help to protect important [validating servers](tutorial-rippled-setup.html#types-of-rippled-servers). diff --git a/content/reference-transaction-format.md b/content/reference-transaction-format.md index 5986ada7f2..4bc0d99d3c 100644 --- a/content/reference-transaction-format.md +++ b/content/reference-transaction-format.md @@ -9,7 +9,7 @@ A _Transaction_ is the only way to modify the XRP Ledger. Transactions are only * [Transaction Results - How to find and interpret transaction results](#transaction-results) * [Full Transaction Response List - Complete table of all error codes](#full-transaction-response-list) -## Authorizing Transactions ## +## Authorizing Transactions In the decentralized XRP Ledger, a digital signature proves that a transaction is authorized to do a specific set of actions. Only signed transactions can be submitted to the network and included in a validated ledger. A signed transaction is immutable: its contents cannot change, and the signature is not valid for any other transaction. @@ -25,7 +25,7 @@ Any signature type can authorize any type of transaction, with the following exc * Only the master key can [permanently give up the ability to freeze](concept-freeze.html#no-freeze). * You can never remove the last method of signing transactions from an address. -## Signing and Submitting Transactions ## +## Signing and Submitting Transactions Sending a transaction to the XRP Ledger involves several steps: @@ -36,7 +36,7 @@ Sending a transaction to the XRP Ledger involves several steps: 5. The `rippled` servers apply those transactions to the previous ledger in a canonical order and share their results. 6. If enough [trusted validators](tutorial-rippled-setup.html#reasons-to-run-a-validator) created the exact same ledger, that ledger is declared _validated_ and the [results of the transactions](#transaction-results) in that ledger are immutable. -### Unsigned Transaction Format ### +### Unsigned Transaction Format Here is an example of an unsigned [Payment transaction][] in JSON: @@ -168,7 +168,7 @@ Example response from the `tx` command: ``` -### Multi-Signing ### +### Multi-Signing Multi-signing in the XRP Ledger is the act of [authorizing transactions](#authorizing-transactions) for the XRP Ledger by using a combination of multiple secret keys. You can have any combination of authorization methods enabled for your address, including multi-signing, a master key, and a [regular key](#setregularkey). (The only requirement is that _at least one_ method must be enabled.) @@ -188,7 +188,7 @@ To successfully submit a multi-signed transaction, you must do all of the follow For more information, see [How to Multi-Sign](tutorial-multisign.html). -### Reliable Transaction Submission ### +### Reliable Transaction Submission Reliably submitting transactions is the process of achieving both of the following: @@ -205,13 +205,13 @@ To have both qualities when submitting a transaction, an application should: Main article: [Reliable Transaction Submission](tutorial-reliable-transaction-submission.html) -### Identifying Transactions ### +### Identifying Transactions The `"hash"` is the unique value that identifies a particular transaction. The server provides the hash in the response when you submit the transaction; you can also look up a transaction in an account's transaction history with the [account_tx command](reference-rippled.html#account-tx). The transaction hash can be used as a "proof of payment" since anyone can [look up the transaction by its hash](#looking-up-transaction-results) to verify its final status. -## Common Fields ## +## Common Fields [Internal Type]: https://github.com/ripple/rippled/blob/master/src/ripple/protocol/impl/SField.cpp @@ -241,7 +241,7 @@ Every transaction type has the same set of fundamental fields. Field names are c [Sequence]: #canceling-or-skipping-a-transaction [Signers]: #signers-field -### Auto-fillable Fields ### +### Auto-fillable Fields Some fields can be automatically filled in before the transaction is signed, either by a `rippled` server or by the library used for offline signing. Both [ripple-lib](https://github.com/ripple/ripple-lib) and `rippled` can automatically provide the following values: @@ -253,7 +253,7 @@ For a production system, we recommend *not* leaving these fields to be filled by The [`Paths` field](#paths) of the [Payment](#payment) transaction type can also be automatically filled in. -### Transaction Cost ### +### Transaction Cost To protect the XRP Ledger from being disrupted by spam and denial-of-service attacks, each transaction must destroy a small amount of XRP. This _[transaction cost](concept-transaction-cost.html)_ is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network. @@ -262,7 +262,7 @@ The `Fee` field specifies an amount, in [drops of XRP][Currency Amount], to dest **Note:** [Multi-signed transactions](#multi-signing) require additional fees to relay to the network. -### Canceling or Skipping a Transaction ### +### Canceling or Skipping a Transaction 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. @@ -274,13 +274,13 @@ This approach is preferable to renumbering and resubmitting transactions 12 and In this way, an AccountSet transaction with no options is the canonical "[no-op](http://en.wikipedia.org/wiki/NOP)" transaction. -### LastLedgerSequence ### +### LastLedgerSequence We strongly recommend that you specify the `LastLedgerSequence` parameter on every transaction. Provide a value of about 3 higher than [the most recent ledger index](reference-rippled.html#ledger) to ensure that your transaction is either validated or rejected within a matter of seconds. Without the `LastLedgerSequence` parameter, a transaction can become stuck in an undesirable state where it is neither validated nor rejected for a long time. Specifically, if the load-based [transaction cost](#transaction-cost) of the network increases after you send a transaction, your transaction may not get propagated enough to be included in a validated ledger, but you would have to pay the (increased) transaction cost to [send another transaction canceling it](#canceling-or-skipping-a-transaction). Later, if the transaction cost decreases again, the transaction can become included in a future ledger. The `LastLedgerSequence` places a hard upper limit on how long the transaction can wait to be validated or rejected. -### AccountTxnID ### +### AccountTxnID The `AccountTxnID` field lets you chain your transactions together, so that a current transaction is not valid unless the previous one (by Sequence Number) is also valid and matches the transaction you expected. @@ -288,7 +288,7 @@ One situation in which this is useful is if you have a primary system for submit To use AccountTxnID, you must first set the [asfAccountTxnID](#accountset-flags) flag, so that the ledger keeps track of the ID for the account's previous transaction. -### Memos ### +### Memos The `Memos` field includes arbitrary messaging data with the transaction. It is presented as an array of objects. Each object has only one field, `Memo`, which in turn contains another object with *one or more* of the following fields: @@ -321,7 +321,7 @@ Example of a transaction with a Memos field: } ``` -### Signers Field ### +### Signers Field The `Signers` field contains a [multi-signature](#multi-signing), which has signatures from up to 8 key pairs, that together should authorize the transaction. The `Signers` list is an array of objects, each with one field, `Signer`. The `Signer` field has the following nested fields: @@ -337,7 +337,7 @@ Because signature verification is a compute-intensive task, multi-signed transac -### Flags ### +### Flags The `Flags` field can contain various options that affect how a transaction should behave. The options are represented as binary values that can be combined with bitwise-or operations to set multiple flags at once. @@ -381,7 +381,7 @@ _Pseudo-Transactions_ that are not created and submitted in the usual way, but m * [EnableAmendment - Apply a change to transaction processing](#enableamendment) -## AccountSet ## +## AccountSet [[Source]
](https://github.com/ripple/rippled/blob/f65cea66ef99b1de149c02c15f06de6c61abf360/src/ripple/app/transactors/SetAccount.cpp "Source") @@ -415,7 +415,7 @@ Example AccountSet: If none of these options are provided, then the AccountSet transaction has no effect (beyond destroying the transaction cost). See [Canceling or Skipping a Transaction](#canceling-or-skipping-a-transaction) for more details. -### Domain ### +### Domain The `Domain` field is represented as the hex string of the lowercase ASCII of the domain. For example, the domain *example.com* would be represented as `"6578616d706c652e636f6d"`. @@ -423,7 +423,7 @@ To remove the `Domain` field from an account, send an AccountSet with the Domain Client applications can use the [ripple.txt](https://wiki.ripple.com/Ripple.txt) file hosted by the domain to confirm that the account is actually operated by that domain. -### AccountSet Flags ### +### AccountSet Flags There are several options which can be either enabled or disabled for an account. Account options are represented by different types of flags depending on the situation: @@ -463,7 +463,7 @@ The following [Transaction flags](#flags), specific to the AccountSet transactio -#### Blocking Incoming Transactions #### +#### Blocking Incoming Transactions Incoming transactions with unclear purposes may be an inconvenience for financial institutions, who would have to recognize when a customer made a mistake, and then potentially refund accounts or adjust balances depending on the mistake. The `asfRequireDest` and `asfDisallowXRP` flags are intended to protect users from accidentally sending funds in a way that is unclear about the reason the funds were sent. @@ -471,7 +471,7 @@ For example, a destination tag is typically used to identify which hosted balanc You can protect against unwanted incoming payments for non-XRP currencies by not creating trust lines in those currencies. Since XRP does not require trust, the `asfDisallowXRP` flag is used to discourage users from sending XRP to an account. However, this flag is not enforced in `rippled` because it could potentially cause accounts to become unusable. (If an account did not have enough XRP to send a transaction that disabled the flag, the account would be completely unusable.) Instead, client applications should disallow or discourage XRP payments to accounts with the `asfDisallowXRP` flag enabled. -### TransferRate ### +### TransferRate The TransferRate field specifies a fee to charge whenever counterparties transfer the currency you issue. See [Transfer Fees](concept-transfer-fees.html) for more information. @@ -479,7 +479,7 @@ In `rippled`'s WebSocket and JSON-RPC APIs, the TransferRate is represented as a -## EscrowCancel ## +## EscrowCancel [[Source]
](https://github.com/ripple/rippled/blob/develop/src/ripple/app/tx/impl/Escrow.cpp "Source") @@ -510,7 +510,7 @@ Any account may submit an EscrowCancel transaction. -## EscrowCreate ## +## EscrowCreate [[Source]
](https://github.com/ripple/rippled/blob/develop/src/ripple/app/tx/impl/Escrow.cpp "Source") @@ -548,7 +548,7 @@ Either `CancelAfter` or `FinishAfter` must be specified. If both are included, t -## EscrowFinish ## +## EscrowFinish [[Source]
](https://github.com/ripple/rippled/blob/develop/src/ripple/app/tx/impl/Escrow.cpp "Source") @@ -586,7 +586,7 @@ Any account may submit an EscrowFinish transaction. -## OfferCancel ## +## OfferCancel [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/CancelOffer.cpp "Source") @@ -614,7 +614,7 @@ The OfferCancel method returns [tesSUCCESS](#transaction-results) even if it did -## OfferCreate ## +## OfferCreate [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/CreateOffer.cpp "Source") @@ -644,7 +644,7 @@ An OfferCreate transaction is effectively a [limit order](http://en.wikipedia.or | TakerGets | [Currency Amount][] | Amount | The amount and type of currency being provided by the offer creator. | | TakerPays | [Currency Amount][] | Amount | The amount and type of currency being requested by the offer creator. | -### Lifecycle of an Offer ### +### Lifecycle of an Offer When an OfferCreate transaction is processed, it automatically consumes matching or crossing offers to the extent possible. (If existing offers provide a better rate than requested, the offer creator could pay less than the full `TakerGets` amount to receive the entire `TakerPays` amount.) If that does not completely fulfill the `TakerPays` amount, then the offer becomes an Offer object in the ledger. (You can use [OfferCreate Flags](#offercreate-flags) to modify this behavior.) @@ -670,14 +670,14 @@ An unfunded offer can stay on the ledger indefinitely, but it does not have any * An offer is found to be unfunded during transaction processing, typically because it was at the tip of the orderbook. * This includes cases where one side or the other of an offer is found to be closer to 0 than `rippled`'s precision supports. -#### Tracking Unfunded Offers #### +#### Tracking Unfunded Offers Tracking the funding status of all offers can be computationally taxing. In particular, addresses that are actively trading may have a large number of offers open. A single balance can affect the funding status of many offers to buy different currencies. Because of this, `rippled` does not proactively find and remove offers. A client application can locally track the funding status of offers. To do this, first retreive an order book using the [`book_offers` command](reference-rippled.html#book-offers) and check the `taker_gets_funded` field of offers. Then, [subscribe](reference-rippled.html#subscribe) to the `transactions` stream and watch the transaction metadata to see which offers are modified. -### Offers and Trust ### +### Offers and Trust The limit values of trust lines (See [TrustSet](#trustset)) do not affect offers. In other words, you can use an offer to acquire more than the maximum amount you trust an issuer to redeem. @@ -685,7 +685,7 @@ However, holding non-XRP balances still requires a trust line to the address iss A trust line indicates an issuer you trust enough to accept their issuances as payment, within limits. Offers are explicit instructions to acquire certain issuances, so they are allowed to go beyond those limits. -### Offer Preference ### +### Offer Preference Existing offers are grouped by exchange rate (sometimes called "offer quality"), which is measured as the ratio between `TakerGets` and `TakerPays`. Offers with a higher exchange rate are taken preferentially. (That is, the person accepting the offer receives as much as possible for the amount of currency they pay out.) Offers with the same exchange rate are taken on the basis of which offer was placed in the earliest ledger version. @@ -704,7 +704,7 @@ The `TickSize` does not affect the part of an Offer that can be executed immedia When an issuer enables, disables, or changes the `TickSize`, Offers that were placed under the previous setting are unaffected. -### Expiration ### +### Expiration Since transactions can take time to propagate and confirm, the timestamp of a ledger is used to determine offer validity. An offer only expires when its Expiration time is before the most-recently validated ledger. In other words, an offer with an `Expiration` field is still considered "active" if its expiration time is later than the timestamp of the most-recently validated ledger, regardless of what your local clock says. @@ -714,7 +714,7 @@ You can determine the final disposition of an offer with an `Expiration` as soon If an OfferCreate transaction has an `Expiration` time that has already passed when the transaction first gets included in a ledger, the transaction does not execute the offer but still results in a `tesSUCCESS` transaction code. (This is because such a transaction could still successfully cancel another offer.) -### Auto-Bridging ### +### Auto-Bridging Any OfferCreate that would exchange two non-XRP currencies could potentially use XRP as an intermediary currency in a synthetic order book. This is because of auto-bridging, which serves to improve liquidity across all currency pairs by using XRP as a vehicle currency. This works because of XRP's nature as a native cryptocurrency to the XRP Ledger. Offer execution can use a combination of direct and auto-bridged offers to achieve the best total exchange rate. @@ -723,7 +723,7 @@ Example: _Anita places an offer to sell GBP and buy BRL. She might find that thi Auto-bridging happens automatically on any OfferCreate transaction. [Payment transactions](#payment) _do not_ autobridge by default, but path-finding can find paths that have the same effect. -### OfferCreate Flags ### +### OfferCreate Flags Transactions of the OfferCreate type support additional values in the [`Flags` field](#flags), as follows: @@ -742,7 +742,7 @@ The following invalid flag combination prompts a `temINVALID_FLAG` error: -## Payment ## +## Payment [[Source]
](https://github.com/ripple/rippled/blob/5425a90f160711e46b2c1f1c93d68e5941e4bfb6/src/ripple/app/transactors/Payment.cpp "Source") A Payment transaction represents a transfer of value from one account to another. (Depending on the path taken, this can involve additional exchanges of value, which occur atomically.) @@ -777,7 +777,7 @@ Example payment: | SendMax | [Currency Amount][] | Amount | _(Optional)_ Highest amount of source currency this transaction is allowed to cost, including [transfer fees](concept-transfer-fees.html), exchange rates, and [slippage](http://en.wikipedia.org/wiki/Slippage_%28finance%29). Does not include the [XRP destroyed as a cost for submitting the transaction](#transaction-cost). For non-XRP amounts, the nested field names MUST be lower-case. Must be supplied for cross-currency/cross-issue payments. Must be omitted for XRP-to-XRP payments. | | DeliverMin | [Currency Amount][] | Amount | _(Optional)_ Minimum amount of destination currency this transaction should deliver. Only valid if this is a [partial payment](#partial-payments). For non-XRP amounts, the nested field names are lower-case. | -### Special issuer Values for SendMax and Amount ### +### Special issuer Values for SendMax and Amount Most of the time, the `issuer` field of a non-XRP [Currency Amount][] indicates a financial institution's [issuing address](concept-issuing-and-operational-addresses.html). However, when describing payments, there are special rules for the `issuer` field in the `Amount` and `SendMax` fields of a payment. @@ -785,13 +785,13 @@ Most of the time, the `issuer` field of a non-XRP [Currency Amount][] indicates * When the `issuer` field of the destination `Amount` field matches the `Destination` address, it is treated as a special case meaning "any issuer that the destination accepts." This includes all addresses to which the destination has extended trust lines, as well as issuances created by the destination which are held on other trust lines. * When the `issuer` field of the `SendMax` field matches the source account's address, it is treated as a special case meaning "any issuer that the source can use." This includes creating new issuances on trust lines that other accounts have extended to the source account, and sending issuances the source account holds from other issuers. -### Creating Accounts ### +### Creating Accounts The Payment transaction type is the only way to create new accounts in the XRP Ledger. To do so, send an amount of XRP that is equal or greater than the [account reserve](concept-reserves.html) to a mathematically-valid account address that does not exist yet. When the Payment is processed, a new [AccountRoot object](reference-ledger-format.html#accountroot) is added to the ledger. If you send an insufficient amount of XRP, or any other currency, the Payment fails. -### Paths ### +### Paths If present, the `Paths` field must contain a _path set_ - an array of path arrays. Each individual path represents one way value can flow from the sender to receiver through various intermediary accounts and order books. A single transaction can potentially use multiple paths, for example if the transaction exchanges currency using several different order books to achieve the best rate. @@ -806,7 +806,7 @@ The `Paths` field must not be an empty array, nor an array whose members are all For more information, see [Paths](concept-paths.html). -### Payment Flags ### +### Payment Flags Transactions of the Payment type support additional values in the [`Flags` field](#flags), as follows: @@ -827,7 +827,7 @@ The [`delivered_amount`](#delivered-amount) field of a payment's metadata indica For more information, see the full article on [Partial Payments](concept-partial-payments.html). -### Limit Quality ### +### Limit Quality The XRP Ledger defines the "quality" of a currency exchange as the ratio of the numeric amount in to the numeric amount out. For example, if you spend $2 USD to receive £1 GBP, then the "quality" of that exchange is `0.5`. @@ -966,7 +966,7 @@ Example PaymentChannelFund: -## SetRegularKey ## +## SetRegularKey [[Source]
](https://github.com/ripple/rippled/blob/4239880acb5e559446d2067f00dabb31cf102a23/src/ripple/app/transactors/SetRegularKey.cpp "Source") @@ -996,7 +996,7 @@ For even greater security, you can use [multi-signing](#multi-signing), but mult -## SignerListSet ## +## SignerListSet [[Source]
](https://github.com/ripple/rippled/blob/ef511282709a6a0721b504c6b7703f9de3eecf38/src/ripple/app/tx/impl/SetSignerList.cpp "Source") The SignerListSet transaction creates, replaces, or removes a list of signers that can be used to [multi-sign](#multi-signing) a transaction. This transaction type was introduced by the [MultiSign amendment](concept-amendments.html#multisign). [New in: rippled 0.31.0][] @@ -1048,7 +1048,7 @@ You cannot remove the last method of signing transactions from an account. If an -## TrustSet ## +## TrustSet [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/SetTrust.cpp "Source") @@ -1079,7 +1079,7 @@ Create or modify a trust line linking two accounts. | QualityIn | Unsigned Integer | UInt32 | _(Optional)_ Value incoming balances on this trust line at the ratio of this number per 1,000,000,000 units. A value of `0` is shorthand for treating balances at face value. | | QualityOut | Unsigned Integer | UInt32 | _(Optional)_ Value outgoing balances on this trust line at the ratio of this number per 1,000,000,000 units. A value of `0` is shorthand for treating balances at face value. | -### Trust Limits ### +### Trust Limits All balances on the XRP Ledger, except for XRP, represent value owed in the world outside the XRP Ledger. The address that issues those funds in the XRP Ledger (identified by the `issuer` field of the `LimitAmount` object) is expected to pay the balance back, outside of the XRP Ledger, when users redeem their XRP Ledger balances by returning them to the issuer. @@ -1095,7 +1095,7 @@ The default state of all flags is off, except for the [NoRipple flag](concept-no The Auth flag of a trust line does not determine whether the trust line counts towards its owner's XRP reserve requirement. However, an enabled Auth flag prevents the trust line from being in its default state. An authorized trust line can never be deleted. An issuer can pre-authorize a trust line with the `tfSetfAuth` flag only, even if the limit and balance of the trust line are 0. -### TrustSet Flags ### +### TrustSet Flags Transactions of the TrustSet type support additional values in the [`Flags` field](#flags), as follows: @@ -1110,7 +1110,7 @@ Transactions of the TrustSet type support additional values in the [`Flags` fiel -# Pseudo-Transactions # +# Pseudo-Transactions Pseudo-Transactions are never submitted by users, nor propagated through the network. Instead, a server may choose to inject them in a proposed ledger directly. If enough servers inject an equivalent pseudo-transaction for it to pass consensus, then it becomes included in the ledger, and appears in ledger data thereafter. @@ -1126,7 +1126,7 @@ Some of the fields that are mandatory for normal transactions do not make sense -## EnableAmendment ## +## EnableAmendment Tracks the progress of the [amendment process](concept-amendments.html#amendment-process) for changes in transaction processing. This can indicate that a proposed amendment gained or lost majority approval, or that an amendment has been enabled. @@ -1137,7 +1137,7 @@ Tracks the progress of the [amendment process](concept-amendments.html#amendment | Amendment | String | Hash256 | A unique identifier for the amendment. This is not intended to be a human-readable name. See [Amendments](concept-amendments.html) for a list of known amendments. | | LedgerSequence | Number | UInt32 | The index of the ledger version where this amendment appears. This distinguishes the pseudo-transaction from other occurrences of the same change. | -### EnableAmendment Flags ### +### EnableAmendment Flags The `Flags` value of the EnableAmendment pseudo-transaction indicates the status of the amendment at the time of the ledger including the pseudo-transaction. @@ -1150,7 +1150,7 @@ A `Flags` value of `0` (no flags) indicates that the amendment has been enabled, -## SetFee ## +## SetFee A change in [transaction cost](concept-transaction-cost.html) or [account reserve](concept-reserves.html) requirements as a result of [Fee Voting](concept-fee-voting.html). @@ -1184,9 +1184,9 @@ A change in [transaction cost](concept-transaction-cost.html) or [account reserv -# Transaction Results # +# Transaction Results -## Immediate Response ## +## Immediate Response The response from the [`submit` command](reference-rippled.html#submit) contains a provisional result from the `rippled` server indicating what happened during local processing of the transaction. @@ -1208,7 +1208,7 @@ If nothing went wrong when submitting and applying the transaction locally, the **Note:** A successful result at this stage does not indicate that the transaction has completely succeeded; only that it was successfully applied to the provisional version of the ledger kept by the local server. See [Finality of Results](#finality-of-results) for details. -## Looking up Transaction Results ## +## Looking up Transaction Results To see the final result of a transaction, use the [`tx` command](reference-rippled.html#tx), [`account_tx` command](reference-rippled.html#account-tx), or other response from `rippled`. Look for `"validated": true` to indicate that this response uses a ledger version that has been validated by consensus. @@ -1226,7 +1226,7 @@ To see the final result of a transaction, use the [`tx` command](reference-rippl "validated": true ``` -## Result Categories ## +## Result Categories Both the `engine_result` and the `meta.TransactionResult` use standard codes to identify the results of transactions, as follows: @@ -1243,7 +1243,7 @@ The distinction between a local error (`tel`) and a malformed transaction (`tem` By contrast, a `tem` error implies that no server anywhere can apply the transaction, regardless of settings. Either the transaction breaks the rules of the protocol, it is unacceptably ambiguous, or it is completely nonsensical. The only way a malformed transaction could become valid is through changes in the protocol; for example, if a new feature is adopted, then transactions using that feature could be considered malformed by servers that are running older software which predates that feature. -## Claimed Cost Justification ## +## Claimed Cost Justification Although it may seem unfair to charge a [transaction cost](concept-transaction-cost.html) for a failed transaction, the `tec` class of errors exists for good reasons: @@ -1251,7 +1251,7 @@ Although it may seem unfair to charge a [transaction cost](concept-transaction-c * Distributing the transaction throughout the network increases network load. Enforcing a cost makes it harder for attackers to abuse the network with failed transactions. * The transaction cost is generally very small in real-world value, so it should not harm users unless they are sending large quantities of transactions. -## Finality of Results ## +## Finality of Results The order in which transactions apply to the consensus ledger is not final until a ledger is closed and the exact transaction set is approved by the consensus process. A transaction that succeeded initially could still fail, and a transaction that failed initially could still succeed. Additionally, a transaction that was rejected by the consensus process in one round could achieve consensus in a later round. @@ -1271,7 +1271,7 @@ Any other transaction result is potentially not final. In that case, the transac -## Understanding Transaction Metadata ## +## Understanding Transaction Metadata The metadata section of a transaction includes detailed information about all the changes to the shared XRP Ledger that the transaction caused. This is true of any transaction that gets included in a ledger, whether or not it is successful. Naturally, the changes are only final if the transaction is validated. @@ -1285,7 +1285,7 @@ Some fields that may appear in transaction metadata include: | `TransactionResult` | String | A [result code](#result-categories) indicating whether the transaction succeeded or how it failed. | | [`delivered_amount`](#delivered-amount) | [Currency Amount][] | The [Currency Amount][] actually received by the `Destination` account. Use this field to determine how much was delivered, regardless of whether the transaction is a [partial payment](#partial-payments). [New in: rippled 0.27.0][] | -### delivered_amount ### +### delivered_amount The `Amount` of a [Payment transaction][] indicates the amount to deliver to the `Destination`, so if the transaction was successful, then the destination received that much -- **except if the transaction was a [partial payment](#partial-payments)**. (In that case, any positive amount up to `Amount` might have arrived.) Rather than choosing whether or not to trust the `Amount` field, you should use the `delivered_amount` field of the metadata to see how much actually reached its destination. @@ -1298,12 +1298,12 @@ If both conditions are true, then `delivered_amount` contains the string value ` See also: [Partial Payments](concept-partial-payments.html) -## Full Transaction Response List ## +## Full Transaction Response List [[Source]
](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/TER.h "Source") -### tel Codes ### +### tel Codes These codes indicate an error in the local server processing the transaction; it is possible that another server with a different configuration or load level could process the transaction successfully. They have numerical values in the range -399 to -300. The exact code for any given error is subject to change, so don't rely on it. @@ -1323,7 +1323,7 @@ These codes indicate an error in the local server processing the transaction; it | `telLOCAL_ERROR` | Unspecified local error. | | `telNO_DST`_`PARTIAL` | The transaction is an XRP payment that would fund a new account, but the [tfPartialPayment flag](#partial-payments) was enabled. This is disallowed. | -### tem Codes ### +### tem Codes These codes indicate that the transaction was malformed, and cannot succeed according to the XRP Ledger protocol. They have numerical values in the range -299 to -200. The exact code for any given error is subject to change, so don't rely on it. @@ -1364,7 +1364,7 @@ These codes indicate that the transaction was malformed, and cannot succeed acco | `temDISABLED` | The transaction requires logic that is disabled. Typically this means you are trying to use an [amendment](concept-amendments.html) that is not enabled for the current ledger. | -### tef Codes ### +### tef Codes These codes indicate that the transaction failed and was not included in a ledger, but the transaction could have succeeded in some theoretical ledger. Typically this means that the transaction can no longer succeed in any future ledger. They have numerical values in the range -199 to -100. The exact code for any given error is subject to change, so don't rely on it. @@ -1389,7 +1389,7 @@ These codes indicate that the transaction failed and was not included in a ledge | `tefPAST_SEQ` | The sequence number of the transaction is lower than the current sequence number of the account sending the transaction. | | `tefWRONG_PRIOR` | The transaction contained an `AccountTxnID` field (or the deprecated `PreviousTxnID` field), but the transaction specified there does not match the account's previous transaction. | -### ter Codes ### +### ter Codes These codes indicate that the transaction failed, but it could apply successfully in the future, usually if some other hypothetical transaction applies first. They have numerical values in the range -99 to -1. The exact code for any given error is subject to change, so don't rely on it. @@ -1407,7 +1407,7 @@ These codes indicate that the transaction failed, but it could apply successfull | `terRETRY` | Unspecified retriable error. | | `terQUEUED` | The transaction met the load-scaled [transaction cost](concept-transaction-cost.html) but did not meet the open ledger requirement, so the transaction has been queued for a future ledger. | -### tes Success ### +### tes Success The code `tesSUCCESS` is the only code that indicates a transaction succeeded. This does not always mean it did what it was supposed to do. (For example, an [OfferCancel][] can "succeed" even if there is no offer for it to cancel.) Success uses the numerical value 0. @@ -1415,7 +1415,7 @@ The code `tesSUCCESS` is the only code that indicates a transaction succeeded. T |:-----------|:----------------------------------------------------------------| | `tesSUCCESS` | The transaction was applied and forwarded to other servers. If this appears in a validated ledger, then the transaction's success is final. | -### tec Codes ### +### tec Codes These codes indicate that the transaction failed, but it was applied to a ledger to apply the [transaction cost](concept-transaction-cost.html). They have numerical values in the range 100 to 199. The exact codes sometimes appear in ledger data, so they do not change, but we recommend not relying on the numeric value regardless. diff --git a/content/tutorial-gateway-guide.md b/content/tutorial-gateway-guide.md index d3dbf90d24..ca64c348a1 100644 --- a/content/tutorial-gateway-guide.md +++ b/content/tutorial-gateway-guide.md @@ -9,7 +9,7 @@ This document explains the concepts and steps necessary to become an XRP Ledger gateway. In this document, we use a fictional online currency exchange named "ACME" and its customers as examples, to show how ACME can expand its business to include being an XRP Ledger gateway. -## Contact Information ## +## Contact Information You are not on your own. Ripple wants gateways to succeed, so we are here to help. Please contact us if you need help building and growing your gateway. @@ -32,7 +32,7 @@ The XRP Ledger has a system of directional accounting relationships, called _tru A "trust line" is link between two addresses in the XRP Ledger. A trust line represents an explicit statement of willingness to hold gateway debt obligations. When a customer sends money into the XRP Ledger, a gateway takes custody of those assets outside of Ripple, and sends issuances in the XRP Ledger to the customer's address. When a customer sends money out of the XRP Ledger, she makes an XRP Ledger payment to the gateway, and the gateway credits the customer in its own system of record, or in some other account. -### XRP ### +### XRP **XRP** is the native cryptocurrency of the XRP Ledger. Like issuances, XRP can be freely sent and exchanged among XRP Ledger addresses. Unlike issuances, XRP is not tied to an accounting relationship. XRP can be sent directly from any XRP Ledger address to any other, without going through a gateway or liquidity provider. This helps make XRP a convenient bridge currency. For more information on XRP, see the [XRP Portal](https://ripple.com/xrp-portal/). @@ -42,7 +42,7 @@ Issuing gateways do not need to accumulate or exchange XRP. They must only hold Private exchanges and liquidity providers may choose to hold additional XRP for trading. Ripple (the company) **does not** promote XRP as a speculative investment. -### Liquidity and Currency Exchange ### +### Liquidity and Currency Exchange The XRP Ledger contains a currency exchange, where any user can place and fulfill bids to exchange XRP and _issuances_ in any combination. Cross-currency payments automatically use the currency exchange to convert currency atomically when the transaction is executed. In this way, users who choose make offers in the distributed exchange provide the liquidity that makes the XRP Ledger useful. @@ -53,7 +53,7 @@ Third-party liquidity providers can use the [`rippled` APIs](reference-rippled.h Contact [partners@ripple.com](mailto:partners@ripple.com) for help establishing liquidity between your gateway and others. -## Suggested Business Practices ## +## Suggested Business Practices The value of a gateway's issuances in the XRP Ledger comes directly from the trust that customers can redeem them with the gateway when needed. We recommend the following precautions to reduce the risk of business interruptions: @@ -63,14 +63,14 @@ The value of a gateway's issuances in the XRP Ledger comes directly from the tru * Publicize all your policies and fees. -### Hot and Cold Wallets ### +### Hot and Cold Wallets {% include 'snippets/issuing-and-operational-addresses-intro.md' %} For more information, see [Issuing and Operational Addresses](concept-issuing-and-operational-addresses.html) -## Fees and Revenue Sources ## +## Fees and Revenue Sources There are several ways in which a gateway can seek to profit from XRP Ledger integration. These can include: @@ -81,12 +81,12 @@ There are several ways in which a gateway can seek to profit from XRP Ledger int * [Financial Exchange](#liquidity-and-currency-exchange). A gateway can also make offers to buy and sell its issuances for other issuances in the XRP Ledger, providing liquidity to cross-currency payments and possibly making a profit. (As with all financial exchange, profits are not guaranteed.) -### Choosing Fee Rates ### +### Choosing Fee Rates Fees imposed by gateways are optional. Higher fees earn more revenue when a gateway's services are used. On the other hand, high fees discourage customers from using your services. Consider the fees that are charged by other gateways, especially ones issuing similar currencies, as well as traditional payment systems outside of the XRP Ledger, such as wire fees. Choosing the right fee structure is a matter of balancing your pricing with what the market is willing to pay. -## Gateway Compliance ## +## Gateway Compliance Gateways are responsible for complying with local regulations and reporting to the appropriate agencies. Regulations vary by country and state, but may include the reporting and compliance requirements described in the following sections. @@ -234,7 +234,7 @@ An example flow for a payment into the XRP Ledger: -### Requirements for Sending to XRP Ledger ### +### Requirements for Sending to XRP Ledger There are several prerequisites that ACME must meet for this to happen: @@ -252,7 +252,7 @@ There are several prerequisites that ACME must meet for this to happen: See [Sending Payments to Customers](#sending-payments-to-customers) for an example of how to send payments into the XRP Ledger. -## Sending from XRP Ledger to Gateway ## +## Sending from XRP Ledger to Gateway A payment out of the XRP Ledger means the Gateway receives a payment in the XRP Ledger, and credits a user in the gateway's system of record. @@ -263,7 +263,7 @@ An example flow of a payment out of the XRP Ledger: Payments going from the XRP Ledger to a gateway can be single-currency or cross-currency payments. The gateway's issuing address can only receive issuances it created (or XRP). -### Requirements for Receiving from XRP Ledger ### +### Requirements for Receiving from XRP Ledger In addition to the [requirements for sending into the XRP Ledger](#requirements-for-sending-to-xrp-ledger), there are several prerequisites that ACME must meet to process payments coming from the XRP Ledger: @@ -273,7 +273,7 @@ In addition to the [requirements for sending into the XRP Ledger](#requirements- - Typically, the preferred method of recognizing incoming payments is through [destination tags](#source-and-destination-tags). -## Precautions ## +## Precautions Processing payments to and from the XRP Ledger naturally comes with some risks, so a gateway should be sure to take care in implementing these processes. We recommend the following precautions: @@ -291,7 +291,7 @@ Processing payments to and from the XRP Ledger naturally comes with some risks, - Monitor for suspicious or abusive behavior. For example, a user could repeatedly send funds into and out of the XRP Ledger, as a denial of service attack that effectively empties an operational address's balance. Suspend customers whose addresses are involved in suspicious behavior by not processing their XRP Ledger payments. -## Trading on Ripple ## +## Trading on Ripple After the issuances have been created in the XRP Ledger, they can be freely transferred and traded by XRP Ledger users. There are several consequences of this situation: @@ -308,7 +308,7 @@ The following diagram depicts an XRP Ledger payment sending 2EUR.ACME from Alice -## Freeze ## +## Freeze A gateway can freeze accounting relationships in the XRP Ledger to meet regulatory requirements: @@ -319,7 +319,7 @@ A gateway can freeze accounting relationships in the XRP Ledger to meet regulato For more information, see the [Freeze article](concept-freeze.html). -## Authorized Accounts ## +## Authorized Accounts The XRP Ledger's Authorized Accounts feature enables a gateway to limit who can hold that gateway's issuances, so that unknown XRP Ledger addresses cannot hold the currency the gateway issues. Ripple feels this is *not necessary* in most cases, since gateways have full control over the process of redeeming Ripple balances for value in the outside world. (You can collect customer information and impose limits on withdrawals at that stage without worrying about what happens within the XRP Ledger.) @@ -334,7 +334,7 @@ The transaction to authorize an accounting relationship must be signed by the is See [RequireAuth](#requireauth) for technical details on how to use Authorized Accounts. -## Source and Destination Tags ## +## Source and Destination Tags *Destination Tags* are a feature of XRP Ledger payments can be used to indicate the beneficiary or destination for a payment. For example, an XRP Ledger payment to a gateway may include a destination tag to indicate which customer should be credited for the payment. A gateway should keep a mapping of destination tags to accounts in the gateway's system of record. @@ -378,7 +378,7 @@ For the gateway's own security as well as the stability of the network, Ripple r Contact [partners@ripple.com](mailto:partners@ripple.com) to see how Ripple can help. -### APIs and Middleware ### +### APIs and Middleware There are several interfaces you can use to connect to the XRP Ledger, depending on your needs and your existing software: @@ -386,14 +386,14 @@ There are several interfaces you can use to connect to the XRP Ledger, depending * [RippleAPI](reference-rippleapi.html) provides a simplified API for JavaScript applications. -## Tool Security ## +## 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. -## DefaultRipple ## +## DefaultRipple The DefaultRipple flag controls whether the balances in an accounting relationship [allowed to ripple](concept-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. @@ -452,7 +452,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. -## Generating Source and Destination Tags ## +## Generating Source and Destination Tags You need a scheme to create Source and Destination tags for your customers and payments. (See [Source and Destination Tags](#source-and-destination-tags) for an explanation of what Source and Destination Tags are.) @@ -465,7 +465,7 @@ We recommend making a user interface to generate a destination tag on-demand whe Enable the [RequireDest](#requiredest) flag on your issuing and operational addresses so that customers must use a destination tag to indicate where funds should go when they send XRP Ledger payments to your gateway. -## DisallowXRP ## +## DisallowXRP The DisallowXRP setting (`disallowIncomingXRP` in RippleAPI) is designed to discourage XRP Ledger users from sending XRP to an address by accident. This reduces the costs and effort of bouncing undesired payments, if your gateway does not trade XRP. The DisallowXRP flag is not strictly enforced, because doing so could allow addresses to become permanently unusable if they run out of XRP. Client applications should honor the DisallowXRP flag by default. @@ -522,7 +522,7 @@ Response: ``` -## RequireDest ## +## RequireDest The `RequireDest` setting (`requireDestinationTag` in RippleAPI) is designed to prevent customers from sending payments to your address while accidentally forgetting the [destination tag](#source-and-destination-tags) that identifies who should be credited for the payment. When enabled, the XRP Ledger rejects any payment to your address that does not specify a destination tag. @@ -580,7 +580,7 @@ Response: } ``` -## RequireAuth ## +## RequireAuth The `RequireAuth` setting (`requireAuthorization` in RippleAPI) prevents all counterparties from holding balances issued by an address unless the address has specifically approved an accounting relationship with that counterparty. @@ -590,7 +590,7 @@ If you want to use the [Authorized Accounts](#authorized-accounts) feature, you You can only enable `RequireAuth` if the address owns no accounting relationships (trust lines) and no offers in the XRP Ledger, so you must decide whether or not to use it before you start doing business in the XRP Ledger. -### Enabling RequireAuth ### +### Enabling RequireAuth The following is an example of using a locally-hosted `rippled`'s [`submit` command](reference-rippled.html#submit) to send an AccountSet transaction to enable the RequireAuth flag: (This method works the same way regardless of whether the address is an issuing address, operational address, or standby address.) @@ -617,7 +617,7 @@ POST http://localhost:5005/ {% include 'snippets/secret-key-warning.md' %} -### Authorizing Trust Lines ### +### Authorizing Trust Lines If you are using the [Authorized Accounts](#authorized-accounts) feature, customers cannot hold balances you issue unless you first authorize their accounting relationships to you in the XRP Ledger. @@ -653,7 +653,7 @@ POST http://localhost:8088/ {% include 'snippets/secret-key-warning.md' %} -## Robustly Monitoring for Payments ## +## Robustly Monitoring for Payments To robustly check for incoming payments, gateways should do the following: @@ -672,7 +672,7 @@ As an added precaution, we recommend comparing the balances of your issuing addr * 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. -## TransferRate ## +## TransferRate The *TransferRate* setting (`transferRate` in RippleAPI) defines a fee to charge for transferring issuances from one XRP Ledger address to another. See [Transfer Fees](concept-transfer-fees.html) for more information. @@ -724,7 +724,7 @@ Response: } ``` -### TransferRate with Operational and Standby Addresses ### +### TransferRate with Operational and Standby Addresses 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. @@ -736,7 +736,7 @@ All XRP Ledger addresses, including operational and standby addresses, are subje For example: If ACME sets a transfer fee of 1%, an XRP Ledger payment to deliver 5 EUR.ACME from a customer address to ACME's issuing address would cost exactly 5 EUR.ACME. However, the customer would need to send 5.05 EUR.ACME to deliver 5 EUR.ACME to ACME's operational address. (The issuing address's total obligations in the XRP Ledger decrease by 0.05 EUR.ACME.) When ACME credits customers for payments to ACME's operational address, ACME credits the customer for the amount delivered to the operational address _and_ the transfer fee, giving the customer €5,05 in ACME's systems. -## Sending Payments to Customers ## +## Sending Payments to Customers When you build an automated system to send payments into the XRP Ledger for your customers, you must make sure that it constructs payments carefully. Malicious actors are constantly trying to find ways to trick a system into paying them more money than it should. @@ -815,7 +815,7 @@ In particular, note the following features of the [Payment Transaction](referenc - The `value` of the `SendMax` amount is slightly higher than the destination `Amount`, to compensate for the [transfer fee](#transferrate). In this case, the transfer fee is 0.5%, so the `SendMax` amount is exactly 1.005 times the destination `Amount`. -## Bouncing Payments ## +## Bouncing Payments When one of your addresses receives a payment whose purpose is unclear, we recommend that you try to return the money to its sender. While this is more work than pocketing the money, it demonstrates good faith towards customers. You can have an operator bounce payments manually, or create a system to do so automatically. @@ -831,7 +831,7 @@ You should use the `SourceTag` value (`source.tag` in RippleAPI) from the incomi To prevent two systems from bouncing payments back and forth indefinitely, you can set a new Source Tag for the outgoing return payment. If you receive an unexpected payment whose Destination Tag matches the Source Tag of a return you sent, then do not bounce it back again. -## Reliable Transaction Submission ## +## Reliable Transaction Submission The goal of reliably submitting transactions is to achieve the following two properties in a finite amount of time: @@ -847,7 +847,7 @@ To submit transactions reliably, follow these guidelines: For more information, see [Reliable Transaction Submission](tutorial-reliable-transaction-submission.html). -## ripple.txt ## +## ripple.txt The [ripple.txt](https://wiki.ripple.com/Ripple.txt) standard provides a way to publish information about your gateway so that automated tools and applications can read and understand it. diff --git a/content/tutorial-multisign.md b/content/tutorial-multisign.md index 61ef93dd33..7fee5bbe94 100644 --- a/content/tutorial-multisign.md +++ b/content/tutorial-multisign.md @@ -1,5 +1,4 @@ -How to Multi-Sign -============================= +# How to Multi-Sign Multi-signing is one of three ways to authorize transactions for the XRP Ledger, alongside signing with [regular keys](reference-transaction-format.html#setregularkey) and master keys. You can configure your address to allow any combination of the three methods to authorize transactions. @@ -17,8 +16,7 @@ To use multi-signing: 3. [Send transactions using multiple signatures.](#sending-a-multi-signed-transaction) -Availability of Multi-Signing ------------------------------ +## Availability of Multi-Signing Multi-signing has been enabled by an [**Amendment**](concept-amendments.html) to the XRP Ledger Consensus Protocol since 2016-06-27. @@ -30,13 +28,12 @@ To force the multi-signing feature to be enabled, add the following stanza to yo MultiSign -Setting up Multi-Signing ------------------------- +## Setting up Multi-Signing To multi-sign transactions from a particular address, you must create a list of addresses that can contribute to a multi-signature for your address. This list is stored in the XRP Ledger as a [SignerList node](reference-ledger-format.html#signerlist). The following procedure demonstrates how to set up a SignerList for your address: -### 1. Prepare a funded address ### +### 1. Prepare a funded address You need an XRP Ledger address that can send transactions, and has enough XRP available. Multi-signing requires more than the usual amount of XRP for the [account reserve](concept-reserves.html) and [transaction cost](concept-transaction-cost.html), increasing with the number of signers and signatures you use. @@ -47,7 +44,7 @@ If you started `rippled` in [stand-alone mode](concept-stand-alone-mode.html) wi 3. Manually close the ledger. -### 2. Prepare member keys ### +### 2. Prepare member keys You need several sets of XRP Ledger keys (address and secret) to include as members of your SignerList. These can be funded addresses that exist in the ledger, or you can generate new addresses using the [`wallet_propose` command](reference-rippled.html#wallet-propose). For example: @@ -70,7 +67,7 @@ You need several sets of XRP Ledger keys (address and secret) to include as memb Take note of the `account_id` (XRP Ledger Address) and `master_seed` (secret key) for each one you generate. -### 3. Send SignerListSet transaction ### +### 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. @@ -153,7 +150,7 @@ Make sure that the [Transaction Result](reference-transaction-format.html#transa **Note:** The more members in the SignerList, the more XRP your address must have for purposes of the [owner reserve](concept-reserves.html#owner-reserves). If your address does not have enough XRP, the transaction fails with [tecINSUFFICIENT_RESERVE](reference-transaction-format.html#tec-codes). See also: [SignerLists and Reserves](reference-ledger-format.html#signerlists-and-reserves). -### 4. Close the ledger ### +### 4. Close the ledger On the live network, you can wait 4-7 seconds for the ledger to close automatically. @@ -170,7 +167,7 @@ If you're running `rippled` in stand-alone mode, use the [`ledger_accept` comman } -### 5. Confirm the new signer list ### +### 5. Confirm the new signer list Use the [`account_objects` command](reference-rippled.html#account-objects) to confirm that the SignerList is associated with the address in the latest validated ledger. @@ -223,7 +220,7 @@ Normally, an account can own many objects of different types (such as trust line If the SignerList is present with the expected contents, then your address is ready to multi-sign. -### 6. Further steps ### +### 6. Further steps At this point, your address is ready to [send a multi-signed transaction](#sending-a-multi-signed-transaction). You may also want to: @@ -231,12 +228,11 @@ At this point, your address is ready to [send a multi-signed transaction](#sendi * Remove the address's regular key pair (if you previously set one) by sending a [SetRegularKey transaction](reference-transaction-format.html#setregularkey). -Sending a Multi-Signed Transaction ----------------------------------- +## Sending a Multi-Signed Transaction Before you can multi-sign a transaction, first [set up multi-signing](#setting-up-multi-signing) for your address. The following procedure demonstrates how to create, sign, and submit a multi-signed transaction. -### 1. Create the transaction ## +### 1. Create the transaction Create a JSON object that represents the transaction you want to submit. You have to specify _everything_ about this transaction, including `Fee` and `Sequence`. Also include the field `SigningPubKey` as an empty string, to indicate that the transaction is multi-signed. @@ -261,7 +257,7 @@ Here's an example transaction ready to be multi-signed: (This transaction creates an accounting relationship from rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC to rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh with a maximum balance of 100 USD.) -### 2. Get one signature ### +### 2. Get one signature Use the [`sign_for` command](reference-rippled.html#sign-for) with the secret key and address of one of the members of your SignerList to get a signature for that member. @@ -316,7 +312,7 @@ Save the `tx_json` field of the response: it has the new signature in the `Signe If you have a problem in stand-alone mode or a non-production network, check that [multi-sign is enabled](#availability-of-multi-signing). -### 3. Get additional signatures ### +### 3. Get additional signatures You can collect additional signatures in parallel or in serial: @@ -390,7 +386,7 @@ You can collect additional signatures in parallel or in serial: Depending on the SignerList you configured, you may need to repeat this step several times to get signatures from all the necessary parties. -### 4. Combine signatures and submit ### +### 4. Combine signatures and submit If you collected the signatures in serial, the `tx_json` from the last `sign_for` response has all the signatures assembled, so you can use that as the argument to the [`submit_multisigned` command](reference-rippled.html#submit-multisigned). @@ -469,7 +465,7 @@ If you collected the signatures in parallel, you must manually construct a `tx_j Take note of the `hash` value from the response so you can check the results of the transaction later. (In this case, the hash is `BD636194C48FD7A100DE4C972336534C8E710FD008C0F3CF7BC5BF34DAF3C3E6`.) -### 5. Close the ledger ## +### 5. Close the ledger If you are using the live network, you can wait 4-7 seconds for the ledger to close automatically. @@ -486,7 +482,7 @@ If you're running `rippled` in stand-alone mode, use the [`ledger_accept` comman } -### 6. Confirm transaction results ### +### 6. Confirm transaction results Use the hash value from the response to the `submit_multisigned` command to look up the transaction using the [`tx` command](reference-rippled.html#tx). In particular, check that the `TransactionResult` is the string `tesSUCCESS`. diff --git a/content/tutorial-rippleapi-beginners-guide.md b/content/tutorial-rippleapi-beginners-guide.md index 431292da4f..3e931a2188 100644 --- a/content/tutorial-rippleapi-beginners-guide.md +++ b/content/tutorial-rippleapi-beginners-guide.md @@ -4,11 +4,11 @@ This tutorial guides you through the basics of building an XRP Ledger-connected 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). -# Environment Setup # +# Environment Setup The first step to using RippleAPI is setting up your development environment. -## Install Node.js and npm ## +## Install Node.js and npm RippleAPI is built as an application for the Node.js runtime environment, so the first step is getting Node.js installed. RippleAPI requires Node.js version 0.12, version 4.x, or higher. @@ -26,7 +26,7 @@ On some platforms, the binary is named `nodejs` instead: nodejs --version ``` -## Use NPM to install RippleAPI and dependencies ## +## Use NPM to install RippleAPI and dependencies RippleAPI uses the newest version of JavaScript, ECMAScript 6 (also known as ES2015). To use the new features of ECMAScript 6, RippleAPI depends on [Babel-Node](https://babeljs.io) and its ES2015 presets. You can use `npm` to install RippleAPI and these dependencies together. @@ -76,7 +76,7 @@ npm WARN notsup Not compatible with your operating system or architecture: fseve npm WARN ajv@1.4.10 requires a peer of ajv-i18n@0.1.x but none was installed. ``` -# First RippleAPI Script ## +# First RippleAPI Script This script, `get-account-info.js`, fetches information about a hard-coded account. Use it to test that RippleAPI works: @@ -84,7 +84,7 @@ This script, `get-account-info.js`, fetches information about a hard-coded accou {% include 'code_samples/rippleapi_quickstart/get-account-info.js' %} ``` -## Running the script ## +## Running the script RippleAPI and the script both use the ECMAScript 6 version of JavaScript. That's why we installed Babel earlier. The easiest way to run ECMAScript 6 is to use the `babel-node` binary, which NPM installs in the `node_modules/.bin/` directory of your project. Thus, running the script looks like this: @@ -106,11 +106,11 @@ getAccountInfo done done and disconnected. ``` -## Understanding the script ## +## Understanding the script In addition to RippleAPI-specific code, this script uses syntax and conventions that are recent developments in JavaScript. Let's divide the sample code into smaller chunks to explain each one. -### Script opening ### +### Script opening ``` 'use strict'; @@ -119,9 +119,9 @@ const RippleAPI = require('ripple-lib').RippleAPI; The opening line enables [strict mode](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode). This is purely optional, but it helps you avoid some common pitfalls of JavaScript. See also: [Restrictions on Code in Strict Mode](https://msdn.microsoft.com/library/br230269%28v=vs.94%29.aspx#Anchor_1). -The second line imports RippleAPI into the current scope using Node.js's require function. RippleAPI is one of [the modules `ripple-lib` exports](https://github.com/ripple/ripple-lib/blob/develop/src/index.js). +The second line imports RippleAPI into the current scope using Node.js's require function. RippleAPI is one of [the modules `ripple-lib` exports](https://github.com/ripple/ripple-lib/blob/develop/src/index.ts). -### Instantiating the API ### +### Instantiating the API ``` const api = new RippleAPI({ @@ -138,7 +138,7 @@ The one argument to the constructor is an options object, which has [a variety o * 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. -### Connecting and Promises ### +### Connecting and Promises ``` api.connect().then(() => { @@ -152,7 +152,7 @@ When a Promise finishes with its asynchronous operations, the Promise runs the c Finally, we have more new ECMAScript 6 syntax - an [arrow function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions). Arrow functions are a shorter way of defining anonymous functions. This is convenient for defining lots of one-off functions as callbacks. The syntax `()=> {...}` is mostly equivalent to `function() {...}`. If you want an anonymous function with one parameter, you can use a syntax like `info => {...}` instead, which is almost the same as `function(info) {...}` syntax. -### Custom code ### +### Custom code ``` /* begin custom code ------------------------------------ */ @@ -178,7 +178,7 @@ Keep in mind that the example code starts in the middle of a callback function ( 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. -### Cleanup ### +### Cleanup ``` }).then(() => { @@ -192,7 +192,7 @@ The rest of the sample code is mostly more [boilerplate code](reference-rippleap 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 # +# 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: @@ -208,11 +208,11 @@ If you are the administrator of the `rippled` server, you can [manually request See [Reliable Transaction Submission](tutorial-reliable-transaction-submission.html) for a more thorough explanation. -# RippleAPI in Web Browsers # +# RippleAPI in Web Browsers RippleAPI can also be used in a web browser if you compile a browser-compatible version and include [lodash](https://www.npmjs.com/package/lodash) as a dependency before the RippleAPI script. -## Build Instructions ## +## Build Instructions To use RippleAPI in a browser, you need to build a browser-compatible version. The following process compiles RippleAPI into a single JavaScript file you can include in a webpage. @@ -276,7 +276,7 @@ This may take a while. At the end, the build process creates a new `build/` fold The file `build/ripple-.js` is a straight export of RippleAPI (whatever version you built) ready to be used in browsers. The file ending in `-min.js` is the same thing, but with the content [minified](https://en.wikipedia.org/wiki/Minification_%28programming%29) for faster loading. -## Example Browser Usage ## +## Example Browser Usage The following HTML file demonstrates basic usage of the browser version of RippleAPI to connect to a public `rippled` server and report information about that server. Instead of using Node.js's "require" syntax, the browser version creates a global variable named `ripple`, which contains the `RippleAPI` class. diff --git a/content/tutorial-rippled-setup.md b/content/tutorial-rippled-setup.md index 6dd2640b07..a4759a8b8b 100644 --- a/content/tutorial-rippled-setup.md +++ b/content/tutorial-rippled-setup.md @@ -1,4 +1,4 @@ -# Operating rippled Servers # +# 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. @@ -8,7 +8,7 @@ This page contains instructions for: * [Participating in the Consensus Process](#running-a-validator) -## Types of rippled Servers ## +## Types of rippled Servers The `rippled` server software can run in several modes depending on its configuration, including: @@ -19,7 +19,7 @@ The `rippled` server software can run in several modes depending on its configur You can also run the `rippled` executable as a client application for accessing [`rippled` APIs](reference-rippled.html) locally. (Two instances of the same binary can run side-by-side in this case; one as a server, and the other running briefly as a client and then terminating.) -## Reasons to Run a Stock Server ## +## Reasons to Run a Stock Server There are lots of reasons you might want to run your own `rippled` server, but most of them can be summarized as: you can trust your own server, you have control over its workload, and you're not at the mercy of others to decide when and how you can access it. Of course, you must practice good network security to protect your server from malicious hackers. @@ -42,7 +42,7 @@ Not all `rippled` servers need to be validators: trusting more servers from the If your organization runs a validating server, you may also run one or more stock servers, to balance the computing load of API access, or as a proxy between your validation server and the outside network. -### Properties of a Good Validator ### +### Properties of a Good Validator There are several properties that define a good validator. The more of these properties your server embodies, the more reason others have to include your server in their list of trusted validators: @@ -58,13 +58,13 @@ There are several properties that define a good validator. The more of these pro At present, Ripple (the company) cannot recommend any validators aside from the 5 core validators run by Ripple: these validators are included in the default `rippled` configuration. However, we are collecting data on other validators and building tools to report on their performance. For metrics on validators, see [validators.ripple.com](https://validators.ripple.com). -# Installing rippled # +# Installing 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. -## System Requirements ## +## 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: @@ -80,7 +80,7 @@ Amazon EC2's m3.large VM size may be appropriate depending on your workload. (Va Naturally, a fast network connection is preferable. -## Installation on CentOS/Red Hat with yum ## +## Installation on CentOS/Red Hat with yum This section assumes that you are using CentOS 7 or Red Hat Enterprise Linux 7. @@ -100,7 +100,7 @@ This section assumes that you are using CentOS 7 or Red Hat Enterprise Linux 7. $ sudo systemctl start rippled.service -## Installation on Ubuntu with alien ## +## Installation on Ubuntu with alien This section assumes that you are using Ubuntu 15.04 or later. @@ -133,7 +133,7 @@ This section assumes that you are using Ubuntu 15.04 or later. $ sudo systemctl start rippled.service -## Postinstall ## +## Postinstall 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. @@ -142,11 +142,11 @@ It can take several minutes for `rippled` to sync with the rest of the network, $ /opt/ripple/bin/rippled -## Updating rippled ## +## Updating rippled You can subscribe to the [rippled Google Group](https://groups.google.com/forum/#!forum/ripple-server) to receive notifications of new `rippled` releases. -### Automatic Update on CentOS/Red Hat ### +### Automatic Update on CentOS/Red Hat Automatic rippled updates can be enabled with a one-time Cron configuration: @@ -168,7 +168,7 @@ Automatic rippled updates can be enabled with a one-time Cron configuration: The script updates the installed `rippled` package within an hour of each new release. -### Manual Update on CentOS/Red Hat ### +### Manual Update on CentOS/Red Hat Run the following commands to update to the latest release of `rippled`: @@ -177,7 +177,7 @@ Run the following commands to update to the latest release of `rippled`: $ sudo systemctl daemon-reload $ sudo service rippled restart -### Manual Update on Ubuntu ### +### Manual Update on Ubuntu Run the following commands to update to the latest release of `rippled`: @@ -189,7 +189,7 @@ Run the following commands to update to the latest release of `rippled`: $ sudo service rippled restart -# Running a Validator # +# Running a Validator Running a `rippled` validator that participates in the Consensus process is simple: @@ -200,7 +200,7 @@ Running a `rippled` validator that participates in the Consensus process is simp * Also see [Properties of a Good Validator](#properties-of-a-good-validator) for best practices. -## Validator Setup ## +## Validator Setup The `validator-keys` tool (included in the `rippled` RPM) is the recommended means to securely generate and manage your validator keys. @@ -225,7 +225,7 @@ The `validator-keys` tool (included in the `rippled` RPM) is the recommended mea See [the `validator-keys-tool` GitHub repository](https://github.com/ripple/validator-keys-tool/blob/master/doc/validator-keys-tool-guide.md) for more information about managing validator keys. -## Public-Facing Server ## +## Public-Facing Server 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. @@ -246,7 +246,7 @@ Remember to restart `rippled` for config changes to take effect. Take care not to publish the IP address of your validator. -## Domain Verification ## +## Domain Verification Network participants are unlikely to trust validators without knowing who is operating them. To address this concern, validator operators can associate their validator with a web domain that they control. @@ -265,7 +265,7 @@ Network participants are unlikely to trust validators without knowing who is ope 4. In order to have the verified validator domain published, email with both signatures as well as the validator public key and domain name. -# Additional Configuration # +# Additional Configuration `rippled` should connect to the XRP Ledger with the default configuration. However, you can change your settings by editing the `rippled.cfg` file (located at `/opt/ripple/etc/rippled.cfg` when installing `rippled` with yum). @@ -280,7 +280,7 @@ Restart `rippled` for any configuration changes to take effect: $ sudo service rippled restart -## Parallel Networks ## +## Parallel Networks Most of the time, we describe the XRP Ledger as one collective, singular entity -- and that's mostly true. There is one production XRP Ledger peer-to-peer network, and all business that takes place on the XRP Ledger occurs within the production network. @@ -290,12 +290,12 @@ However, sometimes you may want to do tests and experiments without interacting Over time, there may also be smaller, temporary test networks for specific purposes. -### Parallel Networks and Consensus ### +### Parallel Networks and Consensus There is no `rippled` setting that defines which network it uses. Instead, it uses the consensus of validators it trusts to know which ledger to accept as the truth. When different consensus groups of `rippled` instances only trust other members of the same group, each group continues as a parallel network. Even if malicious or misbehaving computers connect to both networks, the consensus process overrides the confusion as long as the members of each network are not configured to trust members of another network in excess of their quorum settings. -## Clustering ## +## Clustering If you are running multiple `rippled` servers in a single datacenter, you can configure those servers into a cluster to maximize efficiency. Running your `rippled` servers in a cluster provides the following benefits: