feat: add get_block_timing and to_blocks to (Async)Arkiv

Author: Matthias Zimmermann

README.md

@@ -126,7 +126,7 @@ The snippet below demonstrates the creation of various nodes to connect to using
 ```python
 from arkiv import Arkiv
 from arkiv.account import NamedAccount
-from arkiv.provider import ProviderBuilder## Advanced Features
+from arkiv.provider import ProviderBuilder
 
 ### Provider Builder
 

pyproject.toml

@@ -57,6 +57,8 @@ lint = [
 ]
 dev = [
     "ipython>=8.37.0",
+    "testcontainers>=4.13.1",
+    "websockets>=13.0",
 ]
 
 [build-system]

src/arkiv/contract.py

@@ -191,4 +191,12 @@
         json_rpc_method=RPCEndpoint("arkiv_query"),
         mungers=[default_root_munger],
     ),
+    "get_block_timing": Method(
+        json_rpc_method=RPCEndpoint("arkiv_getBlockTiming"),
+        mungers=[default_root_munger],
+    ),
+    "estimate_costs": Method(
+        json_rpc_method=RPCEndpoint("arkiv_estimateStorageCosts"),
+        mungers=[default_root_munger],
+    ),
 }

src/arkiv/module.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import logging
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from eth_typing import ChecksumAddress, HexStr
 from web3 import Web3
@@ -397,6 +397,39 @@ def cleanup_filters(self) -> None:
         self._active_filters.clear()
         logger.info("All event filters cleaned up")
 
+    def get_block_timing(self) -> Any:
+        block_timing_response = self.client.eth.get_block_timing()
+        logger.info(f"Block timing response: {block_timing_response}")
+
+        return block_timing_response
+
+    def to_blocks(
+        self, seconds: int = 0, minutes: int = 0, hours: int = 0, days: int = 0
+    ) -> int:
+        """
+        Convert a time duration to number of blocks.
+
+        Useful for calculating blocks-to-live (BTL) 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 blocks corresponding to the time duration
+        """
+        total_seconds = seconds + minutes * 60 + hours * 3600 + days * 86400
+
+        if not hasattr(self, "_block_duration"):
+            block_timing = self.get_block_timing()
+            self._block_duration = block_timing["duration"]
+
+        block_time = self._block_duration
+        return total_seconds // block_time if block_time else 0
+
     @property
     def active_filters(self) -> list[EventFilter]:
         """Get a copy of currently active event filters."""

src/arkiv/module_async.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import logging
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from eth_typing import ChecksumAddress, HexStr
 from web3.types import TxParams, TxReceipt
@@ -360,6 +360,39 @@ async def cleanup_filters(self) -> None:
         self._active_filters.clear()
         logger.info("All async event filters cleaned up")
 
+    async def get_block_timing(self) -> Any:
+        block_timing_response = await self.client.eth.get_block_timing()
+        logger.info(f"Block timing response: {block_timing_response}")
+
+        return block_timing_response
+
+    async def to_blocks(
+        self, seconds: int = 0, minutes: int = 0, hours: int = 0, days: int = 0
+    ) -> int:
+        """
+        Convert a time duration to number of blocks.
+
+        Useful for calculating blocks-to-live (BTL) 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 blocks corresponding to the time duration
+        """
+        total_seconds = seconds + minutes * 60 + hours * 3600 + days * 86400
+
+        if not hasattr(self, "_block_duration"):
+            block_timing = await self.get_block_timing()
+            self._block_duration = block_timing["duration"]
+
+        block_time = self._block_duration
+        return total_seconds // block_time if block_time else 0
+
     @property
     def active_filters(self) -> list[AsyncEventFilter]:
         """Get a copy of currently active async event filters."""

src/arkiv/utils.py

@@ -344,9 +344,12 @@ def to_entity(fields: int, response_item: dict[str, Any]) -> Entity:
 
     # Extract created_at if present
     if fields & CREATED_AT != 0:
-        if not hasattr(response_item, "createdAtBlock"):
-            raise ValueError("RPC query response item missing 'createdAtBlock' field")
-        created_at_block = int(response_item.createdAtBlock)
+        if hasattr(response_item, "createdAtBlock"):
+            created_at_block = int(response_item.createdAtBlock)
+        else:
+            # TODO revert to raise pattern once available
+            # raise ValueError("RPC query response item missing 'createdAtBlock' field")
+            logger.info("RPC query response item missing 'createdAtBlock' field")
 
     # Extract last_modified_at if present
     if fields & LAST_MODIFIED_AT != 0:

tests/test_module_utils.py

@@ -0,0 +1,143 @@
+"""Tests for ArkivModule utility methods."""
+
+import logging
+from unittest.mock import MagicMock
+
+import pytest
+
+from arkiv.module import ArkivModule
+from arkiv.module_async import AsyncArkivModule
+
+logger = logging.getLogger(__name__)
+
+
+class TestToBlocks:
+    """Test cases for to_blocks time conversion method."""
+
+    @pytest.fixture
+    def mock_module(self):
+        """Create a mock ArkivModule for testing."""
+        module = MagicMock(spec=ArkivModule)
+        # Mock the get_block_timing response
+        module.get_block_timing.return_value = {"duration": 2}
+        # Bind the actual to_blocks method to our mock
+        module.to_blocks = ArkivModule.to_blocks.__get__(module)
+        return module
+
+    def test_to_blocks_from_seconds(self, mock_module):
+        """Test conversion from seconds to blocks."""
+        # With 2 second block time, 120 seconds = 60 blocks
+        result = mock_module.to_blocks(seconds=120)
+        assert result == 60
+        mock_module.get_block_timing.assert_called_once()
+
+    def test_to_blocks_from_minutes(self, mock_module):
+        """Test conversion from minutes to blocks."""
+        # 2 minutes = 120 seconds = 60 blocks
+        result = mock_module.to_blocks(minutes=2)
+        assert result == 60
+
+    def test_to_blocks_from_hours(self, mock_module):
+        """Test conversion from hours to blocks."""
+        # 1 hour = 3600 seconds = 1800 blocks
+        result = mock_module.to_blocks(hours=1)
+        assert result == 1800
+
+    def test_to_blocks_from_days(self, mock_module):
+        """Test conversion from days to blocks."""
+        # 1 day = 86400 seconds = 43200 blocks
+        result = mock_module.to_blocks(days=1)
+        assert result == 43200
+
+    def test_to_blocks_mixed_units(self, mock_module):
+        """Test conversion with mixed time units."""
+        # 1 day + 2 hours + 30 minutes + 60 seconds
+        # = 86400 + 7200 + 1800 + 60 = 95460 seconds = 47730 blocks
+        result = mock_module.to_blocks(days=1, hours=2, minutes=30, seconds=60)
+        assert result == 47730
+
+    def test_to_blocks_caches_block_duration(self, mock_module):
+        """Test that block duration is cached after first call."""
+        mock_module.to_blocks(seconds=2)
+        mock_module.to_blocks(seconds=4)
+        # Should only call get_block_timing once
+        assert mock_module.get_block_timing.call_count == 1
+
+    def test_to_blocks_default_values(self, mock_module):
+        """Test with all default values (should return 0)."""
+        result = mock_module.to_blocks()
+        assert result == 0
+
+    def test_to_blocks_rounding_down(self, mock_module):
+        """Test that partial blocks are rounded down."""
+        # 125 seconds with 2 second blocks = 62.5 blocks, should round to 62
+        result = mock_module.to_blocks(seconds=125)
+        assert result == 62
+
+
+class TestToBlocksAsync:
+    """Test cases for async to_blocks time conversion method."""
+
+    @pytest.fixture
+    async def mock_module_async(self):
+        """Create a mock AsyncArkivModule for testing."""
+        module = MagicMock(spec=AsyncArkivModule)
+        # Mock the async get_block_timing response
+        async def mock_get_block_timing():
+            return {"duration": 2}
+
+        module.get_block_timing = mock_get_block_timing
+        # Bind the actual to_blocks method to our mock
+        module.to_blocks = AsyncArkivModule.to_blocks.__get__(module)
+        return module
+
+    @pytest.mark.asyncio
+    async def test_async_to_blocks_from_seconds(self, mock_module_async):
+        """Test async conversion from seconds to blocks."""
+        # With 2 second block time, 120 seconds = 60 blocks
+        result = await mock_module_async.to_blocks(seconds=120)
+        assert result == 60
+
+    @pytest.mark.asyncio
+    async def test_async_to_blocks_from_minutes(self, mock_module_async):
+        """Test async conversion from minutes to blocks."""
+        # 2 minutes = 120 seconds = 60 blocks
+        result = await mock_module_async.to_blocks(minutes=2)
+        assert result == 60
+
+    @pytest.mark.asyncio
+    async def test_async_to_blocks_from_hours(self, mock_module_async):
+        """Test async conversion from hours to blocks."""
+        # 1 hour = 3600 seconds = 1800 blocks
+        result = await mock_module_async.to_blocks(hours=1)
+        assert result == 1800
+
+    @pytest.mark.asyncio
+    async def test_async_to_blocks_from_days(self, mock_module_async):
+        """Test async conversion from days to blocks."""
+        # 1 day = 86400 seconds = 43200 blocks
+        result = await mock_module_async.to_blocks(days=1)
+        assert result == 43200
+
+    @pytest.mark.asyncio
+    async def test_async_to_blocks_mixed_units(self, mock_module_async):
+        """Test async conversion with mixed time units."""
+        # 1 day + 2 hours + 30 minutes + 60 seconds
+        # = 86400 + 7200 + 1800 + 60 = 95460 seconds = 47730 blocks
+        result = await mock_module_async.to_blocks(
+            days=1, hours=2, minutes=30, seconds=60
+        )
+        assert result == 47730
+
+    @pytest.mark.asyncio
+    async def test_async_to_blocks_default_values(self, mock_module_async):
+        """Test async with all default values (should return 0)."""
+        result = await mock_module_async.to_blocks()
+        assert result == 0
+
+    @pytest.mark.asyncio
+    async def test_async_to_blocks_rounding_down(self, mock_module_async):
+        """Test that partial blocks are rounded down in async version."""
+        # 125 seconds with 2 second blocks = 62.5 blocks, should round to 62
+        result = await mock_module_async.to_blocks(seconds=125)
+        assert result == 62