cleanup deployment README

.env.example

@@ -1,33 +1,44 @@
-# Test mode:
-# "local" will redeploy OSx contracts,
+# Fork Test mode:
 # "fork-deploy" will run against the live network fork, deploying new contracts via a new instance of the factory
 # "fork-existing" will run against the live network fork, using the existing factory & therefore the existing contracts
-# Local is not yet supported as requires further mocking of OSx
-TEST_MODE="fork-deploy"
-TOKEN_TEST_WHALE="0x" # for fork testing, if you need to distribute tokens, pick a whale
-FACTORY="0x26afd02483951953B0F8A21123169cf7747CA8e2"
+FORK_TEST_MODE="fork-deploy"
+
+# With false, the script will deploy mock tokens with open mint functions
+DEPLOY_AS_PRODUCTION=false
+
+# If deploying against a fork, pass the address of a large token holder who will be
+# impersonated to distribute tokens to addresses inside test cases
+# the whale should have >= 3000 tokens
+TOKEN_TEST_WHALE="0x" 
+
+# If the factory singleton is deployed, pass the address. "Fork existing" mode will use this previously
+# deployed factory, and "fork deploy" will deploy a new factory instance
+FACTORY="0x0000000000000000000000000000000000000000"
 
 # NETWORK AND DEPLOYMENT WALLET
 DEPLOYMENT_PRIVATE_KEY="..."
-ALCHEMY_API_KEY="..."
-ETHERSCAN_API_KEY="..."
 NETWORK="sepolia"
 
-# With false, the script will deploy mock tokens
-DEPLOY_AS_PRODUCTION=true
-MULTISIG_MEMBERS_JSON_FILE_NAME="/script/multisig-members.json"
+# API Keys (optional)
+# Note that having these active will slow down unit tests even when not needed
+# So recommended to only activate when needed
+# ETHERSCAN_API_KEY="..."
+# ALCHEMY_API_KEY="..."
+
 
 # MULTISIG PARAMETERS
-MIN_APPROVALS="5"                            # How many multisig approvals are required
+# define a list of multisig members - said multisig will be assigned administrator roles of the ve contracts
+MULTISIG_MEMBERS_JSON_FILE_NAME="/script/multisig-members.json"
+MIN_APPROVALS="1"                            # How many multisig approvals are required
 MULTISIG_PROPOSAL_EXPIRATION_PERIOD="864000" # How long until a pending proposal expires (10 days)
 
 # GAUGE VOTER PARAMETERS
 # The token to be used for the escrow
-TOKEN1_ADDRESS="0xdc518215FCbeB2b641073F4387895E64d65D51fB"
+TOKEN1_ADDRESS="0x0000000000000000000000000000000000000000"
 VE_TOKEN1_NAME="Voting Escrow Token 1"
 VE_TOKEN1_SYMBOL="veTK1"
 
-# Additional tokens
+# Additional tokens these will have secondary escrow contracts
 TOKEN2_ADDRESS="0x0000000000000000000000000000000000000000" # Ignored if 0x0
 VE_TOKEN2_NAME="Voting Escrow Token 2"
 VE_TOKEN2_SYMBOL="veTK2"
@@ -42,7 +53,7 @@ WARMUP_PERIOD="259200" # 3 days
 COOLDOWN_PERIOD="259200" # 3 days
 
 # Min seconds a user must have locked in escrow before they can queue an exit
-MIN_LOCK_DURATION="4838400" # 8 weeks
+MIN_LOCK_DURATION="3600" # 1 hour
 
 # Prevent voting until manually activated by the multisig
 VOTING_PAUSED=true

Makefile

@@ -3,19 +3,42 @@
 # (-include to ignore error if it does not exist)
 -include .env
 
-# env var check
-check-env :; echo $(ETHERSCAN_API_KEY)
-
 # linux: allow shell scripts to be executed
 allow-scripts:; chmod +x ./coverage.sh
 
+# init the repo
+install :; make allow-scripts && forge build
+
 # create an HTML coverage report in ./report (requires lcov & genhtml)
 coverage:; ./coverage.sh
+	#
+# run unit tests
+test-unit :; forge test --no-match-path "test/fork/**/*.sol"
 
-# init the repo
-install :; make allow-scripts && make coverage
+#### Fork testing ####
+
+# Fork testing - mode sepolia
+ft-mode-sepolia-fork :; forge test --match-contract TestE2EV2 \
+	--rpc-url https://sepolia.mode.network \
+	-vv
+
+# Fork testing - mode mainnet
+ft-mode-fork :;  forge test --match-contract TestE2EV2 \
+	--rpc-url https://mainnet.mode.network/ \
+	-vvvvv
+
+# Fork testing - holesky
+ft-holesky-fork :; forge test --match-contract TestE2EV2 \
+	--rpc-url https://holesky.drpc.org \
+	-vvvvv
+
+# Fork testing - sepolia
+ft-sepolia-fork :; forge test --match-contract TestE2EV2 \
+	--rpc-url https://sepolia.drpc.org \
+	-vvvvv
+
+#### Deployments ####
 
-# deployments
 deploy-preview-mode-sepolia :; forge script script/Deploy.s.sol:Deploy \
   --rpc-url https://sepolia.mode.network \
 	--private-key $(DEPLOYMENT_PRIVATE_KEY) \
@@ -43,25 +66,3 @@ deploy-mode :; forge script script/Deploy.s.sol:Deploy \
 	--etherscan-api-key $(ETHERSCAN_API_KEY) \
 	-vvv
 
-# Fork testing
-ft-mode-sepolia-fork :; forge test --match-contract TestE2EV2 \
-	--rpc-url https://sepolia.mode.network \
-	--fork-block-number 19911297 \
-	-vv
-
-ft-mode-sepolia-fork-nocache :; forge test --match-contract TestE2EV2 \
-	--rpc-url https://sepolia.mode.network \
-	--fork-block-number 19911297 \
-	--no-cache \
-	-vv
-
-ft-mode-fork :;  forge test --match-contract TestE2EV2 \
-	--rpc-url https://mainnet.mode.network/ \
-	--fork-block-number 13848964 \
-	-vvvvv
-
-
-ft-holesky-fork :; forge test --match-contract TestE2EV2 \
-	--rpc-url https://holesky.drpc.org \
-	--fork-block-number 2459459 \
-	-vvvvv

README.md

@@ -1,6 +1,132 @@
 # Aragon VE Governance Hub
 
-# Contracts Overview
+Welcome to Aragon's veGovernance Plugin - a flexible, modular and secure system which can be used to create custom DAOs that foster a strong alignment between token holders and capital flows.
+
+## Setup
+
+To get started, ensure that [Foundry](https://getfoundry.sh/) is installed on your computer, then copy `.env.example` into `.env` and define the parameters
+
+### Understanding `.env.example`
+
+The env.example file contains descriptions for all the initial settings. You don't need all of these right away but should review prior to fork tests and deployments
+
+## Using the Makefile
+
+The `Makefile` functions as a script runner for common tasks. It's recommended to start there. Ensure you have the required tools installed to run the `make` command on your system:
+
+```sh
+# debian
+sudo apt install build-essential
+
+# arch
+sudo pacman -S base-devel
+
+# nix
+nix-env -iA nixpkgs.gnumake
+
+# macOS
+brew install make
+```
+
+Then run the commands as needed
+
+```sh
+# Setup the repo
+make install
+
+# run unit tests
+make unit-test
+
+# generate coverage report in the `report` directory
+# requires lcov and genhtml
+# serve the report/index.html in browser to view
+make coverage
+
+# the .env.example is set to work with sepolia
+make ft-sepolia-fork
+```
+
+## Running fork tests
+
+Fork testing has 2 modes:
+
+1. "fork-deploy" will run against the live network fork, deploying new contracts via a new instance of the factory
+
+2. "fork-existing" will run against the live network fork, using the existing factory & therefore the existing contracts
+
+In both cases, you will need to find the correct Aragon OSx contracts for the chain you wish to fork against. These can be found in the [OSx commons repo](https://github.com/aragon/osx-commons/tree/main/configs/src/deployments/json)
+
+> If running frequent fork tests it's recommended you pass a block number to enable caching
+
+## Deployment
+
+Deployments are done using the deployment factory. This is a singleton contract that will:
+
+- Deploy all contracts
+- Set permissions
+- Transfer ownership to a freshly deployed multisig
+- Store the addresses of the deployment in a single, queriable place.
+
+Check the `Makefile` for examples of deployments on different networks.
+
+### Deployment Checklist
+
+- [] I have reviewed the parameters for the veDAO I want to deploy
+- [] I have reviewed the multisig file for the correct addresses
+  - [] I have ensured all multisig members have undergone a proper security review and are aware of the security implications of being on said multisig
+- [] I have updated the `.env` with these parameters
+- [] I have updated the `CurveConstantLib` and `Clock` with any new constants.
+- [] All my unit tests pass
+- [] I have run a fork test in `fork-deploy` mode against the OSx contracts on my target testnet
+- [] I have deployed my contracts successfully to a target testnet
+- [] I have confirmed my tests still work in `fork-existing` mode with the live tokens and the factory.
+- [] I have run the same workflow against the mainnet I wish to deploy on
+- [] I have previewed my deploy
+- [] My deployer address is a fresh wallet or setup for repeat production deploys in a safe manner.
+- [] My wallet has sufficient native token for gas
+
+### Manual from the command line
+
+You can of course run all commands from the command line:
+
+```sh
+# Load the env vars
+source .env
+```
+
+```sh
+# run unit tests
+forge test --no-match-path "test/fork/**/*.sol"
+```
+
+```sh
+# Set the right RPC URL
+RPC_URL="https://eth-sepolia.g.alchemy.com/v2/${ALCHEMY_API_KEY}"
+```
+
+```sh
+# Run the deployment script
+
+# If using Etherscan
+forge script --chain "$NETWORK" script/Deploy.s.sol:Deploy --rpc-url "$RPC_URL" --broadcast --verify
+
+# If using BlockScout
+forge script --chain "$NETWORK" script/Deploy.s.sol:Deploy --rpc-url "$RPC_URL" --broadcast --verify --verifier blockscout --verifier-url "https://sepolia.explorer.mode.network/api\?"
+```
+
+If you get the error Failed to get EIP-1559 fees, add `--legacy` to the command:
+
+```sh
+forge script --chain "$NETWORK" script/Deploy.s.sol:Deploy --rpc-url "$RPC_URL" --broadcast --verify --legacy
+```
+
+If some contracts fail to verify on Etherscan, retry with this command:
+
+```sh
+forge script --chain "$NETWORK" script/Deploy.s.sol:Deploy --rpc-url "$RPC_URL" --verify --legacy --private-key "$DEPLOYMENT_PRIVATE_KEY" --resume
+```
+
+## Contracts Overview
 
 The primary contracts in the governance hub are found in the `src` directory. The key contracts include
 
@@ -61,43 +187,3 @@ The main workflow in the Mode Governance build is as follows:
 ## Curve design
 
 To build a flexible approach to curve design, we reviewed implementations such as seen in Curve and Aerodrome and attempted to generalise to higher order polynomials [Details on the curve design research can be found here](https://github.com/jordaniza/ve-explainer/blob/main/README.md)
-
-## Deployment
-
-To deploy the DAO, ensure that [Foundry](https://getfoundry.sh/) is installed on your computer.
-
-1. Edit `script/multisig-members.json` with the list of addresses to set as signers
-2. Run `forge build && forge test`
-3. Copy `.env.example` into `.env` and define the parameters
-
-```sh
-# Load the env vars
-source .env
-```
-
-```sh
-# Set the right RPC URL
-RPC_URL="https://eth-sepolia.g.alchemy.com/v2/${ALCHEMY_API_KEY}"
-```
-
-```sh
-# Run the deployment script
-
-# If using Etherscan
-forge script --chain "$NETWORK" script/Deploy.s.sol:Deploy --rpc-url "$RPC_URL" --broadcast --verify
-
-# If using BlockScout
-forge script --chain "$NETWORK" script/Deploy.s.sol:Deploy --rpc-url "$RPC_URL" --broadcast --verify --verifier blockscout --verifier-url "https://sepolia.explorer.mode.network/api\?"
-```
-
-If you get the error Failed to get EIP-1559 fees, add `--legacy` to the command:
-
-```sh
-forge script --chain "$NETWORK" script/Deploy.s.sol:Deploy --rpc-url "$RPC_URL" --broadcast --verify --legacy
-```
-
-If some contracts fail to verify on Etherscan, retry with this command:
-
-```sh
-forge script --chain "$NETWORK" script/Deploy.s.sol:Deploy --rpc-url "$RPC_URL" --verify --legacy --private-key "$DEPLOYMENT_PRIVATE_KEY" --resume
-```

coverage.sh

@@ -1,9 +1,9 @@
 #!/bin/sh
 
 echo "Removing test, script and src/escrow/increasing/delegation and proxylib files from coverage report"
-forge coverage --report lcov &&
-  lcov --remove ./lcov.info -o ./lcov.info.pruned \
-    'test/**/*.sol' 'script/**/*.sol' 'test/*.sol' \
-    'script/*.sol' 'src/escrow/increasing/delegation/*.sol' \
-    'src/libs/ProxyLib.sol' &&
-  genhtml lcov.info.pruned -o report --branch-coverage
+forge coverage --no-match-path "test/fork/**/*.sol" --report lcov &&
+	lcov --remove ./lcov.info -o ./lcov.info.pruned \
+		'test/**/*.sol' 'script/**/*.sol' 'test/*.sol' \
+		'script/*.sol' 'src/escrow/increasing/delegation/*.sol' \
+		'src/libs/ProxyLib.sol' &&
+	genhtml lcov.info.pruned -o report --branch-coverage