Push and Pull Flows and Contracts

In decentralized oracle networks, the way data is retrieved and published on-chain can follow two primary mechanisms: push and pull. Each mechanism serves different use cases and requires specific contract implementations to facilitate seamless interaction with on-chain systems.

Pull Execution Flow

In a pull mechanism, data is fetched by the oracle from an external source only when explicitly requested by a smart contract. This method is useful for cases where data is only needed at specific times during contract execution, allowing for more efficient use of resources by avoiding constant data updates.

The pull mechanism involves the following steps, which are illustrated in the diagram below:

How the Pull Mechanism Works

• Smart Contract Requests Data: The smart contract initiates a data request by calling the requestData function on the oracle. It simply provides the callbackAddress (its own address) and the callbackFunctionId (the function in the smart contract that will handle the response).

• Oracle Generates jobId: The oracle generates a unique jobId for the request and returns it to the smart contract. The smart contract can store this jobId to track the request if needed.

• Oracle Fetches Data: The oracle proceeds to fetch the requested data from the external data source.

• Data Source Responds: The external data source returns the fetched data to the oracle.

• Oracle Calls fulfillData: The oracle calls the fulfillData function on the smart contract using the callbackAddress and callbackFunctionId provided earlier. It passes both the jobId (for identification) and the fetched data to the smart contract.

• Smart Contract Processes Data: The smart contract receives the data through the fulfillData function and processes it according to its logic.

Contracts for the Pull Mechanism

In a pull-based oracle system, two key contracts are involved in the data fetching process:

1. Oracle Interface: This defines the function that a smart contract uses to request data from the oracle.

2. Callback Interface: This defines the function that the oracle uses to return the fetched data back to the smart contract.

Oracle Interface

The Oracle Interface exposes the method through which a smart contract can request data from the oracle. This interface defines the requestData function, which allows the smart contract to initiate a data request. A jobId is generated by the oracle and returned to the calling contract.

interface IIntelliXOracle {
    /**
     * @notice Requests data from the oracle and generates a jobId
     * @param callbackAddress The address of the smart contract that will receive the callback
     * @param callbackFunctionId The function selector of the callback in the calling contract
     * @return jobId A unique identifier for the data request
     */
    function requestData(
        address callbackAddress, 
        bytes4 callbackFunctionId
    ) external returns (uint256 jobId);
}

Callback Interface for Smart Contracts

The Callback Interface must be implemented by the smart contract to handle the data returned by the oracle. The fulfillData function in this interface is called by the oracle once the requested data is fetched, using the callbackAddress and callbackFunctionId provided during the data request.

interface IOracleCallback {
    /**
     * @notice Receives the data from the oracle
     * @param jobId The identifier of the data request
     * @param data The fetched data
     */
    function fulfillData(
        uint256 jobId, 
        MyCustomData calldata data
    ) external;
}

Push Execution Flow