Contract

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

/// @title ISomniaVRFCoordinator
/// @notice Reactivity-native VRF coordinator for Somnia. Consumers request
///         random words; the coordinator delivers them via a callback after
///         a commit delay.
///
///         Two entropy modes:
///
///         Mode A — fast (`useVerifiableEntropy = false`)
///           Entropy from `blockhash(revealBlock - 1)`. Cheap and low-latency,
///           but the block producer for the reveal block can influence it.
///           Testnet-grade only.
///
///         Mode B — verifiable (`useVerifiableEntropy = true`)
///           Entropy mixes drand (League of Entropy publicly-verifiable
///           beacon) with the blockhash. The coordinator fires a Somnia
///           Agents JSON API Request at reveal time; the resulting seed is
///           `keccak256(drand, blockhash, requestId, consumer, revealBlock)`.
///           Compromising either drand or the reveal-block producer alone
///           does not compromise the result.
interface ISomniaVRFCoordinator {
    struct RandomWordsRequest {
        uint32 callbackGasLimit;
        uint16 commitDelayBlocks;
        uint32 numWords;
        bool useVerifiableEntropy;
    }

    struct Request {
        address consumer;
        uint32 callbackGasLimit;
        uint32 numWords;
        uint64 revealBlock;
        bool useVerifiableEntropy;
        bool fulfilled;
        bytes32 capturedBlockhash;
    }

    event RandomWordsRequested(
        uint256 indexed requestId,
        address indexed consumer,
        uint64 revealBlock,
        uint32 numWords,
        uint32 callbackGasLimit,
        bool useVerifiableEntropy
    );

    event BlockhashCaptured(
        uint256 indexed requestId,
        uint64 revealBlock,
        bytes32 blockhashValue
    );

    event DrandRequested(
        uint256 indexed requestId,
        uint256 indexed agentRequestId
    );

    event RandomWordsFulfilled(
        uint256 indexed requestId,
        address indexed consumer,
        uint64 revealBlock,
        bool callbackSuccess,
        bool usedVerifiableEntropy
    );

    error CommitDelayTooShort(uint16 provided, uint16 minimum);
    error CommitDelayTooLong(uint16 provided, uint16 maximum);
    error CallbackGasTooHigh(uint32 provided, uint32 maximum);
    error NumWordsOutOfRange(uint32 provided, uint32 minimum, uint32 maximum);
    error UnknownRequest(uint256 requestId);
    error UnknownAgentRequest(uint256 agentRequestId);
    error NotPrecompile(address caller);
    error NotAgentPlatform(address caller);
    error DrandAlreadyResolved(uint256 requestId);
    error DrandResponseFailed(uint8 status);
    error FastModeDisabled();

    /// @notice Request `numWords` uniformly random uint256 values, delivered via
    ///         the caller's `fulfillRandomWords(requestId, uint256[] words)` callback
    ///         after `commitDelayBlocks` blocks (Mode A) or after the drand round
    ///         following that block resolves (Mode B).
    function requestRandomWords(RandomWordsRequest calldata req)
        external
        returns (uint256 requestId);

    /// @notice Read a pending or historical request.
    function getRequest(uint256 requestId) external view returns (Request memory);
}

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

/// @title IVRFConsumer
/// @notice Callback interface a VRF consumer must implement.
///         Signature mirrors Chainlink's VRFConsumerBaseV2Plus for portability.
interface IVRFConsumer {
    function rawFulfillRandomWords(uint256 requestId, uint256[] calldata randomWords) external;
}

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

/// @notice Types and interfaces for the Somnia Agents platform.
///         Vendored from somnia-chain/somnia-agents-docs so the coordinator can
///         fire an off-chain agent (here: JSON API Request → drand) alongside
///         the Reactivity BlockTick that carries the blockhash side of the seed.

enum ConsensusType {
    Majority,
    Threshold
}

enum ResponseStatus {
    None,
    Pending,
    Success,
    Failed,
    TimedOut
}

struct Response {
    address validator;
    bytes result;
    ResponseStatus status;
    uint256 receipt;
    uint256 timestamp;
    uint256 executionCost;
}

struct Request {
    uint256 id;
    address requester;
    address callbackAddress;
    bytes4 callbackSelector;
    address[] subcommittee;
    Response[] responses;
    uint256 responseCount;
    uint256 failureCount;
    uint256 threshold;
    uint256 createdAt;
    uint256 deadline;
    ResponseStatus status;
    ConsensusType consensusType;
    uint256 remainingBudget;
    uint256 perAgentBudget;
}

interface IAgentRequester {
    function createRequest(
        uint256 agentId,
        address callbackAddress,
        bytes4 callbackSelector,
        bytes calldata payload
    ) external payable returns (uint256 requestId);

    function getRequestDeposit() external view returns (uint256);
}

/// @notice ABI of the JSON API Request base agent (agentId 13174292974160097713).
interface IJsonApiAgent {
    function fetchString(string calldata url, string calldata selector)
        external
        returns (string memory);
}

// SPDX-License-Identifier: MIT
// Copyright (c) 2026 Somnia Foundation

pragma solidity 0.8.30;

/// @notice Somnia event handler interface
/// @title ISomniaEventHandler
/// @author Somnia Foundation
interface ISomniaEventHandler {

    /**
     * @notice Default function invoked for a matching reactivity subscription filter
     * @param emitter Smart contract that emitted the EVM event log(s)
     * @param eventTopics List of event topics associated with the event (event signature being first param)
     * @param data Event data for non-indexed event arguments. May be empty if event only has indexed params
     */
    function onEvent(
        address emitter,
        bytes32[] calldata eventTopics,
        bytes calldata data
    ) external;

}

// SPDX-License-Identifier: MIT
// Copyright (c) 2026 Somnia Foundation

pragma solidity 0.8.30;

/// @notice Somnia reactivity precompile interface and related data structures
/// @title ISomniaReactivityPrecompile
/// @author Somnia Foundation
interface ISomniaReactivityPrecompile {
    /// @notice Data structure representing a subscription
    struct SubscriptionData {
        // Topic filter, use 0x0 to indicate a wildcard or unused topic
        bytes32[4] eventTopics;
        //  Origin (tx.origin) filter, use address(0) to indicate a wildcard
        address origin;
        // Reserved for future use, use address(0)
        address caller;
        // Contract emitting the event filter, use address(0) to indicate a wildcard
        address emitter;
        // The address of the contract that will handle the event
        address handlerContractAddress;
        // The function selector in the handler contract, defaults to ISomniaEventHandler.onEvent
        bytes4 handlerFunctionSelector;
        // Extra fee per gas paid to validators to prioritize this event handling
        uint64 priorityFeePerGas;
        // Maximum fee per gas the subscriber is willing to pay (base fee + priority fee)
        uint64 maxFeePerGas;
        // Maximum gas that will be provisioned per subscription callback
        uint64 gasLimit;
        // Whether the event handling is guaranteed, i.e. moved to the next block if current is full
        bool isGuaranteed;
        // Whether multiple events can be coalesced into a single handling call per block
        bool isCoalesced;
    }

    /// @notice System tick emitted at the end of each block.
    /// @param blockNumber Current block number.
    event BlockTick(uint64 indexed blockNumber);

    /// @notice System tick emitted at epoch boundaries.
    /// @param epochNumber Current epoch number.
    /// @param blockNumber Current block number.
    event EpochTick(uint64 indexed epochNumber, uint64 indexed blockNumber);

    /// @notice Scheduled system event emitted at the requested timestamp.
    /// @param timestampMillis Timestamp in milliseconds.
    event Schedule(uint256 indexed timestampMillis);

    /// @notice Emitted when a new subscription is created
    /// @param subscriptionId New subscription identifier.
    /// @param owner Owner of the created subscription.
    /// @param subscriptionData Persisted subscription payload.
    event SubscriptionCreated(
        uint256 indexed subscriptionId,
        address indexed owner,
        SubscriptionData subscriptionData
    );

    /// @notice Emitted when a subscription is removed
    /// @param subscriptionId Removed subscription identifier.
    /// @param owner Owner of the removed subscription.
    event SubscriptionRemoved(
        uint256 indexed subscriptionId,
        address indexed owner
    );

    /**
     * @notice Creates a new Solidity subscription
     * @dev Cost: SUBSCRIPTION_MANAGEMENT_GAS_COST (~210k GAS)
     * @dev The caller becomes the owner of the subscription.
     * @dev The subscription starts being active immediately.
     * @param subscriptionData Defines the parameters for the subscription incl the handler contract
     * @return subscriptionId The subscription ID assigned to the new subscription
     */
    function subscribe(
        SubscriptionData calldata subscriptionData
    ) external returns (uint256 subscriptionId);

    /**
     * @notice Cancels a Solidity event subscription
     * @dev It can only be called by the owner
     * @dev Cost: SUBSCRIPTION_MANAGEMENT_GAS_COST (~210K GAS)
     * @param subscriptionId Unique subscription identifier
     */
    function unsubscribe(uint256 subscriptionId) external;

    /**
     * @notice Gets detailed information about a specific subscription
     * @param subscriptionId The unique subscription identifier
     * @return subscriptionData The recorded subscription information
     * @return owner The owner of the subscription that can make changes and pays for invocations
     */
    function getSubscriptionInfo(
        uint256 subscriptionId
    )
        external
        view
        returns (SubscriptionData memory subscriptionData, address owner);
}

// SPDX-License-Identifier: MIT
// Copyright (c) 2026 Somnia Foundation

pragma solidity 0.8.30;

import {ISomniaReactivityPrecompile} from "./ISomniaReactivityPrecompile.sol";
import {ISomniaEventHandler} from "./ISomniaEventHandler.sol";

/// @notice The Somnia Reactivity Precompile is a privileged contract at a fixed address
/// @title SomniaExtensions
/// @author Somnia Foundation
library SomniaExtensions {
    /// @notice Topic/origin/emitter matching criteria for a subscription.
    struct SubscriptionFilter {
        bytes32[4] eventTopics;
        address origin;
        address emitter;
    }

    /// @notice Gas and fee controls for subscription callback execution.
    struct SubscriptionOptions {
        uint64 priorityFeePerGas;
        uint64 maxFeePerGas;
        uint64 gasLimit;
    }

    /// @notice Fixed address for the Somnia Reactivity Precompile.
    address public constant SOMNIA_REACTIVITY_PRECOMPILE_ADDRESS =
        address(0x0100);
    /// @notice Minimum balance required by a subscription owner.
    uint256 public constant SUBSCRIPTION_OWNER_MINIMUM_BALANCE = 32 ether;
    /// @notice Minimum protocol base fee per gas used in fee validation.
    uint256 public constant MINIMUM_BASE_FEE_PER_GAS = 6 gwei;
    /// @notice Maximum callback gas limit allowed for a single subscription.
    uint64 public constant MAXIMUM_HANDLER_GAS_LIMIT = 200_000_000;
    /// @notice Default priority fee per gas used when callers opt into defaults.
    uint64 public constant DEFAULT_PRIORITY_FEE_PER_GAS = 0;
    /// @notice Default max fee per gas used when callers opt into defaults.
    uint64 public constant DEFAULT_MAX_FEE_PER_GAS = 20 gwei;
    /// @notice Default callback gas limit used when callers opt into defaults.
    uint64 public constant DEFAULT_HANDLER_GAS_LIMIT = 10_000_000;

    error HandlerZeroAddress();
    error EmptyFilter();
    error GasLimitZero();
    error GasLimitExceeded();
    error InvalidMaxFeePerGas();
    error InsufficientBalance();
    error TimestampInPast();
    error BlockInPast();
    error UnsubscribeFailed();

    /// @notice Creates a subscription owned by the caller using filter and gas options.
    /// @param handler Address of the handler contract that receives callbacks.
    /// @param filter Filter criteria for matching logs.
    /// @param options Fee and gas options for callback execution.
    /// @return subscriptionId Newly created subscription identifier.
    function subscribe(
        address handler,
        SubscriptionFilter memory filter,
        SubscriptionOptions memory options
    ) internal returns (uint256 subscriptionId) {
        return _subscribe(handler, filter, options);
    }

    /// @notice Creates a schedule subscription for an absolute millisecond timestamp.
    /// @param handler Address of the handler contract that receives callbacks.
    /// @param timestampMillis Absolute unix timestamp in milliseconds.
    /// @param options Fee and gas options for callback execution.
    /// @return subscriptionId Newly created subscription identifier.
    function scheduleSubscriptionAtTimestamp(
        address handler,
        uint256 timestampMillis,
        SubscriptionOptions memory options
    ) internal returns (uint256 subscriptionId) {
        if (timestampMillis < ((block.timestamp + 1) * 1000) + 1) {
            revert TimestampInPast();
        }

        SubscriptionFilter memory filter = SubscriptionFilter({
            eventTopics: [
                ISomniaReactivityPrecompile.Schedule.selector,
                bytes32(timestampMillis),
                bytes32(0),
                bytes32(0)
            ],
            origin: address(0),
            emitter: SOMNIA_REACTIVITY_PRECOMPILE_ADDRESS
        });

        return _subscribe(handler, filter, options);
    }

    /// @notice Creates a subscription triggered at a specific future block.
    /// @param handler Address of the handler contract that receives callbacks.
    /// @param blockNumber Future block number to trigger on.
    /// @param options Fee and gas options for callback execution.
    /// @return subscriptionId Newly created subscription identifier.
    function scheduleSubscriptionAtBlock(
        address handler,
        uint64 blockNumber,
        SubscriptionOptions memory options
    ) internal returns (uint256 subscriptionId) {
        if (blockNumber < block.number + 1) {
            revert BlockInPast();
        }

        SubscriptionFilter memory filter = SubscriptionFilter({
            eventTopics: [
                ISomniaReactivityPrecompile.BlockTick.selector,
                bytes32(uint256(blockNumber)),
                bytes32(0),
                bytes32(0)
            ],
            origin: address(0),
            emitter: SOMNIA_REACTIVITY_PRECOMPILE_ADDRESS
        });

        return _subscribe(handler, filter, options);
    }

    /// @notice Creates a subscription triggered at a specific epoch.
    /// @param handler Address of the handler contract that receives callbacks.
    /// @param epochNumber Epoch number to trigger on.
    /// @param options Fee and gas options for callback execution.
    /// @return subscriptionId Newly created subscription identifier.
    function scheduleSubscriptionAtEpoch(
        address handler,
        uint64 epochNumber,
        SubscriptionOptions memory options
    ) internal returns (uint256 subscriptionId) {
        SubscriptionFilter memory filter = SubscriptionFilter({
            eventTopics: [
                ISomniaReactivityPrecompile.EpochTick.selector,
                bytes32(uint256(epochNumber)),
                bytes32(0),
                bytes32(0)
            ],
            origin: address(0),
            emitter: SOMNIA_REACTIVITY_PRECOMPILE_ADDRESS
        });

        return _subscribe(handler, filter, options);
    }

    /// @notice Cancels a subscription.
    /// @param subscriptionId Existing subscription identifier.
    function unsubscribe(uint256 subscriptionId) internal {
        // Low-level call used to bypass false positives from Solidity safety checks
        // solhint-disable-next-line avoid-low-level-calls
        (bool success, ) = SOMNIA_REACTIVITY_PRECOMPILE_ADDRESS.call(
            abi.encodeWithSelector(ISomniaReactivityPrecompile.unsubscribe.selector, subscriptionId)
        );
        if (!success) revert UnsubscribeFailed();
    }

    /// @notice Fetches subscription details and owner for a subscription id.
    /// @param subscriptionId Existing subscription identifier.
    /// @return subscriptionData Stored subscription parameters.
    /// @return owner Address currently owning the subscription.
    function getSubscriptionInfo(
        uint256 subscriptionId
    )
        internal
        view
        returns (
            ISomniaReactivityPrecompile.SubscriptionData
                memory subscriptionData,
            address owner
        )
    {
        return
            ISomniaReactivityPrecompile(SOMNIA_REACTIVITY_PRECOMPILE_ADDRESS)
                .getSubscriptionInfo(subscriptionId);
    }

    /// @notice Returns the library default fee and gas options for subscriptions.
    /// @return options Default subscription options struct.
    function defaultSubscriptionOptions()
        internal
        pure
        returns (SubscriptionOptions memory)
    {
        return
            SubscriptionOptions({
                priorityFeePerGas: DEFAULT_PRIORITY_FEE_PER_GAS,
                maxFeePerGas: DEFAULT_MAX_FEE_PER_GAS,
                gasLimit: DEFAULT_HANDLER_GAS_LIMIT
            });
    }

    /// @dev Internal helper used by all public subscription creation functions.
    function _subscribe(
        address handler,
        SubscriptionFilter memory filter,
        SubscriptionOptions memory options
    ) private returns (uint256 subscriptionId) {
        if (handler == address(0)) {
            revert HandlerZeroAddress();
        }
        if (!_hasAnyFilter(filter)) {
            revert EmptyFilter();
        }
        if (options.gasLimit == 0) {
            revert GasLimitZero();
        }
        if (options.gasLimit > MAXIMUM_HANDLER_GAS_LIMIT) {
            revert GasLimitExceeded();
        }
        if (
            options.maxFeePerGas != 0 &&
            options.priorityFeePerGas + MINIMUM_BASE_FEE_PER_GAS  >
            options.maxFeePerGas
        ) {
            revert InvalidMaxFeePerGas();
        }
        if (address(this).balance < SUBSCRIPTION_OWNER_MINIMUM_BALANCE) {
            revert InsufficientBalance();
        }

        return
            ISomniaReactivityPrecompile(SOMNIA_REACTIVITY_PRECOMPILE_ADDRESS)
                .subscribe(_buildSubscriptionData(handler, filter, options));
    }

    /// @dev Returns true when at least one filter criterion is non-wildcard.
    function _hasAnyFilter(
        SubscriptionFilter memory filter
    ) private pure returns (bool hasAnyFilter) {
        return
            filter.origin != address(0) ||
            filter.emitter != address(0) ||
            filter.eventTopics[0] != bytes32(0) ||
            filter.eventTopics[1] != bytes32(0) ||
            filter.eventTopics[2] != bytes32(0) ||
            filter.eventTopics[3] != bytes32(0);
    }

    /// @dev Builds low-level precompile subscription payload from high-level inputs.
    function _buildSubscriptionData(
        address handler,
        SubscriptionFilter memory filter,
        SubscriptionOptions memory options
    )
        private
        pure
        returns (
            ISomniaReactivityPrecompile.SubscriptionData memory subscriptionData
        )
    {
        ISomniaReactivityPrecompile.SubscriptionData
            memory data = ISomniaReactivityPrecompile.SubscriptionData({
                eventTopics: filter.eventTopics,
                origin: filter.origin,
                caller: address(0),
                emitter: filter.emitter,
                handlerContractAddress: handler,
                handlerFunctionSelector: ISomniaEventHandler.onEvent.selector,
                priorityFeePerGas: options.priorityFeePerGas,
                maxFeePerGas: options.maxFeePerGas,
                gasLimit: options.gasLimit,
                isGuaranteed: false,
                isCoalesced: false
            });

        return data;
    }
}