dao-treasury 0.0.17__cp312-cp312-win32.whl → 0.0.61__cp312-cp312-win32.whl

dao_treasury/_docker.py

@@ -1,42 +1,65 @@
+"""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
-import os
+from importlib import resources
 import subprocess
 from functools import wraps
-from typing import Callable, Iterable, Tuple, TypeVar
+from typing import Any, Callable, Coroutine, Final, Iterable, Tuple, TypeVar, List
 
-from eth_portfolio_scripts.docker import check_system
+import eth_portfolio_scripts.docker
 from typing_extensions import ParamSpec
 
-logger = logging.getLogger(__name__)
+logger: Final = logging.getLogger(__name__)
 
-compose_file = os.path.join(
-    os.path.dirname(os.path.abspath(__file__)), "docker-compose.yaml"
+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.
 
-def up() -> None:
-    """Build and start Grafana 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 them in detached mode using
+    :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 the grafana containers
+        starting all containers (grafana and renderer)
 
     See Also:
         :func:`build`
         :func:`down`
         :func:`_exec_command`
     """
-    build()
-    print("starting the grafana containers")
-    _exec_command(["up", "-d"])
+    # 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:
+def down() -> None:
     """Stop and remove Grafana containers.
 
     This function brings down the Docker Compose services defined
@@ -52,7 +75,7 @@ def down(*_) -> None:
     _exec_command(["down"])
 
 
-def build() -> None:
+def build(*services: str) -> None:
     """Build Docker images for Grafana containers.
 
     This function builds all services defined in the Docker Compose
@@ -68,14 +91,16 @@ def build() -> None:
         :func:`_exec_command`
     """
     print("building the grafana containers")
-    _exec_command(["build"])
+    _exec_command(["build", *services])
 
 
 _P = ParamSpec("_P")
 _T = TypeVar("_T")
 
 
-def ensure_containers(fn: Callable[_P, _T]) -> Callable[_P, _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
@@ -104,27 +129,27 @@ def ensure_containers(fn: Callable[_P, _T]) -> Callable[_P, _T]:
     """
 
     @wraps(fn)
-    async def compose_wrap(*args: _P.args, **kwargs: _P.kwargs):
+    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()
+        up("grafana")
 
         try:
             # attempt to run `fn`
-            await fn(*args, **kwargs)
+            return await fn(*args, **kwargs)
         finally:
             # stop and remove containers
             # down()
-            ...
+            pass
 
     return compose_wrap
 
 
-def _exec_command(command: Iterable[str], *, compose_options: Tuple[str] = ()) -> None:
+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
@@ -149,7 +174,7 @@ def _exec_command(command: Iterable[str], *, compose_options: Tuple[str] = ()) -
     See Also:
         :func:`check_system`
     """
-    check_system()
+    eth_portfolio_scripts.docker.check_system()
     try:
         subprocess.check_output(
             ["docker", "compose", *compose_options, "-f", compose_file, *command]

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

@@ -1,14 +1,20 @@
 from dataclasses import dataclass
-from typing import Dict, Final, Optional, final
+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
@@ -30,8 +36,13 @@ class TreasuryWallet:
     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:
-        self.address = EthAddress(self.address)
+        # 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
@@ -62,6 +73,23 @@ class TreasuryWallet:
             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
@@ -86,13 +114,137 @@ class TreasuryWallet:
     def _get_instance(address: HexAddress) -> Optional["TreasuryWallet"]:
         # sourcery skip: use-contextlib-suppress
         try:
-            return WALLETS[address]
-        except KeyError:
-            pass
-        checksummed = convert.to_address(address)
-        try:
-            instance = WALLETS[address] = WALLETS[checksummed]
+            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
-        else:
-            return instance
+        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,39 @@
+"""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 eth_portfolio._utils
+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
+
+
+SUPPRESS_ERROR_LOGS: Final = eth_portfolio._utils.SUPPRESS_ERROR_LOGS
+"""Append tokens here when you don't expect them to price successfully and do not want to see the associated error logs."""