@gooddollar/goodcollective-contracts 1.0.4 → 1.0.6-beta.0b8171a

package/contracts/DirectPayments/DirectPaymentsFactory.sol

@@ -5,6 +5,9 @@ pragma solidity >=0.8.0;
 import "./DirectPaymentsPool.sol";
 import "./ProvableNFT.sol";
 import "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol";
+import "@openzeppelin/contracts/proxy/beacon/BeaconProxy.sol";
+import "@openzeppelin/contracts/proxy/beacon/UpgradeableBeacon.sol";
+
 import { AccessControlUpgradeable } from "@openzeppelin/contracts-upgradeable/access/AccessControlUpgradeable.sol";
 import { UUPSUpgradeable } from "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
 
@@ -13,7 +16,15 @@ import "hardhat/console.sol";
 contract DirectPaymentsFactory is AccessControlUpgradeable, UUPSUpgradeable {
     error NOT_PROJECT_OWNER();
 
-    event PoolCreated(address indexed pool, string indexed projectId, string ipfs, uint32 indexed nftType);
+    event PoolCreated(
+        address indexed pool,
+        string indexed projectId,
+        string ipfs,
+        uint32 indexed nftType,
+        DirectPaymentsPool.PoolSettings poolSettings,
+        DirectPaymentsPool.SafetyLimits poolLimits
+    );
+
     event PoolDetailsChanged(address indexed pool, string ipfs);
     event PoolVerifiedChanged(address indexed pool, bool isVerified);
     event UpdatedImpl(address indexed impl);
@@ -24,7 +35,7 @@ contract DirectPaymentsFactory is AccessControlUpgradeable, UUPSUpgradeable {
         string projectId;
     }
 
-    address public impl;
+    UpgradeableBeacon public impl;
     ProvableNFT public nft;
     uint32 public nextNftType;
 
@@ -60,18 +71,16 @@ contract DirectPaymentsFactory is AccessControlUpgradeable, UUPSUpgradeable {
     function initialize(
         address _owner,
         address _dpimpl,
-        address _nftimpl,
+        ProvableNFT _nft,
         address _feeRecipient,
         uint32 _feeBps
     ) external initializer {
         nextNftType = 1;
-        impl = _dpimpl;
-        bytes memory initCall = abi.encodeWithSelector(ProvableNFT.initialize.selector, "GoodCollective NFT", "GC-NFT");
-        nft = ProvableNFT(address(new ERC1967Proxy(_nftimpl, initCall)));
+        impl = new UpgradeableBeacon(_dpimpl);
+        nft = _nft;
         feeRecipient = _feeRecipient;
         feeBps = _feeBps;
 
-        nft.grantRole(DEFAULT_ADMIN_ROLE, _owner);
         _setupRole(DEFAULT_ADMIN_ROLE, _owner);
     }
 
@@ -81,7 +90,9 @@ contract DirectPaymentsFactory is AccessControlUpgradeable, UUPSUpgradeable {
         string memory _ipfs,
         DirectPaymentsPool.PoolSettings memory _settings,
         DirectPaymentsPool.SafetyLimits memory _limits
-    ) external onlyProjectOwnerOrNon(_projectId) returns (DirectPaymentsPool pool) {}
+    ) external onlyProjectOwnerOrNon(_projectId) returns (DirectPaymentsPool pool) {
+        return _createPool(_projectId, _ipfs, _settings, _limits, true);
+    }
 
     function createPool(
         string memory _projectId,
@@ -89,6 +100,16 @@ contract DirectPaymentsFactory is AccessControlUpgradeable, UUPSUpgradeable {
         DirectPaymentsPool.PoolSettings memory _settings,
         DirectPaymentsPool.SafetyLimits memory _limits
     ) external onlyProjectOwnerOrNon(_projectId) returns (DirectPaymentsPool pool) {
+        return _createPool(_projectId, _ipfs, _settings, _limits, false);
+    }
+
+    function _createPool(
+        string memory _projectId,
+        string memory _ipfs,
+        DirectPaymentsPool.PoolSettings memory _settings,
+        DirectPaymentsPool.SafetyLimits memory _limits,
+        bool useBeacon
+    ) internal returns (DirectPaymentsPool pool) {
         //TODO: add check if msg.sender is whitelisted
 
         _settings.nftType = nextNftType;
@@ -99,18 +120,25 @@ contract DirectPaymentsFactory is AccessControlUpgradeable, UUPSUpgradeable {
             _limits,
             address(this)
         );
-        pool = DirectPaymentsPool(address(new ERC1967Proxy(impl, initCall)));
+
+        if (useBeacon) {
+            pool = DirectPaymentsPool(address(new BeaconProxy(address(impl), initCall)));
+        } else {
+            pool = DirectPaymentsPool(address(new ERC1967Proxy(impl.implementation(), initCall)));
+        }
 
         nft.grantRole(nft.getManagerRole(nextNftType), _settings.manager);
         nft.grantRole(nft.getManagerRole(nextNftType), address(pool));
         pool.grantRole(pool.MINTER_ROLE(), _settings.manager);
 
-        projectIdToControlPool[keccak256(bytes(_projectId))] = pool;
+        //access control to project is determinted by the first pool access control rules
+        if (address(projectIdToControlPool[keccak256(bytes(_projectId))]) == address(0))
+            projectIdToControlPool[keccak256(bytes(_projectId))] = pool;
         registry[address(pool)].ipfs = _ipfs;
         registry[address(pool)].projectId = _projectId;
 
         pool.renounceRole(DEFAULT_ADMIN_ROLE, address(this));
-        emit PoolCreated(address(pool), _projectId, _ipfs, nextNftType);
+        emit PoolCreated(address(pool), _projectId, _ipfs, nextNftType, _settings, _limits);
 
         nextNftType++;
     }
@@ -126,7 +154,7 @@ contract DirectPaymentsFactory is AccessControlUpgradeable, UUPSUpgradeable {
     }
 
     function updateImpl(address _impl) external onlyRole(DEFAULT_ADMIN_ROLE) {
-        impl = _impl;
+        impl.upgradeTo(_impl);
         emit UpdatedImpl(_impl);
     }
 

package/contracts/DirectPayments/DirectPaymentsPool.sol

@@ -41,22 +41,39 @@ contract DirectPaymentsPool is
     error NOT_MANAGER();
     error ALREADY_CLAIMED(uint256);
     error NFT_MISSING(uint256);
-    error NOT_MEMBER(address);
-    error NOT_WHITELISTED(address);
     error OVER_MEMBER_LIMITS(address);
     error OVER_GLOBAL_LIMITS();
     error UNSUPPORTED_NFT();
     error NO_BALANCE();
+    error NFTTYPE_CHANGED();
+    error EMPTY_MANAGER();
 
     bytes32 public constant MANAGER_ROLE = keccak256("MANAGER_ROLE");
+    bytes32 public constant MEMBER_ROLE = keccak256("MEMBER_ROLE");
     bytes32 public constant MINTER_ROLE = keccak256("MINTER");
 
+    event PoolCreated(
+        address indexed pool,
+        string indexed projectId,
+        string ipfs,
+        uint32 indexed nftType,
+        DirectPaymentsPool.PoolSettings poolSettings,
+        DirectPaymentsPool.SafetyLimits poolLimits
+    );
+
     event PoolSettingsChanged(PoolSettings settings);
     event PoolLimitsChanged(SafetyLimits limits);
-    event MemberAdded(address member);
-    event MemberRemoved(address member);
-    event EventRewardClaimed(uint256 indexed tokenId, ProvableNFT.EventData eventData);
+    event EventRewardClaimed(
+        uint256 indexed tokenId,
+        uint16 eventType,
+        uint32 eventTimestamp,
+        uint256 eventQuantity,
+        string eventUri,
+        address[] contributers,
+        uint256 rewardPerContributer
+    );
     event NFTClaimed(uint256 indexed tokenId, uint256 totalRewards);
+    event NOT_MEMBER_OR_WHITELISTED(address contributer);
 
     // Define functions
     struct PoolSettings {
@@ -67,6 +84,7 @@ contract DirectPaymentsPool is
         IMembersValidator membersValidator;
         IIdentityV2 uniquenessValidator;
         IERC20Upgradeable rewardToken;
+        bool allowRewardOverride;
     }
 
     struct SafetyLimits {
@@ -88,7 +106,7 @@ contract DirectPaymentsPool is
     ProvableNFT public nft;
 
     mapping(uint256 => bool) public claimedNfts;
-    mapping(address => bool) public members;
+    mapping(address => bool) private members_unused; // using access control instead
     mapping(address => LimitsData) public memberLimits;
     LimitsData public globalLimits;
     DirectPaymentsFactory public registry;
@@ -100,7 +118,7 @@ contract DirectPaymentsPool is
      * @dev Authorizes an upgrade for the implementation contract.
      * @param impl The address of the new implementation contract.
      */
-    function _authorizeUpgrade(address impl) internal virtual override {}
+    function _authorizeUpgrade(address impl) internal virtual override onlyRole(DEFAULT_ADMIN_ROLE) {}
 
     function getRegistry() public view override returns (DirectPaymentsFactory) {
         return DirectPaymentsFactory(registry);
@@ -124,12 +142,11 @@ contract DirectPaymentsPool is
         nft = _nft;
         _setupRole(DEFAULT_ADMIN_ROLE, msg.sender);
         _setupRole(DEFAULT_ADMIN_ROLE, _settings.manager);
-
         setSuperToken(ISuperToken(address(settings.rewardToken)));
     }
 
-    function upgradeToLatest(bytes memory data) external payable virtual onlyProxy {
-        address impl = DirectPaymentsFactory(registry).impl();
+    function upgradeToLatest(bytes memory data) external payable virtual {
+        address impl = address(DirectPaymentsFactory(registry).impl());
         _authorizeUpgrade(impl);
         _upgradeToAndCallUUPS(impl, data, false);
     }
@@ -170,14 +187,27 @@ contract DirectPaymentsPool is
         uint totalRewards;
         uint rewardsBalance = settings.rewardToken.balanceOf(address(this));
 
+        bool allowRewardOverride = settings.allowRewardOverride;
         for (uint256 i = 0; i < _data.events.length; i++) {
-            uint128 reward = _eventReward(_data.events[i].subtype);
+            uint reward = (
+                allowRewardOverride && _data.events[i].rewardOverride > 0
+                    ? _data.events[i].rewardOverride
+                    : _eventReward(_data.events[i].subtype)
+            ) * _data.events[i].quantity;
             if (reward > 0) {
-                totalRewards += reward * _data.events[i].quantity;
+                totalRewards += reward;
                 if (totalRewards > rewardsBalance) revert NO_BALANCE();
                 rewardsBalance -= totalRewards;
-                _sendReward(_data.events[i].contributers, uint128(reward * _data.events[i].quantity));
-                emit EventRewardClaimed(_nftId, _data.events[i]);
+                _sendReward(_data.events[i].contributers, uint128(reward));
+                emit EventRewardClaimed(
+                    _nftId,
+                    _data.events[i].subtype,
+                    _data.events[i].timestamp,
+                    _data.events[i].quantity,
+                    _data.events[i].eventUri,
+                    _data.events[i].contributers,
+                    uint128(reward / _data.events[i].contributers.length)
+                );
             }
         }
 
@@ -203,11 +233,17 @@ contract DirectPaymentsPool is
      */
     function _sendReward(address[] memory recipients, uint128 reward) internal {
         uint128 perReward = uint128(reward / recipients.length);
+        uint128 totalSent;
         for (uint i = 0; i < recipients.length; i++) {
-            _enforceAndUpdateMemberLimits(recipients[i], perReward);
-            settings.rewardToken.safeTransfer(recipients[i], perReward);
+            bool valid = _enforceAndUpdateMemberLimits(recipients[i], perReward);
+            if (valid) {
+                settings.rewardToken.safeTransfer(recipients[i], perReward);
+                totalSent += perReward;
+            } else {
+                emit NOT_MEMBER_OR_WHITELISTED(recipients[i]);
+            }
         }
-        _enforceAndUpdateGlobalLimits(reward);
+        _enforceAndUpdateGlobalLimits(totalSent);
     }
 
     /**
@@ -215,8 +251,11 @@ contract DirectPaymentsPool is
      * @param member The address of the member to enforce and update limits for.
      * @param reward The amount of rewards to enforce and update limits for.
      */
-    function _enforceAndUpdateMemberLimits(address member, uint128 reward) internal {
-        if (members[member] == false) revert NOT_MEMBER(member);
+    function _enforceAndUpdateMemberLimits(address member, uint128 reward) internal returns (bool) {
+        //dont revert on non valid members, just dont reward them (their reward is lost)
+        if (_addMember(member, "") == false) {
+            return false;
+        }
 
         uint64 curMonth = _month();
         if (memberLimits[member].lastReward + 60 * 60 * 24 < block.timestamp) //more than a day passed since last reward
@@ -241,6 +280,8 @@ contract DirectPaymentsPool is
             memberLimits[member].daily > limits.maxMemberPerDay ||
             memberLimits[member].monthly > limits.maxMemberPerMonth
         ) revert OVER_MEMBER_LIMITS(member);
+
+        return true;
     }
 
     /**
@@ -285,32 +326,23 @@ contract DirectPaymentsPool is
      * @param extraData Additional data to validate the member.
      */
 
-    function addMember(address member, bytes memory extraData) external {
+    function _addMember(address member, bytes memory extraData) internal returns (bool isMember) {
+        if (hasRole(MEMBER_ROLE, member)) return true;
+
         if (address(settings.uniquenessValidator) != address(0)) {
             address rootAddress = settings.uniquenessValidator.getWhitelistedRoot(member);
-            if (rootAddress == address(0)) revert NOT_WHITELISTED(member);
+            if (rootAddress == address(0)) return false;
         }
 
+        // if no members validator then anyone can join the pool
         if (address(settings.membersValidator) != address(0)) {
             if (settings.membersValidator.isMemberValid(address(this), msg.sender, member, extraData) == false) {
-                revert NOT_MEMBER(member);
+                return false;
             }
-        } else {
-            // if no members validator then only admin can add members
-            if (hasRole(DEFAULT_ADMIN_ROLE, msg.sender) == false) revert NOT_MANAGER();
         }
 
-        members[member] = true;
-        emit MemberAdded(member);
-    }
-
-    /**
-     * @dev Removes a member from the contract.
-     * @param member The address of the member to remove.
-     */
-    function removeMember(address member) external onlyRole(DEFAULT_ADMIN_ROLE) {
-        members[member] = false;
-        emit MemberRemoved(member);
+        _setupRole(MEMBER_ROLE, member);
+        return true;
     }
 
     function mintNFT(address _to, ProvableNFT.NFTData memory _nftData, bool withClaim) external onlyRole(MINTER_ROLE) {
@@ -321,7 +353,7 @@ contract DirectPaymentsPool is
     }
 
     /**
-     * @dev Receives an ERC721 token and triggers a claim for rewards.
+     * @dev Receives an ERC721 token
      * @param operator The address of the operator that sent the token.
      * @param from The address of the sender that sent the token.
      * @param tokenId The ID of the token received.
@@ -347,4 +379,27 @@ contract DirectPaymentsPool is
         if (nftData.nftType != settings.nftType) revert UNSUPPORTED_NFT();
         return DirectPaymentsPool.onERC721Received.selector;
     }
+
+    /**
+     * @dev Sets the safety limits for the pool.
+     * @param _limits The new safety limits.
+     */
+    function setPoolLimits(SafetyLimits memory _limits) public onlyRole(DEFAULT_ADMIN_ROLE) {
+        limits = _limits;
+        emit PoolLimitsChanged(_limits);
+    }
+
+    /**
+     * @dev Sets the settings for the pool.
+     * @param _settings The new pool settings.
+     */
+    function setPoolSettings(PoolSettings memory _settings) public onlyRole(DEFAULT_ADMIN_ROLE) {
+        if (_settings.nftType != settings.nftType) revert NFTTYPE_CHANGED();
+        if (_settings.manager == address(0)) revert EMPTY_MANAGER();
+
+        _revokeRole(DEFAULT_ADMIN_ROLE, settings.manager);
+        settings = _settings;
+        _setupRole(DEFAULT_ADMIN_ROLE, _settings.manager);
+        emit PoolSettingsChanged(_settings);
+    }
 }

package/contracts/DirectPayments/ProvableNFT.sol

@@ -19,12 +19,15 @@ contract ProvableNFT is ERC721Upgradeable, AccessControlUpgradeable, UUPSUpgrade
     bytes32 public constant MINTER_ROLE = keccak256(abi.encodePacked("MINTER"));
     bytes16 private constant _SYMBOLS = "0123456789abcdef";
 
+    event ProvableNftMinted(uint256 tokenId, address to, bytes32 nftDataHash);
+
     struct EventData {
         uint16 subtype;
         uint32 timestamp;
         uint256 quantity;
         string eventUri; //extra data related to event
         address[] contributers;
+        uint128 rewardOverride; //override reward defined per 1 quantity of event, pool will use this instead of its own reward if allowRewardOverride is true
     }
 
     struct NFTData {
@@ -41,7 +44,9 @@ contract ProvableNFT is ERC721Upgradeable, AccessControlUpgradeable, UUPSUpgrade
         _setupRole(DEFAULT_ADMIN_ROLE, msg.sender);
     }
 
-    function _authorizeUpgrade(address newimpl) internal virtual override onlyManager(0) {}
+    function _authorizeUpgrade(address /*newimpl*/) internal virtual override {
+        _onlyManager(0);
+    }
 
     function supportsInterface(
         bytes4 interfaceId
@@ -49,14 +54,13 @@ contract ProvableNFT is ERC721Upgradeable, AccessControlUpgradeable, UUPSUpgrade
         return super.supportsInterface(interfaceId);
     }
 
-    modifier onlyManager(uint32 nftType) {
+    function _onlyManager(uint32 nftType) internal view {
         if (
             ((nftType > 0 && hasRole(getManagerRole(nftType), msg.sender)) ||
                 hasRole(DEFAULT_ADMIN_ROLE, msg.sender)) == false
         ) {
             revert NOT_MANAGER(nftType);
         }
-        _;
     }
 
     /**
@@ -72,23 +76,24 @@ contract ProvableNFT is ERC721Upgradeable, AccessControlUpgradeable, UUPSUpgrade
      * @param _nftDataHash The hash of the NFT's data.
      * @return tokenId ID of the newly minted NFT.
      */
-    function mint(
-        address _to,
-        string memory _uri,
-        bytes32 _nftDataHash
-    ) public onlyManager(0) returns (uint256 tokenId) {
-        return _mint(_to, _uri, _nftDataHash, ""); //send false in calldata, assuming default receiver is a directpaymentspool. without nft data on chain it will fail.
+    function mint(address _to, string memory _uri, bytes32 _nftDataHash) public returns (uint256 tokenId) {
+        _onlyManager(0);
+        NFTData memory nftData;
+
+        return _mint(_to, _uri, _nftDataHash, nftData, ""); //send false in calldata, assuming default receiver is a directpaymentspool. without nft data on chain it will fail.
     }
 
     function _mint(
         address _to,
         string memory _uri,
         bytes32 _nftDataHash,
+        NFTData memory /*_nftData*/,
         bytes memory _callData
     ) internal returns (uint256 tokenId) {
         tokenId = uint256(_nftDataHash);
         nftDatas[tokenId].nftUri = _uri;
         _safeMint(_to, tokenId, _callData);
+        emit ProvableNftMinted(tokenId, _to, _nftDataHash);
     }
 
     /**
@@ -109,7 +114,8 @@ contract ProvableNFT is ERC721Upgradeable, AccessControlUpgradeable, UUPSUpgrade
         NFTData memory _nftData,
         bool _withStore,
         bytes memory _callData
-    ) external onlyManager(_nftData.nftType) returns (uint256 tokenId) {
+    ) external returns (uint256 tokenId) {
+        _onlyManager(_nftData.nftType);
         if (_nftData.nftType == 0) revert BAD_NFTTYPE();
 
         bytes32 dataHash = keccak256(abi.encode(_nftData));
@@ -123,7 +129,7 @@ contract ProvableNFT is ERC721Upgradeable, AccessControlUpgradeable, UUPSUpgrade
                 store.events.push(_nftData.events[i]);
             }
         }
-        _mint(_to, _nftData.nftUri, dataHash, _callData);
+        _mint(_to, _nftData.nftUri, dataHash, _nftData, _callData);
     }
 
     function proveNFTData(uint256 _tokenId, NFTData memory _nftData) public view returns (NFTData memory data) {

package/contracts/GoodCollective/GoodCollectiveSuperApp.sol

@@ -12,6 +12,7 @@ import "@uniswap/v3-periphery/contracts/libraries/TransferHelper.sol";
 import "@uniswap/v3-periphery/contracts/interfaces/ISwapRouter.sol";
 
 import "../DirectPayments/DirectPaymentsFactory.sol";
+import "../utils/HelperLibrary.sol";
 
 // import "hardhat/console.sol";
 
@@ -46,42 +47,18 @@ abstract contract GoodCollectiveSuperApp is SuperAppBaseFlow {
         bool isFlowUpdate
     );
 
-    //TODO: ask about "view" for beforeagreement functions
+    //TODO:
     // ask about "receiver" can it be different then app?
 
     /// @custom:oz-upgrades-unsafe-allow state-variable-immutable
     ISwapRouter public immutable swapRouter;
 
-    /**
-     * @dev A struct containing information about a token swap
-     * @param swapFrom The address of the token being swapped
-     * @param amount The amount of tokens being swapped
-     * @param minReturn The minimum amount of tokens to be received in the swap
-     * @param timestamp The deadline for the swap to occur
-     * @param path The path of tokens to take in a uniswap v3 multi-hop swap, encoded as bytes
-     */
-    struct SwapData {
-        address swapFrom;
-        uint256 amount;
-        uint256 minReturn;
-        uint256 deadline;
-        bytes path;
-    }
-
     struct SupporterData {
         uint256 contribution;
         int96 flowRate;
         uint128 lastUpdated;
     }
 
-    struct Stats {
-        uint256 netIncome; //without fees
-        uint256 totalFees;
-        uint256 lastUpdate;
-        address lastFeeRecipient;
-        int96 lastIncomeRate;
-    }
-
     ISuperToken public superToken;
 
     mapping(address => SupporterData) public supporters;
@@ -89,7 +66,7 @@ abstract contract GoodCollectiveSuperApp is SuperAppBaseFlow {
     //initialize cfaV1 variable
     CFAv1Library.InitData public cfaV1;
 
-    Stats public stats;
+    IGoodCollectiveSuperApp.Stats public stats;
 
     uint256[48] private _reserved;
 
@@ -141,13 +118,7 @@ abstract contract GoodCollectiveSuperApp is SuperAppBaseFlow {
         view
         returns (uint256 netIncome, uint256 totalFees, int96 incomeFlowRate, int96 feeRate)
     {
-        incomeFlowRate = stats.lastIncomeRate;
-        netIncome = stats.netIncome + uint96(stats.lastIncomeRate) * (block.timestamp - stats.lastUpdate);
-        feeRate = superToken.getFlowRate(address(this), stats.lastFeeRecipient);
-        totalFees =
-            stats.totalFees +
-            uint96(superToken.getFlowRate(address(this), stats.lastFeeRecipient)) *
-            (block.timestamp - stats.lastUpdate);
+        return HelperLibrary.getRealtimeStats(stats, superToken);
     }
 
     /**
@@ -197,42 +168,11 @@ abstract contract GoodCollectiveSuperApp is SuperAppBaseFlow {
      * @return Returns the context of the transaction
      */
     function handleSwap(
-        SwapData memory _customData,
+        HelperLibrary.SwapData memory _customData,
         address _sender,
         bytes memory _ctx
     ) external onlyHostOrSender(_sender) returns (bytes memory) {
-        // Transfer the tokens from the sender to this contract
-        TransferHelper.safeTransferFrom(_customData.swapFrom, _sender, address(this), _customData.amount);
-
-        // Approve the router to spend the tokens
-        TransferHelper.safeApprove(_customData.swapFrom, address(swapRouter), _customData.amount);
-
-        if (_customData.path.length > 0) {
-            // If a path is provided, execute a multi-hop swap
-            ISwapRouter.ExactInputParams memory params = ISwapRouter.ExactInputParams({
-                path: _customData.path,
-                recipient: _sender,
-                deadline: _customData.deadline,
-                amountIn: _customData.amount,
-                amountOutMinimum: _customData.minReturn
-            });
-            swapRouter.exactInput(params);
-        } else {
-            // If no path is provided, execute a single-hop swap
-            ISwapRouter.ExactInputSingleParams memory params = ISwapRouter.ExactInputSingleParams({
-                tokenIn: _customData.swapFrom,
-                tokenOut: address(superToken),
-                fee: 10000,
-                recipient: _sender,
-                deadline: _customData.deadline,
-                amountIn: _customData.amount,
-                amountOutMinimum: _customData.minReturn,
-                sqrtPriceLimitX96: 0
-            });
-
-            // Execute the swap using `exactInputSingle`
-            swapRouter.exactInputSingle(params);
-        }
+        HelperLibrary.handleSwap(swapRouter, _customData, address(superToken), _sender);
 
         // Return the context of the transaction
         return _ctx;
@@ -392,6 +332,9 @@ abstract contract GoodCollectiveSuperApp is SuperAppBaseFlow {
         TransferHelper.safeTransfer(address(superToken), recipient, fee);
     }
 
+    /**
+     * for methods that can be called via superfluid batch or directly
+     */
     modifier onlyHostOrSender(address _sender) {
         if (msg.sender != _sender && msg.sender != address(host)) revert ONLY_HOST_OR_SENDER(msg.sender);
         _;

package/contracts/GoodCollective/IGoodCollectiveSuperApp.sol

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.8.0;
+
+interface IGoodCollectiveSuperApp {
+    struct Stats {
+        uint256 netIncome; //without fees
+        uint256 totalFees;
+        uint256 lastUpdate;
+        address lastFeeRecipient;
+        int96 lastIncomeRate;
+    }
+}

package/contracts/utils/HelperLibrary.sol

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity >=0.8.0;
+
+import "@uniswap/v3-periphery/contracts/libraries/TransferHelper.sol";
+import "@uniswap/v3-periphery/contracts/interfaces/ISwapRouter.sol";
+import { ISuperToken } from "@superfluid-finance/ethereum-contracts/contracts/interfaces/superfluid/ISuperfluid.sol";
+import { SuperTokenV1Library } from "@superfluid-finance/ethereum-contracts/contracts/apps/SuperTokenV1Library.sol";
+
+import "../GoodCollective/IGoodCollectiveSuperApp.sol";
+
+library HelperLibrary {
+    using SuperTokenV1Library for ISuperToken;
+
+    /**
+     * @dev A struct containing information about a token swap
+     * @param swapFrom The address of the token being swapped
+     * @param amount The amount of tokens being swapped
+     * @param minReturn The minimum amount of tokens to be received in the swap
+     * @param timestamp The deadline for the swap to occur
+     * @param path The path of tokens to take in a uniswap v3 multi-hop swap, encoded as bytes
+     */
+    struct SwapData {
+        address swapFrom;
+        uint256 amount;
+        uint256 minReturn;
+        uint256 deadline;
+        bytes path;
+    }
+
+    function handleSwap(
+        ISwapRouter swapRouter,
+        SwapData memory _customData,
+        address outTokenIfNoPath,
+        address _sender
+    ) external {
+        // Transfer the tokens from the sender to this contract
+        TransferHelper.safeTransferFrom(_customData.swapFrom, _sender, address(this), _customData.amount);
+
+        // Approve the router to spend the tokens
+        TransferHelper.safeApprove(_customData.swapFrom, address(swapRouter), _customData.amount);
+
+        if (_customData.path.length > 0) {
+            // If a path is provided, execute a multi-hop swap
+            ISwapRouter.ExactInputParams memory params = ISwapRouter.ExactInputParams({
+                path: _customData.path,
+                recipient: _sender,
+                deadline: _customData.deadline,
+                amountIn: _customData.amount,
+                amountOutMinimum: _customData.minReturn
+            });
+            swapRouter.exactInput(params);
+        } else {
+            // If no path is provided, execute a single-hop swap
+            ISwapRouter.ExactInputSingleParams memory params = ISwapRouter.ExactInputSingleParams({
+                tokenIn: _customData.swapFrom,
+                tokenOut: outTokenIfNoPath,
+                fee: 10000,
+                recipient: _sender,
+                deadline: _customData.deadline,
+                amountIn: _customData.amount,
+                amountOutMinimum: _customData.minReturn,
+                sqrtPriceLimitX96: 0
+            });
+
+            // Execute the swap using `exactInputSingle`
+            swapRouter.exactInputSingle(params);
+        }
+    }
+
+    function getRealtimeStats(
+        IGoodCollectiveSuperApp.Stats memory stats,
+        ISuperToken superToken
+    ) external view returns (uint256 netIncome, uint256 totalFees, int96 incomeFlowRate, int96 feeRate) {
+        incomeFlowRate = stats.lastIncomeRate;
+        netIncome = stats.netIncome + uint96(stats.lastIncomeRate) * (block.timestamp - stats.lastUpdate);
+        feeRate = superToken.getFlowRate(address(this), stats.lastFeeRecipient);
+        totalFees =
+            stats.totalFees +
+            uint96(superToken.getFlowRate(address(this), stats.lastFeeRecipient)) *
+            (block.timestamp - stats.lastUpdate);
+    }
+}