# ITokenSaleProposal ## Interface Description License: MIT ## ```solidity interface ITokenSaleProposal ``` The contract for the additional proposal with custom settings. This contract acts as a marketplace to provide DAO pools with the ability to sell their own ERC20 tokens. ## Enums info ### ParticipationType ```solidity enum ParticipationType { DAOVotes, Whitelist, BABT, TokenLock, NftLock } ``` The enum that represents the type of requirements to participate in the tier Parameters: | Name | Description | | --------- | ------------------------------------------------------------------------- | | DAOVotes | indicates that the user must have the required voting power | | Whitelist | indicates that the user must be included in the whitelist of the tier | | BABT | indicates that the user must own the BABT token | | TokenLock | indicates that the user must lock a specific amount of tokens in the tier | | NftLock | indicates that the user must lock an nft in the tier | ## Structs info ### TierMetadata ```solidity struct TierMetadata { string name; string description; } ``` Metadata of the tier that is part of the initial tier parameters Parameters: | Name | Type | Description | | ----------- | ------ | --------------------------- | | name | string | the name of the tier | | description | string | the description of the tier | ### VestingSettings ```solidity struct VestingSettings { uint256 vestingPercentage; uint64 vestingDuration; uint64 cliffPeriod; uint64 unlockStep; } ``` Vesting parameters that are part of the initial tier parameters Parameters: | Name | Type | Description | | ----------------- | ------- | -------------------------------------------------------------------------------------- | | vestingPercentage | uint256 | percentage of the purchased token amount that goes to vesting | | vestingDuration | uint64 | how long vesting lasts from the time of the token purchase | | cliffPeriod | uint64 | how long the user cannot make a vesting withdrawal from the time of the token purchase | | unlockStep | uint64 | the tick step with which funds from the vesting are given to the buyer | ### ParticipationDetails ```solidity struct ParticipationDetails { ITokenSaleProposal.ParticipationType participationType; bytes data; } ``` Participation details that are part of the initial tier parameters Parameters: | Name | Type | Description | | ----------------- | ----------------------------------------- | ------------------------------------------------------------------ | | participationType | enum ITokenSaleProposal.ParticipationType | the type of requirements to participate in the tier | | data | bytes | the additional data associated with the participation requirements | ### TierInitParams ```solidity struct TierInitParams { ITokenSaleProposal.TierMetadata metadata; uint256 totalTokenProvided; uint64 saleStartTime; uint64 saleEndTime; uint64 claimLockDuration; address saleTokenAddress; address[] purchaseTokenAddresses; uint256[] exchangeRates; uint256 minAllocationPerUser; uint256 maxAllocationPerUser; ITokenSaleProposal.VestingSettings vestingSettings; ITokenSaleProposal.ParticipationDetails[] participationDetails; } ``` Initial tier parameters Parameters: | Name | Type | Description | | ---------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | metadata | struct ITokenSaleProposal.TierMetadata | metadata of the tier (see TierMetadata) | | totalTokenProvided | uint256 | total supply of tokens provided for the tier | | saleStartTime | uint64 | start time of token sales | | saleEndTime | uint64 | end time of token sales | | claimLockDuration | uint64 | the period of time between the end of the token sale and the non-vesting tokens claiming | | saleTokenAddress | address | address of the token being sold | | purchaseTokenAddresses | address\[] | tokens, that can be used for purchasing token of the proposal | | exchangeRates | uint256\[] | exchange rates of other tokens to the token of TokenSaleProposal. Must disregard tokens decimals. If you want to sell 1 BTC for 1 ETH, exchangeRate has to be 10\*\*25 | | minAllocationPerUser | uint256 | minimal allocation of tokens per one user | | maxAllocationPerUser | uint256 | maximal allocation of tokens per one user | | vestingSettings | struct ITokenSaleProposal.VestingSettings | settings for managing tokens vesting (unlocking). While tokens are locked investors won\`t be able to withdraw them | | participationDetails | struct ITokenSaleProposal.ParticipationDetails\[] | the list of participation requirement parameters | ### VestingTierInfo ```solidity struct VestingTierInfo { uint64 vestingStartTime; uint64 vestingEndTime; } ``` Vesting tier-related parameters Parameters: | Name | Type | Description | | ---------------- | ------ | -------------------------------------------------------- | | vestingStartTime | uint64 | the start time of the vesting when the cliff period ends | | vestingEndTime | uint64 | the end time of the vesting | ### TierInfo ```solidity struct TierInfo { bool isOff; uint256 totalSold; string uri; ITokenSaleProposal.VestingTierInfo vestingTierInfo; } ``` Dynamic tier parameters Parameters: | Name | Type | Description | | --------------- | ----------------------------------------- | --------------------------- | | isOff | bool | whether the tier is off | | totalSold | uint256 | how many tokens were sold | | uri | string | whitelist uri | | vestingTierInfo | struct ITokenSaleProposal.VestingTierInfo | vesting tier-related params | ### PurchaseInfo ```solidity struct PurchaseInfo { EnumerableMap.AddressToUintMap spentAmounts; uint256 claimTotalAmount; bool isClaimed; EnumerableMap.AddressToUintMap lockedTokens; EnumerableSet.AddressSet lockedNftAddresses; mapping(address => EnumerableSet.UintSet) lockedNfts; } ``` Purchase parameters Parameters: | Name | Type | Description | | ------------------ | ------------------------------------------------ | ------------------------------------------------------------------- | | spentAmounts | struct EnumerableMap.AddressToUintMap | matching purchase token addresses with spent amounts | | claimTotalAmount | uint256 | the total amount to be claimed | | isClaimed | bool | the boolean indicating whether the purchase has been claimed or not | | lockedTokens | struct EnumerableMap.AddressToUintMap | matching user locked tokens to locked amounts | | lockedNftAddresses | struct EnumerableSet.AddressSet | the list of nft addresses locked by the user | | lockedNfts | mapping(address => struct EnumerableSet.UintSet) | the list of nft ids locked by the user | ### PurchaseView ```solidity struct PurchaseView { bool isClaimed; bool canClaim; uint64 claimUnlockTime; uint256 claimTotalAmount; uint256 boughtTotalAmount; address[] lockedTokenAddresses; uint256[] lockedTokenAmounts; address[] lockedNftAddresses; uint256[][] lockedNftIds; address[] purchaseTokenAddresses; uint256[] purchaseTokenAmounts; } ``` Purchase parameters. This struct is used in view functions as part of a return argument Parameters: | Name | Type | Description | | ---------------------- | ------------- | ------------------------------------------------------------------------------- | | isClaimed | bool | the boolean indicating whether non-vesting tokens have been claimed or not | | canClaim | bool | the boolean indication whether the user can claim non-vesting tokens | | claimUnlockTime | uint64 | the time the user can claim its non-vesting tokens | | claimTotalAmount | uint256 | the total amount of tokens to be claimed | | boughtTotalAmount | uint256 | the total amount of tokens user bought including vesting and non-vesting tokens | | lockedTokenAddresses | address\[] | the list of locked token addresses | | lockedTokenAmounts | uint256\[] | the list of locked token amounts | | lockedNftAddresses | address\[] | the list of locked nft addresses | | lockedNftIds | uint256\[]\[] | the list of locked nft ids | | purchaseTokenAddresses | address\[] | the list of purchase token addresses | | purchaseTokenAmounts | uint256\[] | the list of purchase token amounts | ### VestingUserInfo ```solidity struct VestingUserInfo { uint64 latestVestingWithdraw; uint256 vestingTotalAmount; uint256 vestingWithdrawnAmount; } ``` Vesting user-related parameters Parameters: | Name | Type | Description | | ---------------------- | ------- | ---------------------------------------------------------- | | latestVestingWithdraw | uint64 | the latest timestamp of the vesting withdrawal | | vestingTotalAmount | uint256 | the total amount of user vesting tokens | | vestingWithdrawnAmount | uint256 | the total amount of tokens user has withdrawn from vesting | ### VestingUserView ```solidity struct VestingUserView { uint64 latestVestingWithdraw; uint64 nextUnlockTime; uint256 nextUnlockAmount; uint256 vestingTotalAmount; uint256 vestingWithdrawnAmount; uint256 amountToWithdraw; uint256 lockedAmount; } ``` Vesting user-related parameters. This struct is used in view functions as part of a return argument Parameters: | Name | Type | Description | | ---------------------- | ------- | ------------------------------------------------------------------------------------------------ | | latestVestingWithdraw | uint64 | the latest timestamp of the vesting withdrawal | | nextUnlockTime | uint64 | the next time the user will receive vesting funds. It is zero if there are no more locked tokens | | nextUnlockAmount | uint256 | the token amount which will be unlocked in the next unlock time | | vestingTotalAmount | uint256 | the total amount of user vesting tokens | | vestingWithdrawnAmount | uint256 | the total amount of tokens user has withdrawn from vesting | | amountToWithdraw | uint256 | the vesting token amount which can be withdrawn in the current time | | lockedAmount | uint256 | the vesting token amount which is locked in the current time | ### ParticipationInfo ```solidity struct ParticipationInfo { bool isWhitelisted; bool isBABTed; uint256 requiredDaoVotes; EnumerableMap.AddressToUintMap requiredTokenLock; EnumerableMap.AddressToUintMap requiredNftLock; } ``` Participation parameters. Users should meet all the requirements in order to participate in the tier Parameters: | Name | Type | Description | | ----------------- | ------------------------------------- | ----------------------------------------------------------- | | isWhitelisted | bool | the boolean indicating whether the tier requires whitelist | | isBABTed | bool | the boolean indicating whether the tier requires BABT token | | requiredDaoVotes | uint256 | the required amount of DAO votes | | requiredTokenLock | struct EnumerableMap.AddressToUintMap | matching token address to required lock amounts | | requiredNftLock | struct EnumerableMap.AddressToUintMap | matching nft address to required lock amounts | ### UserInfo ```solidity struct UserInfo { ITokenSaleProposal.PurchaseInfo purchaseInfo; ITokenSaleProposal.VestingUserInfo vestingUserInfo; } ``` User parameters Parameters: | Name | Type | Description | | --------------- | ----------------------------------------- | --------------------------------------- | | purchaseInfo | struct ITokenSaleProposal.PurchaseInfo | the information about the user purchase | | vestingUserInfo | struct ITokenSaleProposal.VestingUserInfo | the information about the user vesting | ### UserView ```solidity struct UserView { bool canParticipate; ITokenSaleProposal.PurchaseView purchaseView; ITokenSaleProposal.VestingUserView vestingUserView; } ``` User parameters. This struct is used in view functions as a return argument Parameters: | Name | Type | Description | | --------------- | ----------------------------------------- | -------------------------------------------------------------------------------- | | canParticipate | bool | the boolean indicating whether the user is whitelisted in the corresponding tier | | purchaseView | struct ITokenSaleProposal.PurchaseView | the information about the user purchase | | vestingUserView | struct ITokenSaleProposal.VestingUserView | the information about the user vesting | ### Tier ```solidity struct Tier { ITokenSaleProposal.TierInitParams tierInitParams; ITokenSaleProposal.TierInfo tierInfo; ITokenSaleProposal.ParticipationInfo participationInfo; mapping(address => uint256) rates; mapping(address => ITokenSaleProposal.UserInfo) users; } ``` Tier parameters Parameters: | Name | Type | Description | | ----------------- | ------------------------------------------------------ | ------------------------------------------------------ | | tierInitParams | struct ITokenSaleProposal.TierInitParams | the initial tier parameters | | tierInfo | struct ITokenSaleProposal.TierInfo | the information about the tier | | participationInfo | struct ITokenSaleProposal.ParticipationInfo | the information about participation requirements | | rates | mapping(address => uint256) | the mapping of token addresses to their exchange rates | | users | mapping(address => struct ITokenSaleProposal.UserInfo) | the mapping of user addresses to their infos | ### TierView ```solidity struct TierView { ITokenSaleProposal.TierInitParams tierInitParams; ITokenSaleProposal.TierInfo tierInfo; } ``` Tier parameters. This struct is used in view functions as a return argument Parameters: | Name | Type | Description | | -------------- | ---------------------------------------- | ------------------------------ | | tierInitParams | struct ITokenSaleProposal.TierInitParams | the initial tier parameters | | tierInfo | struct ITokenSaleProposal.TierInfo | the information about the tier | ### WhitelistingRequest ```solidity struct WhitelistingRequest { uint256 tierId; address[] users; string uri; } ``` Whitelisting request parameters. This struct is used as an input parameter to the whitelist update function Parameters: | Name | Type | Description | | ------ | ---------- | --------------------------------------- | | tierId | uint256 | the id of the tier | | users | address\[] | the list of the users to be whitelisted | | uri | string | tokens metadata uri | ## Functions info ### latestTierId (0x83d36375) ```solidity function latestTierId() external view returns (uint256) ``` This function is used to get id (index) of the latest tier of the token sale Return values: | Name | Type | Description | | ---- | ------- | ------------------------- | | \[0] | uint256 | the id of the latest tier | ### createTiers (0x6a6effda) ```solidity function createTiers( ITokenSaleProposal.TierInitParams[] calldata tiers ) external ``` This function is used for tiers creation Parameters: | Name | Type | Description | | ----- | ------------------------------------------- | ------------------- | | tiers | struct ITokenSaleProposal.TierInitParams\[] | parameters of tiers | ### addToWhitelist (0xce6c2d91) ```solidity function addToWhitelist( ITokenSaleProposal.WhitelistingRequest[] calldata requests ) external ``` This function is used to add users to the whitelist of tier Parameters: | Name | Type | Description | | -------- | ------------------------------------------------ | ------------------------------------------ | | requests | struct ITokenSaleProposal.WhitelistingRequest\[] | requests for adding users to the whitelist | ### offTiers (0x20274396) ```solidity function offTiers(uint256[] calldata tierIds) external ``` This function is used to set given tiers inactive Parameters: | Name | Type | Description | | ------- | ---------- | ------------------------ | | tierIds | uint256\[] | tier ids to set inactive | ### recover (0xc59b695a) ```solidity function recover(uint256[] calldata tierIds) external ``` This function is used to return to the DAO treasury tokens that have not been purchased during sale Parameters: | Name | Type | Description | | ------- | ---------- | ------------------------ | | tierIds | uint256\[] | tier ids to recover from | ### claim (0x6ba4c138) ```solidity function claim(uint256[] calldata tierIds) external ``` This function is used to withdraw non-vesting tokens from given tiers Parameters: | Name | Type | Description | | ------- | ---------- | --------------------------------- | | tierIds | uint256\[] | tier ids to make withdrawals from | ### vestingWithdraw (0xe2bdc496) ```solidity function vestingWithdraw(uint256[] calldata tierIds) external ``` This function is used to withdraw vesting tokens from given tiers Parameters: | Name | Type | Description | | ------- | ---------- | --------------------------------- | | tierIds | uint256\[] | tier ids to make withdrawals from | ### buy (0x2afaca20) ```solidity function buy( uint256 tierId, address tokenToBuyWith, uint256 amount ) external payable ``` This function is used to purchase tokens in the given tier Parameters: | Name | Type | Description | | -------------- | ------- | --------------------------------------------------------------------------- | | tierId | uint256 | the id of the tier where tokens will be purchased | | tokenToBuyWith | address | the token that will be used (exchanged) to purchase token on the token sale | | amount | uint256 | the amount of the token to be used for this exchange | ### lockParticipationTokens (0x66813a3b) ```solidity function lockParticipationTokens( uint256 tierId, address tokenToLock, uint256 amountToLock ) external payable ``` This function is used to lock the specified amount of tokens to participate in the given tier Parameters: | Name | Type | Description | | ------------ | ------- | ----------------------------------------- | | tierId | uint256 | the id of the tier to lock the tokens for | | tokenToLock | address | the address of the token to be locked | | amountToLock | uint256 | the number of tokens to be locked | ### lockParticipationNft (0x1ec3f9b7) ```solidity function lockParticipationNft( uint256 tierId, address nftToLock, uint256[] calldata nftIdsToLock ) external ``` This function is used to lock the specified nft to participate in the given tier Parameters: | Name | Type | Description | | ------------ | ---------- | -------------------------------------- | | tierId | uint256 | the id of the tier to lock the nft for | | nftToLock | address | the address of nft to be locked | | nftIdsToLock | uint256\[] | the list of nft ids to be locked | ### unlockParticipationTokens (0x78ee27d7) ```solidity function unlockParticipationTokens( uint256 tierId, address tokenToUnlock, uint256 amountToUnlock ) external ``` This function is used to unlock participation tokens Parameters: | Name | Type | Description | | -------------- | ------- | ------------------------------------------- | | tierId | uint256 | the id of the tier to unlock the tokens for | | tokenToUnlock | address | the address of the token to be unlocked | | amountToUnlock | uint256 | the number of tokens to be unlocked | ### unlockParticipationNft (0x9471f309) ```solidity function unlockParticipationNft( uint256 tierId, address nftToUnlock, uint256[] calldata nftIdsToUnlock ) external ``` This function is used to unlock the participation nft Parameters: | Name | Type | Description | | -------------- | ---------- | ---------------------------------------- | | tierId | uint256 | the id of the tier to unlock the nft for | | nftToUnlock | address | the address of nft to be unlocked | | nftIdsToUnlock | uint256\[] | the list of nft ids to be unlocked | ### getSaleTokenAmount (0xceded63c) ```solidity function getSaleTokenAmount( address user, uint256 tierId, address tokenToBuyWith, uint256 amount ) external view returns (uint256) ``` This function is used to get amount of `TokenSaleProposal` tokens that can be purchased Parameters: | Name | Type | Description | | -------------- | ------- | ------------------------------------------------ | | user | address | the address of the user that purchases tokens | | tierId | uint256 | the id of the tier in which tokens are purchased | | tokenToBuyWith | address | the token which is used for exchange | | amount | uint256 | the token amount used for exchange | Return values: | Name | Type | Description | | ---- | ------- | -------------------------- | | \[0] | uint256 | expected sale token amount | ### getClaimAmounts (0xd6e93fb2) ```solidity function getClaimAmounts( address user, uint256[] calldata tierIds ) external view returns (uint256[] memory claimAmounts) ``` This function is used to get information about the amount of non-vesting tokens that user can withdraw (that are unlocked) from given tiers Parameters: | Name | Type | Description | | ------- | ---------- | ----------------------- | | user | address | the address of the user | | tierIds | uint256\[] | the array of tier ids | Return values: | Name | Type | Description | | ------------ | ---------- | --------------------------------------------------------------- | | claimAmounts | uint256\[] | the array of token amounts that can be withdrawn from each tier | ### getVestingWithdrawAmounts (0x47d436f7) ```solidity function getVestingWithdrawAmounts( address user, uint256[] calldata tierIds ) external view returns (uint256[] memory vestingWithdrawAmounts) ``` This function is used to get information about the amount of vesting tokens that user can withdraw (that are unlocked) from given tiers Parameters: | Name | Type | Description | | ------- | ---------- | ----------------------- | | user | address | the address of the user | | tierIds | uint256\[] | the array of tier ids | Return values: | Name | Type | Description | | ---------------------- | ---------- | --------------------------------------------------------------- | | vestingWithdrawAmounts | uint256\[] | the array of token amounts that can be withdrawn from each tier | ### getRecoverAmounts (0x69bc02d5) ```solidity function getRecoverAmounts( uint256[] calldata tierIds ) external view returns (uint256[] memory recoveringAmounts) ``` This function is used to get amount of tokens that have not been purchased during sale in given tiers and can be returned to DAO treasury Parameters: | Name | Type | Description | | ------- | ---------- | --------------------- | | tierIds | uint256\[] | the array of tier ids | Return values: | Name | Type | Description | | ----------------- | ---------- | ---------------------------------------------------------------------------- | | recoveringAmounts | uint256\[] | the array of token amounts that can be returned to DAO treasury in each tier | ### getTierViews (0x884ce0bd) ```solidity function getTierViews( uint256 offset, uint256 limit ) external view returns (ITokenSaleProposal.TierView[] memory tierViews) ``` This function is used to get a list of tiers Parameters: | Name | Type | Description | | ------ | ------- | -------------------------------------------- | | offset | uint256 | the offset of the list | | limit | uint256 | the limit for amount of elements in the list | Return values: | Name | Type | Description | | --------- | ------------------------------------- | ---------------------- | | tierViews | struct ITokenSaleProposal.TierView\[] | the list of tier views | ### getUserViews (0xb27f37a2) ```solidity function getUserViews( address user, uint256[] calldata tierIds ) external view returns (ITokenSaleProposal.UserView[] memory userViews) ``` This function is used to get user's infos from tiers Parameters: | Name | Type | Description | | ------- | ---------- | ------------------------------------------------ | | user | address | the address of the user whose infos are required | | tierIds | uint256\[] | the list of tier ids to get infos from | Return values: | Name | Type | Description | | --------- | ------------------------------------- | ---------------------- | | userViews | struct ITokenSaleProposal.UserView\[] | the list of user views | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.dexe.network/contract-interfaces/gov-contracts/proposals/itokensaleproposal.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.