rebates: manage outstanding funds + improvements

- Remove ABDK math library and use 0x based implementation (cleaner)
- Expose a parameter setter for the rebate ratio in Staking contract
- Use alpha nominator and denominator in rebate formula
- Track the rebate ratio value in each rebate pool on init to allow for future changes of the parameter

- Ensure that no more funds are claimed than stored
- Track the claimed rewards from the rebate pool to allow managing the remainder
- Burn the remaining funds

- Add configuration test for the rebate ratio
- Add many tests specific to the calculations using a mock contract
    - Test the rebate formula against a Typescript implementation for various alpha and values
    - Test that sum of rebates is not greater that the deposited ones (to catch rounding errors)
    - Test how it behaves with edge values of alpha and fees
- Fix tests in allocation.test.ts

Author: abarmat

.solcover.js

@@ -1,4 +1,4 @@
-const skipFiles = ['abdk-libraries-solidity', 'bancor', 'ens', 'erc1056']
+const skipFiles = ['bancor', 'ens', 'erc1056']
 
 module.exports = {
   providerOptions: {

.soliumignore

@@ -2,7 +2,6 @@ node_modules
 
 contracts/bancor
 contracts/discovery/erc1056
-contracts/staking/libs/abdk-libraries-solidity
 contracts/token/IGraphToken.sol
 contracts/upgrades/GraphProxy.sol
 contracts/rewards/RewardsManager.sol

contracts/staking/IStaking.sol

@@ -67,6 +67,8 @@ interface IStaking {
 
     function setMaxAllocationEpochs(uint32 _maxAllocationEpochs) external;
 
+    function setRebateRatio(uint32 _alphaNumerator, uint32 _alphaDenominator) external;
+
     function setDelegationCapacity(uint32 _delegationCapacity) external;
 
     function setDelegationParameters(

contracts/staking/Staking.sol

@@ -171,7 +171,7 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking {
      * @dev Check if the caller is the slasher.
      */
     modifier onlySlasher {
-        require(slashers[msg.sender] == true, "Caller is not a Slasher");
+        require(slashers[msg.sender] == true, "!slasher");
         _;
     }
 
@@ -194,6 +194,10 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking {
      */
     function initialize(address _controller) external onlyImpl {
         Managed._initialize(_controller);
+
+        // By default 100% rebate ratio to fees
+        alphaNumerator = 1;
+        alphaDenominator = 1;
     }
 
     /**
@@ -258,6 +262,22 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking {
         emit ParameterUpdated("maxAllocationEpochs");
     }
 
+    /**
+     * @dev Set the rebate ratio (fees to allocated stake).
+     * @param _alphaNumerator Numerator of `alpha` in the cobb-douglas function
+     * @param _alphaDenominator Denominator of `alpha` in the cobb-douglas function
+     */
+    function setRebateRatio(uint32 _alphaNumerator, uint32 _alphaDenominator)
+        external
+        override
+        onlyGovernor
+    {
+        require(_alphaNumerator > 0 && _alphaDenominator > 0, "=zero");
+        alphaNumerator = _alphaNumerator;
+        alphaDenominator = _alphaDenominator;
+        emit ParameterUpdated("rebateRatio");
+    }
+
     /**
      * @dev Set the delegation capacity multiplier.
      * @param _delegationCapacity Delegation capacity multiplier
@@ -565,7 +585,7 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking {
 
         // Cannot slash stake of an indexer without any or enough stake
         require(indexerStake.hasTokens(), "Indexer has no stakes");
-        require(_tokens <= indexerStake.tokensStaked, "cannot slash more than staked amount");
+        require(_tokens <= indexerStake.tokensStaked, "Cannot slash more than staked amount");
 
         // Validate beneficiary of slashed tokens
         require(_beneficiary != address(0), "Beneficiary must not be an empty address");
@@ -583,11 +603,10 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking {
         // Remove tokens to slash from the stake
         indexerStake.release(_tokens);
 
+        // -- Effects --
+
         // Set apart the reward for the beneficiary and burn remaining slashed stake
-        uint256 tokensToBurn = _tokens.sub(_reward);
-        if (tokensToBurn > 0) {
-            graphToken().burn(tokensToBurn);
-        }
+        _burnTokens(_tokens.sub(_reward));
 
         // Give the beneficiary a reward for slashing
         if (_reward > 0) {
@@ -759,7 +778,7 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking {
     }
 
     /**
-     * @dev Collect query fees for an allocation.
+     * @dev Collect query fees for an allocation from state channels.
      * Funds received are only accepted from a valid source.
      * @param _tokens Amount of tokens to collect
      */
@@ -795,23 +814,16 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking {
         AllocationState allocState = _getAllocationState(_allocationID);
 
         // Validate ownership
-        require(_onlyAuthOrDelegator(alloc.indexer), "Caller must be authorized");
+        require(_onlyAuthOrDelegator(alloc.indexer), "!auth");
 
         // TODO: restake when delegator called should not be allowed?
 
         // Funds can only be claimed after a period of time passed since allocation was closed
         require(allocState == AllocationState.Finalized, "Allocation must be in finalized state");
 
-        // Find a rebate pool for the epoch
-        Rebates.Pool storage pool = rebates[alloc.closedAtEpoch];
-
-        // Process rebate
-        uint256 tokensToClaim = pool.redeem(alloc.collectedFees, alloc.effectiveAllocation);
-
-        // When all allocations processed then prune rebate pool
-        if (pool.unclaimedAllocationsCount == 0) {
-            delete rebates[alloc.closedAtEpoch];
-        }
+        // Process rebate reward
+        Rebates.Pool storage rebatePool = rebates[alloc.closedAtEpoch];
+        uint256 tokensToClaim = rebatePool.redeem(alloc.collectedFees, alloc.effectiveAllocation);
 
         // Calculate delegation rewards and add them to the delegation pool
         uint256 delegationRewards = _collectDelegationQueryRewards(alloc.indexer, tokensToClaim);
@@ -828,6 +840,14 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking {
         alloc.effectiveAllocation = 0;
         alloc.assetHolder = address(0); // This avoid collect() to be called
 
+        // -- Effects --
+
+        // When all allocations processed then burn unclaimed fees and prune rebate pool
+        if (rebatePool.unclaimedAllocationsCount == 0) {
+            _burnTokens(rebatePool.unclaimedFees());
+            delete rebates[closedAtEpoch];
+        }
+
         // When there are tokens to claim from the rebate pool, transfer or restake
         if (tokensToClaim > 0) {
             // Assign claimed tokens
@@ -850,7 +870,7 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking {
             epochManager().currentEpoch(),
             closedAtEpoch,
             tokensToClaim,
-            pool.unclaimedAllocationsCount,
+            rebatePool.unclaimedAllocationsCount,
             delegationRewards
         );
     }
@@ -893,7 +913,7 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking {
         address _assetHolder,
         bytes32 _metadata
     ) internal {
-        require(_onlyAuth(_indexer), "Caller must be authorized");
+        require(_onlyAuth(_indexer), "!auth");
 
         Stakes.Indexer storage indexerStake = stakes[_indexer];
 
@@ -982,20 +1002,23 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking {
 
         // Validate ownership
         if (epochs > maxAllocationEpochs) {
-            // Verify that the allocation owner or delegator is settling
-            require(_onlyAuthOrDelegator(alloc.indexer), "Caller must be authorized");
+            // Verify that the allocation owner or delegator is closing
+            require(_onlyAuthOrDelegator(alloc.indexer), "!auth");
         } else {
-            // Verify that the allocation owner is settling
-            require(_onlyAuth(alloc.indexer), "Caller must be authorized");
+            // Verify that the allocation owner is closing
+            require(_onlyAuth(alloc.indexer), "!auth");
         }
 
-        // Close the allocation and start counting a period to finalize any other
-        // withdrawal.
+        // Close the allocation and start counting a period to settle remaining payments from
+        // state channels.
         alloc.closedAtEpoch = currentEpoch;
         alloc.effectiveAllocation = _getEffectiveAllocation(alloc.tokens, epochs);
 
-        // Send funds to rebate pool and account the effective allocation
+        // Account collected fees and effective allocation in rebate pool for the epoch
         Rebates.Pool storage rebatePool = rebates[currentEpoch];
+        if (!rebatePool.exists()) {
+            rebatePool.init(alphaNumerator, alphaDenominator);
+        }
         rebatePool.addToPool(alloc.collectedFees, alloc.effectiveAllocation);
 
         // Distribute rewards if proof of indexing was presented
@@ -1025,17 +1048,17 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking {
     }
 
     /**
-     * @dev Withdraw and collect funds for an allocation.
-     * @param _allocationID Allocation that is receiving collected funds
+     * @dev Collect query fees for an allocation from the state channel.
+     * @param _allocationID Allocation that is receiving query fees
      * @param _from Source of collected funds for the allocation
-     * @param _tokens Amount of tokens to withdraw
+     * @param _tokens Amount of tokens to collect
      */
     function _collect(
         address _allocationID,
         address _from,
         uint256 _tokens
     ) internal {
-        uint256 rebateFees = _tokens;
+        uint256 queryFees = _tokens;
 
         // Get allocation
         Allocation storage alloc = allocations[_allocationID];
@@ -1047,26 +1070,29 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking {
             "Allocation must be active or closed"
         );
 
-        // Collect protocol fees to be burned
-        uint256 protocolFees = _collectProtocolFees(rebateFees);
-        rebateFees = rebateFees.sub(protocolFees);
+        // Calculate protocol fees to be burned
+        uint256 protocolFees = _collectProtocolFees(queryFees);
+        queryFees = queryFees.sub(protocolFees);
 
-        // Calculate curation fees only if the subgraph deployment is curated
-        uint256 curationFees = _collectCurationFees(alloc.subgraphDeploymentID, rebateFees);
-        rebateFees = rebateFees.sub(curationFees);
+        // Calculate curation fees (only if the subgraph deployment is curated)
+        uint256 curationFees = _collectCurationFees(alloc.subgraphDeploymentID, queryFees);
+        queryFees = queryFees.sub(curationFees);
 
-        // Collect funds for the allocation
-        alloc.collectedFees = alloc.collectedFees.add(rebateFees);
+        // Collect funds on the allocation
+        alloc.collectedFees = alloc.collectedFees.add(queryFees);
 
         // When allocation is closed redirect funds to the rebate pool
         // This way we can keep collecting tokens even after the allocation is closed and
         // before it gets to the finalized state.
         if (allocState == AllocationState.Closed) {
             Rebates.Pool storage rebatePool = rebates[alloc.closedAtEpoch];
-            rebatePool.fees = rebatePool.fees.add(rebateFees);
+            rebatePool.fees = rebatePool.fees.add(queryFees);
         }
 
-        // TODO: for consistency we could burn protocol fees here
+        // -- Effects --
+
+        // Burn protocol fees
+        _burnTokens(protocolFees);
 
         // Send curation fees to the curator reserve pool
         if (curationFees > 0) {
@@ -1085,7 +1111,7 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking {
             _allocationID,
             _from,
             curationFees,
-            rebateFees
+            queryFees
         );
     }
 
@@ -1240,11 +1266,7 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking {
         if (protocolPercentage == 0) {
             return 0;
         }
-        uint256 protocolFees = uint256(protocolPercentage).mul(_tokens).div(MAX_PPM);
-        if (protocolFees > 0) {
-            graphToken().burn(protocolFees);
-        }
-        return protocolFees;
+        return uint256(protocolPercentage).mul(_tokens).div(MAX_PPM);
     }
 
     /**
@@ -1362,4 +1384,14 @@ contract Staking is StakingV1Storage, GraphUpgradeable, IStaking {
 
         return totalRewards;
     }
+
+    /**
+     * @dev Burn tokens held by this contract.
+     * @param _amount Amount of tokens to burn
+     */
+    function _burnTokens(uint256 _amount) internal {
+        if (_amount > 0) {
+            graphToken().burn(_amount);
+        }
+    }
 }

contracts/staking/StakingStorage.sol

@@ -20,12 +20,16 @@ contract StakingV1Storage is Managed {
     // Parts per million. (Allows for 4 decimal points, 999,999 = 99.9999%)
     uint32 public protocolPercentage;
 
-    // Need to pass this period for channel to be finalized
+    // Period for allocation to be finalized
     uint32 public channelDisputeEpochs;
 
     // Maximum allocation time
     uint32 public maxAllocationEpochs;
 
+    // Rebate ratio
+    uint32 public alphaNumerator;
+    uint32 public alphaDenominator;
+
     // Indexer stakes : indexer => Stake
     mapping(address => Stakes.Indexer) public stakes;
 

contracts/staking/libs/Cobbs.sol

@@ -0,0 +1,90 @@
+/*
+
+  Copyright 2019 ZeroEx Intl.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+
+*/
+
+pragma solidity ^0.6.12;
+pragma experimental ABIEncoderV2;
+
+import "./LibFixedMath.sol";
+
+library LibCobbDouglas {
+    /// @dev The cobb-douglas function used to compute fee-based rewards for
+    ///      staking pools in a given epoch. This function does not perform
+    ///      bounds checking on the inputs, but the following conditions
+    ///      need to be true:
+    ///         0 <= fees / totalFees <= 1
+    ///         0 <= stake / totalStake <= 1
+    ///         0 <= alphaNumerator / alphaDenominator <= 1
+    /// @param totalRewards collected over an epoch.
+    /// @param fees Fees attributed to the the staking pool.
+    /// @param totalFees Total fees collected across all pools that earned rewards.
+    /// @param stake Stake attributed to the staking pool.
+    /// @param totalStake Total stake across all pools that earned rewards.
+    /// @param alphaNumerator Numerator of `alpha` in the cobb-douglas function.
+    /// @param alphaDenominator Denominator of `alpha` in the cobb-douglas
+    ///        function.
+    /// @return rewards Rewards owed to the staking pool.
+    function cobbDouglas(
+        uint256 totalRewards,
+        uint256 fees,
+        uint256 totalFees,
+        uint256 stake,
+        uint256 totalStake,
+        uint32 alphaNumerator,
+        uint32 alphaDenominator
+    ) internal pure returns (uint256 rewards) {
+        int256 feeRatio = LibFixedMath.toFixed(fees, totalFees);
+        int256 stakeRatio = LibFixedMath.toFixed(stake, totalStake);
+        if (feeRatio == 0 || stakeRatio == 0) {
+            return rewards = 0;
+        }
+        // The cobb-doublas function has the form:
+        // `totalRewards * feeRatio ^ alpha * stakeRatio ^ (1-alpha)`
+        // This is equivalent to:
+        // `totalRewards * stakeRatio * e^(alpha * (ln(feeRatio / stakeRatio)))`
+        // However, because `ln(x)` has the domain of `0 < x < 1`
+        // and `exp(x)` has the domain of `x < 0`,
+        // and fixed-point math easily overflows with multiplication,
+        // we will choose the following if `stakeRatio > feeRatio`:
+        // `totalRewards * stakeRatio / e^(alpha * (ln(stakeRatio / feeRatio)))`
+
+        // Compute
+        // `e^(alpha * ln(feeRatio/stakeRatio))` if feeRatio <= stakeRatio
+        // or
+        // `e^(alpa * ln(stakeRatio/feeRatio))` if feeRatio > stakeRatio
+        int256 n = feeRatio <= stakeRatio
+            ? LibFixedMath.div(feeRatio, stakeRatio)
+            : LibFixedMath.div(stakeRatio, feeRatio);
+        n = LibFixedMath.exp(
+            LibFixedMath.mulDiv(
+                LibFixedMath.ln(n),
+                int256(alphaNumerator),
+                int256(alphaDenominator)
+            )
+        );
+        // Compute
+        // `totalRewards * n` if feeRatio <= stakeRatio
+        // or
+        // `totalRewards / n` if stakeRatio > feeRatio
+        // depending on the choice we made earlier.
+        n = feeRatio <= stakeRatio
+            ? LibFixedMath.mul(stakeRatio, n)
+            : LibFixedMath.div(stakeRatio, n);
+        // Multiply the above with totalRewards.
+        rewards = LibFixedMath.uintMul(n, totalRewards);
+    }
+}