From cc16be90666484bf402dd4d57128541247197aa8 Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Thu, 8 Aug 2024 18:39:31 -0700 Subject: [PATCH] migrate oracle docs --- docs/_snippets/common-links.md | 1 + .../concepts/xrpl-sidechains/price-oracles.md | 33 ++++ .../ledger-methods/ledger_entry.md | 58 ++++++- .../get_aggregate_price.md | 161 ++++++++++++++++++ .../ledger-data/ledger-entry-types/oracle.md | 90 ++++++++++ .../transactions/types/oracledelete.md | 44 +++++ .../protocol/transactions/types/oracleset.md | 97 +++++++++++ .../websocket-api/data/command-list.json | 49 ++++++ sidebars.yaml | 5 + 9 files changed, 537 insertions(+), 1 deletion(-) create mode 100644 docs/concepts/xrpl-sidechains/price-oracles.md create mode 100644 docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/get_aggregate_price.md create mode 100644 docs/references/protocol/ledger-data/ledger-entry-types/oracle.md create mode 100644 docs/references/protocol/transactions/types/oracledelete.md create mode 100644 docs/references/protocol/transactions/types/oracleset.md diff --git a/docs/_snippets/common-links.md b/docs/_snippets/common-links.md index 29ab597dc5..4b78a4d285 100644 --- a/docs/_snippets/common-links.md +++ b/docs/_snippets/common-links.md @@ -282,6 +282,7 @@ [PaymentChannelFundトランザクション]: /docs/references/protocol/transactions/types/paymentchannelfund.md [Payment]: /docs/references/protocol/transactions/types/payment.md [Paymentトランザクション]: /docs/references/protocol/transactions/types/payment.md +[PriceOracle amendment]: /resources/known-amendments.md#PriceOracle [RFC-1751]: https://tools.ietf.org/html/rfc1751 [Reporting Mode]: /docs/concepts/networks-and-servers/rippled-server-modes.md#reporting-mode [RequireFullyCanonicalSig amendment]: /resources/known-amendments.md#requirefullycanonicalsig diff --git a/docs/concepts/xrpl-sidechains/price-oracles.md b/docs/concepts/xrpl-sidechains/price-oracles.md new file mode 100644 index 0000000000..49d2ff7b77 --- /dev/null +++ b/docs/concepts/xrpl-sidechains/price-oracles.md @@ -0,0 +1,33 @@ +# Price Oracles + +_(Requires the [PriceOracle amendment][] {% not-enabled /%})_ + +Blockchains can't inherintly interact with and "know" what's happening off the network, but many of its use cases in decentralized finance require this information. + +Price oracles solve this problem. An oracle is a service or technology that gathers real-world information, such as market prices, exchange rates, or interest rates, and relays it to the blockchain. Like blockchains, most oracles are also decentralized and validate data through multiple nodes. + +{% admonition type="info" name="Note" %} + +Oracles aren't limited to only providing financial information. It can provide any type of info, such as what sports team won a game, or even the weather. The oracle implementation on the XRP Ledger, however, only gathers the price of assets. + +{% /admonition %} + + +## How Oracles Works + +Most oracle blockchain interactions work like this: + +1. An oracle validates data on its network. +2. The data is sent to the blockchain. +3. The blockchain uses that information to execute a smart contract, such as releasing funds from an escrow. + +This process can also work in reverse, pushing transaction information to external systems. + + +## Price Oracles on the XRP Ledger + +XRPL price oracles are a native, on-chain oracle, enhancing the native DeFi functionality of the XRP Ledger. Off-chain price oracles send their data to XRPL oracles, which store that information on-chain. Decentralized apps can then query the XRPL oracles for price data; multiple XRPL oracles can be queried to minimize risk and inaccuracies. + +By standardizing price feeds in this manner, all XRPL apps can access a dependable, shared data source. + +{% raw-partial file="/docs/_snippets/common-links.md" /%} diff --git a/docs/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry.md b/docs/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry.md index 461d422b7d..b06dfc360d 100644 --- a/docs/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry.md +++ b/docs/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry.md @@ -40,6 +40,7 @@ In addition to the general fields above, you must specify *exactly 1* of the fol - [Get Bridge Object](#get-bridge-object) - [Get DirectoryNode Object](#get-directorynode-object) - [Get Offer Object](#get-offer-object) + - [Get Oracle Object](#get-oracle-object) - [Get RippleState Object](#get-ripplestate-object) - [Get Check Object](#get-check-object) - [Get Escrow Object](#get-escrow-object) @@ -288,7 +289,7 @@ rippled json ledger_entry '{ "bridge_account": "rnQAXXWoFNN6PEqwqsdTngCtFPCrmfuq {% /tabs %} -[Try it! >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs.devnet.rippletest.net%3A51233%2F#ledger_entry-bridge) +[Try it! >](/resources/dev-tools/websocket-api-tool#ledger_entry-bridge) ### Get DirectoryNode Object @@ -401,6 +402,61 @@ rippled json ledger_entry '{ "offer": { "account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJY [Try it! >](/resources/dev-tools/websocket-api-tool#ledger_entry-offer) +### Get Oracle Object + +_(Requires the [PriceOracle amendment][] {% not-enabled /%})_ + +Retrieve an [Oracle entry](../../../protocol/ledger-data/ledger-entry-types/oracle.md), which represents a single price oracle that can store token prices. + +| Field | Type | Required? | Description | +|-----------------------------|--------|-----------|-------------| +| `oracle` | Object | Yes | The oracle identifier. | +| `oracle.account` | String | Yes | The XRPL account that controls the `Oracle` object. | +| `oracle.oracle_document_id` | Number | Yes | A unique identifier of the price oracle for the `Account` | + +{% tabs %} + +{% tab label="WebSocket" %} +```json +{ + "id": "example_get_oracle", + "command": "ledger_entry", + "oracle" : { + "account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW", + "oracle_document_id": 34 + }, + "ledger_index": "validated" +} +``` +{% /tab %} + +{% tab label="JSON-RPC" %} +```json +{ + "method": "ledger_entry", + "params" : [ + { + "oracle" : { + "account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW", + "oracle_document_id": 34 + }, + "ledger_index": "validated" + } + ] +} +``` +{% /tab %} + +{% tab label="Commandline" %} +```sh +rippled json ledger_entry '{ "oracle": { "account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW", "oracle_document_id": 34 }, "ledger_index": "validated" }' +``` +{% /tab %} + +{% /tabs %} + +[Try it! >](/resources/dev-tools/websocket-api-tool#ledger_entry-oracle) + ### Get RippleState Object diff --git a/docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/get_aggregate_price.md b/docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/get_aggregate_price.md new file mode 100644 index 0000000000..128109a47b --- /dev/null +++ b/docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/get_aggregate_price.md @@ -0,0 +1,161 @@ +--- +html: get_aggregate_price.html +parent: ledger-methods.html +blurb: Calculates the aggregate price of specified Oracle instances. +status: not_enabled +labels: + - Oracle +--- +# get_aggregate_price + +_(Requires the [PriceOracle amendment][] {% not-enabled /%})_ + +[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/rpc/handlers/GetAggregatePrice.cpp "Source") + + +The `get_aggregate_price` method retrieves the aggregate price of specified `Oracle` objects, returning three price statistics: mean, median, and trimmed mean. + + +## Request Format + +An example of the request format: + +{% tabs %} + +{% tab label="WebSocket" %} +```json +{ + "command": "get_aggregate_price", + "ledger_index": "current", + "base_asset": "XRP", + "quote_asset": "USD", + "trim": 20, + "oracles": [ + { + "account": "rp047ow9WcPmnNpVHMQV5A4BF6vaL9Abm6", + "oracle_document_id": 34 + }, + { + "account": "rp147ow9WcPmnNpVHMQV5A4BF6vaL9Abm7", + "oracle_document_id": 56 + }, + { + "account": "rp247ow9WcPmnNpVHMQV5A4BF6vaL9Abm8", + "oracle_document_id": 2 + }, + { + "account": "rp347ow9WcPmnNpVHMQV5A4BF6vaL9Abm9", + "oracle_document_id": 7 + }, + { + "account": "rp447ow9WcPmnNpVHMQV5A4BF6vaL9Abm0", + "oracle_document_id": 109 + } + ] +} +``` +{% /tab %} + +{% tab label="JSON-RPC" %} +```json +{ + "method": "get_aggregate_price", + "params": [ + { + "ledger_index": "current", + "base_asset": "XRP", + "quote_asset": "USD", + "trim": 20, + "oracles": [ + { + "account": "rp047ow9WcPmnNpVHMQV5A4BF6vaL9Abm6", + "oracle_document_id": 34 + }, + { + "account": "rp147ow9WcPmnNpVHMQV5A4BF6vaL9Abm7", + "oracle_document_id": 56 + }, + { + "account": "rp247ow9WcPmnNpVHMQV5A4BF6vaL9Abm8", + "oracle_document_id": 2 + }, + { + "account": "rp347ow9WcPmnNpVHMQV5A4BF6vaL9Abm9", + "oracle_document_id": 7 + }, + { + "account": "rp447ow9WcPmnNpVHMQV5A4BF6vaL9Abm0", + "oracle_document_id": 109 + } + ] + } + ] +} +``` +{% /tab %} + +{% /tabs %} + + +[Try it! >](/resources/dev-tools/websocket-api-tool#get_aggregate_price) + + +The request contains the following parameters: + +| Field | Type | Required? | Description | +|------------------------------|--------|-----------|-------------| +| `base_asset` | String | Yes | The currency code of the asset to be priced. | +| `quote_asset` | String | Yes | The currency code of the asset to quote the price of the base asset. | +| `trim` | Number | No | The percentage of outliers to trim. Valid trim range is 1-25. If included, the API returns statistics for the `trimmed mean`. | +| `trim_threshold` | Number | No | Defines a time range in seconds for filtering out older price data. Default value is 0, which doesn't filter any data. | +| `oracles` | Array | Yes | The oracle identifier. | +| `oracles.account` | String | Yes | The XRPL account that controls the `Oracle` object. | +| `oracles.oracle_document_id` | Number | Yes | A unique identifier of the price oracle for the `Account` | + + +## Response Format + +An example of the response format: + +```json +{ + "entire_set" : { + "mean" : "74.75", + "size" : 10, + "standard_deviation" : "0.1290994448735806" + }, + "ledger_current_index" : 25, + "median" : "74.75", + "status" : "success", + "trimmed_set" : { + "mean" : "74.75", + "size" : 6, + "standard_deviation" : "0.1290994448735806" + }, + "validated" : false, + "time" : 78937648 +} +``` + +| Field | Type | Description | +|-----------------------------|--------|-------------| +| `entire_set` | Object | The statistics from the collected oracle prices. | +| `entire_set.mean` | String | The simple mean. | +| `entire_set.size` | Number | The size of the data set to calculate the mean. | +| `entire_set.standard_deviation` | String | The standard deviation. | +| `trimmed_set` | Object | The trimmed statistics from the collected oracle prices. Only appears if the `trim` field was specified in the request. | +| `trimmed_set.mean` | String | The simple mean of the trimmed data. | +| `trimmed_set.size` | Number | The size of the data to calculate the trimmed mean. | +| `trimmed_set.standard_deviation` | String | The standard deviation of the trimmed data. | +| `time` | Number | The most recent timestamp out of all `LastUpdateTime` values. | + +{% admonition type="info" name="Notes" %} + +- The most recent `Oracle` objects are obtained for the specified oracles. +- The most recent `LastUpdateTime` among all objects is chosen as the upper time threshold. +- An `Oracle` object is included in the aggregation dataset if it contains the specified `base_asset`/`quote_asset` pair, has an `AssetPrice` field, and its `LastUpdateTime` is within the time range specified. +- If an `Oracle` object doesn't contain an `AssetPrice` for the specified token pair, then up to three previous `Oracle` objects are examined and the most recent one that fulfills the requirements is included. + +{% /admonition %} + +{% raw-partial file="/docs/_snippets/common-links.md" /%} diff --git a/docs/references/protocol/ledger-data/ledger-entry-types/oracle.md b/docs/references/protocol/ledger-data/ledger-entry-types/oracle.md new file mode 100644 index 0000000000..f693988b9d --- /dev/null +++ b/docs/references/protocol/ledger-data/ledger-entry-types/oracle.md @@ -0,0 +1,90 @@ +# Oracle + +_(Requires the [PriceOracle amendment][] {% not-enabled /%})_ + +[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/LedgerFormats.cpp#L353-L366 "Source") + +An `Oracle` ledger entry holds data associated with a single price oracle object. + +{% admonition type="info" name="Note" %} + +A price oracle object can store information for up to 10 token pairs. + +{% /admonition %} + + +## Example Oracle JSON + +```json +{ + "LedgerEntryType": "Oracle", + "Owner": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW", + "Provider": "70726F7669646572", + "AssetClass": "63757272656E6379", + "PriceDataSeries": [ + { + "PriceData": { + "BaseAsset": "XRP", + "QuoteAsset": "USD", + "AssetPrice": 74, + "Scale": 2, + } + }, + ], + "LastUpdateTime": 743609414, + "PreviousTxnID": "C53ECF838647FA5A4C780377025FEC7999AB4182590510CA461444B207AB74A9", + "PreviousTxnLgrSeq": 56865244 +} +``` + + +## Oracle Fields + +| Field | JSON Type | Internal Type | Required? | Description | +|---------------------|-----------|---------------|-----------|-------------| +| `Owner` | String | AccountID | Yes | The XRPL account with update and delete privileges for the oracle. It's recommended to set up [multi-signing](https://xrpl.org/set-up-multi-signing.html) on this account. | +| `Provider` | String | Blob | Yes | An arbitrary value that identifies an oracle provider, such as Chainlink, Band, or DIA. This field is a string, up to 256 ASCII hex encoded characters (0x20-0x7E). | +| `PriceDataSeries` | Array | Array | Yes | An array of up to 10 `PriceData` objects, each representing the price information for a token pair. More than five `PriceData` objects require two owner reserves. | +| `LastUpdateTime` | Number | UInt32 | Yes | The time the data was last updated, represented in Unix time. | +| `URI` | String | Blob | No | An optional Universal Resource Identifier to reference price data off-chain. This field is limited to 256 bytes. | +| `AssetClass` | String | Blob | Yes | Describes the type of asset, such as "currency", "commodity", or "index". This field is a string, up to 16 ASCII hex encoded characters (0x20-0x7E). | +| `OwnerNode` | String | UInt64 | Yes | A hint indicating which page of the oracle owner's owner directory links to this entry, in case the directory consists of multiple pages. | +| `PreviousTxnID` | String | UInt256 | Yes | The hash of the previous transaction that modified this entry. | +| `PreviousTxnLgrSeq` | String | UInt32 | Yes | The ledger index that this object was most recently modified or created in. | + + +### PriceData Fields + +| Field | JSON Type | Internal Type | Required? | Description | +|---------------------|-----------|---------------|-----------|-------------| +| `BaseAsset` | String | Currency | Yes | The primary asset in a trading pair. Any valid identifier, such as a stock symbol, bond CUSIP, or currency code is allowed. For example, in the BTC/USD pair, BTC is the base asset; in 912810RR9/BTC, 912810RR9 is the base asset. | +| `QuoteAsset` | String | Currency | Yes | The quote asset in a trading pair. The quote asset denotes the price of one unit of the base asset. For example, in the BTC/USD pair, USD is the quote asset; in 912810RR9/BTC, BTC is the quote asset. | +| `AssetPrice` | Number | UInt64 | No | The asset price after applying the `Scale` precision level. It's not included if the last update transaction didn't include the `BaseAsset`/`QuoteAsset` pair. | +| `Scale` | Number | UInt8 | No | The scaling factor to apply to an asset price. For example, if `Scale` is 6 and original price is 0.155, then the scaled price is 155000. Valid scale ranges are 0-10. It's not included if the last update transaction didn't include the `BaseAsset`/`QuoteAsset` pair. | + + +## Oracle ID Format + +The ID of an `Oracle` object is the [SHA-512Half](https://xrpl.org/basic-data-types.html#hashes) of the following values, concatenated in order: + +1. The `Oracle` space key (`0x52`) +2. The `Owner` Account ID. +3. The `OracleDocumentID`. + + +## Currency Internal Format + +The `Currency` field type represents a standard currency code, such as XRP, or an arbitrary asset as a 160-bit (40 character) hexadecimal string. This type is generally conformant to the XRPL [currency codes](https://xrpl.org/currency-formats.html#standard-currency-codes) format. Below is a JSON example with `BaseAsset` representing a CUSIP code `912810RR9` as a 160-bit hexadecimal string and `QuoteAsset` representing a standard `USD` currency code: + +```json +{ + "PriceData" : { + "BaseAsset" : "3931323831305252390000000000000000000000", + "QuoteAsset" : "USD", + "Scale" : 1, + "SymbolPrice" : 740 + } +} +``` + +{% raw-partial file="/docs/_snippets/common-links.md" /%} diff --git a/docs/references/protocol/transactions/types/oracledelete.md b/docs/references/protocol/transactions/types/oracledelete.md new file mode 100644 index 0000000000..ac1f6afef3 --- /dev/null +++ b/docs/references/protocol/transactions/types/oracledelete.md @@ -0,0 +1,44 @@ +--- +html: oracledelete.html +parent: transaction-types.html +blurb: Delete an existing price oracle. +labels: + - Oracle +status: not_enabled +--- +# OracleDelete +_(Requires the [PriceOracle amendment][] {% not-enabled /%})_ + +[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/DeleteOracle.cpp "Source") + +Delete an `Oracle` ledger entry. + + +## Example OracleDelete JSON + +```json +{ + "TransactionType": "OracleDelete", + "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW", + "OracleDocumentID": 34 +} +``` + + +## OracleDelete Fields + +| Field | JSON Type | Internal Type | Required? | Description | +|--------------------|-----------|---------------|-----------|-------------| +| `Account` | String | AccountID | Yes | This account must match the account in the `Owner` field of the `Oracle` object. | +| `OracleDocumentID` | String | UInt32 | Yes | A unique identifier of the price oracle for the `Account`. | + + +## Error Cases + +Besides errors that can occur for all transactions, `OracleDelete` transactions can result in the following transaction result codes. + +| Error Code | Description | +|---------------|-------------| +| `tecNO_ENTRY` | The `Oracle` object doesn't exist. | + +{% raw-partial file="/docs/_snippets/common-links.md" /%} diff --git a/docs/references/protocol/transactions/types/oracleset.md b/docs/references/protocol/transactions/types/oracleset.md new file mode 100644 index 0000000000..01b363c4c4 --- /dev/null +++ b/docs/references/protocol/transactions/types/oracleset.md @@ -0,0 +1,97 @@ +--- +html: OracleSet.html +parent: transaction-types.html +blurb: Create or update an existing price oracle. +labels: + - Oracle +status: not_enabled +--- +# OracleSet +_(Requires the [PriceOracle amendment][] {% not-enabled /%})_ + +[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/SetOracle.cpp "Source") + +Creates a new `Oracle` ledger entry or updates the fields of an existing one, using the Oracle ID. + +The oracle provider must complete these steps before submitting this transaction: + +1. Create or own the XRPL account in the `Owner` field and have enough XRP to meet the reserve and transaction fee requirements. +2. Publish the XRPL account public key, so it can be used for verification by dApps. +3. Publish a registry of available price oracles with their unique `OracleDocumentID`. + + +## Example OracleSet JSON + +```json +{ + "TransactionType": "OracleSet", + "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW", + "OracleDocumentID": 34, + "Provider": "70726F7669646572", + "LastUpdateTime": 743609014, + "AssetClass": "63757272656E6379", + "PriceDataSeries": [ + { + "PriceData": { + "BaseAsset": "XRP", + "QuoteAsset": "USD", + "AssetPrice": 740, + "Scale": 3 + } + } + ] +} +``` + + +## OracleSet Fields + +| Field | JSON Type | Internal Type | Required? | Description | +|--------------------|-----------|---------------|-----------|-------------| +| `Account` | String | AccountID | Yes | This account must match the account in the `Owner` field of the `Oracle` object. | +| `OracleDocumentID` | Number | UInt32 | Yes | A unique identifier of the price oracle for the `Account`. | +| `Provider` | String | Blob | Variable | An arbitrary value that identifies an oracle provider, such as Chainlink, Band, or DIA. This field is a string, up to 256 ASCII hex encoded characters (0x20-0x7E). This field is required when creating a new `Oracle` ledger entry, but is optional for updates. | +| `URI` | String | Blob | No | An optional Universal Resource Identifier to reference price data off-chain. This field is limited to 256 bytes. | +| `LastUpdateTime` | Number | UInt32 | Yes | The time the data was last updated, represented in the [ripple epoch time](https://xrpl.org/basic-data-types.html#specifying-time). | +| `AssetClass` | String | Blob | Variable | Describes the type of asset, such as "currency", "commodity", or "index". This field is a string, up to 16 ASCII hex encoded characters (0x20-0x7E). This field is required when creating a new `Oracle` ledger entry, but is optional for updates. | +| `PriceDataSeries` | Array | Array | Yes | An array of up to 10 `PriceData` objects, each representing the price information for a token pair. More than five `PriceData` objects require two owner reserves. | + + +### PriceData Fields + +| Field | JSON Type | Internal Type | Required? | Description | +|---------------------|-----------|---------------|-----------|-------------| +| `BaseAsset` | String | Currency | Yes | The primary asset in a trading pair. Any valid identifier, such as a stock symbol, bond CUSIP, or currency code is allowed. For example, in the BTC/USD pair, BTC is the base asset; in 912810RR9/BTC, 912810RR9 is the base asset. | +| `QuoteAsset` | String | Currency | Yes | The quote asset in a trading pair. The quote asset denotes the price of one unit of the base asset. For example, in the BTC/USD pair, BTC is the base asset; in 912810RR9/BTC, 912810RR9 is the base asset. | +| `AssetPrice` | Number | UInt64 | No | The asset price after applying the `Scale` precision level. It's not included if the last update transaction didn't include the `BaseAsset`/`QuoteAsset` pair. | +| `Scale` | Number | UInt8 | No | The scaling factor to apply to an asset price. For example, if `Scale` is 6 and original price is 0.155, then the scaled price is 155000. Valid scale ranges are 0-10. It's not included if the last update transaction didn't include the `BaseAsset`/`QuoteAsset` pair.| + +`PriceData` is created or updated, following these rules: + +- New token pairs in the transaction are added to the object. +- Token pairs in the transaction overwrite corresponding token pairs in the object. +- Token pairs in the transaction with a missing `AssetPrice` field delete corresponding token pairs in the object. +- Token pairs that only appear in the object have `AssetPrice` and `Scale` removed to signify that the price is outdated. + +**Note:** The order of token pairs in the transaction aren't important because each token pair uniquely identifies the location of the `PriceData` object in the `PriceDataSeries`. + + +## Reserve Requirements + +The owner reserve requirement is 1 for one to five `PriceData` objects, and 2 for six to ten `PriceData` objects. + + +## Error Cases + +Besides errors that can occur for all transactions, `OracleSet` transactions can result in the following transaction result codes. + +| Error Code | Description | +|---------------------------|-------------| +| `temARRAY_EMPTY` | The `PriceDataSeries` has no `PriceData` objects. | +| `tecARRAY_TOO_LARGE` | The `PriceDataSeries` exceeds the ten `PriceData` objects limit. | +| `tecINVALID_UPDATE_TIME` | The `Oracle` object has an invalid `LastUpdateTime` value. | +| `tecTOKEN_PAIR_NOT_FOUND` | The token pair you're trying to delete doesn't exist in the `Oracle` object. | +| `tecARRAY_EMPTY` | The `PriceDataSeries` has no `PriceData` objects. | +| `temARRAY_TOO_LARGE` | The `PriceDataSeries` exceeds the ten `PriceData` objects limit. | + +{% raw-partial file="/docs/_snippets/common-links.md" /%} diff --git a/resources/dev-tools/components/websocket-api/data/command-list.json b/resources/dev-tools/components/websocket-api/data/command-list.json index a3f1243690..3ca5f9befa 100644 --- a/resources/dev-tools/components/websocket-api/data/command-list.json +++ b/resources/dev-tools/components/websocket-api/data/command-list.json @@ -294,6 +294,40 @@ "ledger_index": "validated" } }, + { + "name": "get_aggregate_price", + "description": "Retrieves the aggregate price of specified Oracle objects, returning three price statistics: mean, median, and trimmed mean.", + "link": "/docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/get_aggregate_price", + "body": { + "command": "get_aggregate_price", + "ledger_index": "current", + "base_asset": "XRP", + "quote_asset": "USD", + "trim": 20, + "oracles": [ + { + "account": "rp047ow9WcPmnNpVHMQV5A4BF6vaL9Abm6", + "oracle_document_id": 34 + }, + { + "account": "rp147ow9WcPmnNpVHMQV5A4BF6vaL9Abm7", + "oracle_document_id": 56 + }, + { + "account": "rp247ow9WcPmnNpVHMQV5A4BF6vaL9Abm8", + "oracle_document_id": 2 + }, + { + "account": "rp347ow9WcPmnNpVHMQV5A4BF6vaL9Abm9", + "oracle_document_id": 7 + }, + { + "account": "rp447ow9WcPmnNpVHMQV5A4BF6vaL9Abm0", + "oracle_document_id": 109 + } + ] + } + }, { "name": "nft_buy_offers", "description": "Retrieves offers to buy a given NFT.", @@ -630,6 +664,21 @@ "ledger_index": "validated" } }, + { + "name": "ledger_entry - Oracle", + "description": "Returns a single Oracle object in its raw ledger format.", + "link": "/docs/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry#get-oracle-object", + "status": "not_enabled", + "body": { + "id": "example_get_oracle", + "command": "ledger_entry", + "oracle" : { + "account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW", + "oracle_document_id": 34 + }, + "ledger_index": "validated" + } + }, { "name": "ledger_entry - RippleState", "description": "Returns a RippleState object in its raw ledger format.", diff --git a/sidebars.yaml b/sidebars.yaml index 59677e61a6..a98386381b 100644 --- a/sidebars.yaml +++ b/sidebars.yaml @@ -156,6 +156,7 @@ expanded: false items: - page: docs/concepts/xrpl-sidechains/cross-chain-bridges.md + - page: docs/concepts/xrpl-sidechains/price-oracles.md - page: docs/concepts/xrpl-sidechains/witness-servers.md - page: docs/tutorials/index.md label: Tutorials @@ -330,6 +331,7 @@ - page: docs/references/protocol/ledger-data/ledger-entry-types/nftokenoffer.md - page: docs/references/protocol/ledger-data/ledger-entry-types/nftokenpage.md - page: docs/references/protocol/ledger-data/ledger-entry-types/offer.md + - page: docs/references/protocol/ledger-data/ledger-entry-types/oracle.md - page: docs/references/protocol/ledger-data/ledger-entry-types/paychannel.md - page: docs/references/protocol/ledger-data/ledger-entry-types/ripplestate.md - page: docs/references/protocol/ledger-data/ledger-entry-types/signerlist.md @@ -368,6 +370,8 @@ - page: docs/references/protocol/transactions/types/nftokenmint.md - page: docs/references/protocol/transactions/types/offercancel.md - page: docs/references/protocol/transactions/types/offercreate.md + - page: docs/references/protocol/transactions/types/oracledelete.md + - page: docs/references/protocol/transactions/types/oracleset.md - page: docs/references/protocol/transactions/types/payment.md - page: docs/references/protocol/transactions/types/paymentchannelclaim.md - page: docs/references/protocol/transactions/types/paymentchannelcreate.md @@ -471,6 +475,7 @@ - page: docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/book_changes.md - page: docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/book_offers.md - page: docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/deposit_authorized.md + - page: docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/get_aggregate_price.md - page: docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/nft_buy_offers.md - page: docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/nft_sell_offers.md - page: docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/path_find.md