defistream 1.0.4__py3-none-any.whl → 1.1.0__py3-none-any.whl

defistream/__init__.py

@@ -29,23 +29,9 @@ from .exceptions import (
     ServerError,
     ValidationError,
 )
-from .models import (
-    AAVEBorrowEvent,
-    AAVEDepositEvent,
-    AAVELiquidationEvent,
-    AAVERepayEvent,
-    AAVEWithdrawEvent,
-    ERC20TransferEvent,
-    EventBase,
-    LidoDepositEvent,
-    LidoWithdrawEvent,
-    NativeTransferEvent,
-    ResponseMetadata,
-    UniswapSwapEvent,
-)
 from .query import AsyncQueryBuilder, QueryBuilder
 
-__version__ = "1.0.4"
+__version__ = "1.1.0"
 
 __all__ = [
     # Clients
@@ -62,17 +48,4 @@ __all__ = [
     "ValidationError",
     "NotFoundError",
     "ServerError",
-    # Models
-    "EventBase",
-    "ResponseMetadata",
-    "ERC20TransferEvent",
-    "NativeTransferEvent",
-    "AAVEDepositEvent",
-    "AAVEWithdrawEvent",
-    "AAVEBorrowEvent",
-    "AAVERepayEvent",
-    "AAVELiquidationEvent",
-    "UniswapSwapEvent",
-    "LidoDepositEvent",
-    "LidoWithdrawEvent",
 ]

defistream/models.py

@@ -1,7 +1,7 @@
 """Pydantic models for DeFiStream API responses."""
 
 from typing import Any, Literal
-from pydantic import BaseModel, Field
+from pydantic import BaseModel
 
 
 class ResponseMetadata(BaseModel):
@@ -12,153 +12,6 @@ class ResponseMetadata(BaseModel):
     request_cost: int | None = None
 
 
-class EventBase(BaseModel):
-    """Base model for all events."""
-
-    block_number: int
-    time: str | None = None
-    # Verbose fields (only present when verbose=true)
-    name: str | None = None
-    network: str | None = None
-    tx_id: str | None = None
-    tx_hash: str | None = None
-    log_index: int | None = None
-
-
-class ERC20TransferEvent(EventBase):
-    """ERC20 Transfer event."""
-
-    sender: str = Field(alias="from_address", default="")
-    receiver: str = Field(alias="to_address", default="")
-    amount: float = 0.0
-    token_address: str | None = None
-    token_symbol: str | None = None
-
-    model_config = {"populate_by_name": True}
-
-
-class ERC20ApprovalEvent(EventBase):
-    """ERC20 Approval event."""
-
-    owner: str = ""
-    spender: str = ""
-    amount: float = 0.0
-    token_address: str | None = None
-    token_symbol: str | None = None
-
-
-class NativeTransferEvent(EventBase):
-    """Native token (ETH/MATIC/etc) transfer event."""
-
-    sender: str = ""
-    receiver: str = ""
-    amount: float = 0.0
-
-
-class AAVEDepositEvent(EventBase):
-    """AAVE V3 Supply/Deposit event."""
-
-    user: str = ""
-    reserve: str = ""
-    amount: float = 0.0
-    on_behalf_of: str | None = None
-
-
-class AAVEWithdrawEvent(EventBase):
-    """AAVE V3 Withdraw event."""
-
-    user: str = ""
-    reserve: str = ""
-    amount: float = 0.0
-    to: str | None = None
-
-
-class AAVEBorrowEvent(EventBase):
-    """AAVE V3 Borrow event."""
-
-    user: str = ""
-    reserve: str = ""
-    amount: float = 0.0
-    interest_rate_mode: int | None = None
-    borrow_rate: float | None = None
-    on_behalf_of: str | None = None
-
-
-class AAVERepayEvent(EventBase):
-    """AAVE V3 Repay event."""
-
-    user: str = ""
-    reserve: str = ""
-    amount: float = 0.0
-    repayer: str | None = None
-    use_a_tokens: bool | None = None
-
-
-class AAVELiquidationEvent(EventBase):
-    """AAVE V3 Liquidation event."""
-
-    liquidator: str = ""
-    user: str = ""
-    collateral_asset: str = ""
-    debt_asset: str = ""
-    debt_to_cover: float = 0.0
-    liquidated_collateral_amount: float = 0.0
-    receive_a_token: bool | None = None
-
-
-class UniswapSwapEvent(EventBase):
-    """Uniswap V3 Swap event."""
-
-    pool: str = ""
-    sender: str = ""
-    recipient: str = ""
-    amount0: float = 0.0
-    amount1: float = 0.0
-    sqrt_price_x96: int | None = None
-    liquidity: int | None = None
-    tick: int | None = None
-
-
-class UniswapMintEvent(EventBase):
-    """Uniswap V3 Mint (add liquidity) event."""
-
-    pool: str = ""
-    owner: str = ""
-    tick_lower: int = 0
-    tick_upper: int = 0
-    amount: int = 0
-    amount0: float = 0.0
-    amount1: float = 0.0
-
-
-class UniswapBurnEvent(EventBase):
-    """Uniswap V3 Burn (remove liquidity) event."""
-
-    pool: str = ""
-    owner: str = ""
-    tick_lower: int = 0
-    tick_upper: int = 0
-    amount: int = 0
-    amount0: float = 0.0
-    amount1: float = 0.0
-
-
-class LidoDepositEvent(EventBase):
-    """Lido stETH deposit event."""
-
-    sender: str = ""
-    amount: float = 0.0
-    shares: float = 0.0
-
-
-class LidoWithdrawEvent(EventBase):
-    """Lido stETH withdrawal event."""
-
-    owner: str = ""
-    request_id: int = 0
-    amount: float = 0.0
-
-
 class EventsResponse(BaseModel):
     """Standard events API response."""
 

defistream/query.py

@@ -4,10 +4,84 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
 
+from .exceptions import ValidationError
+
 if TYPE_CHECKING:
     from .client import BaseClient
 
 
+# Label/category parameter names that need SQL safety checks
+_LABEL_CATEGORY_PARAMS = frozenset({
+    "involving_label", "involving_category",
+    "sender_label", "sender_category",
+    "receiver_label", "receiver_category",
+})
+
+# Mutual exclusivity groups: within each slot, only one key is allowed
+_INVOLVING_SLOT = ("involving", "involving_label", "involving_category")
+_SENDER_SLOT = ("sender", "sender_label", "sender_category")
+_RECEIVER_SLOT = ("receiver", "receiver_label", "receiver_category")
+
+
+def _normalize_multi(*args: str) -> str:
+    """Join varargs into a comma-separated string.
+
+    Accepts one or more strings. If a single pre-joined string is passed
+    (e.g. "a,b") it passes through unchanged.
+
+    Raises:
+        ValueError: If no arguments are provided.
+    """
+    if not args:
+        raise ValueError("At least one value is required")
+    return ",".join(args)
+
+
+def _validate_sql_safety(params: dict[str, Any]) -> None:
+    """Reject label/category values containing quotes or backslashes.
+
+    Raises:
+        ValidationError: If any label/category value contains ' or \\.
+    """
+    for key in _LABEL_CATEGORY_PARAMS:
+        value = params.get(key)
+        if value is not None and isinstance(value, str):
+            if "'" in value or "\\" in value:
+                raise ValidationError(
+                    f"Parameter '{key}' contains unsafe characters (single quote or backslash)"
+                )
+
+
+def _validate_mutual_exclusivity(params: dict[str, Any]) -> None:
+    """Enforce mutual exclusivity between filter slots.
+
+    Within each slot (involving, sender, receiver) only one key is allowed.
+    Cross-slot: involving* cannot combine with sender* or receiver*.
+
+    Raises:
+        ValidationError: If conflicting parameters are present.
+    """
+    def _check_slot(slot: tuple[str, ...], slot_name: str) -> str | None:
+        present = [k for k in slot if k in params]
+        if len(present) > 1:
+            raise ValidationError(
+                f"Cannot combine {present[0]} with {present[1]} — "
+                f"pick one {slot_name} filter"
+            )
+        return present[0] if present else None
+
+    involving_key = _check_slot(_INVOLVING_SLOT, "involving")
+    sender_key = _check_slot(_SENDER_SLOT, "sender")
+    receiver_key = _check_slot(_RECEIVER_SLOT, "receiver")
+
+    if involving_key and (sender_key or receiver_key):
+        other = sender_key or receiver_key
+        raise ValidationError(
+            f"Cannot combine {involving_key} with {other} — "
+            f"use involving* or sender*/receiver*, not both"
+        )
+
+
 class QueryBuilder:
     """
     Builder for constructing and executing DeFiStream API queries.
@@ -78,21 +152,49 @@ class QueryBuilder:
         return self._copy_with(since=start, until=end)
 
     # ERC20 and Native Token filters
-    def sender(self, address: str) -> "QueryBuilder":
-        """Filter by sender address (ERC20, Native Token)."""
-        return self._copy_with(sender=address)
+    def sender(self, *addresses: str) -> "QueryBuilder":
+        """Filter by sender address (ERC20, Native Token). Accepts multiple addresses."""
+        return self._copy_with(sender=_normalize_multi(*addresses))
+
+    def receiver(self, *addresses: str) -> "QueryBuilder":
+        """Filter by receiver address (ERC20, Native Token). Accepts multiple addresses."""
+        return self._copy_with(receiver=_normalize_multi(*addresses))
+
+    def from_address(self, *addresses: str) -> "QueryBuilder":
+        """Filter by sender address (alias for sender). Accepts multiple addresses."""
+        return self.sender(*addresses)
+
+    def to_address(self, *addresses: str) -> "QueryBuilder":
+        """Filter by receiver address (alias for receiver). Accepts multiple addresses."""
+        return self.receiver(*addresses)
+
+    def involving(self, *addresses: str) -> "QueryBuilder":
+        """Filter by any involved address (all protocols). Accepts multiple addresses."""
+        return self._copy_with(involving=_normalize_multi(*addresses))
+
+    def involving_label(self, *labels: str) -> "QueryBuilder":
+        """Filter by label on any involved address (all protocols)."""
+        return self._copy_with(involving_label=_normalize_multi(*labels))
+
+    def involving_category(self, *categories: str) -> "QueryBuilder":
+        """Filter by category on any involved address (all protocols)."""
+        return self._copy_with(involving_category=_normalize_multi(*categories))
 
-    def receiver(self, address: str) -> "QueryBuilder":
-        """Filter by receiver address (ERC20, Native Token)."""
-        return self._copy_with(receiver=address)
+    def sender_label(self, *labels: str) -> "QueryBuilder":
+        """Filter sender by label (ERC20, Native Token)."""
+        return self._copy_with(sender_label=_normalize_multi(*labels))
 
-    def from_address(self, address: str) -> "QueryBuilder":
-        """Filter by sender address (alias for sender)."""
-        return self.sender(address)
+    def sender_category(self, *categories: str) -> "QueryBuilder":
+        """Filter sender by category (ERC20, Native Token)."""
+        return self._copy_with(sender_category=_normalize_multi(*categories))
 
-    def to_address(self, address: str) -> "QueryBuilder":
-        """Filter by receiver address (alias for receiver)."""
-        return self.receiver(address)
+    def receiver_label(self, *labels: str) -> "QueryBuilder":
+        """Filter receiver by label (ERC20, Native Token)."""
+        return self._copy_with(receiver_label=_normalize_multi(*labels))
+
+    def receiver_category(self, *categories: str) -> "QueryBuilder":
+        """Filter receiver by category (ERC20, Native Token)."""
+        return self._copy_with(receiver_category=_normalize_multi(*categories))
 
     def min_amount(self, amount: float) -> "QueryBuilder":
         """Filter by minimum amount (ERC20, Native Token)."""
@@ -134,6 +236,8 @@ class QueryBuilder:
     def _build_params(self) -> dict[str, Any]:
         """Build the final query parameters."""
         params = self._params.copy()
+        _validate_sql_safety(params)
+        _validate_mutual_exclusivity(params)
         if self._verbose:
             params["verbose"] = "true"
         return params
@@ -294,21 +398,49 @@ class AsyncQueryBuilder:
         return self._copy_with(since=start, until=end)
 
     # ERC20 and Native Token filters
-    def sender(self, address: str) -> "AsyncQueryBuilder":
-        """Filter by sender address (ERC20, Native Token)."""
-        return self._copy_with(sender=address)
+    def sender(self, *addresses: str) -> "AsyncQueryBuilder":
+        """Filter by sender address (ERC20, Native Token). Accepts multiple addresses."""
+        return self._copy_with(sender=_normalize_multi(*addresses))
+
+    def receiver(self, *addresses: str) -> "AsyncQueryBuilder":
+        """Filter by receiver address (ERC20, Native Token). Accepts multiple addresses."""
+        return self._copy_with(receiver=_normalize_multi(*addresses))
+
+    def from_address(self, *addresses: str) -> "AsyncQueryBuilder":
+        """Filter by sender address (alias for sender). Accepts multiple addresses."""
+        return self.sender(*addresses)
+
+    def to_address(self, *addresses: str) -> "AsyncQueryBuilder":
+        """Filter by receiver address (alias for receiver). Accepts multiple addresses."""
+        return self.receiver(*addresses)
+
+    def involving(self, *addresses: str) -> "AsyncQueryBuilder":
+        """Filter by any involved address (all protocols). Accepts multiple addresses."""
+        return self._copy_with(involving=_normalize_multi(*addresses))
+
+    def involving_label(self, *labels: str) -> "AsyncQueryBuilder":
+        """Filter by label on any involved address (all protocols)."""
+        return self._copy_with(involving_label=_normalize_multi(*labels))
+
+    def involving_category(self, *categories: str) -> "AsyncQueryBuilder":
+        """Filter by category on any involved address (all protocols)."""
+        return self._copy_with(involving_category=_normalize_multi(*categories))
+
+    def sender_label(self, *labels: str) -> "AsyncQueryBuilder":
+        """Filter sender by label (ERC20, Native Token)."""
+        return self._copy_with(sender_label=_normalize_multi(*labels))
 
-    def receiver(self, address: str) -> "AsyncQueryBuilder":
-        """Filter by receiver address (ERC20, Native Token)."""
-        return self._copy_with(receiver=address)
+    def sender_category(self, *categories: str) -> "AsyncQueryBuilder":
+        """Filter sender by category (ERC20, Native Token)."""
+        return self._copy_with(sender_category=_normalize_multi(*categories))
 
-    def from_address(self, address: str) -> "AsyncQueryBuilder":
-        """Filter by sender address (alias for sender)."""
-        return self.sender(address)
+    def receiver_label(self, *labels: str) -> "AsyncQueryBuilder":
+        """Filter receiver by label (ERC20, Native Token)."""
+        return self._copy_with(receiver_label=_normalize_multi(*labels))
 
-    def to_address(self, address: str) -> "AsyncQueryBuilder":
-        """Filter by receiver address (alias for receiver)."""
-        return self.receiver(address)
+    def receiver_category(self, *categories: str) -> "AsyncQueryBuilder":
+        """Filter receiver by category (ERC20, Native Token)."""
+        return self._copy_with(receiver_category=_normalize_multi(*categories))
 
     def min_amount(self, amount: float) -> "AsyncQueryBuilder":
         """Filter by minimum amount (ERC20, Native Token)."""
@@ -350,6 +482,8 @@ class AsyncQueryBuilder:
     def _build_params(self) -> dict[str, Any]:
         """Build the final query parameters."""
         params = self._params.copy()
+        _validate_sql_safety(params)
+        _validate_mutual_exclusivity(params)
         if self._verbose:
             params["verbose"] = "true"
         return params

{defistream-1.0.4.dist-info → defistream-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: defistream
-Version: 1.0.4
+Version: 1.1.0
 Summary: Python client for the DeFiStream API
 Project-URL: Homepage, https://defistream.dev
 Project-URL: Documentation, https://docs.defistream.dev
@@ -204,6 +204,47 @@ df = (
 )
 ```
 
+### Label & Category Filters
+
+```python
+# Get USDT transfers involving Binance wallets
+df = (
+    client.erc20.transfers("USDT")
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .involving_label("Binance")
+    .as_df()
+)
+
+# Get USDT transfers FROM exchanges TO DeFi protocols
+df = (
+    client.erc20.transfers("USDT")
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .sender_category("exchange")
+    .receiver_category("defi")
+    .as_df()
+)
+
+# Get AAVE deposits involving exchange addresses
+df = (
+    client.aave.deposits()
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .involving_category("exchange")
+    .as_df()
+)
+
+# Get native ETH transfers FROM Binance or Coinbase (multi-value)
+df = (
+    client.native_token.transfers()
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .sender_label("Binance,Coinbase")
+    .as_df()
+)
+```
+
 ### Verbose Mode
 
 By default, responses omit metadata fields to reduce payload size. Use `.verbose()` to include all fields:
@@ -423,6 +464,23 @@ print(f"Request cost: {client.last_response.request_cost}")
 | `.symbol1(sym)` | Uniswap | Second token symbol (required) |
 | `.fee(tier)` | Uniswap | Fee tier: 100, 500, 3000, 10000 (required) |
 
+### Address Label & Category Filters
+
+Filter events by entity names or categories using the labels database. Available on all protocols.
+
+| Method | Protocols | Description |
+|--------|-----------|-------------|
+| `.involving_label(label)` | All | Filter where any involved address matches a label substring (e.g., "Binance") |
+| `.involving_category(cat)` | All | Filter where any involved address matches a category (e.g., "exchange") |
+| `.sender_label(label)` | ERC20, Native | Filter sender by label substring |
+| `.sender_category(cat)` | ERC20, Native | Filter sender by category |
+| `.receiver_label(label)` | ERC20, Native | Filter receiver by label substring |
+| `.receiver_category(cat)` | ERC20, Native | Filter receiver by category |
+
+**Multi-value support:** Comma-separated values are accepted (e.g., `"Binance,Coinbase"`).
+
+**Mutual exclusivity:** Within each slot (involving/sender/receiver), only one of address/label/category can be set. `involving*` filters cannot be combined with `sender*`/`receiver*` filters.
+
 ### Terminal Methods
 
 | Method | Description |

defistream-1.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+defistream/__init__.py,sha256=h-ca8lWZyPYPDd-rFTvO9J2ptW_p-SvspvgmgAe_wIc,1089
+defistream/client.py,sha256=Ku8ouDbM6Mx4lVmqvBwNvNt-h2FkvqauPMSjKyPkjU4,12717
+defistream/exceptions.py,sha256=_GxZQ18_YvXFtmNHeddWV8fHPIllHgFeP7fP0CmHF1k,1492
+defistream/models.py,sha256=Zw3DHAISxB6pivKybNzyHXR5IcRwvTZl23DHbjfyKwM,622
+defistream/protocols.py,sha256=5_bYd46lDy-mK6LZ8sTGW0Z2IVH4g0cQ5rBbbOXsw0U,15368
+defistream/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+defistream/query.py,sha256=yzrVfeRDZqoTYdQtj7SoYa7yd-NfO8heQ85YxhefU7c,22904
+defistream-1.1.0.dist-info/METADATA,sha256=hO1hUJMZZKkKOyd6B2V-r4sYRkaCmCR32VYfKJ_l3E4,12794
+defistream-1.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+defistream-1.1.0.dist-info/licenses/LICENSE,sha256=72DWAof8dMePfFQmfaswClW5d-sE6k7p-7VpuSKLmU4,1067
+defistream-1.1.0.dist-info/RECORD,,

defistream-1.0.4.dist-info/RECORD

@@ -1,11 +0,0 @@
-defistream/__init__.py,sha256=Vme3GaE4v7qXQcFFbpFe3Soaq06a_4I1ognx8DhzN-U,1680
-defistream/client.py,sha256=Ku8ouDbM6Mx4lVmqvBwNvNt-h2FkvqauPMSjKyPkjU4,12717
-defistream/exceptions.py,sha256=_GxZQ18_YvXFtmNHeddWV8fHPIllHgFeP7fP0CmHF1k,1492
-defistream/models.py,sha256=JiG4IUq19HIANz9MHQCkaE6onGNyNzXcbdJmosrHsw0,3812
-defistream/protocols.py,sha256=5_bYd46lDy-mK6LZ8sTGW0Z2IVH4g0cQ5rBbbOXsw0U,15368
-defistream/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-defistream/query.py,sha256=sNn_0OzNDlsp4N74Grumsb08R5OFPPoppPok3vh8Y6Q,16775
-defistream-1.0.4.dist-info/METADATA,sha256=YGb1XcogAIo9FkKyHYSkCoD0Po0exCuHrrz8i2M3J6w,10877
-defistream-1.0.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-defistream-1.0.4.dist-info/licenses/LICENSE,sha256=72DWAof8dMePfFQmfaswClW5d-sE6k7p-7VpuSKLmU4,1067
-defistream-1.0.4.dist-info/RECORD,,