dao-treasury 0.0.42__cp310-cp310-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl

dao_treasury/sorting/factory.py

@@ -0,0 +1,299 @@
+from typing import Any, Final, Generic, Optional, Union, final, overload
+
+from dao_treasury.constants import CHAINID
+from dao_treasury.sorting.rule import (
+    CostOfRevenueSortRule,
+    ExpenseSortRule,
+    IgnoreSortRule,
+    OtherExpenseSortRule,
+    OtherIncomeSortRule,
+    RevenueSortRule,
+    TRule,
+)
+from dao_treasury.types import Networks, SortFunction, TxGroupName
+
+
+def revenue(
+    txgroup: TxGroupName, networks: Networks = CHAINID
+) -> "SortRuleFactory[RevenueSortRule]":
+    """Create a factory to register revenue sort rules for a given transaction group.
+
+    Args:
+        txgroup: Base name of the transaction group to categorize as revenue.
+        networks: Network ID or iterable of network IDs on which this rule applies.
+
+    See Also:
+        :func:`cost_of_revenue`
+        :class:`SortRuleFactory`
+
+    Examples:
+        >>> from dao_treasury.sorting.factory import revenue
+        >>> @revenue("Token Sales")
+        ... def match_sales(tx):
+        ...     return tx.amount > 0 and tx.to_address is not None
+    """
+    return SortRuleFactory(txgroup, networks, RevenueSortRule)
+
+
+def cost_of_revenue(
+    txgroup: TxGroupName, networks: Networks = CHAINID
+) -> "SortRuleFactory[CostOfRevenueSortRule]":
+    """Create a factory to register cost‐of‐revenue sort rules for a given transaction group.
+
+    Args:
+        txgroup: Base name of the transaction group to categorize as cost of revenue.
+        networks: Network ID or iterable of network IDs on which this rule applies.
+
+    See Also:
+        :func:`revenue`
+        :class:`SortRuleFactory`
+
+    Examples:
+        >>> from dao_treasury.sorting.factory import cost_of_revenue
+        >>> @cost_of_revenue("Manufacturing")
+        ... def match_manufacturing(tx):
+        ...     return tx.from_address is not None and tx.amount_usd > 1000
+    """
+    return SortRuleFactory(txgroup, networks, CostOfRevenueSortRule)
+
+
+def expense(
+    txgroup: TxGroupName, networks: Networks = CHAINID
+) -> "SortRuleFactory[ExpenseSortRule]":
+    """Create a factory to register expense sort rules for a given transaction group.
+
+    Args:
+        txgroup: Base name of the transaction group to categorize as expense.
+        networks: Network ID or iterable of network IDs on which this rule applies.
+
+    See Also:
+        :func:`other_expense`
+        :class:`SortRuleFactory`
+
+    Examples:
+        >>> from dao_treasury.sorting.factory import expense
+        >>> @expense("Office Supplies")
+        ... def match_supplies(tx):
+        ...     return tx.symbol == "USD" and tx.amount < 500
+    """
+    return SortRuleFactory(txgroup, networks, ExpenseSortRule)
+
+
+def other_income(
+    txgroup: TxGroupName, networks: Networks = CHAINID
+) -> "SortRuleFactory[OtherIncomeSortRule]":
+    """Create a factory to register other‐income sort rules for a given transaction group.
+
+    Args:
+        txgroup: Base name of the transaction group to categorize as other income.
+        networks: Network ID or iterable of network IDs on which this rule applies.
+
+    See Also:
+        :func:`revenue`
+        :class:`SortRuleFactory`
+
+    Examples:
+        >>> from dao_treasury.sorting.factory import other_income
+        >>> @other_income("Interest")
+        ... def match_interest(tx):
+        ...     return tx.token_address == SOME_TOKEN and tx.amount > 0
+    """
+    return SortRuleFactory(txgroup, networks, OtherIncomeSortRule)
+
+
+def other_expense(
+    txgroup: TxGroupName, networks: Networks = CHAINID
+) -> "SortRuleFactory[OtherExpenseSortRule]":
+    """Create a factory to register other‐expense sort rules for a given transaction group.
+
+    Args:
+        txgroup: Base name of the transaction group to categorize as other expense.
+        networks: Network ID or iterable of network IDs on which this rule applies.
+
+    See Also:
+        :func:`expense`
+        :class:`SortRuleFactory`
+
+    Examples:
+        >>> from dao_treasury.sorting.factory import other_expense
+        >>> @other_expense("Misc Fees")
+        ... def match_misc(tx):
+        ...     return tx.amount_usd < 0 and tx.symbol == "ETH"
+    """
+    return SortRuleFactory(txgroup, networks, OtherExpenseSortRule)
+
+
+def ignore(
+    txgroup: TxGroupName, networks: Networks = CHAINID
+) -> "SortRuleFactory[IgnoreSortRule]":
+    """Create a factory to register ignore sort rules for a given transaction group.
+
+    Args:
+        txgroup: Base name of the transaction group to categorize as ignored.
+        networks: Network ID or iterable of network IDs on which this rule applies.
+
+    See Also:
+        :class:`SortRuleFactory`
+
+    Examples:
+        >>> from dao_treasury.sorting.factory import ignore
+        >>> @ignore("Dust")
+        ... def match_dust(tx):
+        ...     return abs(tx.value_usd) < 0.01
+    """
+    return SortRuleFactory(txgroup, networks, IgnoreSortRule)
+
+
+@final
+class SortRuleFactory(Generic[TRule]):
+    """Builder for creating sort rule instances for a specific transaction group and network(s).
+
+    This factory supports two patterns:
+
+    1. Decorating a function to register a dynamic matching rule.
+    2. Calling :meth:`match` to supply static match attributes.
+
+    Use the convenience functions like :func:`revenue`, :func:`expense`, etc.,
+    to obtain an instance of this factory preconfigured with the appropriate rule type.
+
+    Examples:
+        >>> from dao_treasury.sorting.factory import revenue
+        >>> @revenue("Sales", networks=[1, 3])
+        ... def match_large_sales(tx):
+        ...     return tx.value_usd > 1000
+    """
+
+    def __init__(
+        self,
+        txgroup: TxGroupName,
+        networks: Networks,
+        rule_type: TRule,
+    ) -> None:
+        """Initialize the sort rule factory.
+
+        Args:
+            txgroup: Base name of the transaction group.
+            networks: Single network ID or iterable of network IDs where the rule applies.
+            rule_type: Sort rule class (e.g., RevenueSortRule) to instantiate.
+        """
+        self.txgroup: Final = txgroup
+        self.networks: Final = (
+            [networks] if isinstance(networks, int) else list(networks)
+        )
+        self.rule_type: Final = rule_type
+        self._rule: Optional[TRule] = None
+
+    @overload
+    def __call__(
+        self, txgroup_name: TxGroupName, networks: Optional[Networks] = None
+    ) -> "SortRuleFactory":
+        """Configure a nested sub‐group.
+
+        Args:
+            txgroup_name: Sub‐group name.
+            networks: Optional network specification.
+        """
+
+    @overload
+    def __call__(self, func: SortFunction) -> SortFunction:
+        """Register a matching function.
+
+        Args:
+            func: The custom matching function.
+        """
+
+    def __call__(  # type: ignore [misc]
+        self,
+        func: Union[TxGroupName, SortFunction],
+        networks: Optional[Networks] = None,
+    ) -> Union["SortRuleFactory", SortFunction]:
+        """Configure a nested sub‐group or register a matching function.
+
+        Overloads:
+            * If `func` is a string, returns a new factory for `txgroup:func`.
+            * If `func` is callable, registers it as the match logic.
+
+        Args:
+            func: Sub‐group suffix (str) or a custom matching function.
+            networks: Optional networks override (only valid when `func` is str).
+
+        Raises:
+            RuntimeError: If `networks` is passed when `func` is callable.
+            ValueError: If `func` is neither str nor callable.
+
+        See Also:
+            :meth:`match`
+
+        Examples:
+            >>> fees = expense("Fees")
+            >>> @fees("Gas")
+            ... def match_gas(tx):
+            ...     return tx.symbol == "ETH"
+        """
+        if isinstance(func, str):
+            return SortRuleFactory(
+                f"{self.txgroup}:{func}", networks or self.networks, self.rule_type
+            )
+        elif callable(func):
+            if networks:
+                raise RuntimeError("you can only pass networks if `func` is a string")
+            if CHAINID in self.networks:
+                self.__check_locked()
+                self._rule = self.rule_type(txgroup=self.txgroup, func=func)
+            return func
+        raise ValueError(func)
+
+    @property
+    def rule(self) -> Optional[TRule]:
+        """Return the created sort rule instance, if any.
+
+        After decoration or a call to :meth:`match`, this property holds the
+        concrete :class:`~dao_treasury.types.SortRule` instance.
+
+        Examples:
+            >>> @other_income("Interest")
+            ... def match_i(tx):
+            ...     return tx.value_usd > 100
+        """
+        return self._rule
+
+    def match(
+        self, func: None = None, **match_values: Any
+    ) -> None:  # TODO: give this proper kwargs
+        """Define static matching attributes for the sort rule.
+
+        Call this method with keyword matchers corresponding to rule attributes
+        (e.g., hash, from_address, symbol) to create a rule matching based on these values.
+
+        Args:
+            func: Must be None; a function match must use the decorator form.
+            **match_values: Attribute values for matching (e.g., hash="0x123", symbol="DAI").
+
+        Raises:
+            ValueError: If `func` is not None.
+            RuntimeError: If a matcher has already been set.
+
+        See Also:
+            :meth:`__call__`
+
+        Examples:
+            >>> ignore("Dust").match(symbol="WETH", from_address="0xAAA")
+        """
+        if func is not None:
+            raise ValueError(
+                f"You cannot pass a func here, call {self} with the function as the sole arg instead"
+            )
+        # Only instantiate when we're on an allowed network
+        if CHAINID in self.networks:
+            self.__check_locked()
+            self._rule = self.rule_type(txgroup=self.txgroup, **match_values)
+            self.locked = True
+
+    def __check_locked(self) -> None:
+        """Ensure that no matcher has already been registered.
+
+        Raises:
+            RuntimeError: If this factory already has a matcher assigned.
+        """
+        if self._rule is not None:
+            raise RuntimeError(f"{self} already has a matcher")

dao_treasury/sorting/rule.py

@@ -0,0 +1,346 @@
+# dao_treasury/sorting/rule.py
+
+"""Module defining transaction sorting rules for the DAO treasury.
+
+This module provides the `_SortRule` base class and subclasses for categorizing
+`TreasuryTx` entries based on their attributes or a custom function. When a rule
+is instantiated, it registers itself in the global `SORT_RULES` mapping under its
+class and configures which transaction attributes to match via `_match_all`.
+
+Examples:
+    # Define a revenue rule for sales (assuming you only transact in DAI for sales)
+    >>> from dao_treasury.sorting.rule import RevenueSortRule, SORT_RULES
+    >>> RevenueSortRule(
+    ...     txgroup='Sale',
+    ...     token_address='0x6B175474E89094d879c81e570a000000000000',
+    ...     symbol='DAI'
+    ... )
+    # Inspect rules registered for RevenueSortRule
+    >>> len(SORT_RULES[RevenueSortRule])
+    1
+
+    # Iterate over all ExpenseSortRule instances
+    >>> from dao_treasury.sorting.rule import ExpenseSortRule
+    >>> for rule in SORT_RULES[ExpenseSortRule]:
+    ...     print(rule.txgroup)
+
+See Also:
+    :const:`~dao_treasury.sorting.rule.SORT_RULES`
+    :class:`~dao_treasury.sorting.rule._SortRule`
+"""
+
+from collections import defaultdict
+from dataclasses import dataclass
+from logging import getLogger
+from typing import (
+    TYPE_CHECKING,
+    DefaultDict,
+    Dict,
+    Final,
+    List,
+    Optional,
+    Type,
+    TypeVar,
+)
+
+from brownie.convert.datatypes import EthAddress
+from eth_typing import HexStr
+from mypy_extensions import mypyc_attr
+
+from dao_treasury._wallet import TreasuryWallet
+from dao_treasury.types import SortFunction, SortRule, TxGroupDbid, TxGroupName
+
+if TYPE_CHECKING:
+    from dao_treasury.db import TreasuryTx
+
+
+logger: Final = getLogger(__name__)
+_log_debug: Final = logger.debug
+
+SORT_RULES: DefaultDict[Type[SortRule], List[SortRule]] = defaultdict(list)
+"""Mapping from sort rule classes to lists of instantiated rules, in creation order per class.
+
+Each key is a subclass of :class:`~dao_treasury.types.SortRule` and the corresponding
+value is the list of rule instances of that class.
+
+Examples:
+    >>> from dao_treasury.sorting.rule import RevenueSortRule, SORT_RULES
+    >>> RevenueSortRule(txgroup='Interest', symbol='DAI')
+    >>> SORT_RULES[RevenueSortRule][0].txgroup
+    'Revenue:Interest'
+"""
+
+_match_all: Final[Dict[TxGroupName, List[str]]] = {}
+"""An internal cache defining which matcher attributes are used for each `txgroup`."""
+
+_MATCHING_ATTRS: Final = (
+    "hash",
+    "from_address",
+    "from_nickname",
+    "to_address",
+    "to_nickname",
+    "token_address",
+    "symbol",
+    "log_index",
+)
+
+
+@mypyc_attr(native_class=False)
+@dataclass(kw_only=True, frozen=True)
+class _SortRule:
+    """Base class for defining transaction matching rules.
+
+    When instantiated, a rule validates its inputs, determines which transaction
+    attributes to match (or uses a custom function), and registers itself
+    in the global `SORT_RULES` mapping under its class.
+
+    Matched transactions are assigned to the specified `txgroup`.
+
+    See Also:
+        :const:`dao_treasury.sorting.rule.SORT_RULES`
+    """
+
+    txgroup: TxGroupName
+    """Name of the transaction group to assign upon match."""
+
+    hash: Optional[HexStr] = None
+    """Exact transaction hash to match."""
+
+    from_address: Optional[EthAddress] = None
+    """Source wallet address to match."""
+
+    from_nickname: Optional[str] = None
+    """Sender nickname (alias) to match."""
+
+    to_address: Optional[EthAddress] = None
+    """Recipient wallet address to match."""
+
+    to_nickname: Optional[str] = None
+    """Recipient nickname (alias) to match."""
+
+    token_address: Optional[EthAddress] = None
+    """Token contract address to match."""
+
+    symbol: Optional[str] = None
+    """Token symbol to match."""
+
+    log_index: Optional[int] = None
+    """Log index within the transaction receipt to match."""
+
+    func: Optional[SortFunction] = None
+    """Custom matching function that takes a `TreasuryTx` and returns a bool or an awaitable that returns a bool."""
+
+    # __instances__: ClassVar[List[Self]] = []
+
+    def __post_init__(self) -> None:
+        """Validate inputs, checksum addresses, and register the rule.
+
+        - Ensures no duplicate rule exists for the same `txgroup`.
+        - Converts address fields to checksummed format.
+        - Determines which attributes will be used for direct matching.
+        - Validates that exactly one of attribute-based or function-based matching is provided.
+        - Registers the instance in :attr:`SORT_RULES` and :data:`_match_all`.
+        """
+        if self.txgroup in _match_all:
+            raise ValueError(
+                f"there is already a matcher defined for txgroup {self.txgroup}: {self}"
+            )
+
+        # ensure addresses are checksummed if applicable
+        for attr in ["from_address", "to_address", "token_address"]:
+            value = getattr(self, attr)
+            if value is not None:
+                checksummed = EthAddress(value)
+                # NOTE: we must use object.__setattr__ to modify a frozen dataclass instance
+                object.__setattr__(self, attr, checksummed)
+
+        # define matchers used for this instance
+        matchers = [attr for attr in _MATCHING_ATTRS if getattr(self, attr) is not None]
+        _match_all[self.txgroup] = matchers
+
+        if self.func is not None and matchers:
+            raise ValueError(
+                "You must specify attributes for matching or pass in a custom matching function, not both."
+            )
+
+        if self.func is None and not matchers:
+            raise ValueError(
+                "You must specify attributes for matching or pass in a custom matching function."
+            )
+
+        if self.func is not None and not callable(self.func):
+            raise TypeError(f"func must be callable. You passed {self.func}")
+
+        # append new instance to instances classvar
+        # TODO: fix dataclass ClassVar handling in mypyc and reenable
+        # self.__instances__.append(self)
+
+        # append new instance under its class key
+        SORT_RULES[type(self)].append(self)
+
+    @property
+    def txgroup_dbid(self) -> TxGroupDbid:
+        """Compute the database ID for this rule's `txgroup`.
+
+        Splits the `txgroup` string on ':' and resolves or creates the hierarchical
+        `TxGroup` entries in the database, returning the final group ID.
+
+        See Also:
+            :class:`~dao_treasury.db.TxGroup`.
+        """
+        from dao_treasury.db import TxGroup
+
+        txgroup = None
+        for part in self.txgroup.split(":"):
+            txgroup = TxGroup.get_dbid(part, txgroup)
+        return txgroup
+
+    async def match(self, tx: "TreasuryTx") -> bool:
+        """Determine if the given transaction matches this rule.
+
+        Args:
+            tx: A `TreasuryTx` entity to test against this rule.
+
+        Returns:
+            True if the transaction matches the rule criteria; otherwise False.
+
+        Examples:
+            # match by symbol and recipient
+            >>> rule = _SortRule(txgroup='Foo', symbol='DAI', to_address='0xabc...')
+            >>> await rule.match(tx)  # where tx.symbol == 'DAI' and tx.to_address == '0xabc...'
+            True
+
+        See Also:
+            :attr:`_match_all`
+        """
+        if matchers := _match_all[self.txgroup]:
+            return all(
+                getattr(tx, matcher) == getattr(self, matcher) for matcher in matchers
+            )
+
+        _log_debug("checking %s for %s", tx, self.func)
+        match = self.func(tx)  # type: ignore [misc]
+        return match if isinstance(match, bool) else await match
+
+
+@mypyc_attr(native_class=False)
+class _InboundSortRule(_SortRule):
+    """Sort rule that applies only to inbound transactions (to the DAO's wallet).
+
+    Checks that the transaction's `to_address` belongs to a known `TreasuryWallet`
+    before applying the base matching logic.
+    """
+
+    async def match(self, tx: "TreasuryTx") -> bool:
+        return (
+            tx.to_address is not None
+            and TreasuryWallet.check_membership(tx.to_address.address, tx.block)
+            and await super().match(tx)
+        )
+
+
+@mypyc_attr(native_class=False)
+class _OutboundSortRule(_SortRule):
+    """Sort rule that applies only to outbound transactions (from the DAO's wallet).
+
+    Checks that the transaction's `from_address` belongs to a known `TreasuryWallet`
+    before applying the base matching logic.
+    """
+
+    async def match(self, tx: "TreasuryTx") -> bool:
+        return TreasuryWallet.check_membership(
+            tx.from_address.address, tx.block
+        ) and await super().match(tx)
+
+
+@mypyc_attr(native_class=False)
+class RevenueSortRule(_InboundSortRule):
+    """Rule to categorize inbound transactions as revenue.
+
+    Prepends 'Revenue:' to the `txgroup` name before registration.
+
+    Examples:
+        >>> RevenueSortRule(txgroup='Sale', to_address='0xabc...', symbol='DAI')
+        # results in a rule with txgroup 'Revenue:Sale'
+    """
+
+    def __post_init__(self) -> None:
+        """Prepends `self.txgroup` with 'Revenue:'."""
+        object.__setattr__(self, "txgroup", f"Revenue:{self.txgroup}")
+        super().__post_init__()
+
+
+@mypyc_attr(native_class=False)
+class CostOfRevenueSortRule(_OutboundSortRule):
+    """Rule to categorize outbound transactions as cost of revenue.
+
+    Prepends 'Cost of Revenue:' to the `txgroup` name before registration.
+    """
+
+    def __post_init__(self) -> None:
+        """Prepends `self.txgroup` with 'Cost of Revenue:'."""
+        object.__setattr__(self, "txgroup", f"Cost of Revenue:{self.txgroup}")
+        super().__post_init__()
+
+
+@mypyc_attr(native_class=False)
+class ExpenseSortRule(_OutboundSortRule):
+    """Rule to categorize outbound transactions as expenses.
+
+    Prepends 'Expenses:' to the `txgroup` name before registration.
+    """
+
+    def __post_init__(self) -> None:
+        """Prepends `self.txgroup` with 'Expenses:'."""
+        object.__setattr__(self, "txgroup", f"Expenses:{self.txgroup}")
+        super().__post_init__()
+
+
+@mypyc_attr(native_class=False)
+class OtherIncomeSortRule(_InboundSortRule):
+    """Rule to categorize inbound transactions as other income.
+
+    Prepends 'Other Income:' to the `txgroup` name before registration.
+    """
+
+    def __post_init__(self) -> None:
+        """Prepends `self.txgroup` with 'Other Income:'."""
+        object.__setattr__(self, "txgroup", f"Other Income:{self.txgroup}")
+        super().__post_init__()
+
+
+@mypyc_attr(native_class=False)
+class OtherExpenseSortRule(_OutboundSortRule):
+    """Rule to categorize outbound transactions as other expenses.
+
+    Prepends 'Other Expenses:' to the `txgroup` name before registration.
+    """
+
+    def __post_init__(self) -> None:
+        """Prepends `self.txgroup` with 'Other Expenses:'."""
+        object.__setattr__(self, "txgroup", f"Other Expenses:{self.txgroup}")
+        super().__post_init__()
+
+
+@mypyc_attr(native_class=False)
+class IgnoreSortRule(_SortRule):
+    """Rule to ignore certain transactions.
+
+    Prepends 'Ignore:' to the `txgroup` name before registration.
+    """
+
+    def __post_init__(self) -> None:
+        """Prepends `self.txgroup` with 'Ignore:'."""
+        object.__setattr__(self, "txgroup", f"Ignore:{self.txgroup}")
+        super().__post_init__()
+
+
+TRule = TypeVar(
+    "TRule",
+    RevenueSortRule,
+    CostOfRevenueSortRule,
+    ExpenseSortRule,
+    OtherIncomeSortRule,
+    OtherExpenseSortRule,
+    IgnoreSortRule,
+)

dao_treasury/sorting/rules/__init__.py

@@ -0,0 +1 @@
+from dao_treasury.sorting.rules.ignore import *

dao_treasury/sorting/rules/ignore/__init__.py

@@ -0,0 +1 @@
+from dao_treasury.sorting.rules.ignore.llamapay import *

dao_treasury/sorting/rules/ignore/llamapay.py

@@ -0,0 +1,20 @@
+from dao_treasury import TreasuryTx
+from dao_treasury.sorting.factory import ignore
+from dao_treasury.streams import llamapay
+
+
+@ignore("LlamaPay")
+def is_llamapay_stream_replenishment(tx: TreasuryTx) -> bool:
+    if tx.to_address.address in llamapay.factories:  # type: ignore [operator]
+        # We amortize these streams daily in the `llamapay` module, you'll sort each stream appropriately.
+        return True
+
+    # NOTE: not sure if we want this yet
+    # Puling unused funds back from vesting escrow / llamapay
+    # elif tx.from_address == "Contract: LlamaPay" and "StreamCancelled" in tx.events:
+    #    if tx.amount > 0:
+    #        tx.amount *= -1
+    #    if tx.value_usd > 0:
+    #        tx.value_usd *= -1
+    #    return True
+    return False