@etherisc/gif-next 0.0.2-e0ff180-766 → 0.0.2-e14821a-976

package/contracts/distribution/DistributionService.sol

@@ -0,0 +1,465 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.20;
+
+import {IAccountingService} from "../accounting/IAccountingService.sol";
+import {IComponentService} from "../shared/IComponentService.sol";
+import {IDistribution} from "../instance/module/IDistribution.sol";
+import {IDistributionService} from "./IDistributionService.sol";
+import {IInstance} from "../instance/IInstance.sol";
+import {IInstanceService} from "../instance/IInstanceService.sol";
+import {IRegistry} from "../registry/IRegistry.sol";
+import {IRegistryService} from "../registry/IRegistryService.sol";
+import {IComponents} from "../instance/module/IComponents.sol";
+import {IPolicy} from "../instance/module/IPolicy.sol";
+
+import {Amount, AmountLib} from "../type/Amount.sol";
+import {ContractLib} from "../shared/ContractLib.sol";
+import {DistributorType, DistributorTypeLib} from "../type/DistributorType.sol";
+import {NftId, NftIdLib} from "../type/NftId.sol";
+import {KEEP_STATE} from "../type/StateId.sol";
+import {ObjectType, ACCOUNTING, COMPONENT, DISTRIBUTION, INSTANCE, DISTRIBUTION, DISTRIBUTOR, REGISTRY} from "../type/ObjectType.sol";
+import {InstanceReader} from "../instance/InstanceReader.sol";
+import {InstanceStore} from "../instance/InstanceStore.sol";
+// TODO PoolLib feels wrong, should likely go in a component type independent lib
+import {PoolLib} from "../pool/PoolLib.sol";
+import {ReferralId, ReferralStatus, ReferralLib, REFERRAL_OK, REFERRAL_ERROR_UNKNOWN, REFERRAL_ERROR_EXPIRED, REFERRAL_ERROR_EXHAUSTED} from "../type/Referral.sol";
+import {Seconds} from "../type/Seconds.sol";
+import {Service} from "../shared/Service.sol";
+import {Timestamp, TimestampLib} from "../type/Timestamp.sol";
+import {UFixed, UFixedLib} from "../type/UFixed.sol";
+
+
+contract DistributionService is
+    Service,
+    IDistributionService
+{
+    // TODO make all storage slot constants private?
+    // keccak256(abi.encode(uint256(keccak256("etherisc.gif.DistributionService@3.0.0")) - 1)) & ~bytes32(uint256(0xff));
+    bytes32 public constant DISTRIBUTION_SERVICE_STORAGE_LOCATION_V3_0 = 0xabfd9ba715b54654d8f0ef9f71a2076277bb1487677f05f4685d1bba29453600;
+
+    struct DistributionServiceStorage {
+        IAccountingService _accountingService;
+        IComponentService _componentService;
+        IInstanceService _instanceService;
+        IRegistryService _registryService;
+    }
+
+
+    function _initialize(
+        address owner, 
+        bytes memory data
+    )
+        internal
+        virtual override
+        initializer()
+    {
+        (
+            address authority,
+            address registry
+        ) = abi.decode(data, (address, address));
+
+        __Service_init(authority, registry, owner);
+
+        DistributionServiceStorage storage $ = _getDistributionServiceStorage();
+        $._accountingService = IAccountingService(_getServiceAddress(ACCOUNTING()));
+        $._componentService = IComponentService(_getServiceAddress(COMPONENT()));
+        $._instanceService = IInstanceService(_getServiceAddress(INSTANCE()));
+        $._registryService = IRegistryService(_getServiceAddress(REGISTRY()));
+
+        _registerInterface(type(IDistributionService).interfaceId);
+    }
+
+
+    function createDistributorType(
+        string memory name,
+        UFixed minDiscountPercentage,
+        UFixed maxDiscountPercentage,
+        UFixed commissionPercentage,
+        uint32 maxReferralCount,
+        Seconds maxReferralLifetime,
+        bool allowSelfReferrals,
+        bool allowRenewals,
+        bytes memory data
+    )
+        external
+        virtual
+        restricted()
+        returns (DistributorType distributorType)
+    {
+        (NftId distributionNftId, IInstance instance) = _getAndVerifyActiveDistribution();
+
+        {
+            NftId productNftId = getRegistry().getParentNftId(distributionNftId);
+            IComponents.FeeInfo memory feeInfo = instance.getInstanceReader().getFeeInfo(productNftId);
+
+            UFixed variableDistributionFees = feeInfo.distributionFee.fractionalFee;
+            UFixed variableFeesPartsTotal = feeInfo.minDistributionOwnerFee.fractionalFee + commissionPercentage;
+
+            if (variableFeesPartsTotal > variableDistributionFees) {
+                revert ErrorDistributionServiceVariableFeesTooHight(variableDistributionFees.toInt1000(), variableFeesPartsTotal.toInt1000());
+            }
+            UFixed maxDiscountPercentageLimit = variableDistributionFees - variableFeesPartsTotal;
+
+            if (maxDiscountPercentage > maxDiscountPercentageLimit) {
+                revert ErrorDistributionServiceMaxDiscountTooHigh(maxDiscountPercentage.toInt1000(), maxDiscountPercentageLimit.toInt1000());
+            }
+        }
+
+        distributorType = DistributorTypeLib.toDistributorType(distributionNftId, name);
+        IDistribution.DistributorTypeInfo memory info = IDistribution.DistributorTypeInfo({
+            name: name,
+            distributionNftId: distributionNftId,
+            minDiscountPercentage: minDiscountPercentage,
+            maxDiscountPercentage: maxDiscountPercentage,
+            commissionPercentage: commissionPercentage,
+            maxReferralCount: maxReferralCount,
+            maxReferralLifetime: maxReferralLifetime,
+            allowSelfReferrals: allowSelfReferrals,
+            allowRenewals: allowRenewals,
+            data: data});
+
+        instance.getInstanceStore().createDistributorType(distributorType, info);
+
+        emit LogDistributionServiceDistributorTypeCreated(distributionNftId, name);
+    }
+
+
+    function createDistributor(
+        address distributor,
+        DistributorType distributorType,
+        bytes memory data
+    )
+        external 
+        virtual
+        restricted()
+        returns (NftId distributorNftId)
+    {
+        (NftId distributionNftId, IInstance instance) = _getAndVerifyActiveDistribution();
+        _checkDistributionType(instance.getInstanceReader(), distributorType, distributionNftId);
+
+        DistributionServiceStorage storage $ = _getDistributionServiceStorage();
+        distributorNftId = $._registryService.registerDistributor(
+            IRegistry.ObjectInfo(
+                NftIdLib.zero(), 
+                distributionNftId,
+                DISTRIBUTOR(),
+                true, // intercepting property for bundles is defined on pool
+                address(0),
+                distributor,
+                ""
+            ));
+
+        IDistribution.DistributorInfo memory info = IDistribution.DistributorInfo({
+            distributorType: distributorType,
+            active: true, 
+            numPoliciesSold: 0,
+            data: data});
+
+        instance.getInstanceStore().createDistributor(distributorNftId, info);
+
+        emit LogDistributionServiceDistributorCreated(distributionNftId, distributorNftId, distributorType, distributor);
+    }
+
+    function changeDistributorType(
+        NftId distributorNftId,
+        DistributorType newDistributorType,
+        bytes memory data
+    )
+        external
+        virtual
+        restricted()
+    {
+        _checkNftType(distributorNftId, DISTRIBUTOR());
+        (NftId distributionNftId, IInstance instance) = _getAndVerifyActiveDistribution();
+        _checkDistributionType(instance.getInstanceReader(), newDistributorType, distributionNftId);
+        
+        IDistribution.DistributorInfo memory distributorInfo = instance.getInstanceReader().getDistributorInfo(distributorNftId);
+        DistributorType oldDistributorType = distributorInfo.distributorType;
+        distributorInfo.distributorType = newDistributorType;
+        distributorInfo.data = data;
+        instance.getInstanceStore().updateDistributor(distributorNftId, distributorInfo, KEEP_STATE());
+
+        emit LogDistributionServiceDistributorTypeChanged(distributorNftId, oldDistributorType, newDistributorType);
+    }
+
+
+    function createReferral(
+        NftId distributorNftId,
+        string memory code,
+        UFixed discountPercentage,
+        uint32 maxReferrals,
+        Timestamp expiryAt,
+        bytes memory data
+    )
+        external
+        virtual
+        restricted()
+        onlyNftOfType(distributorNftId, DISTRIBUTOR())
+        returns (ReferralId referralId)
+    {
+        (NftId distributionNftId, IInstance instance) = _getAndVerifyActiveDistribution();
+
+        if (bytes(code).length == 0) {
+            revert ErrorDistributionServiceInvalidReferral();
+        }
+        if (expiryAt.eqz() || expiryAt < TimestampLib.current()) {
+            revert ErrorDistributionServiceExpirationInvalid(expiryAt);
+        }
+
+        NftId distributorDistributionNftId = getRegistry().getParentNftId(distributorNftId);
+        if (distributorDistributionNftId != distributionNftId) {
+            revert ErrorDistributionServiceDistributorDistributionMismatch(distributorNftId, distributorDistributionNftId, distributionNftId);
+        }
+
+        {
+            InstanceReader instanceReader = instance.getInstanceReader();
+            DistributorType distributorType = instanceReader.getDistributorInfo(distributorNftId).distributorType;
+            IDistribution.DistributorTypeInfo memory distributorTypeData = instanceReader.getDistributorTypeInfo(distributorType);
+
+            if (distributorTypeData.maxReferralCount < maxReferrals) {
+                revert ErrorDistributionServiceMaxReferralsExceeded(distributorTypeData.maxReferralCount, maxReferrals);
+            }
+            if (distributorTypeData.minDiscountPercentage > discountPercentage) {
+                revert ErrorDistributionServiceDiscountTooLow(distributorTypeData.minDiscountPercentage, discountPercentage);
+            }
+            if (distributorTypeData.maxDiscountPercentage < discountPercentage) {
+                revert ErrorDistributionServiceDiscountTooHigh(distributorTypeData.maxDiscountPercentage, discountPercentage);
+            }
+            if (expiryAt.toInt() - TimestampLib.current().toInt() > distributorTypeData.maxReferralLifetime.toInt()) {
+                revert ErrorDistributionServiceExpiryTooLong(distributorTypeData.maxReferralLifetime, expiryAt);
+            }
+        }
+
+        {
+            referralId = ReferralLib.toReferralId(distributionNftId, code);
+            IDistribution.ReferralInfo memory info = IDistribution.ReferralInfo({
+                distributionNftId: distributionNftId,
+                distributorNftId: distributorNftId,
+                referralCode: code,
+                discountPercentage: discountPercentage,
+                maxReferrals: maxReferrals,
+                usedReferrals: 0, 
+                expiryAt: expiryAt,
+                data: data
+            });
+
+            instance.getInstanceStore().createReferral(referralId, info);
+
+            emit LogDistributionServiceReferralCreated(distributionNftId, distributorNftId, referralId, code);
+        }
+    }
+
+    /// @inheritdoc IDistributionService
+    function processReferral(
+        NftId distributionNftId, 
+        ReferralId referralId
+    ) 
+        external
+        virtual
+        restricted()
+        onlyNftOfType(distributionNftId, DISTRIBUTION())
+    {
+        if (referralIsValid(distributionNftId, referralId)) {
+            IInstance instance = IInstance(ContractLib.getInstanceForComponent(getRegistry(), distributionNftId));
+
+            // update book keeping for referral info
+            IDistribution.ReferralInfo memory referralInfo = instance.getInstanceReader().getReferralInfo(referralId);
+            referralInfo.usedReferrals += 1;
+            instance.getInstanceStore().updateReferral(referralId, referralInfo, KEEP_STATE());
+
+            emit LogDistributionServiceReferralProcessed(distributionNftId, referralInfo.distributorNftId, referralId, referralInfo.usedReferrals);
+        }
+    }
+
+    function processSale(
+        NftId distributionNftId, // assume always of distribution type
+        ReferralId referralId,
+        IPolicy.PremiumInfo memory premium
+    )
+        external
+        virtual
+        restricted()
+        onlyNftOfType(distributionNftId, DISTRIBUTION())
+    {
+        IInstance instance = IInstance(ContractLib.getInstanceForComponent(getRegistry(), distributionNftId));
+        InstanceReader reader = instance.getInstanceReader();
+        InstanceStore store = instance.getInstanceStore();
+
+        // get distribution owner fee amount
+        Amount distributionOwnerFee = premium.distributionOwnerFeeFixAmount + premium.distributionOwnerFeeVarAmount;
+
+        DistributionServiceStorage storage $ = _getDistributionServiceStorage();
+
+        // update referral/distributor info if applicable
+        if (referralIsValid(distributionNftId, referralId)) {
+
+            // increase distribution balance by commission amount and distribution owner fee
+            Amount commissionAmount = premium.commissionAmount;
+            $._accountingService.increaseDistributionBalance(store, distributionNftId, commissionAmount, distributionOwnerFee);
+
+            // update book keeping for referral info
+            IDistribution.ReferralInfo memory referralInfo = reader.getReferralInfo(referralId);
+
+            $._accountingService.increaseDistributorBalance(store, referralInfo.distributorNftId, AmountLib.zero(), commissionAmount);
+
+            // update book keeping for distributor info
+            IDistribution.DistributorInfo memory distributorInfo = reader.getDistributorInfo(referralInfo.distributorNftId);
+            distributorInfo.numPoliciesSold += 1;
+            store.updateDistributor(referralInfo.distributorNftId, distributorInfo, KEEP_STATE());
+        } else {
+            // increase distribution balance by distribution owner fee
+            $._accountingService.increaseDistributionBalance(store, distributionNftId, AmountLib.zero(), distributionOwnerFee);
+        }
+
+        emit LogDistributionServiceSaleProcessed(distributionNftId, referralId);
+    }
+
+    /// @inheritdoc IDistributionService
+    function withdrawCommission(NftId distributorNftId, Amount amount) 
+        public 
+        virtual
+        restricted()
+        onlyNftOfType(distributorNftId, DISTRIBUTOR())
+        returns (Amount withdrawnAmount) 
+    {
+        (NftId distributionNftId, IInstance instance) = _getAndVerifyActiveDistribution();
+        InstanceReader reader = instance.getInstanceReader();
+        
+        IComponents.ComponentInfo memory distributionInfo = reader.getComponentInfo(distributionNftId);
+        // address distributionWallet = distributionInfo.tokenHandler.getWallet();
+        
+        Amount commissionAmount = reader.getFeeAmount(distributorNftId);
+        
+        // determine withdrawn amount
+        withdrawnAmount = amount;
+        if (withdrawnAmount >= AmountLib.max()) {
+            withdrawnAmount = commissionAmount;
+        } else {
+            if (withdrawnAmount > commissionAmount) {
+                revert ErrorDistributionServiceCommissionWithdrawAmountExceedsLimit(withdrawnAmount, commissionAmount);
+            }
+        }
+
+        // decrease fee counters by withdrawnAmount and update distributor info
+        {
+            DistributionServiceStorage storage $ = _getDistributionServiceStorage();
+            InstanceStore store = instance.getInstanceStore();
+            // decrease fee counter for distribution balance
+            $._accountingService.decreaseDistributionBalance(store, distributionNftId, withdrawnAmount, AmountLib.zero());
+            // decrease fee counter for distributor fee
+            $._accountingService.decreaseDistributorBalance(store, distributorNftId, AmountLib.zero(), withdrawnAmount);
+        }
+
+        // transfer amount to distributor
+        {
+            address distributor = getRegistry().ownerOf(distributorNftId);
+            emit LogDistributionServiceCommissionWithdrawn(distributorNftId, distributor, address(distributionInfo.tokenHandler.TOKEN()), withdrawnAmount);
+            distributionInfo.tokenHandler.pushToken(distributor, withdrawnAmount);
+        }
+    }
+
+    function referralIsValid(NftId distributionNftId, ReferralId referralId) 
+        public 
+        virtual
+        view 
+        onlyNftOfType(distributionNftId, DISTRIBUTION())
+        returns (bool isValid) 
+    {
+        if (distributionNftId.eqz() || referralId.eqz()) {
+            return false;
+        }
+
+        IInstance instance = IInstance(ContractLib.getInstanceForComponent(getRegistry(), distributionNftId));
+        IDistribution.ReferralInfo memory info = instance.getInstanceReader().getReferralInfo(referralId);
+
+        if (info.distributorNftId.eqz()) {
+            return false;
+        }
+
+        // ensure the referral was created on the same distribution
+        if(info.distributionNftId != distributionNftId) {
+            revert ErrorDistributionServiceReferralDistributionMismatch(referralId, info.distributionNftId, distributionNftId);
+        }
+
+        isValid = info.expiryAt.eqz() || (info.expiryAt.gtz() && TimestampLib.current() <= info.expiryAt);
+        isValid = isValid && info.usedReferrals < info.maxReferrals;
+    }
+
+
+    function getDiscountPercentage(
+        InstanceReader instanceReader,
+        ReferralId referralId
+    )
+        external
+        virtual
+        view 
+        returns (
+            UFixed discountPercentage, 
+            ReferralStatus status
+        )
+    { 
+        IDistribution.ReferralInfo memory info = instanceReader.getReferralInfo(
+            referralId);        
+
+        if (info.expiryAt.eqz()) {
+            return (
+                UFixedLib.zero(),
+                REFERRAL_ERROR_UNKNOWN());
+        }
+
+        if (info.expiryAt < TimestampLib.current()) {
+            return (
+                UFixedLib.zero(),
+                REFERRAL_ERROR_EXPIRED());
+        }
+
+        if (info.usedReferrals >= info.maxReferrals) {
+            return (
+                UFixedLib.zero(),
+                REFERRAL_ERROR_EXHAUSTED());
+        }
+
+        return (
+            info.discountPercentage,
+            REFERRAL_OK()
+        );
+
+    }
+
+
+    function _checkDistributionType(InstanceReader instanceReader, DistributorType distributorType, NftId expectedDistributionNftId) 
+        internal
+        view 
+    {
+        // enfore distributor type belongs to the calling distribution
+        NftId distributorTypeDistributionNftId = instanceReader.getDistributorTypeInfo(distributorType).distributionNftId;
+
+        if (distributorTypeDistributionNftId != expectedDistributionNftId) {
+            revert ErrorDistributionServiceDistributorTypeDistributionMismatch(distributorType, distributorTypeDistributionNftId, expectedDistributionNftId);
+        }
+    }
+
+
+
+    function _getAndVerifyActiveDistribution()
+        internal
+        virtual
+        view
+        returns (
+            NftId poolNftId,
+            IInstance instance
+        )
+    {
+        return PoolLib.getAndVerifyActiveComponent(getRegistry(), msg.sender, DISTRIBUTION());
+    }
+
+    function _getDistributionServiceStorage() private pure returns (DistributionServiceStorage storage $) {
+        assembly {
+            $.slot := DISTRIBUTION_SERVICE_STORAGE_LOCATION_V3_0
+        }
+    }
+
+    function _getDomain() internal pure override returns(ObjectType) {
+        return DISTRIBUTION();
+    }
+}

package/contracts/distribution/DistributionServiceManager.sol

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.20;
+
+import {IVersionable} from "../upgradeability/IVersionable.sol";
+import {ProxyManager} from "../upgradeability/ProxyManager.sol";
+import {DistributionService} from "./DistributionService.sol";
+
+contract DistributionServiceManager is ProxyManager {
+
+    DistributionService private _distributionService;
+
+    /// @dev initializes proxy manager with distribution service implementation and deploys instance
+    constructor(
+        address authority, 
+        address registry,
+        bytes32 salt
+    ) 
+    {
+        DistributionService svc = new DistributionService{salt: salt}();
+        bytes memory data = abi.encode(authority, registry);
+        IVersionable versionable = initialize(
+            registry,
+            address(svc), 
+            data,
+            salt);
+
+        _distributionService = DistributionService(address(versionable));
+    }
+
+    //--- view functions ----------------------------------------------------//
+    function getDistributionService()
+        external
+        view
+        returns (DistributionService distributionService)
+    {
+        return _distributionService;
+    }
+
+}

package/contracts/distribution/IDistributionComponent.sol

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.20;
+
+import {IInstanceLinkedComponent} from "../shared/IInstanceLinkedComponent.sol";
+
+import {Amount} from "../type/Amount.sol";
+import {NftId} from "../type/NftId.sol";
+import {ReferralId, ReferralStatus} from "../type/Referral.sol";
+import {UFixed} from "../type/UFixed.sol";
+
+
+interface IDistributionComponent is IInstanceLinkedComponent {
+
+    event LogDistributorUpdated(address to, address operator);
+
+    function getDiscountPercentage(
+        string memory referralCode
+    ) external view returns (UFixed discountPercentage, ReferralStatus status);
+
+    function getReferralId(
+        string memory referralCode
+    ) external returns (ReferralId referralId);
+
+    function calculateRenewalFeeAmount(
+        ReferralId referralId,
+        uint256 netPremiumAmount
+    ) external view returns (uint256 feeAmount);
+
+    /// @dev Callback function to process a renewal of a policy.
+    /// The default implementation is empty.
+    /// Overwrite this function to implement a use case specific behaviour.
+    function processRenewal(
+        ReferralId referralId,
+        uint256 feeAmount
+    ) external;
+
+    /// @dev Returns true to ensure component is called when transferring distributor Nft Ids.
+    function isVerifying() external view returns (bool verifying);
+
+    /// @dev Withdraw commission for the distributor
+    /// @param distributorNftId the distributor Nft Id
+    /// @param amount the amount to withdraw. If set to AMOUNT_MAX, the full commission available is withdrawn
+    /// @return withdrawnAmount the effective withdrawn amount
+    function withdrawCommission(NftId distributorNftId, Amount amount) external returns (Amount withdrawnAmount);
+}

package/contracts/distribution/IDistributionService.sol

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.20;
+
+import {IPolicy} from "../instance/module/IPolicy.sol";
+import {IService} from "../shared/IService.sol";
+
+import {Amount} from "../type/Amount.sol";
+import {DistributorType} from "../type/DistributorType.sol";
+import {InstanceReader} from "../instance/InstanceReader.sol";
+import {NftId} from "../type/NftId.sol";
+import {ReferralId, ReferralStatus} from "../type/Referral.sol";
+import {Seconds} from "../type/Seconds.sol";
+import {Timestamp} from "../type/Timestamp.sol";
+import {UFixed} from "../type/UFixed.sol";
+
+
+interface IDistributionService is IService {
+    error ErrorDistributionServiceCallerNotRegistered(address caller);
+    error ErrorDistributionServiceParentNftIdNotInstance(NftId nftId, NftId parentNftId);
+    error ErrorDistributionServiceCallerNotDistributor(address caller);
+    error ErrorDistributionServiceInvalidReferralId(ReferralId referralId);
+    error ErrorDistributionServiceMaxReferralsExceeded(uint256 limit, uint256 maxReferrals);
+    error ErrorDistributionServiceDiscountTooLow(UFixed minDiscountPercentage, UFixed discountPercentage);
+    error ErrorDistributionServiceDiscountTooHigh(UFixed maxDiscountPercentage, UFixed discountPercentage);
+    error ErrorDistributionServiceExpiryTooLong(Seconds maxReferralLifetime, Timestamp expiryAt);
+    error ErrorDistributionServiceInvalidReferral();
+    error ErrorDistributionServiceExpirationInvalid(Timestamp expiryAt);
+    error ErrorDistributionServiceCommissionTooHigh(uint256 commissionPercentage, uint256 maxCommissionPercentage);
+    error ErrorDistributionServiceMinFeeTooHigh(uint256 minFee, uint256 limit);
+    error ErrorDistributionServiceDistributorTypeDistributionMismatch(DistributorType distributorType, NftId distributorTypeDistributionNftId, NftId distributionNftId);
+    error ErrorDistributionServiceDistributorDistributionMismatch(NftId distributorNftId, NftId distributorDistributionNftId, NftId distributionNftId);
+
+    error ErrorDistributionServiceCommissionWithdrawAmountExceedsLimit(Amount amount, Amount limit);
+    
+    error ErrorDistributionServiceVariableFeesTooHight(uint256 maxDiscountPercentage, uint256 limit);
+    error ErrorDistributionServiceMaxDiscountTooHigh(uint256 maxDiscountPercentage, uint256 limit);
+
+    error ErrorDistributionServiceReferralInvalid(NftId distributionNftId, ReferralId referralId);
+    error ErrorDistributionServiceInvalidFeeTransferred(Amount transferredDistributionFeeAmount, Amount expectedDistributionFeeAmount);
+    error ErrorDistributionServiceReferralDistributionMismatch(ReferralId referralId, NftId referralDistributionNft, NftId distributionNftId);
+
+    event LogDistributionServiceCommissionWithdrawn(NftId distributorNftId, address recipient, address tokenAddress, Amount amount);
+    event LogDistributionServiceDistributorTypeCreated(NftId distributionNftId, string name);
+    event LogDistributionServiceDistributorCreated(NftId distributionNftId, NftId distributorNftId, DistributorType distributorType, address distributor);
+    event LogDistributionServiceDistributorTypeChanged(NftId distributorNftId, DistributorType oldDistributorType, DistributorType newDistributorType);
+    event LogDistributionServiceReferralCreated(NftId distributionNftId, NftId distributorNftId, ReferralId referralId, string code);
+    event LogDistributionServiceReferralProcessed(NftId distributionNftId, NftId distributorNftId, ReferralId referralId, uint32 usedReferrals);
+    event LogDistributionServiceSaleProcessed(NftId distributionNftId, ReferralId referralId);
+
+    function createDistributorType(
+        string memory name,
+        UFixed minDiscountPercentage,
+        UFixed maxDiscountPercentage,
+        UFixed commissionPercentage,
+        uint32 maxReferralCount,
+        Seconds 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 changeDistributorType(
+        NftId distributorNftId,
+        DistributorType newDistributorType,
+        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 a referral is used. 
+    /// Calling this will increment the referral usage counter. 
+    function processReferral(
+        NftId distributionNftId, 
+        ReferralId referralId
+    ) external;
+
+    /// @dev callback from product service when selling a policy for a specific referralId
+    function processSale(
+        NftId distributionNftId,
+        ReferralId referralId,
+        IPolicy.PremiumInfo memory premium
+    ) external;
+
+    function referralIsValid(
+        NftId distributorNftId,
+        ReferralId referralId
+    ) external view returns (bool isValid);
+
+    /// @dev Withdraw commission for the distributor
+    /// @param distributorNftId the distributor Nft Id
+    /// @param amount the amount to withdraw. If set to AMOUNT_MAX, the full commission available is withdrawn
+    /// @return withdrawnAmount the effective withdrawn amount
+    function withdrawCommission(NftId distributorNftId, Amount amount) external returns (Amount withdrawnAmount);
+
+    /// @dev Returns the discount percentage for the provided referral code.
+    /// The function retuns both the percentage and the status of the referral code.
+    function getDiscountPercentage(InstanceReader instanceReader, ReferralId referralId) external view returns (UFixed discountPercentage, ReferralStatus status);
+}