Transaction events parser

multiversx_sdk/abi/abi.py

@@ -1,10 +1,12 @@
 from copy import deepcopy
 from pathlib import Path
+from types import SimpleNamespace
 from typing import Any, Dict, List, cast
 
 from multiversx_sdk.abi.abi_definition import (AbiDefinition,
                                                EndpointDefinition,
-                                               EnumDefinition,
+                                               EnumDefinition, EventDefinition,
+                                               EventTopicDefinition,
                                                ParameterDefinition,
                                                StructDefinition)
 from multiversx_sdk.abi.address_value import AddressValue
@@ -39,6 +41,7 @@ def __init__(self, definition: AbiDefinition) -> None:
         self.definition = definition
         self.custom_types_prototypes_by_name: Dict[str, Any] = {}
         self.endpoints_prototypes_by_name: Dict[str, EndpointPrototype] = {}
+        self.events_prototypes_by_name: Dict[str, EventPrototype] = {}
 
         for name in definition.types.enums:
             self.custom_types_prototypes_by_name[name] = self._create_custom_type_prototype(name)
@@ -67,6 +70,15 @@ def __init__(self, definition: AbiDefinition) -> None:
 
             self.endpoints_prototypes_by_name[endpoint.name] = endpoint_prototype
 
+        for event in definition.events:
+            prototype = self._create_event_input_prototypes(event)
+
+            event_prototype = EventPrototype(
+                fields=prototype
+            )
+
+            self.events_prototypes_by_name[event.identifier] = event_prototype
+
     def _create_custom_type_prototype(self, name: str) -> Any:
         if name in self.definition.types.enums:
             definition = self.definition.types.enums[name]
@@ -126,10 +138,23 @@ def _create_endpoint_output_prototypes(self, endpoint: EndpointDefinition) -> Li
 
         return prototypes
 
+    def _create_event_input_prototypes(self, event: EventDefinition) -> List[Any]:
+        prototypes: List[Any] = []
+
+        for topic in event.inputs:
+            event_field_prototype = EventField(name=topic.name, value=self._create_event_field_prototype(topic))
+            prototypes.append(event_field_prototype)
+
+        return prototypes
+
     def _create_parameter_prototype(self, parameter: ParameterDefinition) -> Any:
         type_formula = self._type_formula_parser.parse_expression(parameter.type)
         return self._create_prototype(type_formula)
 
+    def _create_event_field_prototype(self, parameter: EventTopicDefinition) -> Any:
+        type_formula = self._type_formula_parser.parse_expression(parameter.type)
+        return self._create_prototype(type_formula)
+
     def encode_constructor_input_parameters(self, values: List[Any]) -> List[bytes]:
         return self._do_encode_endpoint_input_parameters("constructor", self.constructor_prototype, values)
 
@@ -163,6 +188,39 @@ def decode_endpoint_output_parameters(self, endpoint_name: str, encoded_values:
         output_native_values = [value.get_payload() for value in output_values_as_native_object_holders]
         return output_native_values
 
+    def decode_event(self, event_name: str, topics: List[bytes], data_items: List[bytes]) -> SimpleNamespace:
+        result = SimpleNamespace()
+        event_definition = self.definition.get_event_definition(event_name)
+        event_prototype = self._get_event_prototype(event_name)
+
+        indexed_inputs = [input for input in event_definition.inputs if input.indexed]
+        indexed_inputs_names = [item.name for item in indexed_inputs]
+
+        fields = deepcopy(event_prototype.fields)
+
+        output_values = [field.value for field in fields if field.name in indexed_inputs_names]
+        self._serializer.deserialize_parts(topics, output_values)
+
+        output_values_as_native_object_holders = cast(List[IPayloadHolder], output_values)
+        output_native_values = [value.get_payload() for value in output_values_as_native_object_holders]
+
+        for i in range(len(indexed_inputs)):
+            setattr(result, indexed_inputs[i].name, output_native_values[i])
+
+        non_indexed_inputs = [input for input in event_definition.inputs if not input.indexed]
+        non_indexed_inputs_names = [item.name for item in non_indexed_inputs]
+
+        output_values = [field.value for field in fields if field.name in non_indexed_inputs_names]
+        self._serializer.deserialize_parts(data_items, output_values)
+
+        output_values_as_native_object_holders = cast(List[IPayloadHolder], output_values)
+        output_native_values = [value.get_payload() for value in output_values_as_native_object_holders]
+
+        for i in range(len(non_indexed_inputs)):
+            setattr(result, non_indexed_inputs[i].name, output_native_values[i])
+
+        return result
+
     def _get_custom_type_prototype(self, type_name: str) -> Any:
         type_prototype = self.custom_types_prototypes_by_name.get(type_name)
 
@@ -179,6 +237,14 @@ def _get_endpoint_prototype(self, endpoint_name: str) -> 'EndpointPrototype':
 
         return endpoint_prototype
 
+    def _get_event_prototype(self, event_name: str) -> 'EventPrototype':
+        event_prototype = self.events_prototypes_by_name.get(event_name)
+
+        if not event_prototype:
+            raise ValueError(f"event '{event_name}' not found")
+
+        return event_prototype
+
     def _create_prototype(self, type_formula: TypeFormula) -> Any:
         name = type_formula.name
 
@@ -248,3 +314,14 @@ class EndpointPrototype:
     def __init__(self, input_parameters: List[Any], output_parameters: List[Any]) -> None:
         self.input_parameters = input_parameters
         self.output_parameters = output_parameters
+
+
+class EventField:
+    def __init__(self, name: str, value: Any) -> None:
+        self.name = name
+        self.value = value
+
+
+class EventPrototype:
+    def __init__(self, fields: List[EventField]) -> None:
+        self.fields = fields

multiversx_sdk/abi/abi_definition.py

@@ -8,11 +8,13 @@ def __init__(self,
                  constructor: "EndpointDefinition",
                  upgrade_constructor: "EndpointDefinition",
                  endpoints: List["EndpointDefinition"],
-                 types: "TypesDefinitions") -> None:
+                 types: "TypesDefinitions",
+                 events: List["EventDefinition"]) -> None:
         self.constructor = constructor
         self.upgrade_constructor = upgrade_constructor
         self.endpoints = endpoints
         self.types = types
+        self.events = events
 
     @classmethod
     def from_dict(cls, data: Dict[str, Any]) -> "AbiDefinition":
@@ -25,11 +27,14 @@ def from_dict(cls, data: Dict[str, Any]) -> "AbiDefinition":
         endpoints = [EndpointDefinition.from_dict(item) for item in data["endpoints"]] if "endpoints" in data else []
         types = TypesDefinitions.from_dict(data.get("types", {}))
 
+        events = [EventDefinition.from_dict(item) for item in data["events"]] if "events" in data else []
+
         return cls(
             constructor=constructor,
             upgrade_constructor=upgrade_constructor,
             endpoints=endpoints,
-            types=types
+            types=types,
+            events=events
         )
 
     @classmethod
@@ -45,7 +50,8 @@ def _get_definition_for_upgrade(cls, data: Dict[str, Any]) -> "EndpointDefinitio
             return EndpointDefinition.from_dict(data["upgradeConstructor"])
 
         # Fallback for contracts written using a not-old, but not-new Rust framework:
-        if "upgrade" in data["endpoints"]:
+        endpoints = data.get("endpoints", [])
+        if "upgrade" in endpoints:
             return EndpointDefinition.from_dict(data["endpoints"]["upgrade"])
 
         # Fallback for contracts written using an old Rust framework:
@@ -60,6 +66,17 @@ def load(cls, path: Path) -> "AbiDefinition":
         data = json.loads(content)
         return cls.from_dict(data)
 
+    def get_event_definition(self, name: str) -> "EventDefinition":
+        event = [event for event in self.events if event.identifier == name]
+
+        if not len(event):
+            raise Exception(f"event [{name}] not found")
+
+        if len(event) > 1:
+            raise Exception(f"more than one event found: [{event}]")
+
+        return event[0]
+
 
 class EndpointDefinition:
     def __init__(self,
@@ -282,7 +299,7 @@ def from_dict(cls, data: Dict[str, Any]) -> "EventTopicDefinition":
         return cls(
             name=data["name"],
             type=data["type"],
-            indexed=data["indexed"]
+            indexed=data.get("indexed", False)
         )
 
     def __repr__(self):

multiversx_sdk/abi/abi_test.py

@@ -31,6 +31,8 @@ def test_abi():
     assert abi.definition.upgrade_constructor.inputs == [ParameterDefinition("initial_value", "BigUint")]
     assert abi.definition.upgrade_constructor.outputs == []
 
+    assert abi.definition.events == []
+
     assert abi.definition.endpoints[0].name == "getSum"
     assert abi.definition.endpoints[0].inputs == []
     assert abi.definition.endpoints[0].outputs == [ParameterDefinition("", "BigUint")]
@@ -54,6 +56,13 @@ def test_abi():
     assert abi.endpoints_prototypes_by_name["add"].output_parameters == []
 
 
+def test_abi_events():
+    abi = Abi.load(testdata / "artificial.abi.json")
+
+    assert len(abi.definition.events) == 1
+    assert abi.events_prototypes_by_name["firstEvent"].fields[0].value == BigUIntValue()
+
+
 def test_encode_endpoint_input_parameters_artificial_contract():
     abi = Abi.load(testdata / "artificial.abi.json")
 

multiversx_sdk/core/transactions_outcome_parsers/__init__.py

@@ -2,7 +2,7 @@
     DelegationTransactionsOutcomeParser
 from multiversx_sdk.core.transactions_outcome_parsers.resources import (
     SmartContractResult, TransactionEvent, TransactionLogs, TransactionOutcome,
-    find_events_by_identifier)
+    find_events_by_first_topic, find_events_by_identifier)
 from multiversx_sdk.core.transactions_outcome_parsers.smart_contract_transactions_outcome_parser import \
     SmartContractTransactionsOutcomeParser
 from multiversx_sdk.core.transactions_outcome_parsers.token_management_transactions_outcome_parser import \
@@ -11,5 +11,5 @@
 __all__ = [
     "TokenManagementTransactionsOutcomeParser", "SmartContractResult", "TransactionEvent",
     "TransactionLogs", "TransactionOutcome", "find_events_by_identifier", "DelegationTransactionsOutcomeParser",
-    "SmartContractTransactionsOutcomeParser"
+    "SmartContractTransactionsOutcomeParser", "find_events_by_first_topic"
 ]

multiversx_sdk/core/transactions_outcome_parsers/resources.py

@@ -59,6 +59,10 @@ def find_events_by_identifier(transaction_outcome: TransactionOutcome, identifie
     return find_events_by_predicate(transaction_outcome, lambda event: event.identifier == identifier)
 
 
+def find_events_by_first_topic(transaction_outcome: TransactionOutcome, topic: str) -> List[TransactionEvent]:
+    return find_events_by_predicate(transaction_outcome, lambda event: event.topics[0].decode() == topic if len(event.topics) else False)
+
+
 def find_events_by_predicate(
     transaction_outcome: TransactionOutcome,
     predicate: Callable[[TransactionEvent], bool]

multiversx_sdk/core/transactions_outcome_parsers/transaction_events_parser.py

@@ -0,0 +1,39 @@
+from types import SimpleNamespace
+from typing import List, Protocol
+
+from multiversx_sdk.core.transactions_outcome_parsers.resources import \
+    TransactionEvent
+
+
+class IAbi(Protocol):
+    def decode_event(self, event_name: str, topics: List[bytes], data_items: List[bytes]) -> SimpleNamespace:
+        ...
+
+
+class TransactionEventsParser:
+    def __init__(self, abi: IAbi, first_topic_as_identifier: bool = True) -> None:
+        self.abi = abi
+
+        # By default, we consider that the first topic is the event identifier.
+        # This is true for log entries emitted by smart contracts:
+        # https://github.com/multiversx/mx-chain-vm-go/blob/v1.5.27/vmhost/contexts/output.go#L270
+        # https://github.com/multiversx/mx-chain-vm-go/blob/v1.5.27/vmhost/contexts/output.go#L283
+        self.first_topic_as_identifier = first_topic_as_identifier
+
+    def parse_events(self, events: List[TransactionEvent]) -> List[SimpleNamespace]:
+        return [self.parse_event(event) for event in events]
+
+    def parse_event(self, event: TransactionEvent) -> SimpleNamespace:
+        first_topic = event.topics[0].decode() if len(event.topics) else ""
+        abi_identifier = first_topic if first_topic and self.first_topic_as_identifier else event.identifier
+
+        topics = event.topics
+
+        if self.first_topic_as_identifier:
+            topics = topics[1:]
+
+        return self.abi.decode_event(
+            event_name=abi_identifier,
+            topics=topics,
+            data_items=event.data_items,
+        )