From 98a759f455520eeaac325c18608adc639a25f279 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Wed, 18 Jan 2023 18:01:49 -0800 Subject: [PATCH 1/8] [DRAFT] updates to ledger_entry for AMM, type filter --- content/_snippets/lowercase-types.md | 1 + .../account-methods/account_objects.md | 2 +- .../ledger-methods/ledger_data.md | 15 ++-- .../ledger-methods/ledger_entry.md | 90 ++++++++++++++++--- .../data-types/currency-formats.md | 19 +++- 5 files changed, 105 insertions(+), 22 deletions(-) create mode 100644 content/_snippets/lowercase-types.md diff --git a/content/_snippets/lowercase-types.md b/content/_snippets/lowercase-types.md new file mode 100644 index 0000000000..1a6bc9e582 --- /dev/null +++ b/content/_snippets/lowercase-types.md @@ -0,0 +1 @@ +The valid types are: `account`, `amendments`, `amm` :not_enabled:, `check`, `deposit_preauth`, `directory`, `escrow`, `nft_offer`, `offer`, `payment_channel`, `signer_list`, `state` (trust line), and `ticket`. \ No newline at end of file diff --git a/content/references/http-websocket-apis/public-api-methods/account-methods/account_objects.md b/content/references/http-websocket-apis/public-api-methods/account-methods/account_objects.md index 3b66f1c66c..470eaa9162 100644 --- a/content/references/http-websocket-apis/public-api-methods/account-methods/account_objects.md +++ b/content/references/http-websocket-apis/public-api-methods/account-methods/account_objects.md @@ -74,7 +74,7 @@ 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`, `state` (trust line), and `nft_offer`. | +| `type` | String | _(Optional)_ If included, filter results to include only this type of ledger object. The valid types are: `check`, `deposit_preauth`, `escrow`, `nft_offer`, `offer`, `payment_channel`, `signer_list`, `state` (trust line), and `ticket`. | | `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][]) | diff --git a/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_data.md b/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_data.md index fd5fe8e6ef..25d0e5b9b5 100644 --- a/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_data.md +++ b/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_data.md @@ -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. Valid values include: The `ledger` field is deprecated and may be removed without further notice. diff --git a/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry.md b/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry.md index 0a9d9b3f08..83dafef40d 100644 --- a/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry.md +++ b/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry.md @@ -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) @@ -47,7 +48,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. | @@ -100,7 +101,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. | @@ -143,12 +144,77 @@ 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). | + + + +*WebSocket* + +```json +{ + "id": 3, + "command": "ledger_entry", + "amm": { + "asset": { + "XRP" + }, + "asset2": { + "currency" : "TST", + "issuer" : "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd" + } + } + "ledger_index": "validated" +} +``` + +*JSON-RPC* + +```json +{ + "method": "ledger_entry", + "params": [ + { + "amm": { + "asset": { + "XRP" + }, + "asset2": { + "currency" : "TST", + "issuer" : "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd" + } + }, + "ledger_index": "validated" + } + ] +} +``` + +*Commandline* + +```sh +rippled json ledger_entry '{ "amm": { "asset": { "XRP" }, "asset2": { "currency" : "TST", "issuer" : "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd" } }, "ledger_index": "validated" }' +``` + + + +[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). | @@ -204,7 +270,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. | @@ -259,7 +325,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). | @@ -318,7 +384,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. | @@ -363,7 +429,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. | @@ -416,7 +482,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. | @@ -460,7 +526,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. | @@ -512,7 +578,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. | @@ -565,7 +631,7 @@ rippled json ledger_entry '{ "ticket": { "account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJ 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. | diff --git a/content/references/protocol-reference/data-types/currency-formats.md b/content/references/protocol-reference/data-types/currency-formats.md index c87a1c5c72..f675d2a197 100644 --- a/content/references/protocol-reference/data-types/currency-formats.md +++ b/content/references/protocol-reference/data-types/currency-formats.md @@ -74,9 +74,24 @@ For example, to represent $153.75 US dollars issued by account `r9cZA1mLK5R5Am25 ### Specifying Without Amounts -If you are specifying a token without an amount (typically for defining an order book in the [decentralized exchange](decentralized-exchange.html)) you should specify it as a currency object, but omit the `value` field. +In some cases, you need to define an asset (which could be XRP or a token) without a specific amount, such as when defining an order book in the [decentralized exchange](decentralized-exchange.html). -If you are specifying XRP without an amount (typically for defining an order book), you should specify it as a JSON object with _only_ a `currency` field. Never include an `issuer` field for XRP. +To describe a token without an amount, specify it as a currency object, but omit the `value` field. For example: + +```json +{ + "currency": "TST", + "issuer": "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd" +} +``` + +To describe XRP without an amount, specify it as a JSON object with _only_ a `currency` field. Never include an `issuer` field for XRP. For example: + +```json +{ + "currency": "XRP" +} +``` ## String Numbers From b8e37727e2722b9066888c00276ea6541982b7a1 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Sat, 21 Jan 2023 04:39:47 -0800 Subject: [PATCH 2/8] ledger_entry amm fixes --- assets/js/apitool-methods-ws.js | 20 +++++++++++++++++++ .../ledger-methods/ledger_entry.md | 7 ++++--- .../data-types/currency-formats.md | 1 - 3 files changed, 24 insertions(+), 4 deletions(-) diff --git a/assets/js/apitool-methods-ws.js b/assets/js/apitool-methods-ws.js index b3b05276c4..522f366f3a 100644 --- a/assets/js/apitool-methods-ws.js +++ b/assets/js/apitool-methods-ws.js @@ -197,6 +197,26 @@ Request('ledger_entry - AccountRoot', { } }) +Request('ledger_entry - AMM', { + description: "Returns a single Automated Market Maker object in its raw ledger format.", + link: "ledger_entry.html#get-amm-object", + status: "not_enabled", + body: { + "id": "example_get_amm", + "command": "ledger_entry", + "amm": { + "asset": { + "currency": "XRP" + }, + "asset2": { + "currency" : "TST", + "issuer" : "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd" + } + }, + "ledger_index": "validated" + } +}) + Request('ledger_entry - DirectoryNode', { description: "Returns a directory object in its raw ledger format.", link: "ledger_entry.html#get-directorynode-object", diff --git a/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry.md b/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry.md index 83dafef40d..d0cd52bf76 100644 --- a/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry.md +++ b/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry.md @@ -166,7 +166,7 @@ Retrieve an Automated Market-Maker (AMM) object from the ledger. This is similar "command": "ledger_entry", "amm": { "asset": { - "XRP" + "currency": "XRP" }, "asset2": { "currency" : "TST", @@ -186,7 +186,7 @@ Retrieve an Automated Market-Maker (AMM) object from the ledger. This is similar { "amm": { "asset": { - "XRP" + "currency": "XRP" }, "asset2": { "currency" : "TST", @@ -202,7 +202,7 @@ Retrieve an Automated Market-Maker (AMM) object from the ledger. This is similar *Commandline* ```sh -rippled json ledger_entry '{ "amm": { "asset": { "XRP" }, "asset2": { "currency" : "TST", "issuer" : "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd" } }, "ledger_index": "validated" }' +rippled json ledger_entry '{ "amm": { "asset": { "currency": "XRP" }, "asset2": { "currency" : "TST", "issuer" : "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd" } }, "ledger_index": "validated" }' ``` @@ -210,6 +210,7 @@ rippled json ledger_entry '{ "amm": { "asset": { "XRP" }, "asset2": { "currency" [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. diff --git a/content/references/protocol-reference/data-types/currency-formats.md b/content/references/protocol-reference/data-types/currency-formats.md index f675d2a197..bd5bc81912 100644 --- a/content/references/protocol-reference/data-types/currency-formats.md +++ b/content/references/protocol-reference/data-types/currency-formats.md @@ -97,7 +97,6 @@ To describe XRP without an amount, specify it as a JSON object with _only_ a `cu ## String Numbers {% include '_snippets/string-number-formatting.md' %} - ## XRP Precision From 10d4b5880a96aa5fe5a70166ad9f80fbdaa34d39 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Tue, 24 Jan 2023 18:18:16 -0800 Subject: [PATCH 3/8] amm_info response format update --- .../path-and-order-book-methods/amm_info.md | 230 ++++++++++-------- 1 file changed, 134 insertions(+), 96 deletions(-) diff --git a/content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/amm_info.md b/content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/amm_info.md index b21761ec20..55b05b4aa6 100644 --- a/content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/amm_info.md +++ b/content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/amm_info.md @@ -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,12 +190,55 @@ 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. | +| `amount2` | [Currency Amount][] | The total amount of the other asset in the AMM's pool. | +| `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. @@ -217,6 +248,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 + {% include '_snippets/rippled-api-links.md' %} {% include '_snippets/tx-type-links.md' %} From 52f8ed4726746f009648a3d1d11e8c49087e341f Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Tue, 24 Jan 2023 18:18:40 -0800 Subject: [PATCH 4/8] book_offers: touch up formatting --- .../book_offers.md | 40 +++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/book_offers.md b/content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/book_offers.md index 9d6f09b928..0da05f33dc 100644 --- a/content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/book_offers.md +++ b/content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/book_offers.md @@ -68,14 +68,14 @@ 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 | Description | +|:---------------|:-----------------|:-------------------------------| +| `ledger_hash` | [Hash][] | _(Optional)_ A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) | +| `ledger_index` | [Ledger Index][] | _(Optional)_ The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) | +| `limit` | Number | _(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]. | ## Response Format @@ -235,21 +235,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 From 418a321b2766a6e2039b966666fe4c90df0041b4 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Tue, 24 Jan 2023 18:38:05 -0800 Subject: [PATCH 5/8] amm_info: clarify amount/amount2 may be swapped due to canonical asset order --- .../path-and-order-book-methods/amm_info.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/amm_info.md b/content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/amm_info.md index 55b05b4aa6..3b967867f7 100644 --- a/content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/amm_info.md +++ b/content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/amm_info.md @@ -206,8 +206,8 @@ The `amm` field is an object describing the current status of an Automated Marke | 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. | -| `amount2` | [Currency Amount][] | The total amount of the other asset in the AMM's pool. | +| `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. | From 840845cb2b71e430506c9f96afc51fe8d3b14e2e Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Tue, 24 Jan 2023 19:02:34 -0800 Subject: [PATCH 6/8] ledger, ledger_data: clarify type filtering --- content/_snippets/lowercase-types.md | 2 +- .../ledger-methods/ledger.md | 24 ++++++++++--------- .../ledger-methods/ledger_data.md | 2 +- 3 files changed, 15 insertions(+), 13 deletions(-) diff --git a/content/_snippets/lowercase-types.md b/content/_snippets/lowercase-types.md index 1a6bc9e582..6506de65f4 100644 --- a/content/_snippets/lowercase-types.md +++ b/content/_snippets/lowercase-types.md @@ -1 +1 @@ -The valid types are: `account`, `amendments`, `amm` :not_enabled:, `check`, `deposit_preauth`, `directory`, `escrow`, `nft_offer`, `offer`, `payment_channel`, `signer_list`, `state` (trust line), and `ticket`. \ No newline at end of file +The valid types are: `account`, `amendments`, `amm` :not_enabled:, `check`, `deposit_preauth`, `directory`, `escrow`, `fee`, `hashes`, `nft_offer`, `offer`, `payment_channel`, `signer_list`, `state` (trust line), and `ticket`. \ No newline at end of file diff --git a/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger.md b/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger.md index 824a96aa8e..8dda1396fa 100644 --- a/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger.md +++ b/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger.md @@ -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][] 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 results to a specific type of ledger entry. {% include '_snippets/lowercase-types.md' %} Ignored unless you request `accounts` (state data). | + The `ledger` field is deprecated and may be removed without further notice. diff --git a/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_data.md b/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_data.md index 25d0e5b9b5..29483c395b 100644 --- a/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_data.md +++ b/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_data.md @@ -57,7 +57,7 @@ A request can include the following fields: | `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. Valid values include: +| `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. From 0e842b1c1dbfb945e4484cbaa87e78bab01ea8e5 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Wed, 25 Jan 2023 17:31:55 -0800 Subject: [PATCH 7/8] amm_info: clarify vote_weight units --- .../path-and-order-book-methods/amm_info.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/amm_info.md b/content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/amm_info.md index 3b967867f7..2abd4d430c 100644 --- a/content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/amm_info.md +++ b/content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/amm_info.md @@ -235,11 +235,10 @@ The `auction_slot` field of the `amm` object describes the current auction slot 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. - +| `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 From f335de0a754d51fdd74b01b276cac016fa52b6aa Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Wed, 25 Jan 2023 17:57:17 -0800 Subject: [PATCH 8/8] account_objects, book_offers, ledger: edit per @oeggert review --- content/_snippets/rippled-api-links.md | 1 + .../account-methods/account_objects.md | 18 +++++++++--------- .../ledger-methods/ledger.md | 4 ++-- .../book_offers.md | 19 ++++++++++--------- 4 files changed, 22 insertions(+), 20 deletions(-) diff --git a/content/_snippets/rippled-api-links.md b/content/_snippets/rippled-api-links.md index 60a7f32666..1663bd88af 100644 --- a/content/_snippets/rippled-api-links.md +++ b/content/_snippets/rippled-api-links.md @@ -118,6 +118,7 @@ "account_objects", "account_offers", "account_tx", + "amm_info", "book_offers", "can_delete", "channel_authorize", diff --git a/content/references/http-websocket-apis/public-api-methods/account-methods/account_objects.md b/content/references/http-websocket-apis/public-api-methods/account-methods/account_objects.md index 470eaa9162..cf0cbcb346 100644 --- a/content/references/http-websocket-apis/public-api-methods/account-methods/account_objects.md +++ b/content/references/http-websocket-apis/public-api-methods/account-methods/account_objects.md @@ -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`, `nft_offer`, `offer`, `payment_channel`, `signer_list`, `state` (trust line), and `ticket`. | -| `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`. | ## Response Format diff --git a/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger.md b/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger.md index 8dda1396fa..8140d138f9 100644 --- a/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger.md +++ b/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger.md @@ -68,13 +68,13 @@ The request can contain the following parameters: | `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][] instead to fetch state data across multiple paginated requests. | +| `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 results to a specific type of ledger entry. {% include '_snippets/lowercase-types.md' %} Ignored unless you request `accounts` (state data). | +| `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. diff --git a/content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/book_offers.md b/content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/book_offers.md index 0da05f33dc..d9fe5102d3 100644 --- a/content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/book_offers.md +++ b/content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/book_offers.md @@ -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` | [Hash][] | _(Optional)_ A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) | -| `ledger_index` | [Ledger Index][] | _(Optional)_ The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) | -| `limit` | Number | _(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