Merge branch 'master' into escapable

contracts/LPVault.sol

@@ -1,15 +1,33 @@
 pragma solidity ^0.4.11;
 
+/*
+    Copyright 2017, Jordi Baylina
+    Contributors: RJ Ewing, Griff Green, Arthur Lunn
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
 /// @title LPVault
 /// @author Jordi Baylina
-/// @notice This contract holds ether securely for liquid pledging systems. For
+
-///  this iteration the funds will come straight from the Giveth Multisig as a
+/// @dev This contract holds ether securely for liquid pledging systems; for
-///  safety precaution, but once fully tested and optimized this contract will
+///  this iteration the funds will come often be escaped to the Giveth Multisig
+///  (safety precaution), but once fully tested and optimized this contract will
 ///  be a safe place to store funds equipped with optional variable time delays
 ///  to allow for an optional escape hatch to be implemented
 import "giveth-common-contracts/contracts/Escapable.sol";
 
-
 /// @dev `LiquidPledging` is a basic interface to allow the `LPVault` contract
 ///  to confirm and cancel payments in the `LiquidPledging` contract.
 contract LiquidPledging {
@@ -22,19 +40,19 @@ contract LiquidPledging {
 ///  contract that holds funds for the liquid pledging system.
 contract LPVault is Escapable {
 
-    LiquidPledging public liquidPledging; // liquidPledging contract's address
+    LiquidPledging public liquidPledging; // LiquidPledging contract's address
-    bool public autoPay; // if false, payments will take 2 txs to be completed
+    bool public autoPay; // If false, payments will take 2 txs to be completed
 
     enum PaymentStatus {
-        Pending, // means the payment is awaiting confirmation
+        Pending, // When the payment is awaiting confirmation
-        Paid,    // means the payment has been sent
+        Paid,    // When the payment has been sent
-        Canceled // means the payment will never be sent
+        Canceled // When the payment will never be sent
     }
     /// @dev `Payment` is a public structure that describes the details of
     ///  each payment the `ref` param makes it easy to track the movements of
     ///  funds transparently by its connection to other `Payment` structs
     struct Payment {
-        PaymentStatus state; //
+        PaymentStatus state; // Pending, Paid or Canceled
         bytes32 ref; // an input that references details from other contracts
         address dest; // recipient of the ETH
         uint amount; // amount of ETH (in wei) to be sent
@@ -48,39 +66,44 @@ contract LPVault is Escapable {
     {
     }
 
-    /// @dev `liquidPledging` is the only address that can call a function with
+    /// @dev The attached `LiquidPledging` contract is the only address that can
-    ///  this modifier
+    ///  call a function with this modifier
     modifier onlyLiquidPledging() {
         require(msg.sender == address(liquidPledging));
         _;
     }
 
+    /// @dev The fall back function allows ETH to be deposited into the LPVault
+    ///  through a simple send
     function () public payable {}
 
-    /// @notice `setLiquidPledging` is used to attach a specific liquid pledging
+    /// @notice `onlyOwner` used to attach a specific liquidPledging instance
-    ///  instance to this LPvault. Keep in mind this isn't a single pledge but
+    ///  to this LPvault; keep in mind that once a liquidPledging contract is 
-    ///  instead an entire liquid pledging contract.
+    ///  attached it cannot be undone, this vault will be forever connected
     /// @param _newLiquidPledging A full liquid pledging contract
     function setLiquidPledging(address _newLiquidPledging) public onlyOwner {
         require(address(liquidPledging) == 0x0);
         liquidPledging = LiquidPledging(_newLiquidPledging);
     }
 
-    /// @notice `setAutopay` is used to toggle whether the LPvault will
+    /// @notice Used to decentralize, toggles whether the LPVault will
-    ///  automatically confirm a payment after the payment has been authorized.
+    ///  automatically confirm a payment after the payment has been authorized
-    /// @param _automatic If true payments will confirm automatically
+    /// @param _automatic If true, payments will confirm instantly, if false
+    ///  the training wheels are put on and the owner must manually approve 
+    ///  every payment
     function setAutopay(bool _automatic) public onlyOwner {
         autoPay = _automatic;
+        AutoPaySet();
     }
 
-    /// @notice `authorizePayment` is used in order to approve a payment 
+    /// @notice `onlyLiquidPledging` authorizes payments from this contract, if 
-    ///  from the liquid pledging contract. Whenever a project or other address
+    ///  `autoPay == true` the transfer happens automatically `else` the `owner`
-    ///  needs to receive a payment it needs to be authorized with this contract.
+    ///  must call `confirmPayment()` for a transfer to occur (training wheels);
-    /// @param _ref This parameter is used to reference details about the
+    ///  either way, a new payment is added to `payments[]` 
-    ///  payment from another contract.
+    /// @param _ref References the payment will normally be the pledgeID
-    /// @param _dest This is the address that payments will end up being sent to
+    /// @param _dest The address that payments will be sent to
-    /// @param _amount This is the amount that the payment is being authorized
+    /// @param _amount The amount that the payment is being authorized for
-    ///  for.
+    /// @return idPayment The id of the payment (needed by the owner to confirm)
     function authorizePayment(
         bytes32 _ref,
         address _dest,
@@ -103,20 +126,18 @@ contract LPVault is Escapable {
         return idPayment;
     }
 
-    /// @notice `confirmPayment` is a basic function used to allow the
+    /// @notice Allows the owner to confirm payments;  since 
-    ///  owner of the vault to initiate a payment confirmation. Since 
+    ///  `authorizePayment` is the only way to populate the `payments[]` array
-    ///  `authorizePayment` is the only pay to populate the `payments` array
     ///  this is generally used when `autopay` is `false` after a payment has
-    ///  has been authorized.
+    ///  has been authorized
     /// @param _idPayment Array lookup for the payment.
     function confirmPayment(uint _idPayment) public onlyOwner {
         doConfirmPayment(_idPayment);
     }
 
-    /// @notice `doConfirmPayment` is used to actually initiate a payment
+    /// @notice Transfers ETH according to the data held within the specified
-    ///  to the final destination. All of the payment information should be
+    ///  payment id (internal function)
-    ///  set before calling this function.
+    /// @param _idPayment id number for the payment about to be fulfilled 
-    /// @param _idPayment Array lookup for the payment.
     function doConfirmPayment(uint _idPayment) internal {
         require(_idPayment < payments.length);
         Payment storage p = payments[_idPayment];
@@ -125,21 +146,20 @@ contract LPVault is Escapable {
         p.state = PaymentStatus.Paid;
         liquidPledging.confirmPayment(uint64(p.ref), p.amount);
 
-        p.dest.transfer(p.amount);  // only ETH denominated in wei
+        p.dest.transfer(p.amount);  // Transfers ETH denominated in wei
 
         ConfirmPayment(_idPayment);
     }
 
-    /// @notice `cancelPayment` is used when `autopay` is `false` in order
+    /// @notice When `autopay` is `false` and after a payment has been authorized
     ///  to allow the owner to cancel a payment instead of confirming it.
     /// @param _idPayment Array lookup for the payment.
     function cancelPayment(uint _idPayment) public onlyOwner {
         doCancelPayment(_idPayment);
     }
 
-    /// @notice `doCancelPayment` This carries out the task of actually
+    /// @notice Cancels a pending payment (internal function)
-    ///  canceling a payment instead of confirming it.
+    /// @param _idPayment id number for the payment    
-    /// @param _idPayment Array lookup for the payment.    
     function doCancelPayment(uint _idPayment) internal {
         require(_idPayment < payments.length);
         Payment storage p = payments[_idPayment];
@@ -153,8 +173,7 @@ contract LPVault is Escapable {
 
     }
 
-    /// @notice `multiConfirm` allows for more efficient confirmation of
+    /// @notice `onlyOwner` An efficient way to confirm multiple payments
-    ///  multiple payments.
     /// @param _idPayments An array of multiple payment ids
     function multiConfirm(uint[] _idPayments) public onlyOwner {
         for (uint i = 0; i < _idPayments.length; i++) {
@@ -162,8 +181,7 @@ contract LPVault is Escapable {
         }
     }
 
-    /// @notice `multiCancel` allows for more efficient cancellation of
+    /// @notice `onlyOwner` An efficient way to cancel multiple payments
-    ///  multiple payments.
     /// @param _idPayments An array of multiple payment ids
     function multiCancel(uint[] _idPayments) public onlyOwner {
         for (uint i = 0; i < _idPayments.length; i++) {
@@ -171,9 +189,7 @@ contract LPVault is Escapable {
         }
     }
 
-    /// @notice `nPayments` Basic getter to return the number of payments
+    /// @return The total number of payments that have ever been authorized
-    ///  currently held in the system. Since payments are not removed from
-    ///  the array this represents all payments over all time.
     function nPayments() constant public returns (uint) {
         return payments.length;
     }
@@ -199,8 +215,13 @@ contract LPVault is Escapable {
         EscapeFundsCalled(_token, _amount);
     }
 
+    event AutoPaySet();
     event ConfirmPayment(uint indexed idPayment);
     event CancelPayment(uint indexed idPayment);
-    event AuthorizePayment(uint indexed idPayment, bytes32 indexed ref, address indexed dest, uint amount);
+    event AuthorizePayment(
-    event EscapeFundsCalled(address _token, uint _amount);
+        uint indexed idPayment,
+        bytes32 indexed ref,
+        address indexed dest,
+        uint amount
+        );
 }