From 8ea6f485ed387d8da81fd56122a964b1e1634d66 Mon Sep 17 00:00:00 2001 From: Ben DiFrancesco Date: Wed, 25 Sep 2024 15:53:41 -0400 Subject: [PATCH] WIP: update natspec and remove old commented vars --- src/GovernanceStaker.sol | 65 ++++++++++++++++++++-------------------- 1 file changed, 33 insertions(+), 32 deletions(-) diff --git a/src/GovernanceStaker.sol b/src/GovernanceStaker.sol index 211edda..f7f01b8 100644 --- a/src/GovernanceStaker.sol +++ b/src/GovernanceStaker.sol @@ -95,7 +95,20 @@ contract GovernanceStaker is INotifiableRewardReceiver, Multicall, EIP712, Nonce /// @param balance The deposit's staked balance. /// @param owner The owner of this deposit. /// @param delegatee The governance delegate who receives the voting weight for this deposit. - /// @param beneficiary The address that accrues staking rewards earned by this deposit. + /// @param beneficiary The address which has the right to withdraw rewards earned by this + /// deposit. + /// @param earningPower The "power" this deposit has as it pertains to earning rewards, which + /// accrue to this deposit at a rate proportional to its share of the total earning power of the + /// system. + /// @param rewardPerTokenCheckpoint Checkpoint of the reward per token accumulator for this + /// deposit. It represents the value of the global accumulator at the last time a given deposit's + /// rewards were calculated and stored. The difference between the global value and this value + /// can be used to calculate the interim rewards earned by given deposit. + /// @param scaledUnclaimedRewardCheckpoint Checkpoint of the unclaimed rewards earned by a given + /// deposit with the scale factor included. This value is stored any time an action is taken that + /// specifically impacts the rate at which rewards are earned by a given deposit. Total unclaimed + /// rewards for a deposit are thus this value plus all rewards earned after this checkpoint was + /// taken. This value is reset to zero when the deposit's rewards are claimed. struct Deposit { uint256 balance; address owner; @@ -155,9 +168,6 @@ contract GovernanceStaker is INotifiableRewardReceiver, Multicall, EIP712, Nonce /// @notice Tracks the total staked by a depositor across all unique deposits. mapping(address depositor => uint256 amount) public depositorTotalStaked; - /// @notice Tracks the total stake actively earning rewards for a given beneficiary account. - //mapping(address beneficiary => uint256 amount) public earningPower; - /// @notice Stores the metadata associated with a given deposit. mapping(DepositIdentifier depositId => Deposit deposit) public deposits; @@ -178,19 +188,6 @@ contract GovernanceStaker is INotifiableRewardReceiver, Multicall, EIP712, Nonce /// @notice Checkpoint value of the global reward per token accumulator. uint256 public rewardPerTokenAccumulatedCheckpoint; - /// @notice Checkpoint of the reward per token accumulator on a per account basis. It represents - /// the value of the global accumulator at the last time a given beneficiary's rewards were - /// calculated and stored. The difference between the global value and this value can be - /// used to calculate the interim rewards earned by given account. - // mapping(address account => uint256) public beneficiaryRewardPerTokenCheckpoint; - - /// @notice Checkpoint of the unclaimed rewards earned by a given beneficiary with the scale - /// factor included. This value is stored any time an action is taken that specifically impacts - /// the rate at which rewards are earned by a given beneficiary account. Total unclaimed rewards - /// for an account are thus this value plus all rewards earned after this checkpoint was taken. - /// This value is reset to zero when a beneficiary account claims their earned rewards. - //mapping(address account => uint256 amount) public scaledUnclaimedRewardCheckpoint; - /// @notice Maps addresses to whether they are authorized to call `notifyRewardAmount`. mapping(address rewardNotifier => bool) public isRewardNotifier; @@ -243,16 +240,17 @@ contract GovernanceStaker is INotifiableRewardReceiver, Multicall, EIP712, Nonce + (scaledRewardRate * (lastTimeRewardDistributed() - lastCheckpointTime)) / totalStaked; } - /// @notice Live value of the unclaimed rewards earned by a given beneficiary account. It is the - /// sum of the last checkpoint value of their unclaimed rewards with the live calculation of the + /// @notice Live value of the unclaimed rewards earned by a given deposit. It is the + /// sum of the last checkpoint value of the unclaimed rewards with the live calculation of the /// rewards that have accumulated for this account in the interim. This value can only increase, - /// until it is reset to zero once the beneficiary account claims their unearned rewards. + /// until it is reset to zero once the unearned rewards are claimed. /// /// Note that the contract tracks the unclaimed rewards internally with the scale factor /// included, in order to avoid the accrual of precision losses as users takes actions that /// cause rewards to be checkpointed. This external helper method is useful for integrations, and /// returns the value after it has been scaled down to the reward token's raw decimal amount. - /// @return Live value of the unclaimed rewards earned by a given beneficiary account. + /// @param _depositId Identifier of the deposit in question. + /// @return Live value of the unclaimed rewards earned by a given deposit. function unclaimedReward(DepositIdentifier _depositId) external view returns (uint256) { return _scaledUnclaimedReward(deposits[_depositId]) / SCALE_FACTOR; } @@ -473,10 +471,10 @@ contract GovernanceStaker is INotifiableRewardReceiver, Multicall, EIP712, Nonce _alterDelegatee(deposit, _depositId, _newDelegatee); } - /// @notice For an existing deposit, change the beneficiary to which staking rewards are - /// accruing. + /// @notice For an existing deposit, change the beneficiary account which has the right to + /// withdraw staking rewards. /// @param _depositId Unique identifier of the deposit which will have its beneficiary altered. - /// @param _newBeneficiary Address of the new rewards beneficiary. + /// @param _newBeneficiary Address of the new beneficiary. /// @dev The new beneficiary may not be the zero address. The message sender must be the owner of /// the deposit. function alterBeneficiary(DepositIdentifier _depositId, address _newBeneficiary) external { @@ -485,10 +483,11 @@ contract GovernanceStaker is INotifiableRewardReceiver, Multicall, EIP712, Nonce _alterBeneficiary(deposit, _depositId, _newBeneficiary); } - /// @notice For an existing deposit, change the beneficiary to which staking rewards are - /// accruing on behalf of a user, using a signature to validate the user's intent. + /// @notice For an existing deposit, change the beneficiary account which has the right to + /// withdraw staking rewards accruing on behalf of a user, using a signature to validate the + /// user's intent. /// @param _depositId Unique identifier of the deposit which will have its beneficiary altered. - /// @param _newBeneficiary Address of the new rewards beneficiary. + /// @param _newBeneficiary Address of the new beneficiary. /// @param _depositor Address of the user on whose behalf this stake is being made. /// @param _deadline The timestamp after which the signature should expire. /// @param _signature Signature of the user authorizing this stake. @@ -567,8 +566,9 @@ contract GovernanceStaker is INotifiableRewardReceiver, Multicall, EIP712, Nonce _withdraw(deposit, _depositId, _amount); } - /// @notice Claim reward tokens the message sender has earned as a stake beneficiary. Tokens are - /// sent to the message sender. + /// @notice Claim reward tokens earned by a given deposit. Message sender must be the beneficiary + /// address of the deposit. Tokens are sent to the beneficiary address. + /// @param _depositId Identifier of the deposit from which accrued rewards will be claimed. /// @return Amount of reward tokens claimed. function claimReward(DepositIdentifier _depositId) external returns (uint256) { Deposit storage deposit = deposits[_depositId]; @@ -578,8 +578,9 @@ contract GovernanceStaker is INotifiableRewardReceiver, Multicall, EIP712, Nonce return _claimReward(_depositId, deposit); } - /// @notice Claim earned reward tokens for a beneficiary, using a signature to validate the - /// beneficiary's intent. Tokens are sent to the beneficiary. + /// @notice Claim reward tokens earned by a given deposit, using a signature to validate the + /// caller's intent. The signer must be the beneficiary address of the deposit Tokens are sent to + /// the beneficiary. /// @param _depositId The identifier for the deposit for which to claim rewards. /// @param _deadline The timestamp after which the signature should expire. /// @param _signature Signature of the beneficiary authorizing this reward claim. @@ -830,7 +831,7 @@ contract GovernanceStaker is INotifiableRewardReceiver, Multicall, EIP712, Nonce } /// @notice Checkpoints the unclaimed rewards and reward per token accumulator of a given - /// beneficiary account. + /// deposit. /// @param deposit The deposit for which the reward parameters will be checkpointed. /// @dev This is a sensitive internal helper method that must only be called after global rewards /// accumulator has been checkpointed. It assumes the global `rewardPerTokenCheckpoint` is up to