ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-12-06 17:27:57 +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

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. |