Service events are special messages that are generated by smart contracts and included in execution results. They enable communication between system smart contracts and the Flow protocol. In other words, they serve as a communication mechanism between the execution state and the protocol state.
Concretely, service events are defined and emitted as events like any other in Cadence. An event is considered a service event when it is defined on the service event allowlist, in the systemcontracts package. By convention, only service events defined within system contracts (contracts deployed to accounts controlled by the service account) may be added to the event allowlist.
<aside> 🗣 Previously, service events also were required to be emitted during execution of the system chunk. Now service events may be emitted during any transaction. See Revising Service Event Constraints (Apr 2024) for details.
</aside>
When verifying a chunk, Verification Nodes will only produce result approvals when the service events included in the execution result are correct. Thus, the security of this communication mechanism is enforced by the Verification & Sealing sub-system.
When sealing a block in which a a service event was emitted during execution, the consensus committee will update the protocol state accordingly, depending on the semantics of the event.
For example, a service event may indicate that a node's stake has diminished to the point where they should be ejected, in which case the consensus committee would mark that node as ejected in the protocol state.
Service events are fundamentally asynchronous, due the lag between block execution and sealing. Consequently they are handled slightly differently than other protocol state updates.
For a service event emitted in block N, associated state changes are applied at block M and become finalized at block K.
<aside>
📒 For conciseness, we say a service event is sealed when the block in which it was emitted is sealed, and we say a service event is finalized when the block containing the seal is finalized.
</aside>
Service events are fork-specific. Let s be a service event included in block B. Event s only applies in the fork which has block B as the root of its subtree.