dao-treasury 0.0.41__cp310-cp310-win32.whl → 0.0.70__cp310-cp310-win32.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/_docker.py

@@ -14,17 +14,17 @@ 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"""
@@ -55,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])
 
 
@@ -72,6 +72,7 @@ def down() -> None:
     See Also:
         :func:`up`
     """
+    print("stopping all dao-treasury containers")
     _exec_command(["down"])
 
 
@@ -90,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")
 
@@ -174,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/constants.py

@@ -16,6 +16,7 @@ This is the single source of truth for system-wide constants.
 
 from typing import Final
 
+import eth_portfolio._utils
 import y.constants
 
 
@@ -32,3 +33,7 @@ DISPERSE_APP: Final = (
 )
 """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

@@ -18,12 +18,24 @@ 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
@@ -33,13 +45,14 @@ 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,
@@ -63,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."""
 
@@ -71,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
@@ -237,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:
@@ -407,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`.
@@ -721,6 +746,10 @@ class TreasuryTx(DbEntity):
         """Human-readable label for the sender address."""
         return self.from_address.nickname or self.from_address.address  # type: ignore [union-attr]
 
+    @property
+    def token_address(self) -> ChecksumAddress:
+        return self.token.address.address
+
     @property
     def symbol(self) -> str:
         """Ticker symbol for the transferred token."""
@@ -731,7 +760,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:
@@ -748,6 +793,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.
 

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",
@@ -119,6 +125,18 @@ parser.add_argument(
     help="Port for the Grafana rendering service. Default: 8091",
     default=8091,
 )
+parser.add_argument(
+    "--custom-bucket",
+    type=str,
+    action="append",
+    help=(
+        "Custom bucket mapping for a wallet address. "
+        "Specify as 'address:bucket_name'. "
+        "Can be used multiple times. Example: "
+        "--custom-bucket '0x123:My Bucket' --custom-bucket '0x456:Other Bucket'"
+    ),
+    default=None,
+)
 
 args = parser.parse_args()
 
@@ -203,7 +221,27 @@ async def export(args) -> None:
             for address in addresses:
                 db.Address.set_nickname(address, nickname)
 
-    treasury = Treasury(wallets, args.sort_rules, asynchronous=True)
+    # Parse custom_buckets from --custom-bucket arguments
+    custom_buckets = None
+    if args.custom_bucket:
+        custom_buckets = {}
+        for item in args.custom_bucket:
+            if ":" not in item:
+                parser.error(
+                    f"Invalid format for --custom-bucket: '{item}'. Must be 'address:bucket_name'."
+                )
+            address, bucket = item.split(":", 1)
+            address = address.strip()
+            bucket = bucket.strip()
+            if not address or not bucket:
+                parser.error(
+                    f"Invalid format for --custom-bucket: '{item}'. Both address and bucket_name are required."
+                )
+            custom_buckets[address] = bucket
+
+    treasury = Treasury(
+        wallets, args.sort_rules, custom_buckets=custom_buckets, asynchronous=True
+    )
 
     # Start only the requested containers
     if args.start_renderer is True: