From f7816493553c7fc5cbb2287e01971e5da85a7ac0 Mon Sep 17 00:00:00 2001
From: Griff Green <saveoursonics@gmail.com>
Date: Tue, 26 Sep 2017 10:57:09 +0200
Subject: [PATCH] added comments

---
 contracts/Vault.sol | 41 +++++++++++++++++++++++++++++------------
 1 file changed, 29 insertions(+), 12 deletions(-)

diff --git a/contracts/Vault.sol b/contracts/Vault.sol
index 260518c..63e971b 100644
--- a/contracts/Vault.sol
+++ b/contracts/Vault.sol
@@ -1,37 +1,54 @@
 pragma solidity ^0.4.11;
 
+/// @title Vault
+/// @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
+///  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 "./Owned.sol";
 
+/// @dev This is declares a few functions from `LiquidPledging` so that the
+///  `Vault` contract can interface with the `LiquidPledging` contract
 contract LiquidPledging {
     function confirmPayment(uint64 idNote, uint amount);
     function cancelPayment(uint64 idNote, uint amount);
 }
 
+
+/// @dev `Vault` is a higher level contract built off of the `Owned`
+///  contract that holds funds for the liquid pledging system. 
 contract Vault is Owned {
 
-    LiquidPledging public liquidPledging;
-    bool public autoPay;
+    LiquidPledging public liquidPledging; // liquidPledging contract's address
+    bool public autoPay; // if false, payments will take 2 txs to be completed
 
     enum PaymentState {
-        Pending,
-        Paid,
-        Canceled
+        Pending, // means the payment is awaiting confirmation
+        Paid,    // means the payment has been sent 
+        Canceled // means 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 {
-        PaymentState state;
-        bytes32 ref;
-        address dest;
-        uint amount;
+        PaymentState state; // 
+        bytes32 ref; // a hash that references details from other contracts
+        address dest; // recipient of the ETH
+        uint amount; // amount of ETH (in wei) to be sent
     }
 
+    // @dev An array that contains all the payments for this Vault
     Payment[] public payments;
 
+    // @dev `liquidPledging` is the only address that can call a function with
+    /// this modifier
     modifier onlyLiquidPledging() {
         require(msg.sender == address(liquidPledging));
         _;
     }
-
+    /// @dev USED FOR TESTING???
     function VaultMock() {
 
     }
@@ -74,7 +91,7 @@ contract Vault is Owned {
         require(p.state == PaymentState.Pending);
 
         p.state = PaymentState.Paid;
-        p.dest.transfer(p.amount);
+        p.dest.transfer(p.amount);  // only ETH denominated in wei
 
         liquidPledging.confirmPayment(uint64(p.ref), p.amount);