// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import {IEntropyV2Compatible} from "./IEntropyV2Compatible.sol";

/// @notice Commit-reveal randomness with a trusted revealing operator. Not a VRF.
interface IRandomnessHub is IEntropyV2Compatible {
    enum Status {
        None,
        Pending,
        Fulfilled,
        Expired
    }

    /// @notice Everything fixed when a request is accepted. Later configuration changes never touch it.
    struct Request {
        address consumer;
        uint32 laneId;
        uint64 index;
        uint64 blockNumber;
        uint32 callbackGas;
        Status status;
        bool callbackFailed;
        uint128 feePaid;
        bytes32 userContribution;
    }

    /// @notice A hash chain committed by `head` (index 0). `anchor` is the latest verified link.
    struct Lane {
        bytes32 head;
        bytes32 anchor;
        uint64 anchorIndex;
        uint64 nextIndex;
        uint64 length;
    }

    /// @notice Price and per-consumer limits. fee = baseFee + feePerGas * callbackGas (native, 18 decimals).
    struct Tariff {
        uint128 baseFee;
        uint128 feePerGas;
        uint32 defaultCallbackGas;
        uint32 maxCallbackGas;
        uint32 maxPending;
    }

    /// @notice Hub-wide limits that apply however many consumer addresses exist.
    struct Limits {
        uint32 maxPendingTotal;
        uint32 maxRequestsPerBlock; // 0 disables the per-block cap
        uint32 callbackGasCeiling;
    }

    event Expired(uint64 indexed sequenceNumber, address indexed caller);
    event AnchorAdvanced(uint32 indexed laneId, uint64 index, uint64 indexed sequenceNumber);
    event LanePublished(uint32 indexed laneId, bytes32 head, uint64 length);
    event ActiveLaneSet(uint32 indexed laneId);
    event RelayerSet(address indexed relayer, bool allowed);
    event DefaultTariffSet(Tariff tariff);
    event ConsumerTariffSet(address indexed consumer, Tariff tariff);
    event ConsumerTariffCleared(address indexed consumer);
    event LimitsSet(Limits limits);
    event FeesWithdrawn(address indexed to, uint256 amount);
    event AllWithdrawn(address indexed to, uint256 amount, uint256 feesWrittenOff);
    event ERC20Rescued(address indexed token, address indexed to, uint256 amount);

    error NotRelayer();
    error UnknownRequest(uint64 sequenceNumber);
    error NotPending(uint64 sequenceNumber, Status status);
    error NotExpired(uint64 sequenceNumber);
    error TooEarly(uint64 requestBlock);
    error NotExpirable(uint64 sequenceNumber, uint256 age);
    error InvalidSeed();
    error TooFarFromAnchor(uint256 steps);
    error AlreadyAnchored(uint64 index, uint64 anchorIndex);
    error BlockhashUnavailable(uint64 blockNumber);
    error NotEnoughGas();
    error InsufficientFee(uint256 required, uint256 paid);
    error CallbackGasTooHigh(uint32 requested, uint32 allowed);
    error UnknownProvider(address provider);
    error ConsumerNotContract(address caller);
    error ConsumerLimitReached(address consumer, uint32 pending);
    error GlobalLimitReached(uint32 pendingTotal);
    error RateLimited(uint64 blockNumber);
    error NoActiveLane();
    error LaneExhausted(uint32 laneId);
    error InvalidLane(uint32 laneId);
    error LaneHeadUsed(bytes32 head);
    error InvalidConfig();
    error InvalidAmount();
    error ZeroAddress();
    error OwnershipRenounceDisabled();
    error NativeTransferFailed();
    error ForbiddenToken(address token);

    // Delivery and recovery (operator only)
    function fulfill(uint64 sequenceNumber, bytes32 seed) external;

    function advanceAnchor(uint64 expiredSequenceNumber, bytes32 seed) external;

    // Public cleanup: marks a request that can no longer be delivered. Never delivers a number.
    function expire(uint64 sequenceNumber) external;

    // Reads
    function requestOf(uint64 sequenceNumber) external view returns (Request memory);

    function randomOf(uint64 sequenceNumber) external view returns (bytes32);

    function laneOf(uint32 laneId) external view returns (Lane memory);

    function checkpointOf(uint32 laneId, uint64 index) external view returns (bytes32);

    function remaining(uint32 laneId) external view returns (uint64);

    function activeLane() external view returns (uint32);

    function laneCount() external view returns (uint32);

    function quote(address consumer, uint32 gasLimit) external view returns (uint128 fee, uint32 callbackGas);

    function tariffOf(address consumer) external view returns (Tariff memory tariff, bool custom);

    function defaultTariff() external view returns (Tariff memory);

    function limits() external view returns (Limits memory);

    function pendingOf(address consumer) external view returns (uint32);

    function pendingTotal() external view returns (uint32);

    function isRelayer(address account) external view returns (bool);

    function accruedFees() external view returns (uint256);

    function totalFeesEarned() external view returns (uint256);

    function nextSequenceNumber() external view returns (uint64);
}