dao-treasury 0.0.42__cp311-cp311-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl

dao_treasury/types.py

@@ -0,0 +1,133 @@
+from typing import TYPE_CHECKING, Awaitable, Callable, Iterable, Literal, NewType, Union
+
+from y import Network
+
+if TYPE_CHECKING:
+    from dao_treasury.db import TreasuryTx
+    from dao_treasury.sorting.rule import (
+        CostOfRevenueSortRule,
+        ExpenseSortRule,
+        IgnoreSortRule,
+        OtherExpenseSortRule,
+        OtherIncomeSortRule,
+        RevenueSortRule,
+    )
+
+
+Networks = Union[Network, Iterable[Network]]
+"""Type alias for specifying one or more blockchain networks.
+
+This can be a single :class:`~y.networks.Network` enum member or any iterable
+of such members. It is used to restrict operations to specific networks when
+configuring or querying treasury data.
+
+Examples:
+    Specify a single network:
+        >>> net: Networks = Network.Mainnet
+
+    Specify multiple networks:
+        >>> nets: Networks = [Network.Mainnet, Network.Optimism]
+
+See Also:
+    :class:`~y.networks.Network`
+"""
+
+
+TopLevelCategory = Literal[
+    "Revenue",
+    "Cost of Revenue",
+    "Expenses",
+    "Other Income",
+    "Other Expenses",
+    "Ignore",
+]
+"""Literal type defining the allowed top‐level categories for treasury transactions.
+
+Each transaction must be assigned to one of these categories in order to
+generate financial reports.
+
+Examples:
+    Grouping a transaction as revenue:
+        >>> cat: TopLevelCategory = "Revenue"
+
+    Ignoring a transaction:
+        >>> cat: TopLevelCategory = "Ignore"
+"""
+
+
+TxGroupDbid = NewType("TxGroupDbid", int)
+"""NewType representing the primary key of a transaction group in the database.
+
+This is the integer identifier returned by
+:meth:`~dao_treasury.db.TxGroup.get_dbid`.
+
+Examples:
+    Get the database ID for the "Expenses" group:
+        >>> dbid: TxGroupDbid = TxGroupDbid(3)
+"""
+
+
+TxGroupName = str
+"""Alias for the human‐readable name of a transaction group.
+
+Names are passed to
+:meth:`~dao_treasury.db.TxGroup.get_dbid` 
+to retrieve or create groups in the database.
+
+Examples:
+    Creating or retrieving the "Other Income" group:
+        >>> name: TxGroupName = "Other Income"
+        >>> dbid = TxGroup.get_dbid(name)
+"""
+
+
+SortFunction = Union[
+    Callable[["TreasuryTx"], bool],
+    Callable[["TreasuryTx"], Awaitable[bool]],
+]
+"""Type for a function or coroutine that determines if a transaction matches a rule.
+
+A sorting function takes a single :class:`~dao_treasury.db.TreasuryTx`
+instance and returns a boolean or an awaitable resolving to a boolean to
+indicate whether the rule applies.
+
+Examples:
+    Synchronous matcher:
+        >>> def is_large(tx: TreasuryTx) -> bool:
+        ...     return tx.amount > 1000
+
+    Asynchronous matcher:
+        >>> async def has_tag(tx: TreasuryTx) -> bool:
+        ...     return await some_external_check(tx.hash)
+
+See Also:
+    :class:`~dao_treasury.sorting.rule._SortRule.match`
+"""
+
+
+SortRule = Union[
+    "RevenueSortRule",
+    "CostOfRevenueSortRule",
+    "ExpenseSortRule",
+    "OtherIncomeSortRule",
+    "OtherExpenseSortRule",
+    "IgnoreSortRule",
+]
+"""Union of all built‐in sort rule classes.
+
+Each rule assigns transactions to a specific category by matching on
+transaction attributes or by invoking a custom function.
+
+Examples:
+    Define a list of available sort rules:
+        >>> from dao_treasury.sorting.rule import SORT_RULES
+        >>> rules: list[SortRule] = SORT_RULES
+
+See Also:
+    :class:`~dao_treasury.sorting.rule.RevenueSortRule`
+    :class:`~dao_treasury.sorting.rule.ExpenseSortRule`
+    :class:`~dao_treasury.sorting.rule.IgnoreSortRule`
+    :class:`~dao_treasury.sorting.rule.CostOfRevenueSortRule`
+    :class:`~dao_treasury.sorting.rule.OtherIncomeSortRule`
+    :class:`~dao_treasury.sorting.rule.OtherExpenseSortRule`
+"""

dao_treasury-0.0.42.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: dao_treasury
+Version: 0.0.42
+Summary: Produce comprehensive financial reports for your on-chain org
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10,<3.13
+Description-Content-Type: text/markdown
+Requires-Dist: eth-portfolio-temp<0.1,>=0.0.38.dev0
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+DAO Treasury is a comprehensive financial reporting and treasury management solution designed specifically for decentralized organizations. Built as an extension to [eth-portfolio](https://github.com/BobTheBuidler/eth-portfolio)'s [Portfolio Exporter](https://bobthebuidler.github.io/eth-portfolio/exporter.html), DAO Treasury automates the collection and visualization of financial data, enabling organizations to monitor and report on treasury activities with clarity and transparency.
+
+## Key Features
+
+- **Financial Reporting for DAOs:** Extends core portfolio functionalities to generate detailed reports tailored for on-chain organizations.
+- **Dashboard Provisioning:** Utilizes [Grafana](https://grafana.com/) dashboards—defined in JSON files within the .grafana/provisioning directories—to offer real-time, dynamic visualizations of treasury data.
+- **Automated Data Export:** Features a treasury export tool that, once configured (with a supported [brownie network](https://eth-brownie.readthedocs.io/en/stable/network-management.html) and [Docker](https://www.docker.com/get-started/)), continuously captures financial snapshots at set intervals.
+- **Ease of Contribution:** Non-technical users can easily update or create dashboard visuals using Grafana’s intuitive UI. The [Contributing Guidelines](https://github.com/BobTheBuidler/dao-treasury/blob/master/CONTRIBUTING.md) document provides a step-by-step guide to defining new visuals and dashboards and integrating those changes into the repository, ensuring that anyone can contribute to the visual reporting aspect of the project.
+
+## Requirements
+- Python 3.10 or higher.
+- At least 16GB of RAM.
+- All dependencies installed as specified in the project’s pyproject.toml file.
+
+## Prerequisites
+
+- First, you will need to bring your own archive node. This can be one you run yourself, or one from one of the common providers (Tenderly, Alchemy, QuickNode, etc.). Your archive node must have tracing enabled (free-tier Alchemy nodes do not support this option).
+- You must configure a [brownie network](https://eth-brownie.readthedocs.io/en/stable/network-management.html) to use your RPC.
+- You will need an auth token for [Etherscan](https://etherscan.io/)'s API. Follow their [guide](https://docs.etherscan.io/etherscan-v2/getting-an-api-key) to get your key, and set env var `ETHERSCAN_TOKEN` with its value.
+- You'll also need [Docker](https://www.docker.com/get-started/) installed on your system. If on MacOS, you will need to leave Docker Desktop open while Yearn Treasury is running.
+
+## Installation
+
+```bash
+pip install dao-treasury
+```
+
+## Usage
+
+Run the treasury export tool:
+
+```bash
+# For pip installations:
+dao-treasury run --wallet 0x123 --network mainnet --interval 12h
+```
+
+For local development (from source installation), use:
+```bash
+poetry run dao-treasury run --wallet 0x123 --network mainnet --interval 12h
+```
+
+**CLI Options:**
+- `--network`: The id of the brownie network the exporter will connect to (default: mainnet)
+- `--interval`: The time interval between each data snapshot (default: 12h)
+- `--daemon`: Run the export process in the background (default: False) (NOTE: currently unsupported)
+- `--grafana-port`: Set the port for the Grafana dashboard where you can view data (default: 3004)
+- `--renderer-port`: Set the port for the report rendering service (default: 8091)
+- `--victoria-port`: Set the port for the Victoria metrics reporting endpoint (default: 8430)
+- `--start-renderer`: If set, both the Grafana and renderer containers will be started for dashboard image export. By default, only the grafana container is started.
+
+After running the command, the export script will run continuously until you close your terminal.
+To view the dashboards, just open your browser and navigate to [http://localhost:3004](http://localhost:3004)!
+
+## Docker
+
+When you run DAO Treasury, [eth-portfolio](https://github.com/BobTheBuidler/eth-portfolio) will build and start 4 [required Docker containers](https://bobthebuidler.github.io/eth-portfolio/exporter.html#docker-containers) on your system. Additionally, DAO Treasury will build and start 2 more required containers:
+
+- **grafana**
+  - Provides a web-based dashboard for visualizing your treasury data.
+  - Pre-configured with dashboards and plugins for real-time monitoring.
+  - Uses persistent storage to retain dashboard settings and data.
+  - Accessible locally (default port `3004`, configurable via `--grafana-port`).
+  - Supports anonymous access for convenience.
+  - Integrates with the renderer container for dashboard image export.
+  - Loads dashboards and data sources automatically via provisioning files.
+
+- **renderer**
+  - Runs the official Grafana image renderer service.
+  - Enables Grafana to export dashboards as images for reporting or sharing.
+  - Operates on port `8091` by default (configurable via `--renderer-port`).
+  - Tightly integrated with the Grafana container for seamless image rendering.
+  - **Note:** The renderer container is only started if you pass the `--start-renderer` CLI flag.
+
+**How it works:**
+1. DAO Treasury collects and exports treasury data.
+2. Grafana displays this data in pre-built dashboards for analysis and reporting.
+3. The renderer container allows dashboards to be exported as images directly from Grafana (if enabled).
+
+**Additional Information:**
+- All containers are orchestrated via Docker Compose and started automatically as needed.
+- Grafana provisioning ensures dashboards and data sources are set up out-of-the-box.
+- All dashboard data and settings are persisted for durability.
+- Dashboard images can be generated for reporting via the renderer (if enabled).
+
+## Screenshots
+
+#### [DAO Transactions Dashboard](https://bobthebuidler.github.io/dao-treasury/transactions.html)
+
+![image](https://github.com/user-attachments/assets/64eb8947-bdd9-490e-a9ea-c9a8e4194df2)
+
+## Contributing
+
+We welcome contributions to DAO Treasury! For detailed guidelines on how to contribute, please see the [Contributing Guidelines](https://github.com/BobTheBuidler/dao-treasury/blob/master/CONTRIBUTING.md).
+
+Enjoy!

dao_treasury-0.0.42.dist-info/RECORD

@@ -0,0 +1,51 @@
+bf2b4fe1f86ad2ea158b__mypyc.cpython-311-i386-linux-gnu.so,sha256=7YuvT0PcUu4_uq_E82OnYm6eLt2saoEr9xIvrOKI9Rg,1367100
+dao_treasury/ENVIRONMENT_VARIABLES.py,sha256=LEczR1MSWTY00sLHnFs3j_Jm8WZNJCxjwEzrvjbwl2E,636
+dao_treasury/__init__.py,sha256=W4syl9-cNhHOdD25ye9U7aBJTLE_R-uP49FXC_6CUOE,1477
+dao_treasury/_docker.cpython-311-i386-linux-gnu.so,sha256=BLsQRJ9kPkatGXpgrRi819XOdDsMhcNzO4dp0EQTCmE,16248
+dao_treasury/_docker.py,sha256=b3exLlhtaC9S3osrLQsL8SIOLKUtSoop2uue0cSP9WM,5908
+dao_treasury/_nicknames.cpython-311-i386-linux-gnu.so,sha256=BiXjUEyJGH0xGeJdTs1CScn7FW1bY38Y6uaJ6C7RLj4,16268
+dao_treasury/_nicknames.py,sha256=bvz0b8C31tFQ0pGtpSJW86OwjUF_qMBal4VXVT5UyLo,1017
+dao_treasury/_wallet.cpython-311-i386-linux-gnu.so,sha256=2oymfcmqZilYzRHC9XF8CagwoOpuFI9sT8bR3oh4sHg,16248
+dao_treasury/_wallet.py,sha256=epV8LVuwHlOzc9UkA66js7HfEiZBOSAGJMtWbDTzmjU,10462
+dao_treasury/constants.cpython-311-i386-linux-gnu.so,sha256=t8-D2gkSRV8aF1W9qO5-Sa9DszC6AiR-5nGe6DbtMZU,16260
+dao_treasury/constants.py,sha256=MM4X4TK2RD1JaTNMg7zdo6QjKZTTvep6g7TgckE7M-8,1220
+dao_treasury/db.py,sha256=PfXCm8v4sLWdj3lenLJBA_076in300qKUSN9xdBEOCE,48013
+dao_treasury/docker-compose.yaml,sha256=E6KE-IjWDisAM19PPDi4ApR6Eu7jmMTM6J9DhtgJvR4,1309
+dao_treasury/main.py,sha256=31EA10Fpaj9y-cRJPnNnvCBI38UM0848xlzn7A0BzC4,8047
+dao_treasury/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dao_treasury/treasury.py,sha256=taTvwTH_Zdu2M61TrUCENcIUjxdQO3vryrZ2iVb6suM,7223
+dao_treasury/types.cpython-311-i386-linux-gnu.so,sha256=dLltBTZEVhXquDI-QkYh7R2C-VsrGBEWxqTf2dgacTU,16240
+dao_treasury/types.py,sha256=dJDx0hYfDDL3slcUzRnCgrzFFsgCzoqg8uaTtLaT4kk,3685
+dao_treasury/.grafana/provisioning/dashboards/dashboards.yaml,sha256=tr6FBJeAAPX76db8E3qBBVWnq2-yrWDXDGuclMDg6dw,1277
+dao_treasury/.grafana/provisioning/dashboards/streams/LlamaPay.json,sha256=9OzlVtq0wRBDw3MhoaYLrT_hd7w_V3c_B7bYNmX4TJo,7023
+dao_treasury/.grafana/provisioning/dashboards/summary/Monthly.json,sha256=O6ghjzBf333baPjuMuUNguxF2v6rvPCiOu39sm1zxxY,6533
+dao_treasury/.grafana/provisioning/dashboards/transactions/Treasury Transactions.json,sha256=gCWQTzawn5w9LVsxCi4SbobcVXK8IxXrZdk2syH4Ubg,13230
+dao_treasury/.grafana/provisioning/dashboards/treasury/Cashflow (Including Unsorted).json,sha256=4TpUdEmo40EneKldjeNxaiNLW2-IsIBRiy5jz-nqFdY,25664
+dao_treasury/.grafana/provisioning/dashboards/treasury/Cashflow.json,sha256=DOpO3leNVyUUQD5ou5FkdGCGc1xJmCRQjuzSUCvBnGU,18139
+dao_treasury/.grafana/provisioning/dashboards/treasury/Operating Cashflow.json,sha256=tKtUeBp9p-g21MOaFMPItUoXF_coHMM000yNipNB_RU,14352
+dao_treasury/.grafana/provisioning/dashboards/treasury/Treasury.json,sha256=p9bupL06-CKqkqCOb6KkgP1LCa6P1VMkq3yhkyqMAzI,70178
+dao_treasury/.grafana/provisioning/datasources/datasources.yaml,sha256=mjQs8or651NgD_bZnKBm8vSghzjw_g3enL01YPt0dik,327
+dao_treasury/sorting/__init__.cpython-311-i386-linux-gnu.so,sha256=-LAV5uxGNowx64yMQvfTwUS7Ysq8ObYfzkhd1xSoKRc,16248
+dao_treasury/sorting/__init__.py,sha256=vKj3NPB7EWbX7_fSUWKXk-NsyPasOkFhJvJVGclBOAE,10371
+dao_treasury/sorting/_matchers.cpython-311-i386-linux-gnu.so,sha256=pWnHtTW-YYrDlXiQFQrGLnYel_kOmb-Bmtxj0aCK3SQ,16276
+dao_treasury/sorting/_matchers.py,sha256=u0GfPYiODr_NtzbfyLxEKDuXmWRiaeuZulDj9FPDOH8,14005
+dao_treasury/sorting/_rules.cpython-311-i386-linux-gnu.so,sha256=mq17RitfgGl3JExMnG-bVAf-j47x0zDsHb8lyLNNc7Y,16264
+dao_treasury/sorting/_rules.py,sha256=vWkqJVA8yCHKRv9sw872Jq6G0zpM-v_J1jCz-Mgleec,8994
+dao_treasury/sorting/factory.cpython-311-i386-linux-gnu.so,sha256=eNpb3alin4cieY2MRbU-xpnfhJMvJnlF8r3cNVx_7EE,16264
+dao_treasury/sorting/factory.py,sha256=pFD6luc0bKxOTT1hlAp3ZwJw6R0wN8pjIZrqMZwhsko,10185
+dao_treasury/sorting/rule.cpython-311-i386-linux-gnu.so,sha256=p2Bc96hIVK4i3yqPobHHi57yxGYzk1NkNhuZ_BLWNSk,16252
+dao_treasury/sorting/rule.py,sha256=-4dokQbRJ2GPJLEwtpgGG0aXAM1pW4jI17aezo--Z5g,11491
+dao_treasury/sorting/rules/__init__.cpython-311-i386-linux-gnu.so,sha256=RcQ1KUkY8zO6KYwW9LeV0xZO3GS10rQ77NO8A4Ryga8,16256
+dao_treasury/sorting/rules/__init__.py,sha256=ofzIsW0P74kuKr6DlScZIF8p7hBh6guRpe1uOq6oLLA,48
+dao_treasury/sorting/rules/ignore/__init__.cpython-311-i386-linux-gnu.so,sha256=Q5yb_H2lbTsTzwJu9rHlP2pZW4k7e1HzkkA9h6apI-o,16276
+dao_treasury/sorting/rules/ignore/__init__.py,sha256=dJ4oKSLe7fal1Ct7XtMCfVJAtvZXcyIomf8HF3gWUhQ,57
+dao_treasury/sorting/rules/ignore/llamapay.cpython-311-i386-linux-gnu.so,sha256=UfSSqn0gQu7gCj0pyQit292HEHHIGIBeb48quHARQK0,16300
+dao_treasury/sorting/rules/ignore/llamapay.py,sha256=NgiVt9MRtI-f4mw9U5_gqttdPqDa3vt_z5XWJP_UYWs,763
+dao_treasury/streams/__init__.cpython-311-i386-linux-gnu.so,sha256=KIIOB5QSN6mhxxJm6U939Chf052ek03xWUDolitbNh4,16248
+dao_treasury/streams/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dao_treasury/streams/llamapay.cpython-311-i386-linux-gnu.so,sha256=hEHuVvkd5nuYaRr-VzTPCWvjpnaDCE1N4n1D2vFZJZ8,16272
+dao_treasury/streams/llamapay.py,sha256=yn37gwVfqGFF9fOhHuj9_t7KlHGyrdekF2TUmVDyg64,13147
+dao_treasury-0.0.42.dist-info/METADATA,sha256=85p3P6VAMpOINstFqJ4y84mLiaxe6pjQb6SXFz5ejcc,7030
+dao_treasury-0.0.42.dist-info/WHEEL,sha256=TVIpuzrcH5e35TaRIjz3w0RzSOv44d8cwjiur4qemmA,180
+dao_treasury-0.0.42.dist-info/top_level.txt,sha256=Gw-ri_26lZA_3hwhnOX48mffUbmBGr8NhtoQ0XoMeF8,41
+dao_treasury-0.0.42.dist-info/RECORD,,

dao_treasury-0.0.42.dist-info/WHEEL

@@ -0,0 +1,7 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: false
+Tag: cp311-cp311-manylinux_2_5_i686
+Tag: cp311-cp311-manylinux1_i686
+Tag: cp311-cp311-manylinux_2_28_i686
+

dao_treasury-0.0.42.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+bf2b4fe1f86ad2ea158b__mypyc
+dao_treasury