@etherisc/gif-next 0.0.2-ffa91a6-022 → 3.0.0-0fefe0d-162

package/contracts/staking/TargetHandler.sol

@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.20;
+
+import {AccessManaged} from "@openzeppelin/contracts/access/manager/AccessManaged.sol";
+import {Initializable} from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol"; 
+
+import {IRegistry} from "../registry/IRegistry.sol";
+import {ITargetLimitHandler} from "./ITargetLimitHandler.sol";
+
+import {Amount, AmountLib} from "../type/Amount.sol";
+import {Blocknumber, BlocknumberLib} from "../type/Blocknumber.sol";
+import {NftId} from "../type/NftId.sol";
+import {StakingStore} from "./StakingStore.sol";
+import {UFixed, UFixedLib} from "../type/UFixed.sol";
+
+
+contract TargetHandler is
+    Initializable,
+    AccessManaged,
+    ITargetLimitHandler
+{
+
+    event LogTargetHandlerUpdateTriggersSet(uint16 tvlUpdatesTrigger, UFixed minTvlRatioTrigger, Blocknumber lastUpdateIn);
+
+    IRegistry private _registry;
+    StakingStore private _store;
+
+    /// @dev Update trigger value: Number of TVL updates below which limit updates are suppressed
+    uint16 private _tvlUpdatesTrigger; 
+    /// @dev Maximum TVL ratio: Any ratio above this value will trigger a limit update
+    UFixed private _minTvlRatioTrigger;
+    Blocknumber private _lastUpdateIn;
+
+
+    constructor (
+        IRegistry registry,
+        StakingStore stakingStore
+    )
+        AccessManaged(msg.sender)
+    {
+        // set final authority and registry
+        setAuthority(registry.getAuthority());
+        _registry = registry;
+        _store = stakingStore;
+
+        // set default trigger values
+        _setUpdateTriggers(
+            10, // check after 2 TVL updates
+            UFixedLib.toUFixed(1, -1)); // 10% deviation from baseline TVL
+    }
+
+
+    // TODO do we really need this?
+    // if so: add onlyDeployer (new base contract? also for reader)
+    // if not: remove oz intializer/initializable
+    function initialize()
+        external
+        initializer()
+    { }
+
+    //--- staking functions -------------------------------------------------------//
+
+    /// @dev Sets the TVL update triggers.
+    function setUpdateTriggers(
+        uint16 tvlUpdatesTrigger,
+        UFixed minTvlRatioTrigger
+    )
+        external
+        restricted()
+    {
+        _setUpdateTriggers(tvlUpdatesTrigger, minTvlRatioTrigger);
+    }
+
+    //--- ITargetLimitHandler -----------------------------------------------------//
+
+    /// @inheritdoc ITargetLimitHandler
+    // Current implementation only considers the TVL amounts. 
+    // Future implementations may also consider target or token specific factors. 
+    function isLimitUpdateRequired(
+        NftId, // targetNftId
+        address , // token
+        uint16 tvlUpdatesCount,
+        Amount baselineTvlAmount, 
+        Amount currentTvlAmount
+    )
+        external 
+        virtual
+        view
+        returns (bool updateIsRequired)
+    {
+        // no update required if below the TVL updates trigger
+        if (tvlUpdatesCount < _tvlUpdatesTrigger) {
+            return false;
+        }
+
+        // no update required if both amounts are zero
+        Amount zero = AmountLib.zero();
+        if (baselineTvlAmount == zero && currentTvlAmount == zero) {
+            return false;
+
+        // update required if one amount is zero
+        } else if (baselineTvlAmount == zero || currentTvlAmount == zero) {
+            return true;
+        }
+
+        // calculate the ratio of the current TVL amount to the baseline TVL amount
+        UFixed baseline = baselineTvlAmount.toUFixed();
+        UFixed current = currentTvlAmount.toUFixed();
+        UFixed ratio;
+
+        if (baseline > current) { ratio = baseline / current; }
+        else { ratio = current / baseline; }
+
+        // update required if the ratio is above the maximum TVL ratio
+        return ratio >= _minTvlRatioTrigger;
+    }
+
+
+    function _setUpdateTriggers(
+        uint16 tvlUpdatesTrigger,
+        UFixed minTvlRatioTrigger
+    )
+        internal
+    {
+        Blocknumber lastUpdateIn = _lastUpdateIn;
+        _tvlUpdatesTrigger = tvlUpdatesTrigger;
+        _minTvlRatioTrigger = minTvlRatioTrigger;
+        _lastUpdateIn = BlocknumberLib.current();
+
+        emit LogTargetHandlerUpdateTriggersSet(tvlUpdatesTrigger, minTvlRatioTrigger, lastUpdateIn);
+    }
+}

package/contracts/staking/TargetManagerLib.sol

@@ -3,8 +3,10 @@ pragma solidity ^0.8.20;
 
 import {IERC20Metadata} from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
 
+import {IStaking} from "./IStaking.sol";
+
 import {Amount, AmountLib} from "../type/Amount.sol";
-import {Component} from "../shared/Component.sol";
+import {ChainIdLib} from "../type/ChainId.sol";
 import {IRegistry} from "../registry/IRegistry.sol";
 import {IRegistryService} from "../registry/IRegistryService.sol";
 import {IStaking} from "./IStaking.sol";
@@ -37,7 +39,8 @@ library TargetManagerLib {
             revert IStaking.ErrorStakingTargetNotFound(targetNftId);
         }
 
-        checkLockingPeriod(targetNftId, lockingPeriod);
+        ObjectType targetType = reader.getTargetInfo(targetNftId).objectType;
+        checkLockingPeriod(reader, targetNftId, targetType, lockingPeriod);
 
         targetInfo = reader.getTargetInfo(targetNftId);
         oldLockingPeriod = targetInfo.lockingPeriod;
@@ -65,7 +68,8 @@ library TargetManagerLib {
             revert IStaking.ErrorStakingTargetNotFound(targetNftId);
         }
 
-        checkRewardRate(targetNftId, rewardRate);
+        ObjectType targetType = reader.getTargetInfo(targetNftId).objectType;
+        checkRewardRate(reader, targetNftId, targetType, rewardRate);
 
         targetInfo = reader.getTargetInfo(targetNftId);
         oldRewardRate = targetInfo.rewardRate;
@@ -79,8 +83,8 @@ library TargetManagerLib {
         StakingReader stakingReader,
         NftId targetNftId,
         ObjectType expectedObjectType,
-        Seconds initialLockingPeriod,
-        UFixed initialRewardRate
+        Seconds lockingPeriod,
+        UFixed rewardRate
     )
         external
         view
@@ -95,63 +99,54 @@ library TargetManagerLib {
             revert IStaking.ErrorStakingTargetAlreadyRegistered(targetNftId);
         }
 
-        // target object type must be allowed
-        if (!isTargetTypeSupported(expectedObjectType)) {
+        // get setup info for additional checks
+        IStaking.SupportInfo memory supportInfo = stakingReader.getSupportInfo(expectedObjectType);
+
+        // check if type is supported and new targets of that type are allowed
+        if (!(supportInfo.isSupported && supportInfo.allowNewTargets)) {
             revert IStaking.ErrorStakingTargetTypeNotSupported(targetNftId, expectedObjectType);
         }
 
-        checkLockingPeriod(targetNftId, initialLockingPeriod);
-        checkRewardRate(targetNftId, initialRewardRate);
+        // check if cross chain targets are allowed (if applicable)
+        bool isCurrentChain = ChainIdLib.isCurrentChain(targetNftId);
+        if (!supportInfo.allowCrossChain && !isCurrentChain) {
+            revert IStaking.ErrorStakingCrossChainTargetsNotSupported(targetNftId, expectedObjectType);
+        }
 
-        // target nft id must be known and registered with the expected object type
-        if (!registry.isRegistered(targetNftId)) {
-            revert IStaking.ErrorStakingTargetNotFound(targetNftId);
-        } else {
-            // check that expected object type matches with registered object type
-            ObjectType actualObjectType = registry.getObjectInfo(targetNftId).objectType;
-            if (actualObjectType != expectedObjectType) {
-                revert IStaking.ErrorStakingTargetUnexpectedObjectType(targetNftId, expectedObjectType, actualObjectType);
+        // additional check for current chain target: target nft id must be known and registered with the expected object type
+        if (isCurrentChain) {
+            if (!registry.isRegistered(targetNftId)) {
+                revert IStaking.ErrorStakingTargetNotFound(targetNftId);
+            } else {
+                // check that expected object type matches with registered object type
+                ObjectType actualObjectType = registry.getObjectInfo(targetNftId).objectType;
+                if (actualObjectType != expectedObjectType) {
+                    revert IStaking.ErrorStakingTargetUnexpectedObjectType(targetNftId, expectedObjectType, actualObjectType);
+                }
             }
         }
-    }
 
-
-    function isTargetTypeSupported(ObjectType objectType)
-        public 
-        pure 
-        returns (bool isSupported)
-    {
-        if(objectType == PROTOCOL()) { return true; }
-        if(objectType == INSTANCE()) { return true; }
-
-        return false;
+        // check locking period and reward rate
+        _checkLockingPeriod(targetNftId, lockingPeriod, supportInfo);
+        _checkRewardRate(targetNftId, rewardRate, supportInfo);
     }
 
 
-    function checkLockingPeriod(NftId targetNftId, Seconds lockingPeriod)
+    function checkLockingPeriod(StakingReader reader, NftId targetNftId, ObjectType targetType, Seconds lockingPeriod)
         public 
-        pure
+        view
     {
-        // check locking period is >= min locking period
-        if (lockingPeriod.lt(getMinimumLockingPeriod())) {
-            revert IStaking.ErrorStakingLockingPeriodTooShort(targetNftId, getMinimumLockingPeriod(), lockingPeriod);
-        }
-
-        // check locking period <= max locking period
-        if (lockingPeriod > getMaxLockingPeriod()) {
-            revert IStaking.ErrorStakingLockingPeriodTooLong(targetNftId, getMaxLockingPeriod(), lockingPeriod);
-        }
+        IStaking.SupportInfo memory supportInfo = reader.getSupportInfo(targetType);
+        _checkLockingPeriod(targetNftId, lockingPeriod, supportInfo);
     }
 
 
-    function checkRewardRate(NftId targetNftId, UFixed rewardRate)
+    function checkRewardRate(StakingReader reader, NftId targetNftId, ObjectType targetType, UFixed rewardRate)
         public
-        pure
+        view
     {
-        // check reward rate <= max reward rate
-        if (rewardRate > getMaxRewardRate()) {
-            revert IStaking.ErrorStakingRewardRateTooHigh(targetNftId, getMaxRewardRate(), rewardRate);
-        }
+        IStaking.SupportInfo memory supportInfo = reader.getSupportInfo(targetType);
+        _checkRewardRate(targetNftId, rewardRate, supportInfo);
     }
 
 
@@ -160,7 +155,7 @@ library TargetManagerLib {
         UFixed stakingRate
     )
         public
-        view
+        pure
         returns (Amount dipAmount)
     {
         dipAmount = tokenAmount.multiplyWith(stakingRate);
@@ -208,4 +203,32 @@ library TargetManagerLib {
     function toTargetKey(NftId targetNftId) public pure returns (Key32 targetKey) {
         return targetNftId.toKey32(TARGET());
     }
+
+
+    function _checkLockingPeriod(NftId targetNftId, Seconds lockingPeriod, IStaking.SupportInfo memory supportInfo)
+        private
+        pure
+    {
+        if (lockingPeriod < supportInfo.minLockingPeriod || lockingPeriod > supportInfo.maxLockingPeriod) {
+            revert IStaking.ErrorStakingLockingPeriodInvalid(
+                targetNftId, 
+                lockingPeriod, 
+                supportInfo.minLockingPeriod,
+                supportInfo.maxLockingPeriod);
+        }
+    }
+
+
+    function _checkRewardRate(NftId targetNftId, UFixed rewardRate, IStaking.SupportInfo memory supportInfo) 
+        private
+        pure
+    {
+        if (rewardRate < supportInfo.minRewardRate || rewardRate > supportInfo.maxRewardRate) {
+            revert IStaking.ErrorStakingRewardRateInvalid(
+                targetNftId, 
+                rewardRate,
+                supportInfo.minRewardRate,
+                supportInfo.maxRewardRate);
+        }
+    }
 }

package/contracts/type/Amount.sol

@@ -3,6 +3,10 @@ pragma solidity ^0.8.20;
 
 import {UFixed, UFixedLib} from "./UFixed.sol";
 
+/// @dev Targets: 100 trillion (worlds GDP) with 6 decimal places
+/// 3 trillion USD (total crypto market cap) with 12 decimal places.
+/// 2023 100 trillion USD => 100e12 * 1e6 = 1e20
+/// 2024 2 trillion crypto market cap => 2e12 * 1e18 = 2e30
 type Amount is uint96;
 
 using {

package/contracts/type/Blocknumber.sol

@@ -1,7 +1,9 @@
 // SPDX-License-Identifier: Apache-2.0
 pragma solidity ^0.8.20;
 
-type Blocknumber is uint32;
+/// @dev Target: Cover 10 years with 1 ms block times.
+/// Typical block times are a few seconds.
+type Blocknumber is uint40;
 
 using {
     gtBlocknumber as >,
@@ -51,30 +53,23 @@ function neBlocknumber(Blocknumber a, Blocknumber b) pure returns (bool) {
     return Blocknumber.unwrap(a) != Blocknumber.unwrap(b);
 }
 
-/// @dev Converts the uint256 to a Blocknumber.
-function toBlocknumber(uint256 blocknum) pure returns (Blocknumber) {
-    return Blocknumber.wrap(uint32(blocknum));
-}
 
-function blockBlocknumber() view returns (Blocknumber) {
-    return BlocknumberLib.currentBlocknumber();
-}
+library BlocknumberLib {
 
-// TODO move to BlocknumberLib and rename to zero()
-/// @dev Return the Blocknumber zero (0)
-function zeroBlocknumber() pure returns (Blocknumber) {
-    return toBlocknumber(0);
-}
+    function zero() public pure returns (Blocknumber) {
+        return Blocknumber.wrap(0);
+    }
 
-/// @dev Return the current block number
-function blockNumber() view returns (Blocknumber) {
-    return toBlocknumber(block.number);
-}
+    function max() public pure returns (Blocknumber) {
+        return Blocknumber.wrap(type(uint40).max);
+    }
 
-library BlocknumberLib {
-    /// @dev returns the current Blocknumber
-    function currentBlocknumber() public view returns (Blocknumber) {
-        return Blocknumber.wrap(uint32(block.number));
+    function current() public view returns (Blocknumber) {
+        return Blocknumber.wrap(uint40(block.number));
+    }
+
+    function toBlocknumber(uint256 blocknum) public pure returns (Blocknumber) {
+        return Blocknumber.wrap(uint32(blocknum));
     }
 
     /// @dev return true iff blocknumber is 0
@@ -82,7 +77,7 @@ library BlocknumberLib {
         return Blocknumber.unwrap(blocknumber) == 0;
     }
 
-    /// @dev return true iff blocknumber is 0
+    /// @dev return true iff blocknumber is > 0
     function gtz(Blocknumber blocknumber) public pure returns (bool) {
         return Blocknumber.unwrap(blocknumber) > 0;
     }

package/contracts/type/ChainId.sol

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.20;
+
+import {NftId} from "./NftId.sol";
+
+/// @dev Target: Cover chain IDs up to 26 decimal places.
+/// Current longest chain ID seems to be DCHAIN Testnet: 2713017997578000 with 16 decimal places 
+type ChainId is uint96;
+
+using {
+    eqChainId as ==,
+    neChainId as !=,
+    ChainIdLib.toInt,
+    ChainIdLib.eqz,
+    ChainIdLib.gtz
+} for ChainId global;
+
+
+/// @dev return true if ChainId a is equal to ChainId b
+function eqChainId(ChainId a, ChainId b) pure returns (bool) {
+    return ChainId.unwrap(a) == ChainId.unwrap(b);
+}
+
+/// @dev return true if ChainId a is not equal to ChainId b
+function neChainId(ChainId a, ChainId b) pure returns (bool) {
+    return ChainId.unwrap(a) != ChainId.unwrap(b);
+}
+
+
+library ChainIdLib {
+
+    error ErrorChainIdLibValueTooBig(uint256 chainId);
+
+
+    function zero() public pure returns (ChainId) {
+        return ChainId.wrap(0);
+    }
+
+
+    function max() public pure returns (ChainId) {
+        return ChainId.wrap(_max());
+    }
+
+
+    function current() public view returns (ChainId) {
+        return toChainId(block.chainid);
+    }
+
+
+    /// @dev return true iff chainId is 0
+    function eqz(ChainId chainId) public pure returns (bool) {
+        return ChainId.unwrap(chainId) == 0;
+    }
+
+
+    /// @dev return true iff chainId is > 0
+    function gtz(ChainId chainId) public pure returns (bool) {
+        return ChainId.unwrap(chainId) > 0;
+    }
+
+
+    /// @dev converts the uint into ChainId
+    /// function reverts if value is exceeding max ChainId value
+    function toChainId(uint256 chainId) public pure returns (ChainId) {
+        if(chainId > _max()) {
+            revert ErrorChainIdLibValueTooBig(chainId);
+        }
+
+        return ChainId.wrap(uint96(chainId));
+    }
+
+
+    /// @dev returns true iff NFT ID is from the current chain.
+    function isCurrentChain(NftId nftId) public view returns (bool) {
+        return _fromNftId(nftId) == block.chainid;
+    }
+
+
+    function fromNftId(NftId nftId) public pure returns (ChainId) {
+        return toChainId(_fromNftId(nftId));
+    }
+
+
+    /// @dev converts the ChainId to a uint256
+    function toInt(ChainId chainId) public pure returns (uint256) {
+        return uint256(uint96(ChainId.unwrap(chainId)));
+    }
+
+
+    function _fromNftId(NftId nftId) internal pure returns (uint256 chainIdInt) {
+        uint256 nftIdInt = nftId.toInt();
+        uint256 chainIdDigits = nftIdInt % 100; // Extract the last two digits
+        chainIdInt = nftIdInt % 10**(chainIdDigits + 2) / 100; // Extract the chainId
+    }
+
+
+    function _max() internal pure returns (uint96) {
+        // IMPORTANT: type nees to match with actual definition for Amount
+        return type(uint96).max;
+    }
+}

package/contracts/type/Fee.sol

@@ -5,16 +5,16 @@ import {Amount, AmountLib} from "./Amount.sol";
 import {UFixed, UFixedLib} from "./UFixed.sol";
 
 struct Fee {
+    // slot 0
     UFixed fractionalFee;
-    // TODO migrate fixed fee to Amount
-    uint256 fixedFee;
+    Amount fixedFee;
 }
 
 library FeeLib {
 
     /// @dev Return a zero fee struct (0, 0)
     function zero() public pure returns (Fee memory fee) {
-        return Fee(UFixed.wrap(0), 0);
+        return Fee(UFixed.wrap(0), AmountLib.zero());
     }
 
     /// @dev Converts the uint256 to a fee struct.
@@ -22,7 +22,7 @@ library FeeLib {
         UFixed fractionalFee,
         uint256 fixedFee
     ) public pure returns (Fee memory fee) {
-        return Fee(fractionalFee, fixedFee);
+        return Fee(fractionalFee, AmountLib.toAmount(fixedFee));
     }
 
     /// @dev Calculates fee and net amounts for the provided parameters
@@ -41,14 +41,14 @@ library FeeLib {
         if(gtz(fee)) {
             UFixed fractionalAmount = 
                 amount.toUFixed() * fee.fractionalFee;
-            feeAmount = AmountLib.toAmount(fractionalAmount.toInt() + fee.fixedFee);
+            feeAmount = AmountLib.toAmount(fractionalAmount.toInt()) + fee.fixedFee;
             netAmount = netAmount - feeAmount;
         }
     }
 
     /// @dev Return the percent fee struct (x%, 0)
     function percentageFee(uint8 percent) public pure returns (Fee memory fee) {
-        return Fee(UFixedLib.toUFixed(percent, -2), 0);
+        return Fee(UFixedLib.toUFixed(percent, -2), AmountLib.zero());
     }
 
     // pure free functions for operators
@@ -57,10 +57,10 @@ library FeeLib {
     }
 
     function gtz(Fee memory fee) public pure returns (bool) {
-        return UFixed.unwrap(fee.fractionalFee) > 0 || fee.fixedFee > 0;
+        return UFixed.unwrap(fee.fractionalFee) > 0 || fee.fixedFee.gtz();
     }
 
     function eqz(Fee memory fee) public pure returns (bool) {
-        return fee.fixedFee == 0 && UFixed.unwrap(fee.fractionalFee) == 0;
+        return fee.fixedFee.eqz() && UFixed.unwrap(fee.fractionalFee) == 0;
     }
 }

package/contracts/type/NftId.sol

@@ -78,8 +78,8 @@ library NftIdLib {
     }
 
     function toNftId(KeyId keyId) public pure returns (NftId nftId) {
-       uint248 keyIdInt = uint248(bytes31(KeyId.unwrap(keyId)));
-       assert(keyIdInt < type(uint96).max);
-       return NftId.wrap(uint96(keyIdInt));
+        uint248 keyIdInt = uint248(bytes31(KeyId.unwrap(keyId)));
+        assert(keyIdInt < type(uint96).max);
+        return NftId.wrap(uint96(keyIdInt));
     }
 }

package/contracts/type/ObjectType.sol

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 pragma solidity ^0.8.20;
 
+import {StrLib} from "./String.sol";
 import {VersionPart} from "./Version.sol";
 
 type ObjectType is uint8;
@@ -10,6 +11,7 @@ using {
     eqObjectType as ==,
     neObjectType as !=,
     ObjectTypeLib.toInt,
+    ObjectTypeLib.toName,
     ObjectTypeLib.eqz,
     ObjectTypeLib.eq,
     ObjectTypeLib.gtz
@@ -143,7 +145,16 @@ function REFERRAL() pure returns (ObjectType) {
     return ObjectType.wrap(49);
 }
 
+/// @dev Object type for GIF core target roles.
+function CORE() pure returns (ObjectType) {
+    return ObjectType.wrap(97);
+}
 
+/// @dev Object type for target roles of contracts outside the GIF framework.
+/// Example: Custom supporting contracts for a product component.
+function CUSTOM() pure returns (ObjectType) {
+    return ObjectType.wrap(98);
+}
 
 /// @dev Object type that includes any other object type.
 /// Note that eq()/'==' does not take this property into account.
@@ -203,6 +214,8 @@ library ObjectTypeLib {
             return "Registry";
         } else if (objectType == STAKING()) {
             return "Staking";
+        } else if (objectType == RELEASE()) {
+            return "Release";
         } else if (objectType == INSTANCE()) {
             return "Instance";
         } else if (objectType == COMPONENT()) {
@@ -235,10 +248,11 @@ library ObjectTypeLib {
         return string(
             abi.encodePacked(
                 "ObjectType",
-                toString(
+                StrLib.uintToString(
                     toInt(objectType))));
     }
 
+    // TODO move to IService
     function toVersionedName(
         string memory name, 
         string memory suffix, 
@@ -248,10 +262,10 @@ library ObjectTypeLib {
         pure
         returns (string memory versionedName)
     {
-        string memory versionName = "_v0";
+        string memory versionName = "V0";
 
         if (release.toInt() >= 10) {
-            versionName = "_v";
+            versionName = "V";
         }
 
         versionedName = string(
@@ -261,34 +275,4 @@ library ObjectTypeLib {
                 versionName,
                 release.toString()));
     }
-
-    /// @dev returns the provied int as a string
-    function toString(uint256 value) public pure returns (string memory name) {
-
-        if (value == 0) {
-            return "0";
-        }
-
-        uint256 temp = value;
-        uint256 digits = 0;
-        while (temp != 0) {
-            digits++;
-            temp /= 10;
-        }
-
-        bytes memory buffer = new bytes(digits);
-        uint index = digits - 1;
-
-        temp = value;
-        while (temp != 0) {
-            buffer[index] = bytes1(uint8(48 + temp % 10));
-            temp /= 10;
-
-            if (index > 0) {
-                index--;
-            }
-        }
-
-        return string(buffer);
-    }
 }

package/contracts/type/Referral.sol

@@ -13,6 +13,7 @@ using {
     eqReferralId as ==, 
     neReferralId as !=,
     ReferralLib.eqz,
+    ReferralLib.toInt,
     ReferralLib.toKey32
 } for ReferralId global;
 
@@ -74,6 +75,11 @@ library ReferralLib {
         return ReferralStatus.wrap(status);
     }
 
+    /// @dev Converts a referral id into a uint256.
+    function toInt(ReferralId referralId) public pure returns (uint256) {
+        return uint64(ReferralId.unwrap(referralId));
+    }
+
     /// @dev Returns the key32 value for the specified nft id and object type.
     function toKey32(ReferralId id) public pure returns (Key32 key) {
         return Key32Lib.toKey32(REFERRAL(), toKeyId(id));