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

Merge pull request #515 from ripple/rippled_1.2.0

Browse Source 
rippled 1.2.0 docs
This commit is contained in:
Rome Reginelli
2019-02-13 13:41:18 -08:00
committed by GitHub
parent e94c500080 823544073b
commit 7adc4cadf4
23 changed files with 352 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -46,7 +46,9 @@
"channel_verify",
"connect",
"consensus_info",
"crawl_shards",
"deposit_authorized",
"download_shard",
"feature",
"fee",
"fetch_info",

1
content/_snippets/rippled_versions.md
View File

@@ -33,3 +33,4 @@
[New in: rippled 0.90.0]: https://github.com/ripple/rippled/releases/tag/0.90.0 "BADGE_BLUE"
[New in: rippled 1.0.0]: https://github.com/ripple/rippled/releases/tag/1.0.0 "BADGE_BLUE"
[New in: rippled 1.1.0]: https://github.com/ripple/rippled/releases/tag/1.1.0 "BADGE_BLUE"
[New in: rippled 1.2.0]: https://github.com/ripple/rippled/releases/tag/1.2.0 "BADGE_BLUE"

14
content/concepts/consensus-network/transaction-queue.md
View File

@@ -28,11 +28,15 @@ The transaction queue plays an important role in selecting the transactions that
The `rippled` server uses a variety of heuristics to estimate which transactions are "likely to be included in a ledger." The current implementation uses the following rules to decide which transactions to queue:
* Transactions must be properly-formed and [authorized](transaction-basics.html#authorizing-transactions) with valid signatures.
* Transactions with an `AccountTxnID` field cannot be queued.
* A single sending address can have at most 10 transactions queued at the same time. In order for a transaction to be queued, the sender must have enough XRP to pay all the XRP costs of all the sender's queued transactions including both the `Fee` fields and the sum of the XRP that each transaction could send. [New in: rippled 0.32.0][]
* If a transaction affects how the sending address authorizes transactions, no other transactions from the same address can be queued behind it. [New in: rippled 0.32.0][]
* If a transaction includes a `LastLedgerSequence` field, the value of that field must be at least **the current ledger index + 2**.
- Transactions must be properly-formed and [authorized](transaction-basics.html#authorizing-transactions) with valid signatures.
- Transactions with an `AccountTxnID` field cannot be queued.
- A single sending address can have at most 10 transactions queued at the same time.
- To queue a transaction, the sender must have enough XRP for all of the following: [Updated in: rippled 1.2.0][New in: rippled 1.2.0]
- Destroying the XRP [transaction cost](transaction-cost.html) as specified in the `Fee` fields of all the sender's queued transactions. The total amount among queued transactions cannot be more than the base account reserve (currently 20 XRP). (Transactions paying significantly more than the minimum transaction cost of 0.00001 XRP typically skip the queue and go straight into the open ledger.)
- Sending the maximum sum of XRP that all the sender's queued transactions could send.
- Keeping enough XRP to meet the account's [reserve requirements](reserves.html).
- If a transaction affects how the sending address authorizes transactions, no other transactions from the same address can be queued behind it. [New in: rippled 0.32.0][]
- If a transaction includes a `LastLedgerSequence` field, the value of that field must be at least **the current ledger index + 2**.
### Fee Averaging

2
content/concepts/decentralized-exchange/offers.md
View File

@@ -15,6 +15,8 @@ An offer in the ledger can be fulfilled either by additional OfferCreate transac
You can create an offer so long as you have at least some (any positive, nonzero amount) of the currency specified by the `TakerGets` parameter of the offer. The offer sells as much of the currency as you have, up to the `TakerGets` amount, until the `TakerPays` amount is satisfied. An offer cannot place anyone in debt.
If you place an offer that crosses any offers you have existing in the ledger, the old offers are automatically canceled regardless of the amounts involved.
It is possible for an offer to become temporarily or permanently _unfunded_:
* If the creator no longer has any of the `TakerGets` currency.

2
content/concepts/introduction/xrp-ledger-overview.md
View File

@@ -30,6 +30,8 @@ This combines qualities of physical and centralized digital money. Prior to the
The XRP Ledger's system of trusted validators uses a small amount of human interaction to achieve better distribution of authority than other decentralized systems. Fully-automated systems for reaching consensus from an unknown set of participants are vulnerable to concentrations of voting power. For example, Bitcoin mining is disproportionately concentrated in places with cheap electricity. As Ripple curates a list of distinct validators operated by different entities in different jurisdictions, the XRP Ledger can become more resistant to censorship and outside pressures than proof-of-work mining. For more information on Ripple's plan to decentralize the recommended set of validators, see the [Decentralization Strategy Update](https://ripple.com/dev-blog/decentralization-strategy-update/).
For more information about the XRP Ledger's ability to detect censorship, see [Transaction Censorship Detection](transaction-censorship-detection.html).
## Fast, Efficient Consensus Algorithm
[Fast, Efficient Consensus Algorithm]: #fast-efficient-consensus-algorithm

9
content/concepts/issued-currencies/rippling.md
View File

@@ -4,8 +4,9 @@ In the XRP Ledger, "rippling" describes a process of atomic net settlement betwe
Rippling only occurs along the [paths](paths.html) of a payment.
For non-issuing accounts, rippling can be undesirable because it lets other users shift obligations between issuers of the same currency. Thus, the [NoRipple Flag](#the-noripple-flag) disables rippling on all trust lines by default, unless the account enables rippling by default by enabling the [DefaultRipple flag](#the-defaultripple-flag).
For non-issuing accounts, rippling can be undesirable because it lets other users shift obligations between issuers of the same currency. Thus, the [NoRipple Flag](#the-noripple-flag) disables rippling on incoming trust lines by default, unless the account enables rippling by default by enabling the [DefaultRipple flag](#the-defaultripple-flag).
**Caution:** If you create a trust line to another address, you must explicitly enable the tfSetNoRipple flag to block rippling on your side of that trust line.
## Example of Rippling
@@ -25,7 +26,7 @@ Non-issuing accounts, especially liquidity providers who may hold balances from
The "NoRipple" flag is a setting on a trust line. When two trust lines both have NoRipple enabled by the same address, payments from third parties cannot "ripple" through that address on those trust lines. This protects liquidity providers from having balances shift unexpectedly between different issuers of the same currency.
An account can disable NoRipple on a single trust line, which can allow rippling through any pair that includes that trust line. The account can also enable rippling globally by enabling the [DefaultRipple flag](#the-defaultripple-flag).
An account can disable NoRipple on a single trust line, which can allow rippling through any pair that includes that trust line. The account can also enable rippling by default by enabling the [DefaultRipple flag](#the-defaultripple-flag).
For example, imagine Emily has money issued by two different financial institutions, like so
@@ -52,7 +53,9 @@ The NoRipple flag makes certain paths invalid, so that they cannot be used to ma
## The DefaultRipple Flag
The DefaultRipple flag is an account setting that enables rippling on all trust lines by default. Gateways and other currency issuers MUST enable this flag for other addresses to be able to send those the currencies among themselves.
The DefaultRipple flag is an account setting that enables rippling on all incoming trust lines by default. Gateways and other currency issuers MUST enable this flag for their customers to be able to send those currencies to each other.
The DefaultRipple setting of your account does not affect trust lines that you create; only trust lines that others open to you. If you change the DefaultRipple setting of your account, trust lines that were created before the change keep their existing NoRipple settings. You can use a [TrustSet transaction][] to change the NoRipple setting of a trust line to match your address's new default.
For more information, see [DefaultRipple in 'Becoming an XRP Ledger Gateway'](become-an-xrp-ledger-gateway.html#defaultripple).

2
content/concepts/payment-system-basics/accounts/reserves.md
View File

@@ -21,7 +21,7 @@ Many objects in the ledger are owned by a particular address, and count toward t
- [Offers](offer.html) are owned by the address that placed them. Transaction processing automatically removes Offers that are fully consumed or found to be unfunded. Alternatively, the owner can cancel an Offer by sending an [OfferCancel transaction][], or by sending an [OfferCreate transaction][] that contains an `OfferSequence` parameter.
- [Trust lines](ripplestate.html) are shared between two addresses. The owner reserve can apply to one or both of the addresses, depending on whether the fields that address controls are in their default state. See [Contributing to the Owner Reserve](ripplestate.html#contributing-to-the-owner-reserve) for details.
- A single [SignerList](signerlist.html) counts as 3 to 10 objects for purposes of the owner reserve, depending on how many members it has. See also: [SignerLists and Reserves](signerlist.html#signerlists-and-reserves).
- Without the [MultiSignReserve amendment](known-amendments.html#multisignreserve), a single [SignerList](signerlist.html) counts as 3 to 10 objects for purposes of the owner reserve, depending on how many members it has. With the [MultiSignReserve amendment](known-amendments.html#multisignreserve) enabled, a single SignerList counts as 1 object for purposes of the owner reserve, regardless of the number of members it has. See also: [SignerLists and Reserves](signerlist.html#signerlists-and-reserves).
- [Held Payments (Escrow)](escrow-object.html) are owned by the address that placed them.
- [Payment Channels](use-payment-channels.html) are owned by the address that created them.
- [Owner directories](directorynode.html) list all the ledger objects that contribute to an address's owner reserve. However, the owner directory itself does not count towards the reserve.

3
content/concepts/the-rippled-server/ledger-history/history-sharding.md
View File

@@ -27,7 +27,8 @@ The history of all ledgers is shared by servers agreeing to keep particular rang
## See Also
- [Configure History Sharding](configure-history-sharding.html)
<!--{# - [download_shard method][] #}-->
- [download_shard method][]
- [crawl_shards method][]
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}

61
content/concepts/the-rippled-server/transaction-censorship-detection.md Normal file
View File

@@ -0,0 +1,61 @@
# Transaction Censorship Detection
[New in: rippled 1.2.0][]
The XRP Ledger is designed to be [censorship resistant](xrp-ledger-overview.html#censorship-resistant-transaction-processing). In support of this design, the XRP Ledger provides an automated transaction censorship detector that is available on all `rippled` servers, enabling all participants to see if censorship is affecting the network.
While a `rippled` server is in sync with the network, the detector tracks all transactions that, in the view of the `rippled` server, should have been accepted in the last round of [consensus](intro-to-consensus.html) and included in the last validated ledger. The detector issues log messages of increasing severity for transactions that have not been included in a validated ledger after several rounds of consensus.
## How It Works
At a high-level, here’s how the transaction censorship detector works:
1. The detector adds all transactions in a `rippled` server's initial consensus proposal to the tracker.
2. At the close of the consensus round, the detector removes all transactions included in the resulting validated ledger from the tracker.
3. The detector issues a [warning message](#example-warning-message) in the log for any transaction that remains in the tracker for 15 ledgers, surfacing it as a potentially censored transaction. The transaction's presence in the tracker at this time means that is has not been included in a validated ledger after 15 rounds of consensus. If the transaction remains in the tracker for another 15 ledgers, the detector issues another warning message in the log.
For as long as the transaction remains in the tracker, the detector continues to issue a warning message in the log every 15 ledgers, for up to five warning messages. After the fifth warning message, the detector issues a final [error message](#example-error-message) in the log and then stops issuing warning and error messages.
If you see these messages in your `rippled` server log, you should investigate why other servers are failing to include the transaction, starting with the assumption that the cause is more likely to be a [false positive](#potential-false-positives) (innocent bug) than malicious censorship.
## Example Warning Message
This is an example warning message issued by the transaction censorship detector after transaction E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7 remained in the tracker for 15 ledgers, from ledger 18851530 to ledger 18851545.
```text
LedgerConsensus:WRN Potential Censorship: Eligible tx E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7, which we are tracking since ledger 18851530 has not been included as of ledger 18851545.
```
## Example Error Message
This is an example error message issued by the transaction censorship detector after transaction E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7 remained in the tracker for 75 ledgers (5 sets of 15 ledgers), from ledger 18851530 to ledger 18851605.
```text
LedgerConsensus:ERR Potential Censorship: Eligible tx E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7, which we are tracking since ledger 18851530 has not been included as of ledger 18851605. Additional warnings suppressed.
```
## Potential False Positives
The transaction censorship detector may issue false positives in certain scenarios. In this case, a false positive means that the detector has flagged a transaction that has remained in the tracker for 15 ledgers or more, but for innocent reasons.
Here are some scenarios that could cause the detector to issue false positive messages:
- Your `rippled` server is running a build with code that is different from the rest of the network. This may cause your `rippled` server to apply transactions differently, resulting in false positives. While this type of false positive is unlikely, in general, it is crucial that you run the correct version of `rippled`.
- Your `rippled` server is out of sync with the network and has not yet realized it.
- `rippled` servers in the network, including possibly your own server, are being impacted by a class of bug that causes `rippled` servers to inconsistently relay transactions to other `rippled` servers in the network.
Currently, there are no known bugs that cause this unexpected behavior. However, if you see the impact of what you suspect is a bug, consider reporting it to the [Ripple Bug Bounty](https://ripple.com/bug-bounty/) program.
{% include '_snippets/rippled_versions.md' %}

137
content/references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/crawl_shards.md Normal file
View File

@@ -0,0 +1,137 @@
# crawl_shards
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/CrawlShards.cpp "Source")
Requests information from peer servers about which [shards of historical ledger data](history-sharding.html) they have available. [New in: rippled 1.2.0][]
_The `crawl_shards` method is an [admin method](admin-rippled-methods.html) that cannot be run by unprivileged users._
### Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```json
{
"command": "crawl_shards",
"pubkey": true,
"limit": 0
}
```
*JSON-RPC*
```json
{
"method": "crawl_shards",
"params": [
{
"pubkey": true,
"limit": 0
}
]
}
```
<!-- MULTICODE_BLOCK_END -->
**Note:** There is no command-line syntax for this method. Use the [json method][] to access this from the command line.
The request includes the following fields:
| `Field` | Type | Description |
|:---------|:--------|:--------------------------------------------------------|
| `pubkey` | Boolean | _(Optional)_ If `true`, the response includes the node public keys (for peer-to-peer communications) of servers that were crawled. The default is `false`. |
| `limit` | Number | _(Optional)_ How many hops deep to search. The default is 0, which searches direct peers only. With a limit of `1`, searches peers' peers also. The maximum value is `3`. |
**Caution:** The number of peers potentially searched grows exponentially as `limit` increases. With a limit of 2 or 3, it can take several seconds for the server to respond to the API request.
### Response Format
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```json
{
"result": {
"complete_shards": "1-2,5,8-9,584,1973,2358",
"peers": [
{
"complete_shards": "1-2,8,47,371,464,554,653,857,1076,1402,1555,1708,1813,1867",
"public_key": "n9LxFZiySnfDSvfh23N94UxsFkCjWyrchTeKHcYE6tJJQL5iejb2"
},
{
"complete_shards": "8-9,584",
"ip": "192.168.1.132",
"public_key": "n9MN5xwYqbrj64rtfZAXQy7Y3sNxXZJeLt7Lj61a9DYEZ4SE2tQQ"
}
]
},
"status": "success",
"type": "response"
}
```
*JSON-RPC*
```json
200 OK
{
"result": {
"complete_shards": "1-2,5,8-9,584,1973,2358",
"peers": [
{
"complete_shards": "1-2,8,47,371,464,554,653,857,1076,1402,1555,1708,1813,1867",
"public_key": "n9LxFZiySnfDSvfh23N94UxsFkCjWyrchTeKHcYE6tJJQL5iejb2"
},
{
"complete_shards": "8-9,584",
"ip": "192.168.1.132",
"public_key": "n9MN5xwYqbrj64rtfZAXQy7Y3sNxXZJeLt7Lj61a9DYEZ4SE2tQQ"
}
],
"status": "success"
}
}
```
<!-- MULTICODE_BLOCK_END -->
The response follows the [standard format][], with a successful result containing the following fields:
| `Field` | Type | Description |
|:------------------|:-------|:------------------------------------------------|
| `complete_shards` | String | _(May be omitted)_ The range of [history shards](history-sharding.html) that are available on the local server. This may be an empty string, or a disjointed range. For example, `1-2,5,7-9` indicates that shards 1, 2, 5, 7, 8, and 9 are available. Omitted if this server does not have history sharding enabled. |
| `peers` | Array | List of **Peer Shard Objects** (see below) describing which history shards each peer has available. |
#### Peer Shard Objects
Each member of the `peers` array of the response is an object that describes one server in the peer-to-peer network. The list only includes peers that have at least one complete [history shard](history-sharding.html) available. Each object in the array has the following fields:
| `Field` | Type | Description |
|:----------|:-------|:--------------------------------------------------------|
| `complete_shards` | String | The range of history shards this peer has available. This may be disjointed. For example, `1-2,5,7-9` indicates that shards 1, 2, 5, 7, 8, and 9 are available. |
| `ip` | String | _(May be omitted)_ The IP address of the peer this object describes. This may be an IPv4 or IPv6 address. Omitted if this is a [private peer](peer-protocol.html#private-peers). |
| `public_key` | String | _(Omitted unless the request specified `"pubkey": true`)_ The public key this peer uses for peer-to-peer communications, in the XRP Ledger's [base58 format](base58-encodings.html). |
### Possible Errors
- Any of the [universal error types][].
- `invalidParams` - One or more required fields were omitted from the request, or a provided field was specified as the wrong data type.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

46
content/references/rippled-api/ledger-data-formats/ledger-object-types/signerlist.md
View File

@@ -42,16 +42,16 @@ The `SignerList` object type represents a list of parties that, as a group, are
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. No flags are defined for the SignerList type, so this value is always `0`. |
| `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. |
| `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. |
| 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). |
| `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. |
| `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.
@@ -59,16 +59,32 @@ The `SignerEntries` may be any combination of funded and unfunded addresses that
Each member of the `SignerEntries` field is an object that describes that signer in the list. A SignerEntry 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. |
| 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. |
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.
## {{currentpage.name}} Flags
_Requires the [MultiSignReserve Amendment](known-amendments.html#multisignreserve)._
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](known-amendments.html#multisignreserve) is enabled. |
## SignerLists and Reserves
A SignerList contributes to its owner's [reserve requirement](reserves.html). 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.
A SignerList contributes to its owner's [reserve requirement](reserves.html).
Without the [MultiSignReserve Amendment](known-amendments.html#multisignreserve), 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.
With the [MultiSignReserve Amendment](known-amendments.html#multisignreserve) 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][].
## SignerList ID Format

2
content/references/rippled-api/public-rippled-methods/ledger-methods/ledger_entry.md
View File

@@ -80,7 +80,7 @@ The full list of parameters recognized by this method is as follows:
| `ripple_state` | Object | _(Optional)_ Object specifying the RippleState (trust line) object to retrieve. The `accounts` and `currency` sub-fields are required to uniquely specify the RippleState entry to retrieve. |
| `ripple_state.accounts` | Array | _(Required if `ripple_state` is specified)_ 2-length array of account [Address][]es, defining the two accounts linked by this [RippleState object](ripplestate.html). |
| `ripple_state.currency` | String | _(Required if `ripple_state` is specified)_ [Currency Code][] of the [RippleState object](ripplestate.html) to retrieve. |
| `binary` | Boolean | _(Optional)_ If true, return the requested ledger object's contents as a hex string. Otherwise, return data in JSON format. The default is `true` if searching by `index` and `false` otherwise. |
| `binary` | Boolean | _(Optional)_ If true, return the requested ledger object's contents as a hex string. Otherwise, return data in JSON format. The default is `false`. [Updated in: rippled 1.2.0][New in: rippled 1.2.0] |
| `ledger_hash` | String | _(Optional)_ A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) |
| `ledger_index` | String or Unsigned Integer | _(Optional)_ The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |

3
content/references/rippled-api/public-rippled-methods/server-info-methods/server_info.md
View File

@@ -115,6 +115,7 @@ An example of a successful response:
"pubkey_node": "n94UE1ukbq6pfZY9j54sv2A1UrEeHZXLbns3xK5CzU9NbNREytaa",
"pubkey_validator": "n9KM73uq5BM3Fc6cxG3k5TruvbLc8Ffq17JZBmWC4uP4csL4rFST",
"server_state": "proposing",
"server_state_duration_us": 92762334,
"state_accounting": {
"connected": {
"duration_us": "150510079",
@@ -233,6 +234,7 @@ An example of a successful response:
"pubkey_validator" : "n9KM73uq5BM3Fc6cxG3k5TruvbLc8Ffq17JZBmWC4uP4csL4rFST",
"published_ledger" : 24901158,
"server_state" : "proposing",
"server_state_duration_us": 708078257,
"state_accounting" : {
"connected" : {
"duration_us" : "854824665",
@@ -301,6 +303,7 @@ The `info` object may have some arrangement of the following fields:
| `pubkey_node` | String | Public key used to verify this server for peer-to-peer communications. This _node key pair_ is automatically generated by the server the first time it starts up. (If deleted, the server can create a new pair of keys.) You can set a persistent value in the config file using the `[node_seed]` config option, which is useful for [clustering](clustering.html). |
| `pubkey_validator` | String | _(Admin only)_ Public key used by this node to sign ledger validations. This _validation key pair_ is derived from the `[validator_token]` or `[validation_seed]` config field. |
| `server_state` | String | A string indicating to what extent the server is participating in the network. See [Possible Server States](rippled-server-states.html) for more details. |
| `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][] |

3
content/references/rippled-api/public-rippled-methods/server-info-methods/server_state.md
View File

@@ -106,6 +106,7 @@ An example of a successful response:
"pubkey_node": "n94UE1ukbq6pfZY9j54sv2A1UrEeHZXLbns3xK5CzU9NbNREytaa",
"pubkey_validator": "n9KM73uq5BM3Fc6cxG3k5TruvbLc8Ffq17JZBmWC4uP4csL4rFST",
"server_state": "proposing",
"server_state_duration_us": 92762334,
"state_accounting": {
"connected": {
"duration_us": "150510079",
@@ -202,6 +203,7 @@ An example of a successful response:
"pubkey_node" : "n94UE1ukbq6pfZY9j54sv2A1UrEeHZXLbns3xK5CzU9NbNREytaa",
"pubkey_validator" : "n9KM73uq5BM3Fc6cxG3k5TruvbLc8Ffq17JZBmWC4uP4csL4rFST",
"server_state" : "proposing",
"server_state_duration_us": 708078257,
"state_accounting" : {
"connected" : {
"duration_us" : "150510079",
@@ -268,6 +270,7 @@ The `state` object may have some arrangement of the following fields:
| `pubkey_node` | String | Public key used to verify this server for peer-to-peer communications. This _node key pair_ is automatically generated by the server the first time it starts up. (If deleted, the server can create a new pair of keys.) You can set a persistent value in the config file using the `[node_seed]` config option, which is useful for [clustering](clustering.html). |
| `pubkey_validator` | String | _(Admin only)_ Public key used by this node to sign ledger validations. This _validation key pair_ is derived from the `[validator_token]` or `[validation_seed]` config field. |
| `server_state` | String | A string indicating to what extent the server is participating in the network. See [Possible Server States](rippled-server-states.html) for more details. |
| `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][] |

1
content/references/rippled-api/transaction-formats/transaction-results/tec-codes.md
View File

@@ -27,6 +27,7 @@ For the most part, transactions with `tec` codes take no action other than to de
| `tecNO_DST_INSUF_XRP` | 125 | The account on the receiving end of the transaction does not exist, and the transaction is not sending enough XRP to create it. |
| `tecNO_ENTRY` | 140 | Reserved for future use. |
| `tecNO_ISSUER` | 133 | The account specified in the `issuer` field of a currency amount does not exist. |
| `tecKILLED` | 150 | The [OfferCreate transaction][] specified the tfFillOrKill flag and could not be filled, so it was killed. _(Requires the [fix1578 amendment](known-amendments.html#fix1578).)_ |
| `tecNO_LINE` | 135 | The `TakerPays` field of the [OfferCreate transaction][] specifies an asset whose issuer has `lsfRequireAuth` enabled, and the account making the offer does not have a trust line for that asset. (Normally, making an offer implicitly creates a trust line if necessary, but in this case it does not bother because you cannot hold the asset without authorization.) If the trust line exists, but is not authorized, `tecNO_AUTH` occurs instead. |
| `tecNO_LINE_INSUF_RESERVE` | 126 | The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: [Reserves](reserves.html)) This error occurs when the counterparty does not have a trust line to this account for the same currency. (See `tecINSUF_RESERVE_LINE` for the other case.) |
| `tecNO_LINE_REDUNDANT` | 127 | The transaction failed because it tried to set a trust line to its default state, but the trust line did not exist. |

10
content/references/rippled-api/transaction-formats/transaction-types/offercreate.md
View File

@@ -45,15 +45,19 @@ Transactions of the OfferCreate type support additional values in the [`Flags` f
| Flag Name | Hex Value | Decimal Value | Description |
|:--------------------|:-----------|:--------------|:--------------------------|
| tfPassive | 0x00010000 | 65536 | If enabled, the offer does not consume offers that exactly match it, and instead becomes an Offer object in the ledger. It still consumes offers that cross it. |
| tfImmediateOrCancel | 0x00020000 | 131072 | Treat the offer as an [Immediate or Cancel order](http://en.wikipedia.org/wiki/Immediate_or_cancel). If enabled, the offer never becomes a ledger object: it only tries to match existing offers in the ledger. |
| tfFillOrKill | 0x00040000 | 262144 | Treat the offer as a [Fill or Kill order](http://en.wikipedia.org/wiki/Fill_or_kill). Only try to match existing offers in the ledger, and only do so if the entire `TakerPays` quantity can be obtained. |
| tfImmediateOrCancel | 0x00020000 | 131072 | Treat the offer as an [Immediate or Cancel order](http://en.wikipedia.org/wiki/Immediate_or_cancel). If enabled, the offer never becomes a ledger object: it only tries to match existing offers in the ledger. If the offer cannot match any offers immediately, it executes "successfully" without trading any currency. In this case, the transaction has the [result code](transaction-results.html) `tesSUCCESS`, but creates no [Offer objects](offer.html) in the ledger. |
| tfFillOrKill | 0x00040000 | 262144 | Treat the offer as a [Fill or Kill order](http://en.wikipedia.org/wiki/Fill_or_kill). Only try to match existing offers in the ledger, and only do so if the entire `TakerPays` quantity can be obtained. If the [fix1578 amendment](known-amendments.html#fix1578) is enabled and the offer cannot be executed when placed, the transaction has the [result code](transaction-results.html) `tecKILLED`; otherwise, the transaction uses the result code `tesSUCCESS` even when it was killed without trading any currency. |
| tfSell | 0x00080000 | 524288 | Exchange the entire `TakerGets` amount, even if it means obtaining more than the `TakerPays` amount in exchange. |
The following invalid flag combination prompts a `temINVALID_FLAG` error:
* tfImmediateOrCancel and tfFillOrKill
**Note:** When an OfferCreate uses tfImmediateOrCancel or tfFillOrKill and the offer cannot be executed when placed, the transaction may conclude "successfully" without trading any currency or having any effect on the order books. In this case, the transaction has the [result code](transaction-results.html) `tesSUCCESS`, it pays the [transaction cost][] and uses up a `Sequence` number, but has no other effect.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}

2
content/references/rippled-api/transaction-formats/transaction-types/signerlistset.md
View File

@@ -51,6 +51,8 @@ You can create, update, or remove a SignerList using the master key, regular key
You cannot remove the last method of signing transactions from an account. If an account's master key is disabled (it has the [`lsfDisableMaster` flag](accountroot.html#accountroot-flags) enabled) and the account does not have a [Regular Key](cryptographic-keys.html) configured, then you cannot delete the SignerList from the account. Instead, the transaction fails with the error [`tecNO_ALTERNATIVE_KEY`](tec-codes.html).
With the [MultiSignReserve Amendment](known-amendments.html#multisignreserve) enabled, creating or replacing a SignerList enables the lsfOneOwnerCount flag on the SignerList object. When this flag is enabled, the XRP Ledger is able to lower the [`OwnerCount`](accountroot.html#accountroot-fields) and [owner reserve](reserves.html#owner-reserves) for a SignerList as provided by the MultiSignReserve amendment. For more information, see [SignerList Flag](signerlist.html#signerlist-flags).
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}

2
content/references/rippled-api/transaction-formats/transaction-types/trustset.md
View File

@@ -42,7 +42,7 @@ 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 issuances from this account. (No effect unless using the [*asfRequireAuth* AccountSet flag](accountset.html#accountset-flags).) Cannot be unset. |
| tfSetNoRipple | 0x00020000 | 131072 | Blocks rippling between two trustlines of the same currency, if this flag is set on both. (See [No Ripple](rippling.html) for details.) |
| tfSetNoRipple | 0x00020000 | 131072 | Blocks rippling between two trustlines of the same currency, if this flag is set on both. (See [No Ripple](rippling.html) for details.) If the [fix1578 amendment](known-amendments.html#fix1578) 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 NoRipple on the trust line. |
| tfClearNoRipple | 0x00040000 | 262144 | Clears the No-Rippling flag. (See [NoRipple](rippling.html) for details.) |
| tfSetFreeze | 0x00100000 | 1048576 | [Freeze](freezes.html) the trustline. |
| tfClearFreeze | 0x00200000 | 2097152 | [Unfreeze](freezes.html) the trustline. |

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

@@ -16,7 +16,11 @@ This tutorial demonstrates how to enable multi-signing for an address.
## 1. Prepare a funded address
You need an XRP Ledger address that can send transactions, and has enough XRP available. Multi-signing requires more than the usual amount of XRP for the [account reserve](reserves.html) and [transaction cost](transaction-cost.html), increasing with the number of signers and signatures you use.
You need an XRP Ledger address that can send transactions, and has enough XRP available.
Without the [MultiSignReserve Amendment](known-amendments.html#multisignreserve), multi-signing requires more than the usual amount of XRP for the [account reserve](reserves.html) and [transaction cost](transaction-cost.html), increasing with the number of signers and signatures you use.
With the [MultiSignReserve Amendment](known-amendments.html#multisignreserve) enabled, multi-signing requires 5 XRP for the account reserve, regardless of the number of signers and signatures you use. The [transaction cost](transaction-cost.html) of a multi-signed transaction is unaffected by this amendment and still increases with the number of signers and signatures you use.
If you started `rippled` in [stand-alone mode](rippled-server-modes.html#reasons-to-run-a-rippled-server-in-stand-alone-mode) with a new genesis ledger, you must:
@@ -129,7 +133,7 @@ In this example, the SignerList has 3 members, with the weights and quorum set u
Make sure that the [Transaction Result](transaction-results.html) is [**tesSUCCESS**](tes-success.html). Otherwise, the transaction failed. If you have a problem in stand-alone mode or a non-production network, check that [multi-sign is enabled](start-a-new-genesis-ledger-in-stand-alone-mode.html#settings-in-new-genesis-ledgers).
**Note:** The more members in the SignerList, the more XRP your address must have for purposes of the [owner reserve](reserves.html#owner-reserves). If your address does not have enough XRP, the transaction fails with [tecINSUFFICIENT_RESERVE](tec-codes.html). See also: [SignerLists and Reserves](signerlist.html#signerlists-and-reserves).
**Note:** Without the [MultiSignReserve Amendment](known-amendments.html#multisignreserve), the more members in the SignerList, the more XRP your address must have for purposes of the [owner reserve](reserves.html#owner-reserves). If your address does not have enough XRP, the transaction fails with [tecINSUFFICIENT_RESERVE](tec-codes.html). With the [MultiSignReserve Amendment](known-amendments.html#multisignreserve) enabled, the XRP your address must have for purposes of the [owner reserve](reserves.html#owner-reserves) is 5 XRP, regardless of the number of members in the SignerList. See also: [SignerLists and Reserves](signerlist.html#signerlists-and-reserves).
## 4. Close the ledger

13
content/tutorials/manage-the-rippled-server/installation/build-run-rippled-macos.md
View File

@@ -24,13 +24,20 @@ For development purposes Ripple recommends running `rippled` as your own user, n
$ brew install git cmake pkg-config protobuf openssl ninja
0. Install Boost 1.67.0. `rippled` 1.1.x is compatible with Boost 1.67.
0. Install Boost 1.67.0. `rippled` 1.2.x is compatible with Boost 1.67. <!--#{ no boost@1.67 formula, so must manually compile and install. will eventually upgrade to boost 1.68, but needs testing first }# -->
$ brew install boost@1.67
1. Download [Boost 1.67.0](https://dl.bintray.com/boostorg/release/1.67.0/source/boost_1_67_0.tar.bz2).
2. Extract it to a folder. Be sure to note the location.
3. In a terminal, run:
./bootstrap.sh
./b2 cxxflags="-std=c++14"
0. Ensure that your `BOOST_ROOT` environment variable points to the directory created by the Boost installation. To find your Boost install directory, use `brew info boost`. Put this environment variable in your `.bash_profile` file so it's automatically set when you log in. For example:
export BOOST_ROOT=/usr/local/Cellar/boost/1.67.0_1
export BOOST_ROOT=/Users/my_user/boost_1_67_0
0. If you updated your `.bash_profile` file in the previous step, be sure to source it. For example:

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

@@ -4,7 +4,7 @@
For an overview of `rippled`, see [Operating rippled Servers](install-rippled.html).
Use these instructions to build a `rippled` executable from source version 1.1.0 or higher on Ubuntu Linux 16.04 or higher. These instructions were tested on Ubuntu 16.04 LTS.
Use these instructions to build a `rippled` executable from source version 1.2.0 or higher on Ubuntu Linux 16.04 or higher. These instructions were tested on Ubuntu 16.04 LTS.
For information about building `rippled` for other platforms, see [Builds](https://github.com/ripple/rippled/tree/develop/Builds) in the `rippled` GitHub repository.
@@ -27,11 +27,24 @@ These instructions use Ubuntu's APT (Advanced Packaging Tool) to install the sof
3. Install dependencies.
sudo apt-get -y install git cmake pkg-config protobuf-compiler libprotobuf-dev libssl-dev wget
sudo apt-get -y install git pkg-config protobuf-compiler libprotobuf-dev libssl-dev wget
4. Compile Boost.
4. Install CMake.
Version 1.1.0 of `rippled` requires Boost version 1.67.0 exactly. Because Boost version 1.67.0 isn't available in the Ubuntu 16.04 software repositories, you must compile it yourself.
Version 1.2.0 of `rippled` requires CMake 3.9.0 or higher. For the purposes of this tutorial, we used CMake 3.13.3, which was the latest version available at the time of writing.
If you have previously installed CMake 3.9.0 or higher, you can skip these steps.
To install CMake 3.13.3:
wget https://github.com/Kitware/CMake/releases/download/v3.13.3/cmake-3.13.3-Linux-x86_64.sh
sudo sh cmake-3.13.3-Linux-x86_64.sh --prefix=/usr/local --exclude-subdir
Use `cmake --version` to verify that the installation worked.
5. Compile Boost.
Version 1.2.0 of `rippled` requires Boost version 1.67.0 exactly. Because Boost version 1.67.0 isn't available in the Ubuntu 16.04 software repositories, you must compile it yourself.
If you have previously built Boost 1.67.0 for `rippled` and configured the `BOOST_ROOT` environment variable, you can skip these steps.
@@ -59,35 +72,33 @@ These instructions use Ubuntu's APT (Advanced Packaging Tool) to install the sof
6. Set the environment variable `BOOST_ROOT` to point to the new `boost_1_67_0` directory. It's best to put this environment variable in your `.profile`, or equivalent, file for your shell so it's automatically set when you log in. Add the following line to the file:
export BOOST_ROOT=/home/ubuntu/boost_1_67_0
export BOOST_ROOT=/home/my_user/boost_1_67_0
7. Source your updated `.profile` file. For example:
source ~/.profile
5. From a working directory, get the `rippled` source code. The `master` branch has the latest released version.
6. From a working directory, get the `rippled` source code. The `master` branch has the latest released version.
cd ~
git clone https://github.com/ripple/rippled.git
cd rippled
git checkout master
6. Check the commit log to be sure you're compiling the version you intend to. The most recent commit should be signed by a well-known Ripple developer and should set the version number to the latest released version. For example:
7. Check the commit log to be sure you're compiling the version you intend to. The most recent commit should be signed by a well-known Ripple developer and should set the version number to the latest released version. For example:
$ git log -1
commit 3e22a1e9e8f2de450eded6ca4c2db6411e329b2a
commit 4f3a76dec00c0c7ea28e78e625c68499debbbbf3
Author: Nik Bougalis <nikb@bougalis.net>
Date: Wed Sep 5 18:34:43 2018 -0700
Date: Thu Nov 29 21:49:10 2018 -0800
Set version to 1.1.0
Set version to 1.1.2
7. 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.
8. Use CMake to build a `rippled` binary executable from source code. The result will be a `rippled` binary executable in the `my_build` directory.
9. Use CMake to build a `rippled` binary executable from source code. The result will be a `rippled` binary executable in the `my_build` directory.
1. Generate the build system. Builds should be performed in a directory that is separate from the source tree root. In this example, we'll use a `my_build` directory that is a subdirectory of `rippled`.
@@ -97,13 +108,11 @@ These instructions use Ubuntu's APT (Advanced Packaging Tool) to install the sof
**Tip:** The default build includes debugging symbols, which can be useful for development but are inefficient in production. To build `rippled` for use on production servers, add the `-DCMAKE_BUILD_TYPE=Release` flag when running the `cmake` command.
2. Build the `rippled` binary executable. Replace `<number of parallel jobs>` with the number of jobs to run in parallel. Choose this value based on the number of CPU cores you want to use for building.
2. Build the `rippled` binary executable. This may take about 30 minutes, depending on your hardware specs.
cmake --build . -- -j 4
cmake --build .
**Tip:** This example uses 4 processes to build in parallel. The best number of processes to use depends on how many CPU cores your hardware has available. You can use `cat /proc/cpuinfo` to get information about your hardware's processor.
9. _(Optional)_ Run `rippled` unit tests. If there are no test failures, you can be fairly certain that your `rippled` executable compiled correctly.
10. _(Optional)_ Run `rippled` unit tests. If there are no test failures, you can be fairly certain that your `rippled` executable compiled correctly.
./rippled -u

16
content/tutorials/manage-the-rippled-server/troubleshooting/understanding-log-messages.md
View File

@@ -155,6 +155,22 @@ s2.ripple.com 51235
```
## Potential Censorship
Log messages such as the following are issued when the XRP Ledger detects potential transaction censorship. For more information about these log messages and the transaction censorship detector, see [Transaction Censorship Detection](transaction-censorship-detection.html).
**Warning Message**
```text
LedgerConsensus:WRN Potential Censorship: Eligible tx E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7, which we are tracking since ledger 18851530 has not been included as of ledger 18851545.
```
**Error Message**
```text
LedgerConsensus:ERR Potential Censorship: Eligible tx E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7, which we are tracking since ledger 18851530 has not been included as of ledger 18851605. Additional warnings suppressed.
```
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}

20
dactyl-config.yml
View File

@@ -593,6 +593,15 @@ pages:
targets:
- local
- md: concepts/the-rippled-server/transaction-censorship-detection.md
html: transaction-censorship-detection.html
funnel: Docs
doc_type: Concepts
category: The rippled Server
blurb: XRP Ledger provides an automated transaction censorship detector that is available on all rippled servers.
targets:
- local
# Tutorials --------------------------------------------------------------------
- name: Tutorials
@@ -1908,6 +1917,17 @@ pages:
targets:
- local
- md: references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/crawl_shards.md
html: crawl_shards.html
blurb: Request information about which history shards peers have.
funnel: Docs
doc_type: References
supercategory: rippled API
category: Admin rippled Methods
subcategory: Logging and Data Management Methods
targets:
- local
- md: references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/download_shard.md
html: download_shard.html
blurb: Download a specific shard of ledger history.