@etherisc/gif-next 0.0.2-e802d97-251 → 0.0.2-e81f152-917

package/contracts/shared/InstanceLinkedComponent.sol

@@ -6,13 +6,14 @@ import {IAccessManaged} from "@openzeppelin/contracts/access/manager/IAccessMana
 import {IERC20Metadata} from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
 import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
 
+import {Amount} from "../type/Amount.sol";
 import {Component} from "./Component.sol";
 import {IComponentService} from "./IComponentService.sol";
 import {IInstanceLinkedComponent} from "./IInstanceLinkedComponent.sol";
+import {IAuthorization} from "../authorization/IAuthorization.sol";
 import {IComponents} from "../instance/module/IComponents.sol";
 import {IInstanceService} from "../instance/IInstanceService.sol";
 import {IInstance} from "../instance/IInstance.sol";
-import {InstanceAdmin} from "../instance/InstanceAdmin.sol";
 import {InstanceReader} from "../instance/InstanceReader.sol";
 import {IRegistry} from "../registry/IRegistry.sol";
 import {NftId} from "../type/NftId.sol";
@@ -35,6 +36,39 @@ abstract contract InstanceLinkedComponent is
     struct InstanceLinkedComponentStorage {
         IInstance _instance; // instance for this component
         InstanceReader _instanceReader; // instance reader for this component
+        IAuthorization _initialAuthorization;
+        IComponentService _componentService;
+    }
+
+    function lock() external onlyOwner {
+        IInstanceService(_getServiceAddress(INSTANCE())).setComponentLocked(true);
+    }
+    
+    function unlock() external onlyOwner {
+        IInstanceService(_getServiceAddress(INSTANCE())).setComponentLocked(false);
+    }
+
+    function getInstance() public view override returns (IInstance instance) {
+        return _getInstanceLinkedComponentStorage()._instance;
+    }
+
+    function getProductNftId() public view override returns (NftId productNftId) {
+        return getComponentInfo().productNftId;
+    }
+
+    function getAuthorization() external view returns (IAuthorization authorization) {
+        return _getInstanceLinkedComponentStorage()._initialAuthorization;
+    }
+
+    /// @inheritdoc IInstanceLinkedComponent
+    function withdrawFees(Amount amount)
+        external
+        virtual
+        onlyOwner()
+        restricted()
+        returns (Amount withdrawnAmount)
+    {
+        return _withdrawFees(amount);
     }
 
     function _getInstanceLinkedComponentStorage() private pure returns (InstanceLinkedComponentStorage storage $) {
@@ -43,18 +77,19 @@ abstract contract InstanceLinkedComponent is
         }
     }
 
-    function initializeInstanceLinkedComponent(
+    function _initializeInstanceLinkedComponent(
         address registry,
         NftId instanceNftId,
         string memory name,
         address token,
         ObjectType componentType,
+        IAuthorization authorization,
         bool isInterceptor,
         address initialOwner,
         bytes memory registryData, // writeonly data that will saved in the object info record of the registry
         bytes memory componentData // data that will saved with the component info in the instance store
     )
-        public
+        internal
         virtual
         onlyInitializing()
     {
@@ -82,6 +117,8 @@ abstract contract InstanceLinkedComponent is
 
         // set component state
         $._instanceReader = $._instance.getInstanceReader();
+        $._initialAuthorization = authorization;
+        $._componentService = IComponentService(_getServiceAddress(COMPONENT())); 
 
         registerInterface(type(IAccessManaged).interfaceId);
         registerInterface(type(IInstanceLinkedComponent).interfaceId);
@@ -93,22 +130,6 @@ abstract contract InstanceLinkedComponent is
         IComponentService(_getServiceAddress(COMPONENT())).setWallet(newWallet);
     }
 
-    function lock() external onlyOwner {
-        IInstanceService(_getServiceAddress(INSTANCE())).setComponentLocked(true);
-    }
-    
-    function unlock() external onlyOwner {
-        IInstanceService(_getServiceAddress(INSTANCE())).setComponentLocked(false);
-    }
-
-    function getInstance() public view override returns (IInstance instance) {
-        return _getInstanceLinkedComponentStorage()._instance;
-    }
-
-    function getProductNftId() public view override returns (NftId productNftId) {
-        return getComponentInfo().productNftId;
-    }
-
 
     function _getComponentInfo() internal virtual override view returns (IComponents.ComponentInfo memory info) {
         NftId componentNftId = getRegistry().getNftId(address(this));
@@ -134,6 +155,13 @@ abstract contract InstanceLinkedComponent is
         return _getInstanceLinkedComponentStorage()._instanceReader;
     }
 
+    function _withdrawFees(Amount amount)
+        internal
+        returns (Amount withdrawnAmount)
+    {
+        return _getInstanceLinkedComponentStorage()._componentService.withdrawFees(amount);
+    }
+
 
     /// @dev returns the service address for the specified domain
     /// gets address via lookup from registry using the major version form the linked instance

package/contracts/shared/KeyValueStore.sol

@@ -11,7 +11,7 @@ import {Timestamp, TimestampLib} from "../type/Timestamp.sol";
 import {Lifecycle} from "./Lifecycle.sol";
 import {IKeyValueStore} from "./IKeyValueStore.sol";
 
-contract KeyValueStore is
+abstract contract KeyValueStore is
     Lifecycle, 
     IKeyValueStore
 {
@@ -34,8 +34,12 @@ contract KeyValueStore is
             revert ErrorKeyValueStoreAlreadyCreated(key32, objectType);
         }
 
+        if(!hasLifecycle(objectType)) {
+            revert ErrorKeyValueStoreNoLifecycle(objectType);
+        }
+
         Blocknumber blocknumber = blockBlocknumber();
-        StateId initialState = hasLifecycle(objectType) ? getInitialState(objectType) : ACTIVE();
+        StateId initialState = getInitialState(objectType);
 
         // set metadata
         metadata.objectType = objectType;

package/contracts/shared/Lifecycle.sol

@@ -1,15 +1,11 @@
 // SPDX-License-Identifier: Apache-2.0
 pragma solidity ^0.8.20;
 
-import {Initializable} from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol"; 
-
-import {NftId} from "../type/NftId.sol";
-import {ObjectType, COMPONENT, BUNDLE, POLICY, REQUEST, RISK, CLAIM, PAYOUT} from "../type/ObjectType.sol";
-import {StateId, ACTIVE, PAUSED, ARCHIVED, CLOSED, APPLIED, COLLATERALIZED, REVOKED, SUBMITTED, CONFIRMED, DECLINED, EXPECTED, PAID, FULFILLED, FAILED, CANCELLED} from "../type/StateId.sol";
+import {ObjectType} from "../type/ObjectType.sol";
+import {StateId, zeroStateId} from "../type/StateId.sol";
 import {ILifecycle} from "./ILifecycle.sol";
 
-contract Lifecycle is
-    Initializable,
+abstract contract Lifecycle is
     ILifecycle
 {
     mapping(ObjectType objectType => StateId initialState)
@@ -18,16 +14,17 @@ contract Lifecycle is
     mapping(ObjectType objectType => mapping(StateId stateFrom => mapping(StateId stateTo => bool isValid)))
         private _isValidTransition;
 
-    function initializeLifecycle()
-        public
-        onlyInitializing
-    {
-        _setupBundleLifecycle();
-        _setupComponentLifecycle();
-        _setupPolicyLifecycle();
-        _setupClaimAndPayoutLifecycle();
-        _setupRiskLifecycle();
-        _setupRequestLifecycle();
+    /// @dev child class must implement and CALL setup func at deployment/initializaton time
+    function _setupLifecycle() internal virtual;
+
+    function setInitialState(ObjectType ttype, StateId state) internal virtual {
+        assert(_initialState[ttype] == zeroStateId());
+        _initialState[ttype] = state;
+    }
+
+    function setStateTransition(ObjectType ttype, StateId oldState, StateId newState) internal virtual {
+        assert(_isValidTransition[ttype][oldState][newState] == false);
+        _isValidTransition[ttype][oldState][newState] = true;
     }
 
     function hasLifecycle(
@@ -59,9 +56,9 @@ contract Lifecycle is
         public
         view
     {
-        // return if no life cycle support
+        // revert if no life cycle support
         if (_initialState[objectType].eqz()) {
-            return;
+            revert ErrorNoLifecycle(objectType);
         }
 
         // enforce valid state transition
@@ -77,54 +74,4 @@ contract Lifecycle is
     ) public view returns (bool) {
         return _isValidTransition[objectType][fromId][toId];
     }
-
-    function _setupComponentLifecycle() internal {
-        _initialState[COMPONENT()] = ACTIVE();
-        _isValidTransition[COMPONENT()][ACTIVE()][PAUSED()] = true;
-        _isValidTransition[COMPONENT()][PAUSED()][ACTIVE()] = true;
-        _isValidTransition[COMPONENT()][PAUSED()][ARCHIVED()] = true;
-    }
-
-    function _setupBundleLifecycle() internal {
-        _initialState[BUNDLE()] = ACTIVE();
-        _isValidTransition[BUNDLE()][ACTIVE()][PAUSED()] = true;
-        _isValidTransition[BUNDLE()][ACTIVE()][CLOSED()] = true;
-        _isValidTransition[BUNDLE()][PAUSED()][ACTIVE()] = true;
-        _isValidTransition[BUNDLE()][PAUSED()][CLOSED()] = true;
-    }
-
-    function _setupPolicyLifecycle() internal {
-        _initialState[POLICY()] = APPLIED();
-        _isValidTransition[POLICY()][APPLIED()][REVOKED()] = true;
-        _isValidTransition[POLICY()][APPLIED()][DECLINED()] = true;
-        _isValidTransition[POLICY()][APPLIED()][COLLATERALIZED()] = true;
-        _isValidTransition[POLICY()][APPLIED()][ACTIVE()] = true;
-        _isValidTransition[POLICY()][COLLATERALIZED()][ACTIVE()] = true;
-        _isValidTransition[POLICY()][ACTIVE()][CLOSED()] = true;
-    }
-
-    function _setupClaimAndPayoutLifecycle() internal {
-        _initialState[CLAIM()] = SUBMITTED();
-        _isValidTransition[CLAIM()][SUBMITTED()][CONFIRMED()] = true;
-        _isValidTransition[CLAIM()][SUBMITTED()][DECLINED()] = true;
-        _isValidTransition[CLAIM()][CONFIRMED()][CLOSED()] = true;
-
-        _initialState[PAYOUT()] = EXPECTED();
-        _isValidTransition[PAYOUT()][EXPECTED()][PAID()] = true;
-    }
-
-    function _setupRiskLifecycle() internal {
-        _initialState[RISK()] = ACTIVE();
-        _isValidTransition[RISK()][ACTIVE()][PAUSED()] = true;
-        _isValidTransition[RISK()][PAUSED()][ACTIVE()] = true;
-        _isValidTransition[RISK()][PAUSED()][ARCHIVED()] = true;
-    }
-
-    function _setupRequestLifecycle() internal {
-        _initialState[REQUEST()] = ACTIVE();
-        _isValidTransition[REQUEST()][ACTIVE()][FULFILLED()] = true;
-        _isValidTransition[REQUEST()][ACTIVE()][FAILED()] = true;
-        _isValidTransition[REQUEST()][FAILED()][FULFILLED()] = true;
-        _isValidTransition[REQUEST()][ACTIVE()][CANCELLED()] = true;
-    }
 }

package/contracts/shared/{NftIdSetManager.sol → NftIdSet.sol}

@@ -4,7 +4,7 @@ pragma solidity ^0.8.20;
 import {LibNftIdSet} from "../type/NftIdSet.sol";
 import {NftId} from "../type/NftId.sol";
 
-contract NftIdSetManager {
+contract NftIdSet {
 
     error ErrorNftIdSetManagerNotOwner(address owner, address sender);
     error ErrorNftIdSetManagerOwnerAlreadySet(address owner);

package/contracts/shared/NftOwnable.sol

@@ -1,13 +1,13 @@
 // SPDX-License-Identifier: Apache-2.0
 pragma solidity ^0.8.20;
 
-import {ERC165} from "./ERC165.sol";
+import {InitializableERC165} from "./InitializableERC165.sol";
 import {INftOwnable} from "./INftOwnable.sol";
 import {NftId} from "../type/NftId.sol";
 import {RegistryLinked} from "./RegistryLinked.sol";
 
 contract NftOwnable is
-    ERC165,
+    InitializableERC165,
     RegistryLinked,
     INftOwnable
 {

package/contracts/shared/PolicyHolder.sol

@@ -1,22 +1,19 @@
 // SPDX-License-Identifier: Apache-2.0
 pragma solidity ^0.8.20;
 
-import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 import {IERC721Receiver} from "@openzeppelin/contracts/token/ERC721/IERC721Receiver.sol";
-import {Initializable} from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol"; 
 
 import {Amount} from "../type/Amount.sol";
 import {ClaimId} from "../type/ClaimId.sol";
-import {ERC165} from "./ERC165.sol";
+import {InitializableERC165} from "./InitializableERC165.sol";
 import {IPolicyHolder} from "./IPolicyHolder.sol";
 import {NftId} from "../type/NftId.sol";
 import {PayoutId, PayoutIdLib} from "../type/PayoutId.sol";
 import {RegistryLinked} from "./RegistryLinked.sol";
-import {IRegistry} from "../registry/IRegistry.sol";
 
 /// @dev template implementation for IPolicyHolder
 contract PolicyHolder is
-    ERC165,
+    InitializableERC165,
     RegistryLinked, // TODO need upgradeable version
     IPolicyHolder
 {

package/contracts/shared/Service.sol

@@ -4,17 +4,14 @@ pragma solidity ^0.8.20;
 import {AccessManagedUpgradeable} from "@openzeppelin/contracts-upgradeable/access/manager/AccessManagedUpgradeable.sol";
 import {IAccessManaged} from "@openzeppelin/contracts/access/manager/IAccessManaged.sol";
 
-import {ObjectType, REGISTRY, SERVICE} from "../type/ObjectType.sol";
-import {NftId} from "../type/NftId.sol";
-import {Version, VersionPart, VersionLib, VersionPartLib} from "../type/Version.sol";
-
-import {Versionable} from "./Versionable.sol";
+import {IRegistry} from "../registry/IRegistry.sol";
 import {IService} from "./IService.sol";
-import {IVersionable} from "./IVersionable.sol";
-import {Versionable} from "./Versionable.sol";
+import {IVersionable} from "../upgradeability/IVersionable.sol";
+import {ObjectType, REGISTRY, SERVICE} from "../type/ObjectType.sol";
 import {Registerable} from "./Registerable.sol";
-
-import {IRegistry} from "../registry/IRegistry.sol";
+import {RoleId, RoleIdLib} from "../type/RoleId.sol";
+import {Version, VersionLib, VersionPartLib} from "../type/Version.sol";
+import {Versionable} from "../upgradeability/Versionable.sol";
 
 
 /// @dev service base contract
@@ -27,15 +24,6 @@ abstract contract Service is
 
     uint8 private constant GIF_MAJOR_VERSION = 3;
 
-    // from Versionable
-    function getVersion()
-        public 
-        pure 
-        virtual override (IVersionable, Versionable)
-        returns(Version)
-    {
-        return VersionLib.toVersion(GIF_MAJOR_VERSION,0,0);
-    }
 
     function initializeService(
         address registry, 
@@ -58,9 +46,7 @@ abstract contract Service is
         if(authority != address(0)) {
             __AccessManaged_init(authority);
         } else {
-            address registryServiceAddress = getRegistry().getServiceAddress(
-                REGISTRY(), 
-                VersionPartLib.toVersionPart(GIF_MAJOR_VERSION));
+            address registryServiceAddress = _getServiceAddress(REGISTRY());
 
             // copy authority from already registered registry services
             __AccessManaged_init(IAccessManaged(registryServiceAddress).authority());
@@ -70,8 +56,27 @@ abstract contract Service is
         registerInterface(type(IService).interfaceId);
     }
 
+    function getDomain() external virtual pure returns(ObjectType serviceDomain) {
+        return _getDomain();
+    }
+
+    function getRoleId() external virtual pure returns(RoleId serviceRoleId) {
+        return RoleIdLib.roleForTypeAndVersion(_getDomain(), VersionPartLib.toVersionPart(GIF_MAJOR_VERSION));
+    }
+
+    // from Versionable
+    function getVersion()
+        public 
+        pure 
+        virtual override (IVersionable, Versionable)
+        returns(Version)
+    {
+        return VersionLib.toVersion(GIF_MAJOR_VERSION,0,0);
+    }
+
+    function _getDomain() internal virtual pure returns (ObjectType);
 
     function _getServiceAddress(ObjectType domain) internal view returns (address) {
-        return getRegistry().getServiceAddress(domain, getVersion().toMajorPart());
+        return getRegistry().getServiceAddress(domain, VersionPartLib.toVersionPart(GIF_MAJOR_VERSION));
     }
 }

package/contracts/shared/TokenHandler.sol

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 pragma solidity ^0.8.20;
 
+import {AccessManaged} from "@openzeppelin/contracts/access/manager/AccessManaged.sol";
 import {IERC20Metadata} from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
 import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
 
@@ -9,50 +10,130 @@ import {Amount} from "../type/Amount.sol";
 /// @dev token specific transfer helper
 /// a default token contract is provided via contract constructor
 /// relies internally on oz SafeERC20.safeTransferFrom
-contract TokenHandler {
+contract TokenHandler is AccessManaged {
+    error ErrorTokenHandlerAmountIsZero();
+    error ErrorTokenHandlerBalanceTooLow(address token, address from, uint256 balance, uint256 expectedBalance);
+    error ErrorTokenHandlerAllowanceTooSmall(address token, address from, address spender, uint256 allowance, uint256 expectedAllowance);
+    error ErrorTokenHandlerRecipientWalletsMustBeDistinct(address to, address to2, address to3);
+    
+    event LogTokenHandlerTokenTransfer(address token, address from, address to, uint256 amountTransferred);
+
     IERC20Metadata private _token;
 
-    constructor(address token) {
+    constructor(address token, address initialAuthority) AccessManaged(initialAuthority) {
         _token = IERC20Metadata(token);
     }
 
-    /// @dev transfer amount default tokens 
-    function transfer(
+    /// @dev returns the default token defined for this TokenHandler
+    function getToken()
+        external
+        view 
+        returns (IERC20Metadata)
+    {
+        return _token;
+    }
+    
+    /// @dev collect tokens from outside of the gif and transfer them to one wallet within the scope of gif.
+    /// This method also checks balance and allowance and makes sure the amount is greater than zero.
+    function collectTokens(
         address from,
         address to,
         Amount amount
     )
         external
+        restricted()
     {
-        SafeERC20.safeTransferFrom(
-            _token, 
-            from, 
-            to, 
-            amount.toInt());
+        _transfer(from, to, amount, true);
     }
 
-    /// @dev transfer amount of the specified token
-    function safeTransferFrom(
-        address token,
+    /// @dev collect tokens from outside of the gif and transfer them to three distinct wallets within the scope of gif
+    /// This method also checks balance and allowance and makes sure the amount is greater than zero.
+    function collectTokensToThreeRecipients( 
+        address from,
+        address to,
+        Amount amount,
+        address to2,
+        Amount amount2,
+        address to3,
+        Amount amount3
+    )
+        external
+        restricted()
+    {
+        if (to == to2 || to == to3 || to2 == to3) {
+            revert ErrorTokenHandlerRecipientWalletsMustBeDistinct(to, to2, to3);
+        }
+
+        _checkPreconditions(from, amount + amount2 + amount3);
+
+        if (amount.gtz()) {
+            _transfer(from, to, amount, false);
+        }
+        if (amount2.gtz()) {
+            _transfer(from, to2, amount2, false);
+        }
+        if (amount3.gtz()) {
+            _transfer(from, to3, amount3, false);
+        }
+    }
+
+    /// @dev distribute tokens from a wallet within the scope of gif to an external address.
+    /// This method also checks balance and allowance and makes sure the amount is greater than zero.
+    function distributeTokens(
         address from,
         address to,
         Amount amount
     )
         external
+        restricted()
+    {
+        _transfer(from, to, amount, true);
+    }
+
+    function _transfer(
+        address from,
+        address to,
+        Amount amount,
+        bool checkPreconditions
+    )
+        internal
     {
+        if (checkPreconditions) {
+            // check amount > 0, balance >= amount and allowance >= amount
+            _checkPreconditions(from, amount);
+        }
+
+        // transfer the tokens
+        emit LogTokenHandlerTokenTransfer(address(_token), from, to, amount.toInt());
         SafeERC20.safeTransferFrom(
-            IERC20Metadata(token), 
+            _token, 
             from, 
             to, 
             amount.toInt());
     }
 
-    /// @dev returns the default token defined for this TokenHandler
-    function getToken()
-        external
-        view 
-        returns (IERC20Metadata)
+    function _checkPreconditions(
+        address from,
+        Amount amount
+    ) 
+        internal
+        view
     {
-        return _token;
+        // amount must be greater than zero
+        if (amount.eqz()) {
+            revert ErrorTokenHandlerAmountIsZero();
+        }
+
+        // balance must be >= amount
+        uint256 balance = _token.balanceOf(from);
+        if (balance < amount.toInt()) {
+            revert ErrorTokenHandlerBalanceTooLow(address(_token), from, balance, amount.toInt());
+        }
+
+        // allowance must be >= amount
+        uint256 allowance = _token.allowance(from, address(this));
+        if (allowance < amount.toInt()) {
+            revert ErrorTokenHandlerAllowanceTooSmall(address(_token), from, address(this), allowance, amount.toInt());
+        }
     }
 }

package/contracts/staking/IStaking.sol

@@ -3,9 +3,8 @@ pragma solidity ^0.8.20;
 
 import {Amount} from "../type/Amount.sol";
 import {IComponent} from "../shared/IComponent.sol";
-import {IVersionable} from "../shared/IVersionable.sol";
+import {IVersionable} from "../upgradeability/IVersionable.sol";
 import {NftId} from "../type/NftId.sol";
-import {NftIdSetManager} from "../shared/NftIdSetManager.sol";
 import {ObjectType} from "../type/ObjectType.sol";
 import {Seconds} from "../type/Seconds.sol";
 import {StakingReader} from "./StakingReader.sol";

package/contracts/staking/IStakingService.sol

@@ -44,6 +44,13 @@ interface IStakingService is IService
     error ErrorStakingServiceDipBalanceInsufficient(NftId targetNftId, uint256 amount, uint256 balance);
     error ErrorStakingServiceDipAllowanceInsufficient(NftId targetNftId, address tokenHandler, uint256 amount, uint256 allowance);
 
+    /// @dev Set the protocol reward rate stake locking period to the specified duration.
+    /// Permissioned: only staking owner
+    // TODO implement
+    // function setProtocolRewardRate(UFixed rewardRate) external;
+    // function setProtocolLockingPeriod(Seconds lockingPeriod) external;
+    // TODO also make sure that protocol rewards can be refilled and withdrawn
+
     /// @dev creates/registers an on-chain instance staking target.
     /// function granted to instance service
     function createInstanceTarget(
@@ -52,21 +59,25 @@ interface IStakingService is IService
         UFixed initialRewardRate
     ) external;
 
-    /// @dev set the stake locking period to the specified duration.
-    /// permissioned: only the owner of the specified target may set the locking period
-    function setLockingPeriod(NftId targetNftId, Seconds lockingPeriod) external;
+    /// @dev Set the instance stake locking period to the specified duration.
+    /// Permissioned: Only owner of the specified target.
+    function setInstanceLockingPeriod(NftId instanceNftId, Seconds lockingPeriod) external;
+
+    /// @dev Set the instance reward rate to the specified value.
+    /// Permissioned: Only owner of the specified target.
+    function setInstanceRewardRate(NftId instanceNftId, UFixed rewardRate) external;
 
-    /// @dev set the reward rate to the specified value
-    /// permissioned: only the owner of the specified target may set the locking period
-    function setRewardRate(NftId targetNftId, UFixed rewardRate) external;
+    /// @dev (Re)fills the staking reward reserves for the specified target using the dips provided by the reward provider.
+    /// unpermissioned: anybody may fill up staking reward reserves
+    function refillInstanceRewardReserves(NftId instanceNftId, address rewardProvider, Amount dipAmount) external returns (Amount newBalance);
 
-    /// @dev (re)fills the staking reward reserves for the specified target
+    /// @dev (Re)fills the staking reward reserves for the specified target using the dips provided by the sender
     /// unpermissioned: anybody may fill up staking reward reserves
-    function refillRewardReserves(NftId targetNftId, Amount dipAmount) external returns (Amount newBalance);
+    function refillRewardReservesBySender(NftId targetNftId, Amount dipAmount) external returns (Amount newBalance);
 
-    /// @dev defunds the staking reward reserves for the specified target
-    /// permissioned: only the target owner may call this function
-    function withdrawRewardReserves(NftId targetNftId, Amount dipAmount) external returns (Amount newBalance);
+    /// @dev Defunds the staking reward reserves for the specified target
+    /// Permissioned: only the target owner may call this function
+    function withdrawInstanceRewardReserves(NftId instanceNftId, Amount dipAmount) external returns (Amount newBalance);
 
     /// @dev create a new stake with amount DIP to the specified target
     /// returns the id of the newly minted stake nft