Added top-level README to the staking package

contracts/staking/README.md

@@ -1,6 +1,64 @@
-## ERC1155 Tokens
+## Staking Contracts
+
+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 (Catastrophic Failure Mode)
+If a vulnerability is discovered in the staking contract. 
+  1. The 0x Exchange contract stops charging protocol fees
+  2. The staking contract is set to read-only mode (clients may still query balances)
+  3. Vaults are detached from the staking contract
+  4. Users may withdraw their assets directly from vaults
+  5. If state is corrupted, the staking storage is detached from the logic contract and a new storage contract is deployed
+
+ Steps 1-3 are triggered immediately upon discovering a potential failure. Steps 4-5 are triggered if the internal staking state has been corrupted; in this worst-case scenario, the staking contract must be re-deployed — users withdraw their funds from the vaults and re-stake under a new staking contract.
+
+![](images/architecture_failure_mode.png)
+
+
+## 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.
 
-This package implements the stake-based liquidity incentives defined by [ZEIP-31](https://github.com/0xProject/ZEIPs/issues/31). Addresses of the deployed contracts can be found in the 0x [wiki](https://0xproject.com/wiki#Deployed-Addresses) or the [DEPLOYS](./DEPLOYS.json) file within this package.
 
 ## Installation
 

contracts/staking/contracts/src/core_interfaces/IMixinScheduler.sol

@@ -1,85 +0,0 @@
-/*
-
-  Copyright 2018 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.5;
-
-
-contract IMixinScheduler {
-
-    /// @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.
-
-    /// @dev Returns the current epoch.
-    function getCurrentEpoch()
-        public
-        view
-        returns (uint64);
-
-    /// @dev Returns the current epoch period, measured in seconds.
-    ///      Epoch period = [startTimeInSeconds..endTimeInSeconds)
-    function getEpochDurationInSeconds()
-        public
-        pure
-        returns (uint64);
-
-    /// @dev Returns the start time in seconds of the current epoch.
-    ///      Epoch period = [startTimeInSeconds..endTimeInSeconds)
-    function getCurrentEpochStartTimeInSeconds()
-        public
-        view
-        returns (uint64);
-
-    /// @dev Returns the earliest end time in seconds of this epoch.
-    ///      The next epoch can begin once this time is reached.  
-    ///      Epoch period = [startTimeInSeconds..endTimeInSeconds)
-    function getCurrentEpochEarliestEndTimeInSeconds()
-        public
-        view
-        returns (uint64);
-
-    /// @dev Returns the current timelock period
-    function getCurrentTimelockPeriod()
-        public
-        view
-        returns (uint64);
-
-    /// @dev Returns the length of a timelock period, measured in epochs.
-    ///      Timelock period = [startEpoch..endEpoch)
-    function getTimelockDurationInEpochs()
-        public
-        pure
-        returns (uint64);
-
-    /// @dev Returns the epoch that the current timelock period started at.
-    ///      Timelock period = [startEpoch..endEpoch)
-    function getCurrentTimelockPeriodStartEpoch()
-        public
-        view
-        returns (uint64);
-
-    /// @dev Returns the epoch that the current timelock period will end.
-    ///      Timelock period = [startEpoch..endEpoch)
-    function getCurrentTimelockPeriodEndEpoch()
-        public
-        view
-        returns (uint64);
-}