@etherisc/gif-next 0.0.2-bd7444a → 0.0.2-bdb6804-509

package/contracts/instance/InstanceAuthorizationsLib.sol

@@ -0,0 +1,299 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.20;
+
+import {ADMIN_ROLE, INSTANCE_OWNER_ROLE, DISTRIBUTION_OWNER_ROLE, POOL_OWNER_ROLE, PRODUCT_OWNER_ROLE, INSTANCE_SERVICE_ROLE, DISTRIBUTION_SERVICE_ROLE, POOL_SERVICE_ROLE, PRODUCT_SERVICE_ROLE, APPLICATION_SERVICE_ROLE, POLICY_SERVICE_ROLE, CLAIM_SERVICE_ROLE, BUNDLE_SERVICE_ROLE, INSTANCE_ROLE} from "../types/RoleId.sol";
+import {INSTANCE, BUNDLE, APPLICATION, POLICY, CLAIM, PRODUCT, DISTRIBUTION, REGISTRY, POOL} from "../types/ObjectType.sol";
+import {VersionPart} from "../types/Version.sol";
+
+import {IRegistry} from "../registry/IRegistry.sol";
+
+import {Instance} from "./Instance.sol";
+import {InstanceAccessManager} from "./InstanceAccessManager.sol";
+import {InstanceReader} from "./InstanceReader.sol";
+import {BundleManager} from "./BundleManager.sol";
+import {AccessManagerUpgradeableInitializeable} from "./AccessManagerUpgradeableInitializeable.sol";
+import {InstanceStore} from "./InstanceStore.sol";
+
+
+library InstanceAuthorizationsLib
+{
+    function grantInitialAuthorizations(
+        InstanceAccessManager clonedAccessManager,
+        Instance clonedInstance,
+        BundleManager clonedBundleManager,
+        InstanceStore clonedInstanceStore,
+        address instanceOwner,
+        IRegistry registry,
+        VersionPart majorVersion)
+            external
+    {
+        _createCoreAndGifRoles(clonedAccessManager);
+        _createCoreTargets(clonedAccessManager, clonedInstance, clonedBundleManager, clonedInstanceStore);
+        _grantDistributionServiceAuthorizations(clonedAccessManager, clonedInstanceStore, registry, majorVersion);
+        _grantPoolServiceAuthorizations(clonedAccessManager, clonedInstanceStore, registry, majorVersion);
+        _grantProductServiceAuthorizations(clonedAccessManager, clonedInstanceStore, registry, majorVersion);
+        _grantApplicationServiceAuthorizations(clonedAccessManager, clonedInstanceStore, registry, majorVersion);
+        _grantPolicyServiceAuthorizations(clonedAccessManager, clonedInstanceStore, registry, majorVersion);
+        _grantClaimServiceAuthorizations(clonedAccessManager, clonedInstanceStore, registry, majorVersion);
+        _grantBundleServiceAuthorizations(clonedAccessManager, clonedInstanceStore, clonedBundleManager, registry, majorVersion);
+        _grantInstanceServiceAuthorizations(clonedAccessManager, clonedInstance, registry, majorVersion);
+        _grantInstanceAuthorizations(clonedAccessManager, registry, majorVersion);
+        _grantInstanceOwnerAuthorizations(clonedAccessManager, clonedInstance, registry, majorVersion);
+    }
+
+    function _createCoreAndGifRoles(InstanceAccessManager clonedAccessManager) private {
+        // default roles controlled by ADMIN_ROLE -> core roles
+        // all set/granted only once during cloning (the only exception is INSTANCE_OWNER_ROLE, hooked to instance nft)
+        clonedAccessManager.createCoreRole(INSTANCE_SERVICE_ROLE(), "InstanceServiceRole");
+        clonedAccessManager.createCoreRole(DISTRIBUTION_SERVICE_ROLE(), "DistributionServiceRole");
+        clonedAccessManager.createCoreRole(POOL_SERVICE_ROLE(), "PoolServiceRole");
+        clonedAccessManager.createCoreRole(APPLICATION_SERVICE_ROLE(), "ApplicationServiceRole");
+        clonedAccessManager.createCoreRole(PRODUCT_SERVICE_ROLE(), "ProductServiceRole");
+        clonedAccessManager.createCoreRole(CLAIM_SERVICE_ROLE(), "ClaimServiceRole");
+        clonedAccessManager.createCoreRole(POLICY_SERVICE_ROLE(), "PolicyServiceRole");
+        clonedAccessManager.createCoreRole(BUNDLE_SERVICE_ROLE(), "BundleServiceRole");
+        // default roles controlled by INSTANCE_OWNER_ROLE -> gif roles
+        clonedAccessManager.createGifRole(DISTRIBUTION_OWNER_ROLE(), "DistributionOwnerRole", INSTANCE_OWNER_ROLE());
+        clonedAccessManager.createGifRole(POOL_OWNER_ROLE(), "PoolOwnerRole", INSTANCE_OWNER_ROLE());
+        clonedAccessManager.createGifRole(PRODUCT_OWNER_ROLE(), "ProductOwnerRole", INSTANCE_OWNER_ROLE());
+    }
+
+    function _createCoreTargets(
+        InstanceAccessManager clonedAccessManager,
+        Instance clonedInstance,
+        BundleManager clonedBundleManager,
+        InstanceStore clonedInstanceStore)
+        private
+    {
+        clonedAccessManager.createCoreTarget(address(clonedAccessManager), "InstanceAccessManager");// TODO create in instance access manager initializer?
+        clonedAccessManager.createCoreTarget(address(clonedInstance), "Instance");// TODO create in instance access manager initializer?
+        clonedAccessManager.createCoreTarget(address(clonedBundleManager), "BundleManager");
+        clonedAccessManager.createCoreTarget(address(clonedInstanceStore), "InstanceStore");
+    }
+
+    function _grantDistributionServiceAuthorizations(
+        InstanceAccessManager clonedAccessManager,
+        InstanceStore clonedInstanceStore,
+        IRegistry registry,
+        VersionPart majorVersion)
+        private
+    {
+        // configure authorization for distribution service on instance
+        address distributionServiceAddress = registry.getServiceAddress(DISTRIBUTION(), majorVersion);
+        clonedAccessManager.grantRole(DISTRIBUTION_SERVICE_ROLE(), distributionServiceAddress);
+        bytes4[] memory instanceDistributionServiceSelectors = new bytes4[](11);
+        instanceDistributionServiceSelectors[0] = clonedInstanceStore.createDistributionSetup.selector;
+        instanceDistributionServiceSelectors[1] = clonedInstanceStore.updateDistributionSetup.selector;
+        instanceDistributionServiceSelectors[2] = clonedInstanceStore.createDistributorType.selector;
+        instanceDistributionServiceSelectors[3] = clonedInstanceStore.updateDistributorType.selector;
+        instanceDistributionServiceSelectors[4] = clonedInstanceStore.updateDistributorTypeState.selector;
+        instanceDistributionServiceSelectors[5] = clonedInstanceStore.createDistributor.selector;
+        instanceDistributionServiceSelectors[6] = clonedInstanceStore.updateDistributor.selector;
+        instanceDistributionServiceSelectors[7] = clonedInstanceStore.updateDistributorState.selector;
+        instanceDistributionServiceSelectors[8] = clonedInstanceStore.createReferral.selector;
+        instanceDistributionServiceSelectors[9] = clonedInstanceStore.updateReferral.selector;
+        instanceDistributionServiceSelectors[10] = clonedInstanceStore.updateReferralState.selector;
+        clonedAccessManager.setCoreTargetFunctionRole(
+            "InstanceStore",
+            instanceDistributionServiceSelectors,
+            DISTRIBUTION_SERVICE_ROLE());
+    }
+
+    function _grantPoolServiceAuthorizations(
+        InstanceAccessManager clonedAccessManager,
+        InstanceStore clonedInstanceStore,
+        IRegistry registry,
+        VersionPart majorVersion)
+        private
+    {
+        // configure authorization for pool service on instance
+        address poolServiceAddress = registry.getServiceAddress(POOL(), majorVersion);
+        clonedAccessManager.grantRole(POOL_SERVICE_ROLE(), address(poolServiceAddress));
+        bytes4[] memory instancePoolServiceSelectors = new bytes4[](4);
+        instancePoolServiceSelectors[0] = clonedInstanceStore.createPoolSetup.selector;
+        instancePoolServiceSelectors[1] = clonedInstanceStore.updatePoolSetup.selector;
+        clonedAccessManager.setCoreTargetFunctionRole(
+            "InstanceStore",
+            instancePoolServiceSelectors,
+            POOL_SERVICE_ROLE());
+    }
+
+    function _grantProductServiceAuthorizations(
+        InstanceAccessManager clonedAccessManager,
+        InstanceStore clonedInstanceStore,
+        IRegistry registry,
+        VersionPart majorVersion)
+        private
+    {
+        // configure authorization for product service on instance
+        address productServiceAddress = registry.getServiceAddress(PRODUCT(), majorVersion);
+        clonedAccessManager.grantRole(PRODUCT_SERVICE_ROLE(), address(productServiceAddress));
+        bytes4[] memory instanceProductServiceSelectors = new bytes4[](5);
+        instanceProductServiceSelectors[0] = clonedInstanceStore.createProductSetup.selector;
+        instanceProductServiceSelectors[1] = clonedInstanceStore.updateProductSetup.selector;
+        instanceProductServiceSelectors[2] = clonedInstanceStore.createRisk.selector;
+        instanceProductServiceSelectors[3] = clonedInstanceStore.updateRisk.selector;
+        instanceProductServiceSelectors[4] = clonedInstanceStore.updateRiskState.selector;
+        clonedAccessManager.setCoreTargetFunctionRole(
+            "InstanceStore",
+            instanceProductServiceSelectors,
+            PRODUCT_SERVICE_ROLE());
+    }
+
+    function _grantApplicationServiceAuthorizations(
+        InstanceAccessManager clonedAccessManager,
+        InstanceStore clonedInstanceStore,
+        IRegistry registry,
+        VersionPart majorVersion)
+        private
+    {
+        // configure authorization for application services on instance
+        address applicationServiceAddress = registry.getServiceAddress(APPLICATION(), majorVersion);
+        clonedAccessManager.grantRole(APPLICATION_SERVICE_ROLE(), applicationServiceAddress);
+        bytes4[] memory instanceApplicationServiceSelectors = new bytes4[](3);
+        instanceApplicationServiceSelectors[0] = clonedInstanceStore.createApplication.selector;
+        instanceApplicationServiceSelectors[1] = clonedInstanceStore.updateApplication.selector;
+        instanceApplicationServiceSelectors[2] = clonedInstanceStore.updateApplicationState.selector;
+        clonedAccessManager.setCoreTargetFunctionRole(
+            "InstanceStore",
+            instanceApplicationServiceSelectors,
+            APPLICATION_SERVICE_ROLE());
+    }
+
+    function _grantPolicyServiceAuthorizations(
+        InstanceAccessManager clonedAccessManager,
+        InstanceStore clonedInstanceStore,
+        IRegistry registry,
+        VersionPart majorVersion)
+        private
+    {
+        // configure authorization for policy services on instance
+        address policyServiceAddress = registry.getServiceAddress(POLICY(), majorVersion);
+        clonedAccessManager.grantRole(POLICY_SERVICE_ROLE(), policyServiceAddress);
+        bytes4[] memory instancePolicyServiceSelectors = new bytes4[](2);
+        instancePolicyServiceSelectors[0] = clonedInstanceStore.updatePolicy.selector;
+        instancePolicyServiceSelectors[1] = clonedInstanceStore.updatePolicyState.selector;
+        clonedAccessManager.setCoreTargetFunctionRole(
+            "InstanceStore",
+            instancePolicyServiceSelectors,
+            POLICY_SERVICE_ROLE());
+    }
+
+    function _grantClaimServiceAuthorizations(
+        InstanceAccessManager clonedAccessManager,
+        InstanceStore clonedInstanceStore,
+        IRegistry registry,
+        VersionPart majorVersion)
+        private
+    {
+        // configure authorization for claim/payout services on instance
+        address claimServiceAddress = registry.getServiceAddress(CLAIM(), majorVersion);
+        clonedAccessManager.grantRole(POLICY_SERVICE_ROLE(), claimServiceAddress);
+        // TODO add claims function authz
+        bytes4[] memory instanceClaimServiceSelectors = new bytes4[](0);
+        // instanceClaimServiceSelectors[0] = clonedInstanceStore.updatePolicy.selector;
+        // instanceClaimServiceSelectors[1] = clonedInstanceStore.updatePolicyState.selector;
+        clonedAccessManager.setCoreTargetFunctionRole(
+            "InstanceStore",
+            instanceClaimServiceSelectors,
+            CLAIM_SERVICE_ROLE());
+    }
+
+    function _grantBundleServiceAuthorizations(
+        InstanceAccessManager clonedAccessManager,
+        InstanceStore clonedInstanceStore,
+        BundleManager clonedBundleManager,
+        IRegistry registry,
+        VersionPart majorVersion)
+        private
+    {
+        // configure authorization for bundle service on instance
+        address bundleServiceAddress = registry.getServiceAddress(BUNDLE(), majorVersion);
+        clonedAccessManager.grantRole(BUNDLE_SERVICE_ROLE(), address(bundleServiceAddress));
+        bytes4[] memory instanceBundleServiceSelectors = new bytes4[](3);
+        instanceBundleServiceSelectors[0] = clonedInstanceStore.createBundle.selector;
+        instanceBundleServiceSelectors[1] = clonedInstanceStore.updateBundle.selector;
+        instanceBundleServiceSelectors[2] = clonedInstanceStore.updateBundleState.selector;
+        clonedAccessManager.setCoreTargetFunctionRole(
+            "InstanceStore",
+            instanceBundleServiceSelectors,
+            BUNDLE_SERVICE_ROLE());
+
+        // configure authorization for bundle service on bundle manager
+        bytes4[] memory bundleManagerBundleServiceSelectors = new bytes4[](5);
+        bundleManagerBundleServiceSelectors[0] = clonedBundleManager.linkPolicy.selector;
+        bundleManagerBundleServiceSelectors[1] = clonedBundleManager.unlinkPolicy.selector;
+        bundleManagerBundleServiceSelectors[2] = clonedBundleManager.add.selector;
+        bundleManagerBundleServiceSelectors[3] = clonedBundleManager.lock.selector;
+        bundleManagerBundleServiceSelectors[4] = clonedBundleManager.unlock.selector;
+        clonedAccessManager.setCoreTargetFunctionRole(
+            "BundleManager",
+            bundleManagerBundleServiceSelectors,
+            BUNDLE_SERVICE_ROLE());
+    }
+
+    function _grantInstanceServiceAuthorizations(
+        InstanceAccessManager clonedAccessManager,
+        Instance clonedInstance,
+        IRegistry registry,
+        VersionPart majorVersion)
+        private
+    {
+        // configure authorization for instance service on instance
+        address instanceServiceAddress = registry.getServiceAddress(INSTANCE(), majorVersion);
+        clonedAccessManager.grantRole(INSTANCE_SERVICE_ROLE(), instanceServiceAddress);
+        bytes4[] memory instanceInstanceServiceSelectors = new bytes4[](1);
+        instanceInstanceServiceSelectors[0] = clonedInstance.setInstanceReader.selector;
+        clonedAccessManager.setCoreTargetFunctionRole(
+            "Instance",
+            instanceInstanceServiceSelectors,
+            INSTANCE_SERVICE_ROLE());
+
+        // configure authorizations for instance service on instance access manager
+        bytes4[] memory accessManagerInstanceServiceSelectors = new bytes4[](3);
+        accessManagerInstanceServiceSelectors[0] = clonedAccessManager.createGifTarget.selector;
+        accessManagerInstanceServiceSelectors[1] = clonedAccessManager.setTargetLockedByService.selector;
+        accessManagerInstanceServiceSelectors[2] = clonedAccessManager.setCoreTargetFunctionRole.selector;
+        clonedAccessManager.setCoreTargetFunctionRole(
+            "InstanceAccessManager",
+            accessManagerInstanceServiceSelectors,
+            INSTANCE_SERVICE_ROLE());
+    }
+
+    function _grantInstanceAuthorizations(
+        InstanceAccessManager clonedAccessManager,
+        IRegistry registry,
+        VersionPart majorVersion)
+        private
+    {
+        bytes4[] memory accessManagerInstanceSelectors = new bytes4[](4);
+        accessManagerInstanceSelectors[0] = clonedAccessManager.createRole.selector;
+        accessManagerInstanceSelectors[1] = clonedAccessManager.createTarget.selector;
+        accessManagerInstanceSelectors[2] = clonedAccessManager.setTargetFunctionRole.selector;
+        accessManagerInstanceSelectors[3] = clonedAccessManager.setTargetLockedByInstance.selector;
+        clonedAccessManager.setCoreTargetFunctionRole(
+            "InstanceAccessManager",
+            accessManagerInstanceSelectors,
+            INSTANCE_ROLE());
+    }
+
+    function _grantInstanceOwnerAuthorizations(
+        InstanceAccessManager clonedAccessManager,
+        Instance clonedInstance,
+        IRegistry registry,
+        VersionPart majorVersion) 
+        private 
+    {
+        // configure authorization for instance owner on instance access manager
+        // instance owner role is granted/revoked ONLY by INSTANCE_ROLE
+        bytes4[] memory instanceInstanceOwnerSelectors = new bytes4[](4);
+        instanceInstanceOwnerSelectors[0] = clonedInstance.createRole.selector;
+        instanceInstanceOwnerSelectors[1] = clonedInstance.createTarget.selector;
+        instanceInstanceOwnerSelectors[2] = clonedInstance.setTargetFunctionRole.selector;
+        instanceInstanceOwnerSelectors[3] = clonedInstance.setTargetLocked.selector;
+        clonedAccessManager.setCoreTargetFunctionRole(
+            "Instance",
+            instanceInstanceOwnerSelectors,
+            INSTANCE_OWNER_ROLE());
+    }
+}

package/contracts/instance/InstanceReader.sol

@@ -0,0 +1,293 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.20;
+
+import {IERC20Metadata} from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
+
+import {DistributorType} from "../types/DistributorType.sol";
+import {Fee, FeeLib} from "../types/Fee.sol";
+import {Key32} from "../types/Key32.sol";
+import {NftId} from "../types/NftId.sol";
+import {ObjectType, DISTRIBUTOR, DISTRIBUTION, INSTANCE, PRODUCT, POLICY, POOL, TREASURY, BUNDLE} from "../types/ObjectType.sol";
+import {ReferralId, ReferralStatus, ReferralLib, REFERRAL_OK, REFERRAL_ERROR_UNKNOWN, REFERRAL_ERROR_EXPIRED, REFERRAL_ERROR_EXHAUSTED} from "../types/Referral.sol";
+import {Registerable} from "../shared/Registerable.sol";
+import {RiskId} from "../types/RiskId.sol";
+import {UFixed, MathLib, UFixedLib} from "../types/UFixed.sol";
+import {Version} from "../types/Version.sol";
+import {StateId} from "../types/StateId.sol";
+
+import {IRegistry} from "../registry/IRegistry.sol";
+import {IBundle} from "../instance/module/IBundle.sol";
+import {IComponents} from "../instance/module/IComponents.sol";
+import {IDistribution} from "../instance/module/IDistribution.sol";
+import {IInstance} from "./IInstance.sol";
+import {IKeyValueStore} from "../instance/base/IKeyValueStore.sol";
+import {IPolicy} from "../instance/module/IPolicy.sol";
+import {IRisk} from "../instance/module/IRisk.sol";
+import {ISetup} from "../instance/module/ISetup.sol";
+import {ITreasury} from "../instance/module/ITreasury.sol";
+import {TimestampLib} from "../types/Timestamp.sol";
+
+import {InstanceStore} from "./InstanceStore.sol";
+
+
+contract InstanceReader {
+    bool private _initialized;
+
+    IInstance internal _instance;
+    IKeyValueStore internal _store;
+
+    function initialize(address instance) public {
+        require(!_initialized, "ERROR:CRD-000:ALREADY_INITIALIZED");
+
+        require(
+            address(instance) != address(0),
+            "ERROR:CRD-001:INSTANCE_ZERO");
+
+        _instance = IInstance(instance);
+        _store = _instance.getInstanceStore();
+
+        _initialized = true;
+    }
+
+
+    // module specific functions
+
+    function getPolicyInfo(NftId policyNftId)
+        public
+        view
+        returns (IPolicy.PolicyInfo memory info)
+    {
+        bytes memory data = _store.getData(toPolicyKey(policyNftId));
+        if (data.length > 0) {
+            return abi.decode(data, (IPolicy.PolicyInfo));
+        }
+    }
+
+    function getPolicyState(NftId policyNftId)
+        public
+        view
+        returns (StateId state)
+    {
+        return _store.getState(toPolicyKey(policyNftId));
+    }
+
+    function getRiskInfo(RiskId riskId)
+        public 
+        view 
+        returns (IRisk.RiskInfo memory info)
+    {
+        bytes memory data = _store.getData(riskId.toKey32());
+        if (data.length > 0) {
+            return abi.decode(data, (IRisk.RiskInfo));
+        }
+    }
+
+    function getTokenHandler(NftId productNftId)
+        public
+        view
+        returns (address tokenHandler)
+    {
+        bytes memory data = _store.getData(toTreasuryKey(productNftId));
+
+        if (data.length > 0) {
+            ITreasury.TreasuryInfo memory info = abi.decode(data, (ITreasury.TreasuryInfo));
+            return address(info.tokenHandler);
+        }
+    }
+
+    function getTreasuryInfo(NftId productNftId)
+        public 
+        view 
+        returns (ITreasury.TreasuryInfo memory info)
+    {
+        bytes memory data = _store.getData(toTreasuryKey(productNftId));
+        if (data.length > 0) {
+            return abi.decode(data, (ITreasury.TreasuryInfo));
+        }
+    }
+    
+    function getBundleInfo(NftId bundleNftId)
+        public 
+        view 
+        returns (IBundle.BundleInfo memory info)
+    {
+        bytes memory data = _store.getData(toBundleKey(bundleNftId));
+        if (data.length > 0) {
+            return abi.decode(data, (IBundle.BundleInfo));
+        }
+    }
+
+    function getDistributorTypeInfo(DistributorType distributorType)
+        public 
+        view 
+        returns (IDistribution.DistributorTypeInfo memory info)
+    {
+        bytes memory data = _store.getData(distributorType.toKey32());
+        if (data.length > 0) {
+            return abi.decode(data, (IDistribution.DistributorTypeInfo));
+        }
+    }
+
+    function getDistributorInfo(NftId distributorNftId)
+        public
+        view
+        returns (IDistribution.DistributorInfo memory info)
+    {
+        bytes memory data = _store.getData(toDistributorKey(distributorNftId));
+        if (data.length > 0) {
+            return abi.decode(data, (IDistribution.DistributorInfo));
+        }
+    }
+
+    function getDistributionSetupInfo(NftId distributionNftId)
+        public
+        view
+        returns (ISetup.DistributionSetupInfo memory info)
+    {
+        bytes memory data = _store.getData(toDistributionKey(distributionNftId));
+        if (data.length > 0) {
+            return abi.decode(data, (ISetup.DistributionSetupInfo));
+        }
+    }
+
+    // TODO consider to replace by component type specific getXyzInfo
+    function getComponentInfo(NftId poolNftId)
+        public
+        view
+        returns (IComponents.ComponentInfo memory info)
+    {
+        bytes memory data = _store.getData(toPoolKey(poolNftId));
+        if (data.length > 0) {
+            return abi.decode(data, (IComponents.ComponentInfo));
+        }
+    }
+
+    function getProductSetupInfo(NftId productNftId)
+        public
+        view
+        returns (ISetup.ProductSetupInfo memory info)
+    {
+        bytes memory data = _store.getData(toProductKey(productNftId));
+        if (data.length > 0) {
+            return abi.decode(data, (ISetup.ProductSetupInfo));
+        }
+    }
+
+    function getReferralInfo(ReferralId referralId)
+        public 
+        view 
+        returns (IDistribution.ReferralInfo memory info)
+    {
+        bytes memory data = _store.getData(referralId.toKey32());
+        if (data.length > 0) {
+            return abi.decode(data, (IDistribution.ReferralInfo));
+        }
+    }
+
+
+    function getMetadata(Key32 key)
+        public 
+        view 
+        returns (IKeyValueStore.Metadata memory metadata)
+    {
+        return _store.getMetadata(key);
+    }
+
+
+    function toReferralId(
+        NftId distributionNftId,
+        string memory referralCode
+    )
+        public
+        pure 
+        returns (ReferralId referralId)
+    {
+        return ReferralLib.toReferralId(
+            distributionNftId, 
+            referralCode);      
+    }
+
+
+    function getDiscountPercentage(ReferralId referralId)
+        public
+        view
+        returns (
+            UFixed discountPercentage, 
+            ReferralStatus status
+        )
+    {
+        IDistribution.ReferralInfo memory info = getReferralInfo(
+            referralId);        
+
+        if (info.expiryAt.eqz()) {
+            return (
+                UFixedLib.zero(),
+                REFERRAL_ERROR_UNKNOWN());
+        }
+
+        if (info.expiryAt < TimestampLib.blockTimestamp()) {
+            return (
+                UFixedLib.zero(),
+                REFERRAL_ERROR_EXPIRED());
+        }
+
+        if (info.usedReferrals >= info.maxReferrals) {
+            return (
+                UFixedLib.zero(),
+                REFERRAL_ERROR_EXHAUSTED());
+        }
+
+        return (
+            info.discountPercentage,
+            REFERRAL_OK()
+        );
+    }
+
+
+    function toTreasuryKey(NftId productNftId) public pure returns (Key32) { 
+        return productNftId.toKey32(TREASURY());
+    }
+
+
+    function toPolicyKey(NftId policyNftId) public pure returns (Key32) { 
+        return policyNftId.toKey32(POLICY());
+    }
+
+
+    function toDistributorKey(NftId distributorNftId) public pure returns (Key32) { 
+        return distributorNftId.toKey32(DISTRIBUTOR());
+    }
+
+    function toDistributionKey(NftId distributionNftId) public pure returns (Key32) { 
+        return distributionNftId.toKey32(DISTRIBUTION());
+    }
+
+    function toBundleKey(NftId poolNftId) public pure returns (Key32) { 
+        return poolNftId.toKey32(BUNDLE());
+    }
+
+    function toPoolKey(NftId poolNftId) public pure returns (Key32) { 
+        return poolNftId.toKey32(POOL());
+    }
+
+    function toProductKey(NftId productNftId) public pure returns (Key32) { 
+        return productNftId.toKey32(PRODUCT());
+    }
+
+    // low level function
+    function getInstance() external view returns (IInstance instance) {
+        return _instance;
+    }
+
+    function getInstanceStore() external view returns (IKeyValueStore store) {
+        return _store;
+    }
+
+    function toUFixed(uint256 value, int8 exp) public pure returns (UFixed) {
+        return UFixedLib.toUFixed(value, exp);
+    }
+
+    function toInt(UFixed value) public pure returns (uint256) {
+        return UFixedLib.toInt(value);
+    }
+}