Best practices for designing Solidity events on Ethereum and the EVM

Solidity events are a critical feature of Ethereum and EVM blockchains, providing a wide range of use cases essential to the ecosystem. According to the EigenLayer blog, these use cases include logging, off-chain notifications, data indexing and analytics, cross-contract communication, and security monitoring.

For example, events allow smart contracts to record important operations and state changes, which are essential for tracking and debugging contract behavior. Off-chain applications can listen for specific on-chain operations of smart contracts and trigger downstream logic. Events can also be indexed, stored, processed, and analyzed to provide valuable insights and patterns within smart contracts.

EigenLayer emphasizes the importance of designing Solidity events efficiently and cost-effectively. The protocol itself emits a wide range of events on Ethereum, which are used to test, debug, and trigger event-based logic. Events are also indexed into data repositories and data lakes to drive both internal and external analytics, supporting critical protocol functions such as reward calculations and slashing. Real-time monitoring of withdrawal events helps alert teams to unexpected behavior and potential risks.

Descriptive

Events should be self-explanatory, allowing others to read the name and schema and immediately understand the purpose of the event. Avoid using abbreviations in names for clarity. For example, use ‘UserRegisteredEvent’ instead of ‘URE’ to clearly specify the purpose of the event.

Factual by semantics

Events should accurately reflect what happened on-chain without ambiguity. For example, use ‘UserDeletionRequestedEvent’ instead of ‘UserDeletionEvent’ to make it clear that this is a request event and not an actual delete operation.

Atomic and composable

Event design should maintain granularity of operations by breaking complex operations into smaller, atomic events. This ensures that each event is independent and can be composed together to restore the entire history. For example, capture each step separately using ‘UserDeletionRequestedEvent’, ‘UserDeletionWithdrawnEvent’, and ‘UserDeletionCompletedEvent’.

Standalone

Events should contain all the information necessary to interpret them without relying on external data. For example, a ‘UserDepositEvent’ should contain fields such as ‘user_id’, ‘erc20_token’, ‘amount’, ‘from_address’, and ‘to_address’ to provide a complete picture.

Symmetric

On-chain actions are often symmetric, such as registering and deregistering, or depositing and withdrawing. Event design should reflect this symmetry to simplify data processing. For example, ‘WalletDepositEvent’ and ‘WalletWithdrawEvent’ should have similar structures.

Flat and not deeply nested

Events are easier to work with if they are flat rather than deeply nested. Nested events often need to be flattened before use, adding complexity and cost. For example, ‘WalletWithdrawEvent’ should contain simple fields like ‘wallet_address’, ‘to_address’, ‘amount’.

Entity and domain oriented

Events should be categorized by entities or domains, such as ‘User’, ‘Staker’, or ‘Operator’. Using a naming convention like ‘EntityActionEvent’ (e.g. ‘UserLoginEvent’) will help you organize and search for events more efficiently.

Other technical considerations

• Control the size and frequency of events to avoid excessive costs.
• Consider whether to issue events on-chain or off-chain, depending on cost and need.

In conclusion, Solidity events are mission critical to EigenLayer and its ecosystem, as well as all protocols on Ethereum and the EVM. Following these best practices will help developers design events that are efficient, scalable, cost-effective, and developer-friendly.

For more information, visit the EigenLayer blog.

Image source: Shutterstock