feat: add EventWith utility and method to filter events (issue #765)

[raymax0x]

Feat: Add Utility for Filtering Events by Key

This pull request introduces a utility function and an associated method for filtering transaction events by key, addressing #765.

---

What’s New

• EventWith(events []Event, key string) *Event:
  A new function added to rpc/events.go that scans a slice of events and returns the first event containing a matching key.

• (*TransactionReceiptWithBlockInfo).EventWith(key string) *Event:
  A method added to the TransactionReceiptWithBlockInfo struct that internally uses EventWith(...) to return the first matching event in its Events field.

---

Changes Made

• Added EventWith function to rpc/events.go with key-to-felt conversion using internal/utils.HexToFelt.
• Added EventWith method to TransactionReceiptWithBlockInfo in rpc/types_transaction_receipt.go.
• Wrote unit tests in rpc/events_test.go to verify both function and method correctness.

---

✅ Verification

• ✅ All tests passed successfully
• ✅ Unit tests written for both the utility function and method.
• ✅ Compatible with existing receipt logic, no breaking changes.

To verify:

 go test ./...

[raymax0x]

Thanks @raymax0x! I want to expand the idea. In utils, a new file called events.go.

Inside, this new type: type EmittedEventOpts { BlockHash felt, BlockNumber felt, BlockNumberEnd felt, FromAddress felt, KeysSelectors [][]felt, TransactionHash felt, }

The following utilities:

• utils.EmittedEventsWith( emittedEvents []EmittedEvent, opts EmittedEventOpts ) []EmittedEvent
• utils.EmittedEventWith( emittedEvents []EmittedEvent, opts EmittedEventOpts ) EmittedEvent
• utils.EventsWith( events []EmittedEvent, fromAddress felt, keysSelectors [][]felt ) []Event
• utils.EventWith( events []EmittedEvent, fromAddress felt, keysSelectors [][]felt ) Event

The behaviour of keysSelectors [][]felt would be the same as the keys field demonstrated in the examples/readEvent example (ref)

You are free to suggest adjustments to the field names.

WDYT about it? Ask me any questions or give suggestions

Thanks for the quick feedback! Expanding this feature into centralising event filter helpers in utils/events.go sounds great.

It's good to have one event toolbox, which will make much easier to discover and maintain.

First I need to solve this issue, before expanding this feature :

Background

While adding the utility function, I ran into a cyclic-import issue.

Current Package Layout

• rpc – core types (Event, EmittedEvent, …)
• utils – helper functions

The problem: if we add new helpers to utils that rely on rpc types and rpc in turn needs those helpers, we create an import loop.

---

Options

Option	What we do	✅ Pros	⚠️ Cons
1. Keep everything in rpc	Add rpc/events_utils.go	Easiest change, guarantees no cyclic imports	rpc package keeps ballooning
2. Introduce an events package	Move all event-related types and helpers into a new package	Clear separation; both rpc and utils can import events	Requires a one-time refactor and updated imports
3. Interface-based approach	Define small interfaces in utils; have rpc types implement them	Decoupled and future-proof	Adds complexity and boilerplate

---

Next Step

Which option should i choose before I proceed?

[thiagodeev]

Thanks @raymax0x! Unfortunately, due to the proximity of Starknet v0.14.0 + RPC v0.9.0 update in Sepolia, I'll pause the reviews for a few days to release a compliant Starknet.go version ASAP. Hope you understand 🙌

Regarding your question, I understand. Maybe now is a good time to create the types pkg (ref issue). Create it, please, and move all event types that are triggering 'cyclic-import' issues

[raymax0x]

Thanks @raymax0x! Unfortunately, due to the proximity of Starknet v0.14.0 + RPC v0.9.0 update in Sepolia, I'll pause the reviews for a few days to release a compliant Starknet.go version ASAP. Hope you understand 🙌

Regarding your question, I understand. Maybe now is a good time to create the types pkg (ref issue). Create it, please, and move all event types that are triggering 'cyclic-import' issues

Thanks for the confirmation, @thiagodeev !

I'll go ahead and create the types package and move all event-related types there to resolve the cyclic import issues. Appreciate the direction, I’ll keep the changes scoped and aligned with the internal structure. Will update the PR soon. 🙌

[thiagodeev]

Hey @raymax0x! What's the status of this PR? Is it ready for review? Thanks!

[raymax0x]

Hey @raymax0x! What's the status of this PR? Is it ready for review? Thanks! Thanks for the ping, @thiagodeev. I’m tied up with work and will resume this next week. I’ll update the eventWith utility + tests and ping you when it’s ready for review.