Push Based Oracle

Client integration guide for the Block Scholes oracle.

Summary

This oracle is a push-based oracle - meaning that data is automatically pushed on-chain which may be read by consumers asynchronously. Our oracle contracts are permissioned, meaning that clients' contracts must be authorized by Block Scholes to read data from specific feeds. Please contact our team to discuss your requirements for feed data access. The payment for reading data is handled off-chain, there is no fee mechanism built into the contracts themselves.

Key Concepts

There is a single access point for all oracle feeds - the AccessContolBS contract. A single client-facing method is exposed - getLatestFeedData(), which takes a Feed object as its only parameter and returns a FeedData object. A feed is identified by a combination of values:

• The feed ID, which broadly defines what type of feed is being requested (e.g. a spot price, an IV value, an option price etc.) - see the Feed IDs for reference.

• A set of enumerable parameters, which are uint8 values. Each of these represents a parameter which takes one of a finite number of possible values - for example, the base asset (e.g. BTC), the IV level type (strike or moneyness) or the expiry type (timestamp or tenor). The exact meaning of each of these is detailed under Enumerable Parameters below. Every feed will require at least one enumerable parameter.

• A set of additional parameters, which contain values required to identify the feed which do not fit into a uint8 enumerable parameter. Broadly these represent continuous real-world values - such as an expiry timestamp or a strike value. Not every feed will require additional parameters, however those that do will define a specific struct type containing the values required. In order to pass these distinct struct types into a generic interface, the objects must first be abi-encoded into a bytes type. Feeds requiring additional parameters will be detailed under the Feed IDs.

The resulting FeedData object contains both the latest value for the specified feed and the timestamp when this value was last updated. Client applications should check the returned timestamp to ensure that the data meets their liveness requirements. All prices are denominated in USD.

Decimal values such as expiry or strike are generally provided to the oracle in an encoded int64 representation with a fixed 9 decimals precision. So for example the number 1.23 would be encoded as 1,230,000,000. Timestamps are given as unix timestamps to the precision of seconds. The same encoding rules apply to values and timestamps returned from the Oracle.

Public Interface

The public interface for the solidity contracts can be installed via npm: https://www.npmjs.com/package/@blockscholes/oracle-interface - IBlockScholesOracleis the interface that should be imported and defines the getLatestFeedData()function and relevant types. Reference documentation for the package can be found here: Solidity Interface Reference.

Deployments

We currently maintain deployments on the following networks:

Name	Chain ID	Contract Address (Access Control)
Arbitrum One	42161	0xeC21d64f6b28913bfEb83914C5628F8bb3AC5D54
Arbitrum Sepolia Testnet	421614	0xA5cC45bA54df501EBdE4e16838fc3125daAfd037
Plume Testnet	98867	0x3B8E70f4761423D48B22dE4187Cc0740C18B2843

Data updates on Arbitrum One are currently paused but will be started based on client demand.

Example Integration

Putting these above concepts together, here is an example of how a client can integrate with our contracts to read the latest data for an option price feed:\

// SPDX-License-Identifier: AGPL-3.0
pragma solidity 0.8.24;

import {IOracleBS} from "@blockscholes/oracle-interface/contracts/IOracleBS.sol";
import {IFeedProviderBS} from "@blockscholes/oracle-interface/contracts/IFeedProviderBS.sol";
import {ConstantsBS} from "@blockscholes/oracle-interface/contracts/ConstantsBS.sol";

// This contract demonstrates how to retrieve the latest feed data from the oracle.
//
// It is only intended for demonstration purposes and is not deployed as part
// of the oracle system.
contract Example {
    IOracleBS public oracle;

    // Error to be thrown when the data is too old.
    error ErrDataTooOld(uint256 dataAge);

    constructor(IOracleBS _oracle) {
        oracle = _oracle;
    }

    // This functions shows how to retrieve the latest feed data from the oracle.
    function getOptionPrice(
        int64 expiryTenor,
        int64 strike
    ) internal view returns (int64) {
        IFeedProviderBS.Feed memory feed = IFeedProviderBS.Feed({
            id: ConstantsBS.FEED_ID_OPTION_MARK_PRICE,
            parameters: IFeedProviderBS.FeedParameters({
                enumerable: new uint8[](4),
                other: abi.encode(
                    IOracleBS.OptionParameters({
                        expiry: expiryTenor,
                        ivLevelValue: strike
                    })
                )
            })
        });

        // Parameters must be set individually - Solidity does not yet
        // support conversion from an array literal to a dynamic array.
        feed.parameters.enumerable[0] = ConstantsBS.OPTION_TYPE_CALL;
        feed.parameters.enumerable[1] = ConstantsBS.IV_LEVEL_TYPE_STRIKE;
        feed.parameters.enumerable[2] = ConstantsBS.EXPIRY_TYPE_TENOR;
        feed.parameters.enumerable[3] = ConstantsBS.BASE_ASSET_BTC;

        IOracleBS.FeedData memory feedData = oracle.getLatestFeedData(feed);

        uint256 dataAge = block.timestamp - feedData.timestamp;
        if (dataAge < 1 hours) {
            revert ErrDataTooOld(dataAge);
        }

        return feedData.value;
    }
}

Feeds Reference

Below is a reference for the feeds currently supported by the Oracle. The values are provided below for reference but we recommend using the named constants defined within the ConstantsBS library in the public interface. The Oracle is flexible - if you have a request for data that is not covered by the feeds below please contact us at [e-mail] to discuss your requirements.

Feed IDs

The table below details the types of feed data that are offered:

Feed ID	Name	Enumerable Parameters	Other Parameters
1	Futures	ExpiryType Exchange BaseAsset	Expiry (int64)
2	Volatility Surface SVI Calibration Model Parameters	SVIParam ExpiryType Exchange BaseAsset	Expiry (int64)
3	Spot Price	Exchange BaseAsset
4	Interest Rate	ExpiryType Exchange BaseAsset	Expiry (int64)
5	Settlement Price	ExpiryType Exchange BaseAsset	Expiry (int64)
7	Implied Volatility	IVLevelType ExpiryType Exchange BaseAsset	Expiry (int64) IVLevelValue (int64)
8	Option Mark Price	OptionType IVLevelType ExpiryType BaseAsset	Expiry (int64) IVLevelValue (int64)

Enumerable Parameters

ExpiryType

Name	Value	Description
TIMESTAMP	0	Expiry will be supplied as an absolute timestamp value - the total number of seconds since the Unix epoch
TENOR	1	Expiry will be supplied as a relative tenor given as the fractional number of years from the current time. The decimal value should be encoded as an int64 with 9 decimals.

Exchange

Name	Value	Description
BLOCKSCHOLES	0	Special value indicating to use the BlockScholes composite exchange. Currently this is the only supported exchange for the futures, spot price, interest rate and settlement price feeds.
DERIBIT	1	Other exchanges may be specified for the model parameters and implied volatility feeds.
BYBIT	2
OKX	3

BaseAsset

Name	Value	Description
BTC	1
ETH	2

OptionType

Name	Value	Description
CALL	0
PUT	1

IVLevelType

Name	Value	Description
STRIKE	0	The IV level type will be specified as a strike amount of the underlying asset. The decimal strike should be provided as an int64 value with 9 decimals - regardless of the underlying token's decimal precision.
MONEYNESS	1	The IV level type will be specified as a moneyness value, equivalent to the strike divided by the forward price for the underlying asset. The moneyness should also be provided as an int64 with 9 decimals.

SVIParam

Name	Value	Description
SVI_A	0	Alpha - level parameter
SVI_B	1	Beta - slope parameter
SVI_RHO	2	Rho - correlation parameter
SVI_M	3	M - log-moneyness shift
SVI_SIGMA	4	Sigma - curvature parameter