event-design

Event Design

Design Contracts Event-First

Events are the primary interface between onchain state and offchain systems. Design events before writing contract logic. Every state-changing function should emit at least one event.

// Define events FIRST, then build the contract around them
interface IVaultEvents {
    event Deposited(address indexed user, address indexed token, uint256 amount, uint256 shares);
    event Withdrawn(address indexed user, address indexed token, uint256 amount, uint256 shares);
    event FeeCollected(address indexed collector, uint256 amount);
    event StrategyUpdated(address indexed oldStrategy, address indexed newStrategy);
    event EmergencyShutdown(address indexed triggeredBy, uint256 timestamp);
}

Indexed Parameters

• Max 3 indexed parameters per event (4 for anonymous events)
• Indexed parameters become log topics — filterable by indexers
• Non-indexed parameters go in the data section — cheaper, not filterable
• Value types (address, uint, bool, bytes32) are stored directly as topics
• Reference types (string, bytes, arrays) are stored as their keccak256 hash when indexed

// GOOD: key actors indexed for filtering, amounts in data for reading
event Transfer(address indexed from, address indexed to, uint256 amount);

// GOOD: token indexed for per-token queries
event Swap(
    address indexed sender,
    address indexed tokenIn,
    address indexed tokenOut,
    uint256 amountIn,
    uint256 amountOut,
    uint256 fee
);

// BAD: indexing a string hashes it — you can't read the original value from the topic
event NameChanged(string indexed name); // topic = keccak256(name), not the string

What to Index