Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix LockedGold comments #11256

Merged
merged 3 commits into from
Oct 16, 2024
Merged

Fix LockedGold comments #11256

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3d3080f
Fix comments/NatSpecs
m-chrzan Oct 16, 2024
3151dc3
Merge branch 'release/core-contracts/12' into m-chrzan/lockedgold-cle…
m-chrzan Oct 16, 2024
652a9d9
Merge branch 'release/core-contracts/12' into m-chrzan/lockedgold-cle…
martinvol Oct 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 65 additions & 47 deletions packages/protocol/contracts/governance/LockedGold.sol
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,10 @@ import "../common/interfaces/ICeloVersionedContract.sol";
import "../common/libraries/ReentrancyGuard.sol";
import "../common/Blockable.sol";

/**
* @title Manages the CELO locked for use in Celo governance, election, and
* staking systems.
*/
contract LockedGold is
ILockedGold,
ILockedGoldInitializer,
Expand All @@ -38,13 +42,13 @@ contract LockedGold is
uint256 timestamp;
}

// NOTE: This contract does not store an account's locked gold that is being used in electing
// NOTE: This contract does not store an account's locked CELO that is being used in electing
// validators.
struct Balances {
// The amount of locked gold that this account has that is not currently participating in
// The amount of locked CELO that this account has that is not currently participating in
// validator elections.
uint256 nonvoting;
// Gold that has been unlocked and will become available for withdrawal.
// CELO that has been unlocked and will become available for withdrawal.
PendingWithdrawal[] pendingWithdrawals;
}

Expand Down Expand Up @@ -106,6 +110,9 @@ contract LockedGold is
);
event MaxDelegateesCountSet(uint256 value);

/**
* @notice Ensures a function can only be called by an authorized slasher.
*/
modifier onlySlasher() {
require(
registry.isOneOf(slashingWhitelist, msg.sender),
Expand Down Expand Up @@ -133,7 +140,7 @@ contract LockedGold is
}

/**
* @notice Locks gold to be used for voting.
* @notice Locks CELO to be used for voting.
*/
function lock() external payable nonReentrant {
require(
Expand Down Expand Up @@ -172,8 +179,8 @@ contract LockedGold is
}

/**
* @notice Unlocks gold that becomes withdrawable after the unlocking period.
* @param value The amount of gold to unlock.
* @notice Unlocks CELO that becomes withdrawable after the unlocking period.
* @param value The amount of CELO to unlock.
*/
function unlock(uint256 value) external nonReentrant {
require(
Expand All @@ -183,7 +190,7 @@ contract LockedGold is
Balances storage account = balances[msg.sender];

uint256 totalLockedGold = getAccountTotalLockedGold(msg.sender);
// Prevent unlocking gold when voting on governance proposals so that the gold cannot be
// Prevent unlocking CELO when voting on governance proposals so that the CELO cannot be
// used to vote more than once.
uint256 remainingLockedGold = totalLockedGold.sub(value);

Expand Down Expand Up @@ -213,7 +220,7 @@ contract LockedGold is
}

/**
* @notice Relocks gold that has been unlocked but not withdrawn.
* @notice Relocks CELO that has been unlocked but not withdrawn.
* @param index The index of the pending withdrawal to relock from.
* @param value The value to relock from the specified pending withdrawal.
*/
Expand All @@ -237,7 +244,7 @@ contract LockedGold is
}

/**
* @notice Withdraws gold that has been unlocked after the unlocking period has passed.
* @notice Withdraws CELO that has been unlocked after the unlocking period has passed.
* @param index The index of the pending withdrawal to withdraw.
*/
function withdraw(uint256 index) external nonReentrant {
Expand All @@ -257,7 +264,7 @@ contract LockedGold is
}

/**
* Delegates CELO to delegatee.
* @notice Delegates CELO to delegatee.
* @param delegatee The delegatee account.
* @param delegateFraction Fraction of total CELO that will be delegated from delegatee. Fixidity fraction
*/
Expand Down Expand Up @@ -358,7 +365,7 @@ contract LockedGold is
}

/**
* Revokes delegated CELO.
* @notice Revokes delegated CELO.
* @param delegatee The delegatee acount.
* @param revokeFraction Fraction of total CELO that will be revoked from delegatee. Fixidity fraction
*/
Expand Down Expand Up @@ -448,11 +455,11 @@ contract LockedGold is
}

/**
* @notice Slashes `account` by reducing its nonvoting locked gold by `penalty`.
* If there is not enough nonvoting locked gold to slash, calls into
* `Election.slashVotes` to slash the remaining gold. If `account` does not have
* `penalty` worth of locked gold, slashes `account`'s total locked gold.
* Also sends `reward` gold to the reporter, and penalty-reward to the Community Fund.
* @notice Slashes `account` by reducing its nonvoting locked CELO by `penalty`.
* If there is not enough nonvoting locked CELO to slash, calls into
* `Election.slashVotes` to slash the remaining CELO. If `account` does not have
* `penalty` worth of locked CELO, slashes `account`'s total locked CELO.
* Also sends `reward` CELO to the reporter, and penalty-reward to the Community Fund.
* @param account Address of account being slashed.
* @param penalty Amount to slash account.
* @param reporter Address of account reporting the slasher.
Expand All @@ -462,7 +469,7 @@ contract LockedGold is
* @param greaters The groups receiving more votes than the i'th group, or 0 if the i'th group
* has the most votes of any validator group.
* @param indices The indices of the i'th group in `account`'s voting list.
* @dev Fails if `reward` is greater than `account`'s total locked gold.
* @dev Fails if `reward` is greater than `account`'s total locked CELO.
*/
function slash(
address account,
Expand Down Expand Up @@ -491,7 +498,7 @@ contract LockedGold is
require(
getElection().forceDecrementVotes(account, difference, lessers, greaters, indices) ==
difference,
"Cannot revoke enough voting gold."
"Cannot revoke enough voting CELO."
);
}
// forceDecrementVotes does not increment nonvoting account balance, so we can't double count
Expand All @@ -505,36 +512,43 @@ contract LockedGold is
emit AccountSlashed(account, maxSlash, reporter, reward);
}

/// @notice Sets the address of the blocking contract.
/// @param _blockedBy The address of the contract that will determine if this contract is blocked.
/// @dev Can only be called by the owner of the contract.
/**
* @notice Sets the address of the blocking contract.
* @param _blockedBy The address of the contract that will determine if this contract is blocked.
* @dev Can only be called by the owner of the contract.
*/
function setBlockedByContract(address _blockedBy) external onlyOwner {
_setBlockedBy(_blockedBy);
}

/**
* @notice Returns the total amount of locked gold in the system. Note that this does not include
* gold that has been unlocked but not yet withdrawn.
* @return The total amount of locked gold in the system.
* @notice Returns the total amount of locked CELO in the system. Note that this does not include
* CELO that has been unlocked but not yet withdrawn.
* @return The total amount of locked CELO in the system.
*/
function getTotalLockedGold() external view returns (uint256) {
return totalNonvoting.add(getElection().getTotalVotes());
}

/**
* @notice Returns the total amount of locked gold not being used to vote in elections.
* @return The total amount of locked gold not being used to vote in elections.
* @notice Returns the total amount of locked CELO not being used to vote in elections.
* @return The total amount of locked CELO not being used to vote in elections.
*/
function getNonvotingLockedGold() external view returns (uint256) {
return totalNonvoting;
}

/**
* @notice Queries if the given address is an approved slasher.
* @param slasher The address to check.
* @return Whether or not the address is an approved slasher.
*/
function isSlasher(address slasher) external view returns (bool) {
return (registry.isOneOf(slashingWhitelist, slasher));
}

/**
* Return percentage and amount that delegator assigned to delegateee.
* @notice Return percentage and amount that delegator assigned to delegateee.
* Please note that amount doesn't have to be up to date.
* In such case please use `updateDelegatedBalance`.
* @param delegator The delegator address.
Expand All @@ -554,16 +568,16 @@ contract LockedGold is
}

/**
* @notice Returns the total amount of non-voting locked gold for an account.
* @notice Returns the total amount of non-voting locked CELO for an account.
* @param account The account.
* @return The total amount of non-voting locked gold for an account.
* @return The total amount of non-voting locked CELO for an account.
*/
function getAccountNonvotingLockedGold(address account) external view returns (uint256) {
return balances[account].nonvoting;
}

/**
* @notice Returns the total amount to withdraw from unlocked gold for an account.
* @notice Returns the total amount to withdraw from unlocked CELO for an account.
* @param account The address of the account.
* @return Total amount to withdraw.
*/
Expand All @@ -576,6 +590,10 @@ contract LockedGold is
return pendingWithdrawalSum;
}

/**
* @notice Returns the list of approved slashers.
* @return List of Registry identifiers for the approved slashers.
*/
function getSlashingWhitelist() external view returns (bytes32[] memory) {
return slashingWhitelist;
}
Expand Down Expand Up @@ -626,7 +644,7 @@ contract LockedGold is
}

/**
* @notice Sets the duration in seconds users must wait before withdrawing gold after unlocking.
* @notice Sets the duration in seconds users must wait before withdrawing CELO after unlocking.
* @param value The unlocking period in seconds.
*/
function setUnlockingPeriod(uint256 value) public onlyOwner {
Expand All @@ -645,8 +663,8 @@ contract LockedGold is
}

/**
* Updates real delegated amount to delegatee.
* There might be discrepancy because of validator rewards or extra locked gold.
* @notice Updates real delegated amount to delegatee.
* There might be discrepancy because of validator rewards or extra locked CELO.
* Voting power will always be smaller or equal to what it is supposed to be.
* @param delegator The delegator address.
* @param delegatee The delegatee address.
Expand All @@ -659,8 +677,8 @@ contract LockedGold is
}

/**
* Updates real delegated amount to all delegator's delegatees.
* There might be discrepancy because of validator rewards or extra locked gold.
* @notice Updates real delegated amount to all delegator's delegatees.
* There might be discrepancy because of validator rewards or extra locked CELO.
* @param delegator The delegator address.
*/
function updateDelegatedAmount(address delegator) public {
Expand All @@ -678,7 +696,7 @@ contract LockedGold is
}

/**
* Retuns all delegatees of delegator
* @notice Retuns all delegatees of delegator
* @param delegator The delegator address.
*/
function getDelegateesOfDelegator(address delegator) public view returns (address[] memory) {
Expand Down Expand Up @@ -718,7 +736,7 @@ contract LockedGold is
}

/**
* Returns how many percents of CELO is account delegating.
* @notice Returns how many percents of CELO is account delegating.
* @param account The account address.
*/
function getAccountTotalDelegatedFraction(address account) public view returns (uint256) {
Expand All @@ -727,19 +745,19 @@ contract LockedGold is
}

/**
* @notice Returns the total amount of locked gold for an account.
* @notice Returns the total amount of locked CELO for an account.
* @param account The account.
* @return The total amount of locked gold for an account.
* @return The total amount of locked CELO for an account.
*/
function getAccountTotalLockedGold(address account) public view returns (uint256) {
uint256 total = balances[account].nonvoting;
return total.add(getElection().getTotalVotesByAccount(account));
}

/**
* @notice Returns the total amount of locked gold + delegated gold for an account.
* @notice Returns the total amount of locked CELO + delegated CELO for an account.
* @param account The account.
* @return The total amount of locked gold + delegated gold for an account.
* @return The total amount of locked CELO + delegated CELO for an account.
*/
function getAccountTotalGovernanceVotingPower(address account) public view returns (uint256) {
FixidityLib.Fraction memory availableUndelegatedPercents = FixidityLib.fixed1().subtract(
Expand All @@ -756,7 +774,7 @@ contract LockedGold is
}

/**
* Returns expected vs real delegated amount.
* @notice Returns expected and real delegated amount.
* If there is a discrepancy it can be fixed by calling `updateDelegatedAmount` function.
* @param delegator The delegator address.
* @param delegatee The delegatee address.
Expand All @@ -777,8 +795,8 @@ contract LockedGold is
}

/**
* Updates real delegated amount to delegatee.
* There might be discrepancy because of validator rewards or extra locked gold.
* @notice Updates real delegated amount to delegatee.
* There might be discrepancy because of validator rewards or extra locked CELO.
* Voting power will always be smaller or equal to what it is supposed to be.
* @param delegator The delegator address.
* @param delegatee The delegatee address.
Expand Down Expand Up @@ -829,7 +847,7 @@ contract LockedGold is
}

/**
* Revokes amount during unlocking. It will revoke votes from voted proposals if necessary.
* @notice Revokes amount during unlocking. It will revoke votes from voted proposals if necessary.
* @param delegator The delegator account.
* @param amountToRevoke The amount to revoke.
*/
Expand Down Expand Up @@ -857,7 +875,7 @@ contract LockedGold is
}

/**
* Decreases delegatee voting power when removing or unlocking delegated votes.
* @notice Decreases delegatee voting power when removing or unlocking delegated votes.
* @param delegatee The delegatee.
* @param amountToRevoke Amount to revoke.
* @param delegateeInfo Delegatee info.
Expand Down Expand Up @@ -900,7 +918,7 @@ contract LockedGold is
}

/**
* Returns expected vs real delegated amount.
* @notice Returns expected and real delegated amount.
* If there is a discrepancy it can be fixed by calling `updateDelegatedAmount` function.
* @param delegator The delegator address.
* @param delegatee The delegatee address.
Expand Down
Loading