// SPDX-License-Identifier: BUSL-1.1
pragma solidity 0.8.17;

import {IBaseOracleAdapter} from "./interfaces/IBaseOracleAdapter.sol";
import {IBaseController} from "./interfaces/IBaseController.sol";
import {IOval} from "./interfaces/IOval.sol";

/**
 * @title DiamondRootOval contract to provide base functions that the three components of Oval contract system
 * need. They are exposed here to simplify the inheritance structure of Oval contract system and to enable easier
 * composability and extensibility at the integration layer, enabling arbitrary combinations of sources and destinations.
 */
abstract contract DiamondRootOval is IBaseController, IOval, IBaseOracleAdapter {
    /**
     * @notice Returns the latest data from the source.
     * @return answer The latest answer in 18 decimals.
     * @return updatedAt The timestamp of the answer.
     */
    function getLatestSourceData() public view virtual returns (int256, uint256);

    /**
     * @notice Returns the requested round data from the source.
     * @dev If the source does not support rounds this would return uninitialized data.
     * @param roundId The roundId to retrieve the round data for.
     * @return answer Round answer in 18 decimals.
     * @return updatedAt The timestamp of the answer.
     */
    function getSourceDataAtRound(uint256 roundId) public view virtual returns (int256, uint256);

    /**
     * @notice Tries getting latest data as of requested timestamp. If this is not possible, returns the earliest data
     * available past the requested timestamp within provided traversal limitations.
     * @param timestamp The timestamp to try getting latest data at.
     * @param maxTraversal The maximum number of rounds to traverse when looking for historical data.
     * @return answer The answer as of requested timestamp, or earliest available data if not available, in 18 decimals.
     * @return updatedAt The timestamp of the answer.
     * @return roundId The roundId of the answer.
     */
    function tryLatestDataAt(uint256 timestamp, uint256 maxTraversal)
        public
        view
        virtual
        returns (int256, uint256, uint256);

    /**
     * @notice Returns the latest data from the source. Depending on when Oval was last unlocked this might
     * return an slightly stale value to protect the OEV from being stolen by a front runner.
     * @return answer The latest answer in 18 decimals.
     * @return updatedAt The timestamp of the answer.
     * @return roundId The roundId of the answer.
     */
    function internalLatestData() public view virtual returns (int256, uint256, uint256);

    /**
     * @notice Returns the requested round data from the source. Depending on when Oval was last unlocked this might
     * also return uninitialized value to protect the OEV from being stolen by a front runner.
     * @dev If the source does not support rounds this would always return uninitialized data.
     * @param roundId The roundId to retrieve the round data for.
     * @return answer Round answer in 18 decimals.
     * @return updatedAt The timestamp of the answer.
     */
    function internalDataAtRound(uint256 roundId) public view virtual returns (int256, uint256);

    /**
     * @notice Snapshot the current source data. Is a no-op if the source does not require snapshotting.
     */
    function snapshotData() public virtual;

    /**
     * @notice Permissioning function to control who can unlock Oval.
     */
    function canUnlock(address caller, uint256 cachedLatestTimestamp) public view virtual returns (bool);

    /**
     * @notice Time window that bounds how long the permissioned actor has to call the unlockLatestValue function after
     * a new source update is posted. If the permissioned actor does not call unlockLatestValue within this window of a
     * new source price, the latest value will be made available to everyone without going through an MEV-Share auction.
     */
    function lockWindow() public view virtual returns (uint256);

    /**
     * @notice Max number of historical source updates to traverse when looking for a historic value in the past.
     */
    function maxTraversal() public view virtual returns (uint256);

    /**
     * @notice Max age of a historical price that can be used instead of the current price.
     */
    function maxAge() public view virtual returns (uint256);
}