dao-treasury 0.0.68__cp311-cp311-win32.whl

dao_treasury/_docker.py

@@ -0,0 +1,194 @@
+"""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 functools import wraps
+from importlib import resources
+from typing import Any, Callable, Coroutine, Final, Literal, Tuple, TypeVar, List
+
+import eth_portfolio_scripts.docker
+from eth_portfolio_scripts.docker import docker_compose
+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_notice("starting", services)
+    _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`
+    """
+    print("stopping all dao-treasury containers")
+    _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_notice("building", services)
+    _exec_command(["build", *services])
+
+
+def _print_notice(
+    doing: Literal["building", "starting"], services: Tuple[str, ...]
+) -> None:
+    if len(services) == 1:
+        container = services[0]
+        print(f"{doing} the {container} container")
+    elif len(services) == 2:
+        first, second = services
+        print(f"{doing} the {first} and {second} containers")
+    else:
+        *all_but_last, last = services
+        print(f"{doing} the {', '.join(all_but_last)}, and {last} containers")
+
+
+_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`
+    """
+    docker_compose._exec_command(
+        command, compose_file=COMPOSE_FILE, compose_options=compose_options
+    )

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,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."""