dao-treasury 0.0.37__cp310-cp310-macosx_11_0_arm64.whl → 0.0.69__cp310-cp310-macosx_11_0_arm64.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,16 +58,17 @@
         "graphMode": "area",
         "justifyMode": "auto",
         "orientation": "auto",
+        "percentChangeColorMode": "standard",
         "reduceOptions": {
-          "calcs": [
-            "lastNotNull"
-          ],
+          "calcs": ["lastNotNull"],
           "fields": "",
           "values": false
         },
-        "textMode": "auto"
+        "showPercentChange": false,
+        "textMode": "auto",
+        "wideLayout": true
       },
-      "pluginVersion": "10.2.0",
+      "pluginVersion": "12.1.1",
       "targets": [
         {
           "datasource": "SQLite",
@@ -74,18 +76,17 @@
           "queryType": "table",
           "rawQueryText": "SELECT SUM(t.value_usd) AS total_revenue FROM general_ledger t JOIN txgroup_hierarchy gh USING (txgroup_id) WHERE gh.top_category = 'Revenue' AND t.timestamp >= $__from/1000 AND t.timestamp <= $__to/1000",
           "refId": "A",
-          "timeColumns": [
-            "time",
-            "ts"
-          ]
+          "timeColumns": ["time", "ts"]
         }
       ],
       "title": "Revenue",
-      "type": "stat"
+      "type": "stat",
+      "description": "Displays the total value of all transactions sorted as Revenue for the selected period."
     },
     {
       "datasource": "SQLite",
       "fieldConfig": {
+        "unit": "currencyUSD",
         "defaults": {
           "color": {
             "mode": "thresholds"
@@ -96,7 +97,7 @@
             "steps": [
               {
                 "color": "green",
-                "value": null
+                "value": 0
               },
               {
                 "color": "red",
@@ -119,16 +120,17 @@
         "graphMode": "area",
         "justifyMode": "auto",
         "orientation": "auto",
+        "percentChangeColorMode": "standard",
         "reduceOptions": {
-          "calcs": [
-            "lastNotNull"
-          ],
+          "calcs": ["lastNotNull"],
           "fields": "",
           "values": false
         },
-        "textMode": "auto"
+        "showPercentChange": false,
+        "textMode": "auto",
+        "wideLayout": true
       },
-      "pluginVersion": "10.2.0",
+      "pluginVersion": "12.1.1",
       "targets": [
         {
           "datasource": "SQLite",
@@ -136,18 +138,17 @@
           "queryType": "table",
           "rawQueryText": "SELECT SUM(t.value_usd) AS total_revenue FROM general_ledger t JOIN txgroup_hierarchy gh USING (txgroup_id) WHERE gh.top_category = 'Cost of Revenue' AND t.timestamp >= $__from/1000 AND t.timestamp <= $__to/1000",
           "refId": "A",
-          "timeColumns": [
-            "time",
-            "ts"
-          ]
+          "timeColumns": ["time", "ts"]
         }
       ],
       "title": "Cost of Revenue",
-      "type": "stat"
+      "type": "stat",
+      "description": "Displays the total value of all transactions sorted as Cost of Revenue for the selected period."
     },
     {
       "datasource": "SQLite",
       "fieldConfig": {
+        "unit": "currencyUSD",
         "defaults": {
           "color": {
             "mode": "thresholds"
@@ -158,7 +159,7 @@
             "steps": [
               {
                 "color": "green",
-                "value": null
+                "value": 0
               },
               {
                 "color": "red",
@@ -181,16 +182,17 @@
         "graphMode": "area",
         "justifyMode": "auto",
         "orientation": "auto",
+        "percentChangeColorMode": "standard",
         "reduceOptions": {
-          "calcs": [
-            "lastNotNull"
-          ],
+          "calcs": ["lastNotNull"],
           "fields": "",
           "values": false
         },
-        "textMode": "auto"
+        "showPercentChange": false,
+        "textMode": "auto",
+        "wideLayout": true
       },
-      "pluginVersion": "10.2.0",
+      "pluginVersion": "12.1.1",
       "targets": [
         {
           "datasource": "SQLite",
@@ -198,19 +200,18 @@
           "queryType": "table",
           "rawQueryText": "SELECT SUM(t.value_usd) AS total_revenue FROM general_ledger t JOIN txgroup_hierarchy gh USING (txgroup_id) WHERE gh.top_category = 'Expenses' AND t.timestamp >= $__from/1000 AND t.timestamp <= $__to/1000",
           "refId": "A",
-          "timeColumns": [
-            "time",
-            "ts"
-          ]
+          "timeColumns": ["time", "ts"]
         }
       ],
       "title": "Expenses",
-      "type": "stat"
+      "type": "stat",
+      "description": "Displays the total value of all transactions sorted as Expenses for the selected period."
     },
     {
       "datasource": "SQLite",
-      "description": "",
+      "description": "Shows the net operating cashflow (Revenue minus Cost of Revenue and Expenses) for the selected period.",
       "fieldConfig": {
+        "unit": "currencyUSD",
         "defaults": {
           "color": {
             "mode": "thresholds"
@@ -221,7 +222,7 @@
             "steps": [
               {
                 "color": "green",
-                "value": null
+                "value": 0
               },
               {
                 "color": "red",
@@ -244,16 +245,17 @@
         "graphMode": "area",
         "justifyMode": "auto",
         "orientation": "auto",
+        "percentChangeColorMode": "standard",
         "reduceOptions": {
-          "calcs": [
-            "lastNotNull"
-          ],
+          "calcs": ["lastNotNull"],
           "fields": "",
           "values": false
         },
-        "textMode": "auto"
+        "showPercentChange": false,
+        "textMode": "auto",
+        "wideLayout": true
       },
-      "pluginVersion": "10.2.0",
+      "pluginVersion": "12.1.1",
       "targets": [
         {
           "datasource": "SQLite",
@@ -261,10 +263,7 @@
           "queryType": "table",
           "rawQueryText": "SELECT (\n  SUM(CASE WHEN gh.top_category = 'Revenue' THEN t.value_usd ELSE 0 END)\n  - SUM(CASE WHEN gh.top_category = 'Cost of Revenue' THEN t.value_usd ELSE 0 END)\n  - SUM(CASE WHEN gh.top_category = 'Expenses' THEN t.value_usd ELSE 0 END)\n) AS total_net\nFROM general_ledger t\nJOIN txgroup_hierarchy gh USING (txgroup_id)\nWHERE t.timestamp >= $__from/1000 AND t.timestamp <= $__to/1000",
           "refId": "A",
-          "timeColumns": [
-            "time",
-            "ts"
-          ]
+          "timeColumns": ["time", "ts"]
         }
       ],
       "title": "Operating Total",
@@ -272,8 +271,9 @@
     },
     {
       "datasource": "SQLite",
-      "description": "",
+      "description": "Time series chart of all sorted operational cashflows, grouped by category, for the selected period. Shows Total Revenue, Total Expenses, and Net for each week, helping to analyze trends in the DAO's operational financial flows over time.",
       "fieldConfig": {
+        "unit": "currencyUSD",
         "defaults": {
           "color": {
             "mode": "palette-classic"
@@ -285,6 +285,7 @@
             "axisLabel": "",
             "axisPlacement": "auto",
             "barAlignment": 0,
+            "barWidthFactor": 0.6,
             "drawStyle": "bars",
             "fillOpacity": 70,
             "gradientMode": "none",
@@ -316,7 +317,7 @@
             "steps": [
               {
                 "color": "green",
-                "value": null
+                "value": 0
               },
               {
                 "color": "red",
@@ -366,10 +367,12 @@
           "showLegend": true
         },
         "tooltip": {
+          "hideZeros": false,
           "mode": "single",
           "sort": "none"
         }
       },
+      "pluginVersion": "12.1.1",
       "targets": [
         {
           "datasource": "SQLite",
@@ -377,9 +380,7 @@
           "queryType": "table",
           "rawQueryText": "SELECT t.timestamp,\r\n       SUM(CASE WHEN gh.top_category = 'Revenue' THEN t.value_usd ELSE 0 END) AS \"Total Revenue\",\r\n       SUM(CASE WHEN gh.top_category in ('Cost of Revenue','Expenses') THEN t.value_usd ELSE 0 END) * -1 AS \"Total Expenses\",\r\n       SUM(CASE WHEN gh.top_category = 'Revenue' THEN t.value_usd ELSE 0 END) - SUM(CASE WHEN gh.top_category in ('Cost of Revenue','Expenses') THEN t.value_usd ELSE 0 END) AS \"Net\"\r\nFROM general_ledger AS t\r\nJOIN txgroup_hierarchy gh ON t.txgroup_id = gh.txgroup_id\r\nWHERE t.timestamp >= $__from/1000 AND t.timestamp <= $__to/1000\r\nGROUP BY timestamp\r\nORDER BY timestamp;",
           "refId": "A",
-          "timeColumns": [
-            "timestamp"
-          ]
+          "timeColumns": ["timestamp"]
         }
       ],
       "title": "Weekly Cashflow",
@@ -411,39 +412,27 @@
           "options": {
             "fields": {
               "Cost of Revenue": {
-                "aggregations": [
-                  "sum"
-                ],
+                "aggregations": ["sum"],
                 "operation": "aggregate"
               },
               "Expenses": {
-                "aggregations": [
-                  "sum"
-                ],
+                "aggregations": ["sum"],
                 "operation": "aggregate"
               },
               "Net": {
-                "aggregations": [
-                  "sum"
-                ],
+                "aggregations": ["sum"],
                 "operation": "aggregate"
               },
               "Other Expenses": {
-                "aggregations": [
-                  "sum"
-                ],
+                "aggregations": ["sum"],
                 "operation": "aggregate"
               },
               "Other Income": {
-                "aggregations": [
-                  "sum"
-                ],
+                "aggregations": ["sum"],
                 "operation": "aggregate"
               },
               "Revenue": {
-                "aggregations": [
-                  "sum"
-                ],
+                "aggregations": ["sum"],
                 "operation": "aggregate"
               },
               "Timestamp": {
@@ -451,15 +440,11 @@
                 "operation": "groupby"
               },
               "Total Expenses": {
-                "aggregations": [
-                  "sum"
-                ],
+                "aggregations": ["sum"],
                 "operation": "aggregate"
               },
               "Total Revenue": {
-                "aggregations": [
-                  "sum"
-                ],
+                "aggregations": ["sum"],
                 "operation": "aggregate"
               },
               "timestamp": {
@@ -473,9 +458,10 @@
       "type": "timeseries"
     }
   ],
+  "preload": false,
   "refresh": "",
-  "schemaVersion": 38,
-  "tags": [],
+  "schemaVersion": 41,
+  "tags": ["cashflow", "operating"],
   "templating": {
     "list": []
   },
@@ -486,7 +472,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": 7
 }

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,17 +1,30 @@
-"""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
-import subprocess
 from functools import wraps
-from typing import Any, Callable, Coroutine, Final, Iterable, Tuple, TypeVar, List
+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(
+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"""
@@ -42,7 +55,7 @@ def up(*services: str) -> None:
     # 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)")
+    _print_notice("starting", services)
     _exec_command(["up", "-d", *services])
 
 
@@ -59,6 +72,7 @@ def down() -> None:
     See Also:
         :func:`up`
     """
+    print("stopping all dao-treasury containers")
     _exec_command(["down"])
 
 
@@ -77,10 +91,24 @@ def build(*services: str) -> None:
         :func:`up`
         :func:`_exec_command`
     """
-    print("building the grafana containers")
+    _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")
 
@@ -161,17 +189,6 @@ def _exec_command(command: List[str], *, compose_options: Tuple[str, ...] = ())
     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
+    docker_compose._exec_command(
+        command, compose_file=COMPOSE_FILE, compose_options=compose_options
+    )

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