Moved Escrows into an escrow subdirectory, improved docs. (#1430)

* Moved Escrows into an escrow subdirectory, improved docs.

* Fixed escrow mock.

* Fixed some more imports.

contracts/payment/escrow/ConditionalEscrow.sol

@@ -0,0 +1,22 @@
+pragma solidity ^0.4.24;
+
+import "./Escrow.sol";
+
+/**
+ * @title ConditionalEscrow
+ * @dev Base abstract escrow to only allow withdrawal if a condition is met.
+ * @dev Intended usage: See Escrow.sol. Same usage guidelines apply here.
+ */
+contract ConditionalEscrow is Escrow {
+  /**
+  * @dev Returns whether an address is allowed to withdraw their funds. To be
+  * implemented by derived contracts.
+  * @param payee The destination address of the funds.
+  */
+  function withdrawalAllowed(address payee) public view returns (bool);
+
+  function withdraw(address payee) public {
+    require(withdrawalAllowed(payee));
+    super.withdraw(payee);
+  }
+}

contracts/payment/escrow/Escrow.sol

@@ -0,0 +1,54 @@
+pragma solidity ^0.4.24;
+
+import "../../math/SafeMath.sol";
+import "../../ownership/Secondary.sol";
+
+ /**
+ * @title Escrow
+ * @dev Base escrow contract, holds funds designated for a payee until they
+ * withdraw them.
+ * @dev Intended usage: This contract (and derived escrow contracts) should be a
+ * standalone contract, that only interacts with the contract that instantiated
+ * it. That way, it is guaranteed that all Ether will be handled according to
+ * the Escrow rules, and there is no need to check for payable functions or
+ * transfers in the inheritance tree. The contract that uses the escrow as its
+ * payment method should be its primary, and provide public methods redirecting
+ * to the escrow's deposit and withdraw.
+ */
+contract Escrow is Secondary {
+  using SafeMath for uint256;
+
+  event Deposited(address indexed payee, uint256 weiAmount);
+  event Withdrawn(address indexed payee, uint256 weiAmount);
+
+  mapping(address => uint256) private _deposits;
+
+  function depositsOf(address payee) public view returns (uint256) {
+    return _deposits[payee];
+  }
+
+  /**
+  * @dev Stores the sent amount as credit to be withdrawn.
+  * @param payee The destination address of the funds.
+  */
+  function deposit(address payee) public onlyPrimary payable {
+    uint256 amount = msg.value;
+    _deposits[payee] = _deposits[payee].add(amount);
+
+    emit Deposited(payee, amount);
+  }
+
+  /**
+  * @dev Withdraw accumulated balance for a payee.
+  * @param payee The address whose funds will be withdrawn and transferred to.
+  */
+  function withdraw(address payee) public onlyPrimary {
+    uint256 payment = _deposits[payee];
+
+    _deposits[payee] = 0;
+
+    payee.transfer(payment);
+
+    emit Withdrawn(payee, payment);
+  }
+}

contracts/payment/escrow/RefundEscrow.sol

@@ -0,0 +1,91 @@
+pragma solidity ^0.4.24;
+
+import "./ConditionalEscrow.sol";
+
+/**
+ * @title RefundEscrow
+ * @dev Escrow that holds funds for a beneficiary, deposited from multiple
+ * parties.
+ * @dev Intended usage: See Escrow.sol. Same usage guidelines apply here.
+ * @dev The primary account (that is, the contract that instantiates this
+ * contract) may deposit, close the deposit period, and allow for either
+ * withdrawal by the beneficiary, or refunds to the depositors. All interactions
+ * with RefundEscrow will be made through the primary contract. See the
+ * RefundableCrowdsale contract for an example of RefundEscrow’s use.
+ */
+contract RefundEscrow is ConditionalEscrow {
+  enum State { Active, Refunding, Closed }
+
+  event RefundsClosed();
+  event RefundsEnabled();
+
+  State private _state;
+  address private _beneficiary;
+
+  /**
+   * @dev Constructor.
+   * @param beneficiary The beneficiary of the deposits.
+   */
+  constructor(address beneficiary) public {
+    require(beneficiary != address(0));
+    _beneficiary = beneficiary;
+    _state = State.Active;
+  }
+
+  /**
+   * @return the current state of the escrow.
+   */
+  function state() public view returns (State) {
+    return _state;
+  }
+
+  /**
+   * @return the beneficiary of the escrow.
+   */
+  function beneficiary() public view returns (address) {
+    return _beneficiary;
+  }
+
+  /**
+   * @dev Stores funds that may later be refunded.
+   * @param refundee The address funds will be sent to if a refund occurs.
+   */
+  function deposit(address refundee) public payable {
+    require(_state == State.Active);
+    super.deposit(refundee);
+  }
+
+  /**
+   * @dev Allows for the beneficiary to withdraw their funds, rejecting
+   * further deposits.
+   */
+  function close() public onlyPrimary {
+    require(_state == State.Active);
+    _state = State.Closed;
+    emit RefundsClosed();
+  }
+
+  /**
+   * @dev Allows for refunds to take place, rejecting further deposits.
+   */
+  function enableRefunds() public onlyPrimary {
+    require(_state == State.Active);
+    _state = State.Refunding;
+    emit RefundsEnabled();
+  }
+
+  /**
+   * @dev Withdraws the beneficiary's funds.
+   */
+  function beneficiaryWithdraw() public {
+    require(_state == State.Closed);
+    _beneficiary.transfer(address(this).balance);
+  }
+
+  /**
+   * @dev Returns whether refundees can withdraw their deposits (be refunded).
+   */
+  function withdrawalAllowed(address payee) public view returns (bool) {
+    return _state == State.Refunding;
+  }
+}