From 3bb9d624467c0ce658ce9a5cb7a8e714177b0aec Mon Sep 17 00:00:00 2001 From: thurendous Date: Fri, 13 Sep 2024 19:08:58 +0900 Subject: [PATCH] add more readme --- README.md | 35 ++++++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 83dfe80..8c3759e 100644 --- a/README.md +++ b/README.md @@ -123,15 +123,48 @@ There are 2 phases when we want to utilize this token in the protocol. After kic The GovToken is in a sense an achievement recorder. We want to make sure the achievement system is transparent and verifiable for all participants. That is why we did not make this token upgradable. -In fact, voting units in the token must be delegated to someone to be counted as actual voting power. +In fact, voting units in the token must be delegated to someone to be counted as actual voting power. The reason is mentioned in the documentation of OpenZeppelin contract. + +> In fact, voting units _must_ be delegated in order to count as actual votes, and an account has to +> delegate those votes to itself if it wishes to participate in decisions and does not have a trusted representative. ### `VotingPowerExchange.sol` +This contract is used to exchange the utility token for the governance token. The exchange is done by burning the governance token and minting the utility token. + +The voting power exchange contract is the minter of the governance token and the burner of the utility token. + #### Use cases and functions explanation +The contract has several functions to calculate the amount governance token the holder deserve to get by burning the utility token that he has. + +The main function is `exchange()`. It is the function that can only be called by the exchanger role. +Exchanger role is the role that supposed to be managed by the protocol owner. + +The function first checks the validity of the input which includes the sender's signature. The signature is generated off-chain and it can only be generated by the sender himself. + +This makes sure that the sender himself has the intention to exchange such amount of token. In this way, we want to prevent the case that the exchanger role is abused. + +Furthermore, the function checks the nonce and the expiration of the signature to make sure that the signature is fresh and valid. + +Then it calculates the amount of the governance token that the holder deserve to get. + +The calculation is based on the mathematical formula in the _References_ section. + +The contract sets a cap for the amount of the governance token that the holder can get. + +If someone is below the cap and has the utility token to exchange more than the cap, the function will only exchange the amount of the token that the cap allows. + +If someone has already reached the cap, the function will not allow the exchange. + +No one is allowed to get more voting power than the cap. + +After the calculation, the function will mint the governance token to the holder and burn the utility token from the holder. + #### Notes - The contract is created from scratch. +- There are some variables which are used to for the precision of the calculation. - `SafeERC20` is not used because the token contract we are using is known to be safe. ### `MyGovernor.sol`