dao-treasury 0.0.42__cp311-cp311-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl

dao_treasury/.grafana/provisioning/datasources/datasources.yaml

@@ -0,0 +1,17 @@
+apiVersion: 1
+
+datasources:
+- name: SQLite
+  type: frser-sqlite-datasource
+  isDefault: true
+  editable: false
+  jsonData:
+    path: /app/dao-treasury-data/dao-treasury.sqlite
+  secureJsonData: {}
+
+- name: 'PROMETHEUS'
+  type: 'prometheus'
+  access: 'proxy'
+  url: 'http://victoria-metrics:8428'
+  version: 1
+  editable: false

dao_treasury/ENVIRONMENT_VARIABLES.py

@@ -0,0 +1,20 @@
+"""Environment variable configuration for DAO Treasury.
+
+Defines and loads environment variables (with types and defaults) used for
+system configuration, such as SQL debugging. Uses :mod:`typed_envs` for convenience and safety.
+
+Key Responsibilities:
+    - Define and load environment variables for the system.
+    - Provide type-safe access to configuration options.
+
+This is the single source of truth for environment-based settings.
+"""
+
+from typing import Final
+
+from typed_envs import EnvVarFactory
+
+
+_factory = EnvVarFactory("DAO_TREASURY")
+
+SQL_DEBUG: Final = _factory.create_env("SQL_DEBUG", bool, default=False, verbose=False)

dao_treasury/__init__.py

@@ -0,0 +1,62 @@
+"""DAO Treasury package initializer.
+
+Exposes the main public API for the library, including the Treasury class,
+wallet management, sorting rules, and database models. Sets up address
+nicknames and enables SQL debugging if configured.
+
+Key Responsibilities:
+    - Import and expose core classes and functions.
+    - Initialize address nicknames in the database.
+    - Configure SQL debugging for development.
+
+This is the main import point for users and integrations.
+"""
+
+from dao_treasury import ENVIRONMENT_VARIABLES as ENVS
+from dao_treasury._nicknames import setup_address_nicknames_in_db
+from dao_treasury._wallet import TreasuryWallet
+from dao_treasury.db import TreasuryTx
+from dao_treasury.sorting import (
+    CostOfRevenueSortRule,
+    ExpenseSortRule,
+    IgnoreSortRule,
+    OtherExpenseSortRule,
+    OtherIncomeSortRule,
+    RevenueSortRule,
+    SortRuleFactory,
+    cost_of_revenue,
+    expense,
+    ignore,
+    other_expense,
+    other_income,
+    revenue,
+)
+from dao_treasury.treasury import Treasury
+
+
+setup_address_nicknames_in_db()
+
+
+if ENVS.SQL_DEBUG:
+    import pony.orm
+
+    pony.orm.sql_debug(True)
+
+__all__ = [
+    "Treasury",
+    "TreasuryWallet",
+    "CostOfRevenueSortRule",
+    "ExpenseSortRule",
+    "IgnoreSortRule",
+    "OtherExpenseSortRule",
+    "OtherIncomeSortRule",
+    "RevenueSortRule",
+    "cost_of_revenue",
+    "expense",
+    "ignore",
+    "other_expense",
+    "other_income",
+    "revenue",
+    "TreasuryTx",
+    "SortRuleFactory",
+]

dao_treasury/_docker.py

@@ -0,0 +1,190 @@
+"""Docker orchestration utilities for DAO Treasury.
+
+Provides functions to build, start, and stop Docker Compose services
+required for analytics dashboards (Grafana, renderer). Integrates with
+eth-portfolio's Docker setup and ensures all containers are managed
+consistently for local analytics.
+
+Key Responsibilities:
+    - Build and manage Grafana and renderer containers.
+    - Integrate with eth-portfolio Docker services.
+    - Provide decorators/utilities for container lifecycle management.
+
+This is the main entry for all Docker-based orchestration.
+"""
+
+import logging
+from importlib import resources
+import subprocess
+from functools import wraps
+from typing import Any, Callable, Coroutine, Final, Iterable, Tuple, TypeVar, List
+
+import eth_portfolio_scripts.docker
+from typing_extensions import ParamSpec
+
+logger: Final = logging.getLogger(__name__)
+
+compose_file: Final = str(
+    resources.files("dao_treasury").joinpath("docker-compose.yaml")
+)
+"""The path of dao-treasury's docker-compose.yaml file on your machine"""
+
+
+def up(*services: str) -> None:
+    """Build and start the specified containers defined in the compose file.
+
+    Args:
+        services: service names to bring up.
+
+    This function first builds the Docker services by invoking
+    :func:`build` and then starts the specified services in detached mode using
+    Docker Compose. If Docker Compose is not available, it falls back
+    to the legacy ``docker-compose`` command.
+
+    Examples:
+        >>> up('grafana')
+        starting the grafana container
+        >>> up()
+        starting all containers (grafana and renderer)
+
+    See Also:
+        :func:`build`
+        :func:`down`
+        :func:`_exec_command`
+    """
+    # eth-portfolio containers must be started first so dao-treasury can attach to the eth-portfolio docker network
+    eth_portfolio_scripts.docker.up("victoria-metrics")
+    build(*services)
+    print(f"starting the {', '.join(services) if services else 'grafana'} container(s)")
+    _exec_command(["up", "-d", *services])
+
+
+def down() -> None:
+    """Stop and remove Grafana containers.
+
+    This function brings down the Docker Compose services defined
+    in the compose file. Any positional arguments passed are ignored.
+
+    Examples:
+        >>> down()
+        # Stops containers
+
+    See Also:
+        :func:`up`
+    """
+    _exec_command(["down"])
+
+
+def build(*services: str) -> None:
+    """Build Docker images for Grafana containers.
+
+    This function builds all services defined in the Docker Compose
+    configuration file. It is a prerequisite step before starting
+    containers with :func:`up`.
+
+    Examples:
+        >>> build()
+        building the grafana containers
+
+    See Also:
+        :func:`up`
+        :func:`_exec_command`
+    """
+    print("building the grafana containers")
+    _exec_command(["build", *services])
+
+
+_P = ParamSpec("_P")
+_T = TypeVar("_T")
+
+
+def ensure_containers(
+    fn: Callable[_P, Coroutine[Any, Any, _T]],
+) -> Callable[_P, Coroutine[Any, Any, _T]]:
+    """Decorator to ensure Grafana containers are running before execution.
+
+    This async decorator starts the Docker Compose services via
+    :func:`up` before invoking the wrapped coroutine function. Once
+    the wrapped function completes or raises an exception, the containers
+    can be torn down by calling :func:`down`, although teardown is
+    currently commented out.
+
+    Args:
+        fn: The asynchronous function to wrap.
+
+    Returns:
+        A new coroutine function that wraps the original.
+
+    Examples:
+        >>> @ensure_containers
+        ... async def main_task():
+        ...     # Container-dependent logic here
+        ...     pass
+        >>> import asyncio
+        >>> asyncio.run(main_task())
+
+    See Also:
+        :func:`up`
+        :func:`down`
+    """
+
+    @wraps(fn)
+    async def compose_wrap(*args: _P.args, **kwargs: _P.kwargs) -> _T:
+        # register shutdown sequence
+        # TODO: argument to leave them up
+        # NOTE: do we need both this and the finally?
+        # signal.signal(signal.SIGINT, down)
+
+        # start Grafana containers
+        up("grafana")
+
+        try:
+            # attempt to run `fn`
+            return await fn(*args, **kwargs)
+        finally:
+            # stop and remove containers
+            # down()
+            pass
+
+    return compose_wrap
+
+
+def _exec_command(command: List[str], *, compose_options: Tuple[str, ...] = ()) -> None:
+    """Execute a Docker Compose command with system checks and fallback.
+
+    This internal function ensures that Docker and Docker Compose
+    are installed by calling :func:`check_system`. It then executes the
+    specified command using the ``docker compose`` CLI. If that fails,
+    it falls back to the legacy ``docker-compose`` command.
+
+    Args:
+        command: The sequence of command arguments for Docker Compose
+            (e.g., ``['up', '-d']`` or ``['down']``).
+        compose_options: Additional options to pass before specifying
+            the compose file (not commonly used).
+
+    Raises:
+        RuntimeError: If both ``docker compose`` and ``docker-compose``
+            invocations fail.
+
+    Examples:
+        >>> _exec_command(['up', '-d'])
+        # Executes `docker compose -f docker-compose.yaml up -d`
+
+    See Also:
+        :func:`check_system`
+    """
+    eth_portfolio_scripts.docker.check_system()
+    try:
+        subprocess.check_output(
+            ["docker", "compose", *compose_options, "-f", compose_file, *command]
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError) as e:
+        try:
+            subprocess.check_output(
+                ["docker-compose", *compose_options, "-f", compose_file, *command]
+            )
+        except (subprocess.CalledProcessError, FileNotFoundError) as _e:
+            raise RuntimeError(
+                f"Error occurred while running {' '.join(command)}: {_e}"
+            ) from _e

dao_treasury/_nicknames.py

@@ -0,0 +1,32 @@
+"""Address nickname setup utilities.
+
+This module provides functions to assign human-readable nicknames to
+important on-chain addresses (e.g., Zero Address, Disperse.app, tokens).
+It is used at package initialization to ensure all analytics and dashboards
+display professional, consistent labels.
+
+Key Responsibilities:
+    - Set nicknames for core addresses in the database.
+    - Integrate with constants and token metadata.
+    - Support professional, readable analytics outputs.
+
+This is called automatically on package import.
+"""
+
+from typing import Final
+
+from pony.orm import db_session
+
+from dao_treasury import constants
+from dao_treasury.db import Address, _set_address_nicknames_for_tokens
+
+
+set_nickname: Final = Address.set_nickname
+
+
+def setup_address_nicknames_in_db() -> None:
+    with db_session:
+        set_nickname(constants.ZERO_ADDRESS, "Zero Address")
+        for address in constants.DISPERSE_APP:
+            set_nickname(address, "Disperse.app")
+        _set_address_nicknames_for_tokens()

dao_treasury/_wallet.py

@@ -0,0 +1,250 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, Final, List, Optional, final
+
+import yaml
+from brownie.convert.datatypes import EthAddress
+from eth_typing import BlockNumber, ChecksumAddress, HexAddress
+from y import convert
+from y.time import closest_block_after_timestamp
+
+from dao_treasury.constants import CHAINID
+
+
+WALLETS: Final[Dict[ChecksumAddress, "TreasuryWallet"]] = {}
+
+to_address: Final = convert.to_address
+
+
+@final
+@dataclass
+class TreasuryWallet:
+    """A dataclass used to supplement a treasury wallet address with some extra context if needed for your use case"""
+
+    address: EthAddress
+    """The wallet address you need to include with supplemental information."""
+
+    start_block: Optional[int] = None
+    """The first block at which this wallet was considered owned by the DAO, if it wasn't always included in the treasury. If `start_block` is provided, you cannot provide a `start_timestamp`."""
+
+    end_block: Optional[int] = None
+    """The last block at which this wallet was considered owned by the DAO, if it wasn't always included in the treasury. If `end_block` is provided, you cannot provide an `end_timestamp`."""
+
+    start_timestamp: Optional[int] = None
+    """The first timestamp at which this wallet was considered owned by the DAO, if it wasn't always included in the treasury. If `start_timestamp` is provided, you cannot provide a `start_block`."""
+
+    end_timestamp: Optional[int] = None
+    """The last timestamp at which this wallet was considered owned by the DAO, if it wasn't always included in the treasury. If `end_timestamp` is provided, you cannot provide an `end_block`."""
+
+    networks: Optional[List[int]] = None
+    """The networks where the DAO owns this wallet. If not provided, the wallet will be active on all networks."""
+
+    def __post_init__(self) -> None:
+        # If a user provides a wallets yaml file but forgets to wrap the address
+        # keys with quotes, it will be an integer we must convert to an address.
+        self.address = EthAddress(to_address(self.address))
+
+        start_block = self.start_block
+        start_timestamp = self.start_timestamp
+        if start_block is not None:
+            if start_timestamp is not None:
+                raise ValueError(
+                    "You can only pass a start block or a start timestamp, not both."
+                )
+            elif start_block < 0:
+                raise ValueError("start_block can not be negative")
+        if start_timestamp is not None and start_timestamp < 0:
+            raise ValueError("start_timestamp can not be negative")
+
+        end_block = self.end_block
+        end_timestamp = self.end_timestamp
+        if end_block is not None:
+            if end_timestamp is not None:
+                raise ValueError(
+                    "You can only pass an end block or an end timestamp, not both."
+                )
+            elif end_block < 0:
+                raise ValueError("end_block can not be negative")
+        if end_timestamp is not None and end_timestamp < 0:
+            raise ValueError("end_timestamp can not be negative")
+
+        addr = ChecksumAddress(str(self.address))
+        if addr in WALLETS:
+            raise ValueError(f"TreasuryWallet {addr} already exists")
+        WALLETS[addr] = self
+
+    @staticmethod
+    def check_membership(
+        address: Optional[HexAddress], block: Optional[BlockNumber] = None
+    ) -> bool:
+        if address is None:
+            return False
+        wallet = TreasuryWallet._get_instance(address)
+        if wallet is None:
+            return False
+        # If networks filter is set, only include if current chain is listed
+        if wallet.networks and CHAINID not in wallet.networks:
+            return False
+        return block is None or (
+            wallet._start_block <= block
+            and (wallet._end_block is None or wallet._end_block >= block)
+        )
+
+    @property
+    def _start_block(self) -> BlockNumber:
+        start_block = self.start_block
+        if start_block is not None:
+            return start_block
+        start_timestamp = self.start_timestamp
+        if start_timestamp is not None:
+            return closest_block_after_timestamp(start_timestamp) - 1
+        return BlockNumber(0)
+
+    @property
+    def _end_block(self) -> Optional[BlockNumber]:
+        end_block = self.end_block
+        if end_block is not None:
+            return end_block
+        end_timestamp = self.end_timestamp
+        if end_timestamp is not None:
+            return closest_block_after_timestamp(end_timestamp) - 1
+        return None
+
+    @staticmethod
+    def _get_instance(address: HexAddress) -> Optional["TreasuryWallet"]:
+        # sourcery skip: use-contextlib-suppress
+        try:
+            instance = WALLETS[address]
+        except KeyError:
+            checksummed = to_address(address)
+            try:
+                instance = WALLETS[address] = WALLETS[checksummed]
+            except KeyError:
+                return None
+        if instance.networks and CHAINID not in instance.networks:
+            return None
+        return instance
+
+
+def load_wallets_from_yaml(path: Path) -> List[TreasuryWallet]:
+    """
+    Load a YAML mapping of wallet addresses to configuration and return a list of TreasuryWallets.
+    'timestamp' in top-level start/end is universal.
+    'block' in top-level start/end must be provided under the chain ID key.
+    Optional 'networks' key lists chain IDs where this wallet is active.
+    """
+    try:
+        data = yaml.safe_load(path.read_bytes())
+    except Exception as e:
+        raise ValueError(f"Failed to parse wallets YAML: {e}")
+
+    if not isinstance(data, dict):
+        raise ValueError("Wallets YAML file must be a mapping of address to config")
+
+    wallets: List[TreasuryWallet] = []
+    for address, cfg in data.items():
+        # Allow bare keys
+        if cfg is None:
+            cfg = {}
+        elif not isinstance(cfg, dict):
+            raise ValueError(f"Invalid config for wallet {address}, expected mapping")
+
+        kwargs = {"address": address}
+
+        # Extract optional networks list
+        networks = cfg.get("networks")
+        if networks:
+            if not isinstance(networks, list) or not all(
+                isinstance(n, int) for n in networks
+            ):
+                raise ValueError(
+                    f"'networks' for wallet {address} must be a list of integers, got {networks}"
+                )
+            kwargs["networks"] = networks
+
+        # Parse start: timestamp universal, block under chain key
+        start_cfg = cfg.get("start", {})
+        if not isinstance(start_cfg, dict):
+            raise ValueError(
+                f"Invalid 'start' for wallet {address}. Expected mapping, got {start_cfg}."
+            )
+        for key, value in start_cfg.items():
+            if key == "timestamp":
+                if "start_block" in kwargs:
+                    raise ValueError(
+                        "You cannot provide both a start block and a start timestamp"
+                    )
+                kwargs["start_timestamp"] = value
+            elif key == "block":
+                if not isinstance(value, dict):
+                    raise ValueError(
+                        f"Invalid start block for wallet {address}. Expected mapping, got {value}."
+                    )
+                for chainid, start_block in value.items():
+                    if not isinstance(chainid, int):
+                        raise ValueError(
+                            f"Invalid chainid for wallet {address} start block. Expected integer, got {chainid}."
+                        )
+                    if not isinstance(start_block, int):
+                        raise ValueError(
+                            f"Invalid start block for wallet {address}. Expected integer, got {start_block}."
+                        )
+                    if chainid == CHAINID:
+                        if "start_timestamp" in kwargs:
+                            raise ValueError(
+                                "You cannot provide both a start block and a start timestamp"
+                            )
+                        kwargs["start_block"] = start_block
+            else:
+                raise ValueError(
+                    f"Invalid key: {key}. Valid options are 'block' or 'timestamp'."
+                )
+
+        chain_block = start_cfg.get(str(CHAINID)) or start_cfg.get(CHAINID)
+        if chain_block is not None:
+            if not isinstance(chain_block, int):
+                raise ValueError(
+                    f"Invalid start.block for chain {CHAINID} on {address}"
+                )
+            kwargs["start_block"] = chain_block
+
+        # Parse end: timestamp universal, block under chain key
+        end_cfg = cfg.get("end", {})
+        if not isinstance(end_cfg, dict):
+            raise ValueError(
+                f"Invalid 'end' for wallet {address}. Expected mapping, got {end_cfg}."
+            )
+
+        for key, value in end_cfg.items():
+            if key == "timestamp":
+                if "end_block" in kwargs:
+                    raise ValueError(
+                        "You cannot provide both an end block and an end timestamp"
+                    )
+                kwargs["end_timestamp"] = value
+            elif key == "block":
+                if not isinstance(value, dict):
+                    raise ValueError(
+                        f"Invalid end block for wallet {address}. Expected mapping, got {value}."
+                    )
+                for chainid, end_block in value.items():
+                    if not isinstance(chainid, int):
+                        raise ValueError(
+                            f"Invalid chainid for wallet {address} end block. Expected integer, got {chainid}."
+                        )
+                    if not isinstance(end_block, int):
+                        raise ValueError(
+                            f"Invalid end block for wallet {address}. Expected integer, got {end_block}."
+                        )
+                    if chainid == CHAINID:
+                        kwargs["end_block"] = end_block
+            else:
+                raise ValueError(
+                    f"Invalid key: {key}. Valid options are 'block' or 'timestamp'."
+                )
+
+        wallet = TreasuryWallet(**kwargs)
+        print(f"initialized {wallet}")
+        wallets.append(wallet)
+
+    return wallets

dao_treasury/constants.py

@@ -0,0 +1,34 @@
+"""Core constants for DAO Treasury.
+
+All constants are marked with `Final`, ensuring immutability and allowing
+mypyc to compile them as extremely fast C-level constants for maximum
+performance. Defines chain IDs, zero address, and key contract addresses
+(e.g., Disperse.app) used throughout the system for transaction processing,
+nickname assignment, and analytics.
+
+Key Responsibilities:
+    - Provide canonical addresses and chain IDs.
+    - Support nickname setup and transaction categorization.
+    - Guarantee fast, immutable constants at runtime.
+
+This is the single source of truth for system-wide constants.
+"""
+
+from typing import Final
+
+import y.constants
+
+
+CHAINID: Final = y.constants.CHAINID
+# TODO: add docstring
+
+ZERO_ADDRESS: Final = "0x0000000000000000000000000000000000000000"
+# TODO: add docstring
+
+# TODO: move disperse.app stuff from yearn-treasury to dao-treasury and then write a docs file
+DISPERSE_APP: Final = (
+    "0xD152f549545093347A162Dce210e7293f1452150",
+    "0xd15fE25eD0Dba12fE05e7029C88b10C25e8880E3",
+)
+"""If your treasury sends funds to disperse.app, we create additional txs in the db so each individual send can be accounted for."""
+# TODO: all crosslink to disperse.py once ready