[WIP] First Implementation of Staking Contracts (ZEIP 31) #1910

hysz · 2019-06-29T00:58:39Z

Description

This PR includes the first implementation of ZEIP-31 - Stake-based Liquidity Incentives.

Functionality:

Stake your ZRX tokens to unlock their utility within the 0x ecosystem.
- Earn rebates on market making on the 0x protocol
- Participate in governance over the 0x protocol
Create staking pools to leverage the weight of other stakers.
- Increase your market making rebates.
- Increase your voting power.
Delegate your Zrx to staking pools to
- Earn a portion of the pool's market making rebates.
- Support a pool's mission sharing your voting power.

Next Steps:

Add more extensive testing (presently includes basic end-to-end testing)
Optimize Staking contract Nth Root Algorithm / Cobb Douglas
Implement rich revert reasons throughout the contracts
Integrate with 0x Exchange V3 contracts
Test Nets / Audits / Bounties

Notes:
We've iterated on the design many times over the past several months, and this is the first end-to-end implementation. The core protocol team will continue iterating on this, and any feedback/ideas/concerns are welcome.

Architecture

This system is composed of four deployed contracts:

Staking Contract, which is an upgradeable/stateless contract that implements staking logic.
Staking Contract Proxy, which stores staking state and delegates to the Staking Contract.
Zrx Vault, which securely holds staked Zrx Tokens.
Staking Pool Reward Vault, which securely holds rewards earned by staking pools.

These contracts connect to each other and the broader 0x ecosystem like this:

Architecture (Kill Switch)

If a vulnerability is discovered in the staking contract, operations may be halted to conduct forensics:

The 0x Exchange contract stops charging protocol fees
The staking contract is set to read-only mode
Vaults may be detached from the staking contract, depending on the vulnerability.

Architecture (Catastrophic Failures)

In this worst-case scenario, state has been irreperably corrupted and the staking contracts must be re-deployed. Users withdraw their funds from the vaults and re-stake under the new system, at will.

Vaults enter "Catostrophic Failure Mode" allowing users to withdraw their ZRX and Rewards.
A Balance Oracle is deployed for determining the Reward balance of each user. (*)

(*) A Balance Oracle is implemented retroactively, and depends on how state has been corrupted. For example, if state used to compute rewards is not corrupted, then it would be used by the oracle. Conversely, if this state is corrupted, we may need to reconstruct balances from previous state. (No balance oracle is required for ZRX.)

Contracts Directory Structure

The contracts can be found in contracts/src.

* Staking.sol        | This is a stateless contract that encapsulates all the staking logic.
* StakingProxy.sol   | This is a stateful contract that proxies into the Staking contract.
* fees/              | This contains mixins that implement the logic for 0x Protocol fees & rebates.
* immutable/         | This contains mixins that should not be changed.
* interfaces/        | This contains interfaces used throughout the entire staking system.
* libs/              | This contains libraries used by the staking contract; for example, math and signature validation.
* stake/             | This contains mixins that implement the core staking logic.
* staking_pools/     | This contains mixins that implement logic for creating and managing staking pools.
* sys/               | This contains mixins that implement low-level functionality, like scheduling.
* vaults/            | This contains the vaults (like the Zrx Token Vault).

Testing Architecture

These contracts use an actor/simulation pattern. A simulation runs with a specified set of actors, initial state and expected output. Actors have a specific role and validate each call they make to the staking system; for example, there is a Staking Actor who stakes/unstakes their Zrx tokens and validates balances/events. Similarly, there could exist an actor who tries to steal funds.

coveralls · 2019-06-29T01:57:12Z

Coverage remained the same at 75.804% when pulling c0acc8d on feature/contracts-staking/first-implementation into 7407890 on 3.0.

abandeali1

I did a first pass on this, lots to discuss! I did not review any of the math and will need to give this a second pass for some of the more complex areas.

abandeali1 · 2019-06-29T21:46:37Z

contracts/coordinator/contracts/src/libs/LibEIP712CoordinatorDomain.sol

@@ -21,8 +21,7 @@ pragma solidity ^0.5.9;
 import "@0x/contracts-utils/contracts/src/LibEIP712.sol";


-contract LibEIP712CoordinatorDomain is
-    LibEIP712
+contract LibEIP712CoordinatorDomain


The contract opening { should be on this line.

abandeali1 · 2019-06-29T21:56:07Z

contracts/staking/contracts/src/sys/MixinOwnable.sol

+
+contract MixinOwnable is
+    IStakingEvents,
+    MixinDeploymentConstants,


Why do all of these contracts need to be inherited?

This is to remove ambiguity in the contract linearization. Basically, the rule-of-thumb is to order dependencies from most base-like to most derived. However, this can break when there are multiple levels of inheritance. So, to avoid this problem altogether, the inheritance lists are generated in full. In this case - MixinStorage depends on MixinConstants which depends on MixinDeploymentConstants.

Example of general problem:

Ex: contract A {} contract B {} contract C {} contract D is A, B {} Suppose now that there is a contract E that will inherit from B{} and D{} The following follows "most base-like" to "most-derived": contract E is B, D {} However, it unfolds to: B{}, A{}, B{}, D{}, E{} - which is wrong because B{} appears both before and after A{}. The correct contract inheritance for E{} should be: contract E is A{}, B{}, D{} So, even though contract E{} does not directly depend on A{} - it still must be included in the dependency list Because of this, we include all descendants in the output.

abandeali1 · 2019-06-29T21:58:56Z

contracts/staking/contracts/src/StakingProxy.sol

+        payable
+    {
+        address _stakingContract = stakingContract;
+        if (_stakingContract == NIL_ADDRESS) {


We use NIL_ADDRESS sometimes and address(0) sometimes. Isn't address(0) cheaper?

Ah, yeah I actually intended to replace all instances of address(0)with NIL_ADDRESS. I must've missed this one. I believe the cost is the same now that we're using the constant optimizer.

abandeali1 · 2019-06-29T21:59:19Z

contracts/staking/contracts/src/StakingProxy.sol

+    constructor(address _stakingContract)
+        public
+    {
+        owner = msg.sender;


Shouldn't this be handled by the Ownable constructor?

Mm yeah this actually raises an interesting design decision that I'm curious to get your thoughts on: none of the mixins have constructors because they all share the proxy's state, which is not available during constructing of the staking contract. Their state is instead placed in immutable/MixinStorage.sol and inherited by both the proxy and the staking contract.

Maybe an _init() pattern for mixins is cleaner here.

abandeali1 · 2019-06-29T22:02:45Z

contracts/staking/contracts/src/StakingProxy.sol

+    {
+        address _stakingContract = stakingContract;
+        if (_stakingContract == NIL_ADDRESS) {
+            return;


We should probably revert when the stakingContract is detached, no? Otherwise this contract can just collect Ether without registeing it to a maker.

abandeali1 · 2019-07-01T00:28:21Z

contracts/staking/contracts/src/vaults/StakingPoolRewardVault.sol

+    /// @param amount Amount in ETH to record.
+    function withdrawForMember(bytes32 poolId, uint256 amount)
+        external
+        onlyStakingContract


Missing a modifier here as well.

(see note above)

abandeali1 · 2019-07-01T00:31:52Z

contracts/staking/contracts/src/vaults/StakingPoolRewardVault.sol

+    {
+        // operator share must be a valid percentage
+        require(
+            poolOperatorShare <= 100,


I think this denominator is reused elsewhere and should probably be made a constant. Note that we can easily increase the precision here as well.

Note: we discussed offline and have a task for this.

abandeali1 · 2019-07-01T01:10:21Z

contracts/staking/contracts/src/stake/MixinDelegatedStake.sol

+    /// @param owner of Stake
+    /// @param poolId Unique Id of staking pool to delegate stake to.
+    /// @param amount of Stake to delegate.
+    function _delegateStake(


This delegation begins during the current epoch, right? If so, the stake needs to be somehow time-weighted to prevent users from delegating near the end of an epoch with reduced risk.

Note: we discussed offline and have a task for this.

abandeali1 · 2019-07-01T01:12:01Z

contracts/staking/contracts/src/libs/LibRewardMath.sol

+        return (payoutInRealAsset, payoutInShadowAsset);
+    }
+
+    /// @dev Computes how much shadow asset to mint a member who wants to 


Can we better define "shadow asset" here?

abandeali1 · 2019-07-01T01:16:48Z

contracts/staking/contracts/src/fees/MixinExchangeFees.sol

+    /// @return totalRewardsPaid Total rewards paid out across all active pools.
+    /// @return initialContractBalance Balance of this contract before paying rewards.
+    /// @return finalContractBalance Balance of this contract after paying rewards.
+    function _distributeFeesAmongMakerPools()


We should add a TODO that this function needs a way to be executed among multiple blocks (or reduced to ~O(1) complexity). This will be a hard requirement, but can be done in another PR.

dorothy-zbornak

Seems like you put a lot of thought into this! 👍
Got halfway through. Need to do another pass.

dorothy-zbornak · 2019-07-03T22:34:25Z

contracts/staking/contracts/src/Staking.sol

+    // solhint-disable no-empty-blocks
+    function ()
+        external
+        payable


Why is the fallback payable? Why even define a fallback? I get why a payable fallback is in the StakingProxy contract, but not here. Is there a need to ever fund either of these contracts via explicit fallback?

This gets called one deposits into the staking proxy. It's more for future proofing, in case we want additional logic for handling deposits.

dorothy-zbornak · 2019-07-03T22:37:33Z

contracts/staking/contracts/src/StakingProxy.sol

+    constructor(address _stakingContract)
+        public
+    {
+        owner = msg.sender;


Maybe an _init() pattern for mixins is cleaner here.

dorothy-zbornak · 2019-07-03T22:46:19Z

contracts/staking/contracts/src/StakingProxy.sol

+
+    /// @dev Detach the current staking contract.
+    /// Note that this is callable only by this contract's owner.
+    function detachStakingContract()


Is there a scenario where we would just leave the Staking contract detached?
My understanding is that in failure mode, we would simply detach the StakingProxy from the Exchange.
During upgrades, wouldn't we want to immediately swap in a new version of the Staking contract, so why not just an atomic replaceStakingContract() function?

Also, should we do something like _stakingContract.init.delegatecall() when it's being attached? Could be a useful migration hook...

Note: we discussed offline and have a task for both atomic migrations and init.

dorothy-zbornak · 2019-07-03T22:49:10Z

contracts/staking/contracts/src/fees/MixinExchangeFees.sol

+    MixinStakeBalances
+{
+
+    /// @dev This mixin contains the logic for 0x protocol fees.


Nit: I think this natspec actually belongs before the contract definition.

dorothy-zbornak · 2019-07-03T23:05:31Z

contracts/staking/contracts/src/fees/MixinExchangeFees.sol

+        uint256 totalRewardsPaid,
+        uint256 initialContractBalance,
+        uint256 finalContractBalance) = _distributeFeesAmongMakerPools();
+        emit RewardsPaid(


Wouldn't it be more useful to emit something like this per active pool? Logs are cheap, finalization is infrequent, and we aren't anticipating a large number of active pools (right?). This makes me wonder if there should be dust thresholds for payouts as well...

Note: we discussed offline and have a task for this.

dorothy-zbornak · 2019-07-04T00:08:57Z

contracts/staking/contracts/src/fees/MixinExchangeFees.sol

+        // step 3/3 send total payout to vault
+        require(
+            totalRewardsPaid <= initialContractBalance,
+            "MISCALCULATED_REWARDS"


Is this a recoverable state?

If this is triggered then we likely have a bug in the code and would have to redeploy the logic contract in order to finalize the epoch. It is possible that the state is not recoverable in which case we could either subsidize the fees from the current epoch or enter catastrophic failure mode.

dorothy-zbornak · 2019-07-04T00:14:59Z

contracts/staking/contracts/src/immutable/MixinConstants.sol

+
+    uint256 constant internal TOKEN_MULTIPLIER = 1000000000000000000; // 10**18
+
+    bytes32 constant internal INITIAL_POOL_ID = 0x0000000000000000000000000000000100000000000000000000000000000000;


I suspect this has something to do with ERC1155/NFT compat...

dorothy-zbornak · 2019-07-04T00:19:39Z

contracts/staking/contracts/src/immutable/MixinDeploymentConstants.sol

+
+    uint256 constant internal REWARD_PAYOUT_DELEGATED_STAKE_PERCENT_VALUE = 90;
+
+    uint256 constant internal CHAIN_ID = 1;


Def needs to be set in a constructor. Maybe all the way down in StakingProxy.

Note: we discussed offline and have a task for this.

dorothy-zbornak · 2019-07-04T00:23:54Z

contracts/staking/contracts/src/immutable/MixinStorage.sol

+
+
+// solhint-disable max-states-count
+contract MixinStorage is


At first I was trying to come up with ways for this to be more natural (each mixin manages their own storage). It's possible, but storage locations would likely be unreliable (breaking upgrades) because we keep reordering things to get around C3 linearization. 😫

Can this contract just inherit Ownable? We probably also want to have tests that ensure storage slots don't get changes in future upgrades. Let's create a task for these 2 things.

dorothy-zbornak · 2019-07-04T00:56:50Z

contracts/staking/contracts/src/interfaces/IStakingPoolRewardVault.sol

+    /// Note that this is only callable by the staking contract, and when
+    /// not in catastrophic failure mode.
+    /// @param poolId Unique Id of pool.
+    function depositFor(bytes32 poolId)


I'm confused about who actually calls this function. I can't find any instance of the staking contract calling it.

It seems we only do a recordDepositFor(), per pool, then bulk transfer to the vault via fallback during finalization.

deposit() also seems unused, as well?

Note: we discussed offline and have a task for this.

dorothy-zbornak · 2019-07-10T02:59:09Z

contracts/staking/contracts/src/vaults/StakingPoolRewardVault.sol

+    /// not in catastrophic failure mode.
+    /// @param poolId Unique Id of pool.
+    /// @param poolOperatorShare Percentage of rewards given to the pool operator.
+    function registerStakingPool(bytes32 poolId, uint8 poolOperatorShare)


I don't like that we duplicate poolOperatorShare state in both this contract and the Staking contract. It creates a kind of coupling between the two contracts where this value must be in sync. It also makes it awkward if we decide to allow operators to change their share percentage or if we want to change how they're computed because this contract is not upgrade-able.

I think we should explore not storing the poolOperatorShare in this contract and instead have the deposit functions accept explicit values for the operatorAmount and membersAmount.

Note: we discussed offline and have a task for this.

…tion when computing rewards.

… the board - esp w simplified impls)

dorothy-zbornak

👀 👍
I think we should change it back to "timelock"

abandeali1

I still have a lot of comments, but I don't think there is anything blocking the initial implementation from being merged. Excited to dig into this more :)

abandeali1 · 2019-08-21T21:37:58Z

contracts/staking/contracts/src/libs/LibEIP712Hash.sol

+    /// @dev Calculated the EIP712 hash of the StakingPool approval mesasage using the domain separator of this contract.
+    /// @param approval StakingPool approval message containing the transaction hash, transaction signature, and expiration of the approval.
+    /// @return EIP712 hash of the StakingPool approval message with the domain separator of this contract.
+    function _hashStakingPoolApprovalMessage(


Can we create a task to remove this if we haven't already?

+1 there is a task & it's part of this sprint. Will be addressed shortly after merge.

abandeali1 · 2019-08-21T21:39:17Z

contracts/staking/contracts/src/immutable/MixinStorage.sol

+
+
+// solhint-disable max-states-count
+contract MixinStorage is


Can this contract just inherit Ownable? We probably also want to have tests that ensure storage slots don't get changes in future upgrades. Let's create a task for these 2 things.

hysz requested review from abandeali1 and fabioberger as code owners June 29, 2019 00:58

abandeali1 suggested changes Jul 1, 2019

View reviewed changes

dorothy-zbornak reviewed Jul 4, 2019

View reviewed changes

dorothy-zbornak reviewed Jul 10, 2019

View reviewed changes

abandeali1 force-pushed the 3.0 branch from 31324eb to 90d1dec Compare July 24, 2019 18:54

hysz requested review from feuGeneA and xianny as code owners August 1, 2019 18:51

hysz force-pushed the feature/contracts-staking/first-implementation branch 3 times, most recently from fad99eb to d800f14 Compare August 21, 2019 00:33

hysz added 18 commits August 21, 2019 13:04

Implemented staking logic and ZRX vault

3517dd2

Writing staking tests

c062458

compiles and deploys

7fe8eac

staking looks good, aside from the xfer of zrx

13d2cca

staking end-to-end works

c4ca72c

unstaking works

93b5744

hooked up interface to MixinStake

9787cf8

Function to compute nth root

95b284d

Run Newtons nth root algorithm after approximating the root

43173c1

fixed point nth root. This is what well use for the cobb-douglas func…

3c4cfe8

…tion when computing rewards.

decent cobb douglas implementation

19f6a8d

working on it

e2a76c6

works for square roots

64e42d1

Much simplified cobb douglas implementation

f15693a

cobb douglas / simplified / inverse simplified (better results across…

bcfabf1

… the board - esp w simplified impls)

some refactoring for the staking proxy. Compiles, but no tests yet.

36cf4ad

adding events for staking

c6192ea

Split Storage Logic + Staking Logic Contracts

6a902ef

hysz and others added 22 commits August 21, 2019 13:04

Documentation for MixinVaultCore

ee96926

Removed unnecessary lib

508e927

Updated Epoch API for readability + documented Timelock Mixin

93506a4

Ran contracts:gen

15c8e06

Added top-level README to the staking package

6da70cf

Documented libraries and removed unnecessary interface, IMixinScheduler

3922d02

Added more documentation to interfaces

6c82ebe

Pinned contracts-multisig dependency on asset-proxy so it will build

9eb676f

ran prettier

cd14d1e

updated architecture descriptions

3279d2a

New architecture images for README

1f334d2

Added contract registry to kill switch diagram

f1b1eb3

Removed the unused LibRewardsTest

de8b032

Got staking contracts working after rebase

a765e47

Linter fixes

5826825

Updates from staking PR review

41b372f

moved natspec to above contract definition

c939fe2

CamelCase for timelocks

d106051

Renamed MixinTimelockedStake.sol -> MixinTimeLockedStake.sol

47e00ff

Solidity 0.5.5 -> 0.5.9

de26925

Fixed linter errors

ba3cd45

Added changelog entries and cleaned up merge

697e5df

hysz force-pushed the feature/contracts-staking/first-implementation branch from 54563cf to 697e5df Compare August 21, 2019 20:05

dorothy-zbornak approved these changes Aug 21, 2019

View reviewed changes

abandeali1 assigned abandeali1 and dorothy-zbornak Aug 21, 2019

abandeali1 approved these changes Aug 21, 2019

View reviewed changes

Fixed sorting in artifact generation

c0acc8d

hysz force-pushed the feature/contracts-staking/first-implementation branch from 43faea5 to c0acc8d Compare August 21, 2019 23:30

hysz merged commit 249948e into 3.0 Aug 21, 2019


		uint256 constant internal TOKEN_MULTIPLIER = 1000000000000000000; // 10**18

		bytes32 constant internal INITIAL_POOL_ID = 0x0000000000000000000000000000000100000000000000000000000000000000;


		uint256 constant internal REWARD_PAYOUT_DELEGATED_STAKE_PERCENT_VALUE = 90;

		uint256 constant internal CHAIN_ID = 1;

[WIP] First Implementation of Staking Contracts (ZEIP 31) #1910

[WIP] First Implementation of Staking Contracts (ZEIP 31) #1910

Conversation

hysz commented Jun 29, 2019 • edited Loading

Description

Architecture

Architecture (Kill Switch)

Architecture (Catastrophic Failures)

Contracts Directory Structure

Testing Architecture

coveralls commented Jun 29, 2019 • edited Loading

abandeali1 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dorothy-zbornak left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hysz Aug 20, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dorothy-zbornak left a comment

Choose a reason for hiding this comment

abandeali1 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hysz commented Jun 29, 2019 •

edited

Loading

coveralls commented Jun 29, 2019 •

edited

Loading

hysz Aug 20, 2019 •

edited

Loading