add arkiv.delete_entity functionality

Author: Matthias Zimmermann

src/arkiv/module.py

@@ -18,6 +18,7 @@
     PAYLOAD,
     Annotations,
     CreateOp,
+    DeleteOp,
     Entity,
     EntityKey,
     Operations,
@@ -53,7 +54,7 @@ def __init__(self, client: "Arkiv") -> None:
             logger.debug(f"Entity event {event.topic}: {event.signature}")
 
     def is_available(self) -> bool:
-        """Check if Arkiv functionality is available."""
+        """Check if Arkiv functionality is available. Should always be true for Arkiv clients."""
         return True
 
     def execute(
@@ -159,22 +160,35 @@ def create_entities(
         entity_keys = [create.entity_key for create in receipt.creates]
         return entity_keys, receipt.tx_hash
 
-    def entity_exists(self, entity_key: EntityKey) -> bool:
+    def delete_entity(
+        self,
+        entity_key: EntityKey,
+        tx_params: TxParams | None = None,
+    ) -> TxHash:
         """
-        Check if an entity exists storage.
+        Delete an entity from the Arkiv storage contract.
 
         Args:
-            entity_key: The entity key to check
+            entity_key: The entity key to delete
+            tx_params: Optional additional transaction parameters
 
         Returns:
-            True if the entity exists, False otherwise
+            Transaction hash of the delete operation
         """
-        try:
-            self.client.eth.get_entity_metadata(entity_key)  # type: ignore[attr-defined]
-            return True
+        # Create the delete operation
+        delete_op = DeleteOp(entity_key=entity_key)
 
-        except Exception:
-            return False
+        # Wrap in Operations container and execute
+        operations = Operations(deletes=[delete_op])
+        receipt = self.execute(operations, tx_params)
+
+        # Verify the delete succeeded
+        if len(receipt.deletes) != 1:
+            raise RuntimeError(
+                f"Expected 1 delete in receipt, got {len(receipt.deletes)}"
+            )
+
+        return receipt.tx_hash
 
     def transfer_eth(
         self,
@@ -216,6 +230,23 @@ def transfer_eth(
 
         return tx_hash
 
+    def entity_exists(self, entity_key: EntityKey) -> bool:
+        """
+        Check if an entity exists storage.
+
+        Args:
+            entity_key: The entity key to check
+
+        Returns:
+            True if the entity exists, False otherwise
+        """
+        try:
+            self.client.eth.get_entity_metadata(entity_key)  # type: ignore[attr-defined]
+            return True
+
+        except Exception:
+            return False
+
     def get_entity(self, entity_key: EntityKey, fields: int = ALL) -> Entity:
         """
         Get an entity by its entity key.

src/arkiv/utils.py

@@ -169,17 +169,18 @@ def to_receipt(
             event_name = event_data["event"]
 
             entity_key: EntityKey = to_entity_key(event_args["entityKey"])
-            expiration_block: int = event_args["expirationBlock"]
 
             match event_name:
                 case contract.CREATED_EVENT:
+                    expiration_block: int = event_args["expirationBlock"]
                     creates.append(
                         CreateReceipt(
                             entity_key=entity_key,
                             expiration_block=expiration_block,
                         )
                     )
                 case contract.UPDATED_EVENT:
+                    expiration_block = event_args["expirationBlock"]
                     updates.append(
                         UpdateReceipt(
                             entity_key=entity_key,
@@ -254,12 +255,7 @@ def rlp_encode_transaction(tx: Operations) -> bytes:
             for element in tx.updates
         ],
         # Delete
-        [
-            [
-                entity_key_to_bytes(element.entity_key),
-            ]
-            for element in tx.deletes
-        ],
+        [entity_key_to_bytes(element.entity_key) for element in tx.deletes],
         # Extend
         [
             [

tests/test_arkiv_create.py

@@ -21,9 +21,9 @@ class TestArkivClientCreation:
 
     def test_create_arkiv_without_provider(self) -> None:
         """Test creating Arkiv client without provider."""
-        client = Arkiv()
-        _assert_arkiv_client_properties(client, None, "Without Provider")
-        logger.info("Created Arkiv client without provider")
+        with Arkiv() as client:
+            _assert_arkiv_client_properties(client, None, "Without Provider")
+            logger.info("Created Arkiv client without provider")
 
     def test_create_arkiv_with_http_provider(self, arkiv_node) -> None:
         """Test creating Arkiv client with HTTP provider."""
@@ -136,14 +136,14 @@ def test_repr_disconnected(self) -> None:
 
     def test_repr_connected_with_defaults(self) -> None:
         """Test repr of connected client with defaults."""
-        client = Arkiv()
-        repr_str = repr(client)
+        with Arkiv() as client:
+            repr_str = repr(client)
 
-        assert isinstance(repr_str, str), "Should return string"
-        assert "Arkiv" in repr_str, "Should contain class name"
-        assert "connected=True" in repr_str, "Should show connection status"
+            assert isinstance(repr_str, str), "Should return string"
+            assert "Arkiv" in repr_str, "Should contain class name"
+            assert "connected=True" in repr_str, "Should show connection status"
 
-        logger.info(f"Connected client repr: {repr_str}")
+            logger.info(f"Connected client repr: {repr_str}")
 
     def test_repr_connected_with_provider(self, arkiv_node) -> None:
         """Test repr of connected client."""

tests/test_entity_delete.py

@@ -0,0 +1,202 @@
+"""Tests for entity deletion functionality in ArkivModule."""
+
+import logging
+
+import pytest
+
+from arkiv.client import Arkiv
+from arkiv.types import Annotations, CreateOp, DeleteOp, Operations
+
+from .utils import check_tx_hash
+
+logger = logging.getLogger(__name__)
+
+
+class TestEntityDelete:
+    """Test cases for delete_entity function."""
+
+    def test_delete_entity_simple(self, arkiv_client_http: Arkiv) -> None:
+        """Test deleting a single entity."""
+        # First, create an entity to delete
+        payload = b"Test entity for deletion"
+        annotations: Annotations = Annotations({"type": "test", "purpose": "deletion"})
+        btl = 100
+
+        entity_key, _ = arkiv_client_http.arkiv.create_entity(
+            payload=payload, annotations=annotations, btl=btl
+        )
+
+        logger.info(f"Created entity {entity_key} for deletion test")
+
+        # Verify the entity exists
+        assert arkiv_client_http.arkiv.entity_exists(entity_key), (
+            "Entity should exist after creation"
+        )
+
+        # Delete the entity
+        delete_tx_hash = arkiv_client_http.arkiv.delete_entity(entity_key)
+
+        label = "delete_entity"
+        check_tx_hash(label, delete_tx_hash)
+        logger.info(f"{label}: Deleted entity {entity_key}, tx_hash: {delete_tx_hash}")
+
+        # Verify the entity no longer exists
+        assert not arkiv_client_http.arkiv.entity_exists(entity_key), (
+            "Entity should not exist after deletion"
+        )
+
+        logger.info(f"{label}: Entity deletion successful")
+
+    def test_delete_multiple_entities_sequentially(
+        self, arkiv_client_http: Arkiv
+    ) -> None:
+        """Test deleting multiple entities one by one."""
+        # Create multiple entities
+        entity_keys = []
+        for i in range(3):
+            payload = f"Entity {i} for sequential deletion".encode()
+            annotations: Annotations = Annotations({"index": i, "batch": "sequential"})
+            entity_key, _ = arkiv_client_http.arkiv.create_entity(
+                payload=payload, annotations=annotations, btl=150
+            )
+            entity_keys.append(entity_key)
+
+        logger.info(f"Created {len(entity_keys)} entities for sequential deletion")
+
+        # Verify all entities exist
+        for entity_key in entity_keys:
+            assert arkiv_client_http.arkiv.entity_exists(entity_key), (
+                f"Entity {entity_key} should exist before deletion"
+            )
+
+        # Delete entities one by one
+        for i, entity_key in enumerate(entity_keys):
+            delete_tx_hash = arkiv_client_http.arkiv.delete_entity(entity_key)
+            check_tx_hash(f"delete_entity_{i}", delete_tx_hash)
+            logger.info(f"Deleted entity {i + 1}/{len(entity_keys)}: {entity_key}")
+
+            # Verify this entity is deleted
+            assert not arkiv_client_http.arkiv.entity_exists(entity_key), (
+                f"Entity {entity_key} should not exist after deletion"
+            )
+
+        # Verify all entities are gone
+        for entity_key in entity_keys:
+            assert not arkiv_client_http.arkiv.entity_exists(entity_key), (
+                f"Entity {entity_key} should still be deleted"
+            )
+
+        logger.info("Sequential deletion of multiple entities successful")
+
+    def test_delete_entity_execute_bulk(self, arkiv_client_http: Arkiv) -> None:
+        """Test deleting entities that were created in bulk."""
+        # Create entities in bulk
+        create_ops = [
+            CreateOp(
+                payload=f"Bulk entity {i}".encode(),
+                annotations=Annotations({"batch": "bulk", "index": i}),
+                btl=100,
+            )
+            for i in range(3)
+        ]
+
+        entity_keys, _ = arkiv_client_http.arkiv.create_entities(create_ops)
+
+        logger.info(f"Created {len(entity_keys)} entities in bulk")
+
+        # Verify all exist
+        for entity_key in entity_keys:
+            assert arkiv_client_http.arkiv.entity_exists(entity_key), (
+                "Bulk-created entity should exist"
+            )
+
+        # Bulk delete
+        # Wrap in Operations container and execute
+        delete_ops = [DeleteOp(entity_key=key) for key in entity_keys]
+        operations = Operations(deletes=delete_ops)
+        receipt = arkiv_client_http.arkiv.execute(operations)
+
+        # Check transaction hash of bulk delete
+        check_tx_hash("delete_bulk_entity", receipt.tx_hash)
+
+        # Verify all deletes succeeded
+        if len(receipt.deletes) != len(delete_ops):
+            raise RuntimeError(
+                f"Expected {len(delete_ops)} deletes in receipt, got {len(receipt.deletes)}"
+            )
+
+        # Verify all are deleted
+        for entity_key in entity_keys:
+            assert not arkiv_client_http.arkiv.entity_exists(entity_key), (
+                "Bulk-created entity should be deleted"
+            )
+
+        logger.info("Deletion of bulk-created entities successful")
+
+    def test_delete_nonexistent_entity_behavior(self, arkiv_client_http: Arkiv) -> None:
+        """Test that deleting a non-existent entity raises an exception."""
+        from eth_typing import HexStr
+        from web3.exceptions import Web3RPCError
+
+        from arkiv.types import EntityKey
+
+        # Create a fake entity key (should not exist)
+        fake_entity_key = EntityKey(
+            HexStr("0x0000000000000000000000000000000000000000000000000000000000000001")
+        )
+
+        # Verify it doesn't exist
+        assert not arkiv_client_http.arkiv.entity_exists(fake_entity_key), (
+            "Fake entity should not exist"
+        )
+
+        # Attempt to delete should raise a Web3RPCError
+        with pytest.raises(Web3RPCError) as exc_info:
+            logger.info(
+                f"Attempting to delete non-existent entity {fake_entity_key} -> {exc_info}"
+            )
+            arkiv_client_http.arkiv.delete_entity(fake_entity_key)
+
+        # Verify the error message indicates entity not found
+        error_message = str(exc_info.value)
+        assert "entity" in error_message.lower(), "Error message should mention entity"
+        assert "not found" in error_message.lower(), (
+            "Error message should indicate entity not found"
+        )
+
+        logger.info(
+            f"Delete of non-existent entity correctly raised {type(exc_info.value).__name__}"
+        )
+
+    def test_delete_entity_twice(self, arkiv_client_http: Arkiv) -> None:
+        """Test that deleting the same entity twice raises an exception."""
+        from web3.exceptions import Web3RPCError
+
+        # Create an entity
+        entity_key, _ = arkiv_client_http.arkiv.create_entity(
+            payload=b"Entity to delete twice", btl=100
+        )
+
+        # First deletion
+        delete_tx_hash_1 = arkiv_client_http.arkiv.delete_entity(entity_key)
+        check_tx_hash("first_delete", delete_tx_hash_1)
+
+        # Verify it's deleted
+        assert not arkiv_client_http.arkiv.entity_exists(entity_key), (
+            "Entity should be deleted after first deletion"
+        )
+
+        # Second deletion attempt should raise a Web3RPCError
+        with pytest.raises(Web3RPCError) as exc_info:
+            arkiv_client_http.arkiv.delete_entity(entity_key)
+
+        # Verify the error message indicates entity not found
+        error_message = str(exc_info.value)
+        assert "entity" in error_message.lower(), "Error message should mention entity"
+        assert "not found" in error_message.lower(), (
+            "Error message should indicate entity not found"
+        )
+
+        logger.info(
+            f"Second delete of same entity correctly raised {type(exc_info.value).__name__}"
+        )

tests/utils.py

@@ -3,13 +3,27 @@
 from pathlib import Path
 
 from arkiv.account import NamedAccount
+from arkiv.types import TxHash
 
 WALLET_FILE_ENV_PREFIX = "WALLET_FILE"
 WALLET_PASSWORD_ENV_PREFIX = "WALLET_PASSWORD"
 
 logger = logging.getLogger(__name__)
 
 
+def check_tx_hash(label: str, tx_hash: TxHash) -> None:
+    """Check transaction hash validity."""
+    logger.info(f"{label}: Checking transaction hash {tx_hash}")
+    assert tx_hash is not None, f"{label}: Transaction hash should not be None"
+    assert isinstance(tx_hash, str), (
+        f"{label}: Transaction hash should be a string (TxHash)"
+    )
+    assert len(tx_hash) == 66, (
+        f"{label}: Transaction hash should be 66 characters long (0x + 64 hex)"
+    )
+    assert tx_hash.startswith("0x"), f"{label}: Transaction hash should start with 0x"
+
+
 def create_account(index: int, name: str) -> NamedAccount:
     """Create a named account from env vars or generate a new one."""
     wallet_file = os.getenv(f"{WALLET_FILE_ENV_PREFIX}_{index}")