diff --git a/content/concepts/issued-currencies/issued-currencies-overview.md b/content/concepts/issued-currencies/issued-currencies-overview.md index d367263afe..6f02d738a7 100644 --- a/content/concepts/issued-currencies/issued-currencies-overview.md +++ b/content/concepts/issued-currencies/issued-currencies-overview.md @@ -1,6 +1,6 @@ # Issued Currencies Overview -All currencies other than XRP can be represented in the XRP Ledger as **issued currencies**. These digital assets (sometimes called "issuances" or "IOUs") are tracked in accounting relationships, called "trust lines," between addresses. Issued currencies are typically considered as liabilities from one perspective and assets from the other, so the balance of a trust line is negative or positive depending on which side you view it from. Any address may freely issue (non-XRP) currencies, limited only by how much other addresses are willing to hold. +All currencies other than XRP can be represented in the XRP Ledger as **issued currencies**. These digital assets (sometimes called "IOUs") are tracked in accounting relationships, called "trust lines," between addresses. Issued currencies are typically considered as liabilities from one perspective and assets from the other, so the balance of a trust line is negative or positive depending on which side you view it from. Any address may freely issue (non-XRP) currencies, limited only by how much other addresses are willing to hold. Issued currencies can "ripple" through multiple issuers and holders if they use the same currency code. This is useful in some cases, but can cause unexpected and undesirable behavior in others. You can use the [NoRipple flag](rippling.html) on trust lines to prevent those trust lines from rippling. @@ -10,7 +10,7 @@ In the typical model, an issued currency is tied to holdings of currency or othe There are other use cases for issued currencies in the XRP Ledger. For example, you can create an "Initial Coin Offering" (ICO) by issuing a fixed amount of currency to a secondary address, then "throwing away the key" to the issuer. -**Warning:** ICOs may be [regulated as securities](https://www.sec.gov/oiea/investor-alerts-and-bulletins/ib_coinofferings) in the USA. +**Warning:** ICOs may be [regulated as securities](https://www.sec.gov/oiea/investor-alerts-and-bulletins/ib_coinofferings) in the USA. Ripple strongly recommends researching the relevant regulations before engaging in any financial service business. diff --git a/content/concepts/issued-currencies/trust-lines-and-issuing.md b/content/concepts/issued-currencies/trust-lines-and-issuing.md index b94a684248..7a839bb786 100644 --- a/content/concepts/issued-currencies/trust-lines-and-issuing.md +++ b/content/concepts/issued-currencies/trust-lines-and-issuing.md @@ -16,7 +16,7 @@ Trust lines are represented in the ledger's state data as [RippleState objects]( A trust line with settings in the default state is equivalent to no trust line. -The default state of all trust line flags is off, except for the [NoRipple flag](rippling.html), whose default state depends on the DefaultRipple flag. +The default state of all trust line flags is off, except for the [No Ripple flag](rippling.html), whose default state depends on the `DefaultRipple` flag. ## See Also diff --git a/content/concepts/payment-system-basics/accounts/accounts.md b/content/concepts/payment-system-basics/accounts/accounts.md index cf4db6fc7d..dcafa72758 100644 --- a/content/concepts/payment-system-basics/accounts/accounts.md +++ b/content/concepts/payment-system-basics/accounts/accounts.md @@ -2,10 +2,7 @@ An "Account" in the XRP Ledger represents a holder of XRP and a sender of [transactions](transaction-formats.html). The core elements of an account are: -- An identifying **address**, such as `rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn` - - **Note:** The XRP community has [proposed](https://github.com/xrp-community/standards-drafts/issues/6) (and developed a [codec](https://github.com/xrp-community/xrpl-tagged-address-codec) to support) a new **X**-address format that exchanges and wallets could use instead of [destination tags](source-and-destination-tags.html). These "packed" addresses start with an `X` instead of an `r`. For more information, see the [XRPL X-address format](https://xrpaddress.info/) site. - +- An identifying **address**, such as `rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn`. (This is a "classic address", as opposed to the [X-Address format](#addresses).) - An **XRP balance**. Some of this XRP is set aside for the [Reserve](reserves.html). - A **sequence number**, which helps make sure any transactions this account sends are applied in the correct order and only once each. To execute a transaction, the transaction's sequence number and its sender's sequence number must match. Then, as part of applying the transaction, the account's sequence number increases by 1. (See also: [Basic Data Types: Account Sequence](basic-data-types.html#account-sequence).) - A **history of transactions** that affected this account and its balances. diff --git a/content/concepts/payment-system-basics/accounts/cryptographic-keys.md b/content/concepts/payment-system-basics/accounts/cryptographic-keys.md index c6f53046a5..16a1a7fe64 100644 --- a/content/concepts/payment-system-basics/accounts/cryptographic-keys.md +++ b/content/concepts/payment-system-basics/accounts/cryptographic-keys.md @@ -42,9 +42,11 @@ The `wallet_propose` response does not explicitly list the secret key value, als The `public_key` and `public_key_hex` both represent the same public key value. The public key is derived from the secret key as part of key derivation. The public key makes it possible to verify the authenticity of a transaction signature, but not to create more signatures. -**account_id** +**Account ID** -The `account_id` is [derived from the public key](accounts.html#address-encoding) and designates the *potential* for an account to be created in the XRP Ledger. It is important to know that while an `account_id` exists, no actual account exists in the XRP Ledger until the `account_id` receives its first XRP payment. In addition, the `account_id` can't send any transactions until after it's received a transaction that funds and creates the account. +The `account_id` is [derived from the public key](accounts.html#address-encoding) and designates the *potential* for an account to be created in the XRP Ledger. Typically, an Account ID is encoded in [base58][] to make a "classic address", but other representations are possible, including hexadecimal. The [X-Address format](accounts.html#addresses) combines an Account ID and a [Destination Tag](source-and-destination-tags.html) into a single address. + +It is important to know that while an `account_id` exists, no actual account exists in the XRP Ledger until the `account_id` receives its first XRP payment. In addition, the `account_id` can't send any transactions until after it's received a transaction that funds and creates the account. The `account_id` (without a funded account) can, however, be used as a [regular key](#regular-key-pair) or a [member of a signer list](multi-signing.html) to authorize transactions for another account that does exist. diff --git a/content/concepts/payment-system-basics/accounts/depositauth.md b/content/concepts/payment-system-basics/accounts/depositauth.md index acb50d41a7..2c34907cfb 100644 --- a/content/concepts/payment-system-basics/accounts/depositauth.md +++ b/content/concepts/payment-system-basics/accounts/depositauth.md @@ -43,7 +43,7 @@ An account with Deposit Authorization enabled: - **Can** receive XRP or issued currencies by sending a [CheckCash][] transaction. _(Added by the [Checks amendment][].)_ - **Can** receive XRP or issued currencies by sending [OfferCreate transactions][]. - If the account sends an OfferCreate transaction that is not fully executed immediately, it **can** receive the remainder of the ordered XRP or issued currency later when the offer is consumed by other accounts' [Payment][] and [OfferCreate][] transactions. -- If the account has created any trust lines without the [NoRipple flag](rippling.html) enabled, or has enabled the DefaultRipple flag and issued any currency, the account **can** receive the issued currencies of those trust lines in [Payment transactions][] as a result of rippling. It cannot be the destination of those transactions. +- If the account has created any trust lines without the [NoRipple flag](rippling.html) enabled, or has enabled the `DefaultRipple` flag and issued any currency, the account **can** receive the issued currencies of those trust lines in [Payment transactions][] as a result of rippling. It cannot be the destination of those transactions. - In general, an account in the XRP Ledger **cannot** receive any non-XRP currencies in the XRP Ledger as long as all of the following are true. (This rule is not specific to the DepositAuth flag.) - The account has not created any trust lines with a nonzero limit. - The account has not issued currency on trust lines created by others diff --git a/content/concepts/payment-system-basics/ledgers.md b/content/concepts/payment-system-basics/ledgers.md index 93c0d7b298..1dc235ff3b 100644 --- a/content/concepts/payment-system-basics/ledgers.md +++ b/content/concepts/payment-system-basics/ledgers.md @@ -17,7 +17,7 @@ A single ledger version consists of several parts: ## Tree Format -As its name might suggest, a ledger's state tree is a tree data structure. Each object in the state tree is identified by a 256-bit object ID. In JSON, a ledger object's ID is the `index` field, which contains a 64-character hexadecimal string like `"193C591BF62482468422313F9D3274B5927CA80B4DD3707E42015DD609E39C94"`. Every object in the state tree has an ID that you can use to look up that object; every transaction has an indentifying hash that you can use to look up the transaction in the transaction tree. Do not confuse the `index` (ID) of a ledger object with the [`ledger_index` (sequence number) of a ledger][Ledger Index]. +As its name might suggest, a ledger's state tree is a tree data structure. Each object in the state tree is identified by a 256-bit object ID. In JSON, a ledger object's ID is the `index` field, which contains a 64-character hexadecimal string like `"193C591BF62482468422313F9D3274B5927CA80B4DD3707E42015DD609E39C94"`. Every object in the state tree has an ID that you can use to look up that object; every transaction has an identifying hash that you can use to look up the transaction in the transaction tree. Do not confuse the `index` (ID) of a ledger object with the [`ledger_index` (sequence number) of a ledger][Ledger Index]. **Tip:** Sometimes, an object in the ledger's state tree is called a "ledger node". For example, transaction metadata returns a list of `AffectedNodes`. Do not confuse this with a "node" (server) in the peer-to-peer network. diff --git a/content/concepts/payment-system-basics/transaction-basics/source-and-destination-tags.md b/content/concepts/payment-system-basics/transaction-basics/source-and-destination-tags.md index 9e3dd0bf8d..634768d323 100644 --- a/content/concepts/payment-system-basics/transaction-basics/source-and-destination-tags.md +++ b/content/concepts/payment-system-basics/transaction-basics/source-and-destination-tags.md @@ -30,7 +30,7 @@ Assigning tags in numerical order provides less privacy to customers. Since all ## Requiring Tags -For an XRP Ledger address that may receive payments intended for several customer accounts, receiving a payment _without_ a destination tag can be a problem: it is not immediately obvious which customer to credit, which can require a manual intervention and a discussion with the sender to figure out who was the intended recipient. To reduce cases like this, you can [enable the RequireDest setting](require-destination-tags.html). That way, if a user forgets to include a destination tag in a payment, the XRP Ledger rejects their payment instead of giving you money you don't know what to do with. The user can then send the payment again, using the tag as they should have. +For an XRP Ledger address that may receive payments intended for several customer accounts, receiving a payment _without_ a destination tag can be a problem: it is not immediately obvious which customer to credit, which can require a manual intervention and a discussion with the sender to figure out who was the intended recipient. To reduce cases like this, you can [enable the `RequireDest` setting](require-destination-tags.html). That way, if a user forgets to include a destination tag in a payment, the XRP Ledger rejects their payment instead of giving you money you don't know what to do with. The user can then send the payment again, using the tag as they should have. ## See Also diff --git a/content/concepts/payment-system-basics/transaction-basics/transaction-cost.md b/content/concepts/payment-system-basics/transaction-basics/transaction-cost.md index b0a64b1910..be9c8baad4 100644 --- a/content/concepts/payment-system-basics/transaction-basics/transaction-cost.md +++ b/content/concepts/payment-system-basics/transaction-basics/transaction-cost.md @@ -139,11 +139,11 @@ When a transaction has already been distributed to the network, but the account ## Key Reset Transaction -As a special case, an account can send a [SetRegularKey](setregularkey.html) transaction with a transaction cost of `0`, as long as the account's [lsfPasswordSpent flag](accountroot.html) is disabled. This transaction must be signed by the account's _master key pair_. Sending this transaction enables the lsfPasswordSpent flag. +As a special case, an account can send a [SetRegularKey](setregularkey.html) transaction with a transaction cost of `0`, as long as the account's [`lsfPasswordSpent` flag](accountroot.html) is disabled. This transaction must be signed by the account's _master key pair_. Sending this transaction enables the `lsfPasswordSpent` flag. This feature is designed to allow you to recover an account if the regular key is compromised, without worrying about whether the compromised account has any XRP available. This way, you can regain control of the account before you send more XRP to it. -The [lsfPasswordSpent flag](accountroot.html) starts out disabled. It gets enabled when you send a SetRegularKey transaction signed by the master key pair. It gets disabled again when the account receives a [Payment](payment.html) of XRP. +The [`lsfPasswordSpent` flag](accountroot.html) starts out disabled. It gets enabled when you send a SetRegularKey transaction signed by the master key pair. It gets disabled again when the account receives a [Payment](payment.html) of XRP. When the [FeeEscalation amendment][] is enabled, `rippled` prioritizes key reset transactions above other transactions even though the nominal transaction cost of a key reset transaction is zero. diff --git a/content/concepts/payment-types/checks.md b/content/concepts/payment-types/checks.md index e6f383b783..b548ea1f63 100644 --- a/content/concepts/payment-types/checks.md +++ b/content/concepts/payment-types/checks.md @@ -29,7 +29,7 @@ Checks potentially enable many other use cases. Ripple encourages the community ### Use Case: Payment Authorization -**Problem:** To comply with regulations like [BSA, KYC, AML, and CFT](become-an-xrp-ledger-gateway.html#gateway-compliance), financial institutions must provide documentation about the source of funds they receive. Such regulations seek to prevent the illicit transfer of funds by requiring institutions to disclose the source and destination of all payments processed by the institution. Because of the nature of the XRP Ledger, anyone could potentially send XRP (and, under the right circumstances, issued currencies) to an institution's account on the XRP Ledger. Dealing with such unwanted payments adds significant cost and time delays to these institutions' compliance departments, including potential fines or penalties. +**Problem:** To comply with regulations like [BSA, KYC, AML, and CFT](become-an-xrp-ledger-gateway.html#gateway-compliance), financial institutions must provide documentation about the source of funds they receive. Such regulations seek to prevent the illicit transfer of funds by requiring institutions to disclose the source and destination of all payments processed by the institution. Because of the nature of the XRP Ledger, anyone could potentially send XRP (and, under the right circumstances, issued currencies) to an institution's account on the XRP Ledger. Dealing with such unwanted payments adds significant cost and time delays to these institutions' compliance departments, including potential fines or penalties. **Solution:** Institutions can enable [Deposit Authorization](depositauth.html) on their XRP Ledger accounts by [setting the `asfDepositAuth` flag in an `AccountSet` transaction](accountset.html). This makes the account unable to receive Payment transactions. Accounts with Deposit Authorization enabled can only receive funds through Escrow, Payment Channels, or Checks. Checks are the most straightforward, familiar, and flexible way to transfer funds if Deposit Authorization is enabled. @@ -72,6 +72,7 @@ All Checks start the same way, so **Steps 1 and 2** are the same. **Step 4a:** After a Check expires, anyone may cancel it by submitting a [CheckCancel][] transaction. That transaction removes the Check from the ledger. + ## Availability of Checks diff --git a/content/concepts/payment-types/direct-xrp-payments.md b/content/concepts/payment-types/direct-xrp-payments.md index 5b20c9e870..2beb7c6ce6 100644 --- a/content/concepts/payment-types/direct-xrp-payments.md +++ b/content/concepts/payment-types/direct-xrp-payments.md @@ -15,7 +15,7 @@ Generally, any address in the XRP Ledger can send XRP directly to any other addr } ``` -These transaction instructions mean: Send a payment from rf1Bi... to ra5nK... delivering exactly 13 XRP. If the transaction is successfully processed, it does exactly that. Since it usually takes about 4 seconds for each new ledger version to become [validated](consensus.html), a successful transaction can be created, submitted, executed, and have a final outcome in 8 seconds or less, even if gets queued for the ledger version after the current in-progress one. +These transaction instructions mean: Send a payment from `rf1Bi...` to `ra5nK...` delivering exactly 13 XRP. If the transaction is successfully processed, it does exactly that. Since it usually takes about 4 seconds for each new ledger version to become [validated](consensus.html), a successful transaction can be created, submitted, executed, and have a final outcome in 8 seconds or less, even if gets queued for the ledger version after the current in-progress one. **Caution:** The [Payment transaction type][Payment] can also be used for some more specialized kinds of payments, including [cross-currency payments](cross-currency-payments.html) and [partial payments](partial-payments.html). In the case of partial payments, it is possible that the `Amount` shows a large amount of XRP even if the transaction only delivered a very small amount. See [partial payments exploit](partial-payments.html#partial-payments-exploit) for how to avoid crediting a customer for the wrong amount. @@ -52,7 +52,7 @@ From a relatively high level, the XRP Ledger's transaction processing engine app 2. It checks whether the receiving address is a funded account. - - If the receiving address is funded, it checks whether the receiving address has any limitations on receiving payments, such as [DepositAuth](depositauth.html) or [RequireDest](source-and-destination-tags.html#requiring-tags). If the payment does not meet any such limitations, the payment fails. + - If the receiving address is funded, it checks whether the receiving address has any limitations on receiving payments, such as [Deposit Authorization](depositauth.html) or [`RequireDest`](source-and-destination-tags.html#requiring-tags). If the payment does not meet any such limitations, the payment fails. - If the receiving address is not funded, it checks whether the payment would deliver enough XRP to meet the minimum [account reserve](reserves.html). If not, the payment fails. 3. It debits the sending account by an amount of XRP specified by the `Amount` field plus the XRP to be destroyed for the [transaction cost](transaction-cost.html) and credits the receiving account for the same amount. diff --git a/content/concepts/payment-types/escrow.md b/content/concepts/payment-types/escrow.md index fdbf503e53..cba02e290e 100644 --- a/content/concepts/payment-types/escrow.md +++ b/content/concepts/payment-types/escrow.md @@ -26,6 +26,9 @@ All escrows start the same way, so **Steps 1 and 2** are the same as in the succ **Step 4a:** The sender, or any other XRP Ledger address, sends an [EscrowCancel transaction][] to cancel the expired escrow. This destroys the [Escrow object](escrow-object.html) in the ledger and returns the XRP to the sender. + + + ## Limitations Escrow is designed as a feature to enable the XRP Ledger to be used in the [Interledger Protocol][] and with other smart contracts. The current version has a modest scope to avoid complexity. @@ -95,7 +98,7 @@ The Escrow feature takes this idea further by replacing the third party with an Fully automated escrow, backed by the integrity of the XRP Ledger itself, solves important problems for Ripple, and we think there are many other use cases that escrow enables. Ripple encourages the industry to find new and unique ways to put escrow to use. -### Use Case: Time-based Lockup +### Use Case: Time-based Lock-Up **Background:** Ripple holds a large amount of the total XRP, which it sells methodically as a way to fund and incentivize the healthy development of the XRP Ledger and related technologies. At the same time, owning such a large chunk of XRP causes problems for the company, such as: @@ -133,7 +136,7 @@ For more information about Escrow in the XRP Ledger, see the following: For more information on Interledger and how conditional transfers enable secure payments across multiple ledgers, see [Interledger Architecture](https://interledger.org/rfcs/0001-interledger-architecture/). -For more information on Ripple's 55-Billion XRP Lockup, see [Ripple's Insights Blog](https://ripple.com/insights/ripple-to-place-55-billion-xrp-in-escrow-to-ensure-certainty-into-total-xrp-supply/). +For more information on Ripple's 55-billion XRP lock-up, see [Ripple's Insights Blog](https://ripple.com/insights/ripple-to-place-55-billion-xrp-in-escrow-to-ensure-certainty-into-total-xrp-supply/). {% include '_snippets/rippled-api-links.md' %} diff --git a/content/concepts/payment-types/partial-payments.md b/content/concepts/payment-types/partial-payments.md index 484e37750f..1c38def8d1 100644 --- a/content/concepts/payment-types/partial-payments.md +++ b/content/concepts/payment-types/partial-payments.md @@ -1,6 +1,6 @@ # Partial Payments -In the default case, the `Amount` field of a [Payment transaction][] in the XRP Ledger specifies the exact amount to deliver, after charging for exchange rates and [transfer fees](transfer-fees.html). The "Partial Payment" flag ([**tfPartialPayment**](payment.html#payment-flags)) allows a payment to succeed by reducing the amount received instead of increasing the amount sent. Partial payments are useful for [returning payments](become-an-xrp-ledger-gateway.html#bouncing-payments) without incurring additional costs to oneself. +In the default case, the `Amount` field of a [Payment transaction][] in the XRP Ledger specifies the exact amount to deliver, after charging for exchange rates and [transfer fees](transfer-fees.html). The "Partial Payment" flag ([`tfPartialPayment`](payment.html#payment-flags)) allows a payment to succeed by reducing the amount received instead of increasing the amount sent. Partial payments are useful for [returning payments](become-an-xrp-ledger-gateway.html#bouncing-payments) without incurring additional costs to oneself. The amount of XRP used for the [transaction cost](transaction-cost.html) is always deducted from the sender’s account, regardless of the type of transaction. @@ -51,7 +51,7 @@ The delivered amount is **not available** for transactions that meet **both** of - Is a partial payment - Is included in a validated ledger before 2014-01-20 -If both conditions are true, then `delivered_amount` contains the string value `unavailable` instead of an actual amount. If this happens, you can only determine the actual delivered amount by reading the AffectedNodes in the transaction's metadata. If the transaction delivered an issued currency and the `issuer` of the `Amount` is the same account as the `Destination` address, the delivered amount may be divided among multiple `AffectedNodes` members representing trust lines to different counterparties. +If both conditions are true, then `delivered_amount` contains the string value `unavailable` instead of an actual amount. If this happens, you can only determine the actual delivered amount by reading the `AffectedNodes` in the transaction's metadata. If the transaction delivered an issued currency and the `issuer` of the `Amount` is the same account as the `Destination` address, the delivered amount may be divided among multiple `AffectedNodes` members representing trust lines to different counterparties. You can find the `delivered_amount` field in the following places: diff --git a/content/concepts/payment-types/payment-channels.md b/content/concepts/payment-types/payment-channels.md index f080764c30..cb96e37be1 100644 --- a/content/concepts/payment-types/payment-channels.md +++ b/content/concepts/payment-types/payment-channels.md @@ -2,9 +2,9 @@ Payment Channels are an advanced feature for sending "asynchronous" XRP payments that can be divided into very small increments and settled later. -The XRP for a payment channel is set aside for a given time period. The sender creates _Claims_ against the channel, which the recipient verifies without sending an XRP Ledger transaction or waiting for a new ledger version to be approved by [consensus](consensus.html). (This is an _asychronous_ process because it happens separate from the usual pattern of getting transactions approved by consensus.) At any time, the recipient can _redeem_ a Claim to receive an amount of XRP authorized by that Claim. Settling a Claim like this uses a standard XRP Ledger transaction, as part of the usual consensus process. This single transaction can encompass any number of transactions guaranteed by smaller Claims. +The XRP for a payment channel is set aside for a given time period. The sender creates _Claims_ against the channel, which the recipient verifies without sending an XRP Ledger transaction or waiting for a new ledger version to be approved by [consensus](consensus.html). (This is an _asynchronous_ process because it happens separate from the usual pattern of getting transactions approved by consensus.) At any time, the recipient can _redeem_ a Claim to receive an amount of XRP authorized by that Claim. Settling a Claim like this uses a standard XRP Ledger transaction, as part of the usual consensus process. This single transaction can encompass any number of transactions guaranteed by smaller Claims. -Because Claims can be verified individually but settled in bulk later, payment channels make it possible to conduct transactions at a rate only limited by the participants' ability to create and verify the digital signatures of those Claims. This limit is primarily based the speed of the participants' hardware and the complexity of the signature algorithms. For maximum speed, use Ed25519 signatures, which are faster than the XRP Ledger's default secp256k1 ECSDA signatures. Research has [demonstrated the ability to create over Ed25519 100,000 signatures per second and to verify over 70,000 per second](https://ed25519.cr.yp.to/ed25519-20110926.pdf) on commodity hardware in 2011. +Because Claims can be verified individually but settled in bulk later, payment channels make it possible to conduct transactions at a rate only limited by the participants' ability to create and verify the digital signatures of those Claims. This limit is primarily based the speed of the participants' hardware and the complexity of the signature algorithms. For maximum speed, use Ed25519 signatures, which are faster than the XRP Ledger's default secp256k1 ECDSA signatures. Research has [demonstrated the ability to create over Ed25519 100,000 signatures per second and to verify over 70,000 per second](https://ed25519.cr.yp.to/ed25519-20110926.pdf) on commodity hardware in 2011. ## Why Use Payment Channels diff --git a/content/references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/logrotate.md b/content/references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/logrotate.md index 1eb1ad167c..f77e4abd97 100644 --- a/content/references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/logrotate.md +++ b/content/references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/logrotate.md @@ -3,7 +3,7 @@ The `logrotate` command closes and reopens the log file. This is intended to help with log rotation on Linux file systems. -Most Linux systems come preinstalled with a [`logrotate`](https://linux.die.net/man/8/logrotate) program, which is separate from this command. Application specific log rotation scripts are placed in `/etc/logrotate.d` +Most Linux systems come pre-installed with a [`logrotate`](https://linux.die.net/man/8/logrotate) program, which is separate from this command. Application specific log rotation scripts are placed in `/etc/logrotate.d` The following script is a sample that can be created as `/etc/logrotate.d/rippled` diff --git a/content/references/rippled-api/ledger-data-formats/ledger-header.md b/content/references/rippled-api/ledger-data-formats/ledger-header.md index f4976e1d3b..503d3759f0 100644 --- a/content/references/rippled-api/ledger-data-formats/ledger-header.md +++ b/content/references/rippled-api/ledger-data-formats/ledger-header.md @@ -24,7 +24,7 @@ Every ledger version has a unique header that describes the contents. You can lo ## Close Flags -The ledger has only one flag defined for closeFlags: **sLCF_NoConsensusTime** (value `1`). If this flag is enabled, it means that validators had different close times for the ledger, but built otherwise the same ledger, so they declared consensus while "agreeing to disagree" on the close time. In this case, the consensus ledger version contains a `close_time` value that is 1 second after that of the previous ledger. (In this case, there is no official close time, but the actual real-world close time is probably 3-6 seconds later than the specified `close_time`.) +The ledger has only one flag defined for `closeFlags`: **`sLCF_NoConsensusTime`** (value `1`). If this flag is enabled, it means that validators had different close times for the ledger, but built otherwise the same ledger, so they declared consensus while "agreeing to disagree" on the close time. In this case, the consensus ledger version contains a `close_time` value that is 1 second after that of the previous ledger. (In this case, there is no official close time, but the actual real-world close time is probably 3-6 seconds later than the specified `close_time`.) The `closeFlags` field is not included in any JSON representations of a ledger, but is included in the binary representation of a ledger, and is one of the fields that determine the ledger's hash. diff --git a/content/references/rippled-api/ledger-data-formats/ledger-object-types/accountroot.md b/content/references/rippled-api/ledger-data-formats/ledger-object-types/accountroot.md index cceb8bba24..e166548742 100644 --- a/content/references/rippled-api/ledger-data-formats/ledger-object-types/accountroot.md +++ b/content/references/rippled-api/ledger-data-formats/ledger-object-types/accountroot.md @@ -31,17 +31,17 @@ The `AccountRoot` object has the following fields: | Field | JSON Type | [Internal Type][] | Description | |:------------------------------|:----------|:------------------|:-------------| | `LedgerEntryType` | String | UInt16 | The value `0x0061`, mapped to the string `AccountRoot`, indicates that this is an AccountRoot object. | -| `Account` | String | AccountID | The identifying address of this account, such as rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn. | +| `Account` | String | AccountID | The identifying (classic) address of this [account](accounts.html). | | `Balance` | String | Amount | The account's current [XRP balance in drops][XRP, in drops], represented as a string. | | [`Flags`](#accountroot-flags) | Number | UInt32 | A bit-map of boolean flags enabled for this account. | | `OwnerCount` | Number | UInt32 | The number of objects this account owns in the ledger, which contributes to its owner reserve. | | `PreviousTxnID` | String | Hash256 | The identifying hash of the transaction that most recently modified this object. | | `PreviousTxnLgrSeq` | Number | UInt32 | The [index of the ledger][Ledger Index] that contains the transaction that most recently modified this object. | | `Sequence` | Number | UInt32 | The sequence number of the next valid transaction for this account. (Each account starts with Sequence = 1 and increases each time a transaction is made.) | -| `AccountTxnID` | String | Hash256 | _(Optional)_ The identifying hash of the transaction most recently sent by this account. This field must be enabled to use the [AccountTxnID transaction field](transaction-common-fields.html#accounttxnid). To enable it, send an [AccountSet transaction with the asfAccountTxnID flag enabled](accountset.html#accountset-flags). | -| `Domain` | String | VariableLength | _(Optional)_ A domain associated with this account. In JSON, this is the hexadecimal for the ASCII representation of the domain. | +| `AccountTxnID` | String | Hash256 | _(Optional)_ The identifying hash of the transaction most recently sent by this account. This field must be enabled to use the [`AccountTxnID` transaction field](transaction-common-fields.html#accounttxnid). To enable it, send an [AccountSet transaction with the `asfAccountTxnID` flag enabled](accountset.html#accountset-flags). | +| `Domain` | String | Blob | _(Optional)_ A domain associated with this account. In JSON, this is the hexadecimal for the ASCII representation of the domain. | | `EmailHash` | String | Hash128 | _(Optional)_ The md5 hash of an email address. Clients can use this to look up an avatar through services such as [Gravatar](https://en.gravatar.com/). | -| `MessageKey` | String | VariableLength | _(Optional)_ A public key that may be used to send encrypted messages to this account. In JSON, uses hexadecimal. No more than 33 bytes. | +| `MessageKey` | String | Blob | _(Optional)_ A public key that may be used to send encrypted messages to this account. In JSON, uses hexadecimal. No more than 33 bytes. | | `RegularKey` | String | AccountID | _(Optional)_ The address of a [key pair](cryptographic-keys.html) that can be used to sign transactions for this account instead of the master key. Use a [SetRegularKey transaction][] to change this value. | | `TickSize` | Number | UInt8 | _(Optional)_ How many significant digits to use for exchange rates of Offers involving currencies issued by this address. Valid values are `3` to `15`, inclusive. _(Added by the [TickSize amendment][].)_ | | `TransferRate` | Number | UInt32 | _(Optional)_ A [transfer fee](https://ripple.com/knowledge_center/transfer-fees/) to charge other users for sending currency issued by this account to each other. | @@ -50,21 +50,21 @@ The `AccountRoot` object has the following fields: ## AccountRoot Flags -There are several options which can be either enabled or disabled for an account. These options can be changed with an [AccountSet transaction][]. In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with _lsf_. +There are several options which can be either enabled or disabled for an account. These options can be changed with an [AccountSet transaction][]. In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with **`lsf`**. AccountRoot objects can have the following flag values: -| Flag Name | Hex Value | Decimal Value | Description | Corresponding [AccountSet Flag](accountset.html#accountset-flags) | -|-----------|-----------|---------------|-------------|-------------------------------| -| lsfDefaultRipple | 0x00800000 | 8388608 | Enable [rippling](rippling.html) on this addresses's trust lines by default. Required for issuing addresses; discouraged for others. | asfDefaultRipple | -| lsfDepositAuth | 0x01000000 | 16777216 | This account can only receive funds from transactions it sends, and from [preauthorized](depositauth.html#preauthorization) accounts. (It has [DepositAuth](depositauth.html) enabled.) | asfDepositAuth | -| lsfDisableMaster | 0x00100000 | 1048576 | Disallows use of the master key to sign transactions for this account. | asfDisableMaster | -| lsfDisallowXRP | 0x00080000 | 524288 | Client applications should not send XRP to this account. Not enforced by `rippled`. | asfDisallowXRP | -| lsfGlobalFreeze | 0x00400000 | 4194304 | All assets issued by this address are frozen. | asfGlobalFreeze | -| lsfNoFreeze | 0x00200000 | 2097152 | This address cannot freeze trust lines connected to it. Once enabled, cannot be disabled. | asfNoFreeze | -| lsfPasswordSpent | 0x00010000 | 65536 | The account has used its free SetRegularKey transaction. | (None) | -| lsfRequireAuth | 0x00040000 | 262144 | This account must individually approve other users for those users to hold this account's issuances. | asfRequireAuth | -| lsfRequireDestTag | 0x00020000 | 131072 | Requires incoming payments to specify a Destination Tag. | asfRequireDest | +| Flag Name | Hex Value | Decimal Value | Corresponding [AccountSet Flag](accountset.html#accountset-flags) | Description | +|---------------------|--------------|---------------|--------------------|----| +| `lsfDefaultRipple` | `0x00800000` | 8388608 | `asfDefaultRipple` | Enable [rippling](rippling.html) on this addresses's trust lines by default. Required for issuing addresses; discouraged for others. | +| `lsfDepositAuth` | `0x01000000` | 16777216 | `asfDepositAuth` | This account can only receive funds from transactions it sends, and from [preauthorized](depositauth.html#preauthorization) accounts. (It has [DepositAuth](depositauth.html) enabled.) | +| `lsfDisableMaster` | `0x00100000` | 1048576 | `asfDisableMaster` | Disallows use of the master key to sign transactions for this account. | +| `lsfDisallowXRP` | `0x00080000` | 524288 | `asfDisallowXRP` | Client applications should not send XRP to this account. Not enforced by `rippled`. | +| `lsfGlobalFreeze` | `0x00400000` | 4194304 | `asfGlobalFreeze` | All assets issued by this address are frozen. | +| `lsfNoFreeze` | `0x00200000` | 2097152 | `asfNoFreeze` | This address cannot freeze trust lines connected to it. Once enabled, cannot be disabled. | +| `lsfPasswordSpent` | `0x00010000` | 65536 | (None) | The account has used its free SetRegularKey transaction. | +| `lsfRequireAuth` | `0x00040000` | 262144 | `asfRequireAuth` | This account must individually approve other users for those users to hold this account's issuances. | +| `lsfRequireDestTag` | `0x00020000` | 131072 | `asfRequireDest` | Requires incoming payments to specify a Destination Tag. | ## AccountRoot ID Format diff --git a/content/references/rippled-api/ledger-data-formats/ledger-object-types/amendments.md b/content/references/rippled-api/ledger-data-formats/ledger-object-types/amendments.md index a4155e6741..1af3d0af79 100644 --- a/content/references/rippled-api/ledger-data-formats/ledger-object-types/amendments.md +++ b/content/references/rippled-api/ledger-data-formats/ledger-object-types/amendments.md @@ -30,9 +30,9 @@ The `Amendments` object type contains a list of [Amendments](amendments.html) th ## {{currentpage.name}} Fields | Name | JSON Type | [Internal Type][] | Description | -|-------------------|-----------|-------------------|-------------| -| `Amendments` | Array | STI_VECTOR256 | _(Optional)_ Array of 256-bit [amendment IDs](amendments.html#about-amendments) for all currently-enabled amendments. If omitted, there are no enabled amendments. | -| `Majorities` | Array | STI_ARRAY | _(Optional)_ Array of objects describing the status of amendments that have majority support but are not yet enabled. If omitted, there are no pending amendments with majority support. | +|-------------------|-----------|-----------|---------------------| +| `Amendments` | Array | Vector256 | _(Optional)_ Array of 256-bit [amendment IDs](amendments.html#about-amendments) for all currently-enabled amendments. If omitted, there are no enabled amendments. | +| `Majorities` | Array | STArray | _(Optional)_ Array of objects describing the status of amendments that have majority support but are not yet enabled. If omitted, there are no pending amendments with majority support. | | `Flags` | Number | UInt32 | A bit-map of boolean flags. No flags are defined for the Amendments object type, so this value is always `0`. | | `LedgerEntryType` | String | UInt16 | The value `0x0066`, mapped to the string `Amendments`, indicates that this object describes the status of amendments to the XRP Ledger. | diff --git a/content/references/rippled-api/ledger-data-formats/ledger-object-types/directorynode.md b/content/references/rippled-api/ledger-data-formats/ledger-object-types/directorynode.md index c2a4a732e6..0768482396 100644 --- a/content/references/rippled-api/ledger-data-formats/ledger-object-types/directorynode.md +++ b/content/references/rippled-api/ledger-data-formats/ledger-object-types/directorynode.md @@ -6,7 +6,7 @@ The `DirectoryNode` object type provides a list of links to other objects in the There are two kinds of Directories: * **Owner directories** list other objects owned by an account, such as `RippleState` or `Offer` objects. -* **Offer directories** list the offers available in the distributed exchange. A single Offer directory contains all the offers that have the same exchange rate for the same issuances. +* **Offer directories** list the offers available in the distributed exchange. A single Offer directory contains all the offers that have the same exchange rate for the same issued currency. ## Example {{currentpage.name}} JSON @@ -61,10 +61,10 @@ There are two kinds of Directories: | `IndexPrevious` | Number | UInt64 | (Optional) If this Directory consists of multiple pages, this ID links to the previous object in the chain, wrapping around at the beginning. | | `Owner` | String | AccountID | (Owner Directories only) The address of the account that owns the objects in this directory. | | `ExchangeRate` | Number | UInt64 | (Offer Directories only) **DEPRECATED**. Do not use. | -| `TakerPaysCurrency` | String | Hash160 | (Offer Directories only) The currency code of the TakerPays amount from the offers in this directory. | -| `TakerPaysIssuer` | String | Hash160 | (Offer Directories only) The issuer of the TakerPays amount from the offers in this directory. | -| `TakerGetsCurrency` | String | Hash160 | (Offer Directories only) The currency code of the TakerGets amount from the offers in this directory. | -| `TakerGetsIssuer` | String | Hash160 | (Offer Directories only) The issuer of the TakerGets amount from the offers in this directory. | +| `TakerPaysCurrency` | String | Hash160 | (Offer Directories only) The currency code of the `TakerPays` amount from the offers in this directory. | +| `TakerPaysIssuer` | String | Hash160 | (Offer Directories only) The issuer of the `TakerPays` amount from the offers in this directory. | +| `TakerGetsCurrency` | String | Hash160 | (Offer Directories only) The currency code of the `TakerGets` amount from the offers in this directory. | +| `TakerGetsIssuer` | String | Hash160 | (Offer Directories only) The issuer of the `TakerGets` amount from the offers in this directory. | ## Directory ID Formats @@ -87,7 +87,7 @@ There are three different formulas for creating the ID of a DirectoryNode, depen * The AccountID from the `TakerPaysIssuer` * The AccountID from the `TakerGetsIssuer` -The lower 64 bits of an Offer Directory's ID represent the TakerPays amount divided by TakerGets amount from the offer(s) in that directory as a 64-bit number in the XRP Ledger's internal amount format. +The lower 64 bits of an Offer Directory's ID represent the `TakerPays` amount divided by `TakerGets` amount from the offer(s) in that directory as a 64-bit number in the XRP Ledger's internal amount format. **If the DirectoryNode is not the first page in the Directory** (regardless of whether it is an Owner Directory or an Offer Directory), then it has an ID that is the [SHA-512Half][] of the following values, concatenated in order: diff --git a/content/references/rippled-api/ledger-data-formats/ledger-object-types/escrow.md b/content/references/rippled-api/ledger-data-formats/ledger-object-types/escrow.md index 3ce1dc1f02..427ec34a92 100644 --- a/content/references/rippled-api/ledger-data-formats/ledger-object-types/escrow.md +++ b/content/references/rippled-api/ledger-data-formats/ledger-object-types/escrow.md @@ -36,22 +36,22 @@ An `Escrow` object is associated with two addresses: An `Escrow` object has the following fields: -| Name | JSON Type | [Internal Type][] | Description | -|-------------------|-----------|---------------|-------------| +| Name | JSON Type | [Internal Type][] | Description | +|---------------------|-----------|-----------|--------------------------------| | `LedgerEntryType` | String | UInt16 | The value `0x0075`, mapped to the string `Escrow`, indicates that this object is an `Escrow` object. | -| `Account` | String | AccountID | The address of the owner (sender) of this held payment. This is the account that provided the XRP, and gets it back if the held payment is canceled. | -| `Destination` | String | AccountID | The destination address where the XRP is paid if the held payment is successful. | -| `Amount` | String | Amount | The amount of XRP, in drops, to be delivered by the held payment. | -| `Condition` | String | VariableLength | _(Optional)_ A [PREIMAGE-SHA-256 crypto-condition](https://tools.ietf.org/html/draft-thomas-crypto-conditions-02#section-8.1), as hexadecimal. If present, the [EscrowFinish transaction][] must contain a fulfillment that satisfies this condition. | -| `CancelAfter` | Number | UInt32 | _(Optional)_ The held payment can be canceled if and only if this field is present _and_ the time it specifies has passed. Specifically, this is specified as [seconds since the Ripple Epoch][] and it "has passed" if it's earlier than the close time of the previous validated ledger. | -| `FinishAfter` | Number | UInt32 | _(Optional)_ The time, in [seconds since the Ripple Epoch][], after which this held payment can be finished. Any [EscrowFinish transaction][] before this time fails. (Specifically, this is compared with the close time of the previous validated ledger.) | -| `Flags` | Number | UInt32 | A bit-map of boolean flags. No flags are defined for the Escrow type, so this value is always `0`. | -| `SourceTag` | Number | UInt32 | _(Optional)_ An arbitrary tag to further specify the source for this held payment, such as a hosted recipient at the owner's address. | -| `DestinationTag` | Number | UInt32 | _(Optional)_ An arbitrary tag to further specify the destination for this held payment, such as a hosted recipient at the destination address. | +| `Account` | String | AccountID | The address of the owner (sender) of this held payment. This is the account that provided the XRP, and gets it back if the held payment is canceled. | +| `Destination` | String | AccountID | The destination address where the XRP is paid if the held payment is successful. | +| `Amount` | String | Amount | The amount of XRP, in drops, to be delivered by the held payment. | +| `Condition` | String | Blob | _(Optional)_ A [PREIMAGE-SHA-256 crypto-condition](https://tools.ietf.org/html/draft-thomas-crypto-conditions-02#section-8.1), as hexadecimal. If present, the [EscrowFinish transaction][] must contain a fulfillment that satisfies this condition. | +| `CancelAfter` | Number | UInt32 | _(Optional)_ The held payment can be canceled if and only if this field is present _and_ the time it specifies has passed. Specifically, this is specified as [seconds since the Ripple Epoch][] and it "has passed" if it's earlier than the close time of the previous validated ledger. | +| `FinishAfter` | Number | UInt32 | _(Optional)_ The time, in [seconds since the Ripple Epoch][], after which this held payment can be finished. Any [EscrowFinish transaction][] before this time fails. (Specifically, this is compared with the close time of the previous validated ledger.) | +| `Flags` | Number | UInt32 | A bit-map of boolean flags. No flags are defined for the Escrow type, so this value is always `0`. | +| `SourceTag` | Number | UInt32 | _(Optional)_ An arbitrary tag to further specify the source for this held payment, such as a hosted recipient at the owner's address. | +| `DestinationTag` | Number | UInt32 | _(Optional)_ An arbitrary tag to further specify the destination for this held payment, such as a hosted recipient at the destination address. | | `OwnerNode` | String | UInt64 | A hint indicating which page of the owner directory links to this object, in case the directory consists of multiple pages. **Note:** The object does not contain a direct link to the owner directory containing it, since that value can be derived from the `Account`. | | `DestinationNode` | String | UInt64 | _(Optional)_ A hint indicating which page of the destination's owner directory links to this object, in case the directory consists of multiple pages. Omitted on escrows created before enabling the [fix1523 amendment][]. | -| `PreviousTxnID` | String | Hash256 | The identifying hash of the transaction that most recently modified this object. | -| `PreviousTxnLgrSeq` | Number | UInt32 | The [index of the ledger][Ledger Index] that contains the transaction that most recently modified this object. | +| `PreviousTxnID` | String | Hash256 | The identifying hash of the transaction that most recently modified this object. | +| `PreviousTxnLgrSeq` | Number | UInt32 | The [index of the ledger][Ledger Index] that contains the transaction that most recently modified this object. | ## Escrow ID Format diff --git a/content/references/rippled-api/ledger-data-formats/ledger-object-types/ledgerhashes.md b/content/references/rippled-api/ledger-data-formats/ledger-object-types/ledgerhashes.md index 836ad07079..0d1185be62 100644 --- a/content/references/rippled-api/ledger-data-formats/ledger-object-types/ledgerhashes.md +++ b/content/references/rippled-api/ledger-data-formats/ledger-object-types/ledgerhashes.md @@ -39,8 +39,8 @@ A `LedgerHashes` object has the following fields: | `LedgerEntryType` | String | UInt16 | The value `0x0068`, mapped to the string `LedgerHashes`, indicates that this object is a list of ledger hashes. | | `FirstLedgerSequence` | Number | UInt32 | **DEPRECATED** Do not use. (The "recent hashes" object of the production XRP Ledger has the value `2` in this field as a result of a previous `rippled` software. That value gets carried forward as the "recent hashes" object is updated. New "previous history" objects do not have this field, nor do "recent hashes" objects in [parallel networks](parallel-networks.html) started with more recent versions of `rippled`.) | | `LastLedgerSequence` | Number | UInt32 | The [Ledger Index][] of the last entry in this object's `Hashes` array. | -| `Hashes` | Array of Strings | STI_VECTOR256 | An array of up to 256 ledger hashes. The contents depend on which sub-type of `LedgerHashes` object this is. | -| `Flags` | Number | UInt32 | A bit-map of boolean flags for this object. No flags are defined for this type. | +| `Hashes` | Array of Strings | Vector256 | An array of up to 256 ledger hashes. The contents depend on which sub-type of `LedgerHashes` object this is. | +| `Flags` | Number | UInt32 | A bit-map of boolean flags for this object. No flags are defined for this type. | ## Recent History LedgerHashes diff --git a/content/references/rippled-api/ledger-data-formats/ledger-object-types/offer.md b/content/references/rippled-api/ledger-data-formats/ledger-object-types/offer.md index bf419563b8..879b769e04 100644 --- a/content/references/rippled-api/ledger-data-formats/ledger-object-types/offer.md +++ b/content/references/rippled-api/ledger-data-formats/ledger-object-types/offer.md @@ -51,14 +51,14 @@ An `Offer` object has the following fields: ## Offer Flags -There are several options which can be either enabled or disabled when an [OfferCreate transaction][] creates an offer object. In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with _lsf_. +There are several options which can be either enabled or disabled when an [OfferCreate transaction][] creates an offer object. In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with **`lsf`**. `Offer` objects can have the following flag values: -| Flag Name | Hex Value | Decimal Value | Description | Corresponding [OfferCreate Flag](offercreate.html#offercreate-flags) | -|-----------|-----------|---------------|-------------|------------------------| -| lsfPassive | 0x00010000 | 65536 | The object was placed as a passive offer. This has no effect on the object in the ledger. | tfPassive | -| lsfSell | 0x00020000 | 131072 | The object was placed as a sell offer. This has no effect on the object in the ledger (because tfSell only matters if you get a better rate than you asked for, which cannot happen after the object enters the ledger). | tfSell | +| Flag Name | Hex Value | Decimal Value | Corresponding [OfferCreate Flag](offercreate.html#offercreate-flags) | Description | +|--------------|--------------|---------------|-------------|------------------------| +| `lsfPassive` | `0x00010000` | 65536 | `tfPassive` | The object was placed as a passive offer. This has no effect on the object in the ledger. | +| `lsfSell` | `0x00020000` | 131072 | `tfSell` | The object was placed as a sell offer. This has no effect on the object in the ledger (because `tfSell` only matters if you get a better rate than you asked for, which cannot happen after the object enters the ledger). | ## Offer ID Format diff --git a/content/references/rippled-api/ledger-data-formats/ledger-object-types/paychannel.md b/content/references/rippled-api/ledger-data-formats/ledger-object-types/paychannel.md index 3cac47dfe7..a4c897a2da 100644 --- a/content/references/rippled-api/ledger-data-formats/ledger-object-types/paychannel.md +++ b/content/references/rippled-api/ledger-data-formats/ledger-object-types/paychannel.md @@ -45,7 +45,7 @@ A `PayChannel` object has the following fields: | `Destination` | String | AccountID | The destination address for this payment channel. While the payment channel is open, this address is the only one that can receive XRP from the channel. This comes from the `Destination` field of the transaction that created the channel. | | `Amount` | String | Amount | Total [XRP, in drops][], that has been allocated to this channel. This includes XRP that has been paid to the destination address. This is initially set by the transaction that created the channel and can be increased if the source address sends a PaymentChannelFund transaction. | | `Balance` | String | Amount | Total [XRP, in drops][], already paid out by the channel. The difference between this value and the `Amount` field is how much XRP can still be paid to the destination address with PaymentChannelClaim transactions. If the channel closes, the remaining difference is returned to the source address. | -| `PublicKey` | String | PubKey | Public key, in hexadecimal, of the key pair that can be used to sign claims against this channel. This can be any valid secp256k1 or Ed25519 public key. This is set by the transaction that created the channel and must match the public key used in claims against the channel. The channel source address can also send XRP from this channel to the destination without signed claims. | +| `PublicKey` | String | Blob | Public key, in hexadecimal, of the key pair that can be used to sign claims against this channel. This can be any valid secp256k1 or Ed25519 public key. This is set by the transaction that created the channel and must match the public key used in claims against the channel. The channel source address can also send XRP from this channel to the destination without signed claims. | | `SettleDelay` | Number | UInt32 | Number of seconds the source address must wait to close the channel if it still has any XRP in it. Smaller values mean that the destination address has less time to redeem any outstanding claims after the source address requests to close the channel. Can be any value that fits in a 32-bit unsigned integer (0 to 2^32-1). This is set by the transaction that creates the channel. | | `OwnerNode` | String | UInt64 | A hint indicating which page of the source address's owner directory links to this object, in case the directory consists of multiple pages. | | `PreviousTxnID` | String | Hash256 | The identifying hash of the transaction that most recently modified this object. | diff --git a/content/references/rippled-api/ledger-data-formats/ledger-object-types/ripplestate.md b/content/references/rippled-api/ledger-data-formats/ledger-object-types/ripplestate.md index d257236800..24adb9b05c 100644 --- a/content/references/rippled-api/ledger-data-formats/ledger-object-types/ripplestate.md +++ b/content/references/rippled-api/ledger-data-formats/ledger-object-types/ripplestate.md @@ -54,27 +54,27 @@ A `RippleState` object has the following fields: | `PreviousTxnLgrSeq` | Number | UInt32 | The [index of the ledger][Ledger Index] that contains the transaction that most recently modified this object. | | `LowNode` | String | UInt64 | (Omitted in some historical ledgers) A hint indicating which page of the low account's owner directory links to this object, in case the directory consists of multiple pages. | | `HighNode` | String | UInt64 | (Omitted in some historical ledgers) A hint indicating which page of the high account's owner directory links to this object, in case the directory consists of multiple pages. | -| `LowQualityIn` | Number | UInt32 | (Optional) The inbound quality set by the low account, as an integer in the implied ratio LowQualityIn:1,000,000,000. The value 0 is equivalent to 1 billion, or face value. | -| `LowQualityOut` | Number | UInt32 | (Optional) The outbound quality set by the low account, as an integer in the implied ratio LowQualityOut:1,000,000,000. The value 0 is equivalent to 1 billion, or face value. | -| `HighQualityIn` | Number | UInt32 | (Optional) The inbound quality set by the high account, as an integer in the implied ratio HighQualityIn:1,000,000,000. The value 0 is equivalent to 1 billion, or face value. | -| `HighQualityOut` | Number | UInt32 | (Optional) The outbound quality set by the high account, as an integer in the implied ratio HighQualityOut:1,000,000,000. The value 0 is equivalent to 1 billion, or face value. | +| `LowQualityIn` | Number | UInt32 | (Optional) The inbound quality set by the low account, as an integer in the implied ratio `LowQualityIn`:1,000,000,000. As a special case, the value 0 is equivalent to 1 billion, or face value. | +| `LowQualityOut` | Number | UInt32 | (Optional) The outbound quality set by the low account, as an integer in the implied ratio `LowQualityOut`:1,000,000,000. As a special case, the value 0 is equivalent to 1 billion, or face value. | +| `HighQualityIn` | Number | UInt32 | (Optional) The inbound quality set by the high account, as an integer in the implied ratio `HighQualityIn`:1,000,000,000. As a special case, the value 0 is equivalent to 1 billion, or face value. | +| `HighQualityOut` | Number | UInt32 | (Optional) The outbound quality set by the high account, as an integer in the implied ratio `HighQualityOut`:1,000,000,000. As a special case, the value 0 is equivalent to 1 billion, or face value. | ## RippleState Flags -There are several options which can be either enabled or disabled for a trust line. These options can be changed with a [TrustSet transaction][]. In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with _lsf_. +There are several options which can be either enabled or disabled for a trust line. These options can be changed with a [TrustSet transaction][]. In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with **`lsf`**. RippleState objects can have the following flag values: -| Flag Name | Hex Value | Decimal Value | Description | Corresponding [TrustSet Flag](trustset.html#trustset-flags) | -|-----------|-----------|---------------|-------------|------------------------| -| lsfLowReserve | 0x00010000 | 65536 | This RippleState object [contributes to the low account's owner reserve](#contributing-to-the-owner-reserve). | (None) | -| lsfHighReserve | 0x00020000 |131072 | This RippleState object [contributes to the high account's owner reserve](#contributing-to-the-owner-reserve). | (None) | -| lsfLowAuth | 0x00040000 | 262144 | The low account has authorized the high account to hold the low account's issuances. | tfSetAuth | -| lsfHighAuth | 0x00080000 | 524288 | The high account has authorized the low account to hold the high account's issuances. | tfSetAuth | -| lsfLowNoRipple | 0x00100000 | 1048576 | The low account [has disabled rippling](rippling.html) from this trust line to other trust lines with the same account's NoRipple flag set. | tfSetNoRipple | -| lsfHighNoRipple | 0x00200000 | 2097152 | The high account [has disabled rippling](rippling.html) from this trust line to other trust lines with the same account's NoRipple flag set. | tfSetNoRipple | -| lsfLowFreeze | 0x00400000 | 4194304 | The low account has frozen the trust line, preventing the high account from transferring the asset. | tfSetFreeze | -| lsfHighFreeze | 0x00800000 | 8388608 | The high account has frozen the trust line, preventing the low account from transferring the asset. | tfSetFreeze | +| Flag Name | Hex Value | Decimal Value | Corresponding [TrustSet Flag](trustset.html#trustset-flags) | Description | +|-------------------|--------------|---------------|-----------------|---------| +| `lsfLowReserve` | `0x00010000` | 65536 | (None) | This RippleState object [contributes to the low account's owner reserve](#contributing-to-the-owner-reserve). | +| `lsfHighReserve` | `0x00020000` | 131072 | (None) | This RippleState object [contributes to the high account's owner reserve](#contributing-to-the-owner-reserve). | +| `lsfLowAuth` | `0x00040000` | 262144 | `tfSetAuth` | The low account has authorized the high account to hold the low account's issued currency. | +| `lsfHighAuth` | `0x00080000` | 524288 | `tfSetAuth` | The high account has authorized the low account to hold the high account's issued currency. | +| `lsfLowNoRipple` | `0x00100000` | 1048576 | `tfSetNoRipple` | The low account [has disabled rippling](rippling.html) from this trust line. | +| `lsfHighNoRipple` | `0x00200000` | 2097152 | `tfSetNoRipple` | The high account [has disabled rippling](rippling.html) from this trust line. | +| `lsfLowFreeze` | `0x00400000` | 4194304 | `tfSetFreeze` | The low account has frozen the trust line, preventing the high account from transferring the asset. | +| `lsfHighFreeze` | `0x00800000` | 8388608 | `tfSetFreeze` | The high account has frozen the trust line, preventing the low account from transferring the asset. | ## Contributing to the Owner Reserve @@ -93,11 +93,11 @@ The values that count towards a trust line's non-default state are as follows: The **lsfLowAuth** and **lsfHighAuth** flags do not count against the default state, because they cannot be disabled. -The default state of the two NoRipple flags depends on the state of the [lsfDefaultRipple flag](accountroot.html#accountroot-flags) in their corresponding AccountRoot objects. If DefaultRipple is disabled (the default), then the default state of the lsfNoRipple flag is _enabled_ for all of an account's trust lines. If an account enables DefaultRipple, then the lsfNoRipple flag is _disabled_ (rippling is enabled) for an account's trust lines by default. +The default state of the two NoRipple flags depends on the state of the [lsfDefaultRipple flag](accountroot.html#accountroot-flags) in their corresponding AccountRoot objects. If `DefaultRipple` is disabled (the default), then the default state of the `lsfNoRipple` flag is _enabled_ for all of an account's trust lines. If an account enables `DefaultRipple`, then the `lsfNoRipple` flag is _disabled_ (rippling is enabled) for an account's trust lines by default. -**Note:** Prior to the introduction of the DefaultRipple flags in `rippled` version 0.27.3 (March 10, 2015), the default state for all trust lines was with both NoRipple flags disabled (rippling enabled). +**Note:** Prior to the introduction of the `DefaultRipple` flags in `rippled` version 0.27.3 (March 10, 2015), the default state for all trust lines was with both No Ripple flags disabled (rippling enabled). -Fortunately, `rippled` uses lazy evaluation to calculate the owner reserve. This means that even if an account changes the default state of all its trust lines by changing the DefaultRipple flag, that account's reserve stays the same initially. If an account modifies a trust line, `rippled` re-evaluates whether that individual trust line is in its default state and should contribute to the owner reserve. +Fortunately, `rippled` uses lazy evaluation to calculate the owner reserve. This means that even if an account changes the default state of all its trust lines by changing the `DefaultRipple` flag, that account's reserve stays the same initially. If an account modifies a trust line, `rippled` re-evaluates whether that individual trust line is in its default state and should contribute to the owner reserve. ## RippleState ID Format diff --git a/content/references/rippled-api/ledger-data-formats/ledger-object-types/signerlist.md b/content/references/rippled-api/ledger-data-formats/ledger-object-types/signerlist.md index ee4926972c..4c3520e019 100644 --- a/content/references/rippled-api/ledger-data-formats/ledger-object-types/signerlist.md +++ b/content/references/rippled-api/ledger-data-formats/ledger-object-types/signerlist.md @@ -3,7 +3,7 @@ _(Added by the [MultiSign amendment][].)_ -The `SignerList` object type represents a list of parties that, as a group, are authorized to sign a transaction in place of an individual account. You can create, replace, or remove a SignerList using a [SignerListSet transaction][]. +The `SignerList` object type represents a list of parties that, as a group, are authorized to sign a transaction in place of an individual account. You can create, replace, or remove a signer list using a [SignerListSet transaction][]. ## Example {{currentpage.name}} JSON @@ -48,24 +48,24 @@ A `SignerList` object has the following fields: | Name | JSON Type | Internal Type | Description | |:--------------------|:----------|:--------------|:---------------------------| | `LedgerEntryType` | String | UInt16 | The value `0x0053`, mapped to the string `SignerList`, indicates that this object is a SignerList object. | -| `Flags` | Number | UInt32 | A bit-map of Boolean flags enabled for this SignerList. For more information, see [SignerList Flags](#signerlist-flags). | +| `Flags` | Number | UInt32 | A bit-map of Boolean flags enabled for this signer list. For more information, see [SignerList Flags](#signerlist-flags). | | `PreviousTxnID` | String | Hash256 | The identifying hash of the transaction that most recently modified this object. | | `PreviousTxnLgrSeq` | Number | UInt32 | The [index of the ledger][Ledger Index] that contains the transaction that most recently modified this object. | | `OwnerNode` | String | UInt64 | A hint indicating which page of the owner directory links to this object, in case the directory consists of multiple pages. | -| `SignerEntries` | Array | Array | An array of SignerEntry objects representing the parties who are part of this signer list. | +| `SignerEntries` | Array | Array | An array of Signer Entry objects representing the parties who are part of this signer list. | | `SignerListID` | Number | UInt32 | An ID for this signer list. Currently always set to `0`. If a future [amendment](amendments.html) allows multiple signer lists for an account, this may change. | | `SignerQuorum` | Number | UInt32 | A target number for signer weights. To produce a valid signature for the owner of this SignerList, the signers must provide valid signatures whose weights sum to this value or more. | The `SignerEntries` may be any combination of funded and unfunded addresses that use either secp256k1 or ed25519 keys. -### SignerEntry Object +### Signer Entry Object -Each member of the `SignerEntries` field is an object that describes that signer in the list. A SignerEntry has the following fields: +Each member of the `SignerEntries` field is an object that describes that signer in the list. A Signer Entry has the following fields: | Name | JSON Type | Internal Type | Description | |:---------------|:----------|:--------------|:--------------------------------| | `Account` | String | AccountID | An XRP Ledger address whose signature contributes to the multi-signature. It does not need to be a funded address in the ledger. | -| `SignerWeight` | Number | UInt16 | The weight of a signature from this signer. A multi-signature is only valid if the sum weight of the signatures provided meets or exceeds the SignerList's `SignerQuorum` value. | +| `SignerWeight` | Number | UInt16 | The weight of a signature from this signer. A multi-signature is only valid if the sum weight of the signatures provided meets or exceeds the signer list's `SignerQuorum` value. | When processing a multi-signed transaction, the server dereferences the `Account` values with respect to the ledger at the time of transaction execution. If the address _does not_ correspond to a funded [AccountRoot object](accountroot.html), then only the master secret associated with that address can be used to produce a valid signature. If the account _does_ exist in the ledger, then it depends on the state of that account. If the account has a Regular Key configured, the Regular Key can be used. The account's master key can only be used if it is not disabled. A multi-signature cannot be used as part of another multi-signature. @@ -75,27 +75,25 @@ _(Added by the [MultiSignReserve amendment][].)_ SignerList objects can have the following flag value: -| Flag Name | Hex Value | Decimal Value | Description | -|:-----------------|:-----------|:--------------|:-------------------------------| -| lsfOneOwnerCount | 0x00010000 | 65536 | If this flag is enabled, this SignerList counts as one item for purposes of the [owner reserve](reserves.html#owner-reserves). Otherwise, this list counts as N+2 items, where N is the number of signers it contains. This flag is automatically enabled if you add or update a signer list after the [MultiSignReserve amendment][] is enabled. | +| Flag Name | Hex Value | Decimal Value | Description | +|:-------------------|:-------------|:--------------|:-------------------------| +| `lsfOneOwnerCount` | `0x00010000` | 65536 | If this flag is enabled, this SignerList counts as one item for purposes of the [owner reserve](reserves.html#owner-reserves). Otherwise, this list counts as N+2 items, where N is the number of signers it contains. This flag is automatically enabled if you add or update a signer list after the [MultiSignReserve amendment][] is enabled. | -## SignerLists and Reserves +## Signer Lists and Reserves -A SignerList contributes to its owner's [reserve requirement](reserves.html). +A signer list contributes to its owner's [reserve requirement](reserves.html). -Without the [MultiSignReserve amendment][], the SignerList itself counts as two objects, and each member of the list counts as one. As a result, the total owner reserve associated with a SignerList is anywhere from 3 times to 10 times the reserve required by a single trust line ([RippleState](ripplestate.html)) or [Offer](offer.html) object in the ledger. +The [MultiSignReserve amendment][] (enabled 2019-04-17) made it so each signer list counts as one object, regardless of how many members it has. As a result, the owner reserve associated with a new signer list is 5 XRP. -With the [MultiSignReserve amendment][] enabled, the SignerList counts as one object, regardless of how many members it has. As a result, the owner reserve associated with a SignerList is 5 XRP, regardless of how many members it has. - -The reserve requirement does not change for SignerLists created before the MultiSignReserve amendment. To take advantage of the new reserve, update the SignerList by sending a [SignerListSet transaction][]. +A signer list created before the [MultiSignReserve amendment][] itself counts as two objects, and each member of the list counts as one. As a result, the total owner reserve associated with the signer list is anywhere from 3 times to 10 times the reserve required by a single trust line ([RippleState](ripplestate.html)) or [Offer](offer.html) object in the ledger. To update a signer list to use the new, reduced reserve, update the signer list by sending a [SignerListSet transaction][]. ## SignerList ID Format -The ID of a SignerList object is the SHA-512Half of the following values, concatenated in order: +The ID of a signer list object is the SHA-512Half of the following values, concatenated in order: * The RippleState space key (`0x0053`) -* The AccountID of the owner of the SignerList -* The SignerListID (currently always `0`) +* The AccountID of the owner of the signer list +* The `SignerListID` (currently always `0`) {% include '_snippets/rippled-api-links.md' %} diff --git a/content/references/rippled-api/public-rippled-methods/account-methods/account_lines.md b/content/references/rippled-api/public-rippled-methods/account-methods/account_lines.md index 9085d6c273..db16206d93 100644 --- a/content/references/rippled-api/public-rippled-methods/account-methods/account_lines.md +++ b/content/references/rippled-api/public-rippled-methods/account-methods/account_lines.md @@ -43,7 +43,7 @@ rippled account_lines [] [] [Try it! >](websocket-api-tool.html#account_lines) -The request accepts the following paramters: +The request accepts the following parameters: | `Field` | Type | Description | |:---------------|:-------------------------------------------|:---------------| diff --git a/content/references/rippled-api/public-rippled-methods/account-methods/noripple_check.md b/content/references/rippled-api/public-rippled-methods/account-methods/noripple_check.md index a09bef72b1..1520407a6b 100644 --- a/content/references/rippled-api/public-rippled-methods/account-methods/noripple_check.md +++ b/content/references/rippled-api/public-rippled-methods/account-methods/noripple_check.md @@ -1,7 +1,7 @@ # 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](rippling.html), compared with the recommended settings. +The `noripple_check` command provides a quick way to check the status of [the `DefaultRipple` field for an account and the No Ripple flag of its trust lines](rippling.html), compared with the recommended settings. ## Request Format An example of the request format: @@ -10,7 +10,7 @@ An example of the request format: *WebSocket* -``` +```json { "id": 0, "command": "noripple_check", @@ -24,7 +24,7 @@ An example of the request format: *JSON-RPC* -``` +```json { "method": "noripple_check", "params": [ diff --git a/content/references/rippled-api/public-rippled-methods/ledger-methods/ledger.md b/content/references/rippled-api/public-rippled-methods/ledger-methods/ledger.md index 065bfb72e0..a9dd374f3f 100644 --- a/content/references/rippled-api/public-rippled-methods/ledger-methods/ledger.md +++ b/content/references/rippled-api/public-rippled-methods/ledger-methods/ledger.md @@ -1,7 +1,7 @@ # ledger [[Source]](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/LedgerHandler.cpp "Source") -Retrieve information about the public ledger. +Retrieve information about the public [ledger](ledgers.html). ## Request Format An example of the request format: @@ -185,7 +185,7 @@ The response follows the [standard format][], with a successful result containin | `ledger` | Object | The complete header data of this ledger. | | `ledger.account_hash` | String | Hash of all account state information in this ledger, as hex | | `ledger.accountState` | Array | (Omitted unless requested) All the [account-state information](ledger-data-formats.html) in this ledger. | -| `ledger.close_flags` | Integer | A bit-map of flags relating to the closing of this ledger. Currently, the ledger has only one flag defined for `close_flags`: **sLCF_NoConsensusTime** (value 1). If this flag is enabled, it means that validators were in conflict regarding the correct close time for the ledger, but build otherwise the same ledger, so they declared consensus while "agreeing to disagree" on the close time. In this case, the consensus ledger contains a `close_time` that is 1 second after that of the previous ledger. (In this case, there is no official close time, but the actual real-world close time is probably 3-6 seconds later than the specified `close_time`.) | +| `ledger.close_flags` | Integer | A bit-map of flags relating to the closing of this ledger. Currently, the ledger has only one flag defined for `close_flags`: **`sLCF_NoConsensusTime`** (value 1). If this flag is enabled, it means that validators were in conflict regarding the correct close time for the ledger, but build otherwise the same ledger, so they declared consensus while "agreeing to disagree" on the close time. In this case, the consensus ledger contains a `close_time` that is 1 second after that of the previous ledger. (In this case, there is no official close time, but the actual real-world close time is probably 3-6 seconds later than the specified `close_time`.) | | `ledger.close_time` | Integer | The time this ledger was closed, in [seconds since the Ripple Epoch][] | | `ledger.close_time_human` | String | The time this ledger was closed, in human-readable format. Always uses the UTC time zone. [Updated in: rippled 1.5.0][] | | `ledger.close_time_resolution` | Integer | Ledger close times are rounded to within this many seconds. | diff --git a/content/references/rippled-api/public-rippled-methods/ledger-methods/ledger_data.md b/content/references/rippled-api/public-rippled-methods/ledger-methods/ledger_data.md index 6003619eba..8fa6c6bdc1 100644 --- a/content/references/rippled-api/public-rippled-methods/ledger-methods/ledger_data.md +++ b/content/references/rippled-api/public-rippled-methods/ledger-methods/ledger_data.md @@ -97,7 +97,7 @@ An example of a successful response: *WebSocket (binary:false)* -``` +```json { "id": 2, "result": { @@ -245,9 +245,9 @@ The format of each object in the `state` array depends on whether `binary` was s | `Field` | Type | Description | |:--------------------|:----------|:-------------------------------------------| -| `data` | String | (Only included if `"binary":true`) Hex representation of the requested data | -| `LedgerEntryType` | String | (Only included if `"binary":false`) String indicating what type of ledger object this object represents. See [ledger data formats](ledger-data-formats.html) for the full list. | -| (Additional fields) | (Various) | (Only included if `"binary":false`) Additional fields describing this object, depending on which LedgerEntryType it is. | +| `data` | String | _(Only included if `"binary":true`)_ Hex representation of the requested data | +| `LedgerEntryType` | String | _(Only included if `"binary":false`)_ String indicating what type of ledger object this object represents. See [ledger object types](ledger-object-types.html) for the full list. | +| (Additional fields) | (Various) | _(Only included if `"binary":false`)_ Additional fields describing this object, depending on which [ledger object type](ledger-object-types.html) it is. | | `index` | String | Unique identifier for this ledger entry, as hex. | ## Possible Errors diff --git a/content/references/rippled-api/public-rippled-methods/path-and-order-book-methods/book_offers.md b/content/references/rippled-api/public-rippled-methods/path-and-order-book-methods/book_offers.md index 637f183787..4b515fd74f 100644 --- a/content/references/rippled-api/public-rippled-methods/path-and-order-book-methods/book_offers.md +++ b/content/references/rippled-api/public-rippled-methods/path-and-order-book-methods/book_offers.md @@ -77,7 +77,7 @@ An example of a successful response: *WebSocket* -``` +```json { "id": 11, "status": "success", @@ -165,7 +165,7 @@ In addition to the standard Offer fields, the following fields may be included i | `Field` | Type | Description | |:--------------------|:---------------------------------|:--------------------| -| `owner_funds` | String | Amount of the TakerGets currency the side placing the offer has available to be traded. (XRP is represented as drops; any other currency is represented as a decimal value.) If a trader has multiple offers in the same book, only the highest-ranked offer includes this field. | +| `owner_funds` | String | Amount of the `TakerGets` currency the side placing the offer has available to be traded. (XRP is represented as drops; any other currency is represented as a decimal value.) If a trader has multiple offers in the same book, only the highest-ranked offer includes this field. | | `taker_gets_funded` | String (XRP) or Object (non-XRP) | (Only included in partially-funded offers) The maximum amount of currency that the taker can get, given the funding status of the offer. | | `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` | String | 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.) | diff --git a/content/references/rippled-api/public-rippled-methods/path-and-order-book-methods/path_find.md b/content/references/rippled-api/public-rippled-methods/path-and-order-book-methods/path_find.md index c2de39862b..a15a9282df 100644 --- a/content/references/rippled-api/public-rippled-methods/path-and-order-book-methods/path_find.md +++ b/content/references/rippled-api/public-rippled-methods/path-and-order-book-methods/path_find.md @@ -14,7 +14,7 @@ Although the `rippled` server tries to find the cheapest path or combination of ## path_find create [[Source]](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp#L50-L56 "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. +The `create` sub-command 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. @@ -48,7 +48,7 @@ The request includes the following parameters: | `Field` | Type | Description | |:----------------------|:-----------------|:----------------------------------| -| `subcommand` | String | Use `"create"` to send the create subcommand | +| `subcommand` | String | Use `"create"` to send the create sub-command | | `source_account` | String | Unique address of the account to find a path from. (In other words, the account that would be sending a payment.) | | `destination_account` | String | Unique address of the account to find a path to. (In other words, the account that would receive a payment.) | | `destination_amount` | String or Object | [Currency Amount][] that the destination account would receive in a transaction. **Special case:** [New in: rippled 0.30.0][] You can specify `"-1"` (for XRP) or provide -1 as the contents of the `value` field (for non-XRP currencies). This requests a path to deliver as much as possible, while spending no more than the amount specified in `send_max` (if provided). | @@ -463,7 +463,7 @@ In addition to the initial response, the server sends more messages in a similar If the follow-up includes `"full_reply": true`, then this is the best path that rippled can find as of the current ledger. -Here is an example of an asychronous follow-up from a path_find create request: +Here is an example of an asynchronous follow-up from a path_find create request: @@ -491,7 +491,7 @@ Here is an example of an asychronous follow-up from a path_find create request: ## path_find close [[Source]](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp#L58-L67 "Source") -The `close` subcommand of `path_find` instructs the server to stop sending information about the current open pathfinding request. +The `close` sub-command of `path_find` instructs the server to stop sending information about the current open pathfinding request. ### Request Format An example of the request format: @@ -514,7 +514,7 @@ The request includes the following parameters: | `Field` | Type | Description | |:-------------|:-------|:-------------------------------------------| -| `subcommand` | String | Use `"close"` to send the close subcommand | +| `subcommand` | String | Use `"close"` to send the close sub-command | ### Response Format @@ -536,7 +536,7 @@ If there was no outstanding pathfinding request, an error is returned instead. ## path_find status [[Source]](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp#L69-L77 "Source") -The `status` subcommand of `path_find` requests an immediate update about the client's currently-open pathfinding request. +The `status` sub-command of `path_find` requests an immediate update about the client's currently-open pathfinding request. ### Request Format An example of the request format: @@ -559,7 +559,7 @@ The request includes the following parameters: | `Field` | Type | Description | |:-------------|:-------|:---------------------------------------------| -| `subcommand` | String | Use `"status"` to send the status subcommand | +| `subcommand` | String | Use `"status"` to send the status sub-command | ### Response Format diff --git a/content/references/rippled-api/public-rippled-methods/public-rippled-methods.md b/content/references/rippled-api/public-rippled-methods/public-rippled-methods.md index 503044848a..4bba5b92da 100644 --- a/content/references/rippled-api/public-rippled-methods/public-rippled-methods.md +++ b/content/references/rippled-api/public-rippled-methods/public-rippled-methods.md @@ -15,7 +15,7 @@ An account in the XRP Ledger represents a holder of XRP and a sender of transact * **[`account_offers`](account_offers.html)** - Get info about an account's currency exchange offers. * **[`account_tx`](account_tx.html)** - Get info about an account's transactions. * **[`gateway_balances`](gateway_balances.html)** - Calculate total amounts issued by an account. -* **[`noripple_check`](noripple_check.html)** - Get recommended changes to an account's DefaultRipple and NoRipple settings. +* **[`noripple_check`](noripple_check.html)** - Get recommended changes to an account's `DefaultRipple` and No Ripple settings. ## [Ledger Methods](ledger-methods.html) diff --git a/content/references/rippled-api/public-rippled-methods/server-info-methods/server_info.md b/content/references/rippled-api/public-rippled-methods/server-info-methods/server_info.md index e8b0eda960..dae08ef865 100644 --- a/content/references/rippled-api/public-rippled-methods/server-info-methods/server_info.md +++ b/content/references/rippled-api/public-rippled-methods/server-info-methods/server_info.md @@ -492,7 +492,7 @@ The `info` object may have some arrangement of the following fields: | `build_version` | String | The version number of the running `rippled` version. | | `closed_ledger` | Object | (May be omitted) Information on the most recently closed ledger that has not been validated by consensus. If the most recently validated ledger is available, the response omits this field and includes `validated_ledger` instead. The member fields are the same as the `validated_ledger` field. | | `complete_ledgers` | String | Range expression indicating the sequence numbers of the ledger versions the local `rippled` has in its database. This may be a disjoint sequence such as `24900901-24900984,24901116-24901158`. If the server does not have any complete ledgers (for example, it just started syncing with the network), this is the string `empty`. | -| `hostid` | String | On an admin request, returns the hostname of the server running the `rippled` instance; otherwise, returns a single RFC1751 word based on the node public key. | +| `hostid` | String | On an admin request, returns the hostname of the server running the `rippled` instance; otherwise, returns a single [RFC-1751][] word based on the node public key. | | `io_latency_ms` | Number | Amount of time spent waiting for I/O operations, in milliseconds. If this number is not very, very low, then the `rippled` server is probably having serious load issues. | | `jq_trans_overflow` | String - Number | The number of times (since starting up) that this server has had over 250 transactions waiting to be processed at once. A large number here may mean that your server is unable to handle the transaction load of the XRP Ledger network. For detailed recommendations of future-proof server specifications, see [Capacity Planning](capacity-planning.html). [New in: rippled 0.90.0][] | | `last_close` | Object | Information about the last time the server closed a ledger, including the amount of time it took to reach a consensus and the number of trusted validators participating. | @@ -513,7 +513,7 @@ The `info` object may have some arrangement of the following fields: | `server_state_duration_us` | Number | The number of consecutive microseconds the server has been in the current state. [New in: rippled 1.2.0][] | | `state_accounting` | Object | A map of various [server states](rippled-server-states.html) with information about the time the server spends in each. This can be useful for tracking the long-term health of your server's connectivity to the network. [New in: rippled 0.30.1][] | | `state_accounting.*.duration_us` | String | The number of microseconds the server has spent in this state. (This is updated whenever the server transitions into another state.) [New in: rippled 0.30.1][] | -| `state_accounting.*.transitions` | Number | The number of times the server has transitioned into this state. [New in: rippled 0.30.1][] | +| `state_accounting.*.transitions` | Number | The number of times the server has changed into this state. [New in: rippled 0.30.1][] | | `time` | String | The current time in UTC, according to the server's clock. [Updated in: rippled 1.5.0][] | | `uptime` | Number | Number of consecutive seconds that the server has been operational. [New in: rippled 0.30.1][] | | `validated_ledger` | Object | _(May be omitted)_ Information about the most recent fully-validated ledger. If the most recent validated ledger is not available, the response omits this field and includes `closed_ledger` instead. | diff --git a/content/references/rippled-api/public-rippled-methods/server-info-methods/server_state.md b/content/references/rippled-api/public-rippled-methods/server-info-methods/server_state.md index 3a11888606..4eddb47a83 100644 --- a/content/references/rippled-api/public-rippled-methods/server-info-methods/server_state.md +++ b/content/references/rippled-api/public-rippled-methods/server-info-methods/server_state.md @@ -547,7 +547,7 @@ The `state` object may have some arrangement of the following fields: | `server_state_duration_us` | Number | The number of consecutive microseconds the server has been in the current state. [New in: rippled 1.2.0][] | | `state_accounting` | Object | A map of various [server states](rippled-server-states.html) with information about the time the server spends in each. This can be useful for tracking the long-term health of your server's connectivity to the network. [New in: rippled 0.30.1][] | | `state_accounting.*.duration_us` | String | The number of microseconds the server has spent in this state. (This is updated whenever the server transitions into another state.) [New in: rippled 0.30.1][] | -| `state_accounting.*.transitions` | Number | The number of times the server has transitioned into this state. [New in: rippled 0.30.1][] | +| `state_accounting.*.transitions` | Number | The number of times the server has changed into this state. [New in: rippled 0.30.1][] | | `time` | String | The current time in UTC, according to the server's clock. [Updated in: rippled 1.5.0][] | | `uptime` | Number | Number of consecutive seconds that the server has been operational. [New in: rippled 0.30.1][] | | `validated_ledger` | Object | _(May be omitted)_ Information about the most recent fully-validated ledger. If the most recent validated ledger is not available, the response omits this field and includes `closed_ledger` instead. | diff --git a/content/references/rippled-api/public-rippled-methods/subscription-methods/subscribe.md b/content/references/rippled-api/public-rippled-methods/subscription-methods/subscribe.md index 730fdeb3c1..b60b264d2b 100644 --- a/content/references/rippled-api/public-rippled-methods/subscription-methods/subscribe.md +++ b/content/references/rippled-api/public-rippled-methods/subscription-methods/subscribe.md @@ -10,7 +10,7 @@ An example of the request format: *Subscribe to accounts* -``` +```json { "id": "Example watch Bitstamp's hot wallet", "command": "subscribe", @@ -20,7 +20,7 @@ An example of the request format: *Subscribe to order book* -``` +```json { "id": "Example subscribe to XRP/GateHub USD order book", "command": "subscribe", @@ -41,7 +41,7 @@ An example of the request format: *Subscribe to ledger stream* -``` +```json { "id": "Example watch for new validated ledgers", "command": "subscribe", @@ -110,9 +110,9 @@ An example of a successful response: The response follows the [standard format][]. The fields contained in the response vary depending on what subscriptions were included in the request. * `accounts` and `accounts_proposed` - No fields returned. -* *Stream: server* - Information about the server status, such as `load_base` (the current load level of the server), `random` (a randomly-generated value), and others, subject to change. -* *Stream: transactions*, *Stream: transactions_proposed*, *Stream: validations*, and *Stream: consensus* - No fields returned. -* *Stream: ledger* - Information about the ledgers on hand and current fee schedule. This includes the same fields as a [ledger stream message](#ledger-stream), except that it omits the `type` and `txn_count` fields. +* *Stream: `server`* - Information about the server status, such as `load_base` (the current load level of the server), `random` (a randomly-generated value), and others, subject to change. +* *Stream: `transactions`*, *Stream: `transactions_proposed`*, *Stream: `validations`*, and *Stream: `consensus`* - No fields returned. +* *Stream: `ledger`* - Information about the ledgers on hand and current fee schedule. This includes the same fields as a [ledger stream message](#ledger-stream), except that it omits the `type` and `txn_count` fields. * `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 @@ -163,7 +163,7 @@ The fields from a ledger stream message are as follows: | `reserve_base` | Number | The minimum [reserve](reserves.html), in [drops of XRP][], that is required for an account. If this ledger version includes a [SetFee pseudo-transaction](setfee.html) the new base reserve applies starting with the following ledger version. | | `reserve_inc` | Number | The [owner reserve](reserves.html#owner-reserves) for each object an account owns in the ledger, in [drops of XRP][]. If the ledger includes a [SetFee pseudo-transaction](setfee.html) the new owner reserve applies after this ledger. | | `txn_count` | Number | Number of new transactions included in this ledger version. | -| `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. | +| `validated_ledgers` | String | _(May be omitted)_ Range of ledgers that the server has available. This may be a disjoint sequence such as `24900901-24900984,24901116-24901158`. 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 diff --git a/content/references/rippled-api/transaction-formats/transaction-common-fields.md b/content/references/rippled-api/transaction-formats/transaction-common-fields.md index 3ce48661c7..ddf6a8fc27 100644 --- a/content/references/rippled-api/transaction-formats/transaction-common-fields.md +++ b/content/references/rippled-api/transaction-formats/transaction-common-fields.md @@ -2,35 +2,33 @@ Every transaction has the same set of common fields, plus additional fields based on the [transaction type](transaction-types.html). Field names are case-sensitive. The common fields for all transactions are: -| Field | JSON Type | [Internal Type][] | Description | -|:-------------------|:-----------------|:------------------|:-----------------| -| Account | String | Account | _(Required)_ The unique address of the [account](accounts.html) that initiated the transaction. | -| TransactionType | String | UInt16 | _(Required)_ The type of transaction. Valid types include: `Payment`, `OfferCreate`, `OfferCancel`, `TrustSet`, `AccountSet`, `AccountDelete`, `SetRegularKey`, `SignerListSet`, `EscrowCreate`, `EscrowFinish`, `EscrowCancel`, `PaymentChannelCreate`, `PaymentChannelFund`, `PaymentChannelClaim`, and `DepositPreauth`. | -| Fee | String | Amount | _(Required; [auto-fillable][])_ Integer amount of XRP, in drops, to be destroyed as a cost for distributing this transaction to the network. Some transaction types have different minimum requirements. See [Transaction Cost][] for details. | -| Sequence | Unsigned Integer | UInt32 | _(Required; [auto-fillable][])_ The [sequence number](basic-data-types.html#account-sequence) of the account sending the transaction. A transaction is only valid if the `Sequence` number is exactly 1 greater than the previous transaction from the same account. | -| [AccountTxnID][] | String | Hash256 | _(Optional)_ Hash value identifying another transaction. If provided, this transaction is only valid if the sending account's previously-sent transaction matches the provided hash. | -| [Flags][] | Unsigned Integer | UInt32 | _(Optional)_ Set of bit-flags for this transaction. | -| LastLedgerSequence | Number | UInt32 | _(Optional; strongly recommended)_ Highest ledger index this transaction can appear in. Specifying this field places a strict upper limit on how long the transaction can wait to be validated or rejected. See [Reliable Transaction Submission](reliable-transaction-submission.html) for more details. | -| [Memos][] | Array of Objects | Array | _(Optional)_ Additional arbitrary information used to identify this transaction. | -| [Signers][] | Array | Array | _(Optional)_ Array of objects that represent a [multi-signature](multi-signing.html) which authorizes this transaction. | -| SourceTag | Unsigned Integer | UInt32 | _(Optional)_ Arbitrary integer used to identify the reason for this payment, or a sender on whose behalf this transaction is made. Conventionally, a refund should specify the initial payment's `SourceTag` as the refund payment's `DestinationTag`. | -| SigningPubKey | String | Blob | _(Automatically added when signing)_ Hex representation of the public key that corresponds to the private key used to sign this transaction. If an empty string, indicates a multi-signature is present in the `Signers` field instead. | -| TxnSignature | String | Blob | _(Automatically added when signing)_ The signature that verifies this transaction as originating from the account it says it is from. | +| Field | JSON Type | [Internal Type][] | Description | +|:---------------------|:-----------------|:------------------|:-----------------| +| `Account` | String | Account | _(Required)_ The unique address of the [account](accounts.html) that initiated the transaction. | +| `TransactionType` | String | UInt16 | _(Required)_ The type of transaction. Valid types include: `Payment`, `OfferCreate`, `OfferCancel`, `TrustSet`, `AccountSet`, `AccountDelete`, `SetRegularKey`, `SignerListSet`, `EscrowCreate`, `EscrowFinish`, `EscrowCancel`, `PaymentChannelCreate`, `PaymentChannelFund`, `PaymentChannelClaim`, and `DepositPreauth`. | +| `Fee` | String | Amount | _(Required; [auto-fillable][])_ Integer amount of XRP, in drops, to be destroyed as a cost for distributing this transaction to the network. Some transaction types have different minimum requirements. See [Transaction Cost][] for details. | +| `Sequence` | Number | UInt32 | _(Required; [auto-fillable][])_ The [sequence number](basic-data-types.html#account-sequence) of the account sending the transaction. A transaction is only valid if the `Sequence` number is exactly 1 greater than the previous transaction from the same account. | +| [`AccountTxnID`](#accounttxnid) | String | Hash256 | _(Optional)_ Hash value identifying another transaction. If provided, this transaction is only valid if the sending account's previously-sent transaction matches the provided hash. | +| [`Flags`](#flags-field) | Number | UInt32 | _(Optional)_ Set of bit-flags for this transaction. | +| `LastLedgerSequence` | Number | UInt32 | _(Optional; strongly recommended)_ Highest ledger index this transaction can appear in. Specifying this field places a strict upper limit on how long the transaction can wait to be validated or rejected. See [Reliable Transaction Submission](reliable-transaction-submission.html) for more details. | +| [`Memos`](#memos-field) | Array of Objects | Array | _(Optional)_ Additional arbitrary information used to identify this transaction. | +| [`Signers`](#signers-field) | Array | Array | _(Optional)_ Array of objects that represent a [multi-signature](multi-signing.html) which authorizes this transaction. | +| `SourceTag` | Number | UInt32 | _(Optional)_ Arbitrary integer used to identify the reason for this payment, or a sender on whose behalf this transaction is made. Conventionally, a refund should specify the initial payment's `SourceTag` as the refund payment's `DestinationTag`. | +| `SigningPubKey` | String | Blob | _(Automatically added when signing)_ Hex representation of the public key that corresponds to the private key used to sign this transaction. If an empty string, indicates a multi-signature is present in the `Signers` field instead. | +| `TxnSignature` | String | Blob | _(Automatically added when signing)_ The signature that verifies this transaction as originating from the account it says it is from. | [auto-fillable]: #auto-fillable-fields -[AccountTxnID]: #accounttxnid -[Flags]: #flags-field -[Memos]: #memos-field -[Signers]: #signers-field -[Removed in: rippled 0.28.0][]: The `PreviousTxnID` field of transactions was replaced by the [AccountTxnID][] field. This String / Hash256 field is present in some historical transactions. This is unrelated to the field also named `PreviousTxnID` in some [ledger objects](ledger-data-formats.html). +[Removed in: rippled 0.28.0][]: The `PreviousTxnID` field of transactions was replaced by the [`AccountTxnID`](#accounttxnid) field. This String / Hash256 field is present in some historical transactions. This is unrelated to the field also named `PreviousTxnID` in some [ledger objects](ledger-data-formats.html). ## 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. -Unlike the `PreviousTxnID` field, which tracks the last transaction to _modify_ an account (regardless of sender), the `AccountTxnID` tracks the last transaction _sent by_ an account. To use AccountTxnID, you must first set the [asfAccountTxnID](accountset.html#accountset-flags) flag, so that the ledger keeps track of the ID for the account's previous transaction. (`PreviousTxnID`, by comparison, is always tracked.) +Unlike the `PreviousTxnID` field, which tracks the last transaction to _modify_ an account (regardless of sender), the `AccountTxnID` tracks the last transaction _sent by_ an account. To use `AccountTxnID`, you must first set the [`asfAccountTxnID`](accountset.html#accountset-flags) flag, so that the ledger keeps track of the ID for the account's previous transaction. (`PreviousTxnID`, by comparison, is always tracked.) One situation in which this is useful is if you have a primary system for submitting transactions and a passive backup system. If the passive backup system becomes disconnected from the primary, but the primary is not fully dead, and they both begin operating at the same time, you could potentially have serious problems like some transactions sending twice and others not at all. Chaining your transactions together with `AccountTxnID` ensures that, even if both systems are active, only one of them can submit valid transactions at a time. @@ -66,9 +64,9 @@ Bits that are not defined as flags MUST be 0. (The [fix1543 amendment][] enforce The only flag that applies globally to all transactions is as follows: -| Flag Name | Hex Value | Decimal Value | Description | -|:--------------------|:-----------|:--------------|:--------------------------| -| tfFullyCanonicalSig | 0x80000000 | 2147483648 | _(Strongly recommended)_ Require a fully-canonical signature. | +| Flag Name | Hex Value | Decimal Value | Description | +|:----------------------|:-----------|:--------------|:--------------------------| +| `tfFullyCanonicalSig` | `0x80000000` | 2147483648 | _(Strongly recommended)_ Require a fully-canonical signature. | When using the [sign method][] (or [submit method][] in "sign-and-submit" mode), `rippled` adds a `Flags` field with `tfFullyCanonicalSig` enabled unless the `Flags` field is already present. The `tfFullyCanonicalSig` flag ***is not*** automatically enabled if `Flags` is explicitly specified. The flag ***is not*** automatically enabled when using the [sign_for method][] to add a signature to a multi-signed transaction. @@ -91,19 +89,19 @@ A transaction's `Flags` field can contain flags that apply at different levels o 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: -| Field | Type | [Internal Type][] | Description | -|:-----------|:-------|:------------------|:-----------------------------------| -| MemoData | String | Blob | Arbitrary hex value, conventionally containing the content of the memo. | -| MemoFormat | String | Blob | Hex value representing characters allowed in URLs. Conventionally containing information on how the memo is encoded, for example as a [MIME type](http://www.iana.org/assignments/media-types/media-types.xhtml). | -| MemoType | String | Blob | Hex value representing characters allowed in URLs. Conventionally, a unique relation (according to [RFC 5988](http://tools.ietf.org/html/rfc5988#section-4)) that defines the format of this memo. | +| Field | Type | [Internal Type][] | Description | +|:-------------|:-------|:------------------|:---------------------------------| +| `MemoData` | String | Blob | Arbitrary hex value, conventionally containing the content of the memo. | +| `MemoFormat` | String | Blob | Hex value representing characters allowed in URLs. Conventionally containing information on how the memo is encoded, for example as a [MIME type](http://www.iana.org/assignments/media-types/media-types.xhtml). | +| `MemoType` | String | Blob | Hex value representing characters allowed in URLs. Conventionally, a unique relation (according to [RFC 5988](http://tools.ietf.org/html/rfc5988#section-4)) that defines the format of this memo. | The MemoType and MemoFormat fields should only consist of the following characters: `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~:/?#[]@!$&'()*+,;=%` -The `Memos` field is limited to no more than 1KB in size (when serialized in binary format). +The `Memos` field is limited to no more than 1 KB in size (when serialized in binary format). Example of a transaction with a Memos field: -``` +```json { "TransactionType": "Payment", "Account": "rMmTCjGFRWPz8S2zAUUoNVSQHxtRQD4eCx", @@ -131,7 +129,7 @@ The `Signers` field contains a [multi-signature](multi-signing.html), which has | TxnSignature | String | Blob | A signature for this transaction, verifiable using the `SigningPubKey`. | | SigningPubKey | String | Blob | The public key used to create this signature. | -The `SigningPubKey` must be a key that is associated with the `Account` address. If the referenced `Account` is a funded account in the ledger, then the SigningPubKey can be that account's current Regular Key if one is set. It could also be that account's Master Key, unless the [lsfDisableMaster](accountroot.html#accountroot-flags) flag is enabled. If the referenced `Account` address is not a funded account in the ledger, then the `SigningPubKey` must be the master key associated with that address. +The `SigningPubKey` must be a key that is associated with the `Account` address. If the referenced `Account` is a funded account in the ledger, then the SigningPubKey can be that account's current Regular Key if one is set. It could also be that account's Master Key, unless the [`lsfDisableMaster`](accountroot.html#accountroot-flags) flag is enabled. If the referenced `Account` address is not a funded account in the ledger, then the `SigningPubKey` must be the master key associated with that address. Because signature verification is a compute-intensive task, multi-signed transactions cost additional XRP to relay to the network. Each signature included in the multi-signature increases the [transaction cost][] required for the transaction. For example, if the current minimum transaction cost to relay a transaction to the network is `10000` drops, then a multi-signed transaction with 3 entries in the `Signers` array would need a `Fee` value of at least `40000` drops to relay. diff --git a/content/references/rippled-api/transaction-formats/transaction-results/tel-codes.md b/content/references/rippled-api/transaction-formats/transaction-results/tel-codes.md index 38b5007f4e..a0d9e8c7ee 100644 --- a/content/references/rippled-api/transaction-formats/transaction-results/tel-codes.md +++ b/content/references/rippled-api/transaction-formats/transaction-results/tel-codes.md @@ -12,7 +12,7 @@ These codes indicate an error in the local server processing the transaction; it | `telCAN_NOT_QUEUE` | The transaction did not meet the [open ledger cost](transaction-cost.html), but this server did not queue this transaction because it did not meet the [queuing restrictions](transaction-queue.html#queuing-restrictions). For example, a transaction returns this code when the sender already has 10 other transactions in the queue. You can try again later or sign and submit a replacement transaction with a higher transaction cost in the `Fee` field. | | `telCAN_NOT_QUEUE_BALANCE` | The transaction did not meet the [open ledger cost](transaction-cost.html) and also was not added to the transaction queue because the sum of potential XRP costs of already-queued transactions is greater than the expected balance of the account. You can try again later, or try submitting to a different server. [New in: rippled 0.70.2][] | | `telCAN_NOT_QUEUE_BLOCKS` | The transaction did not meet the [open ledger cost](transaction-cost.html) and also was not added to the transaction queue. This transaction could not replace an existing transaction in the queue because it would block already-queued transactions from the same sender by changing authorization methods. (This includes all [SetRegularKey][] and [SignerListSet][] transactions, as well as [AccountSet][] transactions that change the `RequireAuth`/`OptionalAuth`, `DisableMaster`, or `AccountTxnID` flags.) You can try again later, or try submitting to a different server. [New in: rippled 0.70.2][] | -| `telCAN_NOT_QUEUE_BLOCKED` | The transaction did not meet the [open ledger cost](transaction-cost.html) and also was not added to the transaction queue because a transaction queued ahead of it from the same sender blocks it. (This includes all [SetRegularKey][] and [SignerListSet][] transactions, as well as [AccountSet][] transactions that change the RequireAuth/OptionalAuth, DisableMaster, or AccountTxnID flags.) You can try again later, or try submitting to a different server. [New in: rippled 0.70.2][] | +| `telCAN_NOT_QUEUE_BLOCKED` | The transaction did not meet the [open ledger cost](transaction-cost.html) and also was not added to the transaction queue because a transaction queued ahead of it from the same sender blocks it. (This includes all [SetRegularKey][] and [SignerListSet][] transactions, as well as [AccountSet][] transactions that change the `RequireAuth`/`OptionalAuth`, `DisableMaster`, or `AccountTxnID` flags.) You can try again later, or try submitting to a different server. [New in: rippled 0.70.2][] | | `telCAN_NOT_QUEUE_FEE` | The transaction did not meet the [open ledger cost](transaction-cost.html) and also was not added to the transaction queue. This code occurs when a transaction with the same sender and sequence number already exists in the queue and the new one does not pay a large enough transaction cost to replace the existing transaction. To replace a transaction in the queue, the new transaction must have a `Fee` value that is at least 25% more, as measured in [fee levels](transaction-cost.html#fee-levels). You can increase the `Fee` and try again, send this with a higher `Sequence` number so it doesn't replace an existing transaction, or try sending to another server. [New in: rippled 0.70.2][] | | `telCAN_NOT_QUEUE_FULL` | The transaction did not meet the [open ledger cost](transaction-cost.html) and the server did not queue this transaction because this server's transaction queue is full. You could increase the `Fee` and try again, try again later, or try submitting to a different server. The new transaction must have a higher transaction cost, as measured in [fee levels](transaction-cost.html#fee-levels), than the transaction in the queue with the smallest transaction cost. [New in: rippled 0.70.2][] | | `telFAILED_PROCESSING` | An unspecified error occurred when processing the transaction. | diff --git a/content/references/rippled-api/transaction-formats/transaction-results/transaction-results.md b/content/references/rippled-api/transaction-formats/transaction-results/transaction-results.md index 6ee826b9b3..0e93ee8b65 100644 --- a/content/references/rippled-api/transaction-formats/transaction-results/transaction-results.md +++ b/content/references/rippled-api/transaction-formats/transaction-results/transaction-results.md @@ -4,14 +4,14 @@ The `rippled` server summarizes transaction results with result codes, which appear in fields such as `engine_result` and `meta.TransactionResult`. These codes are grouped into several categories of with different prefixes: -| Category | Prefix | Description | -|:----------------------|:------------------------|:---------------------------| -| Claimed cost only | [tec](tec-codes.html) | The transaction did not achieve its intended purpose, but the [transaction cost](transaction-cost.html) was destroyed. This result is only final in a validated ledger. | -| Failure | [tef](tef-codes.html) | The transaction cannot be applied to the server's current (in-progress) ledger or any later one. It may have already been applied, or the condition of the ledger makes it impossible to apply in the future. | -| Local error | [tel](tel-codes.html) | The `rippled` server had an error due to local conditions, such as high load. You may get a different response if you resubmit to a different server or at a different time. | -| Malformed transaction | [tem](tem-codes.html) | The transaction was not valid, due to improper syntax, conflicting options, a bad signature, or something else. | -| Retry | [ter](ter-codes.html) | The transaction could not be applied, but it could apply successfully in a future ledger. | -| Success | [tes](tes-success.html) | (Not an error) The transaction succeeded. This result only final in a validated ledger. | +| Category | Prefix | Description | +|:----------------------|:--------------------------|:-------------------------| +| Claimed cost only | [`tec`](tec-codes.html) | The transaction did not achieve its intended purpose, but the [transaction cost](transaction-cost.html) was destroyed. This result is only final in a validated ledger. | +| Failure | [`tef`](tef-codes.html) | The transaction cannot be applied to the server's current (in-progress) ledger or any later one. It may have already been applied, or the condition of the ledger makes it impossible to apply in the future. | +| Local error | [`tel`](tel-codes.html) | The `rippled` server had an error due to local conditions, such as high load. You may get a different response if you resubmit to a different server or at a different time. | +| Malformed transaction | [`tem`](tem-codes.html) | The transaction was not valid, due to improper syntax, conflicting options, a bad signature, or something else. | +| Retry | [`ter`](ter-codes.html) | The transaction could not be applied, but it could apply successfully in a future ledger. | +| Success | [`tes`](tes-success.html) | (Not an error) The transaction succeeded. This result only final in a validated ledger. | The `rippled` server automatically retries failed transactions. It is important not to assume that a transaction has completely failed based on a tentative failure result. A transaction may later succeed unless its success or failure is [final](finality-of-results.html). diff --git a/content/references/rippled-api/transaction-formats/transaction-types/accountset.md b/content/references/rippled-api/transaction-formats/transaction-types/accountset.md index 99514d06da..18c656da76 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/accountset.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/accountset.md @@ -24,21 +24,15 @@ An AccountSet transaction modifies the properties of an [account in the XRP Ledg | Field | JSON Type | [Internal Type][] | Description | |:-----------------|:-----------------|:------------------|:-------------------| -| [ClearFlag][] | Number | UInt32 | _(Optional)_ Unique identifier of a flag to disable for this account. | -| [Domain][] | String | Blob | _(Optional)_ The domain that owns this account, as a string of hex representing the ASCII for the domain in lowercase. | -| EmailHash | String | Hash128 | _(Optional)_ Hash of an email address to be used for generating an avatar image. Conventionally, clients use [Gravatar](http://en.gravatar.com/site/implement/hash/) to display this image. | -| MessageKey | String | Blob | _(Optional)_ Public key for sending encrypted messages to this account. | -| [SetFlag][] | Number | UInt32 | _(Optional)_ Integer flag to enable for this account. | -| [TransferRate][] | Unsigned Integer | UInt32 | _(Optional)_ The fee to charge when users transfer this account's issued currencies, represented as billionths of a unit. Cannot be more than `2000000000` or less than `1000000000`, except for the special case `0` meaning no fee. | -| [TickSize][] | Unsigned Integer | UInt8 | _(Optional)_ Tick size to use for offers involving a currency issued by this address. The exchange rates of those offers is rounded to this many significant digits. Valid values are `3` to `15` inclusive, or `0` to disable. _(Added by the [TickSize amendment][].)_ | -| WalletLocator | String | Hash256 | _(Optional)_ Not used. | -| WalletSize | Number | UInt32 | _(Optional)_ Not used. | - -[ClearFlag]: #accountset-flags -[Domain]: #domain -[SetFlag]: #accountset-flags -[TickSize]: ticksize.html -[TransferRate]: accountset.html#transferrate +| [`ClearFlag`](#accountset-flags) | Number | UInt32 | _(Optional)_ Unique identifier of a flag to disable for this account. | +| [Domain](#domain) | String | Blob | _(Optional)_ The domain that owns this account, as a string of hex representing the ASCII for the domain in lowercase. | +| `EmailHash` | String | Hash128 | _(Optional)_ Hash of an email address to be used for generating an avatar image. Conventionally, clients use [Gravatar](http://en.gravatar.com/site/implement/hash/) to display this image. | +| `MessageKey` | String | Blob | _(Optional)_ Public key for sending encrypted messages to this account. | +| [`SetFlag`](#accountset-flags) | Number | UInt32 | _(Optional)_ Integer flag to enable for this account. | +| [`TransferRate`](#transferrate) | Number | UInt32 | _(Optional)_ The fee to charge when users transfer this account's issued currencies, represented as billionths of a unit. Cannot be more than `2000000000` or less than `1000000000`, except for the special case `0` meaning no fee. | +| [`TickSize`](ticksize.html) | Number | UInt8 | _(Optional)_ Tick size to use for offers involving a currency issued by this address. The exchange rates of those offers is rounded to this many significant digits. Valid values are `3` to `15` inclusive, or `0` to disable. _(Added by the [TickSize amendment][].)_ | +| `WalletLocator` | String | Hash256 | _(Optional)_ Not used. | +| `WalletSize` | Number | UInt32 | _(Optional)_ Not used. | If none of these options are provided, then the AccountSet transaction has no effect (beyond destroying the transaction cost). See [Cancel or Skip a Transaction](cancel-or-skip-a-transaction.html) for more details. @@ -57,40 +51,40 @@ You can put any domain in your account's `Domain` field. To prove that an accoun 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: -* The `AccountSet` transaction type has several "AccountSet Flags" (prefixed **asf**) that can enable an option when passed as the `SetFlag` parameter, or disable an option when passed as the `ClearFlag` parameter. -* The `AccountSet` transaction type has several transaction flags (prefixed **tf**) that can be used to enable or disable specific account options when passed in the `Flags` parameter. This style is discouraged. New account options do not have corresponding transaction (tf) flags. -* The `AccountRoot` ledger object type has several ledger-specific-flags (prefixed **lsf**) which represent the state of particular account options within a particular ledger. These settings apply until a transaction changes them. +* The `AccountSet` transaction type has several "AccountSet Flags" (prefixed **`asf`**) that can enable an option when passed as the `SetFlag` parameter, or disable an option when passed as the `ClearFlag` parameter. +* The `AccountSet` transaction type has several transaction flags (prefixed **`tf`**) that can be used to enable or disable specific account options when passed in the `Flags` parameter. This style is discouraged. New account options do not have corresponding transaction (`tf`) flags. +* The `AccountRoot` ledger object type has several ledger-state-flags (prefixed **`lsf`**) which represent the state of particular account options within a particular ledger. These settings apply until a transaction changes them. -The preferred way to enable and disable Account Flags is using the `SetFlag` and `ClearFlag` parameters of an AccountSet transaction. AccountSet flags have names that begin with **asf**. +The preferred way to enable and disable Account Flags is using the `SetFlag` and `ClearFlag` parameters of an AccountSet transaction. AccountSet flags have names that begin with **`asf`**. All flags are disabled by default. The available AccountSet flags are: -| Flag Name | Decimal Value | Corresponding Ledger Flag | Description | -|:-----------------|:--------------|:--------------------------|:--------------| -| asfAccountTxnID | 5 | (None) | Track the ID of this account's most recent transaction. Required for [AccountTxnID](transaction-common-fields.html#accounttxnid) | -| asfDefaultRipple | 8 | lsfDefaultRipple | Enable [rippling](rippling.html) on this account's trust lines by default. [New in: rippled 0.27.3][] | -| asfDepositAuth | 9 | lsfDepositAuth | Enable [Deposit Authorization](depositauth.html) on this account. _(Added by the [DepositAuth amendment][].)_ | -| asfDisableMaster | 4 | lsfDisableMaster | Disallow use of the master key pair. Can only be enabled if the account has configured another way to sign transactions, such as a [Regular Key](cryptographic-keys.html) or a [Signer List](multi-signing.html). | -| asfDisallowXRP | 3 | lsfDisallowXRP | XRP should not be sent to this account. (Enforced by client applications, not by `rippled`) | -| asfGlobalFreeze | 7 | lsfGlobalFreeze | [Freeze](freezes.html) all assets issued by this account. | -| asfNoFreeze | 6 | lsfNoFreeze | Permanently give up the ability to [freeze individual trust lines or disable Global Freeze](freezes.html). This flag can never be disabled after being enabled. | -| asfRequireAuth | 2 | lsfRequireAuth | Require authorization for users to hold balances issued by this address. Can only be enabled if the address has no trust lines connected to it. | -| asfRequireDest | 1 | lsfRequireDestTag | Require a destination tag to send transactions to this account. | +| Flag Name | Decimal Value | Corresponding Ledger Flag | Description | +|:-------------------|:--------------|:--------------------------|:--------------| +| `asfAccountTxnID` | 5 | (None) | Track the ID of this account's most recent transaction. Required for [AccountTxnID](transaction-common-fields.html#accounttxnid) | +| `asfDefaultRipple` | 8 | `lsfDefaultRipple` | Enable [rippling](rippling.html) on this account's trust lines by default. [New in: rippled 0.27.3][] | +| `asfDepositAuth` | 9 | `lsfDepositAuth` | Enable [Deposit Authorization](depositauth.html) on this account. _(Added by the [DepositAuth amendment][].)_ | +| `asfDisableMaster` | 4 | `lsfDisableMaster` | Disallow use of the master key pair. Can only be enabled if the account has configured another way to sign transactions, such as a [Regular Key](cryptographic-keys.html) or a [Signer List](multi-signing.html). | +| `asfDisallowXRP` | 3 | `lsfDisallowXRP` | XRP should not be sent to this account. (Enforced by client applications, not by `rippled`) | +| `asfGlobalFreeze` | 7 | `lsfGlobalFreeze` | [Freeze](freezes.html) all assets issued by this account. | +| `asfNoFreeze` | 6 | `lsfNoFreeze` | Permanently give up the ability to [freeze individual trust lines or disable Global Freeze](freezes.html). This flag can never be disabled after being enabled. | +| `asfRequireAuth` | 2 | `lsfRequireAuth` | Require authorization for users to hold balances issued by this address. Can only be enabled if the address has no trust lines connected to it. | +| `asfRequireDest` | 1 | `lsfRequireDestTag` | Require a destination tag to send transactions to this account. | To enable the `asfDisableMaster` or `asfNoFreeze` flags, you must [authorize the transaction](transaction-basics.html#authorizing-transactions) by signing it with the master key pair. You cannot use a regular key pair or a multi-signature. You can disable `asfDisableMaster` (that is, re-enable the master key pair) using a regular key pair or multi-signature. [New in: rippled 0.28.0][] The following [Transaction flags](transaction-common-fields.html#flags-field), specific to the AccountSet transaction type, serve the same purpose, but are discouraged: -| Flag Name | Hex Value | Decimal Value | Replaced by AccountSet Flag | -|:------------------|:-----------|:--------------|:----------------------------| -| tfRequireDestTag | 0x00010000 | 65536 | asfRequireDest (SetFlag) | -| tfOptionalDestTag | 0x00020000 | 131072 | asfRequireDest (ClearFlag) | -| tfRequireAuth | 0x00040000 | 262144 | asfRequireAuth (SetFlag) | -| tfOptionalAuth | 0x00080000 | 524288 | asfRequireAuth (ClearFlag) | -| tfDisallowXRP | 0x00100000 | 1048576 | asfDisallowXRP (SetFlag) | -| tfAllowXRP | 0x00200000 | 2097152 | asfDisallowXRP (ClearFlag) | +| Flag Name | Hex Value | Decimal Value | Replaced by AccountSet Flag | +|:--------------------|:-------------|:--------------|:----------------------------| +| `tfRequireDestTag` | `0x00010000` | 65536 | `asfRequireDest` (`SetFlag`) | +| `tfOptionalDestTag` | `0x00020000` | 131072 | `asfRequireDest` (`ClearFlag`) | +| `tfRequireAuth` | `0x00040000` | 262144 | `asfRequireAuth` (`SetFlag`) | +| `tfOptionalAuth` | `0x00080000` | 524288 | `asfRequireAuth` (`ClearFlag`) | +| `tfDisallowXRP` | `0x00100000` | 1048576 | `asfDisallowXRP` (`SetFlag`) | +| `tfAllowXRP` | `0x00200000` | 2097152 | `asfDisallowXRP` (`ClearFlag`) | **Caution:** The numeric values of `tf` and `asf` flags in transactions do not match up with the values they set in the accounts "at rest" in the ledger. To read the flags of an account in the ledger, see [`AccountRoot` flags](accountroot.html#accountroot-flags). @@ -105,9 +99,11 @@ You can protect against unwanted incoming payments for non-XRP currencies by not ## TransferRate -The TransferRate field specifies a fee to charge whenever counterparties transfer the currency you issue. See [Transfer Fees](transfer-fees.html) for more information. +The `TransferRate` field specifies a fee to charge whenever counterparties transfer the currency you issue. See [Transfer Fees](transfer-fees.html) for more information. -In `rippled`'s WebSocket and JSON-RPC APIs, the TransferRate is represented as an integer, the amount that must be sent for 1 billion units to arrive. For example, a 20% transfer fee is represented as the value `1200000000`. The value cannot be less than 1000000000. (Less than that would indicate giving away money for sending transactions, which is exploitable.) You can specify 0 as a shortcut for 1000000000, meaning no fee. +In `rippled`'s WebSocket and JSON-RPC APIs, the transfer fee is represented as an integer, the amount that must be sent for 1 billion units to arrive. For example, a 20% transfer fee is represented as the value `1200000000`. The value cannot be less than 1000000000. (Less than that would indicate giving away money for sending transactions, which is exploitable.) You can specify 0 as a shortcut for 1000000000, meaning no fee. + + {% include '_snippets/rippled-api-links.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-types/checkcreate.md b/content/references/rippled-api/transaction-formats/transaction-types/checkcreate.md index 1c0ba7e651..429ba9fa87 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/checkcreate.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/checkcreate.md @@ -35,7 +35,7 @@ Create a Check object in the ledger, which is a deferred payment that can be cas - If the `Destination` is the sender of the transaction, the transaction fails with the result code `temREDUNDANT`. - If the `Destination` [account](accounts.html) does not exist in the ledger, the transaction fails with the result code `tecNO_DST`. -- If the `Destination` account has the RequireDest flag enabled but the transaction does not include a `DestinationTag` field, the transaction fails with the result code `tecDST_TAG_NEEDED`. +- If the `Destination` account has the `RequireDest` flag enabled but the transaction does not include a `DestinationTag` field, the transaction fails with the result code `tecDST_TAG_NEEDED`. - If `SendMax` specifies an issued currency which is [frozen](freezes.html), the transaction fails with the result `tecFROZEN`. - If the `Expiration` of the transaction is in the past, the transaction fails with the result `tecEXPIRED`. - If the sender does not have enough XRP to meet the [owner reserve](reserves.html#owner-reserves) after adding the Check, the transaction fails with the result `tecINSUFFICIENT_RESERVE`. diff --git a/content/references/rippled-api/transaction-formats/transaction-types/offercancel.md b/content/references/rippled-api/transaction-formats/transaction-types/offercancel.md index 9fbac50a77..e201d6876a 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/offercancel.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/offercancel.md @@ -22,13 +22,13 @@ An OfferCancel transaction removes an Offer object from the XRP Ledger. -| Field | JSON Type | [Internal Type][] | Description | -|:--------------|:----------|:------------------|:-----------------------------| -| OfferSequence | Number | UInt32 | The sequence number of a previous OfferCreate transaction. If specified, cancel any offer object in the ledger that was created by that transaction. It is not considered an error if the offer specified does not exist. | +| Field | JSON Type | [Internal Type][] | Description | +|:----------------|:----------|:------------------|:-----------------------------| +| `OfferSequence` | Number | UInt32 | The sequence number of a previous OfferCreate transaction. If specified, cancel any offer object in the ledger that was created by that transaction. It is not considered an error if the offer specified does not exist. | *Tip:* To remove an old offer and replace it with a new one, you can use an [OfferCreate transaction][] with an `OfferSequence` parameter, instead of using OfferCancel and another OfferCreate. -The OfferCancel method returns [tesSUCCESS](tes-success.html) even if it did not find an offer with the matching sequence number. +The OfferCancel method returns [`tesSUCCESS`](tes-success.html) even if it did not find an offer with the matching sequence number. {% include '_snippets/rippled-api-links.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-types/payment.md b/content/references/rippled-api/transaction-formats/transaction-types/payment.md index bc7f61d92f..aaf058485d 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/payment.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/payment.md @@ -27,27 +27,27 @@ Payments are also the only way to [create accounts](#creating-accounts). -| Field | JSON Type | [Internal Type][] | Description | -|:---------------|:---------------------|:------------------|:-----------------| -| Amount | [Currency Amount][] | Amount | The amount of currency to deliver. For non-XRP amounts, the nested field names MUST be lower-case. If the [**tfPartialPayment** flag](#payment-flags) is set, deliver _up to_ this amount instead. | -| Destination | String | Account | The unique address of the account receiving the payment. | -| DestinationTag | Number | UInt32 | _(Optional)_ Arbitrary tag that identifies the reason for the payment to the destination, or a hosted recipient to pay. | -| InvoiceID | String | Hash256 | _(Optional)_ Arbitrary 256-bit hash representing a specific reason or identifier for this payment. | -| Paths | Array of path arrays | PathSet | (Optional, auto-fillable) Array of [payment paths](paths.html) to be used for this transaction. Must be omitted for XRP-to-XRP transactions. | -| SendMax | [Currency Amount][] | Amount | _(Optional)_ Highest amount of source currency this transaction is allowed to cost, including [transfer fees](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.html). 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.html). For non-XRP amounts, the nested field names are lower-case. | +| Field | JSON Type | [Internal Type][] | Description | +|:-----------------|:---------------------|:------------------|:---------------| +| `Amount` | [Currency Amount][] | Amount | The amount of currency to deliver. For non-XRP amounts, the nested field names MUST be lower-case. If the [**tfPartialPayment** flag](#payment-flags) is set, deliver _up to_ this amount instead. | +| `Destination` | String | Account | The unique address of the account receiving the payment. | +| `DestinationTag` | Number | UInt32 | _(Optional)_ Arbitrary tag that identifies the reason for the payment to the destination, or a hosted recipient to pay. | +| `InvoiceID` | String | Hash256 | _(Optional)_ Arbitrary 256-bit hash representing a specific reason or identifier for this payment. | +| `Paths` | Array of path arrays | PathSet | (Optional, auto-fillable) Array of [payment paths](paths.html) to be used for this transaction. Must be omitted for XRP-to-XRP transactions. | +| `SendMax` | [Currency Amount][] | Amount | _(Optional)_ Highest amount of source currency this transaction is allowed to cost, including [transfer fees](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.html). 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.html). For non-XRP amounts, the nested field names are lower-case. | ## Types of Payments The Payment transaction type is a general-purpose tool that can represent several different types of abstract actions. You can identify the transaction type based on the transaction's fields, as described in the table below: -| Payment type | `Amount` | `SendMax` | `Paths` | `Address` = `Destination`? | Description | -|:------------------------------------------|:--------------------------------|:--------------------------------|:-----------------|:---------------------------|:--| -| [Direct XRP-to-XRP Payment][] | String (XRP) | Omitted | Omitted | No | Transfers XRP directly from one account to another. Always delivers the exact amount. No fee applies other than the basic [transaction cost](transaction-cost.html). | -| [Creating or redeeming issued currency][] | Object | Object (optional) | Optional | No | Increases or decreases the amount of a non-XRP currency or asset tracked in the XRP Ledger. [Transfer fees](transfer-fees.html) and [freezes](freezes.html) do not apply when sending and redeeming directly. | -| [Cross-currency Payment][] | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Usually required | No | Send issued currency from one holder to another. The `Amount` and `SendMax` cannot _both_ be XRP. These payments [ripple through](rippling.html) the issuer and can take longer [paths](paths.html) through several intermediaries if the transaction specifies a path set. [Transfer fees](transfer-fees.html) set by the issuer(s) apply to this type of transaction. These transactions consume offers in the [decentralized exchange](decentralized-exchange.html) to connect between different currencies, or possibly even between currencies with the same currency code and different issuers. | -| [Partial payment][] | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Usually required | No | Sends _up to_ a specific amount of any currency. Uses the [tfPartialPayment flag](#payment-flags). May include a `DeliverMin` amount specifying the minimum that the transaction must deliver to be successful; if the transaction does not specify `DeliverMin`, it can succeed by delivering _any positive amount_. | -| Currency conversion | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Required | Yes | Consumes offers in the [decentralized exchange](decentralized-exchange.html) to convert one currency to another, possibly taking [arbitrage](https://en.wikipedia.org/wiki/Arbitrage) opportunities. The `Amount` and `SendMax` cannot both be XRP. Also called a _circular payment_ because it delivers money to the sender. The [Data API](data-api.html) tracks this type of transaction as an "exchange" and not a "payment". | +| Payment type | `Amount` | `SendMax` | `Paths` | `Address` = `Destination`? | Description | +|:-------------|:----------|:-----------|:----------|:---------------------------|:--| +| [Direct XRP-to-XRP Payment][] | String (XRP) | Omitted | Omitted | No | Transfers XRP directly from one account to another. Always delivers the exact amount. No fee applies other than the basic [transaction cost](transaction-cost.html). | +| [Creating or redeeming issued currency][] | Object | Object (optional) | Optional | No | Increases or decreases the amount of a non-XRP currency or asset tracked in the XRP Ledger. [Transfer fees](transfer-fees.html) and [freezes](freezes.html) do not apply when sending and redeeming directly. | +| [Cross-currency Payment][] | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Usually required | No | Send issued currency from one holder to another. The `Amount` and `SendMax` cannot _both_ be XRP. These payments [ripple through](rippling.html) the issuer and can take longer [paths](paths.html) through several intermediaries if the transaction specifies a path set. [Transfer fees](transfer-fees.html) set by the issuer(s) apply to this type of transaction. These transactions consume offers in the [decentralized exchange](decentralized-exchange.html) to connect between different currencies, or possibly even between currencies with the same currency code and different issuers. | +| [Partial payment][] | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Usually required | No | Sends _up to_ a specific amount of any currency. Uses the [`tfPartialPayment` flag](#payment-flags). May include a `DeliverMin` amount specifying the minimum that the transaction must deliver to be successful; if the transaction does not specify `DeliverMin`, it can succeed by delivering _any positive amount_. | +| Currency conversion | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Required | Yes | Consumes offers in the [decentralized exchange](decentralized-exchange.html) to convert one currency to another, possibly taking [arbitrage](https://en.wikipedia.org/wiki/Arbitrage) opportunities. The `Amount` and `SendMax` cannot both be XRP. Also called a _circular payment_ because it delivers money to the sender. The [Data API](data-api.html) tracks this type of transaction as an "exchange" and not a "payment". | [Direct XRP-to-XRP Payment]: direct-xrp-payments.html [Creating or redeeming issued currency]: issued-currencies-overview.html @@ -59,9 +59,9 @@ The Payment transaction type is a general-purpose tool that can represent severa Most of the time, the `issuer` field of a non-XRP [Currency Amount][] indicates a financial institution's [issuing address](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. -* There is only ever one balance for the same currency between two addresses. This means that, sometimes, the `issuer` field of an amount actually refers to a counterparty that is redeeming issuances, instead of the address that created the issuances. -* 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. +* There is only ever one balance for the same currency between two addresses. This means that, sometimes, the `issuer` field of an amount actually refers to a counterparty that is redeeming the issued currency, instead of the address that issued the currency. +* 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 currencies issued by the destination. +* 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 issued currencies on trust lines that other accounts have extended to the source account, and sending issued currencies the source account holds from other issuers. ## Creating Accounts @@ -88,11 +88,11 @@ For more information, see [Paths](paths.html). Transactions of the Payment type support additional values in the [`Flags` field](transaction-common-fields.html#flags-field), as follows: -| Flag Name | Hex Value | Decimal Value | Description | -|:-----------------|:-----------|:--------------|:-----------------------------| -| tfNoDirectRipple | 0x00010000 | 65536 | Do not use the default path; only use paths included in the `Paths` field. This is intended to force the transaction to take arbitrage opportunities. Most clients do not need this. | -| tfPartialPayment | 0x00020000 | 131072 | If the specified `Amount` cannot be sent without spending more than `SendMax`, reduce the received amount instead of failing outright. See [Partial Payments](partial-payments.html) for more details. | -| tfLimitQuality | 0x00040000 | 262144 | Only take paths where all the conversions have an input:output ratio that is equal or better than the ratio of `Amount`:`SendMax`. See [Limit Quality](#limit-quality) for details. | +| Flag Name | Hex Value | Decimal Value | Description | +|:-------------------|:-------------|:--------------|:-----------------------------| +| `tfNoDirectRipple` | `0x00010000` | 65536 | Do not use the default path; only use paths included in the `Paths` field. This is intended to force the transaction to take arbitrage opportunities. Most clients do not need this. | +| `tfPartialPayment` | `0x00020000` | 131072 | If the specified `Amount` cannot be sent without spending more than `SendMax`, reduce the received amount instead of failing outright. See [Partial Payments](partial-payments.html) for more details. | +| `tfLimitQuality` | `0x00040000` | 262144 | Only take paths where all the conversions have an input:output ratio that is equal or better than the ratio of `Amount`:`SendMax`. See [Limit Quality](#limit-quality) for details. | ## Partial Payments diff --git a/content/references/rippled-api/transaction-formats/transaction-types/trustset.md b/content/references/rippled-api/transaction-formats/transaction-types/trustset.md index 7b9349e0b2..385279b525 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/trustset.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/trustset.md @@ -42,13 +42,17 @@ Transactions of the TrustSet type support additional values in the [`Flags` fiel | Flag Name | Hex Value | Decimal Value | Description | |:------------------|:-------------|:--------------|:--------------------------| | `tfSetfAuth` | `0x00010000` | 65536 | Authorize the other party to hold [currency issued by this account](issued-currencies.html). (No effect unless using the [`asfRequireAuth` AccountSet flag](accountset.html#accountset-flags).) Cannot be unset. | -| `tfSetNoRipple` | `0x00020000` | 131072 | Blocks rippling between two trust lines of the same currency, if this flag is set on both. (See [No Ripple](rippling.html) for details.) If the [fix1578 amendment][] is enabled, a transaction that uses this flag and cannot enable NoRipple fails with the result code `tecNO_PERMISSION`. If the amendment is not enabled, the transaction can result in `tesSUCCESS` (making any other changes it can) even if it cannot enable No Ripple on the trust line. | -| `tfClearNoRipple` | `0x00040000` | 262144 | Clears the No-Rippling flag. (See [No Ripple](rippling.html) for details.) | -| `tfSetFreeze` | `0x00100000` | 1048576 | [Freeze](freezes.html) the trustline. | -| `tfClearFreeze` | `0x00200000` | 2097152 | [Unfreeze](freezes.html) the trustline. | +| `tfSetNoRipple` | `0x00020000` | 131072 | Enable the No Ripple flag, which blocks [rippling](rippling.html) between two trust lines of the same currency if this flag is enabled on both. | +| `tfClearNoRipple` | `0x00040000` | 262144 | Disable the No Ripple flag, allowing [rippling](rippling.html) on this trust line.) | +| `tfSetFreeze` | `0x00100000` | 1048576 | [Freeze](freezes.html) the trust line. | +| `tfClearFreeze` | `0x00200000` | 2097152 | [Unfreeze](freezes.html) the trust line. | + +If a transaction tries to enable No Ripple but cannot, it fails with the result code `tecNO_PERMISSION`. Before the [fix1578 amendment][] became enabled, such a transaction would result in `tesSUCCESS` (making any other changes it could) instead. 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. + + {% include '_snippets/rippled-api-links.md' %} {% include '_snippets/tx-type-links.md' %} diff --git a/content/tutorials/manage-the-rippled-server/configuration/configure-history-sharding.md b/content/tutorials/manage-the-rippled-server/configuration/configure-history-sharding.md index 144dc1b93c..e88072a952 100644 --- a/content/tutorials/manage-the-rippled-server/configuration/configure-history-sharding.md +++ b/content/tutorials/manage-the-rippled-server/configuration/configure-history-sharding.md @@ -20,6 +20,8 @@ Before you configure your `rippled` server to store history shards, you must dec ## 2. Edit rippled.cfg + + Edit your `rippled.cfg` file to add a `[shard_db]` stanza. {% include '_snippets/conf-file-location.md' %} diff --git a/content/tutorials/manage-the-rippled-server/configuration/run-rippled-as-a-validator.md b/content/tutorials/manage-the-rippled-server/configuration/run-rippled-as-a-validator.md index 73eb47f409..ec94f92886 100644 --- a/content/tutorials/manage-the-rippled-server/configuration/run-rippled-as-a-validator.md +++ b/content/tutorials/manage-the-rippled-server/configuration/run-rippled-as-a-validator.md @@ -48,7 +48,7 @@ For more information, see [Install `rippled`](install-rippled.html). ## 3. Enable validation on your `rippled` server -Enabling validation on your `rippled` server means providing a validator token in your server's `rippled.cfg` file. Ripple recommends using the `validator-keys` tool (included in `rippled` RPMs) to securely generate and manage your validator keys and tokens. +Enabling validation on your `rippled` server means providing a validator token in your server's `rippled.cfg` file. Ripple recommends using the `validator-keys` tool (included in `rippled` packages) to securely generate and manage your validator keys and tokens. In a location **not** on your validator: @@ -259,7 +259,7 @@ To provide domain verification: Provide the value returned in the **SSL Signature** field of the Google Form. - 3. Using the [`validator-keys` tool](https://github.com/ripple/validator-keys-tool/blob/master/doc/validator-keys-tool-guide.md) (included in `rippled` RPMs), sign the domain name. + 3. Using the [`validator-keys` tool](https://github.com/ripple/validator-keys-tool/blob/master/doc/validator-keys-tool-guide.md) (included in `rippled` packages), sign the domain name. $ validator-keys --keyfile /PATH/TO/YOUR/validator-keys.json sign YOUR_DOMAIN_NAME diff --git a/content/tutorials/manage-the-rippled-server/configure-peering/use-a-peer-reservation.md b/content/tutorials/manage-the-rippled-server/configure-peering/use-a-peer-reservation.md index 95824875bd..d2f597fe10 100644 --- a/content/tutorials/manage-the-rippled-server/configure-peering/use-a-peer-reservation.md +++ b/content/tutorials/manage-the-rippled-server/configure-peering/use-a-peer-reservation.md @@ -150,7 +150,7 @@ As a server administrator, you can manage the reservations your server has for o - Remove one of your reservations using the [peer_reservations_del method][]. - Check which peers are currently connected and how much bandwidth they have used, using the [peers method][]. -**Tip:** Although there is no API method to immediately disconnect from an unwanted peer, you can use a software firewall such as `firewalld` to block an unwanted peer from connecting to your server. For examples, see the community-contributed [rbh script](https://github.com/gnanderson/rbh). +**Tip:** Although there is no API method to immediately disconnect from an unwanted peer, you can use a software firewall such as `firewalld` to block an unwanted peer from connecting to your server. For examples, see the community-contributed [rbh script](https://github.com/gnanderson/rbh). ## See Also diff --git a/content/tutorials/manage-the-rippled-server/installation/build-run-rippled-macos.md b/content/tutorials/manage-the-rippled-server/installation/build-run-rippled-macos.md index f2a315e2b6..75f08430d3 100644 --- a/content/tutorials/manage-the-rippled-server/installation/build-run-rippled-macos.md +++ b/content/tutorials/manage-the-rippled-server/installation/build-run-rippled-macos.md @@ -42,7 +42,7 @@ For development purposes, run `rippled` as a non-admin user, not using `sudo`. 2. Edit below code with your Boost directory location and run to add Boost environment variable to your `.bash_profile` file so it's automatically set when you log in. - $ echo $"export BOOST_ROOT=/Users/my_user/boost_1_71_0" >> ~/.bash_profile + $ echo "export BOOST_ROOT=/Users/my_user/boost_1_71_0" >> ~/.bash_profile 0. If you updated your `.bash_profile` file in the previous step, be sure to source it in a new Terminal window. For example: diff --git a/content/tutorials/manage-the-rippled-server/installation/build-run-rippled-ubuntu.md b/content/tutorials/manage-the-rippled-server/installation/build-run-rippled-ubuntu.md index e346a4fa28..aacd7f0d79 100644 --- a/content/tutorials/manage-the-rippled-server/installation/build-run-rippled-ubuntu.md +++ b/content/tutorials/manage-the-rippled-server/installation/build-run-rippled-ubuntu.md @@ -97,7 +97,7 @@ These instructions use Ubuntu's APT (Advanced Packaging Tool) to install the sof -8. If you previously built, or (more importantly) tried and failed to build `rippled`, you should delete the `my_build/` directory (or whatever you named it) to start clean before moving on to the next step. Otherwise, you may get unexpected behavior, like a `rippled` executable that crashes due to a segmentation fault (segfault). +8. If you previously built, or (more importantly) tried and failed to build `rippled`, you should delete the `my_build/` directory (or whatever you named it) to start clean before moving on to the next step. Otherwise, you may get unexpected behavior, like a `rippled` executable that crashes due to a segmentation fault (segfault). If this is your first time building `rippled` 1.0.0 or higher, you won't have a `my_build/` directory and can move on to the next step. diff --git a/content/tutorials/manage-the-rippled-server/installation/capacity-planning.md b/content/tutorials/manage-the-rippled-server/installation/capacity-planning.md index a7684f7250..9c8bfcd022 100644 --- a/content/tutorials/manage-the-rippled-server/installation/capacity-planning.md +++ b/content/tutorials/manage-the-rippled-server/installation/capacity-planning.md @@ -19,16 +19,16 @@ Ripple recommends you always use the largest node size your available RAM can su #### Recommendation -Each `node_size` has a corresponding requirement for available RAM. For example, if you set `node_size` to `huge`, you should have at least 32GB of available RAM to help ensure that `rippled` can run smoothly. +Each `node_size` has a corresponding requirement for available RAM. For example, if you set `node_size` to `huge`, you should have at least 32 GB of available RAM to help ensure that `rippled` can run smoothly. To tune your server, it may be useful to start with `tiny` and increase the size to `small`, `medium`, and so on as you refine the requirements for your use case. | RAM available for `rippled` | `node_size` value | Notes | |:----------------------------|:------------------|:---------------------------| -| < 8GB | `tiny` | Not recommended for testing or production servers. This is the default value if you don't specify a value in `rippled.cfg`. | -| 8GB | `small` | Recommended for test servers. | -| 16GB | `medium` | The `rippled-example.cfg` file uses this value. | -| 32GB | `huge` | Recommended for production servers. | +| < 8 GB | `tiny` | Not recommended for testing or production servers. This is the default value if you don't specify a value in `rippled.cfg`. | +| 8 GB | `small` | Recommended for test servers. | +| 16 GB | `medium` | The `rippled-example.cfg` file uses this value. | +| 32 GB | `huge` | Recommended for production servers. | Although `large` is also a legal value for `[node_size]`, in practice it performs worse than `huge` in most circumstances. Ripple recommends always using `huge` instead of `large`. @@ -53,7 +53,7 @@ The example `rippled-example.cfg` file has the `type` field in the `[node_db]` s #### More About Using RocksDB -[RocksDB](https://rocksdb.org/docs/getting-started.html) is an embeddable persistent key-value store. +[RocksDB](https://rocksdb.org/docs/getting-started.html) is an persistent key-value store built into `rippled`. RocksDB works well on solid-state disks. RocksDB performs better than NuDB when used with rotational disks, but you may still encounter performance problems unless you use solid-state disks. @@ -165,7 +165,7 @@ If you want to contribute to storing ledger history but you do not have enough d ##### Amazon Web Services -Amazon Web Services (AWS) is a popular virtualized hosting environment. You can run `rippled` in AWS, but Ripple does not recommend using Elastic Block Storage (EBS). Elastic Block Storage's maximum number of IOPS (5,000) is insufficient for `rippled`'s heaviest loads, despite being very expensive. +Amazon Web Services (AWS) is a popular virtualized hosting environment. You can run `rippled` in AWS, but Ripple does not recommend using Elastic Block Storage (EBS). Elastic Block Storage's maximum number of IOPS (5,000) is insufficient for `rippled`'s heaviest loads, despite being very expensive. AWS instance stores (`ephemeral` storage) do not have these constraints. Therefore, Ripple recommends deploying `rippled` servers with host types such as `M3` that have instance storage. The `database_path` and `node_db` path should each reside on instance storage. @@ -183,9 +183,9 @@ Here are examples of observed network bandwidth use for common `rippled` tasks: | Task | Transmit/Receive | |:------------------------------------------------|:---------------------------| -| Process current transaction volumes | 2Mbps transmit, 2 Mbps receive | -| Serve historical ledger and transaction reports | 100Mbps transmit | -| Start up `rippled` | 20Mbps receive | +| Process current transaction volumes | 2 Mbps transmit, 2 Mbps receive | +| Serve historical ledger and transaction reports | 100 Mbps transmit | +| Start up `rippled` | 20 Mbps receive | ## See Also diff --git a/content/tutorials/manage-the-rippled-server/installation/install-rippled-on-ubuntu.md b/content/tutorials/manage-the-rippled-server/installation/install-rippled-on-ubuntu.md index 2b02b37f18..c71dc84e4f 100644 --- a/content/tutorials/manage-the-rippled-server/installation/install-rippled-on-ubuntu.md +++ b/content/tutorials/manage-the-rippled-server/installation/install-rippled-on-ubuntu.md @@ -45,7 +45,7 @@ Before you install `rippled`, you must meet the [System Requirements](system-req The above example is appropriate for **Ubuntu 18.04 Bionic Beaver**. For other operating systems, replace the word `bionic` with one of the following: - - `xenial` for **Ubuntu 16.04 Xenial Xerus** + - `xenial` for **Ubuntu 16.04 Xenial Xerus** - `stretch` for **Debian 9 Stretch** If you want access to development or pre-release versions of `rippled`, use one of the following instead of `stable`: diff --git a/content/tutorials/manage-the-rippled-server/installation/system-requirements.md b/content/tutorials/manage-the-rippled-server/installation/system-requirements.md index 805bd98329..3e0c14db79 100644 --- a/content/tutorials/manage-the-rippled-server/installation/system-requirements.md +++ b/content/tutorials/manage-the-rippled-server/installation/system-requirements.md @@ -9,7 +9,9 @@ A `rippled` server should run comfortably on commodity hardware, to make it inex - Development: Mac OS X, Windows (64-bit), or most Linux distributions - CPU: 64-bit x86_64, 2+ cores - Disk: Minimum 50GB for the database partition. SSD strongly recommended (minimum 1000 IOPS, more is better) -- RAM: 8GB+ +- RAM: 8 GB+ + + Amazon EC2's `m3.large` VM size may be appropriate depending on your workload. A fast network connection is preferable. Any increase in a server's client-handling load increases resources needs. @@ -22,8 +24,8 @@ For best performance in enterprise production environments, Ripple recommends ru - CPU: Intel Xeon 3+ GHz processor with 4 cores and hyperthreading enabled - Disk: SSD (7000+ writes/second, 10,000+ reads/second) - RAM: - - For testing: 8GB+ - - For production: 32GB + - For testing: 8 GB+ + - For production: 32 GB - Network: Enterprise data center network with a gigabit network interface on the host ## System Time diff --git a/content/tutorials/manage-the-rippled-server/installation/update-rippled-automatically-on-linux.md b/content/tutorials/manage-the-rippled-server/installation/update-rippled-automatically-on-linux.md index 856c207185..f9069d3258 100644 --- a/content/tutorials/manage-the-rippled-server/installation/update-rippled-automatically-on-linux.md +++ b/content/tutorials/manage-the-rippled-server/installation/update-rippled-automatically-on-linux.md @@ -12,7 +12,7 @@ To set up automatic updates, complete the following steps: $ sudo ln -s /opt/ripple/etc/update-rippled-cron /etc/cron.d/ - This cron configuration runs a script to update the installed `rippled` package within an hour of each new release. To reduce the chance of outages from all servers updating simultaneously, the script delays the update for a random number of minutes, up to 59. + This configuration runs a script to update the installed `rippled` package within an hour of each new release. To reduce the chance of outages from all servers updating simultaneously, the script delays the update for a random number of minutes, up to 59. **Caution:** In the future, it is possible that changes to Ripple's repositories may require manual intervention to update the URLs where your script searches for updates. Stay tuned to the [XRP Ledger Blog](/blog/) or the [ripple-server mailing list](https://groups.google.com/forum/#!forum/ripple-server) for announcements on any required changes. diff --git a/content/tutorials/manage-the-rippled-server/stand-alone-mode/start-a-new-genesis-ledger-in-stand-alone-mode.md b/content/tutorials/manage-the-rippled-server/stand-alone-mode/start-a-new-genesis-ledger-in-stand-alone-mode.md index 317a99c800..93816e7f39 100644 --- a/content/tutorials/manage-the-rippled-server/stand-alone-mode/start-a-new-genesis-ledger-in-stand-alone-mode.md +++ b/content/tutorials/manage-the-rippled-server/stand-alone-mode/start-a-new-genesis-ledger-in-stand-alone-mode.md @@ -14,7 +14,7 @@ In a genesis ledger, the [genesis address](accounts.html#special-addresses) hold **Address:** `rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh` -**Secret:** `snoPBrXtMeMyMHUVTgbuqAfg1SUTb` ("masterpassphrase") +**Secret:** `snoPBrXtMeMyMHUVTgbuqAfg1SUTb` ("`masterpassphrase`") ## Settings in New Genesis Ledgers diff --git a/content/tutorials/manage-the-rippled-server/troubleshooting/diagnosing-problems.md b/content/tutorials/manage-the-rippled-server/troubleshooting/diagnosing-problems.md index 95a56a03b9..c6cff0df34 100644 --- a/content/tutorials/manage-the-rippled-server/troubleshooting/diagnosing-problems.md +++ b/content/tutorials/manage-the-rippled-server/troubleshooting/diagnosing-problems.md @@ -80,7 +80,7 @@ For troubleshooting purposes, the most important fields are (from most commonly - **`peers`** - This field indicates how many other servers in the XRP Ledger peer-to-peer network your server is connected to. Healthy servers typically show between 5 and 50 peers, unless explicitly configured to connect only to certain peers. - - If you have 0 peers, your server may be unable to contact the network, or your system clock may be wrong. (Ripple recommends running an [NTP](http://www.ntp.org/) daemon on all servers to keep their clocks synced.) + - If you have 0 peers, your server may be unable to contact the network, or your system clock may be wrong. (Ripple recommends running an [NTP](http://www.ntp.org/) daemon on all servers to keep their clocks synced.) - If you have exactly 10 peers, that may indicate that your `rippled` is unable to receive incoming connections through a router using [NAT](https://en.wikipedia.org/wiki/Network_address_translation). You can improve connectivity by configuring your router's firewall to forward the port used for peer-to-peer connections (port 51235 [by default](https://github.com/ripple/rippled/blob/8429dd67e60ba360da591bfa905b58a35638fda1/cfg/rippled-example.cfg#L1065)). @@ -149,7 +149,7 @@ To use the script: 3. Upload the output file where others can see it. - You can upload the file directly to [GitHub Gist](https://gist.github.com/), [Pastebin](https://pastebin.com/), or a similar service. If you are running `rippled` on a remote server, you may find it easier to first transfer the file to a machine with a web browser, using `scp` or a similar tool. + You can upload the file directly to [GitHub Gist](https://gist.github.com/), [Pastebin](https://pastebin.com/), or a similar service. If you are running `rippled` on a remote server, you may find it easier to first transfer the file to a machine with a web browser, using `scp` or a similar tool. ## See Also diff --git a/content/tutorials/use-complex-payment-types/use-checks/cash-a-check-for-a-flexible-amount.md b/content/tutorials/use-complex-payment-types/use-checks/cash-a-check-for-a-flexible-amount.md index bcf883f6f4..ee37ee87cf 100644 --- a/content/tutorials/use-complex-payment-types/use-checks/cash-a-check-for-a-flexible-amount.md +++ b/content/tutorials/use-complex-payment-types/use-checks/cash-a-check-for-a-flexible-amount.md @@ -164,7 +164,7 @@ If the Check was cashed for a flexible `DeliverMin` amount and succeeded, you ca - For XRP, the `AccountRoot` object of the Check's sender has its XRP `Balance` field debited. The `AccountRoot` object of the Check's recipient (the one who sent the CheckCash transaction) has its XRP `Balance` credited for at least the `DeliverMin` of the CheckCash transaction minus the [transaction cost](transaction-cost.html) of sending the transaction. - For example, the following `ModifiedNode` shows that the account rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis, the Check's recipient and the sender of this CheckCash transaction, had its XRP balance change from `9999999970` drops to `10099999960` drops, meaning the recipient was credited a _net_ of 99.99999 XRP as a result of processing the transaction. + For example, the following `ModifiedNode` shows that the account `rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis`, the Check's recipient and the sender of this CheckCash transaction, had its XRP balance change from `9999999970` drops to `10099999960` drops, meaning the recipient was credited a _net_ of 99.99999 XRP as a result of processing the transaction. { "ModifiedNode": { @@ -186,7 +186,7 @@ If the Check was cashed for a flexible `DeliverMin` amount and succeeded, you ca } } - The net amount of 99.99999 XRP includes deducting the transaction cost that is destroyed to pay for sending this CheckCash transaction. The following transaction instructions (excerpted) show that the transaction cost (the `Fee` field) was 10 drops of XRP. By adding this to the net balance change, we conclude that the recipient, rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis, was credited a _gross_ amount of exactly 100 XRP for cashing the Check. + The net amount of 99.99999 XRP includes deducting the transaction cost that is destroyed to pay for sending this CheckCash transaction. The following part of the transaction instructions shows that the transaction cost (the `Fee` field) was 10 drops of XRP. By adding this to the net balance change, we conclude that the recipient, `rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis`, was credited a _gross_ amount of exactly 100 XRP for cashing the Check. "Account" : "rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis", "TransactionType" : "CheckCash", diff --git a/content/tutorials/use-complex-payment-types/use-escrows/send-a-conditionally-held-escrow.md b/content/tutorials/use-complex-payment-types/use-escrows/send-a-conditionally-held-escrow.md index ec2b7a6671..cad7702c72 100644 --- a/content/tutorials/use-complex-payment-types/use-escrows/send-a-conditionally-held-escrow.md +++ b/content/tutorials/use-complex-payment-types/use-escrows/send-a-conditionally-held-escrow.md @@ -2,10 +2,10 @@ ## 1. Generate condition and fulfillment -XRP Ledger escrows require PREIMAGE-SHA-256 [crypto-conditions][]. To calculate a condition and fulfillment in the proper format, you should use a crypto-conditions library such as [five-bells-condition](https://github.com/interledgerjs/five-bells-condition). For fulfillments, the following methods are recommended to generate the fulfillment: +XRP Ledger escrows require PREIMAGE-SHA-256 [crypto-conditions][]. To calculate a condition and fulfillment in the proper format, you should use a crypto-conditions library such as [five-bells-condition](https://github.com/interledgerjs/five-bells-condition). To generate the fulfillment: - Use a cryptographically secure source of randomness to generate at least 32 random bytes. -- Follow Interledger Protocol's [PSK specification](https://github.com/interledger/rfcs/blob/master/deprecated/0016-pre-shared-key/0016-pre-shared-key.md) and use an HMAC-SHA-256 of the ILP packet as the fulfillment. +- Follow Interledger Protocol's [PSK specification](https://github.com/interledger/rfcs/blob/master/deprecated/0016-pre-shared-key/0016-pre-shared-key.md) and use an HMAC-SHA-256 of the ILP packet as the fulfillment. Example JavaScript code for a random fulfillment and condition: @@ -62,7 +62,7 @@ print(cancel_after) -**Warning:** In the XRP Ledger, you must specify time as **seconds since the Ripple Epoch** (2000-01-01T00:00:00Z). If you use a UNIX time in the `CancelAfter` or `FinishAfter` field without converting to the equivalent Ripple time first, that sets the unlock time to an extra **30 years** in the future! +**Warning:** In the XRP Ledger, you must specify time as **[seconds since the Ripple Epoch][]**. If you use a UNIX time in the `CancelAfter` or `FinishAfter` field without converting it, that sets the unlock time to an extra **30 years** in the future! ## 3. Submit EscrowCreate transaction diff --git a/content/tutorials/use-complex-payment-types/use-payment-channels.md b/content/tutorials/use-complex-payment-types/use-payment-channels.md index 23c59e4b5c..f275a8cde7 100644 --- a/content/tutorials/use-complex-payment-types/use-payment-channels.md +++ b/content/tutorials/use-complex-payment-types/use-payment-channels.md @@ -10,10 +10,10 @@ The example addresses used in this tutorial are: | | | |--|--| -| **Payer's address** | rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH | -| **Public key used for channel (in the XRP Ledger's [base58][] encoded string format)** | aB44YfzW24VDEJQ2UuLPV2PvqcPCSoLnL7y5M1EzhdW4LnK5xMS3 -| **Public key used for channel (in hex)** | 023693F15967AE357D0327974AD46FE3C127113B1110D6044FD41E723689F81CC6 | -| **Payee's address** | rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn | +| **Payer's address** | `rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH` | +| **Public key used for channel (in the XRP Ledger's [base58][] encoded string format)** | `aB44YfzW24VDEJQ2UuLPV2PvqcPCSoLnL7y5M1EzhdW4LnK5xMS3` +| **Public key used for channel (in hex)** | `023693F15967AE357D0327974AD46FE3C127113B1110D6044FD41E723689F81CC6` | +| **Payee's address** | `rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn` | **Tip:** In this example, the channel's public key is the public key from the payer's master key pair. This is perfectly safe and valid. It is also perfectly safe and valid to use a different key pair, as long as only the payer knows the public and secret keys for that key pair. @@ -49,7 +49,7 @@ This is a [PaymentChannelCreate transaction][]. As part of this process, the pay **Tip:** The "settlement delay" does not delay the settlement, which can happen as fast as a ledger version closes (3-5 seconds). The "settlement delay" is a forced delay on closing the channel so that the payee has a chance to finish with settlement. -The following example shows creation of a payment channel by [submitting](submit.html#sign-and-submit-mode) to a local `rippled` server with the JSON-RPC API. The payment channel allocates 100 XRP from the [example payer](#example-values) (rN7n7...) to the [example payee](#example-values) (rf1Bi...) with a settlement delay of 1 day. The public key is the example payer's master public key, in hexadecimal. +The following example shows creation of a payment channel by [submitting](submit.html#sign-and-submit-mode) to a local `rippled` server with the JSON-RPC API. The payment channel allocates 100 XRP from the [example payer](#example-values) (rN7n7...) to the [example payee](#example-values) (rf1Bi...) with a settlement delay of 1 day. The public key is the example payer's master public key, in hexadecimal. **Note:** A payment channel counts as one object toward the payer's [owner reserve](reserves.html#owner-reserves). The owner must keep at least enough XRP to satisfy the reserve after subtracting the XRP allocated to the payment channel. @@ -154,7 +154,7 @@ In the response from the JSON-RPC, the payer should look for the following: - In the transaction's `meta` field, confirm that the `TransactionResult` is `tesSUCCESS`. - Confirm that the response has `"validated":true` to indicate the data comes from a validated ledger. (The result `tesSUCCESS` is only [final](finality-of-results.html) if it appears in a validated ledger version.) -- In the `AffectedNodes` array of the transaction's `meta` field, look for a `CreatedNode` object with the `LedgerEntryType` of `PayChannel`. The `LedgerIndex` field of the `CreatedNode` object indicates the Channel ID. (In the above example, this is a hex string starting with "5DB0...") The Channel ID is necessary later to sign claims. +- In the `AffectedNodes` array of the transaction's `meta` field, look for a `CreatedNode` object with the `LedgerEntryType` of `PayChannel`. The `LedgerIndex` field of the `CreatedNode` object indicates the Channel ID. (In the above example, this is a hex string starting with "`5DB0`...") The Channel ID is necessary later to sign claims. For more information on the PayChannel ledger object type, see [PayChannel ledger object](paychannel.html). @@ -430,6 +430,8 @@ If the channel _does_ have XRP remaining, the request to close a channel acts as The payee can also close a payment channel immediately after processing a claim _(9b in the [flow diagram][])_. + + Example of [submitting a transaction](submit.html#sign-and-submit-mode) requesting a channel to close: { @@ -471,7 +473,7 @@ Example `account_channels` response: } } -In this example, the `expiration` value 547073182 in [seconds since the Ripple Epoch][] maps to 2017-05-02T20:46:22Z, so any claims not redeemed by that time are no longer valid. +In this example, the `expiration` value 547073182 in [seconds since the Ripple Epoch][] maps to `2017-05-02T20:46:22Z`, so any claims not redeemed by that time are no longer valid. ## 10. Anyone can close the expired channel. diff --git a/content/tutorials/xrp-ledger-businesses/list-xrp-as-an-exchange.md b/content/tutorials/xrp-ledger-businesses/list-xrp-as-an-exchange.md index 9b7f3ec052..7b94a90e8f 100644 --- a/content/tutorials/xrp-ledger-businesses/list-xrp-as-an-exchange.md +++ b/content/tutorials/xrp-ledger-businesses/list-xrp-as-an-exchange.md @@ -48,7 +48,7 @@ Before integrating, exchanges should be aware of the [partial payments](partial- #### Partial Payments Warning -When the [tfPartialPayment flag](payment.html#payment-flags) is enabled, the `Amount` field **_is not guaranteed to be the amount received_**. The `delivered_amount` field of a payment's metadata indicates the amount of currency actually received by the destination account. When receiving a payment, use `delivered_amount` instead of the Amount field to determine how much your account received instead. +When the [`tfPartialPayment` flag](payment.html#payment-flags) is enabled, the `Amount` field **_is not guaranteed to be the amount received_**. The `delivered_amount` field of a payment's metadata indicates the amount of currency actually received by the destination account. When receiving a payment, use `delivered_amount` instead of the Amount field to determine how much your account received instead. **Warning:** Be aware that malicious actors could exploit this. For more information, see [Partial Payments](partial-payments.html). @@ -74,7 +74,7 @@ To follow Ripple's recommended best practices, Alpha Exchange should create at l * The malicious actor could issue currency in the XRP Ledger by using the cold wallet, but that currency should not be valued by anyone (unless the exchange explicitly stated it was also a gateway). - * If a malicious actor sets the asfRequireAuth flag for the account, that cannot be unset, although this only relates to issuing currency and should not affect an exchange that is not also a gateway. Any other settings a malicious actor changes with a master key can be reverted. + * If a malicious actor sets the `asfRequireAuth` flag for the account, that cannot be unset, although this only relates to issuing currency and should not affect an exchange that is not also a gateway. Any other settings a malicious actor changes with a master key can be reverted. * One or more [_hot wallets_](issuing-and-operational-addresses.html#operational-addresses) to conduct the day-to-day business of managing customers' XRP withdrawals and deposits. For example, with a hot wallet, exchanges can securely support these types of automated XRP transfers. Hot wallets need to be online to service instant withdrawal requests. @@ -119,7 +119,7 @@ XRP Balances User Balance - Acct # + Account # User Balance @@ -235,7 +235,7 @@ XRP Balances User Balance - Acct # + Account # User Balance @@ -306,7 +306,7 @@ A user named Charlie wants to deposit 50,000 XRP to Alpha Exchange. Doing this i 1. Charlie submits a payment of 50,000 XRP (by using [RippleAPI](rippleapi-reference.html) or similar software) to Alpha Exchange's [cold wallet](#accounts). - a. Charlie adds an identifier (in this case, `789`) to the payment to associate it with his account at Alpha Exchange. This is called a [_destination tag_](become-an-xrp-ledger-gateway.html#source-and-destination-tags). (To use this, Alpha Exchange should have set the asfRequireDest flag on all of its accounts to require all incoming payments to have a destination tag like Charlie's. For more information, see [AccountSet Flags](accountset.html#accountset-flags)). + a. Charlie adds an identifier (in this case, `789`) to the payment to associate it with his account at Alpha Exchange. This is called a [_destination tag_](become-an-xrp-ledger-gateway.html#source-and-destination-tags). (To use this, Alpha Exchange should have set the `asfRequireDest` flag on all of its accounts to require all incoming payments to have a destination tag like Charlie's. For more information, see [AccountSet Flags](accountset.html#accountset-flags)). 2. The software at Alpha Exchange detects the incoming payment, and recognizes `789` as the destination tag for Charlie’s account. @@ -329,7 +329,7 @@ XRP Balances User Balance - Acct # + Account # User Balance @@ -428,7 +428,7 @@ Off-Ledger Balances - Acct # + Account # User Balance @@ -520,7 +520,7 @@ Off-Ledger Balances User Balance - Acct # + Account # User Balance diff --git a/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md b/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md index e96d42a5de..75c3fbe0e0 100644 --- a/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md +++ b/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md @@ -10,7 +10,7 @@ To enable XRP Charts to list your exchange, you'll need to make the following da Then, you'll need to [send an exchange listing request to XRP Charts](#send-an-exchange-listing-request-to-xrp-charts). -If you have any questions about endpoint specifications, contact . +If you have any questions about endpoint specifications, contact . ## Provide a Recently Executed Trades Endpoint diff --git a/tool/spelling.txt b/tool/spelling.txt index 02ed2224bb..b9c1cad1d2 100644 --- a/tool/spelling.txt +++ b/tool/spelling.txt @@ -11,7 +11,6 @@ backend backfilling backfills billionths -bitcoin bitwise blockchain blog @@ -21,7 +20,6 @@ callbacks canceled canceling cannot -centos codebase colocation commandline @@ -34,7 +32,6 @@ cryptographically csv datacenter ddos -debian debug decrypt denominate @@ -64,9 +61,8 @@ firewalls fulfills gapped geolocation +ghz gigabit -github -google haven't hardcoded hashed @@ -93,14 +89,14 @@ ipv4 ipv6 isn't iterating -firefox javascript json -linux loopback lowercase maintainer malware +mbps +md5 metadata mitigations modulo @@ -108,7 +104,6 @@ namespace nonces npm onboarding -openssl outages overwriting paginate @@ -136,7 +131,6 @@ reconfigure reconfiguring reconnecting reconnects -redhat refunding renumbering reorders @@ -145,9 +139,9 @@ retriable retries retried retrying -rhel roadmaps sandbox +scammers serialize serialized serializing @@ -160,6 +154,7 @@ subfolder subfolders supermajority svg +symlink synced synchronizing syncing @@ -184,7 +179,6 @@ triskelion troubleshoot truncates typos -ubuntu unauthorize uncomment undesirably @@ -206,6 +200,8 @@ urls utc validator versioning +virtualization +virtualized wasn't we'll won't @@ -216,13 +212,28 @@ whitespace workaround writable wss -xeon xml you'll you're you've zeroes +bitcoin +centos +debian +firefox +github +google +linux +nginx +openssl +redhat +rhel +ubuntu +xenial +xeon +xerus + btc cny eur @@ -266,6 +277,7 @@ channel_verify checkcancel checkcash checkcreate +cmake consensus_info cors crawl_shards @@ -325,6 +337,7 @@ ledger_accept ledger_cleaner ledger_closed ledger_current +ledger_data ledger_entry ledger_request ledgerhashes @@ -332,16 +345,17 @@ log_level logrotate lz4 mainnet -md5 +micropayments multisign multisigning multisignreserve -nginx noripple +noripple_check nudb ownerpaysfee path_find pathfinding +pathset paychan paychannel paymentchannelclaim @@ -370,6 +384,7 @@ shor sign_for signerlist signerlistset +statsd submit_multisigned suspay testnet @@ -386,5 +401,6 @@ validation_create validation_seed validator_info validator_list_sites +vector256 xpring xrpchat