// SPDX-License-Identifier: MIT

pragma solidity >=0.8.0 <0.9.0;

import "../libs/Witnet.sol";

interface IWitOracleQueriable {
    
    /// @notice Removes all query data from storage. Pays back reward on expired queries.
    /// @dev Fails if the query is not in a final status, or not called from the actual requester.
    /// @param queryId The unique query identifier.
    function deleteQuery(uint256 queryId) external returns (Witnet.QueryEvmReward);

    /// @notice Estimate the minimum reward required for posting a data request.
    /// @param evmGasPrice Expected gas price to pay upon posting the data request.
    function estimateBaseFee(uint256 evmGasPrice) external view returns (uint256);
    
    /// @notice Estimate the minimum reward required for posting a data request with a callback.
    /// @param evmGasPrice Expected gas price to pay upon posting the data request.
    /// @param callbackGas Maximum gas to be spent when reporting the data request result.
    function estimateBaseFeeWithCallback(uint256 evmGasPrice, uint24 callbackGas) external view returns (uint256);

    /// @notice Estimate the extra reward (i.e. over the base fee) to be paid when posting a new
    /// @notice data query in order to avoid getting provable "too low incentives" results from
    /// @notice the Wit/Oracle blockchain. 
    /// @dev The extra fee gets calculated in proportion to:
    /// @param evmGasPrice Tentative EVM gas price at the moment the query result is ready.
    /// @param evmWitPrice  Tentative nanoWit price in Wei at the moment the query is solved on the Wit/Oracle blockchain.
    /// @param querySLA The query SLA data security parameters as required for the Wit/Oracle blockchain. 
    function estimateExtraFee(uint256 evmGasPrice, uint256 evmWitPrice, Witnet.QuerySLA calldata querySLA) external view returns (uint256);

    /// @notice Returns next query id to be generated by the Witnet Request Board.
    function getNextQueryId() external view returns (Witnet.QueryId);

    /// @notice Gets the whole Query data contents, if any, no matter its current status.
    function getQuery(Witnet.QueryId queryId) external view returns (Witnet.Query memory);

    /// @notice Gets the current EVM reward the reporter can claim, if not done yet.
    function getQueryEvmReward(uint256) external view returns (Witnet.QueryEvmReward);

    /// @notice Retrieves the RAD hash and SLA parameters of the given query.
    function getQueryRequest(Witnet.QueryId) external view returns (Witnet.QueryRequest memory);

    /// @notice Retrieves the whole `Witnet.QueryResponse` record referred to a previously posted Witnet Data Request.
    function getQueryResponse(Witnet.QueryId) external view returns (Witnet.QueryResponse memory);

    function getQueryResult(uint256) external view returns (Witnet.DataResult memory);
    function getQueryResultStatus(uint256) external view returns (Witnet.ResultStatus);
    function getQueryResultStatusDescription(uint256) external view returns (string memory);
    
    /// @notice Gets query's result back tracing trails
    function getQueryResultTrails(uint256) 
        external view returns (
            bytes32 queryUUID,
            Witnet.TransactionHash resultDrTxHash,
            Witnet.Timestamp resultTimestamp,
            uint256 resultFinalityBlock
        );

    /// @notice Gets current status of given query.
    function getQueryStatus(uint256) external view returns (Witnet.QueryStatus);
    function getQueryStatusString(uint256) external view returns (string memory);
    
    /// @notice Get current status of all given query ids.
    function getQueryStatusBatch(uint256[] calldata) external view returns (Witnet.QueryStatus[] memory);

    /// @notice Request real world data from the Wit/Oracle sidechain. 
    /// @notice The paid fee is escrowed as a reward for the reporter that eventually relays back 
    /// @notice a valid query result from the Wit/Oracle sidechain.
    /// @notice Query results are CBOR-encoded, and can contain either some     data, or an error.
    /// @dev Reasons to revert:
    /// @dev - the data request's RAD hash was not previously verified into the WitOracleRadonRegistry contract;
    /// @dev - invalid query SLA parameters were provided;
    /// @dev - insufficient value is paid as reward.
    /// @param radonHash The unique hash of the Radon Request to be solved by Wit/Oracle sidechain. 
    function queryData(
            Witnet.RadonHash radonHash,
            Witnet.QuerySLA calldata
        )
        external payable returns (uint256);

    /// @notice Request real world data from the Wit/Oracle sidechain. 
    /// @notice The paid fee is escrowed as a reward for the reporter that eventually relays back 
    /// @notice a valid query result from the Wit/Oracle sidechain.
    /// @notice The Witnet-provable result will be reported directly to the requesting contract. 
    /// @notice Query results are CBOR-encoded, and can contain either some data, or an error.
    /// @dev Reasons to revert:
    /// @dev - the data request's RAD hash was not previously verified into the Radon Registry;
    /// @dev - invalid query SLA parameters were provided;
    /// @dev - insufficient value is paid as reward.
    /// @dev - passed `consumer` is not a contract implementing the IWitOracleQueriableConsumer interface;
    /// @param radonHash The unique hash of the Radon Request to be solved by Wit/Oracle sidechain. 
    function queryDataWithCallback(
            Witnet.RadonHash radonHash, 
            Witnet.QuerySLA calldata, 
            Witnet.QueryCallback calldata
        )
        external payable returns (uint256);

    /// @notice Increments the reward of a previously posted request by adding the transaction value to it.
    function upgradeQueryEvmReward(uint256) external payable;
}