add some readme and some doc in code

.gas-snapshot

@@ -0,0 +1,156 @@
+AmbassadorTest:testBalanceOfBatchWorks() (gas: 26010)
+AmbassadorTest:testBalanceOfWorks() (gas: 31180)
+AmbassadorTest:testBurnBatchCanBeCalledByBurner() (gas: 75954)
+AmbassadorTest:testBurnBatchWillFailByNonBurner() (gas: 85060)
+AmbassadorTest:testBurningTokenSuccessfully() (gas: 115515)
+AmbassadorTest:testBurningTokenWillFailByNonBurner() (gas: 127990)
+AmbassadorTest:testBurningTokenWillSucceedByNewBurner() (gas: 140025)
+AmbassadorTest:testConstructorWillRevertIfAdminIsZero() (gas: 49376)
+AmbassadorTest:testMintBatchWillWork() (gas: 81972)
+AmbassadorTest:testMintingTokenWillFailByNonMinter() (gas: 29783)
+AmbassadorTest:testMintingTokenWillSucceedByNewMinter() (gas: 165748)
+AmbassadorTest:testMintingTokensSuccessfully() (gas: 123301)
+AmbassadorTest:testSetURI() (gas: 51205)
+AmbassadorTest:testSetURIByNonUriSetter() (gas: 12128)
+AmbassadorTest:testSupportsInterface() (gas: 16538)
+AmbassadorTest:testTokenRoles() (gas: 39075)
+AmbassadorTest:testTransferWillWork() (gas: 61413)
+ERC20UpgradeableTokenV1Test:testApprovingAllAndTransferFromAll() (gas: 67881)
+ERC20UpgradeableTokenV1Test:testApprovingAllAndTransferFromHalf() (gas: 90094)
+ERC20UpgradeableTokenV1Test:testApprovingAndTransferFrom() (gas: 70217)
+ERC20UpgradeableTokenV1Test:testApprovingSpending() (gas: 47204)
+ERC20UpgradeableTokenV1Test:testDefaultAdminCannotBeZero() (gas: 3404094)
+ERC20UpgradeableTokenV1Test:testFailingToBurnTokens() (gas: 35201)
+ERC20UpgradeableTokenV1Test:testGrantRoles() (gas: 63145)
+ERC20UpgradeableTokenV1Test:testGrantingAndRevokingRoles() (gas: 49891)
+ERC20UpgradeableTokenV1Test:testPausingAndUnpausingSuccessfully() (gas: 36164)
+ERC20UpgradeableTokenV1Test:testRolesAreSetCorrectly() (gas: 45900)
+ERC20UpgradeableTokenV1Test:testSendingTokens() (gas: 89772)
+ERC20UpgradeableTokenV1Test:testShowingBasicTokenInfo() (gas: 31607)
+ERC20UpgradeableTokenV1Test:testSucceedingToBurnTokens() (gas: 39063)
+ERC20UpgradeableTokenV1Test:testUpgradeabilityOfToken() (gas: 3680933)
+ERC20UpgradeableTokenV1Test:testWhenPausedNoMintingOrTransferringIsAllowed() (gas: 61788)
+GovTokenTest:testBurningCanBeDoneByBurner() (gas: 71425)
+GovTokenTest:testBurningCanBeDoneByNewBurner() (gas: 104676)
+GovTokenTest:testBurningCannotBeDoneByNonBurner() (gas: 31512)
+GovTokenTest:testClock() (gas: 14358)
+GovTokenTest:testClockMode() (gas: 11350)
+GovTokenTest:testDelegateBySig() (gas: 90761)
+GovTokenTest:testDelegates() (gas: 29514)
+GovTokenTest:testGovTokenDefaultAdminCannotBeZero() (gas: 98903)
+GovTokenTest:testInitialVotes() (gas: 28882)
+GovTokenTest:testMintingCanBeDoneByMinter() (gas: 95606)
+GovTokenTest:testMintingCanBeDoneByNewMinter() (gas: 126921)
+GovTokenTest:testMintingCannotBeDoneByNonMinter() (gas: 41757)
+GovTokenTest:testNonRoleCannotCallSetBurnedAmountOfUtilToken() (gas: 31075)
+GovTokenTest:testNonces() (gas: 67641)
+GovTokenTest:testSetBurnedAmountOfUtilTokenEvent() (gas: 77722)
+GovTokenTest:testTheRolesOfTheGovToken() (gas: 31013)
+GovTokenTest:testTheTokenInfos() (gas: 21406)
+GovTokenTest:testTokensAreNotTransferrable() (gas: 49053)
+GovTokenTest:testVotesAfterDelegateToOther() (gas: 141319)
+GovTokenTest:testVotesAfterSelfDelegate() (gas: 100610)
+GovTokenTest:testVotingPowerExchangeCanCallSetBurnedAmountOfUtilToken() (gas: 73352)
+VotingPowerExchangeTest:testBasicVotingPowerExchangeInfo() (gas: 14590)
+VotingPowerExchangeTest:testCalculateIncrementedBurningAmountWhenCurrentIsNotZero() (gas: 48619)
+VotingPowerExchangeTest:testCalculateIncrementedBurningAmountWhenCurrentIsZero() (gas: 41986)
+VotingPowerExchangeTest:testCalculationOfIncreasedVotingPowerWhenCurrentIsNotZero() (gas: 70426)
+VotingPowerExchangeTest:testCalculationOfIncreasedVotingPowerWhenCurrentIsZero() (gas: 50901)
+VotingPowerExchangeTest:testConstantValues() (gas: 11697)
+VotingPowerExchangeTest:testConstructorOfVotingPowerExchange() (gas: 2236713)
+VotingPowerExchangeTest:testExchangeFailCaseWhenAmountIsTooSmall() (gas: 41022)
+VotingPowerExchangeTest:testExchangeFailCaseWhenNonceIsUsed() (gas: 202448)
+VotingPowerExchangeTest:testExchangeFailCaseWhenSenderIsNotSigner() (gas: 67348)
+VotingPowerExchangeTest:testExchangeFailCaseWhenSignatureExpired() (gas: 44099)
+VotingPowerExchangeTest:testExchangeFailCaseWhenSignatureIsInvalid() (gas: 67050)
+VotingPowerExchangeTest:testExchangeFailCaseWhenUserGotMoreThanVotingPowerCap() (gas: 133248)
+VotingPowerExchangeTest:testExchangeFailsWhenSenderIsZeroAddress() (gas: 38841)
+VotingPowerExchangeTest:testExchangeLargeAmountSuccessCase() (gas: 210242)
+VotingPowerExchangeTest:testExchangeMediumAmountSuccessCase() (gas: 215165)
+VotingPowerExchangeTest:testExchangeSmallAmountSuccessCase() (gas: 210504)
+VotingPowerExchangeTest:testExchangeTwiceToCrossVotingPowerCapFailureCase() (gas: 249775)
+VotingPowerExchangeTest:testExchangeTwiceToGetToVotingPowerCapSuccessCase() (gas: 304984)
+VotingPowerExchangeTest:testExchangeVotingPowerCapSuccessCase() (gas: 221279)
+VotingPowerExchangeTest:testGovTokenBasicInfo() (gas: 25278)
+VotingPowerExchangeTest:testGovTokenNotBeingTransferrable() (gas: 68747)
+VotingPowerExchangeTest:testReturnedSetupValues() (gas: 63204)
+VotingPowerExchangeTest:testSettingVotingPowerCap() (gas: 25153)
+VotingPowerExchangeTest:testSettingVotingPowerCapFails() (gas: 14249)
+VotingPowerExchangeTest:testSettingVotingPowerCapFailsCase2() (gas: 23198)
+VotingPowerExchangeTest:testTokensAccessRoles() (gas: 70485)
+VotingPowerExchangeTest:testTokensBalanceOf() (gas: 27834)
+VotingPowerExchangeTest:testTokensBurning() (gas: 86324)
+VotingPowerExchangeTest:testUtilityTokenBasicInfo() (gas: 31675)
+VotingPowerExchangeTest:testUtilityTokenCanBeTransferred() (gas: 88383)
+VotingPowerExchangeTest:testUtilityTokensPausability() (gas: 76194)
+VotingPowerExchangeTest:testVotingPowerCap() (gas: 11060)
+VotingPowerExchangeTest:testVotingPowerExchangesRoles() (gas: 57604)
+VotingPowerExchangeUnitTest:testCalculateBurningAmountFromVotingPower() (gas: 347974)
+VotingPowerExchangeUnitTest:testCalculateIncrementedBurningAmount() (gas: 55875)
+VotingPowerExchangeUnitTest:testCalculateIncrementedVotingPower() (gas: 77126)
+VotingPowerExchangeUnitTest:testCalculateVotingPowerFromBurnedAmount() (gas: 480905)
+VotingPowerExchangeUnitTest:testCalculateVotingPowerFromBurnedAmountRareCases() (gas: 34497)
+VotingPowerExchangeUnitTest:testCalculationOfVotingPowerMintingWhenMintedSeparately() (gas: 17907)
+VotingPowerExchangeUnitTest:testCalculationOfVotingPowerMintingWhenMintedSeparately2() (gas: 18027)
+VotingPowerExchangeUnitTest:testConstructorValidation() (gas: 109717)
+VotingPowerExchangeUnitTest:testSomeMoreSpecialCasesForCalculateVotingPowerFromBurnedAmount() (gas: 15833)
+VotingPowerExchangeUnitTest:testSpecialCasesForCalculateVotingPowerFromBurnedAmount() (gas: 15772)
+VotingPwoerExchangeTest:testCalculateIncrementedVotingPower(uint256) (runs: 4104, μ: 20724, ~: 20079)
+VotingPwoerExchangeTest:testCalculateIncrementedVotingPower_0_to_10(uint256) (runs: 4104, μ: 20700, ~: 20033)
+VotingPwoerExchangeTest:testCalculateIncrementedVotingPower_100_to_110(uint256) (runs: 4104, μ: 20643, ~: 19997)
+VotingPwoerExchangeTest:testCalculateIncrementedVotingPower_10_to_110(uint256) (runs: 4104, μ: 21431, ~: 21491)
+VotingPwoerExchangeTest:testCalculateIncrementedVotingPower_10_to_20(uint256) (runs: 4104, μ: 20715, ~: 20060)
+VotingPwoerExchangeTest:testCalculateIncrementedVotingPower_20_to_30(uint256) (runs: 4104, μ: 20735, ~: 20082)
+VotingPwoerExchangeTest:testCalculateIncrementedVotingPower_30_to_40(uint256) (runs: 4104, μ: 20829, ~: 20178)
+VotingPwoerExchangeTest:testCalculateIncrementedVotingPower_40_to_50(uint256) (runs: 4104, μ: 20768, ~: 20122)
+VotingPwoerExchangeTest:testCalculateIncrementedVotingPower_50_to_60(uint256) (runs: 4104, μ: 20889, ~: 20238)
+VotingPwoerExchangeTest:testCalculateIncrementedVotingPower_60_to_70(uint256) (runs: 4104, μ: 20852, ~: 20215)
+VotingPwoerExchangeTest:testCalculateIncrementedVotingPower_70_to_80(uint256) (runs: 4104, μ: 20713, ~: 20065)
+VotingPwoerExchangeTest:testCalculateIncrementedVotingPower_80_to_90(uint256) (runs: 4104, μ: 20663, ~: 20021)
+VotingPwoerExchangeTest:testCalculateIncrementedVotingPower_90_to_100(uint256) (runs: 4104, μ: 20665, ~: 20024)
+VotingPwoerExchangeTest:testExchangeWithAnyAmountLessThan1e18WillRevert(uint256) (runs: 4100, μ: 41692, ~: 41692)
+VotingPwoerExchangeTest:testExchangeWithAnyAmountWhichIsInRangeWillSucceed(uint256) (runs: 4104, μ: 218340, ~: 218466)
+VotingPwoerExchangeTest:testExchangeWithAnyAmountWithinNewCapWillSucceed(uint256) (runs: 4104, μ: 229223, ~: 229377)
+VotingPwoerExchangeTest:testExchangeWithAnyExpirationWhichIsExpiredWillRevert(uint256) (runs: 4104, μ: 46557, ~: 47250)
+VotingPwoerExchangeTest:testExchangeWithAnyExpirationWhichIsNotExpiredWillSucceed(uint256) (runs: 4103, μ: 228136, ~: 228136)
+VotingPwoerExchangeTest:testExchangeWithAnyNonceWhichIsUsedWillRevert(bytes32) (runs: 4104, μ: 202877, ~: 202877)
+VotingPwoerExchangeTest:testExchangeWithAnyRoleWhoIsNotExchangerWillRevert(address) (runs: 4104, μ: 44206, ~: 44206)
+VotingPwoerExchangeTest:testExchangeWithAnySenderWhoIsNotTheSignerWillRevert(address) (runs: 4104, μ: 70231, ~: 70233)
+VotingPwoerExchangeTest:testFuzzCalculateBurningAmountFromVotingPower_0_10(uint256) (runs: 4104, μ: 17869, ~: 17187)
+VotingPwoerExchangeTest:testFuzzCalculateBurningAmountFromVotingPower_0_110(uint256) (runs: 4104, μ: 17856, ~: 17186)
+VotingPwoerExchangeTest:testFuzzCalculateBurningAmountFromVotingPower_100_110(uint256) (runs: 4104, μ: 18594, ~: 18639)
+VotingPwoerExchangeTest:testFuzzCalculateBurningAmountFromVotingPower_10_20(uint256) (runs: 4104, μ: 18569, ~: 18615)
+VotingPwoerExchangeTest:testFuzzCalculateBurningAmountFromVotingPower_20_30(uint256) (runs: 4104, μ: 18548, ~: 18595)
+VotingPwoerExchangeTest:testFuzzCalculateBurningAmountFromVotingPower_30_40(uint256) (runs: 4104, μ: 18618, ~: 18663)
+VotingPwoerExchangeTest:testFuzzCalculateBurningAmountFromVotingPower_40_50(uint256) (runs: 4104, μ: 18638, ~: 18683)
+VotingPwoerExchangeTest:testFuzzCalculateBurningAmountFromVotingPower_50_60(uint256) (runs: 4104, μ: 18639, ~: 18684)
+VotingPwoerExchangeTest:testFuzzCalculateBurningAmountFromVotingPower_60_70(uint256) (runs: 4104, μ: 18616, ~: 18662)
+VotingPwoerExchangeTest:testFuzzCalculateBurningAmountFromVotingPower_70_80(uint256) (runs: 4104, μ: 18574, ~: 18618)
+VotingPwoerExchangeTest:testFuzzCalculateBurningAmountFromVotingPower_80_90(uint256) (runs: 4104, μ: 18617, ~: 18662)
+VotingPwoerExchangeTest:testFuzzCalculateBurningAmountFromVotingPower_90_100(uint256) (runs: 4104, μ: 18618, ~: 18663)
+VotingPwoerExchangeTest:testFuzzCalculateIncrementedBurningAmount_0_to_110(uint256) (runs: 4104, μ: 17928, ~: 17258)
+VotingPwoerExchangeTest:testFuzzCalculateIncrementedBurningAmount_100_to_110(uint256) (runs: 4104, μ: 17970, ~: 17288)
+VotingPwoerExchangeTest:testFuzzCalculateIncrementedBurningAmount_10_to_110(uint256) (runs: 4104, μ: 17999, ~: 17329)
+VotingPwoerExchangeTest:testFuzzCalculateIncrementedBurningAmount_20_to_110(uint256) (runs: 4104, μ: 17959, ~: 17288)
+VotingPwoerExchangeTest:testFuzzCalculateIncrementedBurningAmount_30_to_110(uint256) (runs: 4104, μ: 17937, ~: 17266)
+VotingPwoerExchangeTest:testFuzzCalculateIncrementedBurningAmount_40_to_110(uint256) (runs: 4104, μ: 18003, ~: 17332)
+VotingPwoerExchangeTest:testFuzzCalculateIncrementedBurningAmount_50_to_110(uint256) (runs: 4104, μ: 17938, ~: 17265)
+VotingPwoerExchangeTest:testFuzzCalculateIncrementedBurningAmount_60_to_110(uint256) (runs: 4104, μ: 17982, ~: 17308)
+VotingPwoerExchangeTest:testFuzzCalculateIncrementedBurningAmount_70_to_110(uint256) (runs: 4104, μ: 17961, ~: 17287)
+VotingPwoerExchangeTest:testFuzzCalculateIncrementedBurningAmount_80_to_110(uint256) (runs: 4104, μ: 17919, ~: 17244)
+VotingPwoerExchangeTest:testFuzzCalculateIncrementedBurningAmount_90_to_110(uint256) (runs: 4104, μ: 17988, ~: 17310)
+VotingPwoerExchangeTest:testFuzzCalculateVotingPowerFromBurnedAmount(uint256) (runs: 4104, μ: 20407, ~: 19752)
+VotingPwoerExchangeTest:testFuzzCalculateVotingPowerFromBurnedAmount_0_925(uint256) (runs: 4104, μ: 20404, ~: 19731)
+VotingPwoerExchangeTest:testFuzzCalculateVotingPowerFromBurnedAmount_12700_19625(uint256) (runs: 4104, μ: 21358, ~: 21399)
+VotingPwoerExchangeTest:testFuzzCalculateVotingPowerFromBurnedAmount_19625_28050(uint256) (runs: 4104, μ: 21350, ~: 21402)
+VotingPwoerExchangeTest:testFuzzCalculateVotingPowerFromBurnedAmount_28050_37975(uint256) (runs: 4104, μ: 21352, ~: 21401)
+VotingPwoerExchangeTest:testFuzzCalculateVotingPowerFromBurnedAmount_3350_7275(uint256) (runs: 4104, μ: 21235, ~: 21270)
+VotingPwoerExchangeTest:testFuzzCalculateVotingPowerFromBurnedAmount_37975_49400(uint256) (runs: 4104, μ: 21218, ~: 21251)
+VotingPwoerExchangeTest:testFuzzCalculateVotingPowerFromBurnedAmount_49400_62325(uint256) (runs: 4104, μ: 21222, ~: 21271)
+VotingPwoerExchangeTest:testFuzzCalculateVotingPowerFromBurnedAmount_62325_76750(uint256) (runs: 4104, μ: 21212, ~: 21252)
+VotingPwoerExchangeTest:testFuzzCalculateVotingPowerFromBurnedAmount_7275_12700(uint256) (runs: 4104, μ: 21270, ~: 21330)
+VotingPwoerExchangeTest:testFuzzCalculateVotingPowerFromBurnedAmount_76750_92675(uint256) (runs: 4104, μ: 21246, ~: 21275)
+VotingPwoerExchangeTest:testFuzzCalculateVotingPowerFromBurnedAmount_925_3350(uint256) (runs: 4104, μ: 21297, ~: 21361)
+VotingPwoerExchangeTest:testSetVotingPowerCap(uint256) (runs: 4100, μ: 25451, ~: 25451)
+VotingPwoerExchangeTest:testSetVotingPowerCap_revertWhenLowerThanExisting(uint256) (runs: 4100, μ: 18046, ~: 18046)
+VotingPwoerExchangeTest:testSetVotingPowerCap_revertWhenNonManagerCalled(address) (runs: 4104, μ: 17759, ~: 17759)

README.md

@@ -161,6 +161,8 @@ 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.
 
+The function also updates the amount of the utility token that the holder has burned in the GovToken contract.
+
 #### Notes
 
 - The contract is created from scratch.

src/GovToken.sol

@@ -23,7 +23,6 @@ contract GovToken is ERC20, ERC20Burnable, AccessControl, ERC20Permit, ERC20Vote
     // added for recording the amount of utility tokens burned by a specific account
     mapping(address account => uint256 burnedAmount) public burnedAmountOfUtilToken;
 
-    /// votingPowerExchange role is supposed to be only granted to VotingPowerExchange contract
     constructor(
         string memory name,
         string memory symbol,
@@ -38,12 +37,13 @@ contract GovToken is ERC20, ERC20Burnable, AccessControl, ERC20Permit, ERC20Vote
         _grantRole(MINTER_ROLE, minter);
         _grantRole(BURNER_ROLE, burner);
         _grantRole(BURNER_ROLE, burner);
+        // votingPowerExchange role is supposed to be only granted to VotingPowerExchange contract
         _grantRole(VOTING_POWER_EXCHANGE_ROLE, votingPowerExchange);
     }
 
     // The following functions are overrides required by Solidity.
     /// @dev this function is intentionally made this way to not allow token transfer
-    /// @dev instead minting and burning is allowed
+    /// @dev on the other hand, minting and burning are allowed
     /// @dev added this function to the original contract
     ///
     function _update(address from, address to, uint256 value) internal override(ERC20, ERC20Votes) {
@@ -84,15 +84,28 @@ contract GovToken is ERC20, ERC20Burnable, AccessControl, ERC20Permit, ERC20Vote
         emit burnedAmountOfUtilTokenSet(account, amount);
     }
 
+    /**
+     * @notice Overrides the clock function to return the current timestamp.
+     * @return The current timestamp.
+     */
     function clock() public view override returns (uint48) {
         return uint48(block.timestamp);
     }
 
+    /**
+     * @notice Overrides the CLOCK_MODE function to return the current timestamp.
+     * @return The current timestamp.
+     */
     // solhint-disable-next-line func-name-mixedcase
     function CLOCK_MODE() public pure override returns (string memory) {
         return "mode=timestamp";
     }
 
+    /**
+     * @notice Overrides the nonces function to return the nonce of the owner.
+     * @param owner The address of the owner.
+     * @return The nonce of the owner.
+     */
     function nonces(address owner) public view override(ERC20Permit, Nonces) returns (uint256) {
         return super.nonces(owner);
     }