@etherisc/gif-next 0.0.2-770fd3b-604 → 0.0.2-77a1ccf-469

package/contracts/instance/service/DistributionService.sol

@@ -6,9 +6,10 @@ import {IInstance} from "../../instance/IInstance.sol";
 import {InstanceAccessManager} from "../InstanceAccessManager.sol";
 import {InstanceReader} from "../../instance/InstanceReader.sol";
 import {ISetup} from "../../instance/module/ISetup.sol";
+import {IPolicy} from "../module/IPolicy.sol";
 
-import {NftId, NftIdLib} from "../../types/NftId.sol";
-import {Fee} from "../../types/Fee.sol";
+import {NftId, NftIdLib, zeroNftId} from "../../types/NftId.sol";
+import {Fee, FeeLib} from "../../types/Fee.sol";
 import {DISTRIBUTION_OWNER_ROLE} from "../../types/RoleId.sol";
 import {KEEP_STATE} from "../../types/StateId.sol";
 import {ObjectType, DISTRIBUTION, INSTANCE, DISTRIBUTION, DISTRIBUTOR} from "../../types/ObjectType.sol";
@@ -25,7 +26,7 @@ import {IComponent} from "../../components/IComponent.sol";
 import {IDistributionComponent} from "../../components/IDistributionComponent.sol";
 import {IDistributionService} from "./IDistributionService.sol";
 
-import {UFixed} from "../../types/UFixed.sol";
+import {UFixed, UFixedLib} from "../../types/UFixed.sol";
 import {DistributorType, DistributorTypeLib} from "../../types/DistributorType.sol";
 import {ReferralId, ReferralStatus, ReferralLib} from "../../types/Referral.sol";
 import {Timestamp, TimestampLib, zeroTimestamp} from "../../types/Timestamp.sol";
@@ -38,6 +39,9 @@ contract DistributionService is
     IDistributionService
 {
     using NftIdLib for NftId;
+    using TimestampLib for Timestamp;
+    using UFixedLib for UFixed;
+    using FeeLib for Fee;
 
     address internal _registryAddress;
     
@@ -87,16 +91,22 @@ contract DistributionService is
     }
 
     function setFees(
+        Fee memory minDistributionOwnerFee,
         Fee memory distributionFee
     )
         external
         override
     {
+        if (minDistributionOwnerFee.fractionalFee > distributionFee.fractionalFee) {
+            revert ErrorIDistributionServiceMinFeeTooHigh(minDistributionOwnerFee.fractionalFee.toInt(), distributionFee.fractionalFee.toInt());
+        }
+
         (IRegistry.ObjectInfo memory info , IInstance instance) = _getAndVerifyComponentInfoAndInstance(DISTRIBUTION());
         InstanceReader instanceReader = instance.getInstanceReader();
         NftId distributionNftId = info.nftId;
 
         ISetup.DistributionSetupInfo memory distSetupInfo = instanceReader.getDistributionSetupInfo(distributionNftId);
+        distSetupInfo.minDistributionOwnerFee = minDistributionOwnerFee;
         distSetupInfo.distributionFee = distributionFee;
         
         instance.updateDistributionSetup(distributionNftId, distSetupInfo, KEEP_STATE());
@@ -117,6 +127,16 @@ contract DistributionService is
         returns (DistributorType distributorType)
     {
         (,NftId distributionNftId, IInstance instance) = _getAndVerifyCallingDistribution();
+
+        {
+            ISetup.DistributionSetupInfo memory setupInfo = instance.getInstanceReader().getDistributionSetupInfo(distributionNftId);
+            UFixed variableFeesPartsTotal = setupInfo.minDistributionOwnerFee.fractionalFee.add(commissionPercentage);
+            UFixed maxDiscountPercentageLimit = setupInfo.distributionFee.fractionalFee.sub(variableFeesPartsTotal);
+            if (maxDiscountPercentage.gt(maxDiscountPercentageLimit)) {
+                revert ErrorIDistributionServiceMaxDiscountTooHigh(maxDiscountPercentage.toInt(), maxDiscountPercentageLimit.toInt());
+            }
+        }
+        
         distributorType = DistributorTypeLib.toDistributorType(distributionNftId, name);
         Key32 key32 = distributorType.toKey32();
 
@@ -144,18 +164,23 @@ contract DistributionService is
     {
         (, NftId distributionNftId, IInstance instance) = _getAndVerifyCallingDistribution();
 
-        // FIXME: add this function
-        // distributorNftId = _registryService.registerDistributor(
-        //     distributionNftId,
-        //     DISTRIBUTOR(),
-        //     true, // distribution module is intercepting
-        //     distributor,
-        //     "");
+        distributorNftId = getRegistryService().registerDistributor(
+            IRegistry.ObjectInfo(
+                zeroNftId(), 
+                distributionNftId,
+                DISTRIBUTOR(),
+                true, // intercepting property for bundles is defined on pool
+                address(0),
+                distributor,
+                ""
+            ));
 
         IDistribution.DistributorInfo memory info = IDistribution.DistributorInfo(
             distributorType,
             true, // active
-            data);
+            data,
+            0,
+            0);
 
         instance.createDistributor(distributorNftId, info);
     }
@@ -167,13 +192,11 @@ contract DistributionService is
     ) external virtual
     {
         (,, IInstance instance) = _getAndVerifyCallingDistribution();
-
-        IDistribution.DistributorInfo memory info = IDistribution.DistributorInfo(
-            distributorType,
-            true, // active
-            data);
-
-        instance.updateDistributor(distributorNftId, info, KEEP_STATE());
+        InstanceReader instanceReader = instance.getInstanceReader();
+        IDistribution.DistributorInfo memory distributorInfo = instanceReader.getDistributorInfo(distributorNftId);
+        distributorInfo.distributorType = distributorType;
+        distributorInfo.data = data;
+        instance.updateDistributor(distributorNftId, distributorInfo, KEEP_STATE());
     }
 
 
@@ -190,8 +213,31 @@ contract DistributionService is
         returns (ReferralId referralId)
     {
         (,NftId distributionNftId, IInstance instance) = _getAndVerifyCallingDistribution();
-        require(bytes(code).length > 0, "ERROR:DSV-030:CODE_INVALID");
-        require(expiryAt > zeroTimestamp(), "ERROR:DSV-031:EXPIRY_AT_ZERO");
+
+        if (bytes(code).length == 0) {
+            revert ErrorIDistributionServiceInvalidReferral(code);
+        }
+        if (expiryAt.eqz()) {
+            revert ErrorIDistributionServiceExpirationInvalid(expiryAt);
+        }
+
+        InstanceReader instanceReader = instance.getInstanceReader();
+        IDistribution.DistributorInfo memory distributorInfo = instanceReader.getDistributorInfo(distributorNftId);
+        DistributorType distributorType = distributorInfo.distributorType;
+        IDistribution.DistributorTypeInfo memory distributorTypeData = instanceReader.getDistributorTypeInfo(distributorType);
+
+        if (distributorTypeData.maxReferralCount < maxReferrals) {
+            revert ErrorIDistributionServiceMaxReferralsExceeded(distributorTypeData.maxReferralCount);
+        }
+        if (distributorTypeData.minDiscountPercentage > discountPercentage) {
+            revert ErrorIDistributionServiceDiscountTooLow(distributorTypeData.minDiscountPercentage.toInt(), discountPercentage.toInt());
+        }
+        if (distributorTypeData.maxDiscountPercentage < discountPercentage) {
+            revert ErrorIDistributionServiceDiscountTooHigh(distributorTypeData.maxDiscountPercentage.toInt(), discountPercentage.toInt());
+        }
+        if (expiryAt.toInt() - TimestampLib.blockTimestamp().toInt() > distributorTypeData.maxReferralLifetime) {
+            revert ErrorIDistributionServiceExpiryTooLong(distributorTypeData.maxReferralLifetime, expiryAt.toInt());
+        }
 
         referralId = ReferralLib.toReferralId(distributionNftId, code);
         IDistribution.ReferralInfo memory info = IDistribution.ReferralInfo(
@@ -215,19 +261,71 @@ contract DistributionService is
         external
         virtual
     {
+        // TODO: fetch referral
+        // TODO: update referral usage numbers
+        // TODO: update bookkeeping
+        // TODO: calculate commission for distributor
+        // TODO: calculate fee for distribution owner
+        // TODO: updates sum of commission per distributor -> DistributorInfo
+        // TODO: updates sum of fee per distribution owner
         revert("NOT_IMPLEMENTED_YET");
     }
 
     function calculateFeeAmount(
+        NftId distributionNftId,
         ReferralId referralId,
-        uint256 premiumAmount
+        IPolicy.Premium memory premium
     )
         external
         virtual
         view 
-        returns (uint256 feeAmount)
+        returns (IPolicy.Premium memory finalPremium)
     {
-        revert("NOT_IMPLEMENTED_YET");
+        (, IInstance instance) = _getAndVerifyDistribution(distributionNftId);
+        InstanceReader reader = instance.getInstanceReader();
+        
+        // first calculate all fixed and variable fees for the distribution - this will defined the fullPremium
+        ISetup.DistributionSetupInfo memory setupInfo = reader.getDistributionSetupInfo(distributionNftId);
+        Fee memory distributionFee = setupInfo.distributionFee;
+        Fee memory minDistributionOwnerFee = setupInfo.minDistributionOwnerFee;
+        uint256 distributionFeeVarAmount = (UFixedLib.toUFixed(premium.netPremiumAmount) * distributionFee.fractionalFee).toInt();
+        premium.distributionFeeVarAmount = distributionFeeVarAmount;
+        premium.fullPremiumAmount += distributionFeeVarAmount;
+            
+        // if the referral is not valid, then the distribution owner gets everything
+        if (! referralIsValid(distributionNftId, referralId)) {
+            premium.distributionOwnerFeeFixAmount = premium.distributionFeeFixAmount;
+            premium.distributionOwnerFeeVarAmount = premium.distributionFeeVarAmount;
+            premium.premiumAmount = premium.fullPremiumAmount;
+            return premium;
+        }
+
+        // if the referral is valid, the the commission and discount are calculated based in the full premium
+        // the remaing amount goes to the distribution owner
+        IDistribution.ReferralInfo memory referralInfo = reader.getReferralInfo(referralId);
+        IDistribution.DistributorInfo memory distributorInfo = reader.getDistributorInfo(referralInfo.distributorNftId);
+        IDistribution.DistributorTypeInfo memory distributorTypeInfo = reader.getDistributorTypeInfo(distributorInfo.distributorType);
+
+        uint256 commissionAmount = UFixedLib.toUFixed(premium.netPremiumAmount).mul(distributorTypeInfo.commissionPercentage).toInt();
+        premium.commissionAmount = commissionAmount;
+        premium.discountAmount = UFixedLib.toUFixed(premium.fullPremiumAmount).mul(referralInfo.discountPercentage).toInt();
+        premium.distributionOwnerFeeFixAmount = minDistributionOwnerFee.fixedFee;
+        premium.distributionOwnerFeeVarAmount = distributionFeeVarAmount - commissionAmount - premium.discountAmount;
+        premium.premiumAmount = premium.fullPremiumAmount - premium.discountAmount;
+        
+        return premium; 
+    }
+
+    function referralIsValid(NftId distributionNftId, ReferralId referralId) public view returns (bool isValid) {
+        (address distributionAddress, IInstance instance) = _getAndVerifyDistribution(distributionNftId);
+        IDistribution.ReferralInfo memory info = instance.getInstanceReader().getReferralInfo(referralId);
+
+        if (info.distributorNftId.eqz()) {
+            return false;
+        }
+
+        isValid = info.expiryAt.eqz() || (info.expiryAt.gtz() && TimestampLib.blockTimestamp() <= info.expiryAt);
+        isValid = isValid && info.usedReferrals < info.maxReferrals;
     }
 
     function _getAndVerifyCallingDistribution()
@@ -247,7 +345,25 @@ contract DistributionService is
             instance
         ) = _getAndVerifyCaller();
 
-        require(objectType == DISTRIBUTION(), "ERROR:PRS-031:CALLER_NOT_DISTRUBUTION");
+        if(objectType != DISTRIBUTION()) {
+            revert ErrorIDistributionServiceCallerNotDistributor(msg.sender);
+        }
+    }
+
+    function _getAndVerifyDistribution(NftId distributionNftId)
+        internal
+        view
+        returns(
+            address distributionAddress,
+            IInstance instance
+        )
+    {
+        IRegistry.ObjectInfo memory info = getRegistry().getObjectInfo(distributionNftId);
+        IRegistry.ObjectInfo memory parentInfo = getRegistry().getObjectInfo(info.parentNftId);
+        if (parentInfo.objectType != INSTANCE()) {
+            revert ErrorIDistributionServiceParentNftIdNotInstance(distributionNftId, info.parentNftId);
+        }
+        instance = IInstance(parentInfo.objectAddress);
     }
 
     function _getAndVerifyCaller()
@@ -262,12 +378,16 @@ contract DistributionService is
     {
         objectAddress = msg.sender;
         objectNftId = getRegistry().getNftId(objectAddress);
-        require(objectNftId.gtz(), "ERROR:SRV-030:CALLER_UNKNOWN");
+        if ( objectNftId.eqz()) {
+            revert ErrorIServiceCallerUnknown(objectAddress);
+        }
         IRegistry.ObjectInfo memory info = getRegistry().getObjectInfo(objectNftId);
         objectType = info.objectType;
 
         IRegistry.ObjectInfo memory parentInfo = getRegistry().getObjectInfo(info.parentNftId);
-        require(parentInfo.objectType == INSTANCE(), "ERROR:SRV-031:PARENT_NOT_INSTANCE");
+        if (parentInfo.objectType != INSTANCE()) {
+            revert ErrorIDistributionServiceParentNftIdNotInstance(objectNftId, info.parentNftId);
+        }
         instance = IInstance(parentInfo.objectAddress);
     }
 

package/contracts/instance/service/DistributionServiceManager.sol

@@ -16,7 +16,7 @@ contract DistributionServiceManager is ProxyManager {
     constructor(
         address registryAddress
     )
-        ProxyManager()
+        ProxyManager(registryAddress)
     {
         DistributionService distSrv = new DistributionService();
         bytes memory data = abi.encode(registryAddress, address(this));

package/contracts/instance/service/IApplicationService.sol

@@ -1,12 +1,14 @@
 // SPDX-License-Identifier: Apache-2.0
 pragma solidity ^0.8.19;
 
+import {IPolicy} from "../module/IPolicy.sol";
 import {IRisk} from "../module/IRisk.sol";
 import {IService} from "../../shared/IService.sol";
 
 import {NftId} from "../../types/NftId.sol";
 import {ReferralId} from "../../types/Referral.sol";
 import {RiskId} from "../../types/RiskId.sol";
+import {Seconds} from "../../types/Seconds.sol";
 import {StateId} from "../../types/StateId.sol";
 import {Timestamp} from "../../types/Timestamp.sol";
 import {UFixed} from "../../types/UFixed.sol";
@@ -17,23 +19,24 @@ import {Fee} from "../../types/Fee.sol";
 interface IApplicationService is IService {
     
     error IApplicationServicePolicyNotApplied(NftId applicationNftId);
+    error IApplicationServiceBundlePoolMismatch(NftId bundleNftId, NftId bundlePoolNftId, NftId poolNftId);
 
     /// @dev creates a new application based on the specified attributes
     /// may only be called by a product component
     function create(
         address applicationOwner,
         RiskId riskId,
+        uint256 sumInsuredAmount,
+        Seconds lifetime,
         NftId bundleNftId,
         ReferralId referralId,
-        uint256 sumInsuredAmount,
-        uint256 lifetime,
         bytes memory applicationData
     ) external returns (NftId applicationNftId);
 
     /// @dev updates application attributes
     /// may only be called while the application is in applied state
     /// may only be called by the referenced product related to applicationNftId
-    function ajust(
+    function adjust(
         NftId applicationNftId,
         RiskId riskId,
         NftId bundleNftId,
@@ -63,9 +66,10 @@ interface IApplicationService is IService {
     /// @dev calculates the premium amount for the specified attributes
     /// also returns the various fee components involved with creating a policy
     function calculatePremium(
+        NftId productNftId,
         RiskId riskId,
         uint256 sumInsuredAmount,
-        uint256 lifetime,
+        Seconds lifetime,
         bytes memory applicationData,
         NftId bundleNftId,
         ReferralId referralId
@@ -73,10 +77,6 @@ interface IApplicationService is IService {
         external
         view
         returns (
-            uint256 premiumAmount,
-            uint256 distributionFeeAmount,
-            uint256 productFeeAmount,
-            uint256 poolFeeAmount,
-            uint256 bundleFeeAmount
+            IPolicy.Premium memory premium
         );
 }

package/contracts/instance/service/IBundleService.sol

@@ -3,10 +3,11 @@ pragma solidity ^0.8.19;
 
 import {NftId} from "../../types/NftId.sol";
 import {Fee} from "../../types/Fee.sol";
-import {StateId} from "../../types/StateId.sol";
 import {IService} from "../../shared/IService.sol";
 import {IBundle} from "../module/IBundle.sol";
 import {IInstance} from "../../instance/IInstance.sol";
+import {Seconds} from "../../types/Seconds.sol";
+import {StateId} from "../../types/StateId.sol";
 
 interface IBundleService is IService {
     error ErrorIBundleServiceInsufficientAllowance(address bundleOwner, address tokenHandlerAddress, uint256 amount);
@@ -15,7 +16,7 @@ interface IBundleService is IService {
         address owner,
         Fee memory fee, 
         uint256 amount,
-        uint256 lifetime, 
+        Seconds lifetime, 
         bytes calldata filter
     ) external returns(NftId bundleNftId);
 

package/contracts/instance/service/IClaimService.sol

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.19;
+
+import {IRisk} from "../module/IRisk.sol";
+import {IService} from "../../shared/IService.sol";
+
+import {ClaimId} from "../../types/ClaimId.sol";
+import {PayoutId} from "../../types/PayoutId.sol";
+import {NftId} from "../../types/NftId.sol";
+import {ReferralId} from "../../types/Referral.sol";
+import {RiskId} from "../../types/RiskId.sol";
+import {StateId} from "../../types/StateId.sol";
+import {Timestamp} from "../../types/Timestamp.sol";
+import {UFixed} from "../../types/UFixed.sol";
+import {Fee} from "../../types/Fee.sol";
+
+/// @dev gif service responsible for creating claims and payouts
+/// only product components may call transaction functions
+interface IClaimService is
+    IService
+{
+
+    /// @dev create a new claim for the specified policy
+    /// function can only be called by product, policy needs to match with calling product
+    function createClaim(
+        NftId policyNftId, 
+        uint256 claimAmount,
+        bytes memory claimData
+    ) external returns (ClaimId);
+
+    /// @dev confirms the specified claim and fixes the final claim amount
+    /// function can only be called by product, policy needs to match with calling product
+    function confirmClaim(NftId policyNftId, ClaimId claimId, uint256 claimAmount) external;
+
+    /// @dev declares the claim as invalid, no payout(s) will be made
+    /// function can only be called by product, policy needs to match with calling product
+    function declineClaim(NftId policyNftId, ClaimId claimId) external;
+
+    /// @dev closes the claim
+    /// a claim may only be closed once all existing payouts have been executed and the sum of the paid out amounts has reached the claim amount
+    /// function can only be called by product, policy needs to match with calling product
+    function closeClaim(NftId policyNftId, ClaimId claimId) external; 
+
+    /// @dev create a new payout for the specified policy and claim
+    /// function can only be called by product, policy needs to match with calling product
+    function createPayout(
+        NftId policyNftId, 
+        ClaimId claimId,
+        uint256 payoutAmount,
+        bytes calldata payoutData
+    ) external returns (PayoutId payoutId);
+
+    /// @dev callback function to confirm transfer of payout token to beneficiary
+    /// allows claim service to update claims/payout book keeping
+    /// only pool service can confirm executed payout
+    function payoutExecuted(
+        NftId policyNftId, 
+        PayoutId payoutId
+    ) external;
+
+}

package/contracts/instance/service/IDistributionService.sol

@@ -3,6 +3,7 @@ pragma solidity ^0.8.19;
 
 import {NftId} from "../../types/NftId.sol";
 import {Fee} from "../../types/Fee.sol";
+import {IPolicy} from "../module/IPolicy.sol";
 import {IService} from "../../shared/IService.sol";
 import {UFixed} from "../../types/UFixed.sol";
 import {DistributorType} from "../../types/DistributorType.sol";
@@ -11,7 +12,21 @@ import {Timestamp} from "../../types/Timestamp.sol";
 
 
 interface IDistributionService is IService {
+    error ErrorIDistributionServiceParentNftIdNotInstance(NftId nftId, NftId parentNftId);
+    error ErrorIDistributionServiceCallerNotDistributor(address caller);
+    error ErrorIDistributionServiceInvalidReferralId(ReferralId referralId);
+    error ErrorIDistributionServiceMaxReferralsExceeded(uint256 maxReferrals);
+    error ErrorIDistributionServiceDiscountTooLow(uint256 minDiscountPercentage, uint256 discountPercentage);
+    error ErrorIDistributionServiceDiscountTooHigh(uint256 maxDiscountPercentage, uint256 discountPercentage);
+    error ErrorIDistributionServiceExpiryTooLong(uint256 maxReferralLifetime, uint256 expiryAt);
+    error ErrorIDistributionServiceInvalidReferral(string code);
+    error ErrorIDistributionServiceExpirationInvalid(Timestamp expiryAt);
+    error ErrorIDistributionServiceCommissionTooHigh(uint256 commissionPercentage, uint256 maxCommissionPercentage);
+    error ErrorIDistributionServiceMinFeeTooHigh(uint256 minFee, uint256 limit);
+    error ErrorIDistributionServiceMaxDiscountTooHigh(uint256 maxDiscountPercentage, uint256 limit);
+
     function setFees(
+        Fee memory minDistributionOwnerFee,
         Fee memory distributionFee
     ) external;
     
@@ -59,7 +74,13 @@ interface IDistributionService is IService {
     ) external;
 
     function calculateFeeAmount(
+        NftId distributionNftId,
         ReferralId referralId,
-        uint256 premiumAmount
-    ) external view returns (uint256 feeAmount);
+        IPolicy.Premium memory premium
+    ) external view returns (IPolicy.Premium memory finalPremium);
+
+    function referralIsValid(
+        NftId distributorNftId,
+        ReferralId referralId
+    ) external view returns (bool isValid);
 }

package/contracts/instance/service/IPolicyService.sol

@@ -7,6 +7,7 @@ import {IService} from "../../shared/IService.sol";
 import {NftId} from "../../types/NftId.sol";
 import {ReferralId} from "../../types/Referral.sol";
 import {RiskId} from "../../types/RiskId.sol";
+import {Seconds} from "../../types/Seconds.sol";
 import {StateId} from "../../types/StateId.sol";
 import {Timestamp} from "../../types/Timestamp.sol";
 import {UFixed} from "../../types/UFixed.sol";
@@ -22,42 +23,15 @@ interface IPolicyService is IService {
     error ErrorIPolicyServicePremiumNotFullyPaid(NftId policyNftId, uint256 premiumAmount, uint256 premiumPaidAmount);
     error ErrorIPolicyServiceOpenClaims(NftId policyNftId, uint16 openClaimsCount);
     error ErrorIPolicyServicePolicyHasNotExpired(NftId policyNftId, Timestamp expiredAt);
-    
-    function calculatePremium(
-        RiskId riskId,
-        uint256 sumInsuredAmount,
-        uint256 lifetime,
-        bytes memory applicationData,
-        NftId bundleNftId,
-        ReferralId referralId
-    )
-        external
-        view
-        returns (
-            uint256 premiumAmount,
-            uint256 productFeeAmount,
-            uint256 poolFeeAmount,
-            uint256 bundleFeeAmount,
-            uint256 distributionFeeAmount
-        );
-
-
-    function createApplication(
-        address applicationOwner,
-        RiskId riskId,
-        uint256 sumInsuredAmount,
-        uint256 lifetime,
-        bytes memory applicationData,
-        NftId bundleNftId,
-        ReferralId referralId
-    ) external returns (NftId nftId);
 
     /// @dev declines an application represented by {policyNftId}
     /// an application can only be declined in applied state
     /// only the related product may decline an application
     function decline(NftId policyNftId) external;
 
-    /// @dev underwrites the policy represented by {policyNftId}.
+    /// @dev underwrites the policy represented by {policyNftId}
+    /// sets the policy state to underwritten
+    /// may set the policy state to activated and set the activation date
     /// optionally collects premiums and activates the policy.
     /// - premium payment is only attempted if requirePremiumPayment is set to true
     /// - activation is only done if activateAt is a non-zero timestamp
@@ -69,17 +43,25 @@ interface IPolicyService is IService {
         Timestamp activateAt
     ) external;
 
+    /// @dev collects the premium token for the specified policy
     function collectPremium(NftId policyNftId, Timestamp activateAt) external;
 
+    /// @dev activates the specified policy and sets the activation date in the policy metadata
+    /// to activate a policy it needs to be in underwritten state
     function activate(NftId policyNftId, Timestamp activateAt) external;
 
-    function close(NftId nftId) external;
+    /// @dev expires the specified policy and sets the expiry date in the policy metadata
+    /// to expire a policy it must be in active state, policies may be expired even when the predefined expiry date is still in the future
+    /// a policy can only be closed when it has been expired. in addition, it must not have any open claims
+    /// this function can only be called by a product. the policy needs to match with the calling product
+    function expire(NftId policyNftId) external;
 
-    // function createClaim(uint256 nftId, uint256 claimAmount) external;
-    // function confirmClaim(uint256 nftId, uint256 claimId, uint256 claimAmount) external;
-    // function declineClaim(uint256 nftId, uint256 claimId) external;
-    // function closeClaim(uint256 nftId, uint256 claimId) external; // TODO payoutClaim() -> implicit close when payed out in full
+    /// @dev closes the specified policy and sets the closed data in the policy metadata
+    /// a policy can only be closed when it has been expired. in addition, it must not have any open claims
+    /// this function can only be called by a product. the policy needs to match with the calling product
+    function close(NftId policyNftId) external;
 
+    // TODO move function to pool service
     function calculateRequiredCollateral(
         UFixed collateralizationLevel, 
         uint256 sumInsuredAmount