Integrating Supra Oracles

A process and key information for integrating Supra oracles into your MELD dApp

Integrating Supra oracles is designed to be quick and easy and there are two types of oracles you can select from.

The first is a "Pull" oracle. This is where a request is sent from the smart contract to the oracle requesting live data on pricing.

The second is a "Push" oracle. This oracle feeds pricing information at regular intervals and allows you to query the most recent or historical data.

Key information: MELD_USDT data pair: Pair ID 153 MELD Kanazawa Subnet Contract address: 0x8D53f34C06A873dA78B39f87cbBeCCdc8c31ACc0

For a full list of available pricing information, please visit the Pull Oracle available networks and Push Oracle available network pages at Supra.

Retrieving the S-Value

The following code sample uses Solidity to retrieve an "S-Value", ie a Supra oracle price value, from their push oracle.

Step 1: Create The S-Value Interface

In the first step, you need to build data structures to receive the data feeds and functions required to fetch data into configured data structures. You may add the following code to the Solidity smart contract that you wish to retrieve the S-Value.

pragma solidity 0.8.19;

// depending on the requirement, you may build one or more data structures given below. 

interface ISupraSValueFeed {

// Data structure to hold the pair data
struct priceFeed {
    uint256 round;
    uint256 decimals;
    uint256 time;
    uint256 price;
    }


// Data structure to hold the derived/converted data pairs.  This depends on your requirements.

struct derivedData{
    int256 roundDifference;
    uint256 derivedPrice;
    uint256 decimals;
}


// Below functions enable you to retrieve different flavours of S-Value
// Term "pair ID" and "Pair index" both refer to the same item.

// Function to retrieve the data for a single data pair
function getSvalue(uint256 _pairIndex)
    external 
    view
    returns (priceFeed memory);



//Function to fetch the data for multiple data pairs
function getSvalues(uint256[] memory _pairIndexes)
    external
    view
    returns (priceFeed[] memory);


// Function to convert and derive new data pairs using two pair IDs and a mathematical operator multiplication(*) or division(/).
//** Currently only available in testnets
function getDerivedSvalue(uint256 pair_id_1,uint256 pair_id_2,
    uint256 operation)
    external
    view
    returns (derivedData memory);



// Function to check the latest Timestamp on which a data pair is updated. This will help you check the staleness of a data pair before performing an action. 
function getTimestamp(uint256 _tradingPair) 
external
view
returns (uint256);

}

The above code creates the interface that you will later apply in order to fetch a price from SupraOracles.

Step 2: Configure The S-Value Feed Address

Next, to retrieve the S-Value, configure the S-Value feed using the Supra Smart Contract address as demonstrated below. The Supra contract MELD Kanazawa testnet is 0x8D53f34C06A873dA78B39f87cbBeCCdc8c31ACc0

Copy

contract ISupraSValueFeedExample {
    ISupraSValueFeed internal sValueFeed;
    constructor() {
        sValueFeed = ISupraSValueFeed(0x8D53f34C06A873dA78B39f87cbBeCCdc8c31ACc0);
    }
} 
// MELD Kanazawa testnet is used above, but can be replaced with the network of your choosing.

Step 3: Get The S-Value Crypto Price

Now you can access the S-Values for any trading pairs Supra publishes. The sample below retrieves S-value for single as well as multiple data pairs for demonstration purposes. You may use it as appropriate. The MELD_USDT pair is ID 153.

Copy

// requesting s-value for a single pair
function getPrice(uint256 _priceIndex)
    external
    view 
    returns (ISupraSValueFeed.priceFeed memory) {
    return sValueFeed.getSvalue(_priceIndex);
}

// requesting s-values for multiple pairs
function getPriceForMultiplePair(uint256[] memory _pairIndexes) 
    external 
    view 
    returns (ISupraSValueFeed.priceFeed[] memory) {
    return sValueFeed.getSvalues(_pairIndexes);
}

// Function to convert and derive a new data pair using two existing pair ids, and a mathematical operator division(1), or multiplication(0).
function getDerivedValueOfPair (uint256 pair_id_1,uint256 pair_id_2,uint256 operation)
    external
    view
    returns(ISupraSValueFeed.derivedData memory){
    return sValueFeed.getDerivedSvalue(pair_id_1,pair_id_2,operation);
}

Recommended Best Practices: Create a function with access control that updates the sValueFeed using the function updateSupraSvalueFeed().

This will allow you to update the address of the Supra storage contract after deployment to future-proof your contract. Access control is mandatory to prevent the undesired modification of the address.

function updateSupraSvalueFeed(ISupraSValueFeed _newSValueFeed) 
external 
onlyOwner {
sValueFeed = _newSValueFeed;
}

Example Implementation:

Here's an example of what your implementation should look like:

pragma solidity 0.8.19;
import "./ISupraSValueFeed.sol";
import "@openzeppelin/contracts/access/Ownable.sol";

contract ConsumerContract is Ownable {

ISupraSValueFeed internal sValueFeed;

constructor(ISupraSValueFeed _sValueFeed) {
sValueFeed=_sValueFeed; 
}


function updateSupraSvalueFeed(ISupraSValueFeed _newSValueFeed) 
external 
onlyOwner {
sValueFeed = _newSValueFeed;
}


function getSupraSvalueFeed() external view returns(ISupraSValueFeed){
return sValueFeed;
}


function getPrice(uint256 _priceIndex) 
external
view 
returns (ISupraSValueFeed.priceFeed memory) {
return sValueFeed.getSvalue(_priceIndex);
}


function getPriceForMultiplePair(uint256[] memory _pairIndexes) 
external
view
returns (ISupraSValueFeed.priceFeed[] memory) {
return sValueFeed.getSvalues(_pairIndexes);
}

function getDerivedValueOfPair(uint256 pair_id_1,uint256 pair_id_2,uint256 operation)
external
view 
returns(ISupraSValueFeed.derivedData memory){
return sValueFeed.getDerivedSvalue(pair_id_1,pair_id_2,operation);
}
}

For additional information on integrating Supra Oracles, visit the Supra Oracle Data Feeds documentation.