Events & Logs — How to structure your events

Name clearlyUse past-tense verbs (Transfer, RoleGranted) and avoid overloading similar names. Consistency makes indexing simpler.

Talk is cheap. Show me the code.

— Linus Torvalds

Include who/whatLog the caller, the subject, and the value. Index addresses and ids you expect users to filter on. Keep payloads small; avoid dumping arrays or large blobs.

VersioningIf you must change event shapes, consider emitting both old and new for a transition period or ship a new contract. Communicate signature changes to integrators.

Don’t misuse eventsNever store critical state only in events. Contracts cannot read logs; if the value matters to logic, put it in storage and emit an event alongside.