add watching of entity deletion events

Author: matthiaszimmermann

src/arkiv/contract.py

@@ -17,44 +17,52 @@
 
 CREATED_EVENT: Final[str] = "GolemBaseStorageEntityCreated"
 UPDATED_EVENT: Final[str] = "GolemBaseStorageEntityUpdated"
-DELETED_EVENT: Final[str] = "GolemBaseStorageEntityDeleted"
 EXTENDED_EVENT: Final[str] = "GolemBaseStorageEntityBTLExtended"
+DELETED_EVENT: Final[str] = "GolemBaseStorageEntityDeleted"
 
+EVENTS: dict[str, str] = {
+    "created": CREATED_EVENT,
+    "updated": UPDATED_EVENT,
+    "extended": EXTENDED_EVENT,
+    "deleted": DELETED_EVENT,
+}
 
+TYPE_EVENT = "event"
+TYPE_UINT = "uint256"
 EVENTS_ABI: Final[Sequence[dict[str, Any]]] = [
     {
         "anonymous": False,
         "inputs": [
-            {"indexed": True, "name": "entityKey", "type": "uint256"},
-            {"indexed": False, "name": "expirationBlock", "type": "uint256"},
+            {"indexed": True, "name": "entityKey", "type": TYPE_UINT},
+            {"indexed": False, "name": "expirationBlock", "type": TYPE_UINT},
         ],
         "name": CREATED_EVENT,
-        "type": "event",
+        "type": TYPE_EVENT,
     },
     {
         "anonymous": False,
         "inputs": [
-            {"indexed": True, "name": "entityKey", "type": "uint256"},
-            {"indexed": False, "name": "expirationBlock", "type": "uint256"},
+            {"indexed": True, "name": "entityKey", "type": TYPE_UINT},
+            {"indexed": False, "name": "expirationBlock", "type": TYPE_UINT},
         ],
         "name": UPDATED_EVENT,
-        "type": "event",
+        "type": TYPE_EVENT,
     },
     {
         "anonymous": False,
-        "inputs": [{"indexed": True, "name": "entityKey", "type": "uint256"}],
+        "inputs": [{"indexed": True, "name": "entityKey", "type": TYPE_UINT}],
         "name": DELETED_EVENT,
-        "type": "event",
+        "type": TYPE_EVENT,
     },
     {
         "anonymous": False,
         "inputs": [
-            {"indexed": True, "name": "entityKey", "type": "uint256"},
-            {"indexed": False, "name": "oldExpirationBlock", "type": "uint256"},
-            {"indexed": False, "name": "newExpirationBlock", "type": "uint256"},
+            {"indexed": True, "name": "entityKey", "type": TYPE_UINT},
+            {"indexed": False, "name": "oldExpirationBlock", "type": TYPE_UINT},
+            {"indexed": False, "name": "newExpirationBlock", "type": TYPE_UINT},
         ],
         "name": EXTENDED_EVENT,
-        "type": "event",
+        "type": TYPE_EVENT,
     },
 ]
 

src/arkiv/events.py

@@ -11,10 +11,12 @@
 from web3.contract.contract import ContractEvent
 from web3.types import EventData, LogReceipt
 
-from .contract import CREATED_EVENT, EXTENDED_EVENT, UPDATED_EVENT
+from .contract import EVENTS
 from .types import (
     CreateCallback,
     CreateEvent,
+    DeleteCallback,
+    DeleteEvent,
     EventType,
     ExtendCallback,
     ExtendEvent,
@@ -34,7 +36,7 @@ def __init__(
         self,
         contract: Contract,
         event_type: EventType,
-        callback: CreateCallback | UpdateCallback | ExtendCallback,
+        callback: CreateCallback | UpdateCallback | ExtendCallback | DeleteCallback,
         from_block: str | int = "latest",
         auto_start: bool = True,
     ) -> None:
@@ -50,7 +52,9 @@ def __init__(
         """
         self.contract: Contract = contract
         self.event_type: EventType = event_type
-        self.callback: CreateCallback | UpdateCallback | ExtendCallback = callback
+        self.callback: (
+            CreateCallback | UpdateCallback | ExtendCallback | DeleteCallback
+        ) = callback
         self.from_block: str | int = from_block
 
         # Internal state
@@ -74,14 +78,9 @@ def start(self) -> None:
 
         # Create the Web3 filter
         contract_event: ContractEvent
-        if self.event_type == "created":
-            contract_event = self.contract.events[CREATED_EVENT]
-            self._filter = contract_event.create_filter(from_block=self.from_block)
-        elif self.event_type == "updated":
-            contract_event = self.contract.events[UPDATED_EVENT]
-            self._filter = contract_event.create_filter(from_block=self.from_block)
-        elif self.event_type == "extended":
-            contract_event = self.contract.events[EXTENDED_EVENT]
+        if self.event_type in EVENTS.keys():
+            event_name = EVENTS[self.event_type]
+            contract_event = self.contract.events[event_name]
             self._filter = contract_event.create_filter(from_block=self.from_block)
         else:
             raise NotImplementedError(
@@ -204,6 +203,12 @@ def _process_event(self, event_data: EventData) -> None:
                 cast(ExtendCallback, self.callback), extend_event, tx_hash
             )
 
+        elif self.event_type == "deleted":
+            delete_event = DeleteEvent(entity_key=entity_key)
+            self._trigger_callback(
+                cast(DeleteCallback, self.callback), delete_event, tx_hash
+            )
+
         else:
             logger.warning(f"Unknown event type: {self.event_type}")
 
@@ -224,8 +229,8 @@ def _extract_tx_hash(self, event_data: EventData) -> TxHash:
 
     def _trigger_callback(
         self,
-        callback: CreateCallback | UpdateCallback | ExtendCallback,
-        event: CreateEvent | UpdateEvent | ExtendEvent,
+        callback: CreateCallback | UpdateCallback | ExtendCallback | DeleteCallback,
+        event: CreateEvent | UpdateEvent | ExtendEvent | DeleteEvent,
         tx_hash: TxHash,
     ) -> None:
         """

src/arkiv/module.py

@@ -449,6 +449,26 @@ def watch_entity_extended(
             "extended", callback, from_block=from_block, auto_start=auto_start
         )
 
+    def watch_entity_deleted(
+        self,
+        callback: ExtendCallback,
+        *,
+        from_block: str | int = "latest",
+        auto_start: bool = True,
+    ) -> EventFilter:
+        """
+        Watch for entity deletion events.
+
+        Creates an event filter that monitors entity deletion events. The
+        callback receives (DeleteEvent, TxHash) for each deleted entity.
+
+        See `_watch_entity_event` for detailed documentation on parameters, return
+        value, error handling, and usage examples.
+        """
+        return self._watch_entity_event(
+            "deleted", callback, from_block=from_block, auto_start=auto_start
+        )
+
     def cleanup_filters(self) -> None:
         """
         Stop and uninstall all active event filters.
@@ -494,10 +514,10 @@ def _watch_entity_event(
         occurs, receiving details about the event and the transaction hash.
 
         Args:
-            event_type: Type of event to watch for ("created", "updated", "extended")
+            event_type: Type of event to watch for ("created", "updated", "extended", "deleted")
             callback: Function to call when an event is detected.
                      Receives (Event, TxHash) as arguments where Event is one of:
-                     CreateEvent, UpdateEvent, or ExtendEvent depending on event_type.
+                     CreateEvent, UpdateEvent, ExtendEvent, or DeleteEvent depending on event_type.
             from_block: Starting block for the filter. Can be:
                        - "latest": Only watch for new events (default)
                        - Block number (int): Watch from a specific historical block