How balancermaxis/protocol_fee_allocator_v2 works
Project Overview and Purpose
• This project is a Python application designed to compute and distribute protocol fees. The goal (as suggested by its name and structure) is to gather fee data over time, process it through accounting logic, and then generate outputs (CSV files) that likely serve as input for multisig proposals and incentive allocations.
• It interacts with external chain explorer APIs (as indicated by the need for EXPLORER_API_KEY environment variables) for deterministic block fetching. Fee data is stored in JSON files inside the project and then used to calculate allocations.
Key Components Identified from the File Structure
• Main Application Entry:
• main.py: This is the starting point for the application.
• fee_allocator/fee_allocator.py: Likely the core orchestrator that ties all modules together.
• Domain-Specific Modules:
• fee_allocator/abi: Contains JSON files (such as ERC20.json and bribe_market.json) that define smart contract ABIs used to interact with external smart contracts.
• fee_allocator/accounting: Comprises modules to handle fee accounting. It includes chain handling (chains.py), pool processing (core_pools.py), utility decorators, interfaces, models, and overrides. This indicates a separation of the accounting logic from fee collection.
• fee_allocator/allocations: Handles the creation of allocation outputs. It has directories for “incentives” (with CSV outputs indicating time-bound incentive distributions) and “output_for_msig” (for multisig proposals likely containing bribe-related data).
• fee_allocator/fees_collected: Stores JSON snapshots of collected fee data (with various timestamp ranges) and a script get_report.py for generating reports probably used to feed the accounting and allocation processes.
• fee_allocator/logger.py and fee_allocator/utils.py: Utilities for logging and common functions.
• Infrastructure and Support:
• .env.example: Indicates that the application uses environment variables for configuration (e.g., DRPC_KEY and explorer API keys).
• GitHub workflows under .github/workflows: Defines automation processes such as fee collection triggers and report generation.
• Test suite in tests/: Contains cached joblib files, test data (input_fees.json, expected outputs), and test scripts (like test_allocator.py).
Relationships and Data Flow
• The entry point (main.py) initializes the fee allocation process by calling into fee_allocator.py.
• Within fee_allocator.py, the process likely involves:
• Reading raw fee data from fee_allocator/fees_collected (JSON files).
• Using the accounting module to process fee data (interacting with models, chain-specific logic, and core pools).
• Employing data from the ABI definitions in fee_allocator/abi for smart contract interactions if needed.
• Passing processed fee data to the allocations module:
– The incentives submodule prepares CSVs for incentive distributions.
– The output_for_msig submodule prepares CSV files intended for multisig transactions (e.g., bribe proposals).
• External dependencies include chain explorer APIs (driven by environment configurations) and possibly smart contract interactions via defined ABIs.
• GitHub workflows automate tasks like fee collection and report generation, ensuring new data and allocations are created on schedule.
Architectural Patterns and Design Principles
• Separation of Concerns: The project is divided into clearly defined modules (accounting, allocations, fee collection) which each handle a specific responsibility.
• Modularity: Each folder under the fee_allocator package is focused on a specific domain (e.g., ABI interactions, accounting logic, output creation).
• Configuration via Environment Variables: Emphasizes flexibility and secure handling of keys.
• Testability: The presence of a comprehensive tests folder suggests an architecture that supports unit/integration testing.