Add support for event querying (#111)

* Add event filtering and docs

* Add default to query options

* Update version

Author: adam-maj

docs/docs/contract-events.md

@@ -81,3 +81,24 @@ def remove_all_listeners()
 
 Remove all event listeners from this contract.
 
+<a id="core.classes.contract_events.ContractEvents.get_events"></a>
+
+#### get\_events
+
+```python
+def get_events(
+    event_name: str, options: EventQueryOptions = EventQueryOptions()
+) -> Tuple[AttributeDict]
+```
+
+Query past events of a specific type on the contract.
+
+**Arguments**:
+
+- `event_name`: The name of the event to query.
+- `options`: The options to use when querying for events, including block range specifications and filters
+
+**Returns**:
+
+A list of events.
+

pyproject.toml

@@ -6,7 +6,7 @@ packages = [
   {include = "thirdweb"},
 ]
 readme = "README.md"
-version = "2.0.18"
+version = "2.1.1"
 
 [tool.poetry.dependencies]
 python = ">=3.7.1"

tests/test_events.py

@@ -7,7 +7,7 @@
 from thirdweb.contracts.nft_collection import NFTCollection
 from thirdweb.core.sdk import ThirdwebSDK
 from thirdweb.types.contracts.signature import PayloadToSign721
-from thirdweb.types.events import SignatureEvent, TxEvent
+from thirdweb.types.events import EventQueryOptions, SignatureEvent, TxEvent
 from thirdweb.types.nft import NFTMetadataInput
 from thirdweb.types.settings.metadata import NFTCollectionContractMetadata
 
@@ -77,3 +77,14 @@ def listener(event: SignatureEvent):
         )
     )
     assert event_status is not None
+
+
+@pytest.mark.usefixtures("primary_account")
+def test_collection_events(nft_collection: NFTCollection, primary_account, secondary_account):
+    nft_collection.mint(NFTMetadataInput(name="Minted"))
+    events = nft_collection.events.get_events("TokensMinted", EventQueryOptions(filters={"mintedTo": primary_account.address}))
+    assert len(events) == 1
+    assert events[0].get("event") == "TokensMinted"
+
+    events = nft_collection.events.get_events("TokensMinted", EventQueryOptions(filters={"mintedTo": secondary_account.address}))
+    assert len(events) == 0

thirdweb/core/classes/contract_events.py

@@ -1,10 +1,9 @@
-from typing import Any, Callable, Dict, Generic
+from typing import Any, Callable, Dict, Generic, Tuple
 from thirdweb.constants.events import EventType
 from thirdweb.core.classes.contract_wrapper import ContractWrapper
 from thirdweb.types.contract import TContractABI
-from thirdweb.types.events import TxEvent
-
-
+from thirdweb.types.events import EventQueryOptions, TxEvent
+from web3.datastructures import AttributeDict
 class ContractEvents(Generic[TContractABI]):
     _contract_wrapper: ContractWrapper[TContractABI]
 
@@ -71,3 +70,16 @@ def remove_all_listeners(self):
         """
 
         self._contract_wrapper.remove_all_listeners()
+
+    def get_events(self, event_name: str, options: EventQueryOptions = EventQueryOptions()) -> Tuple[AttributeDict]:
+        """
+        Query past events of a specific type on the contract.
+
+        :param event_name: The name of the event to query.
+        :param options: The options to use when querying for events, including block range specifications and filters
+        :return: A list of events.
+        """
+
+        events_interface = self._contract_wrapper.get_contract_interface().events[event_name]
+        return events_interface.getLogs(options.filters, options.from_block, options.to_block)
+

thirdweb/types/__init__.py

@@ -1,6 +1,7 @@
-from .sdk import *
-from .nft import *
-from .multiwrap import *
-from .marketplace import *
-from .settings import *
-from .auth import *
+from thirdweb.types.sdk import *
+from thirdweb.types.nft import *
+from thirdweb.types.multiwrap import *
+from thirdweb.types.marketplace import *
+from thirdweb.types.settings import *
+from thirdweb.types.auth import *
+from thirdweb.types.events import *

thirdweb/types/events.py

@@ -1,7 +1,8 @@
 from dataclasses import dataclass
-from typing import Union
-
+import dataclasses
+from typing import Any, Dict, Optional, Union
 from thirdweb.constants.events import EventStatus
+from web3.types import BlockIdentifier
 
 
 @dataclass
@@ -15,3 +16,9 @@ class SignatureEvent:
     status: EventStatus
     message: str
     signature: Union[str, bytes]
+
+@dataclass
+class EventQueryOptions:
+    filters: Dict[str, Any] = dataclasses.field(default_factory=dict)
+    from_block: Optional[BlockIdentifier] = "earliest"
+    to_block: Optional[BlockIdentifier] = "latest"