add reviewer suggestions

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

View File

@@ -252,6 +252,12 @@
[OfferCreateトランザクション]: /docs/references/protocol/transactions/types/offercreate.md
[Offerエントリ]: /docs/references/protocol/ledger-data/ledger-entry-types/offer.md
[Offerオブジェクト]: /docs/references/protocol/ledger-data/ledger-entry-types/offer.md
[OracleDelete transaction]: /docs/references/protocol/transactions/types/oracledelete.md
[OracleDelete transactions]: /docs/references/protocol/transactions/types/oracledelete.md
[Oracle entry]: /docs/references/protocol/ledger-data/ledger-entry-types/oracle.md
[Oracle object]: /docs/references/protocol/ledger-data/ledger-entry-types/oracle.md
[OracleSet transaction]: /docs/references/protocol/transactions/types/oracleset.md
[OracleSet transactions]: /docs/references/protocol/transactions/types/oracleset.md
[OwnerPaysFee amendment]: /resources/known-amendments.md#ownerpaysfee
[OwnerPaysFeeの修正]: /resources/known-amendments.md#ownerpaysfee
[PayChan amendment]: /resources/known-amendments.md#paychan
@@ -499,6 +505,8 @@
[fixTakerDryOfferRemovalの修正]: /resources/known-amendments.md#fixtakerdryofferremoval
[fixTrustLinesToSelf amendment]: /resources/known-amendments.md#fixtrustlinestoself
[fixTrustLinesToSelfの修正]: /resources/known-amendments.md#fixtrustlinestoself
[get_aggregate_price command]: /docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/get_aggregate_price.md
[get_aggregate_price method]: /docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/get_aggregate_price.md
[gateway_balances command]: /docs/references/http-websocket-apis/public-api-methods/account-methods/gateway_balances.md
[gateway_balances method]: /docs/references/http-websocket-apis/public-api-methods/account-methods/gateway_balances.md
[gateway_balances メソッド]: /docs/references/http-websocket-apis/public-api-methods/account-methods/gateway_balances.md

View File

@@ -38,7 +38,7 @@ An exception to the owner reserve is that you can create your first two trust li
Many objects in the ledger (ledger entries) are owned by a particular account. Usually, the owner is the account that created the object. Each object increases the owner's total reserve requirement by the owner reserve. When objects are removed from the ledger, they no longer count against the reserve requirement.
Objects that count towards their owner's reserve requirement include: [Checks](../payment-types/checks.md), [Deposit Preauthorizations](depositauth.md#preauthorization), [Escrows](../payment-types/escrow.md), [NFT Offers](../tokens/nfts/trading.md), [NFT Pages](../tokens/nfts/index.md), [Offers](../../references/protocol/ledger-data/ledger-entry-types/offer.md), [Payment Channels](../payment-types/payment-channels.md), [Signer Lists](multi-signing.md), [Tickets](tickets.md), and [Trust Lines](../tokens/fungible-tokens/index.md).
Objects that count towards their owner's reserve requirement include: [Checks](../payment-types/checks.md), [Deposit Preauthorizations](depositauth.md#preauthorization), [Escrows](../payment-types/escrow.md), [NFT Offers](../tokens/nfts/trading.md), [NFT Pages](../tokens/nfts/index.md), [Offers](../../references/protocol/ledger-data/ledger-entry-types/offer.md), [Oracles](../xrpl-sidechains/price-oracles.md), [Payment Channels](../payment-types/payment-channels.md), [Signer Lists](multi-signing.md), [Tickets](tickets.md), and [Trust Lines](../tokens/fungible-tokens/index.md).
Some special cases:
@@ -46,6 +46,7 @@ Some special cases:
- Trust lines (`RippleState` entries) are shared between two accounts. The owner reserve can apply to one or both of them. Most often, the token holder owes a reserve and the issuer does not. See also: [RippleState: Contributing to the Owner Reserve](../../references/protocol/ledger-data/ledger-entry-types/ripplestate.md#contributing-to-the-owner-reserve).
- Signer lists created before the [MultiSignReserve amendment][] activated in April 2019 count as multiple objects. See also: [Signer Lists and Reserves](../../references/protocol/ledger-data/ledger-entry-types/signerlist.md#signer-lists-and-reserves).
- An [Owner Directory](../../references/protocol/ledger-data/ledger-entry-types/directorynode.md) is a ledger entry that lists all objects related to an account, including all objects the account owns. However, the owner directory itself does not count towards the reserve.
- Oracles count as one item for the owner reserve if it contains one to five `PriceData` objects, or two items if it contains six to ten `PriceData` objects.
### Looking Up Reserves

View File

@@ -8,7 +8,7 @@ Price oracles solve this problem. An oracle is a service or technology that gath
{% 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.
Generally speaking, oracles aren't limited to only providing financial information. They can provide any type of info, such as what sports team won a game, or even the weather. The XRP Ledger's Price Oracle feature, however, is designed specifically for reporting the prices of assets.
{% /admonition %}
@@ -17,7 +17,7 @@ Oracles aren't limited to only providing financial information. It can provide a
Most oracle blockchain interactions work like this:
1. An oracle validates data on its network.
1. Data is validated offchain by a decentralized oracle 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.
@@ -30,4 +30,12 @@ XRPL price oracles are a native, on-chain oracle, enhancing the native DeFi func
By standardizing price feeds in this manner, all XRPL apps can access a dependable, shared data source.
## See Also
- **References:**
- [get_aggregate_price method][]
- [Oracle entry][]
- [OracleDelete transaction][]
- [OracleSet transaction][]
{% raw-partial file="/docs/_snippets/common-links.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

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" /%}

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
{

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

View File

@@ -306,24 +306,16 @@
"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
}
]
}
@@ -673,7 +665,7 @@
"id": "example_get_oracle",
"command": "ledger_entry",
"oracle" : {
"account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
"account": "rNZ9m6AP9K7z3EVg6GhPMx36V4QmZKeWds",
"oracle_document_id": 34
},
"ledger_index": "validated"