dao-treasury 0.0.38__cp310-cp310-win_amd64.whl → 0.0.61__cp310-cp310-win_amd64.whl

dao_treasury/.grafana/provisioning/dashboards/treasury/Operating Cashflow.json

@@ -18,12 +18,13 @@
   "editable": true,
   "fiscalYearStartMonth": 0,
   "graphTooltip": 1,
+  "id": 6,
   "links": [],
-  "liveNow": false,
   "panels": [
     {
       "datasource": "SQLite",
       "fieldConfig": {
+        "unit": "currencyUSD",
         "defaults": {
           "color": {
             "mode": "thresholds"
@@ -34,7 +35,7 @@
             "steps": [
               {
                 "color": "green",
-                "value": null
+                "value": 0
               },
               {
                 "color": "red",
@@ -57,6 +58,7 @@
         "graphMode": "area",
         "justifyMode": "auto",
         "orientation": "auto",
+        "percentChangeColorMode": "standard",
         "reduceOptions": {
           "calcs": [
             "lastNotNull"
@@ -64,9 +66,11 @@
           "fields": "",
           "values": false
         },
-        "textMode": "auto"
+        "showPercentChange": false,
+        "textMode": "auto",
+        "wideLayout": true
       },
-      "pluginVersion": "10.2.0",
+      "pluginVersion": "12.1.1",
       "targets": [
         {
           "datasource": "SQLite",
@@ -86,6 +90,7 @@
     {
       "datasource": "SQLite",
       "fieldConfig": {
+        "unit": "currencyUSD",
         "defaults": {
           "color": {
             "mode": "thresholds"
@@ -96,7 +101,7 @@
             "steps": [
               {
                 "color": "green",
-                "value": null
+                "value": 0
               },
               {
                 "color": "red",
@@ -119,6 +124,7 @@
         "graphMode": "area",
         "justifyMode": "auto",
         "orientation": "auto",
+        "percentChangeColorMode": "standard",
         "reduceOptions": {
           "calcs": [
             "lastNotNull"
@@ -126,9 +132,11 @@
           "fields": "",
           "values": false
         },
-        "textMode": "auto"
+        "showPercentChange": false,
+        "textMode": "auto",
+        "wideLayout": true
       },
-      "pluginVersion": "10.2.0",
+      "pluginVersion": "12.1.1",
       "targets": [
         {
           "datasource": "SQLite",
@@ -148,6 +156,7 @@
     {
       "datasource": "SQLite",
       "fieldConfig": {
+        "unit": "currencyUSD",
         "defaults": {
           "color": {
             "mode": "thresholds"
@@ -158,7 +167,7 @@
             "steps": [
               {
                 "color": "green",
-                "value": null
+                "value": 0
               },
               {
                 "color": "red",
@@ -181,6 +190,7 @@
         "graphMode": "area",
         "justifyMode": "auto",
         "orientation": "auto",
+        "percentChangeColorMode": "standard",
         "reduceOptions": {
           "calcs": [
             "lastNotNull"
@@ -188,9 +198,11 @@
           "fields": "",
           "values": false
         },
-        "textMode": "auto"
+        "showPercentChange": false,
+        "textMode": "auto",
+        "wideLayout": true
       },
-      "pluginVersion": "10.2.0",
+      "pluginVersion": "12.1.1",
       "targets": [
         {
           "datasource": "SQLite",
@@ -211,6 +223,7 @@
       "datasource": "SQLite",
       "description": "",
       "fieldConfig": {
+        "unit": "currencyUSD",
         "defaults": {
           "color": {
             "mode": "thresholds"
@@ -221,7 +234,7 @@
             "steps": [
               {
                 "color": "green",
-                "value": null
+                "value": 0
               },
               {
                 "color": "red",
@@ -244,6 +257,7 @@
         "graphMode": "area",
         "justifyMode": "auto",
         "orientation": "auto",
+        "percentChangeColorMode": "standard",
         "reduceOptions": {
           "calcs": [
             "lastNotNull"
@@ -251,9 +265,11 @@
           "fields": "",
           "values": false
         },
-        "textMode": "auto"
+        "showPercentChange": false,
+        "textMode": "auto",
+        "wideLayout": true
       },
-      "pluginVersion": "10.2.0",
+      "pluginVersion": "12.1.1",
       "targets": [
         {
           "datasource": "SQLite",
@@ -274,6 +290,7 @@
       "datasource": "SQLite",
       "description": "",
       "fieldConfig": {
+        "unit": "currencyUSD",
         "defaults": {
           "color": {
             "mode": "palette-classic"
@@ -285,6 +302,7 @@
             "axisLabel": "",
             "axisPlacement": "auto",
             "barAlignment": 0,
+            "barWidthFactor": 0.6,
             "drawStyle": "bars",
             "fillOpacity": 70,
             "gradientMode": "none",
@@ -316,7 +334,7 @@
             "steps": [
               {
                 "color": "green",
-                "value": null
+                "value": 0
               },
               {
                 "color": "red",
@@ -366,10 +384,12 @@
           "showLegend": true
         },
         "tooltip": {
+          "hideZeros": false,
           "mode": "single",
           "sort": "none"
         }
       },
+      "pluginVersion": "12.1.1",
       "targets": [
         {
           "datasource": "SQLite",
@@ -473,8 +493,9 @@
       "type": "timeseries"
     }
   ],
+  "preload": false,
   "refresh": "",
-  "schemaVersion": 38,
+  "schemaVersion": 41,
   "tags": [],
   "templating": {
     "list": []
@@ -486,7 +507,7 @@
   "timepicker": {},
   "timezone": "",
   "title": "Operating Cashflow Summary",
+  "description": "Provides a focused view of core operational cashflows, including only sorted transactions in Revenue, Cost of Revenue, and Expenses categories. Excludes unsorted transactions and non-operational activity, helping monitor specifically the DAO's operational financial flows.",
   "uid": "fdf9969c-357a-4203-ae7b-12816e87bc7e",
-  "version": 1,
-  "weekStart": ""
+  "version": 5
 }

dao_treasury/ENVIRONMENT_VARIABLES.py

@@ -1,3 +1,15 @@
+"""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

dao_treasury/__init__.py

@@ -1,3 +1,17 @@
+"""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

dao_treasury/_docker.py

@@ -1,4 +1,17 @@
-"""This module contains utilities for managing dao-treasury's docker containers"""
+"""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

dao_treasury/_nicknames.py

@@ -1,3 +1,18 @@
+"""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

dao_treasury/constants.py

@@ -1,11 +1,30 @@
+"""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 = (
@@ -13,3 +32,8 @@ DISPERSE_APP: Final = (
     "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."""

dao_treasury/db.py

@@ -3,6 +3,7 @@
 Database models and utilities for DAO treasury reporting.
 
 This module defines Pony ORM entities for:
+
 - Blockchain networks (:class:`Chain`)
 - On-chain addresses (:class:`Address`)
 - ERC-20 tokens and native coin placeholder (:class:`Token`)
@@ -17,27 +18,41 @@ and creating SQL views for reporting.
 
 import typing
 from asyncio import Semaphore
+from collections import OrderedDict
 from decimal import Decimal, InvalidOperation
 from functools import lru_cache
 from logging import getLogger
 from os import path
 from pathlib import Path
-from typing import TYPE_CHECKING, Dict, Final, Tuple, Union, final
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Coroutine,
+    Dict,
+    Final,
+    Literal,
+    Tuple,
+    Union,
+    final,
+    overload,
+)
 from datetime import date, datetime, time, timezone
 
+import eth_portfolio
 from a_sync import AsyncThreadPoolExecutor
 from brownie import chain
 from brownie.convert.datatypes import HexString
 from brownie.exceptions import EventLookupError
 from brownie.network.event import EventDict, _EventItem
 from brownie.network.transaction import TransactionReceipt
-from eth_typing import ChecksumAddress, HexAddress, HexStr
 from eth_portfolio.structs import (
     InternalTransfer,
     LedgerEntry,
     TokenTransfer,
     Transaction,
 )
+from eth_retry import auto_retry
+from eth_typing import ChecksumAddress, HexAddress, HexStr
 from pony.orm import (
     Database,
     InterfaceError,
@@ -61,6 +76,9 @@ from dao_treasury.constants import CHAINID
 from dao_treasury.types import TxGroupDbid, TxGroupName
 
 
+EventItem = _EventItem[_EventItem[OrderedDict[str, Any]]]
+
+
 SQLITE_DIR = Path(path.expanduser("~")) / ".dao-treasury"
 """Path to the directory in the user's home where the DAO treasury SQLite database is stored."""
 
@@ -69,6 +87,7 @@ SQLITE_DIR.mkdir(parents=True, exist_ok=True)
 
 _INSERT_THREAD = AsyncThreadPoolExecutor(1)
 _SORT_THREAD = AsyncThreadPoolExecutor(1)
+_EVENTS_THREADS = AsyncThreadPoolExecutor(16)
 _SORT_SEMAPHORE = Semaphore(50)
 
 _UTC = timezone.utc
@@ -235,6 +254,10 @@ class Address(DbEntity):
     def contract(self) -> Contract:
         return Contract(self.address)
 
+    @property
+    def contract_coro(self) -> Coroutine[Any, Any, Contract]:
+        return Contract.coroutine(self.address)
+
     @staticmethod
     @lru_cache(maxsize=None)
     def get_dbid(address: HexAddress) -> int:
@@ -405,6 +428,10 @@ class Token(DbEntity):
     def contract(self) -> Contract:
         return Contract(self.address.address)
 
+    @property
+    def contract_coro(self) -> Coroutine[Any, Any, Contract]:
+        return Contract.coroutine(self.address.address)
+
     @property
     def scale(self) -> int:
         """Base for division according to `decimals`, e.g., `10**decimals`.
@@ -729,7 +756,23 @@ class TreasuryTx(DbEntity):
         """Decoded event logs for this transaction."""
         return self._transaction.events
 
-    def get_events(self, event_name: str) -> _EventItem:
+    async def events_async(self) -> EventDict:
+        """Asynchronously fetch decoded event logs for this transaction."""
+        tx = self._transaction
+        events = tx._events
+        if events is None:
+            events = await _EVENTS_THREADS.run(getattr, tx, "events")
+        return events
+
+    @overload
+    def get_events(
+        self, event_name: str, sync: Literal[False]
+    ) -> Coroutine[Any, Any, EventItem]: ...
+    @overload
+    def get_events(self, event_name: str, sync: bool = True) -> EventItem: ...
+    def get_events(self, event_name: str, sync: bool = True) -> EventItem:
+        if not sync:
+            return _EVENTS_THREADS.run(self.get_events, event_name)
         try:
             return self.events[event_name]
         except EventLookupError:
@@ -746,6 +789,7 @@ class TreasuryTx(DbEntity):
         return get_transaction(self.hash)
 
     @staticmethod
+    @auto_retry
     async def insert(entry: LedgerEntry) -> None:
         """Asynchronously insert and sort a ledger entry.
 
@@ -1383,3 +1427,24 @@ def _validate_integrity_error(
         )
         else None
     )
+
+
+def _drop_shitcoin_txs() -> None:
+    """
+    Purge any shitcoin txs from the db.
+
+    These should not be frequent, and only occur if a user populated the db before a shitcoin was added to the SHITCOINS mapping.
+    """
+    shitcoins = eth_portfolio.SHITCOINS[CHAINID]
+    with db_session:
+        shitcoin_txs = select(
+            tx for tx in TreasuryTx if tx.token.address.address in shitcoins
+        )
+        if count := shitcoin_txs.count():
+            logger.info(f"Purging {count} shitcoin txs from the database...")
+            for tx in shitcoin_txs:
+                tx.delete()
+            logger.info("Shitcoin tx purge complete.")
+
+
+_drop_shitcoin_txs()

dao_treasury/docker-compose.yaml

@@ -5,7 +5,7 @@ networks:
 
 services:
   grafana:
-    image: grafana/grafana:10.2.0
+    image: grafana/grafana:12.2.1
     ports:
       - 127.0.0.1:${DAO_TREASURY_GRAFANA_PORT:-3004}:3000
     environment:

dao_treasury/main.py

@@ -97,6 +97,12 @@ parser.add_argument(
     help="The time interval between datapoints. default: 1d",
     default="1d",
 )
+parser.add_argument(
+    "--concurrency",
+    type=int,
+    help="The max number of historical blocks to export concurrently. default: 30",
+    default=30,
+)
 parser.add_argument(
     "--daemon",
     action="store_true",

dao_treasury/sorting/rule.py

@@ -130,8 +130,6 @@ class _SortRule:
     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.
 
@@ -235,7 +233,7 @@ class _InboundSortRule(_SortRule):
         return (
             tx.to_address is not None
             and TreasuryWallet.check_membership(tx.to_address.address, tx.block)
-            and await super().match(tx)
+            and await super(_InboundSortRule, self).match(tx)
         )
 
 
@@ -250,7 +248,7 @@ class _OutboundSortRule(_SortRule):
     async def match(self, tx: "TreasuryTx") -> bool:
         return TreasuryWallet.check_membership(
             tx.from_address.address, tx.block
-        ) and await super().match(tx)
+        ) and await super(_OutboundSortRule, self).match(tx)
 
 
 @mypyc_attr(native_class=False)
@@ -267,7 +265,7 @@ class RevenueSortRule(_InboundSortRule):
     def __post_init__(self) -> None:
         """Prepends `self.txgroup` with 'Revenue:'."""
         object.__setattr__(self, "txgroup", f"Revenue:{self.txgroup}")
-        super().__post_init__()
+        super(RevenueSortRule, self).__post_init__()
 
 
 @mypyc_attr(native_class=False)
@@ -280,7 +278,7 @@ class CostOfRevenueSortRule(_OutboundSortRule):
     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__()
+        super(CostOfRevenueSortRule, self).__post_init__()
 
 
 @mypyc_attr(native_class=False)
@@ -293,7 +291,7 @@ class ExpenseSortRule(_OutboundSortRule):
     def __post_init__(self) -> None:
         """Prepends `self.txgroup` with 'Expenses:'."""
         object.__setattr__(self, "txgroup", f"Expenses:{self.txgroup}")
-        super().__post_init__()
+        super(ExpenseSortRule, self).__post_init__()
 
 
 @mypyc_attr(native_class=False)
@@ -306,7 +304,7 @@ class OtherIncomeSortRule(_InboundSortRule):
     def __post_init__(self) -> None:
         """Prepends `self.txgroup` with 'Other Income:'."""
         object.__setattr__(self, "txgroup", f"Other Income:{self.txgroup}")
-        super().__post_init__()
+        super(OtherIncomeSortRule, self).__post_init__()
 
 
 @mypyc_attr(native_class=False)
@@ -319,7 +317,7 @@ class OtherExpenseSortRule(_OutboundSortRule):
     def __post_init__(self) -> None:
         """Prepends `self.txgroup` with 'Other Expenses:'."""
         object.__setattr__(self, "txgroup", f"Other Expenses:{self.txgroup}")
-        super().__post_init__()
+        super(OtherExpenseSortRule, self).__post_init__()
 
 
 @mypyc_attr(native_class=False)
@@ -332,7 +330,7 @@ class IgnoreSortRule(_SortRule):
     def __post_init__(self) -> None:
         """Prepends `self.txgroup` with 'Ignore:'."""
         object.__setattr__(self, "txgroup", f"Ignore:{self.txgroup}")
-        super().__post_init__()
+        super(IgnoreSortRule, self).__post_init__()
 
 
 TRule = TypeVar(

dao_treasury/streams/llamapay.py

@@ -22,7 +22,7 @@ from eth_typing import BlockNumber, ChecksumAddress, HexAddress, HexStr
 from tqdm.asyncio import tqdm_asyncio
 
 import y
-from y.time import UnixTimestamp
+from y.time import NoBlockFound, UnixTimestamp
 from y.utils.events import decode_logs, get_logs_asap
 
 from dao_treasury import constants
@@ -338,7 +338,19 @@ class LlamaPayProcessor:
         check_at = date_obj + timedelta(days=1) - timedelta(seconds=1)
         if check_at > now(tz=_UTC):
             await sleep((check_at - now(tz=_UTC)).total_seconds())
-        block = await get_block_at_timestamp(check_at, sync=False)
+
+        while True:
+            try:
+                block = await get_block_at_timestamp(check_at, sync=False)
+            except NoBlockFound:
+                sleep_time = (check_at - now(tz=_UTC)).total_seconds()
+                logger.debug(
+                    "no block found for %s, sleeping %ss", check_at, sleep_time
+                )
+                await sleep(sleep_time)
+            else:
+                break
+
         price_fut = create_task(get_price(stream_token, block, sync=False))
         start_timestamp = await _get_start_timestamp(stream_id, block)
         if start_timestamp == 0: