Merge pull request #2208 from 0xProject/cleanup/staking/spec

Updated README to point to new specification

contracts/staking/README.md

@@ -2,51 +2,7 @@
 
 This package implements the stake-based liquidity incentives defined by [ZEIP-31](https://github.com/0xProject/ZEIPs/issues/31).
 
-Functionality:
-
-1. 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
-2. Create staking pools to leverage the weight of other stakers.
-    - Increase your market making rebates.
-    - Increase your voting power.
-3. 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.
-
-## Architecture
-
-This system is composed of four deployed contracts:
-
-1. Staking Contract, which is an upgradeable/stateless contract that implements staking logic.
-2. Staking Contract Proxy, which stores staking state and delegates to the Staking Contract.
-3. Zrx Vault, which securely holds staked Zrx Tokens.
-4. 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:
-
-![](images/architecture.png)
-
-## Architecture (Kill Switch)
-
-If a vulnerability is discovered in the staking contract, operations may be halted to conduct forensics:
-
-1. The 0x Exchange contract stops charging protocol fees
-2. The staking contract is set to read-only mode
-3. Vaults may be detached from the staking contract, depending on the vulnerability.
-
-![](images/architecture_kill_switch.png)
-
-## 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.
-
-4. Vaults enter "Catastrophic Failure Mode" allowing users to withdraw their ZRX and Rewards.
-5. A Balance Oracle is deployed for determining the Reward balance of each user. (\*)
-
-![](images/architecture_failure_mode.png)
-
-(\*) 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.)
+See the specification [here](https://github.com/0xProject/0x-protocol-specification/blob/3.0/staking/staking-specification.md).
 
 ## Contracts Directory Structure
 
@@ -55,20 +11,17 @@ 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.
+* ReadOnlyProxy.sol  | This is a stateless contract the makes read-only calls from the Staking Proxy to the Staking Contract.
+* fees/              | This contains mixins that implement the logic for 0x Protocol fees.
+* immutable/         | This contains mixins that are generally immutable. Changing these files can result in catastrophic failures. Exercise extreme caution.
 * 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.
+* sys/               | This contains mixins that implement system-level functionality, like scheduling and finalization.
 * 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.
-
 ## Installation
 
 **Install**
@@ -130,7 +83,3 @@ yarn lint
 ```bash
 yarn test
 ```
-
-#### Testing options
-
-Contracts testing options like coverage, profiling, revert traces or backing node choosing - are described [here](../TESTING.md).

contracts/staking/contracts/src/ZrxVault.sol

@@ -28,18 +28,6 @@ import "./libs/LibStakingRichErrors.sol";
 import "./interfaces/IZrxVault.sol";
 
 
-/// @dev This vault manages Zrx Tokens.
-/// When a user mints stake, their Zrx Tokens are deposited into this vault.
-/// Similarly, when they burn stake, their Zrx Tokens are withdrawn from this vault.
-/// The contract also includes management of the staking contract
-/// and setting the vault to "Catastrophic Failure Mode".
-/// Catastrophic Failure Mode should only be set iff there is
-/// non-recoverable corruption of the staking contracts. If there is a
-/// recoverable flaw/bug/vulnerability, simply detach the staking contract
-/// by setting its address to `address(0)`. In Catastrophic Failure Mode, only withdrawals
-/// can be made (no deposits). Once Catastrophic Failure Mode  is invoked,
-/// it cannot be returned to normal mode; this prevents corruption of related
-/// state in the staking contract.
 contract ZrxVault is
     Authorizable,
     IZrxVault

contracts/staking/contracts/src/fees/MixinExchangeManager.sol

@@ -24,10 +24,6 @@ import "../interfaces/IStakingEvents.sol";
 import "../immutable/MixinStorage.sol";
 
 
-/// @dev This mixin contains logic for managing exchanges.
-/// Any exchange contract that connects to the staking contract
-/// must be added here. When an exchange contract is deprecated
-/// then it should be removed.
 contract MixinExchangeManager is
     IStakingEvents,
     MixinStorage

contracts/staking/contracts/src/interfaces/IZrxVault.sol

@@ -19,18 +19,6 @@
 pragma solidity ^0.5.9;
 
 
-/// @dev This vault manages Zrx Tokens.
-/// When a user mints stake, their Zrx Tokens are deposited into this vault.
-/// Similarly, when they burn stake, their Zrx Tokens are withdrawn from this vault.
-/// The contract also includes management of the staking contract
-/// and setting the vault to "Catastrophic Failure Mode".
-/// Catastrophic Failure Mode should only be set iff there is
-/// non-recoverable corruption of the staking contracts. If there is a
-/// recoverable flaw/bug/vulnerability, simply detach the staking contract
-/// by setting its address to `address(0)`. In Catastrophic Failure Mode, only withdrawals
-/// can be made (no deposits). Once Catastrophic Failure Mode  is invoked,
-/// it cannot be returned to normal mode; this prevents corruption of related
-/// state in the staking contract.
 interface IZrxVault {
 
     /// @dev Emmitted whenever a StakingProxy is set in a vault.

contracts/staking/contracts/src/stake/MixinStake.sol

@@ -24,7 +24,6 @@ import "../staking_pools/MixinStakingPool.sol";
 import "../libs/LibStakingRichErrors.sol";
 
 
-/// @dev This mixin contains logic for managing ZRX tokens and Stake.
 contract MixinStake is
     MixinStakingPool
 {

contracts/staking/contracts/src/stake/MixinStakeBalances.sol

@@ -24,8 +24,6 @@ import "../interfaces/IStructs.sol";
 import "./MixinStakeStorage.sol";
 
 
-/// @dev This mixin contains logic for querying stake balances.
-/// **** Read MixinStake before continuing ****
 contract MixinStakeBalances is
     MixinStakeStorage
 {

contracts/staking/contracts/src/sys/MixinFinalizer.sol

@@ -27,11 +27,6 @@ import "../interfaces/IStructs.sol";
 import "../staking_pools/MixinStakingPoolRewards.sol";
 
 
-/// @dev This mixin contains functions related to finalizing epochs.
-///      Finalization occurs AFTER the current epoch is ended/advanced and
-///      over (potentially) multiple blocks/transactions. This pattern prevents
-///      the contract from stalling while we finalize rewards for the previous
-///      epoch.
 contract MixinFinalizer is
     MixinStakingPoolRewards
 {
@@ -96,7 +91,7 @@ contract MixinFinalizer is
     }
 
     /// @dev Instantly finalizes a single pool that was active in the previous
-    ///      epoch, crediting it rewards for members and withdrawing operator's 
+    ///      epoch, crediting it rewards for members and withdrawing operator's
     ///      rewards as WETH. This can be called by internal functions that need
     ///      to finalize a pool immediately. Does nothing if the pool is already
     ///      finalized or was not active in the previous epoch.

contracts/staking/contracts/src/sys/MixinScheduler.sol

@@ -25,12 +25,6 @@ import "../immutable/MixinStorage.sol";
 import "../interfaces/IStakingEvents.sol";
 
 
-/// @dev This mixin contains logic for time-based scheduling.
-/// All processes in the system are segmented into time intervals, called epochs.
-/// Epochs have a fixed minimum time period that is configured when this contract is deployed.
-/// The current epoch only changes by calling this contract, which can be invoked by anyone.
-/// Epochs serve as the basis for all other time intervals, which provides a more stable
-/// and consistent scheduling metric than time. TimeLocks, for example, are measured in epochs.
 contract MixinScheduler is
     IStakingEvents,
     MixinStorage