Price Oracles

Price Oracles on the XRP Ledger bring real-world pricing data on-chain—bridging external market data with decentralized applications (dApps). This feature enables dApps, decentralized exchanges, and DeFi protocols to function with up-to-date, verifiable price feeds.

---

Price Oracles Explained

What Are Price Oracles?

Price Oracles are on-chain ledger objects that store external price information (e.g., XRP/USD). They are created and updated via the OracleSet transaction, and can be removed using the OracleDelete transaction. dApps can access this data to trigger smart contract logic, perform asset conversions, or maintain stablecoins.

Why Use Price Oracles?

• Reliable Data Feeds: Provide verified, real-time pricing data from trusted providers.

• Decentralized Trust: Price data is recorded on the immutable XRPL ledger.

• Data Aggregation: Multiple oracle instances can be aggregated to calculate mean, median, or trimmed mean values, reducing the impact of outliers.

How Price Oracles Work

The PriceOracle object includes fields such as Owner, Provider, PriceDataSeries, and LastUpdateTime. You use an OracleSet transaction to create or update an oracle instance, while the OracleDelete transaction removes it from the ledger. Additionally, the get_aggregate_price API allows for combining data from multiple Price Oracle objects to generate reliable price statistics.

---

Advantages of Price Oracles

1. Real-World Data Integration Seamlessly integrate external pricing data into on-chain applications.

2. Enhanced Transparency and Security Data stored on XRPL is verifiable and tamper-resistant.

3. Robust Data Aggregation Aggregating data from several oracles minimizes anomalies and improves reliability.

4. Dynamic Data Management Easily update or remove price feeds with dedicated transactions.

---

Price Oracles in Action

Prerequisites

Before working with Price Oracles, ensure you have:

• An active Owner account on the XRPL that meets the XRP reserve requirements.

• Sufficient XRP to cover transaction fees.

• Trust in your external data provider (e.g., a reputable API or on-chain oracle service).

Initialize the Client and Wallet

Begin by installing the XRPL library:

npm install xrpl

Then, initialize your XRPL client and wallet:

import { Client, Wallet } from "xrpl";

const client = new Client("wss://xrplcluster.com");
await client.connect();

// Initialize your owner wallet (replace with your actual secret)
const ownerWallet = Wallet.fromSeed("sXXXXXXXXXXXXXXXXXXXXXXXXXXXX");

Example: Creating/Updating a Price Oracle

Submit an OracleSet transaction to create or update a Price Oracle instance:

const oracleSetTx = {
    TransactionType: "OracleSet",
    Account: ownerWallet.classicAddress,
    OracleDocumentID: 34,  // Unique identifier for this Price Oracle instance
    Provider: "70726F7669646572", // Hex-encoded provider identifier (e.g., "provider")
    AssetClass: "63757272656E6379", // Hex-encoded asset class (e.g., "currency")
    LastUpdateTime: Math.floor(Date.now() / 1000), // Current Unix time
    PriceDataSeries: [
        {
            PriceData: {
                BaseAsset: "XRP",
                QuoteAsset: "USD",
                AssetPrice: 740,  // Example: represents 7.40 with a Scale of 2
                Scale: 2
            }
        }
    ]
};

try {
    const response = await client.submitAndWait(oracleSetTx, { autofill: true, wallet: ownerWallet });
    console.log("OracleSet Transaction Result:", response);
} catch (error) {
    console.error("Failed to submit OracleSet transaction:", error);
}

Retrieving a Price Oracle

Use the ledger_entry API to fetch the on-chain Price Oracle object:

const ledgerEntryRequest = {
    method: "ledger_entry",
    oracle: {
        account: ownerWallet.classicAddress,
        oracle_document_id: 34
    },
    ledger_index: "validated"
};

const ledgerEntryResponse = await client.request(ledgerEntryRequest);
console.log("Retrieved Price Oracle:", ledgerEntryResponse.result.node);

Convert AssetPrice to Integer

To get a decimal representation of the AssetPrice convert it from HEX to a Number:

const AssetPriceHex = '0x' + '2e4'
const price = Number(AssetPriceHex)

Aggregating Price Data

Aggregate data from multiple oracles with the get_aggregate_price API:

const aggregatePriceRequest = {
    method: "get_aggregate_price",
    ledger_index: "current",
    base_asset: "XRP",
    quote_asset: "USD",
    trim: 20, // Trim 20% of outlier data
    oracles: [
        {
            account: ownerWallet.classicAddress,
            oracle_document_id: 34
        }
        // Include additional oracle objects as needed
    ]
};

const aggregatePriceResponse = await client.request(aggregatePriceRequest);
console.log("Aggregated Price Data:", aggregatePriceResponse.result);

Additionally Delete the Oracle Object

To delete the Oracle Object from your Account perform an OracleDelete Transaction.

const oracleDeleteTx = {
  TransactionType: "OracleDelete",
  Account: ownerWallet.classicAddress,
  OracleDocumentID: 34
};

try {
    const response = await client.submitAndWait(oracleDeleteTx, { autofill: true, wallet: ownerWallet });
    console.log("OracleDelete Transaction Result:", response);
} catch (error) {
    console.error("Failed to submit OracleDelete transaction:", error);
}

---

Key Considerations

XRP Reserve Requirements

• Ensure your account meets the reserve requirement, especially when including more than five token pairs in PriceDataSeries.

Data Accuracy and Validity

• Validate that the LastUpdateTime reflects current pricing data.

• Maintain consistency for the Provider and AssetClass fields across updates.

Transaction Signing

• All OracleSet and OracleDelete transactions must be signed by the owner account or its authorized multi-signers.

---

Advantages in Financial Applications

Price Oracles empower the XRPL ecosystem by enabling:

1. Decentralized Finance (DeFi) Utilize real-world price data to support lending, derivatives, and other DeFi products.

2. Stablecoin Management Maintain stablecoin peg values with aggregated price feeds.

3. Efficient Trading and DEX Integration Provide reliable market data for order matching and automated market making.

By integrating Price Oracles, developers can build robust, data-driven applications that benefit from transparent and up-to-date market insights.

---

Remember to disconnect your client after operations:

await client.disconnect();

Happy building with Price Oracles on XRPL!