metagov/dao-governance-surfaces

Extract and label the "governance surface" of a set of DAO smart contracts

dao-governance-surfaces

Extract and label the "governance surface" of a set of DAO smart contracts.

Simple summary

An organization's governance surface is the set of available actions through which it can adapt itself. In DAOs specifically, many of these actions are circumscribed by a smart contract, which contains a set of parameters and the mechanisms for modifying these parameters.

This repository contains the tools for collecting the parameters and functions that define the governance surface into a series of linked objects and tables, including metadata about who is allowed to view a parameter or perform an action and keyword labels based on the variable names and plain-text comments in the code.

Setup

• Fork and clone this repository, then navigate to the root directory of the project
• Set up a Python environment from requirements.txt. Example using conda:

conda env create -n dgs python=3.10
conda activate dgs
pip install -r requirements.txt

• Run git submodule update --init --recursive to initialize the solidity_parser submodule
• Run pip install -r solidity-parser/requirements.txt to install the additional requirements of the solidity_parser library
• Run python download_and_parse_contracts.py to collect and parse data from a prepopulated list of DAO factory contract repositorys. Or, provide your own GitHub repo url to analyze a particular repository: python download_and_parse_contracts.py [url]
• Run factory_contracts.ipynb to see the results!

Implementation

Overall flow

Using the AST generated by a Solidity parser, extract the contract and functions definitions (including their state variables or arguments and any associated enums, structs, modifiers, and events). Then, find any comments associated with these and attach them to the corresponding object or parameter. Finally, label each object or parameter based on the keywords found in the name or associated comments. Export two linked tables as CSV files.

Data model

The data extracted about the smart contract governance surface is modeled by ContractObjects (a 'contract', 'event', 'modifier', 'function', 'struct', or 'enum' definition with properties such as visibility, modifiers for functions, and inheritance for contracts) and ContractParameters (a contract state variable or function argument with properties such as data type). Each ContractParameter is linked to the ContractObject for which it is defined.

Other notes

This repository is generally applicable to extracting the "control surface" and comments for any smart contract. The labels generated by keyword searching can be updated by modifying config/keywords.json

Check out the tests for details on how the data modeling, comment parsing, keyword labeling, and GitHub repo downloading is expected to behave.

Motivation

Some applications of this work include:

• Mapping the space: develop a data-driven, fine-grained representation of computational governance or a new model for DAOs
• Supporting standards creation: inform and frontend development for end-user governance design interface
• Conducting fundamental research: for example, investigate the relationship between “size” of a governance surface and “requisite variety” (tradeoff between resilience and robustness; see Zargham and Nabben, 2022)
• Performing audits/forensic investigation: automate some of smart contract inspection undertaken in “governance audits,” comparable to current contract audits focused on security
• Predict DAO performance: build a data pipeline with which to run ML-driven workflows to analyze, predict, or optimize governance in DAOs with respect to a list of target indicators

Hypotheses (open to contributions!)

Practical roadmap for Metagov

1. Construct and fill a "virtual" data lake
2. Develop basic research hypotheses on top of the data (can crowdsource)
3. Test hypotheses
4. Write a paper about it
5. Use the above to identify more concrete business use-cases
6. Get businesses to fund more research + data engineering (more hypothesis formation and testing)
7. Integrate with DAOstar standards work (internally)
8. Develop and maintain public services that people can query

dao-governance-surfaces's Issues

Reindexing error on processing object/parameter CSVs

In the main notebook, just loading the files is returning an error:

File [~/Repositories/dao-governance-surfaces/dgs/utils.py:77](https://file+.vscode-resource.vscode-cdn.net/home/notchia/Repositories/dao-governance-surfaces/~/Repositories/dao-governance-surfaces/dgs/utils.py:77), in load_results_from_files(dir)
     74 df_params = pd.concat(all_params, axis=1).set_index('id')
     76 # Load child parameter names into df_objects for ease of analysis
---> 77 df_objects['parameters_names'] = df_objects['parameters'].apply(
     78     lambda values: [df_params.at[v, 'parameter_name'] for v in values] if isinstance(values, list) else np.nan
     79 )

...

ValueError: cannot reindex on an axis with duplicate labels

Zip files appear to be invalid

Many repos in the config file are showing up as having invalid zip files when reading the response from the constructed zip URL.