dss-vest
A token vesting plan for contributors. Includes scheduling, cliff vesting, third-party revocation and meta transaction following ERC2771.
Requirements
Deployment using DappHub
dss-vest
allows DAOs to create a participant vesting plan via token mints or surplus withdrawals.
$ dapp update
$ make deploy-suckable
or
$ make deploy-mintable gem=0xbeef...
or
$ make deploy-transferrable owner=0xdead... gem=0xbeef...
DssVestMintable
Pass the address of the vesting token to the constructor on deploy. This contract must be given authority to mint()
tokens in the vesting contract.
After deployment, governance must set the cap
value using the file
function.
DssVestSuckable
Pass the MCD chainlog address to the constructor to set up the contract for scheduled Dai suck
s. Note: this contract must be given authority to suck()
Dai from the vat
's surplus buffer.
A vat.live
check is introduced to disable vest()
in the event of Emergency Shutdown (aka Global Settlement).
After deployment, governance must set the cap
value using the file
function.
DssVestTransferrable
Pass the authorized sender address and the address of the token contract to the constructor to set up the contract for streaming arbitrary ERC20 tokens. Note: this contract must be given ERC approve()
authority to withdraw tokens from this contract.
After deployment, the owner must also set the cap
value using the file
function.
Deployment using Foundry
source .env
forge create --rpc-url $GOERLI_RPC_URL --private-key $PRIVATE_KEY --verify --etherscan-api-key=$ETHERSCAN_API_KEY src/Factory.sol:DssVestNaiveFactory
After the first DssVestMintable has been created using the factory, it should be verified.
- paste the constructor arguments into a file stored at
$FILE
. The format is described here (see last example). - verify
forge verify-contract $CONTRACT_ADDRESS --chain goerli --constructor-args-path $FILE src/DssVest.sol:DssVestMintable
Creating a vest
create(_usr, _tot, _bgn, _tau, _eta, _mgr) returns (id)
Create a new vesting plan.
-
_usr
: The plan beneficiary -
_tot
: The total amount of the vesting plan, in token units- ex. 100 MKR =
100 * 10**18
- ex. 100 MKR =
-
_bgn
: A unix-timestamp of the plan start date -
_tau
: The duration of the vesting plan (in seconds) -
_eta
: The cliff period, a duration in seconds from the_bgn
time, in which tokens are accrued but not payable. (in seconds) -
_mgr
: (Optional) The address of an authorized manager. This address has permission to remove the vesting plan when the contributor leaves the project.- Note:
auth
users on this contract always have the ability toyank
a vesting contract.
- Note:
Interacting with a vest
vest(_id)
The vesting plan participant calls vest(id)
after the cliff period to pay out all accrued and unpaid tokens.
vest(_id, _maxAmt)
The vesting plan participant calls vest(id, maxAmt)
after the cliff period to pay out accrued and unpaid tokens, up to maxAmt.
move(_id, _dst)
The vesting plan participant can transfer their contract _id
control and ownership to another address _dst
.
unpaid(_id) returns (amt)
Returns the amount of accrued, vested, unpaid tokens.
accrued(_id) returns (amt)
Returns the amount of tokens that have accrued from the beginning of the plan to the current block.
valid(_id) returns (bool)
Returns true if the plan id is valid and has not been claimed or yanked before the cliff.
restrict(uint256)
Allows governance or the owner to restrict vesting to the owner only.
unrestrict(uint256)
Allows governance or the owner to enable permissionless vesting.
Revoking a vest
yank(_id)
An authorized user (ex. governance) of the vesting contract, or an optional plan manager, can yank
a vesting contract. If the contract is yanked prior to the plan cliff, no funds will be paid out. If a plan is yank
ed after the contract cliff period has ended, new accruals will cease and the participant will be able to call vest
to claim any vested funds.
yank(_id, _end)
Allows governance to schedule a point in the future to end the vest. Used for planned offboarding of contributors.
Echidna
Install Echidna
- Install Echidna v2.0.0
$ nix-env -i -f https://github.com/crytic/echidna/archive/v2.0.0.tar.gz
- Install Echidna v2.0.0 via echidnup
$ echidnup v2.0.0
Local Dependencies
- Install solc 0.8.17
$ nix-env -f https://github.com/dapphub/dapptools/archive/master.tar.gz -iA solc-static-versions.solc_0_6_12
- Install solc 0.8.17 via duppsolc
$ duppsolc 0.8.17
Run Echidna Tests
- DssVestMintableEchidnaTest:
$ make echidna-mintable
- DssVestSuckableEchidnaTest:
$ make echidna-suckable
- DssVestTransferrableEchidnaTest:
$ make echidna-transferrable
Certora
Install Certora
- Install Java
sudo apt install openjdk-14-jdk
- Install Certora Prover
pip3 install certora-cli
- Set Certora Key (optional)
export CERTORAKEY=<key>
Local Dependencies
- Install solc-select and install solc 0.8.17 artifacts:
make solc-select
Run Certora Specs
- Run DssVestMintable Specs:
make certora-mintable
- Run DssVestSuckable Specs:
make certora-suckable
- Run DssVestTransferrable Specs:
make certora-transferrable
Foundry
Some foundry tests have been added extending the contracts to be ERC2771 compliant. Other unit tests can also be run with foundry. To do so, follow these steps:
-
Get a rpc URL that can be used for mainnet forks, e.g. from infura
-
Run
forge test --fork-url "$ETH_RPC_URL"
or
ETH_RPC_URL=$ETH_RPC_URL yarn test
Either replace
"$ETH_RPC_URL"
with the URL from step 1, or make sure the environment variable contains this URL.
NPM
Follow these steps to publish a new version of the package to NPM:
- prepare: update version in
package.json
- preview
npm publish --access public --dry-run
- publish
npm publish --access public