feat: complete switch to expires_in, add to_blocks, and to_seconds utility functions

Author: Matthias Zimmermann

README.md

@@ -44,12 +44,9 @@ entity_key, receipt = client.arkiv.create_entity(
     expires_in=1000
 )
 
-# Check and print entity key
-exists = client.arkiv.entity_exists(entity_key)
-print(f"Created entity: {entity_key} (exists={exists}), creation TX: {receipt.tx_hash}")
-
 # Get individual entity and print its details
 entity = client.arkiv.get_entity(entity_key)
+print(f"Creation TX: {receipt.tx_hash}")
 print(f"Entity: {entity}")
 
 # Clean up - delete entity
@@ -148,9 +145,9 @@ provider = ProviderBuilder().kaolin().build()
 client = Arkiv(provider, account=bob)
 
 # Additional builder examples
+provider_custom = ProviderBuilder().custom("https://mendoza.hoodi.arkiv.network/rpc").build()
 provider_container = ProviderBuilder().node().build()
 provider_kaolin_ws = ProviderBuilder().kaolin().ws().build()
-provider_custom = ProviderBuilder().custom("https://my-rpc.io").build()
 ```
 
 ### Query Iterator

src/arkiv/module_base.py

@@ -76,6 +76,9 @@ class ArkivModuleBase(Generic[ClientT]):
     EXPIRES_IN_DEFAULT = (
         1000  # Default expiration time for created entities (~30 mins with 2s blocks)
     )
+    CONTENT_TYPE_DEFAULT = (
+        "application/octet-stream"  # Default content type for payloads
+    )
 
     def __init__(
         self, client: ClientT, expires_in_default: int = EXPIRES_IN_DEFAULT
@@ -453,15 +456,35 @@ def query_entities_page(
         """
         raise NotImplementedError("Subclasses must implement query_entities()")
 
+    @staticmethod
+    def to_seconds(
+        seconds: int = 0, minutes: int = 0, hours: int = 0, days: int = 0
+    ) -> int:
+        """
+        Convert a time duration to number of seconds.
+
+        Useful for calculating expires_in parameters based on desired entity lifetime.
+
+        Args:
+            seconds: Number of seconds
+            minutes: Number of minutes
+            hours: Number of hours
+            days: Number of days
+
+        Returns:
+            Total number of seconds corresponding to the time duration
+        """
+        from arkiv.utils import to_seconds as _to_seconds
+
+        return _to_seconds(seconds, minutes, hours, days)
+
+    @staticmethod
     def to_blocks(
-        self, seconds: int = 0, minutes: int = 0, hours: int = 0, days: int = 0
+        seconds: int = 0, minutes: int = 0, hours: int = 0, days: int = 0
     ) -> int:
         """
         Convert a time duration to number of blocks.
 
-        Useful for calculating expires_in parameters based on
-        desired entity lifetime.
-
         Args:
             seconds: Number of seconds
             minutes: Number of minutes
@@ -471,8 +494,9 @@ def to_blocks(
         Returns:
             Number of blocks corresponding to the time duration
         """
-        total_seconds = seconds + minutes * 60 + hours * 3600 + days * 86400
-        return total_seconds // self.BLOCK_TIME_SECONDS
+        from arkiv.utils import to_blocks as _to_blocks
+
+        return _to_blocks(seconds=seconds, minutes=minutes, hours=hours, days=days)
 
     # NOTE: Other public API methods (iterate_entities, watch_entity_*, etc.) could also
     # be defined here, but they have more significant differences between sync/async

src/arkiv/utils.py

@@ -65,14 +65,53 @@
     UpdateOp,
 )
 
-CONTENT_TYPE_DEFAULT = "application/octet-stream"
-EXPIRES_IN_DEFAULT = (
-    1000  # Default blocks to live for created entities (~30 mins with 2s blocks)
-)
-
 logger = logging.getLogger(__name__)
 
 
+def to_seconds(
+    seconds: int = 0, minutes: int = 0, hours: int = 0, days: int = 0
+) -> int:
+    """
+    Convert a time duration to number of seconds.
+
+    Useful for calculating expires_in parameters based on
+    desired entity lifetime.
+
+    Args:
+        seconds: Number of seconds
+        minutes: Number of minutes
+        hours: Number of hours
+        days: Number of days
+
+    Returns:
+        Number of seconds corresponding to the time duration
+    """
+    total_seconds = seconds + minutes * 60 + hours * 3600 + days * 86400
+    return total_seconds
+
+
+def to_blocks(seconds: int = 0, minutes: int = 0, hours: int = 0, days: int = 0) -> int:
+    """
+    Convert a time duration to number of blocks.
+
+    Args:
+        seconds: Number of seconds
+        minutes: Number of minutes
+        hours: Number of hours
+        days: Number of days
+
+    Returns:
+        Number of blocks corresponding to the time duration
+    """
+    # Import here to avoid circular dependency
+    from arkiv.module_base import ArkivModuleBase
+
+    total_seconds = ArkivModuleBase.to_seconds(
+        seconds=seconds, minutes=minutes, hours=hours, days=days
+    )
+    return total_seconds // ArkivModuleBase.BLOCK_TIME_SECONDS
+
+
 def to_entity_key(entity_key_int: int) -> EntityKey:
     hex_value = Web3.to_hex(entity_key_int)
     # ensure lenth is 66 (0x + 64 hex)
@@ -129,11 +168,17 @@ def check_and_set_entity_op_defaults(
 ) -> tuple[bytes, str, Attributes, int]:
     """Check and set defaults for entity management arguments."""
     if expires_in is None:
-        expires_in = EXPIRES_IN_DEFAULT
+        # Import here to avoid circular dependency
+        from arkiv.module_base import ArkivModuleBase
+
+        expires_in = ArkivModuleBase.EXPIRES_IN_DEFAULT
     if not payload:
         payload = b""
     if not content_type:
-        content_type = CONTENT_TYPE_DEFAULT
+        # Import here to avoid circular dependency
+        from arkiv.module_base import ArkivModuleBase
+
+        content_type = ArkivModuleBase.CONTENT_TYPE_DEFAULT
     if not attributes:
         attributes = Attributes({})
 
@@ -710,7 +755,7 @@ def rlp_encode_transaction(tx: Operations) -> bytes:
         # Create
         [
             [
-                element.expires_in,
+                to_blocks(seconds=element.expires_in),
                 element.content_type,
                 element.payload,
                 *split_attributes(element.attributes),
@@ -722,7 +767,7 @@ def rlp_encode_transaction(tx: Operations) -> bytes:
             [
                 entity_key_to_bytes(element.key),
                 element.content_type,
-                element.expires_in,
+                to_blocks(seconds=element.expires_in),
                 element.payload,
                 *split_attributes(element.attributes),
             ]

tests/test_arkiv_fixture.py

@@ -7,6 +7,7 @@
 from arkiv import Arkiv
 from arkiv.account import NamedAccount
 from arkiv.module import ArkivModule
+from arkiv.module_base import ArkivModuleBase
 
 logger = logging.getLogger(__name__)
 
@@ -131,3 +132,42 @@ def test_arkiv_transfer_eth_address(
     )
 
     logger.info("Arkiv ETH transfer between accounts succeeded (to: checksum address)")
+
+
+def test_arkiv_module_base_to_seconds() -> None:
+    """Test ArkivModuleBase.to_seconds static method."""
+    # Test individual units
+    assert ArkivModuleBase.to_seconds(seconds=120) == 120
+    assert ArkivModuleBase.to_seconds(minutes=2) == 120
+    assert ArkivModuleBase.to_seconds(hours=1) == 3600
+    assert ArkivModuleBase.to_seconds(days=1) == 86400
+
+    # Test mixed units
+    result = ArkivModuleBase.to_seconds(days=1, hours=2, minutes=30, seconds=60)
+    assert result == 95460  # 86400 + 7200 + 1800 + 60
+
+    # Test default (no arguments)
+    assert ArkivModuleBase.to_seconds() == 0
+
+    logger.info("ArkivModuleBase.to_seconds() works correctly")
+
+
+def test_arkiv_module_base_to_blocks() -> None:
+    """Test ArkivModuleBase.to_blocks static method."""
+    # Test individual units (with 2 second block time)
+    assert ArkivModuleBase.to_blocks(seconds=120) == 60
+    assert ArkivModuleBase.to_blocks(minutes=2) == 60
+    assert ArkivModuleBase.to_blocks(hours=1) == 1800
+    assert ArkivModuleBase.to_blocks(days=1) == 43200
+
+    # Test mixed units
+    result = ArkivModuleBase.to_blocks(days=1, hours=2, minutes=30, seconds=60)
+    assert result == 47730  # 95460 seconds / 2 = 47730 blocks
+
+    # Test default (no arguments)
+    assert ArkivModuleBase.to_blocks() == 0
+
+    # Test rounding down
+    assert ArkivModuleBase.to_blocks(seconds=125) == 62  # 125 / 2 = 62.5 -> 62
+
+    logger.info("ArkivModuleBase.to_blocks() works correctly")

tests/test_entity_update.py

@@ -373,11 +373,13 @@ def test_update_entity_expires_in_extension(self, arkiv_client_http: Arkiv) -> N
 
         # Get initial expiration
         entity_before = arkiv_client_http.arkiv.get_entity(entity_key)
-        initial_expiration = entity_before.expires_at_block
-        assert initial_expiration is not None, "Entity should have expiration block"
-        logger.info(f"Initial expiration block: {initial_expiration}")
+        initial_expiration_block = entity_before.expires_at_block
+        assert initial_expiration_block is not None, (
+            "Entity should have expiration block"
+        )
+        logger.info(f"Initial expiration block: {initial_expiration_block}")
 
-        # Update with higher expires_in
+        # Update with higher expires_in (in seconds)
         new_expires_in = 200
         update_tx_hash = arkiv_client_http.arkiv.update_entity(
             entity_key,
@@ -387,25 +389,20 @@ def test_update_entity_expires_in_extension(self, arkiv_client_http: Arkiv) -> N
         )
         check_tx_hash("update_expires_in", update_tx_hash)
 
-        # Verify new expiration (expiration extension calculation)
-        assert entity_before.expires_at_block is not None
-        expected = replace(
-            entity_before,
-            expires_at_block=entity_before.expires_at_block
-            - initial_expiration
-            + new_expires_in,
-        )
-        check_entity("update_expires_in", arkiv_client_http, expected)
+        # Get updated entity
+        entity_after = arkiv_client_http.arkiv.get_entity(entity_key)
 
-        # Verify expiration was extended (should be roughly initial + new_expires_in)
-        # Note: exact value depends on block advancement during the update
-        assert expected.expires_at_block is not None
-        assert expected.expires_at_block > initial_expiration, (
-            "Expiration should increase with higher expires_in"
+        # Verify new expiration was extended
+        # The new expiration should be: current_block + to_blocks(new_expires_in)
+        # Since we don't know the exact current block, we verify it's greater than initial
+        assert entity_after.expires_at_block is not None
+        assert entity_after.expires_at_block > initial_expiration_block, (
+            f"Expiration should increase with higher expires_in: "
+            f"{initial_expiration_block} -> {entity_after.expires_at_block}"
         )
 
         logger.info(
-            f"Expiration extension successful: {initial_expiration} -> {expected.expires_at_block}"
+            f"Expiration extension successful: {initial_expiration_block} -> {entity_after.expires_at_block}"
         )
 
     def test_update_entity_both_payload_and_attributes(

tests/test_module_utils.py

@@ -7,6 +7,47 @@
 logger = logging.getLogger(__name__)
 
 
+class TestToSeconds:
+    """Test cases for to_seconds time conversion method."""
+
+    def test_to_seconds_from_seconds(self, arkiv_client_http: Arkiv):
+        """Test conversion from seconds."""
+        result = arkiv_client_http.arkiv.to_seconds(seconds=120)
+        assert result == 120
+
+    def test_to_seconds_from_minutes(self, arkiv_client_http: Arkiv):
+        """Test conversion from minutes to seconds."""
+        # 2 minutes = 120 seconds
+        result = arkiv_client_http.arkiv.to_seconds(minutes=2)
+        assert result == 120
+
+    def test_to_seconds_from_hours(self, arkiv_client_http: Arkiv):
+        """Test conversion from hours to seconds."""
+        # 1 hour = 3600 seconds
+        result = arkiv_client_http.arkiv.to_seconds(hours=1)
+        assert result == 3600
+
+    def test_to_seconds_from_days(self, arkiv_client_http: Arkiv):
+        """Test conversion from days to seconds."""
+        # 1 day = 86400 seconds
+        result = arkiv_client_http.arkiv.to_seconds(days=1)
+        assert result == 86400
+
+    def test_to_seconds_mixed_units(self, arkiv_client_http: Arkiv):
+        """Test conversion with mixed time units."""
+        # 1 day + 2 hours + 30 minutes + 60 seconds
+        # = 86400 + 7200 + 1800 + 60 = 95460 seconds
+        result = arkiv_client_http.arkiv.to_seconds(
+            days=1, hours=2, minutes=30, seconds=60
+        )
+        assert result == 95460
+
+    def test_to_seconds_default_values(self, arkiv_client_http: Arkiv):
+        """Test with all default values (should return 0)."""
+        result = arkiv_client_http.arkiv.to_seconds()
+        assert result == 0
+
+
 class TestToBlocks:
     """Test cases for to_blocks time conversion method."""
 

tests/test_query_select.py

@@ -21,8 +21,10 @@
     EntityKey,
     QueryOptions,
 )
+from arkiv.utils import to_blocks
 
-EXPIRES_IN = 100
+EXPIRES_IN = 100  # In seconds
+EXPIRES_IN_BLOCKS = to_blocks(seconds=EXPIRES_IN)  # Convert to blocks
 CONTENT_TYPE_VALUE = "text/plain"
 
 
@@ -193,7 +195,7 @@ def test_query_select_all_fields(self, arkiv_client_http: Arkiv) -> None:
             expected_created_at + 1 if expected_created_at else None
         )
         expected_expires_at = (
-            expected_last_modified_at + EXPIRES_IN
+            expected_last_modified_at + EXPIRES_IN_BLOCKS
             if expected_last_modified_at
             else None
         )