Rename all the things

Author: davidlaprade

src/FlexVotingClient.sol

@@ -79,14 +79,15 @@ abstract contract FlexVotingClient {
   /// must be one that supports fractional voting, e.g. GovernorCountingFractional.
   IFractionalGovernor public immutable GOVERNOR;
 
-  /// @dev Mapping from address to the checkpoint history of raw balances
-  /// of that address.
-  mapping(address => Checkpoints.Trace208) internal balanceCheckpoints;
+  /// @dev Mapping from address to the checkpoint history of internal voting
+  /// weight for that address, i.e. how much weight they can call `expressVote`
+  /// with at a given time.
+  mapping(address => Checkpoints.Trace208) internal voteWeightCheckpoints;
 
-  /// @dev History of the sum total of raw balances in the system. May or may
+  /// @dev History of the sum total of voting weight in the system. May or may
   /// not be equivalent to this contract's balance of `GOVERNOR`s token at a
   /// given time.
-  Checkpoints.Trace208 internal totalBalanceCheckpoints;
+  Checkpoints.Trace208 internal totalVoteWeightCheckpoints;
 
   // https://github.com/OpenZeppelin/openzeppelin-contracts/blob/7b74442c5e87ea51dde41c7f18a209fa5154f1a4/contracts/governance/extensions/GovernorCountingFractional.sol#L37
   uint8 internal constant VOTE_TYPE_FRACTIONAL = 255;
@@ -124,7 +125,7 @@ abstract contract FlexVotingClient {
   /// @param support The depositor's vote preferences in accordance with the `VoteType` enum.
   function expressVote(uint256 proposalId, uint8 support) external virtual {
     address voter = msg.sender;
-    uint256 weight = getPastRawBalance(voter, GOVERNOR.proposalSnapshot(proposalId));
+    uint256 weight = getPastVoteWeight(voter, GOVERNOR.proposalSnapshot(proposalId));
     if (weight == 0) revert FlexVotingClient__NoVotingWeight();
 
     if (proposalVotersHasVoted[proposalId][voter]) revert FlexVotingClient__AlreadyVoted();
@@ -143,10 +144,12 @@ abstract contract FlexVotingClient {
   }
 
   /// @notice Causes this contract to cast a vote to the Governor for all of the
-  /// accumulated votes expressed by users. Uses the sum of all raw balances to
-  /// proportionally split its voting weight. Can be called by anyone. Can be
-  /// called multiple times during the lifecycle of a given proposal.
-  /// @param proposalId The ID of the proposal which the Pool will now vote on.
+  /// accumulated votes expressed by users. Uses the total internal vote weight
+  /// to proportionally split weight among expressed votes. Can be called by
+  /// anyone. It is idempotent and can be called multiple times during the
+  /// lifecycle of a given proposal.
+  /// @param proposalId The ID of the proposal which the FlexVotingClient will
+  /// now vote on.
   function castVote(uint256 proposalId) external {
     ProposalVote storage _proposalVote = proposalVotes[proposalId];
     if (_proposalVote.forVotes + _proposalVote.againstVotes + _proposalVote.abstainVotes == 0) {
@@ -155,7 +158,7 @@ abstract contract FlexVotingClient {
 
     uint256 _proposalSnapshot = GOVERNOR.proposalSnapshot(proposalId);
 
-    // We use the snapshot of total raw balances to determine the weight with
+    // We use the snapshot of total vote weight to determine the weight with
     // which to vote. We do this for two reasons:
     //   (1) We cannot use the proposalVote numbers alone, since some people with
     //       balances at the snapshot might never express their preferences. If a
@@ -168,28 +171,28 @@ abstract contract FlexVotingClient {
     //       earlier call to this function. The weight of those preferences
     //       should still be taken into consideration when determining how much
     //       weight to vote with this time.
-    // Using the total raw balance to proportion votes in this way means that in
+    // Using the total vote weight to proportion votes in this way means that in
     // many circumstances this function will not cast votes with all of its
     // weight.
-    uint256 _totalRawBalanceAtSnapshot = getPastTotalBalance(_proposalSnapshot);
+    uint256 _totalVotesInternal = getPastTotalVoteWeight(_proposalSnapshot);
 
     // We need 256 bits because of the multiplication we're about to do.
-    uint256 _votingWeightAtSnapshot =
+    uint256 _totalTokenWeight =
       IVotingToken(address(GOVERNOR.token())).getPastVotes(address(this), _proposalSnapshot);
 
-    //      forVotesRaw          forVoteWeight
-    // --------------------- = ------------------
-    //     totalRawBalance      totalVoteWeight
+    //     userVotesInternal          userVoteWeight
+    // ------------------------- = --------------------
+    //     totalVotesInternal         totalTokenWeight
     //
-    // forVoteWeight = forVotesRaw * totalVoteWeight / totalRawBalance
+    // userVoteWeight = userVotesInternal * totalTokenWeight / totalVotesInternal
     uint128 _forVotesToCast = SafeCast.toUint128(
-      (_votingWeightAtSnapshot * _proposalVote.forVotes) / _totalRawBalanceAtSnapshot
+      (_totalTokenWeight * _proposalVote.forVotes) / _totalVotesInternal
     );
     uint128 _againstVotesToCast = SafeCast.toUint128(
-      (_votingWeightAtSnapshot * _proposalVote.againstVotes) / _totalRawBalanceAtSnapshot
+      (_totalTokenWeight * _proposalVote.againstVotes) / _totalVotesInternal
     );
     uint128 _abstainVotesToCast = SafeCast.toUint128(
-      (_votingWeightAtSnapshot * _proposalVote.abstainVotes) / _totalRawBalanceAtSnapshot
+      (_totalTokenWeight * _proposalVote.abstainVotes) / _totalVotesInternal
     );
 
     // Clear the stored votes so that we don't double-cast them.
@@ -206,11 +209,9 @@ abstract contract FlexVotingClient {
     Checkpoints.Trace208 storage _checkpoint,
     int256 _delta
   ) internal returns (uint208 _prevTotal, uint208 _newTotal) {
-
     // The casting in this function is safe since:
     // - if oldTotal + delta > int256.max it will panic and revert.
-    // - if |delta| <= oldTotal
-    //   * there is no risk of wrapping
+    // - if |delta| <= oldTotal there is no risk of wrapping
     // - if |delta| > oldTotal
     //   * uint256(oldTotal + delta) will wrap but the wrapped value will
     //     necessarily be greater than uint208.max, so SafeCast will revert.
@@ -232,35 +233,35 @@ abstract contract FlexVotingClient {
     _checkpoint.push(_timepoint, _newTotal);
   }
 
-  /// @dev Checkpoints the _user's current raw balance.
-  function _checkpointRawBalanceOf(
+  /// @dev Checkpoints internal voting weight of `user` after applying `_delta`.
+  function _checkpointVoteWeightOf(
     address _user,
     int256 _delta
   ) internal virtual {
-    _applyDeltaToCheckpoint(balanceCheckpoints[_user], _delta);
+    _applyDeltaToCheckpoint(voteWeightCheckpoints[_user], _delta);
   }
 
-  /// @dev Checkpoints the total balance after applying `_delta`.
-  function _checkpointTotalBalance(int256 _delta) internal virtual {
-    _applyDeltaToCheckpoint(totalBalanceCheckpoints, _delta);
+  /// @dev Checkpoints the total vote weight after applying `_delta`.
+  function _checkpointTotalVoteWeight(int256 _delta) internal virtual {
+    _applyDeltaToCheckpoint(totalVoteWeightCheckpoints, _delta);
   }
 
-  /// @notice Returns the `_user`'s raw balance at `_timepoint`.
-  /// @param _user The account that's historical raw balance will be looked up.
-  /// @param _timepoint The timepoint at which to lookup the _user's raw
-  /// balance, either a block number or a timestamp as determined by
+  /// @notice Returns the `_user`'s internal voting weight at `_timepoint`.
+  /// @param _user The account that's historical vote weight will be looked up.
+  /// @param _timepoint The timepoint at which to lookup the _user's internal
+  /// voting weight, either a block number or a timestamp as determined by
   /// {GOVERNOR.token().clock()}.
-  function getPastRawBalance(address _user, uint256 _timepoint) public view returns (uint256) {
+  function getPastVoteWeight(address _user, uint256 _timepoint) public view returns (uint256) {
     uint48 key = SafeCast.toUint48(_timepoint);
-    return balanceCheckpoints[_user].upperLookup(key);
+    return voteWeightCheckpoints[_user].upperLookup(key);
   }
 
-  /// @notice Returns the sum total of raw balances of all users at `_timepoint`.
-  /// @param _timepoint The timepoint at which to lookup the total balance,
+  /// @notice Returns the total internal voting weight of all users at `_timepoint`.
+  /// @param _timepoint The timepoint at which to lookup the total weight,
   /// either a block number or a timestamp as determined by
   /// {GOVERNOR.token().clock()}.
-  function getPastTotalBalance(uint256 _timepoint) public view returns (uint256) {
+  function getPastTotalVoteWeight(uint256 _timepoint) public view returns (uint256) {
     uint48 key = SafeCast.toUint48(_timepoint);
-    return totalBalanceCheckpoints.upperLookup(key);
+    return totalVoteWeightCheckpoints.upperLookup(key);
   }
 }

src/FlexVotingDelegatable.sol

@@ -48,12 +48,12 @@ abstract contract FlexVotingDelegatable is Context, FlexVotingClient {
     _updateDelegateBalance(oldDelegate, delegatee, _delta);
   }
 
-  function _checkpointRawBalanceOf(
+  function _checkpointVoteWeightOf(
     address _user,
     int256 _delta
   ) internal virtual override {
     address _proxy = delegates(_user);
-    _applyDeltaToCheckpoint(balanceCheckpoints[_proxy], _delta);
+    _applyDeltaToCheckpoint(voteWeightCheckpoints[_proxy], _delta);
   }
 
   // @dev Moves delegated votes from one delegate to another.
@@ -62,12 +62,12 @@ abstract contract FlexVotingDelegatable is Context, FlexVotingClient {
 
     // Decrement old delegate's weight.
     (uint208 _oldFrom, uint208 _newFrom) =
-      _applyDeltaToCheckpoint(balanceCheckpoints[from], -_delta);
+      _applyDeltaToCheckpoint(voteWeightCheckpoints[from], -_delta);
     emit DelegateWeightChanged(from, _oldFrom, _newFrom);
 
     // Increment new delegate's weight.
     (uint208 _oldTo, uint208 _newTo) =
-      _applyDeltaToCheckpoint(balanceCheckpoints[to], _delta);
+      _applyDeltaToCheckpoint(voteWeightCheckpoints[to], _delta);
     emit DelegateWeightChanged(to, _oldTo, _newTo);
   }
 }

test/FlexVotingClient.invariants.t.sol

@@ -107,17 +107,17 @@ contract FlexVotingInvariantTest is FlexVotingInvariantSetup {
     uint256 _checkpoint = block.number;
     vm.roll(_checkpoint + 1);
     assertEq(
-      flexClient.getPastTotalBalance(_checkpoint),
+      flexClient.getPastTotalVoteWeight(_checkpoint),
       handler.ghost_depositSum() - handler.ghost_withdrawSum()
     );
 
     uint256 _sum;
     address[] memory _depositors = handler.getActors();
     for (uint256 d; d < _depositors.length; d++) {
       address _depositor = _depositors[d];
-      _sum += flexClient.getPastRawBalance(_depositor, _checkpoint);
+      _sum += flexClient.getPastVoteWeight(_depositor, _checkpoint);
     }
-    assertEq(flexClient.getPastTotalBalance(_checkpoint), _sum);
+    assertEq(flexClient.getPastTotalVoteWeight(_checkpoint), _sum);
   }
 
   function invariant_SumOfDepositsIsGTEProposalVotes() public view {

test/FlexVotingClient.t.sol

@@ -8,8 +8,8 @@ import {
   _RawBalanceOf,
   _CastVoteReasonString,
   _SelfDelegate,
-  _CheckpointRawBalanceOf,
-  _CheckpointTotalBalance,
+  _CheckpointVoteWeightOf,
+  _CheckpointTotalVoteWeight,
   GetPastRawBalance,
   GetPastTotalBalance,
   Withdraw,
@@ -70,7 +70,7 @@ contract BlockNumberClock__SelfDelegate is _SelfDelegate {
   }
 }
 
-contract BlockNumberClock__CheckpointRawBalanceOf is _CheckpointRawBalanceOf {
+contract BlockNumberClock__CheckpointVoteWeightOf is _CheckpointVoteWeightOf {
   function _timestampClock() internal pure override returns (bool) {
     return false;
   }
@@ -90,7 +90,7 @@ contract BlockNumberClock_GetPastRawBalance is GetPastRawBalance {
   }
 }
 
-contract BlockNumber__CheckpointTotalBalance is _CheckpointTotalBalance {
+contract BlockNumber__CheckpointTotalVoteWeight is _CheckpointTotalVoteWeight {
   function _timestampClock() internal pure override returns (bool) {
     return false;
   }
@@ -211,7 +211,7 @@ contract TimestampClock__SelfDelegate is _SelfDelegate {
   }
 }
 
-contract TimestampClock__CheckpointRawBalanceOf is _CheckpointRawBalanceOf {
+contract TimestampClock__CheckpointVoteWeightOf is _CheckpointVoteWeightOf {
   function _timestampClock() internal pure override returns (bool) {
     return true;
   }
@@ -231,7 +231,7 @@ contract TimestampClock_GetPastRawBalance is GetPastRawBalance {
   }
 }
 
-contract TimestampClock__CheckpointTotalBalance is _CheckpointTotalBalance {
+contract TimestampClock__CheckpointTotalVoteWeight is _CheckpointTotalVoteWeight {
   function _timestampClock() internal pure override returns (bool) {
     return true;
   }

test/FlexVotingDelegatable.t.sol

@@ -16,8 +16,8 @@ import {
   _RawBalanceOf,
   _CastVoteReasonString,
   _SelfDelegate,
-  _CheckpointRawBalanceOf,
-  _CheckpointTotalBalance,
+  _CheckpointVoteWeightOf,
+  _CheckpointTotalVoteWeight,
   GetPastRawBalance,
   GetPastTotalBalance,
   Withdraw,
@@ -88,8 +88,8 @@ abstract contract Delegation is FlexVotingClientTest {
     _mintGovAndDepositIntoFlexClient(_delegate, _delegateWeight);
 
     _advanceTimeBy(1); // Make past balances retrievable.
-    assertEq(client().getPastRawBalance(_delegate, _now() - 1), _delegateWeight);
-    assertEq(client().getPastRawBalance(_delegator, _now() - 1), _delegatorWeight);
+    assertEq(client().getPastVoteWeight(_delegate, _now() - 1), _delegateWeight);
+    assertEq(client().getPastVoteWeight(_delegator, _now() - 1), _delegatorWeight);
 
     // Delegate.
     vm.expectEmit();
@@ -101,8 +101,8 @@ abstract contract Delegation is FlexVotingClientTest {
 
     uint256 _combined = _delegatorWeight + _delegateWeight;
     _advanceTimeBy(1); // Make past balances retrievable.
-    assertEq(client().getPastRawBalance(_delegator, _now() - 1), 0);
-    assertEq(client().getPastRawBalance(_delegate, _now() - 1), _combined);
+    assertEq(client().getPastVoteWeight(_delegator, _now() - 1), 0);
+    assertEq(client().getPastVoteWeight(_delegate, _now() - 1), _combined);
 
     // Create the proposal.
     uint256 _proposalId = _createAndSubmitProposal();
@@ -382,14 +382,14 @@ abstract contract Delegation is FlexVotingClientTest {
 
     // The delegator has no weight to vote with, despite having a deposit balance.
     assertEq(client().deposits(_delegator), _weight);
-    assertEq(client().getPastRawBalance(_delegator, _proposalTimepoint), 0);
+    assertEq(client().getPastVoteWeight(_delegator, _proposalTimepoint), 0);
     vm.expectRevert(FVC.FlexVotingClient__NoVotingWeight.selector);
     vm.prank(_delegator);
     client().expressVote(_proposalId, uint8(_voteType));
 
     // The delegate *has* weight to vote with, despite having no deposit balance.
     assertEq(client().deposits(_delegate), 0);
-    assertEq(client().getPastRawBalance(_delegate, _proposalTimepoint), _weight);
+    assertEq(client().getPastVoteWeight(_delegate, _proposalTimepoint), _weight);
     vm.prank(_delegate);
     client().expressVote(_proposalId, uint8(_voteType));
 
@@ -451,7 +451,7 @@ contract BlockNumber__SelfDelegate is _SelfDelegate {
   }
 }
 
-contract BlockNumber__CheckpointRawBalanceOf is _CheckpointRawBalanceOf {
+contract BlockNumber__CheckpointVoteWeightOf is _CheckpointVoteWeightOf {
   function _timestampClock() internal pure override returns (bool) {
     return false;
   }
@@ -461,7 +461,7 @@ contract BlockNumber__CheckpointRawBalanceOf is _CheckpointRawBalanceOf {
   }
 }
 
-contract BlockNumber__CheckpointTotalBalance is _CheckpointTotalBalance {
+contract BlockNumber__CheckpointTotalVoteWeight is _CheckpointTotalVoteWeight {
   function _timestampClock() internal pure override returns (bool) {
     return false;
   }
@@ -601,7 +601,7 @@ contract TimestampClock__SelfDelegate is _SelfDelegate {
   }
 }
 
-contract TimestampClock__CheckpointRawBalanceOf is _CheckpointRawBalanceOf {
+contract TimestampClock__CheckpointVoteWeightOf is _CheckpointVoteWeightOf {
   function _timestampClock() internal pure override returns (bool) {
     return true;
   }
@@ -611,7 +611,7 @@ contract TimestampClock__CheckpointRawBalanceOf is _CheckpointRawBalanceOf {
   }
 }
 
-contract TimestampClock__CheckpointTotalBalance is _CheckpointTotalBalance {
+contract TimestampClock__CheckpointTotalVoteWeight is _CheckpointTotalVoteWeight {
   function _timestampClock() internal pure override returns (bool) {
     return true;
   }

test/MockFlexVotingClient.sol

@@ -35,12 +35,12 @@ contract MockFlexVotingClient is FlexVotingClient {
     return _rawBalanceOf(_user);
   }
 
-  function exposed_latestTotalBalance() external view returns (uint208) {
-    return totalBalanceCheckpoints.latest();
+  function exposed_latestTotalWeight() external view returns (uint208) {
+    return totalVoteWeightCheckpoints.latest();
   }
 
-  function exposed_checkpointTotalBalance(int256 _delta) external {
-    return _checkpointTotalBalance(_delta);
+  function exposed_checkpointTotalVoteWeight(int256 _delta) external {
+    return _checkpointTotalVoteWeight(_delta);
   }
 
   function exposed_castVoteReasonString() external returns (string memory) {
@@ -55,8 +55,8 @@ contract MockFlexVotingClient is FlexVotingClient {
     deposits[_user] = _amount;
   }
 
-  function exposed_checkpointRawBalanceOf(address _user, int256 _delta) external {
-    _checkpointRawBalanceOf(_user, _delta);
+  function exposed_checkpointVoteWeightOf(address _user, int256 _delta) external {
+    _checkpointVoteWeightOf(_user, _delta);
   }
   // End test hooks
   // ---------------------------------------------------------------------------
@@ -67,8 +67,8 @@ contract MockFlexVotingClient is FlexVotingClient {
     deposits[msg.sender] += _amount;
 
     int256 _delta = int256(uint256(_amount));
-    _checkpointRawBalanceOf(msg.sender, _delta);
-    _checkpointTotalBalance(_delta);
+    _checkpointVoteWeightOf(msg.sender, _delta);
+    _checkpointTotalVoteWeight(_delta);
 
     // Assumes revert on failure.
     TOKEN.transferFrom(msg.sender, address(this), _amount);
@@ -81,8 +81,8 @@ contract MockFlexVotingClient is FlexVotingClient {
     deposits[msg.sender] -= _amount;
 
     int256 _delta = -1 * int256(uint256(_amount));
-    _checkpointRawBalanceOf(msg.sender, _delta);
-    _checkpointTotalBalance(_delta);
+    _checkpointVoteWeightOf(msg.sender, _delta);
+    _checkpointTotalVoteWeight(_delta);
 
     TOKEN.transfer(msg.sender, _amount); // Assumes revert on failure.
   }