Skip to main content

ISubscriptionService

Overview​

The following Solidity code defines the ISubscriptionService interface, which serves as an event subscription service for reactive contracts that can use this service to subscribe to specific events based on certain criteria and receive notifications when those events occur.

ISubscriptionService.sol
pragma solidity >=0.8.0;

interface ISubscriptionService {
    function subscribe(
        uint256 chain_id,
        address _contract,
        uint256 topic_0,
        uint256 topic_1,
        uint256 topic_2,
        uint256 topic_3
    ) external;
    function unsubscribe(
        uint256 chain_id,
        address _contract,
        uint256 topic_0,
        uint256 topic_1,
        uint256 topic_2,
        uint256 topic_3
    ) external;
}

Description​

The interface consists of two functions: subscribe and unsubscribe. The subscribe function allows a contract to subscribe to events emitted by other contracts when these events match the specified criteria. The unsubscribe function removes an active subscription of the calling contract, if one exists, based on the specified criteria. The parameters of both functions mirror each other:

  • chain_id: A uint256 representing the EIP155 source chain ID for the event.

  • _contract: The address of the originating contract that emitted the event.

  • topic_0, topic_1, topic_2, topic_3: The topics of the event, which are uint256 values. Depending on the event, these topics may contain specific information related to the event. At least one of these topics must be specified, or REACTIVE_IGNORE can be used to subscribe to all topics.

Both the subscribe and unsubscribe functions in the ISubscriptionService interface are marked as external. Any contract that implements the ISubscriptionService interface must provide functions with identical parameters and visibility specifier for both subscribe and unsubscribe, and these functions must be callable from outside the implementing contract.

note

Unsubscribing is an expensive operation due to the necessity of searching and removing subscriptions. Duplicate or overlapping subscriptions are allowed, but clients must ensure idempotency.