Skip to main content
Events are the primary mechanism for smart contracts to communicate what happened on-chain. This tutorial covers emitting events in Solidity, querying them via JSON-RPC, and decoding them with ethers.js.

Emitting events in Solidity

Querying events with ethers.js

Filtering by indexed parameters

Indexed event parameters can be used as topics for efficient filtering:
You can also filter with null to match any value:

Raw eth_getLogs

For lower-level access or when you don’t have the ABI:
Compute the topic hash for an event signature:

Real-time event subscription

Real-time subscriptions require a WebSocket connection, and public WebSocket endpoints are not currently offered on Mainnet or Testnet (see Network endpoints).Query past events over HTTP with queryFilter, or point the provider at the local WebSocket port on a node you run yourself.

Decoding raw log data

If you have raw log data without the ABI:

Best practices

  • Index only parameters you need to filter on — indexed parameters cost more gas
  • Keep event payloads minimal; emit only what consumers need
  • Do not use events as the primary storage mechanism — use them for off-chain notification
  • Paginate eth_getLogs queries in blocks of 1,000–10,000 to avoid timeout errors

Next steps