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

Merge branch 'master' into ledger_entry1580

Browse Source
This commit is contained in:
Dennis Dawson
2023-02-21 15:43:12 -08:00
committed by GitHub
parent d605d9a92a e4dcb43289
commit 2722cc7f6c
225 changed files with 8680 additions and 1122 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
content/references/http-websocket-apis/admin-api-methods/status-and-debugging-methods/feature.md
View File

@@ -187,7 +187,7 @@ The response follows the [standard format][], with a successful result containin
|:------------|:--------|:-----------------------------------------------------|
| `enabled` | Boolean | Whether this amendment is currently enabled in the latest ledger. |
| `name` | String | (May be omitted) The human-readable name for this amendment, if known. |
| `supported` | Boolean | Whether the server knows how to apply this amendment. If this field is set to `false` (the server does not know how to apply this amendment) and `enabled` is set to `true` (this amendment is enabled in the latest ledger), this amendment may cause your server to be [amendment blocked](amendments.html#amendment-blocked). |
| `supported` | Boolean | Whether the server knows how to apply this amendment. If this field is set to `false` (the server does not know how to apply this amendment) and `enabled` is set to `true` (this amendment is enabled in the latest ledger), this amendment may cause your server to be [amendment blocked](amendments.html#amendment-blocked-servers). |
| `vetoed` | Boolean | Whether the server has been instructed to vote against this amendment. |
**Caution:** The `name` for an amendment does not strictly indicate what that amendment does. The name is not guaranteed to be unique or consistent across servers.

2
content/references/http-websocket-apis/api-conventions/error-formatting.md
View File

@@ -108,7 +108,7 @@ For other errors that returned with HTTP status code 200 OK, the responses are f
All methods can potentially return any of the following values for the `error` code:
- `amendmentBlocked` - The server is [amendment blocked](amendments.html#amendment-blocked) and needs to be updated to the latest version to stay synced with the XRP Ledger network.
- `amendmentBlocked` - The server is [amendment blocked](amendments.html#amendment-blocked-servers) and needs to be updated to the latest version to stay synced with the XRP Ledger network.
- `failedToForward` - ([Reporting Mode][] servers only) The server tried to forward this request to a P2P Mode server, but the connection failed.
- `invalid_API_version` - The server does not support the [API version number](request-formatting.html#api-versioning) from the request.
- `jsonInvalid` - (WebSocket only) The request is not a proper JSON object.

4
content/references/http-websocket-apis/api-conventions/response-formatting.md
View File

@@ -126,7 +126,7 @@ Example warning:
]
```
This warning indicates that the one or more [amendments](amendments.html) to the XRP Ledger protocol are scheduled to become enabled, but the current server does not have an implementation for those amendments. If those amendments become enabled, the current server will become [amendment blocked](amendments.html#amendment-blocked), so you should [upgrade to the latest `rippled` version](install-rippled.html) as soon as possible. <!-- STYLE_OVERRIDE: will -->
This warning indicates that the one or more [amendments](amendments.html) to the XRP Ledger protocol are scheduled to become enabled, but the current server does not have an implementation for those amendments. If those amendments become enabled, the current server will become [amendment blocked](amendments.html#amendment-blocked-servers), so you should [upgrade to the latest `rippled` version](install-rippled.html) as soon as possible. <!-- STYLE_OVERRIDE: will -->
The server only sends this warning if the client is [connected as an admin](get-started-using-http-websocket-apis.html#admin-access).
@@ -153,7 +153,7 @@ Example warning:
]
```
This warning indicates that the server is [amendment blocked](amendments.html#amendment-blocked) and can no longer remain synced with the XRP Ledger.
This warning indicates that the server is [amendment blocked](amendments.html#amendment-blocked-servers) and can no longer remain synced with the XRP Ledger.
The server administrator must [upgrade `rippled`](install-rippled.html) to a version that supports the activated amendments.

6
content/references/http-websocket-apis/peer-port-methods/health-check.md
View File

@@ -90,8 +90,8 @@ The response's HTTP status code indicates the health of the server:
| Status Code | Health Status | Description |
|:------------------------------|:--------------|:-----------------------------|
| **200 OK** | Healthy | All health metrics are within acceptable ranges. |
| **503 Service Unavailable** | Warning | One or more metric is in the warning range. Manual intervention may or may not be necessary. |
| **500 Internal Server Error** | Critical | One or more metric is in the critical range. There is a serious problem that probably needs manual intervention to fix. |
| **503 Service Unavailable** | Warning | One or more metrics are in the warning range. Manual intervention may or may not be necessary. |
| **500 Internal Server Error** | Critical | One or more metrics are in the critical range. There is a serious problem that probably needs manual intervention to fix. |
The response body is a JSON object with a single `info` object at the top level. The `info` object contains values for each metric that is in a warning or critical range. The response omits metrics that are in a healthy range, so a fully healthy server has an empty object.
@@ -99,7 +99,7 @@ The `info` object may contain the following fields:
| `Field` | Value | Description |
|:--------------------|:--------|:---------------------------------------------|
| `amendment_blocked` | Boolean | _(May be omitted)_ If `true`, the server is [amendment blocked](amendments.html#amendment-blocked) and must be upgraded to remain synced with the network; this state is critical. If the server is not amendment blocked, this field is omitted. |
| `amendment_blocked` | Boolean | _(May be omitted)_ If `true`, the server is [amendment blocked](amendments.html#amendment-blocked-servers) and must be upgraded to remain synced with the network; this state is critical. If the server is not amendment blocked, this field is omitted. |
| `load_factor` | Number | _(May be omitted)_ A measure of the overall load the server is under. This reflects I/O, CPU, and memory limitations. This is a warning if the load factor is over 100, or critical if the load factor is 1000 or higher. |
| `peers` | Number | _(May be omitted)_ The number of [peer servers](peer-protocol.html) this server is connected to. This is a warning if connected to 7 or fewer peers, and critical if connected to zero peers. |
| `server_state` | String | _(May be omitted)_ The current [server state](rippled-server-states.html). This is a warning if the server is in the `tracking`, `syncing`, or `connected` states. This is critical if the server is in the `disconnected` state. |

18
content/references/http-websocket-apis/public-api-methods/account-methods/account_objects.md
View File

@@ -71,15 +71,15 @@ rippled account_objects r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 validated
The request includes the following parameters:
| `Field` | Type | Description |
|:-------------------------|:-----------------|:-------------------------------|
| `account` | String | A unique identifier for the account, most commonly the account's address. |
| `type` | String | _(Optional)_ If included, filter results to include only this type of ledger object. The valid types are: `check`, `deposit_preauth`, `escrow`, `offer`, `payment_channel`, `signer_list`, `ticket`, and `state` (trust line). <!-- Author's note: Omitted types that can't be owned by an account --> |
| `deletion_blockers_only` | Boolean | _(Optional)_ If `true`, the response only includes objects that would block this account from [being deleted](accounts.html#deletion-of-accounts). The default is `false`. [New in: rippled 1.4.0][] |
| `ledger_hash` | String | _(Optional)_ A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) |
| `ledger_index` | String or Number | _(Optional)_ The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |
| `limit` | Number | _(Optional)_ The maximum number of objects to include in the results. Must be within the inclusive range `10` to `400` on non-admin connections. The default is `200`. |
| `marker` | [Marker][] | _(Optional)_ Value from a previous paginated response. Resume retrieving data where that response left off. |
| `Field` | Type | Required? | Description |
|:-------------------------|:-----------------|:----------|-------------|
| `account` | String | Yes | A unique identifier for the account, most commonly the account's [Address][]. |
| `deletion_blockers_only` | Boolean | No | If `true`, the response only includes objects that would block this account from [being deleted](accounts.html#deletion-of-accounts). The default is `false`. [New in: rippled 1.4.0][] |
| `ledger_hash` | [Hash][] | No | A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) |
| `ledger_index` | [Ledger Index][] | No | The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |
| `limit` | Number | No | The maximum number of objects to include in the results. Must be within the inclusive range `10` to `400` on non-admin connections. The default is `200`. |
| `marker` | [Marker][] | No | Value from a previous paginated response. Resume retrieving data where that response left off. |
| `type` | String | No | Filter results by a ledger entry type. The valid types are: `check`, `deposit_preauth`, `escrow`, `nft_offer`, `offer`, `payment_channel`, `signer_list`, `state` (trust line), and `ticket`. <!-- Author's note: Omitted types that can't be owned by an account --> |
## Response Format

24
content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger.md
View File

@@ -63,17 +63,19 @@ rippled ledger validated
The request can contain the following parameters:
| `Field` | Type | Description |
|:---------------|:---------------------------|:-------------------------------|
| `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 [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |
| `full` | Boolean | _(Optional)_ **Admin required** If `true`, return full information on the entire ledger. Ignored if you did not specify a ledger version. The default is `false`. (Equivalent to enabling `transactions`, `accounts`, and `expand`.) The [Clio server](the-clio-server.html) does not support this field. **Caution:** On Mainnet, this can be gigabytes worth of data, so the request is likely to time out. |
| `accounts` | Boolean | _(Optional)_ **Admin required.** If `true`, return information on accounts in the ledger. Ignored if you did not specify a ledger version. The default is `false`. **Caution:** On Mainnet, this can be gigabytes worth of data, so the request is likely to time out. |
| `transactions` | Boolean | _(Optional)_ If `true`, return information on transactions in the specified ledger version. The default is `false`. Ignored if you did not specify a ledger version. |
| `expand` | Boolean | _(Optional)_ Provide full JSON-formatted information for transaction/account information instead of only hashes. The default is `false`. Ignored unless you request transactions, accounts, or both. |
| `owner_funds` | Boolean | _(Optional)_ If `true`, include `owner_funds` field in the metadata of OfferCreate transactions in the response. The default is `false`. Ignored unless transactions are included and `expand` is true. |
| `binary` | Boolean | _(Optional)_ If `true`, and `transactions` and `expand` are both also `true`, return transaction information in binary format (hexadecimal string) instead of JSON format. [New in: rippled 0.28.0][] |
| `queue` | Boolean | _(Optional)_ If `true`, and the command is requesting the `current` ledger, includes an array of [queued transactions](transaction-cost.html#queued-transactions) in the results.
| `Field` | Type | Required? | Description |
|:---------------|:-----------------|:----------|-------------|
| `ledger_hash` | [Hash][] | No | A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]). |
| `ledger_index` | [Ledger Index][] | No | The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |
| `full` | Boolean | No | **Admin only** If `true`, return full information on the entire ledger. Ignored if you did not specify a ledger version. The default is `false`. (Equivalent to enabling `transactions`, `accounts`, and `expand`.) The [Clio server](the-clio-server.html) does not support this field. **Caution:** On Mainnet, this can be gigabytes worth of data, so the request is likely to time out. |
| `accounts` | Boolean | No | **Admin only.** If `true`, return the ledger's entire state data. Ignored if you did not specify a ledger version. The default is `false`. **Caution:** On Mainnet, this can be gigabytes worth of data, so the request is likely to time out. Use [ledger_data][ledger_data method] instead to fetch state data across multiple paginated requests. |
| `transactions` | Boolean | No | If `true`, return information on transactions in the specified ledger version. The default is `false`. Ignored if you did not specify a ledger version. |
| `expand` | Boolean | No | Provide full JSON-formatted information for transaction/account information instead of only hashes. The default is `false`. Ignored unless you request transactions, accounts, or both. |
| `owner_funds` | Boolean | No | If `true`, include `owner_funds` field in the metadata of OfferCreate transactions in the response. The default is `false`. Ignored unless transactions are included and `expand` is true. |
| `binary` | Boolean | No | If `true`, and `transactions` and `expand` are both also `true`, return transaction information in binary format (hexadecimal string) instead of JSON format. [New in: rippled 0.28.0][] |
| `queue` | Boolean | No | If `true`, and the command is requesting the `current` ledger, includes an array of [queued transactions](transaction-cost.html#queued-transactions) in the results. |
| `type` | String | No | Filter by a ledger entry type. {% include '_snippets/lowercase-types.md' %} Ignored unless you request `accounts` (state data). |
The `ledger` field is deprecated and may be removed without further notice.

15
content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_data.md
View File

@@ -50,13 +50,14 @@ An example of the request format:
A request can include the following fields:
| `Field` | Type | Required? | Description |
|:---------------|:--------------------------|:----------|----------------|
| `ledger_hash` | String - [Hash][] | No | A 20-byte hex string identifying the ledger version to use. |
| `ledger_index` | Number - [Ledger Index][] | No | The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |
| `binary` | Boolean | No | If `true`, return ledger entries as hexadecimal strings instead of JSON. The default is `false`. |
| `limit` | Integer | No | Limit the number of ledger entries to retrieve. The server may return fewer than this number of entries. Cannot be more than 2048 (when requesting binary) or 256 (when requesting JSON). The default is the maximum. |
| `marker` | [Marker][] | No | Value from a previous paginated response. Resume retrieving data where that response left off. |
| `Field` | Type | Required? | Description |
|:---------------|:-----------------|:----------|----------------|
| `ledger_hash` | [Hash][] | No | A 20-byte hex string identifying the ledger version to use. |
| `ledger_index` | [Ledger Index][] | No | The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |
| `binary` | Boolean | No | If `true`, return ledger entries as hexadecimal strings instead of JSON. The default is `false`. |
| `limit` | Number | No | Limit the number of ledger entries to retrieve. The server may return fewer than this number of entries. Cannot be more than 2048 (when requesting binary) or 256 (when requesting JSON). The default is the maximum. |
| `marker` | [Marker][] | No | Value from a previous paginated response. Resume retrieving data where that response left off. |
| `type` | String | No | Filter results to a specific type of ledger entry. {% include '_snippets/lowercase-types.md' %} |
The `ledger` field is deprecated and may be removed without further notice.

91
content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry.md
View File

@@ -19,7 +19,7 @@ This method can retrieve several different types of data. You can select which t
### General Fields
| `Field` | Type | Description |
| Field | Type | Description |
|:------------------------|:---------------------------|:----------------------|
| `binary` | Boolean | _(Optional)_ If `true`, return the requested ledger object's contents as a hex string in the XRP Ledger's [binary format](serialization.html). Otherwise, return data in JSON format. The default is `false`. [Updated in: rippled 1.2.0][] |
| `ledger_hash` | String | _(Optional)_ A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) |
@@ -31,6 +31,7 @@ In addition to the general fields above, you must specify *exactly 1* of the fol
- [`index`](#get-ledger-object-by-id)
- [`account_root`](#get-accountroot-object)
- [`amm`](#get-amm-object) :not_enabled:
- [`directory`](#get-directorynode-object)
- [`offer`](#get-offer-object)
- [`ripple_state`](#get-ripplestate-object)
@@ -48,7 +49,7 @@ In addition to the general fields above, you must specify *exactly 1* of the fol
Retrieve any type of ledger object by its unique ID.
| `Field` | Type | Description |
| Field | Type | Description |
|:--------|:-------|:----------------------------------------------------------|
| `index` | String | The [object ID](ledger-object-ids.html) of a single object to retrieve from the ledger, as a 64-character (256-bit) hexadecimal string. |
@@ -101,7 +102,7 @@ rippled json ledger_entry '{ "index": "7DB0788C020F02780A673DC74757F23823FA3014C
Retrieve an [AccountRoot object](accountroot.html) by its address. This is roughly equivalent to the [account_info method][].
| `Field` | Type | Description |
| Field | Type | Description |
|:------------------------|:---------------------------|:----------------------|
| `account_root` | String - [Address][] | The classic address of the [AccountRoot object](accountroot.html) to retrieve. |
@@ -144,12 +145,78 @@ rippled json ledger_entry '{ "account_root": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59
### Get AMM Object
_(Automated Market Maker (AMM) functionality is part of the proposed [XLS-30d](https://github.com/XRPLF/XRPL-Standards/discussions/78) extension :not_enabled: to the XRP Ledger protocol. You can use these features on AMM test networks, but there isn't an official amendment and they aren't available on the production Mainnet.)_
Retrieve an Automated Market-Maker (AMM) object from the ledger. This is similar to [amm_info method][], but the `ledger_entry` version returns only the ledger entry as stored.
| Field | Type | Description |
|:-------------|:-----------------|:----------------------|
| `amm` | Object or String | The [AMM](amm.html) to retrieve. If you specify a string, it must be the [object ID](ledger-object-ids.html) of the AMM, as hexadecimal. If you specify an object, it must contain `asset` and `asset2` sub-fields. |
| `amm.asset` | Object | One of the two assets in this AMM's pool, as a [currency object without an amount](currency-formats.html#specifying-without-amounts). |
| `amm.asset2` | Object | The other of the two assets in this AMM's pool, as a [currency object without an amount](currency-formats.html#specifying-without-amounts). |
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```json
{
"id": 3,
"command": "ledger_entry",
"amm": {
"asset": {
"currency": "XRP"
},
"asset2": {
"currency" : "TST",
"issuer" : "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd"
}
}
"ledger_index": "validated"
}
```
*JSON-RPC*
```json
{
"method": "ledger_entry",
"params": [
{
"amm": {
"asset": {
"currency": "XRP"
},
"asset2": {
"currency" : "TST",
"issuer" : "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd"
}
},
"ledger_index": "validated"
}
]
}
```
*Commandline*
```sh
rippled json ledger_entry '{ "amm": { "asset": { "currency": "XRP" }, "asset2": { "currency" : "TST", "issuer" : "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd" } }, "ledger_index": "validated" }'
```
<!-- MULTICODE_BLOCK_END -->
[Try it! >](websocket-api-tool.html?server=wss%3A%2F%2Famm.devnet.rippletest.net%3A51233%2F#ledger_entry-amm)
### Get DirectoryNode Object
Retrieve a [DirectoryNode](directorynode.html), which contains a list of other ledger objects. Can be provided as string (object ID of the Directory) or as an object.
| `Field` | Type | Description |
| Field | Type | Description |
|:------------------------|:---------------------------|:----------------------|
| `directory` | Object or String | The [DirectoryNode](directorynode.html) to retrieve. If a string, must be the [object ID](ledger-object-ids.html) of the directory, as hexadecimal. If an object, requires either `dir_root` or `owner` as a sub-field, plus optionally a `sub_index` sub-field. |
| `directory.sub_index` | Unsigned Integer | _(Optional)_ If provided, jumps to a later "page" of the [DirectoryNode](directorynode.html). |
@@ -205,7 +272,7 @@ rippled json ledger_entry '{ "directory": { "owner": "rf1BiGeXwwQoi8Z2ueFYTEXSwu
Retrieve an [Offer object](offer.html), which defines an offer to exchange currency. Can be provided as string (unique index of the Offer) or as an object.
| `Field` | Type | Description |
| Field | Type | Description |
|:------------------------|:---------------------------|:----------------------|
| `offer` | Object or String | The [Offer object](offer.html) to retrieve. If a string, interpret as the [unique object ID](ledgers.html#tree-format) to the Offer. If an object, requires the sub-fields `account` and `seq` to uniquely identify the offer. |
| `offer.account` | String - [Address][] | _(Required if `offer` is specified as an object)_ The account that placed the offer. |
@@ -260,7 +327,7 @@ rippled json ledger_entry '{ "offer": { "account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJY
Retrieve a [RippleState object](ripplestate.html), which tracks a (non-XRP) currency balance between two accounts.
| `Field` | Type | Description |
| Field | Type | Description |
|:------------------------|:---------------------------|:----------------------|
| `ripple_state` | Object | 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). |
@@ -319,7 +386,7 @@ rippled json ledger_entry '{ "ripple_state": { "accounts": ["rf1BiGeXwwQoi8Z2ueF
Retrieve a [Check object](check.html), which is a potential payment that can be cashed by its recipient. [New in: rippled 1.0.0][]
| `Field` | Type | Description |
| Field | Type | Description |
|:--------|:-------|:----------------------------------------------------------|
| `check` | String | The [object ID](ledger-object-ids.html) of a [Check object](check.html) to retrieve. |
@@ -364,7 +431,7 @@ rippled json ledger_entry '{ "check": "C4A46CCD8F096E994C4B0DEAB6CE98E722FC17D79
Retrieve an [Escrow object](escrow-object.html), which holds XRP until a specific time or condition is met. Can be provided as string (object ID of the Escrow) or as an object. [New in: rippled 1.0.0][]
| `Field` | Type | Description |
| Field | Type | Description |
|:------------------------|:---------------------------|:----------------------|
| `escrow` | Object or String | The [Escrow object](escrow-object.html) to retrieve. If a string, must be the [object ID](ledger-object-ids.html) of the Escrow, as hexadecimal. If an object, requires `owner` and `seq` sub-fields. |
| `escrow.owner` | String - [Address][] | _(Required if `escrow` is specified as an object)_ The owner (sender) of the Escrow object. |
@@ -417,7 +484,7 @@ rippled json ledger_entry '{ "escrow": { "owner": "rL4fPHi2FWGwRGRQSH7gBcxkuo2b9
Retrieve a [PayChannel object](paychannel.html), which holds XRP for asynchronous payments. [New in: rippled 1.0.0][]
| `Field` | Type | Description |
| Field | Type | Description |
|:------------------|:-------|:------------------------------------------------|
| `payment_channel` | String | The [object ID](ledger-object-ids.html) of a [PayChannel object](paychannel.html) to retrieve. |
@@ -461,7 +528,7 @@ rippled json ledger_entry '{ "payment_channel": "C7F634794B79DB40E87179A9D1BF05D
Retrieve a [DepositPreauth object](depositpreauth-object.html), which tracks preauthorization for payments to accounts requiring [Deposit Authorization](depositauth.html). Can be provided as string (object ID of the DepositPreauth) or as an object. [New in: rippled 1.1.0][]
| `Field` | Type | Description |
| Field | Type | Description |
|:-----------------------------|:---------------------|:-----------------------|
| `deposit_preauth` | Object or String | Specify a [DepositPreauth object](depositpreauth-object.html) to retrieve. If a string, must be the [object ID](ledger-object-ids.html) of the DepositPreauth object, as hexadecimal. If an object, requires `owner` and `authorized` sub-fields. |
| `deposit_preauth.owner` | String - [Address][] | _(Required if `deposit_preauth` is specified as an object)_ The account that provided the preauthorization. |
@@ -513,7 +580,7 @@ rippled json ledger_entry '{ "deposit_preauth": { "owner": "rf1BiGeXwwQoi8Z2ueFY
Retrieve a [Ticket object](ticket.html), which represents a [sequence number][] set aside for future use. Can be provided as string (object ID of the Ticket) or as an object. _(Added by the [TicketBatch amendment][])_
| `Field` | Type | Description |
| Field | Type | Description |
|:--------------------|:---------------------|:----------------------|
| `ticket` | Object or String | The [Ticket object](ticket.html) to retrieve. If a string, must be the [object ID](ledger-object-ids.html) of the Ticket, as hexadecimal. If an object, the `account` and `ticket_seq` sub-fields are required to uniquely specify the Ticket entry. |
| `ticket.account` | String - [Address][] | _(Required if `ticket` is specified as an object)_ The owner of the Ticket object. |
@@ -608,7 +675,7 @@ rippled json ledger_entry '{ "nft_page": "255DD86DDF59D778081A06D02701E9B2C9F4F0
The response follows the [standard format][], with a successful result containing the following fields:
| `Field` | Type | Description |
| Field | Type | Description |
|:---------------|:-----------------|:-----------------------------------------|
| `index` | String | The unique ID of this [ledger object](ledger-object-types.html). |
| `ledger_index` | Unsigned Integer | The [ledger index][] of the ledger that was used when retrieving this data. |

229
content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/amm_info.md
View File

@@ -81,54 +81,48 @@ An example of a successful response:
{
"result": {
"amm": {
"AMMAccount" : "rE54zDvgnghAoPopCgvtiqWNq3dU5y836S",
"Asset" : {
"currency" : "XRP"
},
"Asset2" : {
"currency" : "TST",
"issuer" : "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd"
},
"AuctionSlot" : {
"Account" : "rJVUeRqDFNs2xqA7ncVE6ZoAhPUoaJJSQm",
"AuthAccounts" : [
{
"AuthAccount" : {
"Account" : "rMKXGCbJ5d8LbrqthdG46q3f969MVK2Qeg"
}
},
{
"AuthAccount" : {
"Account" : "rBepJuTLFJt3WmtLXYAxSjtBWAeQxVbncv"
}
}
],
"DiscountedFee" : 0,
"Expiration" : 721870180,
"Price" : {
"currency" : "039C99CD9AB0B70B32ECDA51EAAE471625608EA2",
"issuer" : "rE54zDvgnghAoPopCgvtiqWNq3dU5y836S",
"value" : "0.8696263565463045"
}
},
"Flags" : 0,
"LPTokenBalance" : {
"currency" : "039C99CD9AB0B70B32ECDA51EAAE471625608EA2",
"issuer" : "rE54zDvgnghAoPopCgvtiqWNq3dU5y836S",
"value" : "71150.53584131501"
},
"TradingFee" : 600,
"VoteSlots" : [
"amm_account": "rp9E3FN3gNmvePGhYnf414T2TkUuoxu8vM",
"amount": "296890496",
"amount2": {
"currency": "TST",
"issuer": "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd",
"value": "25.81656470648473"
},
"asset2_frozen": false,
"auction_slot": {
"account": "rJVUeRqDFNs2xqA7ncVE6ZoAhPUoaJJSQm",
"auth_accounts": [
{
"VoteEntry" : {
"Account" : "rJVUeRqDFNs2xqA7ncVE6ZoAhPUoaJJSQm",
"TradingFee" : 600,
"VoteWeight" : 100000
}
"account": "r3f2WpQMsAd8k4Zoijv2PZ78EYFJ2EdvgV"
},
{
"account": "rnW8FAPgpQgA6VoESnVrUVJHBdq9QAtRZs"
}
]
],
"discounted_fee": 0,
"expiration": "2023-Jan-26 00:28:40.000000000 UTC",
"price": {
"currency": "039C99CD9AB0B70B32ECDA51EAAE471625608EA2",
"issuer": "rp9E3FN3gNmvePGhYnf414T2TkUuoxu8vM",
"value": "0"
},
"time_interval": 0
},
"lp_token": {
"currency": "039C99CD9AB0B70B32ECDA51EAAE471625608EA2",
"issuer": "rp9E3FN3gNmvePGhYnf414T2TkUuoxu8vM",
"value": "87533.41976112682"
},
"trading_fee": 600,
"vote_slots": [
{
"account": "rJVUeRqDFNs2xqA7ncVE6ZoAhPUoaJJSQm",
"trading_fee": 600,
"vote_weight": 9684
}
]
},
"ledger_current_index": 226645,
"ledger_current_index": 316725,
"validated": false
},
"status": "success",
@@ -144,54 +138,48 @@ An example of a successful response:
{
"result": {
"amm": {
"AMMAccount" : "rE54zDvgnghAoPopCgvtiqWNq3dU5y836S",
"Asset" : {
"currency" : "XRP"
},
"Asset2" : {
"currency" : "TST",
"issuer" : "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd"
},
"AuctionSlot" : {
"Account" : "rJVUeRqDFNs2xqA7ncVE6ZoAhPUoaJJSQm",
"AuthAccounts" : [
{
"AuthAccount" : {
"Account" : "rMKXGCbJ5d8LbrqthdG46q3f969MVK2Qeg"
}
},
{
"AuthAccount" : {
"Account" : "rBepJuTLFJt3WmtLXYAxSjtBWAeQxVbncv"
}
}
],
"DiscountedFee" : 0,
"Expiration" : 721870180,
"Price" : {
"currency" : "039C99CD9AB0B70B32ECDA51EAAE471625608EA2",
"issuer" : "rE54zDvgnghAoPopCgvtiqWNq3dU5y836S",
"value" : "0.8696263565463045"
}
},
"Flags" : 0,
"LPTokenBalance" : {
"currency" : "039C99CD9AB0B70B32ECDA51EAAE471625608EA2",
"issuer" : "rE54zDvgnghAoPopCgvtiqWNq3dU5y836S",
"value" : "71150.53584131501"
},
"TradingFee" : 600,
"VoteSlots" : [
"amm_account": "rp9E3FN3gNmvePGhYnf414T2TkUuoxu8vM",
"amount": "296890496",
"amount2": {
"currency": "TST",
"issuer": "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd",
"value": "25.81656470648473"
},
"asset2_frozen": false,
"auction_slot": {
"account": "rJVUeRqDFNs2xqA7ncVE6ZoAhPUoaJJSQm",
"auth_accounts": [
{
"VoteEntry" : {
"Account" : "rJVUeRqDFNs2xqA7ncVE6ZoAhPUoaJJSQm",
"TradingFee" : 600,
"VoteWeight" : 100000
}
"account": "r3f2WpQMsAd8k4Zoijv2PZ78EYFJ2EdvgV"
},
{
"account": "rnW8FAPgpQgA6VoESnVrUVJHBdq9QAtRZs"
}
]
],
"discounted_fee": 0,
"expiration": "2023-Jan-26 00:28:40.000000000 UTC",
"price": {
"currency": "039C99CD9AB0B70B32ECDA51EAAE471625608EA2",
"issuer": "rp9E3FN3gNmvePGhYnf414T2TkUuoxu8vM",
"value": "0"
},
"time_interval": 0
},
"lp_token": {
"currency": "039C99CD9AB0B70B32ECDA51EAAE471625608EA2",
"issuer": "rp9E3FN3gNmvePGhYnf414T2TkUuoxu8vM",
"value": "87533.41976112682"
},
"trading_fee": 600,
"vote_slots": [
{
"account": "rJVUeRqDFNs2xqA7ncVE6ZoAhPUoaJJSQm",
"trading_fee": 600,
"vote_weight": 9684
}
]
},
"ledger_current_index": 226620,
"ledger_current_index": 316745,
"status": "success",
"validated": false
}
@@ -202,14 +190,56 @@ An example of a successful response:
The response follows the [standard format][], with a successful result containing the following fields:
| `Field` | Type | Description |
|:-----------------------|:--------|:----------------------------------------------------------|
| `amm` | Object | The [AMM object](amm.html) for the requested asset pair. |
| `ledger_current_index` | Integer | _(Omitted if `ledger_index` is provided instead)_ The [ledger index][] of the current in-progress ledger, which was used when retrieving this information. |
| `ledger_index` | Integer | _(Omitted if `ledger_current_index` is provided instead)_ The [ledger index][] of the ledger version used when retrieving this information. |
| `validated` | Boolean | If `true`, the ledger used for this request is validated and these results are final; if omitted or set to `false`, the data is pending and may change. |
| Field | Type | Description |
|:-----------------------|:-----------------|:----------------------------------------------------------|
| `amm` | Object | An [**AMM Description Object**](#amm-description-object) for the requested asset pair. |
| `ledger_current_index` | [Ledger Index][] | _(Omitted if `ledger_index` is provided instead)_ The [ledger index][] of the current in-progress ledger, which was used when retrieving this information. |
| `ledger_hash` | [Hash][] | _(Omitted if `ledger_current_index` is provided instead)_ The identifying hash of the ledger version that was used when retrieving this data. |
| `ledger_index` | [Ledger Index][] | _(Omitted if `ledger_current_index` is provided instead)_ The [ledger index][] of the ledger version used when retrieving this information. |
| `validated` | Boolean | If `true`, the ledger used for this request is validated and these results are final; if omitted or set to `false`, the data is pending and may change. |
### AMM Description Object
The `amm` field is an object describing the current status of an Automated Market Maker (AMM) in the ledger, and contains the following fields:
| Field | Type | Description |
|-----------------|---------------------|-------------|
| `amm_account` | String | The [Address][] of the AMM Account. |
| `amount` | [Currency Amount][] | The total amount of one asset in the AMM's pool. (Note: This could be `asset` _or_ `asset2` from the request.) |
| `amount2` | [Currency Amount][] | The total amount of the other asset in the AMM's pool. (Note: This could be `asset` _or_ `asset2` from the request.) |
| `asset_frozen` | Boolean | _(Omitted for XRP)_ If `true`, the `amount` currency is currently [frozen](freezes.html). |
| `asset2_frozen` | Boolean | _(Omitted for XRP)_ If `true`, the `amount2` currency is currently [frozen](freezes.html). |
| `auction_slot` | Object | _(May be omitted)_ An [Auction Slot Object](#auction-slot-object) describing the current auction slot holder, if there is one. |
| `lp_token` | [Currency Amount][] | The total amount of this AMM's LP Tokens outstanding. |
| `trading_fee` | Number | The AMM's current trading fee, in units of 1/100,000; a value of 1 is equivalent to a 0.001% fee. |
| `vote_slots` | Array | _(May be omitted)_ The current votes for the AMM's trading fee, as [Vote Slot Objects](#vote-slot-objects). |
### Auction Slot Object
The `auction_slot` field of the `amm` object describes the current auction slot holder of the AMM, and contains the following fields:
| Field | Type | Description |
|------------------|---------------------|-------------|
| `account` | String | The [Address][] of the account that owns the auction slot. |
| `auth_accounts` | Array | A list of additional accounts that the auction slot holder has designated as being eligible of the discounted trading fee. Each member of this array is an object with one field, `account`, containing the address of the designated account. |
| `discounted_fee` | Number | The discounted trading fee that applies to the auction slot holder, and any eligible accounts, when trading against this AMM. This is always 0. |
| `expiration` | String | The ISO 8601 UTC timestamp after which this auction slot expires. After expired, the auction slot does not apply (but the data can remain in the ledger until another transaction replaces it or cleans it up). |
| `price` | [Currency Amount][] | The amount, in LP Tokens, that the auction slot holder paid to win the auction slot. This affects the price to outbid the current slot holder. |
| `time_interval` | Number | The current 72-minute time interval this auction slot is in, from 0 to 19. The auction slot expires after 24 hours (20 intervals of 72 minutes) and affects the cost to outbid the current holder and how much the current holder is refunded if someone outbids them. |
### Vote Slot Objects
Each entry in the `vote_slots` array represents one liquidity provider's vote to set the trading fee, and contains the following fields:
| Field | Type | Description |
|---------------|--------|-------------|
| `account` | String | The [Address][] of this liquidity provider. |
| `trading_fee` | Number | The trading fee this liquidity provider voted for, in units of 1/100,000. |
| `vote_weight` | Number | How much this liquidity provider's vote counts towards the final trading fee. This is proportional to how much of the AMM's LP Tokens this liquidity provider holds. The value is equal to 100,000 times the number of this LP Tokens this liquidity provider holds, divided by the total number of LP Tokens outstanding. For example, a value of 1000 means that the liquidity provider holds 1% of this AMM's LP Tokens. |
### Possible Errors
@@ -217,6 +247,13 @@ The response follows the [standard format][], with a successful result containin
- `actNotFound` - The AMM for this asset pair does not exist, or an issuing account specified in the request does not exist.
- `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
## See Also
- [AMM object](amm.html) - The canonical storage format of the AMM object
- [AMMBid][] - More info on the auction slot and bidding mechanism
- [AMMVote][] - More info on the trading fee voting mechanism
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}

43
content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/book_offers.md
View File

@@ -9,7 +9,7 @@ labels:
# book_offers
[[Source]](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/BookOffers.cpp "Source")
The `book_offers` method retrieves a list of offers, also known as the [order book](http://www.investopedia.com/terms/o/order-book.asp), between two currencies.
The `book_offers` method retrieves a list of [Offers](offers.html) between two currencies, also known as an _order book_. The response omits [unfunded Offers](offers.html#lifecycle-of-an-offer) and reports how much of each remaining Offer's total is currently funded.
## Request Format
An example of the request format:
@@ -68,14 +68,15 @@ rippled book_offers 'USD/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B' 'EUR/rvYAfWj5gh67oV6
The request includes the following parameters:
| `Field` | Type | Description |
|:---------------|:-------------------------------------------|:-------------------------------|
| `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 [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |
| `limit` | Unsigned Integer | _(Optional)_ If provided, the server does not provide more than this many offers in the results. The total number of results returned may be fewer than the limit, because the server omits unfunded offers. |
| `taker` | String | _(Optional)_ The [Address][] of an account to use as a perspective. [Unfunded offers](offers.html#lifecycle-of-an-offer) placed by this account are always included in the response. (You can use this to look up your own orders to cancel them.) |
| `taker_gets` | Object | Specification of which currency the account taking the offer would receive, as an object with `currency` and `issuer` fields (omit issuer for XRP), like [currency amounts][Currency Amount]. |
| `taker_pays` | Object | Specification of which currency the account taking the offer would pay, as an object with `currency` and `issuer` fields (omit issuer for XRP), like [currency amounts][Currency Amount]. |
| `Field` | Type | Required? | Description |
|:---------------|:-----------------|:----------|-------------|
| `taker_gets` | Object | Yes | The asset the account taking the Offer would receive, as a [currency without an amount](currency-formats.html#specifying-without-amounts). |
| `taker_pays` | Object | Yes | The asset the account taking the Offer would pay, as a [currency without an amount](currency-formats.html#specifying-without-amounts). |
| `ledger_hash` | [Hash][] | No | A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) |
| `ledger_index` | [Ledger Index][] | No | The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |
| `limit` | Number | No | The maximum number of Offers to return. The response may include fewer results. |
| `taker` | String | No | The [Address][] of an account to use as a perspective. The response includes this account's Offers even if they are unfunded. (You can use this to see what Offers are above or below yours in the order book.) |
## Response Format
@@ -235,21 +236,21 @@ An example of a successful response:
The response follows the [standard format][], with a successful result containing the following fields:
| `Field` | Type | Description |
|:-----------------------|:--------------------------|:------------------------|
| `ledger_current_index` | Number - [Ledger Index][] | _(Omitted if `ledger_current_index` is provided)_ The [ledger index][] of the current in-progress ledger version, which was used to retrieve this information. |
| `ledger_index` | Number - [Ledger Index][] | _(Omitted if `ledger_current_index` provided)_ The ledger index of the ledger version that was used when retrieving this data, as requested. |
| `ledger_hash` | String - [Hash][] | _(May be omitted)_ The identifying hash of the ledger version that was used when retrieving this data, as requested. |
| `offers` | Array | Array of offer objects, each of which has the fields of an [Offer object](offer.html) |
| `Field` | Type | Description |
|:-----------------------|:-----------------|:------------------------|
| `ledger_current_index` | [Ledger Index][] | _(Omitted if `ledger_current_index` is provided)_ The [ledger index][] of the current in-progress ledger version, which was used to retrieve this information. |
| `ledger_index` | [Ledger Index][] | _(Omitted if `ledger_current_index` provided)_ The ledger index of the ledger version that was used when retrieving this data, as requested. |
| `ledger_hash` | [Hash][] | _(May be omitted)_ The identifying hash of the ledger version that was used when retrieving this data, as requested. |
| `offers` | Array | Array of offer objects, each of which has the fields of an [Offer object](offer.html) |
In addition to the standard Offer fields, the following fields may be included in members of the `offers` array:
| `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. |
| `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.) |
| `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. |
| `taker_gets_funded` | [Currency Amount][] | _(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` | [Currency Amount][] | _(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.) |
## Possible Errors

2
content/references/http-websocket-apis/public-api-methods/server-info-methods/server_info.md
View File

@@ -258,7 +258,7 @@ The `info` object may have some arrangement of the following fields:
| `Field` | Type | Description |
|:------------------------------------|:----------------|:---------------------|
| `amendment_blocked` | Boolean | _(May be omitted)_ If `true`, this server is [amendment blocked](amendments.html#amendment-blocked). If the server is not amendment blocked, the response omits this field. [New in: rippled 0.80.0][] |
| `amendment_blocked` | Boolean | _(May be omitted)_ If `true`, this server is [amendment blocked](amendments.html#amendment-blocked-servers). If the server is not amendment blocked, the response omits this field. [New in: rippled 0.80.0][] |
| `build_version` | String | The version number of the running `rippled` server. |
| `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 recently started syncing with the network), this is the string `empty`. |

2
content/references/http-websocket-apis/public-api-methods/server-info-methods/server_state.md
View File

@@ -268,7 +268,7 @@ The `state` object may have some arrangement of the following fields:
| `Field` | Type | Description |
|:---------------------------------|:----------------|:------------------------|
| `amendment_blocked` | Boolean | _(May be omitted)_ If `true`, this server is [amendment blocked](amendments.html#amendment-blocked). If the server is not amendment blocked, the response omits this field. [New in: rippled 0.80.0][] |
| `amendment_blocked` | Boolean | _(May be omitted)_ If `true`, this server is [amendment blocked](amendments.html#amendment-blocked-servers). If the server is not amendment blocked, the response omits this field. [New in: rippled 0.80.0][] |
| `build_version` | String | The version number of the running `rippled` version. |
| `complete_ledgers` | String | Range expression indicating the sequence numbers of the ledger versions the local `rippled` has in its database. It is possible to be a disjoint sequence, e.g. "2500-5000,32570-7695432". If the server does not have any complete ledgers (for example, it recently started syncing with the network), this is the string `empty`. |
| `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. |

2
content/references/http-websocket-apis/public-api-methods/transaction-methods/submit.md
View File

@@ -319,7 +319,7 @@ The response follows the [standard format][], with a successful result containin
## Possible Errors
* Any of the [universal error types][].
* `amendmentBlocked` - The transaction cannot be submitted to the network because the `rippled` server is [amendment blocked](amendments.html#amendment-blocked).
* `amendmentBlocked` - The transaction cannot be submitted to the network because the `rippled` server is [amendment blocked](amendments.html#amendment-blocked-servers).
* `highFee` - The `fee_mult_max` parameter was specified, but the server's current fee multiplier exceeds the specified one. (Sign-and-Submit mode only)
* `internalJson` - An internal error occurred when serializing the transaction to JSON. This could be caused by many aspects of the transaction, including a bad signature or some fields being malformed.
* `internalSubmit` - An internal error occurred when submitting the transaction. This could be caused by many aspects of the transaction, including a bad signature or some fields being malformed.