crowetic/protocol
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

@0x/contracts-staking: Extract MixinExchangeFees._cobbDouglas() into its own library.

Browse Source
This commit is contained in:
Lawrence Forman 2019-09-20 15:41:06 -04:00
parent 5fe9edce8c
commit 7a33f68138
10 changed files with 167 additions and 128 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
contracts/staking/CHANGELOG.json
View File

@ -53,6 +53,10 @@
{
"note": "Removed MixinStakingPoolRewardVault.sol",
"pr": 2156
},
{
"note": "Refactored out `_cobbDouglas()` into its own library",
"pr": 2179
}
]
}

71
contracts/staking/contracts/src/fees/MixinExchangeFees.sol
View File

@ -23,7 +23,7 @@ import "@0x/contracts-erc20/contracts/src/interfaces/IEtherToken.sol";
import "@0x/contracts-utils/contracts/src/LibRichErrors.sol";
import "@0x/contracts-utils/contracts/src/LibSafeMath.sol";
import "../libs/LibStakingRichErrors.sol";
import "../libs/LibFixedMath.sol";
import "../libs/LibCobbDouglas.sol";
import "../immutable/MixinDeploymentConstants.sol";
import "../interfaces/IStructs.sol";
import "../staking_pools/MixinStakingPool.sol";
@ -153,7 +153,7 @@ contract MixinExchangeFees is
}
/// @dev Pays rewards to market making pools that were active this epoch.
/// Each pool receives a portion of the fees generated this epoch (see _cobbDouglas) that is
/// Each pool receives a portion of the fees generated this epoch (see LibCobbDouglas) that is
/// proportional to (i) the fee volume attributed to their pool over the epoch, and
/// (ii) the amount of stake provided by the maker and their delegators. Rebates are paid
/// into the Reward Vault where they can be withdraw by makers and
@ -245,7 +245,7 @@ contract MixinExchangeFees is
// step 3/4 - record reward for each pool
for (uint256 i = 0; i != totalActivePools; i++) {
// compute reward using cobb-douglas formula
uint256 reward = _cobbDouglas(
uint256 reward = LibCobbDouglas.cobbDouglas(
initialContractBalance,
activePools[i].feesCollected,
totalFeesCollected,
@ -290,69 +290,4 @@ contract MixinExchangeFees is
finalContractBalance
);
}
/// @dev The cobb-douglas function used to compute fee-based rewards for staking pools in a given epoch.
/// Note that in this function there is no limitation on alpha; we tend to get better rounding
/// on the simplified versions below.
/// @param totalRewards collected over an epoch.
/// @param ownerFees Fees attributed to the owner of the staking pool.
/// @param totalFees collected across all active staking pools in the epoch.
/// @param ownerStake Stake attributed to the owner of the staking pool.
/// @param totalStake collected across all active staking pools in the epoch.
/// @param alphaNumerator Numerator of `alpha` in the cobb-dougles function.
/// @param alphaDenominator Denominator of `alpha` in the cobb-douglas function.
/// @return ownerRewards Rewards for the owner.
function _cobbDouglas(
uint256 totalRewards,
uint256 ownerFees,
uint256 totalFees,
uint256 ownerStake,
uint256 totalStake,
uint256 alphaNumerator,
uint256 alphaDenominator
)
internal
pure
returns (uint256 ownerRewards)
{
int256 feeRatio = LibFixedMath._toFixed(ownerFees, totalFees);
int256 stakeRatio = LibFixedMath._toFixed(ownerStake, totalStake);
if (feeRatio == 0 || stakeRatio == 0) {
return ownerRewards = 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^(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
n = feeRatio <= stakeRatio ?
LibFixedMath._mul(stakeRatio, n) :
LibFixedMath._div(stakeRatio, n);
// Multiply the above with totalRewards.
ownerRewards = LibFixedMath._uintMul(n, totalRewards);
}
}

98
contracts/staking/contracts/src/libs/LibCobbDouglas.sol Normal file
View File

@ -0,0 +1,98 @@
/*
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.5.9;
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 active staking pools in
/// the epoch.
/// @param stake Stake attributed to the staking pool.
/// @param totalStake Total stake across all active staking pools in the
/// epoch.
/// @param alphaNumerator Numerator of `alpha` in the cobb-douglas function.
/// @param alphaDenominator Denominator of `alpha` in the cobb-douglas
/// function.
/// @return ownerRewards Rewards owned to the staking pool.
function cobbDouglas(
uint256 totalRewards,
uint256 fees,
uint256 totalFees,
uint256 stake,
uint256 totalStake,
uint32 alphaNumerator,
uint32 alphaDenominator
)
internal
pure
returns (uint256 ownerRewards)
{
int256 feeRatio = LibFixedMath.toFixed(fees, totalFees);
int256 stakeRatio = LibFixedMath.toFixed(stake, totalStake);
if (feeRatio == 0 || stakeRatio == 0) {
return ownerRewards = 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^(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.
ownerRewards = LibFixedMath.uintMul(n, totalRewards);
}
}

60
contracts/staking/contracts/src/libs/LibFixedMath.sol
View File

@ -39,46 +39,46 @@ library LibFixedMath {
int256 private constant EXP_MIN_VAL = -int256(0x0000000000000000000000000000001ff0000000000000000000000000000000);
/// @dev Get one as a fixed-point number.
function _one() internal pure returns (int256 f) {
function one() internal pure returns (int256 f) {
f = FIXED_1;
}
/// @dev Returns the addition of two fixed point numbers, reverting on overflow.
function _add(int256 a, int256 b) internal pure returns (int256 c) {
c = __add(a, b);
function add(int256 a, int256 b) internal pure returns (int256 c) {
c = _add(a, b);
}
/// @dev Returns the addition of two fixed point numbers, reverting on overflow.
function _sub(int256 a, int256 b) internal pure returns (int256 c) {
c = __add(a, -b);
function sub(int256 a, int256 b) internal pure returns (int256 c) {
c = _add(a, -b);
}
/// @dev Returns the multiplication of two fixed point numbers, reverting on overflow.
function _mul(int256 a, int256 b) internal pure returns (int256 c) {
c = __mul(a, b) / FIXED_1;
function mul(int256 a, int256 b) internal pure returns (int256 c) {
c = _mul(a, b) / FIXED_1;
}
/// @dev Returns the division of two fixed point numbers.
function _div(int256 a, int256 b) internal pure returns (int256 c) {
c = __div(__mul(a, FIXED_1), b);
function div(int256 a, int256 b) internal pure returns (int256 c) {
c = _div(_mul(a, FIXED_1), b);
}
/// @dev Performs (a * n) / d, without scaling for precision.
function _mulDiv(int256 a, int256 n, int256 d) internal pure returns (int256 c) {
c = __div(__mul(a, n), d);
function mulDiv(int256 a, int256 n, int256 d) internal pure returns (int256 c) {
c = _div(_mul(a, n), d);
}
/// @dev Returns the unsigned integer result of multiplying a fixed-point
/// number with an integer, reverting if the multiplication overflows.
/// Negative results are clamped to zero.
function _uintMul(int256 f, uint256 u) internal pure returns (uint256) {
function uintMul(int256 f, uint256 u) internal pure returns (uint256) {
if (int256(u) < int256(0)) {
LibRichErrors.rrevert(LibFixedMathRichErrors.UnsignedValueError(
LibFixedMathRichErrors.ValueErrorCodes.TOO_LARGE,
u
));
}
int256 c = __mul(f, int256(u));
int256 c = _mul(f, int256(u));
if (c <= 0) {
return 0;
}
@ -86,7 +86,7 @@ library LibFixedMath {
}
/// @dev Returns the absolute value of a fixed point number.
function _abs(int256 f) internal pure returns (int256 c) {
function abs(int256 f) internal pure returns (int256 c) {
if (f >= 0) {
c = f;
} else {
@ -95,35 +95,35 @@ library LibFixedMath {
}
/// @dev Returns 1 / `x`, where `x` is a fixed-point number.
function _invert(int256 f) internal pure returns (int256 c) {
c = __div(FIXED_1_SQUARED, f);
function invert(int256 f) internal pure returns (int256 c) {
c = _div(FIXED_1_SQUARED, f);
}
/// @dev Convert signed `n` / 1 to a fixed-point number.
function _toFixed(int256 n) internal pure returns (int256 f) {
f = __mul(n, FIXED_1);
function toFixed(int256 n) internal pure returns (int256 f) {
f = _mul(n, FIXED_1);
}
/// @dev Convert signed `n` / `d` to a fixed-point number.
function _toFixed(int256 n, int256 d) internal pure returns (int256 f) {
f = __div(__mul(n, FIXED_1), d);
function toFixed(int256 n, int256 d) internal pure returns (int256 f) {
f = _div(_mul(n, FIXED_1), d);
}
/// @dev Convert unsigned `n` / 1 to a fixed-point number.
/// Reverts if `n` is too large to fit in a fixed-point number.
function _toFixed(uint256 n) internal pure returns (int256 f) {
function toFixed(uint256 n) internal pure returns (int256 f) {
if (int256(n) < int256(0)) {
LibRichErrors.rrevert(LibFixedMathRichErrors.UnsignedValueError(
LibFixedMathRichErrors.ValueErrorCodes.TOO_LARGE,
n
));
}
f = __mul(int256(n), FIXED_1);
f = _mul(int256(n), FIXED_1);
}
/// @dev Convert unsigned `n` / `d` to a fixed-point number.
/// Reverts if `n` / `d` is too large to fit in a fixed-point number.
function _toFixed(uint256 n, uint256 d) internal pure returns (int256 f) {
function toFixed(uint256 n, uint256 d) internal pure returns (int256 f) {
if (int256(n) < int256(0)) {
LibRichErrors.rrevert(LibFixedMathRichErrors.UnsignedValueError(
LibFixedMathRichErrors.ValueErrorCodes.TOO_LARGE,
@ -136,16 +136,16 @@ library LibFixedMath {
d
));
}
f = __div(__mul(int256(n), FIXED_1), int256(d));
f = _div(_mul(int256(n), FIXED_1), int256(d));
}
/// @dev Convert a fixed-point number to an integer.
function _toInteger(int256 f) internal pure returns (int256 n) {
function toInteger(int256 f) internal pure returns (int256 n) {
return f / FIXED_1;
}
/// @dev Get the natural logarithm of a fixed-point number 0 < `x` <= LN_MAX_VAL
function _ln(int256 x) internal pure returns (int256 r) {
function ln(int256 x) internal pure returns (int256 r) {
if (x > LN_MAX_VAL) {
LibRichErrors.rrevert(LibFixedMathRichErrors.SignedValueError(
LibFixedMathRichErrors.ValueErrorCodes.TOO_LARGE,
@ -233,7 +233,7 @@ library LibFixedMath {
}
/// @dev Compute the natural exponent for a fixed-point number EXP_MIN_VAL <= `x` <= 1
function _exp(int256 x) internal pure returns (int256 r) {
function exp(int256 x) internal pure returns (int256 r) {
if (x < EXP_MIN_VAL) {
// Saturate to zero below EXP_MIN_VAL.
return 0;
@ -330,7 +330,7 @@ library LibFixedMath {
}
/// @dev Returns the multiplication two numbers, reverting on overflow.
function __mul(int256 a, int256 b) private pure returns (int256 c) {
function _mul(int256 a, int256 b) private pure returns (int256 c) {
if (a == 0) {
return 0;
}
@ -345,7 +345,7 @@ library LibFixedMath {
}
/// @dev Returns the division of two numbers, reverting on division by zero.
function __div(int256 a, int256 b) private pure returns (int256 c) {
function _div(int256 a, int256 b) private pure returns (int256 c) {
if (b == 0) {
LibRichErrors.rrevert(LibFixedMathRichErrors.BinOpError(
LibFixedMathRichErrors.BinOpErrorCodes.DIVISION_BY_ZERO,
@ -357,7 +357,7 @@ library LibFixedMath {
}
/// @dev Adds two numbers, reverting on overflow.
function __add(int256 a, int256 b) private pure returns (int256 c) {
function _add(int256 a, int256 b) private pure returns (int256 c) {
c = a + b;
if (c > 0 && a < 0 && b < 0) {
LibRichErrors.rrevert(LibFixedMathRichErrors.BinOpError(

22
contracts/staking/contracts/test/TestCobbDouglas.sol
View File

@ -18,31 +18,29 @@
pragma solidity ^0.5.9;
pragma experimental ABIEncoderV2;
import "../src/fees/MixinExchangeFees.sol";
import "../src/libs/LibCobbDouglas.sol";
contract TestCobbDouglas is
MixinExchangeFees
{
contract TestCobbDouglas {
function cobbDouglas(
uint256 totalRewards,
uint256 ownerFees,
uint256 fees,
uint256 totalFees,
uint256 ownerStake,
uint256 stake,
uint256 totalStake,
uint256 alphaNumerator,
uint256 alphaDenominator
uint32 alphaNumerator,
uint32 alphaDenominator
)
external
pure
returns (uint256 ownerRewards)
returns (uint256 rewards)
{
ownerRewards = _cobbDouglas(
rewards = LibCobbDouglas.cobbDouglas(
totalRewards,
ownerFees,
fees,
totalFees,
ownerStake,
stake,
totalStake,
alphaNumerator,
alphaDenominator

34
contracts/staking/contracts/test/TestLibFixedMath.sol
View File

@ -23,66 +23,66 @@ import "../src/libs/LibFixedMath.sol";
contract TestLibFixedMath {
function one() external pure returns (int256) {
return LibFixedMath._one();
return LibFixedMath.one();
}
function mulDiv(int256 a, int256 n, int256 d) external pure returns (int256) {
return LibFixedMath._mulDiv(a, n, d);
return LibFixedMath.mulDiv(a, n, d);
}
function mul(int256 a, int256 b) external pure returns (int256) {
return LibFixedMath._mul(a, b);
return LibFixedMath.mul(a, b);
}
function div(int256 a, int256 b) external pure returns (int256) {
return LibFixedMath._div(a, b);
return LibFixedMath.div(a, b);
}
function add(int256 a, int256 b) external pure returns (int256) {
return LibFixedMath._add(a, b);
return LibFixedMath.add(a, b);
}
function sub(int256 a, int256 b) external pure returns (int256) {
return LibFixedMath._sub(a, b);
return LibFixedMath.sub(a, b);
}
function uintMul(int256 f, uint256 u) external pure returns (uint256) {
return LibFixedMath._uintMul(f, u);
return LibFixedMath.uintMul(f, u);
}
function abs(int256 a) external pure returns (int256) {
return LibFixedMath._abs(a);
return LibFixedMath.abs(a);
}
function invert(int256 a) external pure returns (int256) {
return LibFixedMath._invert(a);
return LibFixedMath.invert(a);
}
function toFixedSigned(int256 n, int256 d) external pure returns (int256) {
return LibFixedMath._toFixed(n, d);
return LibFixedMath.toFixed(n, d);
}
function toFixedSigned(int256 n) external pure returns (int256) {
return LibFixedMath._toFixed(n);
return LibFixedMath.toFixed(n);
}
function toFixedUnsigned(uint256 n, uint256 d) external pure returns (int256) {
return LibFixedMath._toFixed(n, d);
return LibFixedMath.toFixed(n, d);
}
function toFixedUnsigned(uint256 n) external pure returns (int256) {
return LibFixedMath._toFixed(n);
return LibFixedMath.toFixed(n);
}
function toInteger(int256 f) external pure returns (int256) {
return LibFixedMath._toInteger(f);
return LibFixedMath.toInteger(f);
}
function ln(int256 x) external pure returns (int256 r) {
return LibFixedMath._ln(x);
return LibFixedMath.ln(x);
}
function exp(int256 x) external pure returns (int256 r) {
return LibFixedMath._exp(x);
return LibFixedMath.exp(x);
}
}

2
contracts/staking/package.json
View File

@ -37,7 +37,7 @@
},
"config": {
"abis:comment": "This list is auto-generated by contracts-gen. Don't edit manually.",
"abis": "./generated-artifacts/@(EthVault|IEthVault|IStaking|IStakingEvents|IStakingPoolRewardVault|IStakingProxy|IStorage|IStorageInit|IStructs|IVaultCore|IZrxVault|LibFixedMath|LibFixedMathRichErrors|LibProxy|LibSafeDowncast|LibStakingRichErrors|MixinConstants|MixinCumulativeRewards|MixinDeploymentConstants|MixinExchangeFees|MixinExchangeManager|MixinParams|MixinScheduler|MixinStake|MixinStakeBalances|MixinStakeStorage|MixinStakingPool|MixinStakingPoolMakers|MixinStakingPoolModifiers|MixinStakingPoolRewards|MixinStorage|MixinVaultCore|ReadOnlyProxy|Staking|StakingPoolRewardVault|StakingProxy|TestCobbDouglas|TestCumulativeRewardTracking|TestInitTarget|TestLibFixedMath|TestLibProxy|TestLibProxyReceiver|TestLibSafeDowncast|TestProtocolFees|TestProtocolFeesERC20Proxy|TestStaking|TestStakingProxy|TestStorageLayout|ZrxVault).json"
"abis": "./generated-artifacts/@(EthVault|IEthVault|IStaking|IStakingEvents|IStakingPoolRewardVault|IStakingProxy|IStorage|IStorageInit|IStructs|IVaultCore|IZrxVault|LibCobbDouglas|LibFixedMath|LibFixedMathRichErrors|LibProxy|LibSafeDowncast|LibStakingRichErrors|MixinConstants|MixinCumulativeRewards|MixinDeploymentConstants|MixinExchangeFees|MixinExchangeManager|MixinParams|MixinScheduler|MixinStake|MixinStakeBalances|MixinStakeStorage|MixinStakingPool|MixinStakingPoolMakers|MixinStakingPoolModifiers|MixinStakingPoolRewards|MixinStorage|MixinVaultCore|ReadOnlyProxy|Staking|StakingPoolRewardVault|StakingProxy|TestCobbDouglas|TestCumulativeRewardTracking|TestInitTarget|TestLibFixedMath|TestLibProxy|TestLibProxyReceiver|TestLibSafeDowncast|TestProtocolFees|TestProtocolFeesERC20Proxy|TestStaking|TestStakingProxy|TestStorageLayout|ZrxVault).json"
},
"repository": {
"type": "git",

2
contracts/staking/src/artifacts.ts
View File

@ -16,6 +16,7 @@ import * as IStorageInit from '../generated-artifacts/IStorageInit.json';
import * as IStructs from '../generated-artifacts/IStructs.json';
import * as IVaultCore from '../generated-artifacts/IVaultCore.json';
import * as IZrxVault from '../generated-artifacts/IZrxVault.json';
import * as LibCobbDouglas from '../generated-artifacts/LibCobbDouglas.json';
import * as LibFixedMath from '../generated-artifacts/LibFixedMath.json';
import * as LibFixedMathRichErrors from '../generated-artifacts/LibFixedMathRichErrors.json';
import * as LibProxy from '../generated-artifacts/LibProxy.json';
@ -73,6 +74,7 @@ export const artifacts = {
IStructs: IStructs as ContractArtifact,
IVaultCore: IVaultCore as ContractArtifact,
IZrxVault: IZrxVault as ContractArtifact,
LibCobbDouglas: LibCobbDouglas as ContractArtifact,
LibFixedMath: LibFixedMath as ContractArtifact,
LibFixedMathRichErrors: LibFixedMathRichErrors as ContractArtifact,
LibProxy: LibProxy as ContractArtifact,

1
contracts/staking/src/wrappers.ts
View File

@ -14,6 +14,7 @@ export * from '../generated-wrappers/i_storage_init';
export * from '../generated-wrappers/i_structs';
export * from '../generated-wrappers/i_vault_core';
export * from '../generated-wrappers/i_zrx_vault';
export * from '../generated-wrappers/lib_cobb_douglas';
export * from '../generated-wrappers/lib_fixed_math';
export * from '../generated-wrappers/lib_fixed_math_rich_errors';
export * from '../generated-wrappers/lib_proxy';

1
contracts/staking/tsconfig.json
View File

@ -14,6 +14,7 @@
"generated-artifacts/IStructs.json",
"generated-artifacts/IVaultCore.json",
"generated-artifacts/IZrxVault.json",
"generated-artifacts/LibCobbDouglas.json",
"generated-artifacts/LibFixedMath.json",
"generated-artifacts/LibFixedMathRichErrors.json",
"generated-artifacts/LibProxy.json",