// SPDX-License-Identifier: MIT

pragma solidity >=0.8.17 <0.9.0;

import {IWitRandomnessAdmin} from "./IWitRandomnessAdmin.sol";
import {IWitRandomnessConsumer} from "./IWitRandomnessConsumer.sol";
import {IWitRandomnessEvents} from "./IWitRandomnessEvents.sol";
import {IWitRandomnessTypes, Witnet} from "./IWitRandomnessTypes.sol";

/// @title The Wit/Randomness V3 appliance interface.
/// @author Witnet Foundation.
interface IWitRandomness
    is 
        IWitRandomnessAdmin,
        IWitRandomnessEvents, 
        IWitRandomnessTypes        
{
    /// Address of the underlying logic contract.
    function base() external view returns (address);

    /// Creates a light-proxy clone to the `base()` logic address, to be owned by the specified `curator`address.
    /// Curators of cloned instances can optionally settle one single `IWitRandomnessConsumer` consuming contract.
    /// The consuming contract, if settled, will be immediately reported every time a new `randomize()` request
    /// gets solved and bridged back from Witnet. Either way, randomness resolutions will be reamin stored in the 
    /// `WitRandomness` storage, as for future reference. 
    /// @param curator Address that will have authoritative access to `IWitRandomnessAdmin` methods.
    function clone(address curator) external returns (IWitRandomness);

    /// Returns the consumer address where all valid randomize results will be reported to.
    /// @dev If zero, generated randomness will not be reported to any other external address. 
    /// @dev The consumer contract must implement the `IWitRandomnessConsumer` interface, 
    /// @dev and accept this instance as source of entropy.
    /// @dev It can only be settled by a curator on cloned instances.
    function consumer() external view returns (IWitRandomnessConsumer);

    /// Returns amount of wei required to be paid as a fee when requesting randomization with a 
    /// transaction gas price as the one given.
    function estimateRandomizeFee(uint256 evmGasPrice) external view returns (uint256);

    /// Retrieves the result of keccak256-hashing the given block number with the randomness value 
    /// generated by the Witnet blockchain in response to the first non-failing randomize request solved 
    /// after such block number.
    ///
    /// @dev Reverts if:
    ///    i.   no `randomize()` was queried on neither the given block, nor afterwards.
    ///    ii.  the first non-failing `randomize()` request found on or after the given block is not solved yet.
    ///    iii. all `randomize()` requests that took place on or after the given block were solved with errors.
    ///
    /// @param blockNumber Block number from which the search will start.
    function fetchRandomnessAfter(uint256 blockNumber) external view returns (bytes32);

    /// Retrieves the actual random value, unique hash and timestamp of the witnessing commit/reveal act 
    /// that took place in the Witnet blockchain in response to the first non-failing randomize query
    /// solved after the given block number.
    ///
    /// @dev Reverts if:
    ///    i.   no `randomize()` was queried on neither the given block, nor afterwards.
    ///    ii.  the first non-failing `randomize()` request found on or after the given block is not solved yet.
    ///    iii. all `randomize()` requests that took place on or after the given block were solved with errors.
    ///
    /// @param blockNumber Block number from which the search will start.
    /// @return witnetQueryUUID Universal identifier of the query posted from this contract that ultimately solved randomness.
    /// @return witnetTimestamp Timestamp at which the randomness value was generated by the Witnet blockchain.
    /// @return witnetDrTxHash Hash of the witnessing commit/reveal act that took place on the Witnet blockchain.
    //  @return evmFinalityBlock EVM block number at which the generated randomness can be considered to be final.
    function fetchRandomnessAfterProof(uint256 blockNumber) external view returns (
            bytes32 witnetQueryUUID,
            Witnet.Timestamp witnetTimestamp,
            Witnet.TransactionHash witnetDrTxHash,
            uint256 evmFinalityBlock
        );
    
    /// Returns last block number on which a randomize was queried.
    function getLastRandomizeBlock() external view returns (uint256);

    /// Retrieves metadata related to the randomize request that got queried to the `WitOracle` contract 
    /// on the specified block number, if any.
    ///
    /// @dev Returns zero values if no randomize request was actually queried on the specified block number.
    ///
    /// @param blockNumber Block number from which the search will start.
    /// @return witOracleQueryId Identifier of the underlying Wit/Oracle query created on the specified block (0 if none).
    /// @return prevRandomizeBlock Block number in which a randomize request got queried just before the specified block.
    /// @return nextRandomizeBlock Block number in which a randomize request got queried just after the specified block.
    function getRandomizeData(uint256 blockNumber) external view returns (
            Witnet.QueryId witOracleQueryId,
            uint256 prevRandomizeBlock,
            uint256 nextRandomizeBlock
        );
    
    /// Returns the number of the next block in which a randomize request was posted after the given one. 
    /// @param blockNumber Block number from which the search will start.
    /// @return Number of the first block found after the given one, or `0` otherwise.
    function getRandomizeNextBlock(uint256 blockNumber) external view returns (uint256); 

    /// Returns the number of the previous block in which a randomize request was posted before the given one.
    /// @param blockNumber Block number from which the search will start.
    /// @return First block found before the given one, or `0` otherwise.
    function getRandomizePrevBlock(uint256 blockNumber) external view returns (uint256);

    /// Returns the identifier of the Wit/Oracle query that has either solved randomness
    /// for the specified block number, is currently attending randomness for the specified block number,
    /// of the one that attempted to solve it. 
    /// @dev Returns zero if no randomize was request on or after the specified block number.
    function getRandomizeQueryId(uint256 blockNumber) external view returns (Witnet.QueryId);

    /// Explains why the last attempt of generating randomness for the specified block number failed.
    function getRandomizeQueryErrorDescription(uint256 blockNumber) external view returns (string memory);

    /// Returns security and liveness parameters required to the Witnet blockchain 
    /// when solving randomness requests, if no others are specified.
    /// @return callbackGasLimit Max. expendable gas upon randomness delivery.
    /// @return extraFeePercentage Overhead percentage applied when estimating the randomize request fee. 
    /// @return witCommitteeSize Number of Witnet witnessing nodes required to generate unbiased randomness.
    /// @return witInclusionFees Minimum amount of fees in $nanoWIT to be paid on the Witnet blockchain.
    function getRandomizeQueryParams()
        external view returns (
            uint24 callbackGasLimit,
            uint16 extraFeePercentage,
            uint16 witCommitteeSize,
            uint64 witInclusionFees
        );

    /// Returns the immutable bytecode of the Radon Request that's being used 
    /// for solving randomness requests on the Witnet blockchain.
    function getRandomizeRadonBytecode() external view returns (bytes memory);

    /// Returns the unique identifier of the Radon Request that's being used 
    /// for solving request randomness requests on the Witnet blockchain.
    function getRandomizeRadonHash() external view returns (Witnet.RadonHash);

    /// @notice Returns status of the first non-errored randomize request queried on or after the given block number.
    ///  - 0 -> Void: no randomize request was actually queried on or after the given block number.
    ///  - 1 -> Awaiting: a randomize request was found but it's not yet solved by the Wit/Oracle.
    ///  - 2 -> Ready: a successfull randomize value was reported and is ready to be read.
    ///  - 3 -> Error: all attempted randomize requests at or after the given block were solved with errors.
    ///  - 4 -> Finalizing: a randomize result was relayed already but cannot yet be considered to be final.
    function getRandomizeStatus(uint256 blockNumber) external view returns (RandomizeStatus);    

    /// Return the number of EVM blocks after a randomize requests that have to elapse before
    /// considering such request to be delayed. Results to delayed requests can potentially be
    /// provided by later requests, if solved earlier. A value of zero means that randomize 
    /// requests will never expire. 
    function getRandomizeWaitingBlocks() external view returns (uint16);

    /// Returns `true` only if a successfull resolution from the Witnet blockchain is found for the 
    /// first non-failing randomize request posted on or after the given block number.
    function isRandomized(uint256 blockNumber) external view returns (bool);

    /// @notice Requests the Witnet blockchain to generate an unbiased 256-bit random seed.
    /// @dev Only one randomize request per block will get ultimately relayed to the Witnet blockchain.
    /// @return EVM funds actually paid as randomize fee.
    function randomize() external payable returns (uint256);

    /// Verifies that the specified randomness seed was actually generated on the Witnet blockchain
    /// and used for producing the randomness value returned by `fetchRandomnessAfter(blockNumber)`.
    function verifyRandomnessAfter(uint256 blockNumber, bytes32 witnetRandomness) external view returns (bool);

    /// The Wit/Oracle core address accepted as source of entropy.
    function witOracle() external view returns (address);
}