Integration Details

Suggest Edits

There are 2 ways of reading Umbrella on-chain data feeds:

  1. Direct Access: reading the data directly from the Umbrella feeds smart contract. This method has lower gas requirements.
  2. Via Reader: For those projects who need to integrate but cannot change their smart contract, they can read the data from the Umbrella Feeds Reader smart contracts. The Umbrella Feeds Reader connects to the Umbrella feeds smart contract. This method is more costly in terms of gas a it has one additional step compared to the Direct Access.

📘

Prices are stored under a key. key is constant, and it is the hash of the feed name (eg hash("UMB-USD") ).

Smart Contract hierarchy

Getting the address of the latest UmbrellaFeeds smart contract

Address of the lastest UmbrellaFeeds smart contract can be resolved by using the Umbrella Registry smart contract.

📘

Addresses of the Umbrella Registry contracts for the different blockchains can be found in here.

Address can be resolved with the following method:

IRegistry.getAddress(bytes32("UmbrellaFeeds"))

Direct access

It is recommended option as it is the most gas effective.

The UmbrellaFeedssmart contract is where all prices are submitted by the on-chain data feature of the Umbrella Oracle. Use getPriceData(key) method to get price data about a specific key.

Price data structure contains:

struct PriceData {  
    uint8 data; // not in use, reserved for future  
    uint24 heartbeat; // if price is flat, how often it will be updated  
    uint32 timestamp; // last update  
    uint128 price; // 8 decimals  
}

Via reader

There is the option to create dedicated contract reader which emulates interface of other leader oracles. As a first stage, we are implementing a contract with a Chainlink-like interface..

In order to instantiate a new Reader contract for a given data point:

  1. Go to UmbrellaFeedsReaderFactorysmart contract and use the deployed(key) method to check whether there is already a Reader contract for your key.

📘

UmbrellaFeedsReaderFactory smart contract address can be retrieved from the Registry using the UmbrellaFeedsReaderFactory keyword.

  1. if a Reader method for your key hasn't beed instantiated, use the UmbrellaFeedsReaderFactory.deploy(key) method to create a new instance of the UmbrellaFeedsReader contract, dedicated for provided key.
    1. Use deployed(key) method to read address of deployed contract.
    2. In case contract code is not verified automatically, you can use (UmbrellaFeedsReader standard JSON)[./flattened/UmbrellaFeedsReader.stdandard.json] to verify its code.

UmbrellaFeedsReader provides few methods that you can use depending on the case:

  • latestRoundData(): it follows chainlink interface to easier migration process from Chainlink to Umbrella.

🚧

IMPORTANT

Only answer and updatedAtfield are in use.

  • getPriceData(): it returns PriceData.

Fallback mechanism

A fallback mechanism has been included in the UmbrellaFeedsReader smart contract to ensure you always read data from the latest UmbrellaFeeds contract.

Like a Proxy

While proxy contracts are forced to read implementation address all the time, the fallback mechanism searches for a new address ONLY when it is needed, and only then, additional cost is added to the transaction.

Redeployments of contracts are very rare, so it is more effective to simply update contract address when needed than paying additional fee every time we read the price.

If you chose to read prices directly from the UmbrellaFeeds contract, you will need to implement a mechanism similar to the fallback on your side. You can check the implementation of the UmbrellaFeedsReaderFactory smart contract as an example.

🚧

When using testnets

Take into consideration testnets are connected to Umbrella Nework Development or Sandbox environments, which are not as stable as the Production environment.

It is a good practice to keep the Umbrella Network team aware of the tests you will perform on testnets so they can let you know in case of any planned outage.

You can also monitor below wallet's balances and send some native test tokens in case they are depleted to avoid missing updates:

Dev: 0xF564E65BB80fCaef45419323656308F5272cAD0e
SBX: 0x0298037D898e8Fd5cD71F035B5832B8af5C058C0

Updated 8 months ago