dao-treasury 0.0.35__cp311-cp311-win_amd64.whl → 0.1.1__cp311-cp311-win_amd64.whl

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

@@ -18,11 +18,11 @@
   "editable": true,
   "fiscalYearStartMonth": 0,
   "graphTooltip": 1,
+  "id": 6,
   "links": [],
-  "liveNow": false,
   "panels": [
     {
-      "datasource": "SQLite",
+      "datasource": "PostgreSQL",
       "fieldConfig": {
         "defaults": {
           "color": {
@@ -34,14 +34,15 @@
             "steps": [
               {
                 "color": "green",
-                "value": null
+                "value": 0
               },
               {
                 "color": "red",
                 "value": 80
               }
             ]
-          }
+          },
+          "unit": "currencyUSD"
         },
         "overrides": []
       },
@@ -57,34 +58,32 @@
         "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",
-          "queryText": "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",
-          "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",
+          "datasource": "PostgreSQL",
+          "format": "table",
+          "rawSql": "SELECT SUM(p.value_usd) AS total_revenue FROM usdvalue_presum p JOIN txgroup_hierarchy gh USING (txgroup_id) WHERE gh.top_category = 'Revenue' AND p.timestamp >= $__from/1000 AND p.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",
+      "datasource": "PostgreSQL",
       "fieldConfig": {
         "defaults": {
           "color": {
@@ -96,14 +95,15 @@
             "steps": [
               {
                 "color": "green",
-                "value": null
+                "value": 0
               },
               {
                 "color": "red",
                 "value": 80
               }
             ]
-          }
+          },
+          "unit": "currencyUSD"
         },
         "overrides": []
       },
@@ -119,34 +119,32 @@
         "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",
-          "queryText": "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",
-          "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",
+          "datasource": "PostgreSQL",
+          "format": "table",
+          "rawSql": "SELECT SUM(p.value_usd) AS total_revenue FROM usdvalue_presum p JOIN txgroup_hierarchy gh USING (txgroup_id) WHERE gh.top_category = 'Cost of Revenue' AND p.timestamp >= $__from/1000 AND p.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",
+      "datasource": "PostgreSQL",
       "fieldConfig": {
         "defaults": {
           "color": {
@@ -158,14 +156,15 @@
             "steps": [
               {
                 "color": "green",
-                "value": null
+                "value": 0
               },
               {
                 "color": "red",
                 "value": 80
               }
             ]
-          }
+          },
+          "unit": "currencyUSD"
         },
         "overrides": []
       },
@@ -181,35 +180,33 @@
         "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",
-          "queryText": "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",
-          "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",
+          "datasource": "PostgreSQL",
+          "format": "table",
+          "rawSql": "SELECT SUM(p.value_usd) AS total_revenue FROM usdvalue_presum p JOIN txgroup_hierarchy gh USING (txgroup_id) WHERE gh.top_category = 'Expenses' AND p.timestamp >= $__from/1000 AND p.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": "",
+      "datasource": "PostgreSQL",
+      "description": "Shows the net operating cashflow (Revenue minus Cost of Revenue and Expenses) for the selected period.",
       "fieldConfig": {
         "defaults": {
           "color": {
@@ -221,14 +218,15 @@
             "steps": [
               {
                 "color": "green",
-                "value": null
+                "value": 0
               },
               {
                 "color": "red",
                 "value": 80
               }
             ]
-          }
+          },
+          "unit": "currencyUSD"
         },
         "overrides": []
       },
@@ -244,35 +242,32 @@
         "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",
-          "queryText": "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",
-          "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",
+          "datasource": "PostgreSQL",
+          "format": "table",
+          "rawSql": "SELECT (\n  SUM(CASE WHEN gh.top_category = 'Revenue' THEN p.value_usd ELSE 0 END)\n  - SUM(CASE WHEN gh.top_category = 'Cost of Revenue' THEN p.value_usd ELSE 0 END)\n  - SUM(CASE WHEN gh.top_category = 'Expenses' THEN p.value_usd ELSE 0 END)\n) AS total_net\nFROM usdvalue_presum p\nJOIN txgroup_hierarchy gh USING (txgroup_id)\nWHERE p.timestamp >= $__from/1000 AND p.timestamp <= $__to/1000",
           "refId": "A",
-          "timeColumns": [
-            "time",
-            "ts"
-          ]
+          "timeColumns": ["time", "ts"]
         }
       ],
       "title": "Operating Total",
       "type": "stat"
     },
     {
-      "datasource": "SQLite",
-      "description": "",
+      "datasource": "PostgreSQL",
+      "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": {
         "defaults": {
           "color": {
@@ -285,6 +280,7 @@
             "axisLabel": "",
             "axisPlacement": "auto",
             "barAlignment": 0,
+            "barWidthFactor": 0.6,
             "drawStyle": "bars",
             "fillOpacity": 70,
             "gradientMode": "none",
@@ -316,14 +312,15 @@
             "steps": [
               {
                 "color": "green",
-                "value": null
+                "value": 0
               },
               {
                 "color": "red",
                 "value": 80
               }
             ]
-          }
+          },
+          "unit": "currencyUSD"
         },
         "overrides": [
           {
@@ -366,20 +363,19 @@
           "showLegend": true
         },
         "tooltip": {
+          "hideZeros": false,
           "mode": "single",
           "sort": "none"
         }
       },
+      "pluginVersion": "12.1.1",
       "targets": [
         {
-          "datasource": "SQLite",
-          "queryText": "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;",
-          "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;",
+          "datasource": "PostgreSQL",
+          "format": "table",
+          "rawSql": "SELECT to_timestamp(p.timestamp) AS \"timestamp\", SUM(CASE WHEN gh.top_category = 'Revenue' THEN p.value_usd ELSE 0 END) AS \"Total Revenue\", SUM(CASE WHEN gh.top_category in ('Cost of Revenue','Expenses') THEN p.value_usd ELSE 0 END) * -1 AS \"Total Expenses\", SUM(CASE WHEN gh.top_category = 'Revenue' THEN p.value_usd ELSE 0 END) - SUM(CASE WHEN gh.top_category in ('Cost of Revenue','Expenses') THEN p.value_usd ELSE 0 END) AS \"Net\" FROM usdvalue_presum AS p JOIN txgroup_hierarchy gh ON p.txgroup_id = gh.txgroup_id WHERE p.timestamp >= $__from/1000 AND p.timestamp <= $__to/1000 GROUP BY timestamp ORDER BY timestamp;",
           "refId": "A",
-          "timeColumns": [
-            "timestamp"
-          ]
+          "timeColumns": ["timestamp"]
         }
       ],
       "title": "Weekly Cashflow",
@@ -411,39 +407,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 +435,11 @@
                 "operation": "groupby"
               },
               "Total Expenses": {
-                "aggregations": [
-                  "sum"
-                ],
+                "aggregations": ["sum"],
                 "operation": "aggregate"
               },
               "Total Revenue": {
-                "aggregations": [
-                  "sum"
-                ],
+                "aggregations": ["sum"],
                 "operation": "aggregate"
               },
               "timestamp": {
@@ -473,9 +453,10 @@
       "type": "timeseries"
     }
   ],
+  "preload": false,
   "refresh": "",
-  "schemaVersion": 38,
-  "tags": [],
+  "schemaVersion": 41,
+  "tags": ["cashflow", "operating"],
   "templating": {
     "list": []
   },
@@ -486,7 +467,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": 105
 }

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

@@ -1,13 +1,18 @@
 apiVersion: 1
 
 datasources:
-- name: SQLite
-  type: frser-sqlite-datasource
+- name: PostgreSQL
+  type: postgres
   isDefault: true
   editable: false
+  url: postgres:5432
+  user: dao_treasury
   jsonData:
-    path: /app/dao-treasury-data/dao-treasury.sqlite
-  secureJsonData: {}
+    database: dao_treasury
+    sslmode: "disable"
+    postgresVersion: 1801
+  secureJsonData:
+    password: dao_treasury
 
 - name: 'PROMETHEUS'
   type: 'prometheus'

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,5 +1,18 @@
+"""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 (
@@ -20,9 +33,6 @@ from dao_treasury.sorting import (
 from dao_treasury.treasury import Treasury
 
 
-setup_address_nicknames_in_db()
-
-
 if ENVS.SQL_DEBUG:
     import pony.orm
 

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"""
@@ -39,10 +52,14 @@ def up(*services: str) -> None:
         :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")
+    # the proper envs for victoria-metrics arent set yet when we need to start up the postgres container,
+    # but they're ready by the time we start the other containers
+    if services != ("postgres",):
+        # 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 +76,7 @@ def down() -> None:
     See Also:
         :func:`up`
     """
+    print("stopping all dao-treasury containers")
     _exec_command(["down"])
 
 
@@ -77,10 +95,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 +193,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,17 +1,33 @@
+"""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
+from dao_treasury.db import Address, init_db, set_address_nicknames_for_tokens
 
 
 set_nickname: Final = Address.set_nickname
 
 
 def setup_address_nicknames_in_db() -> None:
+    init_db()
     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()
+        set_address_nicknames_for_tokens()