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

rpc/events.go

@@ -2,6 +2,8 @@
 
 import (
 	"context"
+
+	internalutils "github.com/NethermindEth/starknet.go/internal/utils"
 )
 
 // Events retrieves events from the provider matching the given filter.
@@ -23,3 +25,19 @@
 
 	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
+}

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")
+}

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)
+}