feat: add update_entity to AsyncArkivModule

Author: matthiaszimmermann

src/arkiv/module_async.py

@@ -22,6 +22,7 @@
     Operations,
     TransactionReceipt,
     TxHash,
+    UpdateOp,
 )
 from .utils import merge_annotations, to_tx_params
 
@@ -101,6 +102,50 @@ async def create_entity(
         entity_key = create.entity_key
         return entity_key, receipt.tx_hash
 
+    async def update_entity(
+        self,
+        entity_key: EntityKey,
+        payload: bytes | None = None,
+        annotations: Annotations | None = None,
+        btl: int | None = None,
+        tx_params: TxParams | None = None,
+    ) -> TxHash:
+        """
+        Update an existing entity on the Arkiv storage contract (async).
+
+        Args:
+            entity_key: The entity key of the entity to update
+            payload: Optional new data payload for the entity, existing payload will be replaced
+            annotations: Optional new key-value annotations, existing annotations will be replaced
+            btl: Blocks to live (default: self.btl_default, ~30 minutes with 2s blocks)
+            tx_params: Optional additional transaction parameters
+
+        Returns:
+            Transaction hash of the update operation
+        """
+        # Create the update operation
+        payload, annotations, btl = self._check_and_set_argument_defaults(
+            payload, annotations, btl
+        )
+        update_op = UpdateOp(
+            entity_key=entity_key,
+            payload=payload,
+            annotations=annotations,
+            btl=btl,
+        )
+
+        # Wrap in Operations container and execute
+        operations = Operations(updates=[update_op])
+        receipt = await self.execute(operations, tx_params)
+
+        # Verify the update succeeded
+        if len(receipt.updates) != 1:
+            raise RuntimeError(
+                f"Expected 1 update in receipt, got {len(receipt.updates)}"
+            )
+
+        return receipt.tx_hash
+
     async def entity_exists(self, entity_key: EntityKey) -> bool:
         """
         Check if an entity exists storage (async).

tests/test_async_entity_update.py

@@ -0,0 +1,83 @@
+"""Tests for async entity update functionality in AsyncArkivModule."""
+
+import logging
+
+import pytest
+
+from arkiv import AsyncArkiv
+from arkiv.types import Annotations
+from arkiv.utils import check_entity_key
+
+from .utils import check_tx_hash
+
+logger = logging.getLogger(__name__)
+
+
+class TestAsyncEntityUpdate:
+    """Test cases for async update_entity function."""
+
+    @pytest.mark.asyncio
+    async def test_async_update_entity_basic(
+        self, async_arkiv_client_http: AsyncArkiv
+    ) -> None:
+        """Test updating an entity with async client."""
+        # Create entity
+        original_payload = b"Original payload"
+        original_annotations = Annotations({"status": "initial", "version": 1})
+        entity_key, _tx_hash = await async_arkiv_client_http.arkiv.create_entity(
+            payload=original_payload, annotations=original_annotations, btl=100
+        )
+
+        # Update entity
+        new_payload = b"Updated payload"
+        new_annotations = Annotations({"status": "updated", "version": 2})
+        update_tx_hash = await async_arkiv_client_http.arkiv.update_entity(
+            entity_key=entity_key,
+            payload=new_payload,
+            annotations=new_annotations,
+            btl=150,
+        )
+
+        # Verify update transaction hash
+        check_tx_hash("test_async_update_entity_basic", update_tx_hash)
+
+        # Verify entity was updated
+        entity = await async_arkiv_client_http.arkiv.get_entity(entity_key)
+        assert entity.payload == new_payload, "Payload should be updated"
+        assert entity.annotations == new_annotations, "Annotations should be updated"
+
+        logger.info(f"Updated async entity: {entity_key} (tx: {update_tx_hash})")
+
+    @pytest.mark.asyncio
+    async def test_async_update_entities_sequentially(
+        self, async_arkiv_client_http: AsyncArkiv
+    ) -> None:
+        """Test updating multiple entities sequentially."""
+        # Create multiple entities
+        entity_keys = []
+        for i in range(3):
+            entity_key, _tx_hash = await async_arkiv_client_http.arkiv.create_entity(
+                payload=f"Entity {i}".encode(),
+                annotations=Annotations({"index": i, "version": 1}),
+            )
+            entity_keys.append(entity_key)
+
+        # Update all entities sequentially
+        for i, entity_key in enumerate(entity_keys):
+            update_tx_hash = await async_arkiv_client_http.arkiv.update_entity(
+                entity_key=entity_key,
+                payload=f"Updated entity {i}".encode(),
+                annotations=Annotations({"index": i, "version": 2}),
+            )
+            # Verify individual entity_key and tx_hash formats
+            check_entity_key(entity_key, f"test_async_update_entities_sequentially_{i}")
+            check_tx_hash(f"test_async_update_entities_sequentially_{i}", update_tx_hash)
+            logger.info(f"Updated entity {i + 1}/3: {entity_key}")
+
+        # Verify all updates
+        for i, entity_key in enumerate(entity_keys):
+            entity = await async_arkiv_client_http.arkiv.get_entity(entity_key)
+            assert entity.payload == f"Updated entity {i}".encode()
+            assert entity.annotations == Annotations({"index": i, "version": 2})
+
+        logger.info("Successfully updated 3 entities sequentially")

tests/test_entity_create.py

@@ -7,27 +7,16 @@
 
 from arkiv.client import Arkiv
 from arkiv.contract import STORAGE_ADDRESS
-from arkiv.types import Annotations, CreateOp, Operations, TxHash
+from arkiv.types import Annotations, CreateOp, Operations
 from arkiv.utils import check_entity_key, to_receipt, to_tx_params
 
+from .utils import check_tx_hash
+
 logger = logging.getLogger(__name__)
 
 TX_SUCCESS = 1
 
 
-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"
-
-
 class TestEntityCreate:
     """Test cases for create_entity function."""