@etherisc/gif-next 0.0.2-984cc08-642 → 0.0.2-989147f-853

package/contracts/distribution/DistributionService.sol

@@ -0,0 +1,351 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.19;
+
+import {IRegistry} from "../registry/IRegistry.sol";
+import {IInstance} from "../instance/IInstance.sol";
+import {InstanceAccessManager} from "../instance/InstanceAccessManager.sol";
+import {InstanceReader} from "../instance/InstanceReader.sol";
+import {ISetup} from "../instance/module/ISetup.sol";
+import {IPolicy} from "../instance/module/IPolicy.sol";
+
+import {Amount, AmountLib} from "../type/Amount.sol";
+import {NftId, NftIdLib, zeroNftId} from "../type/NftId.sol";
+import {Fee, FeeLib} from "../type/Fee.sol";
+import {PRODUCT_SERVICE_ROLE, DISTRIBUTION_OWNER_ROLE} from "../type/RoleId.sol";
+import {KEEP_STATE} from "../type/StateId.sol";
+import {ObjectType, DISTRIBUTION, INSTANCE, DISTRIBUTION, DISTRIBUTOR, PRICE} from "../type/ObjectType.sol";
+import {Version, VersionLib} from "../type/Version.sol";
+import {RoleId} from "../type/RoleId.sol";
+
+import {IVersionable} from "../shared/IVersionable.sol";
+import {Versionable} from "../shared/Versionable.sol";
+
+import {IService} from "../shared/IService.sol";
+import {Service} from "../shared/Service.sol";
+import {ComponentService} from "../shared/ComponentService.sol";
+import {InstanceService} from "../instance/InstanceService.sol";
+import {IComponent} from "../shared/IComponent.sol";
+import {IDistributionComponent} from "../distribution/IDistributionComponent.sol";
+import {IDistributionService} from "./IDistributionService.sol";
+import {IPricingService} from "../product/IPricingService.sol";
+
+import {UFixed, UFixedLib} from "../type/UFixed.sol";
+import {DistributorType, DistributorTypeLib} from "../type/DistributorType.sol";
+import {ReferralId, ReferralStatus, ReferralLib} from "../type/Referral.sol";
+import {Timestamp, TimestampLib, zeroTimestamp} from "../type/Timestamp.sol";
+import {Key32} from "../type/Key32.sol";
+import {IDistribution} from "../instance/module/IDistribution.sol";
+import {InstanceStore} from "../instance/InstanceStore.sol";
+
+
+contract DistributionService is
+    ComponentService,
+    IDistributionService
+{
+    using NftIdLib for NftId;
+    using TimestampLib for Timestamp;
+    using UFixedLib for UFixed;
+    using FeeLib for Fee;
+    using ReferralLib for ReferralId;
+
+    address internal _registryAddress;
+    
+    function _initialize(
+        address owner, 
+        bytes memory data
+    )
+        internal
+        initializer
+        virtual override
+    {
+        (
+            address registryAddress,, 
+            //address managerAddress
+            address authority
+        ) = abi.decode(data, (address, address, address));
+
+        initializeService(registryAddress, authority, owner);
+        registerInterface(type(IDistributionService).interfaceId);
+    }
+
+    function getDomain() public pure override returns(ObjectType) {
+        return DISTRIBUTION();
+    }
+
+    function register(address distributionAddress) 
+        external
+        returns(NftId distributionNftId)
+    {
+        (
+            IComponent component,
+            address owner,
+            IInstance instance,
+            NftId instanceNftId
+        ) = _checkComponentForRegistration(
+            distributionAddress,
+            DISTRIBUTION(),
+            DISTRIBUTION_OWNER_ROLE());
+
+        IRegistry.ObjectInfo memory distributionInfo = getRegistryService().registerDistribution(component, owner);
+        IDistributionComponent distribution = IDistributionComponent(distributionAddress);
+        distribution.linkToRegisteredNftId();
+        distributionNftId = distributionInfo.nftId;
+
+        instance.getInstanceStore().createDistributionSetup(distributionNftId, distribution.getSetupInfo());
+        // TODO move to distribution?
+        bytes4[][] memory selectors = new bytes4[][](2);
+        selectors[0] = new bytes4[](1);
+        // TODO check if array size should be 1 instead of 2
+        selectors[1] = new bytes4[](2);
+
+        selectors[0][0] = IDistributionComponent.setFees.selector;
+        selectors[1][0] = IDistributionComponent.processRenewal.selector;
+
+        RoleId[] memory roles = new RoleId[](2);
+        roles[0] = DISTRIBUTION_OWNER_ROLE();
+        roles[1] = PRODUCT_SERVICE_ROLE();
+
+        getInstanceService().createGifTarget(
+            instanceNftId, 
+            distributionAddress, 
+            distribution.getName(), 
+            selectors, 
+            roles);
+    }
+
+    function setFees(
+        Fee memory minDistributionOwnerFee,
+        Fee memory distributionFee
+    )
+        external
+        override
+    {
+        if (minDistributionOwnerFee.fractionalFee > distributionFee.fractionalFee) {
+            revert ErrorIDistributionServiceMinFeeTooHigh(minDistributionOwnerFee.fractionalFee.toInt(), distributionFee.fractionalFee.toInt());
+        }
+
+        (NftId distributionNftId,, IInstance instance) = _getAndVerifyCallingComponentAndInstance(DISTRIBUTION());
+        InstanceReader instanceReader = instance.getInstanceReader();
+
+        ISetup.DistributionSetupInfo memory distSetupInfo = instanceReader.getDistributionSetupInfo(distributionNftId);
+        distSetupInfo.minDistributionOwnerFee = minDistributionOwnerFee;
+        distSetupInfo.distributionFee = distributionFee;
+        
+        instance.getInstanceStore().updateDistributionSetup(distributionNftId, distSetupInfo, KEEP_STATE());
+    }
+
+    function createDistributorType(
+        string memory name,
+        UFixed minDiscountPercentage,
+        UFixed maxDiscountPercentage,
+        UFixed commissionPercentage,
+        uint32 maxReferralCount,
+        uint32 maxReferralLifetime,
+        bool allowSelfReferrals,
+        bool allowRenewals,
+        bytes memory data
+    )
+        external
+        returns (DistributorType distributorType)
+    {
+        (NftId distributionNftId,, IInstance instance) = _getAndVerifyCallingComponentAndInstance(DISTRIBUTION());
+
+        {
+            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);
+        IDistribution.DistributorTypeInfo memory info = IDistribution.DistributorTypeInfo(
+            name,
+            minDiscountPercentage,
+            maxDiscountPercentage,
+            commissionPercentage,
+            maxReferralCount,
+            maxReferralLifetime,
+            allowSelfReferrals,
+            allowRenewals,
+            data);
+
+        instance.getInstanceStore().createDistributorType(distributorType, info);
+    }
+
+
+    function createDistributor(
+        address distributor,
+        DistributorType distributorType,
+        bytes memory data
+    )
+        external 
+        virtual
+        returns (NftId distributorNftId)
+    {
+        (NftId distributionNftId,, IInstance instance) = _getAndVerifyCallingComponentAndInstance(DISTRIBUTION());
+
+        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,
+            AmountLib.zero(),
+            0);
+
+        instance.getInstanceStore().createDistributor(distributorNftId, info);
+    }
+
+    // function updateDistributorType(
+    //     NftId distributorNftId,
+    //     DistributorType distributorType,
+    //     bytes memory data
+    // )
+    //     external
+    //     virtual
+    // {
+    //     (, IInstance instance) = _getAndVerifyCallingDistribution();
+    //     InstanceReader instanceReader = instance.getInstanceReader();
+    //     IDistribution.DistributorInfo memory distributorInfo = instanceReader.getDistributorInfo(distributorNftId);
+    //     distributorInfo.distributorType = distributorType;
+    //     distributorInfo.data = data;
+    //     instance.updateDistributor(distributorNftId, distributorInfo, KEEP_STATE());
+    // }
+
+
+    function createReferral(
+        NftId distributorNftId,
+        string memory code,
+        UFixed discountPercentage,
+        uint32 maxReferrals,
+        Timestamp expiryAt,
+        bytes memory data
+    )
+        external
+        virtual
+        returns (ReferralId referralId)
+    {
+        (NftId distributionNftId,, IInstance instance) = _getAndVerifyCallingComponentAndInstance(DISTRIBUTION());
+
+        if (bytes(code).length == 0) {
+            revert ErrorIDistributionServiceInvalidReferral(code);
+        }
+        if (expiryAt.eqz()) {
+            revert ErrorIDistributionServiceExpirationInvalid(expiryAt);
+        }
+
+        InstanceReader instanceReader = instance.getInstanceReader();
+        DistributorType distributorType = instanceReader.getDistributorInfo(distributorNftId).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(
+            distributorNftId,
+            code,
+            discountPercentage,
+            maxReferrals,
+            0, // used referrals
+            expiryAt,
+            data
+        );
+
+        instance.getInstanceStore().createReferral(referralId, info);
+        return referralId;
+    }
+
+    function processSale(
+        NftId distributionNftId, // assume always of distribution type
+        ReferralId referralId,
+        IPolicy.Premium memory premium,
+        Amount transferredDistributionFeeAmount
+    )
+        external
+        virtual
+        restricted
+    {
+        bool isReferral = ! referralId.eqz();
+        bool referralValid = referralIsValid(distributionNftId, referralId);
+
+        if (isReferral && ! referralValid) {
+            revert ErrorIDistributionServiceReferralInvalid(distributionNftId, referralId);
+        }
+
+        IInstance instance = _getInstanceForDistribution(distributionNftId);
+        InstanceReader reader = instance.getInstanceReader();
+        InstanceStore store = instance.getInstanceStore();
+        IDistribution.ReferralInfo memory referralInfo = reader.getReferralInfo(referralId);
+        IDistribution.DistributorInfo memory distributorInfo = reader.getDistributorInfo(referralInfo.distributorNftId);
+        ISetup.DistributionSetupInfo memory setupInfo = reader.getDistributionSetupInfo(distributionNftId);
+        
+        Amount distributionOwnerFee = AmountLib.toAmount(premium.distributionOwnerFeeFixAmount + premium.distributionOwnerFeeVarAmount);
+        Amount commissionAmount = AmountLib.toAmount(premium.commissionAmount);
+
+        if (!(transferredDistributionFeeAmount == distributionOwnerFee + commissionAmount)) {
+            revert ErrorDistributionServiceInvalidFeeTransferred(transferredDistributionFeeAmount, distributionOwnerFee + commissionAmount);
+        }
+
+
+        if (distributionOwnerFee.gtz()) {
+            setupInfo.sumDistributionOwnerFees += distributionOwnerFee.toInt();
+            store.updateDistributionSetup(distributionNftId, setupInfo, KEEP_STATE());
+        }
+
+        if (isReferral) {
+            referralInfo.usedReferrals += 1;
+            store.updateReferral(referralId, referralInfo, KEEP_STATE());
+
+            if (commissionAmount.gtz()) {
+                distributorInfo.commissionAmount = distributorInfo.commissionAmount + commissionAmount;
+                distributorInfo.numPoliciesSold += 1;
+                store.updateDistributor(referralInfo.distributorNftId, distributorInfo, KEEP_STATE());
+            }
+        }
+    }
+
+    // TODO: zero should return false
+    function referralIsValid(NftId distributionNftId, ReferralId referralId) public view returns (bool isValid) {
+        IInstance instance = _getInstanceForDistribution(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 _getInstanceForDistribution(NftId distributionNftId)
+        internal
+        view
+        returns(IInstance instance)
+    {
+        NftId instanceNftId = getRegistry().getObjectInfo(distributionNftId).parentNftId;
+        address instanceAddress = getRegistry().getObjectInfo(instanceNftId).objectAddress;
+        return IInstance(instanceAddress);
+    }
+}

package/contracts/{instance/service → distribution}/DistributionServiceManager.sol

@@ -1,12 +1,12 @@
 // SPDX-License-Identifier: Apache-2.0
 pragma solidity ^0.8.20;
 
-import {IVersionable} from "../../shared/IVersionable.sol";
-import {ProxyManager} from "../../shared/ProxyManager.sol";
+import {IVersionable} from "../shared/IVersionable.sol";
+import {ProxyManager} from "../shared/ProxyManager.sol";
 import {DistributionService} from "./DistributionService.sol";
-import {Registry} from "../../registry/Registry.sol";
-import {RegistryService} from "../../registry/RegistryService.sol";
-import {REGISTRY} from "../../types/ObjectType.sol";
+import {Registry} from "../registry/Registry.sol";
+import {RegistryService} from "../registry/RegistryService.sol";
+import {REGISTRY} from "../type/ObjectType.sol";
 
 contract DistributionServiceManager is ProxyManager {
 
@@ -14,15 +14,18 @@ contract DistributionServiceManager is ProxyManager {
 
     /// @dev initializes proxy manager with distribution service implementation and deploys instance
     constructor(
-        address registryAddress
-    )
-        ProxyManager()
+        address authority, 
+        address registryAddress,
+        bytes32 salt
+    ) 
+        ProxyManager(registryAddress)
     {
-        DistributionService distSrv = new DistributionService();
-        bytes memory data = abi.encode(registryAddress, address(this));
-        IVersionable versionable = deploy(
+        DistributionService distSrv = new DistributionService{salt: salt}();
+        bytes memory data = abi.encode(registryAddress, address(this), authority);
+        IVersionable versionable = deployDetermenistic(
             address(distSrv), 
-            data);
+            data,
+            salt);
 
         _distributionService = DistributionService(address(versionable));
         

package/contracts/distribution/IDistributionComponent.sol

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.19;
+
+import {Fee} from "../type/Fee.sol";
+import {IComponent} from "../shared/IComponent.sol";
+import {ISetup} from "../instance/module/ISetup.sol";
+import {ReferralId, ReferralStatus} from "../type/Referral.sol";
+import {NftId} from "../type/NftId.sol";
+import {DistributorType} from "../type/DistributorType.sol";
+import {UFixed} from "../type/UFixed.sol";
+import {Timestamp} from "../type/Timestamp.sol";
+
+interface IDistributionComponent is IComponent {
+
+    event LogDistributorUpdated(address to, address caller);
+
+    function getSetupInfo() external view returns (ISetup.DistributionSetupInfo memory setupInfo);
+
+    function setFees(
+        Fee memory minDistributionOwnerFee,
+        Fee memory distributionFee
+    ) external;
+
+    function createDistributorType(
+        string memory name,
+        UFixed minDiscountPercentage,
+        UFixed maxDiscountPercentage,
+        UFixed commissionPercentage,
+        uint32 maxReferralCount,
+        uint32 maxReferralLifetime,
+        bool allowSelfReferrals,
+        bool allowRenewals,
+        bytes memory data
+    ) external returns (DistributorType distributorType);
+
+    function createDistributor(
+        address distributor,
+        DistributorType distributorType,
+        bytes memory data
+    ) external returns(NftId distributorNftId);
+
+    function updateDistributorType(
+        NftId distributorNftId,
+        DistributorType distributorType,
+        bytes memory data
+    ) external;
+
+    function calculateRenewalFeeAmount(
+        ReferralId referralId,
+        uint256 netPremiumAmount
+    ) external view returns (uint256 feeAmount);
+
+    /// @dev callback from product service when a policy is renews for a specific referralId
+    function processRenewal(
+        ReferralId referralId,
+        uint256 feeAmount
+    ) external;
+
+    function getDiscountPercentage(
+        string memory referralCode
+    ) external view returns (UFixed discountPercentage, ReferralStatus status);
+
+    function getDistributionFee() external view returns (Fee memory distibutionFee);
+
+    function getReferralId(
+        string memory referralCode
+    ) external returns (ReferralId referralId);
+
+    /// @dev returns true iff the component needs to be called when selling/renewing policis
+    function isVerifying() external view returns (bool verifying);
+}

package/contracts/distribution/IDistributionService.sol

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.19;
+
+import {Amount} from "../type/Amount.sol";
+import {NftId} from "../type/NftId.sol";
+import {Fee} from "../type/Fee.sol";
+import {IPolicy} from "../instance/module/IPolicy.sol";
+import {IService} from "../shared/IService.sol";
+import {UFixed} from "../type/UFixed.sol";
+import {DistributorType} from "../type/DistributorType.sol";
+import {ReferralId} from "../type/Referral.sol";
+import {Timestamp} from "../type/Timestamp.sol";
+
+
+interface IDistributionService is IService {
+    error ErrorDistributionServiceCallerNotRegistered(address caller);
+    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);
+    error ErrorIDistributionServiceReferralInvalid(NftId distributionNftId, ReferralId referralId);
+    error ErrorDistributionServiceInvalidFeeTransferred(Amount transferredDistributionFeeAmount, Amount expectedDistributionFeeAmount);
+
+    function setFees(
+        Fee memory minDistributionOwnerFee,
+        Fee memory distributionFee
+    ) external;
+    
+    function createDistributorType(
+        string memory name,
+        UFixed minDiscountPercentage,
+        UFixed maxDiscountPercentage,
+        UFixed commissionPercentage,
+        uint32 maxReferralCount,
+        uint32 maxReferralLifetime,
+        bool allowSelfReferrals,
+        bool allowRenewals,
+        bytes memory data
+    )
+        external
+        returns (DistributorType distributorType);
+
+    function createDistributor(
+        address distributor,
+        DistributorType distributorType,
+        bytes memory data
+    ) external returns (NftId distributorNftId);
+
+    // TODO re-enable and reorganize (service contract too large)
+    // function updateDistributorType(
+    //     NftId distributorNftId,
+    //     DistributorType distributorType,
+    //     bytes memory data
+    // ) external;
+
+    function createReferral(
+        NftId distributorNftId,
+        string memory code,
+        UFixed discountPercentage,
+        uint32 maxReferrals,
+        Timestamp expiryAt,
+        bytes memory data
+    )
+        external
+        returns (ReferralId referralId);
+
+    /// @dev callback from product service when selling a policy for a specific referralId
+    function processSale(
+        NftId distributionNftId,
+        ReferralId referralId,
+        IPolicy.Premium memory premium,
+        Amount transferredDistributionFeeAmount
+    ) external;
+
+    function referralIsValid(
+        NftId distributorNftId,
+        ReferralId referralId
+    ) external view returns (bool isValid);
+}

package/contracts/instance/BundleManager.sol

@@ -2,15 +2,15 @@
 pragma solidity ^0.8.20;
 
 import {IInstance} from "./IInstance.sol";
-import {INSTANCE} from "../types/ObjectType.sol";
+import {INSTANCE} from "../type/ObjectType.sol";
 import {InstanceReader} from "./InstanceReader.sol";
 import {IPolicy} from "../instance/module/IPolicy.sol";
 import {IRegistry} from "../registry/IRegistry.sol";
-import {LibNftIdSet} from "../types/NftIdSet.sol";
-import {NftId} from "../types/NftId.sol";
-import {TimestampLib} from "../types/Timestamp.sol";
+import {LibNftIdSet} from "../type/NftIdSet.sol";
+import {NftId} from "../type/NftId.sol";
+import {TimestampLib} from "../type/Timestamp.sol";
 
-import {ObjectManager} from "./ObjectManager.sol";
+import {ObjectManager} from "./base/ObjectManager.sol";
 
 contract BundleManager is 
     ObjectManager
@@ -22,9 +22,10 @@ contract BundleManager is
     event LogBundleManagerBundleAdded(NftId poolNftId, NftId bundleNftId);
     event LogBundleManagerBundleUnlocked(NftId poolNftId, NftId bundleNftId);
     event LogBundleManagerBundleLocked(NftId poolNftId, NftId bundleNftId);
+    event LogBundleManagerBundleClosed(NftId poolNftId, NftId bundleNftId);
 
-    error ErrorBundleManagerErrorPolicyAlreadyActivated(NftId policyNftId);
-    error ErrorBundleManagerErrorBundleLocked(NftId bundleNftId, NftId policyNftId);
+    error ErrorBundleManagerPolicyAlreadyActivated(NftId policyNftId);
+    error ErrorBundleManagerBundleLocked(NftId bundleNftId, NftId policyNftId);
     error ErrorBundleManagerPolicyWithOpenClaims(NftId policyNftId, uint256 openClaimsCount);
     error ErrorBundleManagerPolicyNotCloseable(NftId policyNftId);
     error ErrorBundleManagerBundleUnknown(NftId bundleNftId);
@@ -32,9 +33,8 @@ contract BundleManager is
 
     mapping(NftId bundleNftId => LibNftIdSet.Set policies) internal _activePolicies;
 
-    /// @dev links a policy with its bundle
-    // to link a policy it MUST NOT yet have been activated
-    // the bundle MUST be unlocked (active) for linking (underwriting) and registered with this instance
+    /// @dev links a policy to its bundle
+    // to link a policy it MUST NOT yet have been linked
     function linkPolicy(NftId policyNftId) external restricted() {
         NftId bundleNftId = _instance.getInstanceReader().getPolicyInfo(policyNftId).bundleNftId;
         // decision will likely depend on the decision what to check here and what in the service
@@ -42,7 +42,7 @@ contract BundleManager is
 
         // ensure bundle is unlocked (in active set) and registered with this instance
         if (!_isActive(poolNftId, bundleNftId)) {
-            revert ErrorBundleManagerErrorBundleLocked(bundleNftId, policyNftId);
+            revert ErrorBundleManagerBundleLocked(bundleNftId, policyNftId);
         }
 
         LibNftIdSet.add(_activePolicies[bundleNftId], policyNftId);
@@ -71,7 +71,7 @@ contract BundleManager is
     }
 
 
-    /// @dev add a new bundle to a riskpool registerd with this instance
+    /// @dev add a new bundle to a pool registerd with this instance
     // the corresponding pool is fetched via instance reader
     function add(NftId bundleNftId) external restricted() {
         NftId poolNftId = _instance.getInstanceReader().getBundleInfo(bundleNftId).poolNftId;
@@ -85,14 +85,15 @@ contract BundleManager is
         emit LogBundleManagerBundleAdded(poolNftId, bundleNftId);
     }
 
-    /// @dev unlocked (active) bundles are available to underwrite new policies
+
+    /// @dev unlocked (active) bundles are available to collateralize new policies
     function unlock(NftId bundleNftId) external restricted() {
         NftId poolNftId = _instance.getInstanceReader().getBundleInfo(bundleNftId).poolNftId;
         _activate(poolNftId, bundleNftId);
         emit LogBundleManagerBundleUnlocked(poolNftId, bundleNftId);
     }
 
-    /// @dev locked (deactivated) bundles may not underwrite any new policies
+    /// @dev locked (deactivated) bundles may not collateralize any new policies
     function lock(NftId bundleNftId) external restricted() {
         NftId poolNftId = _instance.getInstanceReader().getBundleInfo(bundleNftId).poolNftId;
         _deactivate(poolNftId, bundleNftId);