mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-21 04:05:49 +00:00
migrate oracle docs
This commit is contained in:
Oliver Eggert
@@ -282,6 +282,7 @@
|
|||||||
[PaymentChannelFundトランザクション]: /docs/references/protocol/transactions/types/paymentchannelfund.md
|
[PaymentChannelFundトランザクション]: /docs/references/protocol/transactions/types/paymentchannelfund.md
|
||||||
[Payment]: /docs/references/protocol/transactions/types/payment.md
|
[Payment]: /docs/references/protocol/transactions/types/payment.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
|
[RFC-1751]: https://tools.ietf.org/html/rfc1751
|
||||||
[Reporting Mode]: /docs/concepts/networks-and-servers/rippled-server-modes.md#reporting-mode
|
[Reporting Mode]: /docs/concepts/networks-and-servers/rippled-server-modes.md#reporting-mode
|
||||||
[RequireFullyCanonicalSig amendment]: /resources/known-amendments.md#requirefullycanonicalsig
|
[RequireFullyCanonicalSig amendment]: /resources/known-amendments.md#requirefullycanonicalsig
|
||||||
|
|||||||
33
docs/concepts/xrpl-sidechains/price-oracles.md
Normal file
33
docs/concepts/xrpl-sidechains/price-oracles.md
Normal file
@@ -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" /%}
|
||||||
@@ -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 Bridge Object](#get-bridge-object)
|
||||||
- [Get DirectoryNode Object](#get-directorynode-object)
|
- [Get DirectoryNode Object](#get-directorynode-object)
|
||||||
- [Get Offer Object](#get-offer-object)
|
- [Get Offer Object](#get-offer-object)
|
||||||
|
- [Get Oracle Object](#get-oracle-object)
|
||||||
- [Get RippleState Object](#get-ripplestate-object)
|
- [Get RippleState Object](#get-ripplestate-object)
|
||||||
- [Get Check Object](#get-check-object)
|
- [Get Check Object](#get-check-object)
|
||||||
- [Get Escrow Object](#get-escrow-object)
|
- [Get Escrow Object](#get-escrow-object)
|
||||||
@@ -288,7 +289,7 @@ rippled json ledger_entry '{ "bridge_account": "rnQAXXWoFNN6PEqwqsdTngCtFPCrmfuq
|
|||||||
|
|
||||||
{% /tabs %}
|
{% /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
|
### 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)
|
[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
|
### Get RippleState Object
|
||||||
|
|
||||||
|
|||||||
@@ -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" /%}
|
||||||
@@ -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" /%}
|
||||||
44
docs/references/protocol/transactions/types/oracledelete.md
Normal file
44
docs/references/protocol/transactions/types/oracledelete.md
Normal file
@@ -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" /%}
|
||||||
97
docs/references/protocol/transactions/types/oracleset.md
Normal file
97
docs/references/protocol/transactions/types/oracleset.md
Normal file
@@ -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" /%}
|
||||||
@@ -294,6 +294,40 @@
|
|||||||
"ledger_index": "validated"
|
"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",
|
"name": "nft_buy_offers",
|
||||||
"description": "Retrieves offers to buy a given NFT.",
|
"description": "Retrieves offers to buy a given NFT.",
|
||||||
@@ -630,6 +664,21 @@
|
|||||||
"ledger_index": "validated"
|
"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",
|
"name": "ledger_entry - RippleState",
|
||||||
"description": "Returns a RippleState object in its raw ledger format.",
|
"description": "Returns a RippleState object in its raw ledger format.",
|
||||||
|
|||||||
@@ -156,6 +156,7 @@
|
|||||||
expanded: false
|
expanded: false
|
||||||
items:
|
items:
|
||||||
- page: docs/concepts/xrpl-sidechains/cross-chain-bridges.md
|
- 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/concepts/xrpl-sidechains/witness-servers.md
|
||||||
- page: docs/tutorials/index.md
|
- page: docs/tutorials/index.md
|
||||||
label: Tutorials
|
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/nftokenoffer.md
|
||||||
- page: docs/references/protocol/ledger-data/ledger-entry-types/nftokenpage.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/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/paychannel.md
|
||||||
- page: docs/references/protocol/ledger-data/ledger-entry-types/ripplestate.md
|
- page: docs/references/protocol/ledger-data/ledger-entry-types/ripplestate.md
|
||||||
- page: docs/references/protocol/ledger-data/ledger-entry-types/signerlist.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/nftokenmint.md
|
||||||
- page: docs/references/protocol/transactions/types/offercancel.md
|
- page: docs/references/protocol/transactions/types/offercancel.md
|
||||||
- page: docs/references/protocol/transactions/types/offercreate.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/payment.md
|
||||||
- page: docs/references/protocol/transactions/types/paymentchannelclaim.md
|
- page: docs/references/protocol/transactions/types/paymentchannelclaim.md
|
||||||
- page: docs/references/protocol/transactions/types/paymentchannelcreate.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_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/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/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_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/nft_sell_offers.md
|
||||||
- page: docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/path_find.md
|
- page: docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/path_find.md
|
||||||
|
|||||||
Reference in New Issue
Block a user