bugfix(typing): Fix type for topics filtering

- Topics can be single topics or lists of AND / OR conditions. Here, we
  update to a better defined ``TopicFilter`` type to better define these cases.

Author: fselmo

newsfragments/3748.bugfix.rst

@@ -0,0 +1 @@
+Fix ``topics`` type for ``LogsSubscription`` to reflect AND / OR nested list conditions on log filters.

newsfragments/3748.feature.rst

@@ -0,0 +1 @@
+Add the ``TopicFilter`` type to better describe the cases for filtering logs by topics.

web3/_utils/module_testing/persistent_connection_provider.py

@@ -9,6 +9,7 @@
     Dict,
     Generator,
     List,
+    Sequence,
     Tuple,
     Union,
     cast,
@@ -44,6 +45,7 @@
     LogReceipt,
     Nonce,
     RPCEndpoint,
+    TopicFilter,
     TxData,
     Wei,
 )
@@ -580,6 +582,112 @@ async def test_async_eth_subscribe_creates_and_handles_logs_subscription_type(
         sub_manager.total_handler_calls = 0
         await clean_up_task(emit_event_task)
 
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize(
+        "topics",
+        [
+            pytest.param(
+                [
+                    HexStr(
+                        "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"  # noqa: E501
+                    )
+                ],
+                id="Single specific topic at position 0",
+            ),
+            pytest.param(
+                [
+                    None,
+                    HexStr(
+                        "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"  # noqa: E501
+                    ),
+                ],
+                id="Wildcard at position 0, specific topic at position 1",
+            ),
+            pytest.param(
+                [
+                    [
+                        HexStr(
+                            "0x1111111111111111111111111111111111111111111111111111111111111111"  # noqa: E501
+                        ),
+                        HexStr(
+                            "0x2222222222222222222222222222222222222222222222222222222222222222"  # noqa: E501
+                        ),
+                    ]
+                ],
+                id="OR pattern: topic A or B at position 0",
+            ),
+            pytest.param(
+                [
+                    [
+                        HexStr(
+                            "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"  # noqa: E501
+                        ),
+                        HexStr(
+                            "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"  # noqa: E501
+                        ),
+                    ],
+                    HexStr(
+                        "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"  # noqa: E501
+                    ),
+                ],
+                id="Complex: (A or B) at position 0 AND C at position 1",
+            ),
+            pytest.param(
+                [
+                    HexBytes(
+                        "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"  # noqa: E501
+                    )
+                ],
+                id="Single specific topic at position 0 with HexBytes",
+            ),
+            pytest.param(
+                [
+                    [
+                        HexBytes(
+                            "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"  # noqa: E501
+                        ),
+                        HexStr(
+                            "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"  # noqa: E501
+                        ),
+                        b"\xcc" * 32,
+                    ]
+                ],
+                id="OR pattern with mixed HexBytes, HexStr, and bytes at position 0",
+            ),
+        ],
+    )
+    async def test_async_logs_subscription_with_and_or_topic_patterns(
+        self,
+        async_w3: AsyncWeb3,
+        async_emitter_contract: "AsyncContract",
+        topics: Sequence[TopicFilter],
+    ) -> None:
+        """Test that LogsSubscription properly handles AND/OR topic patterns."""
+        sub_manager = async_w3.subscription_manager
+
+        subscription = LogsSubscription(
+            address=async_emitter_contract.address,
+            topics=topics,
+            handler=idle_handler,
+        )
+
+        await sub_manager.subscribe(subscription)
+        assert len(sub_manager.subscriptions) == 1
+        assert isinstance(sub_manager.subscriptions[0], LogsSubscription)
+        assert sub_manager.subscriptions[0].topics == topics
+
+        assert subscription.subscription_params == (
+            "logs",
+            {
+                "address": async_emitter_contract.address,
+                "topics": topics,
+            },
+        )
+
+        # clean up
+        await sub_manager.unsubscribe(subscription)
+        assert len(sub_manager.subscriptions) == 0
+
     @pytest.mark.asyncio
     async def test_async_extradata_poa_middleware_on_eth_subscription(
         self,

web3/types.py

@@ -62,6 +62,19 @@
 
 # bytes, hexbytes, or hexstr representing a 32 byte hash
 _Hash32 = Union[Hash32, HexBytes, HexStr]
+
+# --- ``TopicFilter`` type for event log filtering with AND/OR patterns --- #
+# - ``None``: wildcard, matches any value at this position
+# - ``_Hash32``: single topic that must match exactly
+# - ``Sequence[Union[None, _Hash32]]``: OR condition, at least one must match
+# - ``Sequence[Sequence[...]]``: nested OR conditions
+TopicFilter = Union[
+    None,
+    _Hash32,
+    Sequence[Union[None, _Hash32]],
+    Sequence["TopicFilter"],
+]
+
 EnodeURI = NewType("EnodeURI", str)
 ENS = NewType("ENS", str)
 Nonce = NewType("Nonce", int)
@@ -345,7 +358,7 @@ class FilterParams(TypedDict, total=False):
     blockHash: HexBytes
     fromBlock: BlockIdentifier
     toBlock: BlockIdentifier
-    topics: Sequence[Optional[Union[_Hash32, Sequence[_Hash32]]]]
+    topics: Sequence[TopicFilter]
 
 
 class FeeHistory(TypedDict):
@@ -667,4 +680,4 @@ class LogsSubscriptionArg(TypedDict, total=False):
         ENS,
         Sequence[Union[Address, ChecksumAddress, ENS]],
     ]
-    topics: Sequence[Union[HexStr, Sequence[HexStr]]]
+    topics: Sequence[TopicFilter]

web3/utils/subscriptions.py

@@ -30,6 +30,7 @@
     FilterParams,
     LogReceipt,
     SyncProgress,
+    TopicFilter,
     TxData,
 )
 
@@ -215,7 +216,7 @@ def __init__(
         address: Optional[
             Union[Address, ChecksumAddress, List[Address], List[ChecksumAddress]]
         ] = None,
-        topics: Optional[List[HexStr]] = None,
+        topics: Optional[Sequence[TopicFilter]] = None,
         handler: LogsSubscriptionHandler = None,
         handler_context: Optional[Dict[str, Any]] = None,
         label: Optional[str] = None,