add TxHash type, refactorings

Author: Matthias Zimmermann

src/arkiv/module.py

@@ -4,8 +4,7 @@
 import logging
 from typing import TYPE_CHECKING, Any
 
-from eth_typing import ChecksumAddress
-from hexbytes import HexBytes
+from eth_typing import ChecksumAddress, HexStr
 from web3 import Web3
 from web3.types import TxParams, TxReceipt
 
@@ -21,6 +20,7 @@
     EntityKey,
     Operations,
     TransactionReceipt,
+    TxHash,
 )
 from .utils import merge_annotations, to_receipt, to_tx_params
 
@@ -54,13 +54,44 @@ def is_available(self) -> bool:
         """Check if Arkiv functionality is available."""
         return True
 
+    def execute(
+        self, operations: Operations, tx_params: TxParams | None = None
+    ) -> TransactionReceipt:
+        """
+        Execute operations on the Arkiv storage contract.
+
+        Args:
+            operations: Operations to execute (creates, updates, deletes, extensions)
+            tx_params: Optional additional transaction parameters
+
+        Returns:
+            TransactionReceipt with details of all operations executed
+        """
+        # Convert to transaction parameters and send
+        client: Arkiv = self.client
+        tx_params = to_tx_params(operations, tx_params)
+        tx_hash_bytes = client.eth.send_transaction(tx_params)
+        tx_hash = TxHash(HexStr(tx_hash_bytes.to_0x_hex()))
+
+        tx_receipt: TxReceipt = client.eth.wait_for_transaction_receipt(tx_hash)
+        tx_status: int = tx_receipt["status"]
+        if tx_status != TX_SUCCESS:
+            raise RuntimeError(f"Transaction failed with status {tx_status}")
+
+        # Parse and return receipt
+        receipt: TransactionReceipt = to_receipt(
+            client.arkiv.contract, tx_hash, tx_receipt
+        )
+        logger.info(f"Arkiv receipt: {receipt}")
+        return receipt
+
     def create_entity(
         self,
         payload: bytes | None = None,
         annotations: Annotations | None = None,
         btl: int = 0,
         tx_params: TxParams | None = None,
-    ) -> tuple[EntityKey, HexBytes]:
+    ) -> tuple[EntityKey, TxHash]:
         """
         Create a new entity on the Arkiv storage contract.
 
@@ -71,7 +102,7 @@ def create_entity(
             tx_params: Optional additional transaction parameters
 
         Returns:
-            Transaction hash of the create operation
+            The entity key and transaction hash of the create operation
         """
         # Check and set defaults
         if not payload:
@@ -82,30 +113,49 @@ def create_entity(
         # Create the operation
         create_op = CreateOp(payload=payload, annotations=annotations, btl=btl)
 
-        # Wrap in Operations container
+        # Wrap in Operations container and execute
         operations = Operations(creates=[create_op])
+        receipt = self.execute(operations, tx_params)
 
-        # Convert to transaction parameters and send
-        client: Arkiv = self.client
-        tx_params = to_tx_params(operations, tx_params)
-        tx_hash = client.eth.send_transaction(tx_params)
-
-        tx_receipt: TxReceipt = client.eth.wait_for_transaction_receipt(tx_hash)
-        tx_status: int = tx_receipt["status"]
-        if tx_status != TX_SUCCESS:
-            raise RuntimeError(f"Transaction failed with status {tx_status}")
-
-        # assert that receipt has a creates field
-        receipt: TransactionReceipt = to_receipt(
-            client.arkiv.contract, tx_hash, tx_receipt
-        )
+        # Verify we got at least one create
         creates = receipt.creates
         if len(creates) == 0:
             raise RuntimeError("Receipt should have at least one entry in 'creates'")
 
         create = creates[0]
         entity_key = create.entity_key
-        return entity_key, tx_hash
+        return entity_key, receipt.tx_hash
+
+    def create_entities(
+        self,
+        create_ops: list[CreateOp],
+        tx_params: TxParams | None = None,
+    ) -> tuple[list[EntityKey], TxHash]:
+        """
+        Create multiple entities in a single transaction (bulk create).
+
+        Args:
+            create_ops: List of CreateOp objects to create
+            tx_params: Optional additional transaction parameters
+
+        Returns:
+            An array of all created entity keys and transaction hash of the operation
+        """
+        if not create_ops or len(create_ops) == 0:
+            raise ValueError("create_ops must contain at least one CreateOp")
+
+        # Wrap in Operations container and execute
+        operations = Operations(creates=create_ops)
+        receipt = self.execute(operations, tx_params)
+
+        # Verify all creates succeeded
+        if len(receipt.creates) != len(create_ops):
+            raise RuntimeError(
+                f"Expected {len(create_ops)} creates in receipt, got {len(receipt.creates)}"
+            )
+
+        entity_keys = [create.entity_key for create in receipt.creates]
+        return entity_keys, receipt.tx_hash
 
     def get_entity(self, entity_key: EntityKey, fields: int = ALL) -> Entity:
         """

src/arkiv/types.py

@@ -5,7 +5,6 @@
 from typing import NewType
 
 from eth_typing import ChecksumAddress, HexStr
-from hexbytes import HexBytes
 from web3.datastructures import AttributeDict
 
 # Field bitmask values to specify which entity fields are populated
@@ -14,6 +13,8 @@
 METADATA = 4
 ALL = PAYLOAD | ANNOTATIONS | METADATA
 
+# Transaction hash type
+TxHash = NewType("TxHash", HexStr)
 
 # Unique key for all entities
 EntityKey = NewType("EntityKey", HexStr)
@@ -145,7 +146,7 @@ class DeleteReceipt:
 class TransactionReceipt:
     """The return type of a transaction."""
 
-    tx_hash: HexBytes
+    tx_hash: TxHash
     creates: Sequence[CreateReceipt]
     updates: Sequence[UpdateReceipt]
     extensions: Sequence[ExtendReceipt]

src/arkiv/utils.py

@@ -26,6 +26,7 @@
     StringAnnotations,
     StringAnnotationsRlp,
     TransactionReceipt,
+    TxHash,
     UpdateReceipt,
 )
 
@@ -107,12 +108,36 @@ def to_tx_params(
     return tx_params
 
 
+def to_hex_bytes(tx_hash: TxHash) -> HexBytes:
+    """
+    Convert a TxHash to HexBytes for Web3.py methods that require it.
+
+    Args:
+        tx_hash: Transaction hash as TxHash
+
+    Returns:
+        Transaction hash as HexBytes with utility methods
+
+    Example:
+        tx_hash: TxHash = client.arkiv.create_entity(...)
+        hex_bytes = to_hex_bytes(tx_hash)
+    """
+    return HexBytes(tx_hash)
+
+
 def to_receipt(
-    contract_: Contract, tx_hash: HexBytes, tx_receipt: TxReceipt
+    contract_: Contract, tx_hash_: TxHash | HexBytes, tx_receipt: TxReceipt
 ) -> TransactionReceipt:
     """Convert a tx hash and a raw transaction receipt to a typed receipt."""
     logger.debug(f"Transaction receipt: {tx_receipt}")
 
+    # normalize tx_hash to TxHash if needed
+    tx_hash: TxHash = (
+        tx_hash_
+        if isinstance(tx_hash_, str)
+        else TxHash(HexStr(HexBytes(tx_hash_).to_0x_hex()))
+    )
+
     # Initialize receipt with tx hash and empty receipt collections
     creates: list[CreateReceipt] = []
     updates: list[UpdateReceipt] = []
@@ -260,7 +285,7 @@ def split_annotations(
             else:
                 string_annotations.append((key, value))
 
-    logger.info(
+    logger.debug(
         f"Split annotations into {string_annotations} and {numeric_annotations}"
     )
     return string_annotations, numeric_annotations

tests/test_entity_create.py

@@ -7,22 +7,25 @@
 
 from arkiv.client import Arkiv
 from arkiv.contract import STORAGE_ADDRESS
-from arkiv.types import Annotations, CreateOp, Operations
+from arkiv.types import Annotations, CreateOp, Operations, TxHash
 from arkiv.utils import check_entity_key, to_receipt, to_tx_params
 
 logger = logging.getLogger(__name__)
 
 TX_SUCCESS = 1
 
 
-def check_tx_hash(label: str, tx_hash: HexBytes) -> None:
+def check_tx_hash(label: str, tx_hash: TxHash) -> None:
     """Check transaction hash validity."""
-    logger.info(f"{label}: Checking transaction hash {tx_hash.to_0x_hex()}")
+    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, HexBytes), (
-        f"{label}: Transaction hash should be HexBytes"
+    assert isinstance(tx_hash, str), (
+        f"{label}: Transaction hash should be a string (TxHash)"
     )
-    assert len(tx_hash) == 32, f"{label}: Transaction hash should be 32 bytes long"
+    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:
@@ -171,3 +174,68 @@ def test_create_entity_simple(self, arkiv_client_http: Arkiv) -> None:
             f"{label}: Entity expiration block should be in the future"
         )
         logger.info(f"{label}: Entity creation and retrieval successful")
+
+    def test_create_entities_bulk(self, arkiv_client_http: Arkiv) -> None:
+        """Test create_entities for bulk entity creation."""
+        # Create multiple CreateOp objects
+        create_ops = [
+            CreateOp(
+                payload=b"Entity 1",
+                annotations=Annotations({"type": "bulk", "index": 1}),
+                btl=100,
+            ),
+            CreateOp(
+                payload=b"Entity 2",
+                annotations=Annotations({"type": "bulk", "index": 2}),
+                btl=100,
+            ),
+            CreateOp(
+                payload=b"Entity 3",
+                annotations=Annotations({"type": "bulk", "index": 3}),
+                btl=100,
+            ),
+        ]
+
+        # Call create_entities
+        entity_keys, tx_hash = arkiv_client_http.arkiv.create_entities(create_ops)
+
+        label = "create_entities"
+        logger.info(f"{label}: Entity keys: {entity_keys}, tx_hash: {tx_hash}")
+
+        # Verify transaction hash
+        assert tx_hash is not None, f"{label}: Transaction hash should not be None"
+        check_tx_hash(label, tx_hash)
+
+        # Verify all entities were created
+        assert len(entity_keys) == 3, f"{label}: Should have 3 created entities"
+
+        # Verify each entity can be retrieved and has correct data
+        for i, entity_key in enumerate(entity_keys):
+            check_entity_key(entity_key, f"{label} entity {i + 1}")
+
+            entity = arkiv_client_http.arkiv.get_entity(entity_key)
+            logger.info(f"{label}: Retrieved entity {i + 1}: {entity}")
+
+            expected_payload = f"Entity {i + 1}".encode()
+            expected_annotations = Annotations({"type": "bulk", "index": i + 1})
+
+            assert entity.payload == expected_payload, (
+                f"{label}: Entity {i + 1} payload should match"
+            )
+            assert entity.annotations == expected_annotations, (
+                f"{label}: Entity {i + 1} annotations should match"
+            )
+            assert entity.owner == arkiv_client_http.eth.default_account, (
+                f"{label}: Entity {i + 1} owner should match transaction sender"
+            )
+
+        logger.info(f"{label}: Bulk entity creation successful")
+
+    def test_create_entities_empty_list_raises(self, arkiv_client_http: Arkiv) -> None:
+        """Test that create_entities raises ValueError for empty list."""
+        import pytest
+
+        with pytest.raises(
+            ValueError, match="create_ops must contain at least one CreateOp"
+        ):
+            arkiv_client_http.arkiv.create_entities([])

tests/test_entity_create_parallel.py

@@ -88,7 +88,7 @@ def client_task(client: Arkiv, client_idx: int, num_entities: int) -> list[Entit
             entity_key, tx_hash = client.arkiv.create_entity(
                 payload=payload, annotations=annotations, btl=btl
             )
-            logger.info(f"Entity creation TX[{client_idx}][{j}]: {tx_hash.to_0x_hex()}")
+            logger.info(f"Entity creation TX[{client_idx}][{j}]: {tx_hash}")
             created.append(entity_key)
 
             # entity tx successful, increase counter