Skill — Copyable reference implementation. Use as-is or customize. See Skills Philosophy.
Event Listening
This guide covers subscribing to live contract events and querying historical event logs using Voltaire’s Contract and EventStream APIs.Prerequisites
Creating a Contract Instance
Subscribing to Live Events
Usewatch() to poll for new events as they occur:
Start Watching from a Specific Block
Stop Watching with AbortSignal
Querying Historical Events
Usebackfill() to fetch events from a specific block range:
Dynamic Chunking for Large Ranges
EventStream automatically handles large block ranges by chunking requests:- Starts with 500 blocks per request (configurable)
- Reduces chunk size by 50% on “block range too large” errors
- Increases chunk size by 25% after 5 consecutive successes
Backfill Then Watch Pattern
Process all historical events, then continue with live events:Filtering by Topic
Filter events by indexed parameters when creating the stream:Filter by Sender
Filter by Recipient
Filter by Both Sender and Recipient
Decoding Event Data
Each yielded result contains the decoded log and metadata:Standalone EventStream
Create an EventStream without a Contract for more control:Retry Configuration
Configure retry behavior for transient RPC errors:Error Handling
Low-Level: Using eth_getLogs Directly
For maximum control, use the provider’seth_getLogs method directly:
Collecting Events into an Array
Break out of the stream after collecting a set number of events:Break on Condition
Stop streaming when a specific condition is met:Related
- Contract Events Reference - Full EventStream API
- Contract Overview - Contract module introduction
- Logs & Filters - Low-level eth_getLogs

