From fdd0cf4c50fba78dd20b139b923070bb186461dd Mon Sep 17 00:00:00 2001
From: raymax0x <recognizeyourself909@gmail.com>
Date: Mon, 30 Jun 2025 15:48:55 +0530
Subject: [PATCH] feat: add utility function to find events by key

This commit introduces a new utility function, `EventWith`, that allows searching for events within a transaction receipt or a slice of events based on a specific key.

The `EventWith` function iterates through the events and compares the provided key against the event keys. If a match is found, the corresponding event is returned. This functionality simplifies event filtering and retrieval, making it easier to work with transaction receipts and event data.

A new method `EventWith` is added to `TransactionReceiptWithBlockInfo` to use the new utility function.

Additionally, comprehensive unit tests are included to ensure the correctness and reliability of the new function.
---
 rpc/events.go                    | 18 +++++++++++++++
 rpc/events_test.go               | 38 ++++++++++++++++++++++++++++++++
 rpc/types_transaction_receipt.go |  6 +++++
 3 files changed, 62 insertions(+)

diff --git a/rpc/events.go b/rpc/events.go
index decb996b4..b00426b33 100644
--- a/rpc/events.go
+++ b/rpc/events.go
@@ -2,6 +2,8 @@ package rpc
 
 import (
 	"context"
+
+	internalutils "github.com/NethermindEth/starknet.go/internal/utils"
 )
 
 // Events retrieves events from the provider matching the given filter.
@@ -23,3 +25,19 @@ func (provider *Provider) Events(ctx context.Context, input EventsInput) (*Event
 
 	return &result, nil
 }
+
+func EventWith(events []Event, key string) *Event {
+	feltKey, err := internalutils.HexToFelt(key)
+	if err != nil {
+		return nil
+	}
+
+	for i := range events {
+		for _, k := range events[i].Keys {
+			if k.Equal(feltKey) {
+				return &events[i]
+			}
+		}
+	}
+	return nil
+}
diff --git a/rpc/events_test.go b/rpc/events_test.go
index 65e200082..14c588286 100644
--- a/rpc/events_test.go
+++ b/rpc/events_test.go
@@ -142,3 +142,41 @@ func TestEvents(t *testing.T) {
 		require.Exactly(t, test.expectedResp.Events[0], events.Events[0], "Events mismatch")
 	}
 }
+
+func TestEventWith(t *testing.T) {
+	key := "0xabc"
+	feltKey := internalUtils.TestHexToFelt(t, key)
+
+	events := []Event{
+		{
+			EventContent: EventContent{
+				Keys: []*felt.Felt{feltKey},
+			},
+		},
+	}
+
+	found := EventWith(events, key)
+	require.NotNil(t, found, "Expected to find event")
+	require.True(t, found.Keys[0].Equal(feltKey), "Expected matching key")
+}
+
+func TestTransactionReceiptWithBlockInfo_EventWith(t *testing.T) {
+	key := "0xdead"
+	feltKey := internalUtils.TestHexToFelt(t, key)
+
+	receipt := &TransactionReceiptWithBlockInfo{
+		TransactionReceipt: TransactionReceipt{
+			Events: []Event{
+				{
+					EventContent: EventContent{
+						Keys: []*felt.Felt{feltKey},
+					},
+				},
+			},
+		},
+	}
+
+	found := receipt.EventWith(key)
+	require.NotNil(t, found, "Expected to find event from receipt method")
+	require.True(t, found.Keys[0].Equal(feltKey), "Expected matching key in receipt method")
+}
diff --git a/rpc/types_transaction_receipt.go b/rpc/types_transaction_receipt.go
index 67c7425c1..7f28d02c9 100644
--- a/rpc/types_transaction_receipt.go
+++ b/rpc/types_transaction_receipt.go
@@ -205,3 +205,9 @@ func (tr *TransactionReceiptWithBlockInfo) UnmarshalJSON(data []byte) error {
 
 	return nil
 }
+
+// EventWith finds the first event in the transaction receipt that has a specific key.
+// The key is provided as a hex string. If no event is found, it returns nil.
+func (tr *TransactionReceiptWithBlockInfo) EventWith(key string) *Event {
+	return EventWith(tr.Events, key)
+}