ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-12-06 17:27:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

add reviewer suggestions

Browse Source
This commit is contained in:
Oliver Eggert
2024-08-28 15:38:46 -07:00
parent 778a589b5e
commit 5bec54f0cb
8 changed files with 107 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry.md
View File

@@ -289,7 +289,7 @@ rippled json ledger_entry '{ "bridge_account": "rnQAXXWoFNN6PEqwqsdTngCtFPCrmfuq
{% /tabs %}
[Try it! >](/resources/dev-tools/websocket-api-tool#ledger_entry-bridge)
[Try it! >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs.devnet.rippletest.net%3A51233%2F#ledger_entry-bridge)
### Get DirectoryNode Object
@@ -408,11 +408,11 @@ _(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` |
| Field | Type | Required? | Description |
|-----------------------------|----------------------|-----------|-------------|
| `oracle` | Object | Yes | The oracle identifier. |
| `oracle.account` | String - [Address][] | Yes | The account that controls the `Oracle` object. |
| `oracle.oracle_document_id` | Number | Yes | A unique identifier of the price oracle for the `Account` |
{% tabs %}
@@ -422,7 +422,7 @@ Retrieve an [Oracle entry](../../../protocol/ledger-data/ledger-entry-types/orac
"id": "example_get_oracle",
"command": "ledger_entry",
"oracle" : {
"account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
"account": "rNZ9m6AP9K7z3EVg6GhPMx36V4QmZKeWds",
"oracle_document_id": 34
},
"ledger_index": "validated"
@@ -437,7 +437,7 @@ Retrieve an [Oracle entry](../../../protocol/ledger-data/ledger-entry-types/orac
"params" : [
{
"oracle" : {
"account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
"account": "rNZ9m6AP9K7z3EVg6GhPMx36V4QmZKeWds",
"oracle_document_id": 34
},
"ledger_index": "validated"
@@ -449,13 +449,13 @@ Retrieve an [Oracle entry](../../../protocol/ledger-data/ledger-entry-types/orac
{% tab label="Commandline" %}
```sh
rippled json ledger_entry '{ "oracle": { "account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW", "oracle_document_id": 34 }, "ledger_index": "validated" }'
rippled json ledger_entry '{ "oracle": { "account": "rNZ9m6AP9K7z3EVg6GhPMx36V4QmZKeWds", "oracle_document_id": 34 }, "ledger_index": "validated" }'
```
{% /tab %}
{% /tabs %}
[Try it! >](/resources/dev-tools/websocket-api-tool#ledger_entry-oracle)
[Try it! >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs.devnet.rippletest.net%3A51233%2F#ledger_entry-oracle)
### Get RippleState Object

92
docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/get_aggregate_price.md
View File

@@ -68,24 +68,16 @@ An example of the request format:
"trim": 20,
"oracles": [
{
"account": "rp047ow9WcPmnNpVHMQV5A4BF6vaL9Abm6",
"account": "rNZ9m6AP9K7z3EVg6GhPMx36V4QmZKeWds",
"oracle_document_id": 34
},
{
"account": "rp147ow9WcPmnNpVHMQV5A4BF6vaL9Abm7",
"oracle_document_id": 56
"account": "rMVKq8zrVsJZQFEiTARyC6WfZznhhLMcNi",
"oracle_document_id": 100
},
{
"account": "rp247ow9WcPmnNpVHMQV5A4BF6vaL9Abm8",
"account": "r92kJTnUbUUq15t2BBZYGYxY79RnNc7rLQ",
"oracle_document_id": 2
},
{
"account": "rp347ow9WcPmnNpVHMQV5A4BF6vaL9Abm9",
"oracle_document_id": 7
},
{
"account": "rp447ow9WcPmnNpVHMQV5A4BF6vaL9Abm0",
"oracle_document_id": 109
}
]
}
@@ -97,7 +89,7 @@ An example of the request format:
{% /tabs %}
[Try it! >](/resources/dev-tools/websocket-api-tool#get_aggregate_price)
[Try it! >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs.devnet.rippletest.net%3A51233%2F#get_aggregate_price)
The request contains the following parameters:
@@ -108,9 +100,14 @@ The request contains the following parameters:
| `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` |
| `oracles` | Array | Yes | An array of oracle identifier objects. You must list between 1 and 200 oracle identifiers. |
Each member of the `oracles` array is an oracle identifier object with the following fields:
| Field | Type | Required? | Description |
|----------------------|--------|-----------|-------------|
| `account` | String | Yes | The XRPL account that controls the `Oracle` object. |
| `oracle_document_id` | Number | Yes | A unique identifier of the price oracle for the `Account` |
## Response Format
@@ -119,35 +116,38 @@ An example of the response format:
```json
{
"entire_set" : {
"mean" : "74.75",
"size" : 10,
"standard_deviation" : "0.1290994448735806"
"result": {
"entire_set": {
"mean": "0.78",
"size": 3,
"standard_deviation": "0.03464101615137754"
},
"ledger_current_index": 3677185,
"median": "0.8",
"time": 1724877762,
"trimmed_set": {
"mean": "0.78",
"size": 3,
"standard_deviation": "0.03464101615137754"
},
"validated": false
},
"ledger_current_index" : 25,
"median" : "74.75",
"status" : "success",
"trimmed_set" : {
"mean" : "74.75",
"size" : 6,
"standard_deviation" : "0.1290994448735806"
},
"validated" : false,
"time" : 78937648
"status": "success",
"type": "response"
}
```
| 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. |
| Field | Type | Description |
|----------------------------------|-----------------|-------------|
| `entire_set` | Object | The statistics from the collected oracle prices. |
| `entire_set.mean` | String - Number | The simple mean. |
| `entire_set.size` | Number | The size of the data set to calculate the mean. |
| `entire_set.standard_deviation` | String - Number | 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 - Number | 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 - Number | The standard deviation of the trimmed data. |
| `time` | Number | The most recent timestamp out of all `LastUpdateTime` values, represented in Unix time. |
{% admonition type="info" name="Notes" %}
@@ -158,4 +158,14 @@ An example of the response format:
{% /admonition %}
## Possible Errors
- Any of the [universal error types][].
- `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
- `internal` - The `trim_threshold` setting removed all prices.
- `objectNotFound` - There are no prices in the dataset.
- `oracleMalformed` - The `oracles` array is malformed. At least one object field is specified incorrectly or missing, or the number of objects is outside the bounds of 1 to 200.
-
{% raw-partial file="/docs/_snippets/common-links.md" /%}

23
docs/references/protocol/ledger-data/ledger-entry-types/oracle.md
View File

@@ -18,7 +18,7 @@ A price oracle object can store information for up to 10 token pairs.
```json
{
"LedgerEntryType": "Oracle",
"Owner": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
"Owner": "rNZ9m6AP9K7z3EVg6GhPMx36V4QmZKeWds",
"Provider": "70726F7669646572",
"AssetClass": "63757272656E6379",
"PriceDataSeries": [
@@ -26,14 +26,14 @@ A price oracle object can store information for up to 10 token pairs.
"PriceData": {
"BaseAsset": "XRP",
"QuoteAsset": "USD",
"AssetPrice": 74,
"Scale": 2,
"AssetPrice": 740,
"Scale": 3,
}
},
],
"LastUpdateTime": 743609414,
"LastUpdateTime": 1724871860,
"PreviousTxnID": "C53ECF838647FA5A4C780377025FEC7999AB4182590510CA461444B207AB74A9",
"PreviousTxnLgrSeq": 56865244
"PreviousTxnLgrSeq": 3675418
}
```
@@ -57,15 +57,20 @@ A price oracle object can store information for up to 10 token pairs.
| 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. |
| `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. |
| `QuoteAsset` | String | Currency | Yes | The quote asset in a trading pair. The quote asset denotes the price of one unit of 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. |
## Oracle Reserve
An `Oracle` object counts as one item for purposes of the [owner reserve](/docs/concepts/accounts/reserves.md#base-reserve-and-owner-reserve) if it contains one to five `PriceData` objects, and counts as two items if it contains six to ten `PriceData` objects.
## 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:
The ID of an `Oracle` object is the [SHA-512Half][] of the following values, concatenated in order:
1. The `Oracle` space key (`0x52`)
2. The `Owner` Account ID.
@@ -74,7 +79,7 @@ The ID of an `Oracle` object is the [SHA-512Half](https://xrpl.org/basic-data-ty
## 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:
The `Currency` field type contains 160 bits of arbitrary data representing a currency or asset code. If the data matches the XRPL's standard format for [currency codes][], the API displays it as a string such as `"USD"`; otherwise, it displays as 40 characters of hexadecimal. The following JSON example represents the `912810RR9/USD` trading pair. The `BaseAsset` is a CUSIP code `912810RR9` represented as a hexadecimal string, and the `QuoteAsset` is a standard `USD` currency code:
```json
{

23
docs/references/protocol/transactions/types/oracleset.md
View File

@@ -13,22 +13,16 @@ _(Requires the [PriceOracle amendment][] {% not-enabled /%})_
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",
"Account": "rNZ9m6AP9K7z3EVg6GhPMx36V4QmZKeWds",
"OracleDocumentID": 34,
"Provider": "70726F7669646572",
"LastUpdateTime": 743609014,
"LastUpdateTime": 1724871860,
"AssetClass": "63757272656E6379",
"PriceDataSeries": [
{
@@ -52,13 +46,13 @@ The oracle provider must complete these steps before submitting this transaction
| `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). |
| `LastUpdateTime` | Number | UInt32 | Yes | The time the data was last updated, in [seconds since the Ripple Epoch][]. |
| `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
| `LastUpdateTime` | Number | UInt32 | Yes | The time the data was last updated, in [seconds since the Ripple Epoch][]. |
| 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. |
@@ -73,12 +67,9 @@ The oracle provider must complete these steps before submitting this transaction
- 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.
{% admonition type="info" name="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`.
{% /admonition %}
## Error Cases