# Gitcoin Governor Upgrade Development, Testing and Simulation Summary

### Overview

This document is a brief summary of the engineering work completed by ScopeLift as part of the Gitcoin Governor upgrade.

All of the work done by ScopeLift is open source and availble on GitHub at [gitcoinco/Alpha-Governor-Upgrade](https://github.com/gitcoinco/Alpha-Governor-Upgrade). The work is done using the [Foundry](https://github.com/foundry-rs/foundry) development framework.

The repository has the following directory structure:

* [/src](https://github.com/gitcoinco/Alpha-Governor-Upgrade/tree/main/src) - The core Governor contract
* [/script](https://github.com/gitcoinco/Alpha-Governor-Upgrade/tree/main/script) - Scripts for deploying the new Governor and submitting the upgrade proposal
* [/test](https://github.com/gitcoinco/Alpha-Governor-Upgrade/tree/main/test) - The testing and simulation of the new Governor

### Core Contracts

The [core Governor contract](https://github.com/gitcoinco/Alpha-Governor-Upgrade/blob/main/src/GitcoinGovernor.sol) is relatively simple. It is constructed using the [OpenZeppelin](https://github.com/OpenZeppelin/openzeppelin-contracts) Governor contracts and the ScopeLift [Flexible Voting](https://github.com/ScopeLift/flexible-voting) extension. No other dependencies or sub-dependencies are used.

### Scripts

The scripts are straightforward Foundry scripts. The [deploy script](https://github.com/gitcoinco/Alpha-Governor-Upgrade/blob/main/script/Deploy.s.sol) was used to deploy the [candidate](https://etherscan.io/address/0x1a84384e1f1b12d53e60c8c528178dc87767b488) Governor on April 7th, 2023. The [propose script](https://github.com/gitcoinco/Alpha-Governor-Upgrade/blob/main/script/Propose.s.sol) will be used by a delegate with sufficient voting weight to propose the upgrade to the DAO's existing Governor contract for onchain voting.

### Testing & Simulation

The tests are where the majority of the engineering effort for this upgrade took place. There are approximately [1,500 lines](https://github.com/gitcoinco/Alpha-Governor-Upgrade/blob/main/test/GitcoinGovernor.t.sol) of tests written in Solidity using Foundry's testing framework.

The tests run on "local fork" of Mainnet, meaning the test environment pulls its state and contract code from Mainnet as the tests interact with it. Effectively, the tests run in a simulated environment that mimics the real environment where the contracts will execute as closely as possible.

The tests exercise the Deploy script and the Propose script in order to hew as closely as possible to the scenario that will occur in production. Additionally, the tests are architected to be executed in different scenarios. One such scenario deploys the Governor scripts on the local test network.

The second scenario was added after the candidate Governor was deployed. It uses the actual deployed contract code that now exists on mainnet directly. This, again, allows the test suite to be simulated as closely as possible to the production environment.

After the proposal is submitted to the Alpha Governor, a third scenario will be added which will simulate the relevant tests against the actual proposal data that will—at that point—be onchain. When the simulations complete successfully after this update, we can be further assured the upgrade will work exactly as expected, and that no bugs were somehow introduced in the proposal phase.

The test suite itself simulates dozens of different individual scenarios related to the Governor upgrade and to its usage by the DAO before and after the upgrade occurs. These include:

* Successful deployment of the updated Governor with parameters that match the existing Governor
* Successful submission of the upgrade proposal to the existing Governor
* Rejection of the upgrade proposal if the vote fails
* Continued successful operation of the existing Governor contracts if the upgrade proposal vote fails
* Successful execution of the upgrade after a passing vote
* Ability of the new Governor to queue and vote on new proposals after the upgrade, including:
* Proposals that succeed and are executed
* Proposals that fail and do not execute
* Ability of the new Governor to move treasury funds after a successful upgrade, including individual tests for Ether, for each token held by Governance, and for combinations thereof
* Ability of the new Governor to queue and execute proposals which modify its own Governance parameters, with individual tests for the voting delay, voting period, and proposal threshold
* Ability of the new Governor to exercise Flexible Voting capabilities and pass various proposals wherein some or all voters leverage Flexible Voting
* Validation that the *old* Governor no longer has the ability to execute proposals after the upgrade, including validation that it has no provenance over the treasury funds

Wherever possible within the test suite, parameters used by the tests are "fuzzed." This means that instead of hardcoding values, random parameter values are injected each time the test suite runs. The suite has been run thousands of times, thereby exercising millions of individual permutations and validating that all test expectations hold regardless of the input.