From 5dacc279431a87c2020d31c7dd895b51d3358bdc Mon Sep 17 00:00:00 2001 From: alf40k Date: Tue, 24 Oct 2017 00:09:56 -0400 Subject: [PATCH] Add copyrights and finish commenting plugin interface --- contracts/ILiquidPledgingPlugin.sol | 55 +++++++++++++++++++++++++++-- contracts/LiquidPledging.sol | 38 ++++++++++++++++---- contracts/LiquidPledgingBase.sol | 26 +++++++++++++- contracts/LiquidPledgingMock.sol | 1 - 4 files changed, 108 insertions(+), 12 deletions(-) diff --git a/contracts/ILiquidPledgingPlugin.sol b/contracts/ILiquidPledgingPlugin.sol index d0f755c..e76a7cc 100644 --- a/contracts/ILiquidPledgingPlugin.sol +++ b/contracts/ILiquidPledgingPlugin.sol @@ -1,9 +1,35 @@ pragma solidity ^0.4.11; +/* + Copyright 2017, Jordi Baylina + Contributor: Adrià Massanet + + 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 . +*/ + + +/// @dev `ILiquidPledgingPlugin` is the basic interface for any +/// liquid pledging plugin contract ILiquidPledgingPlugin { + /// @notice Plugins are used (much like web hooks) to initiate an action /// upon any donation, delegation, or transfer; this is an optional feature - /// and allows for extreme customization of the contract + /// and allows for extreme customization of the contract. This function + /// implements any action that should be initiated before a transfer. + /// @param pledgeManager The admin or current manager of the pledge + /// @param pledgeFrom This is the Id from which value will be transfered. + /// @param pledgeTo This is the Id that value will be transfered to. /// @param context The situation that is triggering the plugin: /// 0 -> Plugin for the owner transferring pledge to another party /// 1 -> Plugin for the first delegate transferring pledge to another party @@ -16,17 +42,40 @@ contract ILiquidPledgingPlugin { /// 258 -> Plugin for the second delegate receiving pledge to another party /// ... /// 511 -> Plugin for the intendedProject receiving pledge to another party + /// @param _amount The amount of value that will be transfered. function beforeTransfer( uint64 pledgeManager, uint64 pledgeFrom, uint64 pledgeTo, uint64 context, uint amount - ) returns (uint maxAllowed); + ) returns (uint maxAllowed); + + /// @notice Plugins are used (much like web hooks) to initiate an action + /// upon any donation, delegation, or transfer; this is an optional feature + /// and allows for extreme customization of the contract. This function + /// implements any action that should be initiated after a transfer. + /// @param pledgeManager The admin or current manager of the pledge + /// @param pledgeFrom This is the Id from which value will be transfered. + /// @param pledgeTo This is the Id that value will be transfered to. + /// @param context The situation that is triggering the plugin: + /// 0 -> Plugin for the owner transferring pledge to another party + /// 1 -> Plugin for the first delegate transferring pledge to another party + /// 2 -> Plugin for the second delegate transferring pledge to another party + /// ... + /// 255 -> Plugin for the intendedProject transferring pledge to another party + /// + /// 256 -> Plugin for the owner receiving pledge to another party + /// 257 -> Plugin for the first delegate receiving pledge to another party + /// 258 -> Plugin for the second delegate receiving pledge to another party + /// ... + /// 511 -> Plugin for the intendedProject receiving pledge to another party + /// @param _amount The amount of value that will be transfered. function afterTransfer( uint64 pledgeManager, uint64 pledgeFrom, uint64 pledgeTo, uint64 context, - uint amount); + uint amount + ); } diff --git a/contracts/LiquidPledging.sol b/contracts/LiquidPledging.sol index 4277373..3a53c33 100644 --- a/contracts/LiquidPledging.sol +++ b/contracts/LiquidPledging.sol @@ -1,4 +1,5 @@ pragma solidity ^0.4.11; + /* Copyright 2017, Jordi Baylina Contributor: Adrià Massanet @@ -20,7 +21,10 @@ pragma solidity ^0.4.11; // Contract Imports import "./LiquidPledgingBase.sol"; -/// @dev `LiquidPleding` is a +/// @dev `LiquidPleding` allows for liquid pledging through the use of +/// internal id structures and delegate chaining. All basic operations for +/// handling liquid pledging are supplied as well as plugin features +/// to allow for expanded functionality. contract LiquidPledging is LiquidPledgingBase { @@ -625,7 +629,7 @@ contract LiquidPledging is LiquidPledgingBase { /// @param toPledge This is the Id that value is being transfered to. /// @param context The situation that is triggering the plugin. See plugin /// for a full description of contexts. - /// @param _amount The amount of value that is being transfered. + /// @param amount The amount of value that is being transfered. function callPlugin( bool before, uint64 adminId, @@ -664,11 +668,10 @@ contract LiquidPledging is LiquidPledgingBase { } } - /// @notice `callPluginsPledge` is used to apply various plugin calls - /// to the delegate chain or the intended project dependent on whether - /// the function is called with the same pledge Id that the call is from. - /// If `fromPledge` and `idPledge` share the same ID the plugin is called - /// on the intended project instead of the delegate chain. + /// @notice `callPluginsPledge` is used to apply plugin calls to + /// the delegate chain and the intended project if there is one. + /// It does so in either a transferring or receiving context based + /// on the `idPledge` and `fromPledge` parameters. /// @param before This toggle determines whether the plugin call is occuring /// before or after a transfer. /// @param idPledge This is the Id of the pledge on which this plugin @@ -683,10 +686,13 @@ contract LiquidPledging is LiquidPledgingBase { uint64 toPledge, uint amount ) internal returns (uint allowedAmount) { + // Determine if callPlugin is being applied in a receiving + // or transferring context uint64 offset = idPledge == fromPledge ? 0 : 256; allowedAmount = amount; Pledge storage n = findPledge(idPledge); + // Always call the plugin on the owner allowedAmount = callPlugin( before, n.owner, @@ -696,6 +702,7 @@ contract LiquidPledging is LiquidPledgingBase { allowedAmount ); + // Apply call plugin to all delegates for (uint64 i=0; i 0) { allowedAmount = callPlugin( before, @@ -719,6 +729,15 @@ contract LiquidPledging is LiquidPledgingBase { } } + + /// @notice `callPlugins` calls `callPluginsPledge` once for the transfer + /// context and once for the receiving context. The aggregated + /// allowed amount is then returned. + /// @param before This toggle determines whether the plugin call is occuring + /// before or after a transfer. + /// @param fromPledge This is the Id from which value is being transfered. + /// @param toPledge This is the Id that value is being transfered to. + /// @param amount The amount of value that is being transfered. function callPlugins( bool before, uint64 fromPledge, @@ -727,6 +746,7 @@ contract LiquidPledging is LiquidPledgingBase { ) internal returns (uint allowedAmount) { allowedAmount = amount; + // Call the pledges plugins in the transfer context allowedAmount = callPluginsPledge( before, fromPledge, @@ -734,6 +754,8 @@ contract LiquidPledging is LiquidPledgingBase { toPledge, allowedAmount ); + + // Call the pledges plugins in the receive context allowedAmount = callPluginsPledge( before, toPledge, @@ -747,10 +769,12 @@ contract LiquidPledging is LiquidPledgingBase { // Test functions ///////////// + /// @notice Basic helper function to return the current time function getTime() internal returns (uint) { return now; } + // Event Delcerations event Transfer(uint64 indexed from, uint64 indexed to, uint amount); event CancelProject(uint64 indexed idProject); diff --git a/contracts/LiquidPledgingBase.sol b/contracts/LiquidPledgingBase.sol index 977032d..e0775ad 100644 --- a/contracts/LiquidPledgingBase.sol +++ b/contracts/LiquidPledgingBase.sol @@ -1,4 +1,21 @@ pragma solidity ^0.4.11; +/* + Copyright 2017, Jordi Baylina + Contributor: Adrià Massanet + + 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 . +*/ import "./ILiquidPledgingPlugin.sol"; @@ -9,7 +26,11 @@ contract Vault { function () payable; } +/// @dev `LiquidPledgingBase` is the base level contract used to carry out +/// liquid pledging. This function mostly handles the data structures +/// and basic CRUD methods for liquid pledging. contract LiquidPledgingBase { + // Limits inserted to prevent large loops that could prevent canceling uint constant MAX_DELEGATES = 20; uint constant MAX_SUBPROJECT_LEVEL = 20; @@ -28,7 +49,9 @@ contract LiquidPledgingBase { uint64 commitTime; // In seconds, used for Givers' & Delegates' vetos uint64 parentProject; // Only for projects bool canceled; //Always false except for canceled projects - ILiquidPledgingPlugin plugin; // if the plugin is 0x0 then nothing happens if its a contract address than that smart contract is called via the milestone contract + // if the plugin is 0x0 then nothing happens if its a contract address + // than that smart contract is called via the milestone contract + ILiquidPledgingPlugin plugin; } struct Pledge { @@ -53,6 +76,7 @@ contract LiquidPledgingBase { // Modifiers ///// + /// @notice basic method to restrict a function to only the current vault modifier onlyVault() { require(msg.sender == address(vault)); _; diff --git a/contracts/LiquidPledgingMock.sol b/contracts/LiquidPledgingMock.sol index ddfe81f..baa03a3 100644 --- a/contracts/LiquidPledgingMock.sol +++ b/contracts/LiquidPledgingMock.sol @@ -3,7 +3,6 @@ pragma solidity ^0.4.11; import "./LiquidPledging.sol"; // @dev LiquidPledgingMock mocks current block number - contract LiquidPledgingMock is LiquidPledging { uint public mock_time;