BasketManagerUtils
Library containing utility functions for managing storage related to baskets, including creating new baskets, proposing and executing rebalances, and settling internal and external token trades.
State Variables
_USD_ISO_4217_CODE
CONSTANTS ///
ISO 4217 numeric code for USD, used as a constant address representation
address private constant _USD_ISO_4217_CODE = address(840);
_MAX_NUM_OF_BASKET_TOKENS
Maximum number of basket tokens allowed to be created.
uint256 private constant _MAX_NUM_OF_BASKET_TOKENS = 256;
_WEIGHT_PRECISION
Precision used for weight calculations and slippage calculations.
uint256 private constant _WEIGHT_PRECISION = 1e18;
_REBALANCE_COOLDOWN_SEC
Minimum time between rebalances in seconds.
uint40 private constant _REBALANCE_COOLDOWN_SEC = 1 hours;
Functions
createNewBasket
Creates a new basket token with the given parameters.
function createNewBasket(
BasketManagerStorage storage self,
string calldata basketName,
string calldata symbol,
address baseAsset,
uint256 bitFlag,
address strategy
)
external
returns (address basket);
Parameters
| Name | Type | Description |
|---|---|---|
self | BasketManagerStorage | BasketManagerStorage struct containing strategy data. |
basketName | string | Name of the basket. |
symbol | string | Symbol of the basket. |
baseAsset | address | |
bitFlag | uint256 | Asset selection bitFlag for the basket. |
strategy | address | Address of the strategy contract for the basket. |
Returns
| Name | Type | Description |
|---|---|---|
basket | address | Address of the newly created basket token. |
proposeRebalance
Proposes a rebalance for the given baskets. The rebalance is proposed if the difference between the target balance and the current balance of any asset in the basket is more than 500 USD.
function proposeRebalance(BasketManagerStorage storage self, address[] calldata baskets) external;
Parameters
| Name | Type | Description |
|---|---|---|
self | BasketManagerStorage | |
baskets | address[] | Array of basket addresses to rebalance. |
proposeTokenSwap
If the proposed token swap results are not close to the target balances, this function will revert.
This function can only be called after proposeRebalance.
function proposeTokenSwap(
BasketManagerStorage storage self,
InternalTrade[] calldata internalTrades,
ExternalTrade[] calldata externalTrades,
address[] calldata baskets,
uint64[][] calldata basketTargetWeights,
address[][] calldata basketAssets
)
external;
Parameters
| Name | Type | Description |
|---|---|---|
self | BasketManagerStorage | BasketManagerStorage struct containing strategy data. |
internalTrades | InternalTrade[] | Array of internal trades to execute. |
externalTrades | ExternalTrade[] | Array of external trades to execute. |
baskets | address[] | Array of basket addresses currently being rebalanced. |
basketTargetWeights | uint64[][] | Array of target weights for each basket. |
basketAssets | address[][] | Array of assets in each basket. |
completeRebalance
Completes the rebalance for the given baskets. The rebalance can be completed if it has been more than 15 minutes since the last action.
function completeRebalance(
BasketManagerStorage storage self,
ExternalTrade[] calldata externalTrades,
address[] calldata baskets,
uint64[][] calldata basketTargetWeights,
address[][] calldata basketAssets
)
external;
Parameters
| Name | Type | Description |
|---|---|---|
self | BasketManagerStorage | BasketManagerStorage struct containing strategy data. |
externalTrades | ExternalTrade[] | Array of external trades matching those proposed for rebalance. |
baskets | address[] | Array of basket addresses proposed for rebalance. |
basketTargetWeights | uint64[][] | Array of target weights for each basket. |
basketAssets | address[][] |
proRataRedeem
FALLBACK REDEEM LOGIC ///
Fallback redeem function to redeem shares when the rebalance is not in progress. Redeems the shares for each underlying asset in the basket pro-rata to the amount of shares redeemed.
function proRataRedeem(
BasketManagerStorage storage self,
uint256 totalSupplyBefore,
uint256 burnedShares,
address to
)
external;
Parameters
| Name | Type | Description |
|---|---|---|
self | BasketManagerStorage | |
totalSupplyBefore | uint256 | Total supply of the basket token before the shares were burned. |
burnedShares | uint256 | Amount of shares burned. |
to | address | Address to send the redeemed assets to. |
getAssetIndexInBasket
Returns the index of the asset in a given basket
function getAssetIndexInBasket(
BasketManagerStorage storage self,
address basketToken,
address asset
)
public
view
returns (uint256 index);
Parameters
| Name | Type | Description |
|---|---|---|
self | BasketManagerStorage | BasketManagerStorage struct containing strategy data. |
basketToken | address | Basket token address. |
asset | address | Asset address. |
Returns
| Name | Type | Description |
|---|---|---|
index | uint256 | Index of the asset in the basket. |
basketTokenToIndex
Returns the index of the basket token.
function basketTokenToIndex(
BasketManagerStorage storage self,
address basketToken
)
public
view
returns (uint256 index);
Parameters
| Name | Type | Description |
|---|---|---|
self | BasketManagerStorage | BasketManagerStorage struct containing strategy data. |
basketToken | address | Basket token address. |
Returns
| Name | Type | Description |
|---|---|---|
index | uint256 | Index of the basket token. |
_indexOf
INTERNAL FUNCTIONS ///
Returns the index of the element in the array.
Reverts if the element does not exist in the array.
function _indexOf(address[] calldata array, address element) internal pure returns (uint256 index);
Parameters
| Name | Type | Description |
|---|---|---|
array | address[] | Array to find the element in. |
element | address | Element to find in the array. |
Returns
| Name | Type | Description |
|---|---|---|
index | uint256 | Index of the element in the array. |
_finalizeRebalance
PRIVATE FUNCTIONS ///
Internal function to finalize the state changes for the current rebalance. Resets rebalance status and attempts to process pending redeems. If all pending redeems cannot be fulfilled notifies basket token of a failed rebalance.
function _finalizeRebalance(
BasketManagerStorage storage self,
EulerRouter eulerRouter,
address[] calldata baskets,
address[][] calldata basketAssets
)
private;
Parameters
| Name | Type | Description |
|---|---|---|
self | BasketManagerStorage | BasketManagerStorage struct containing strategy data. |
eulerRouter | EulerRouter | |
baskets | address[] | Array of basket addresses currently being rebalanced. |
basketAssets | address[][] |
_completeTokenSwap
Internal function to complete proposed token swaps.
function _completeTokenSwap(
BasketManagerStorage storage self,
ExternalTrade[] calldata externalTrades
)
private
returns (uint256[2][] memory claimedAmounts);
Parameters
| Name | Type | Description |
|---|---|---|
self | BasketManagerStorage | BasketManagerStorage struct containing strategy data. |
externalTrades | ExternalTrade[] | Array of external trades to be completed. |
Returns
| Name | Type | Description |
|---|---|---|
claimedAmounts | uint256[2][] | amounts claimed from the completed token swaps |
_processExternalTrades
Internal function to update internal accounting with result of completed token swaps.
function _processExternalTrades(BasketManagerStorage storage self, ExternalTrade[] calldata externalTrades) private;
Parameters
| Name | Type | Description |
|---|---|---|
self | BasketManagerStorage | BasketManagerStorage struct containing strategy data. |
externalTrades | ExternalTrade[] | Array of external trades to be completed. |
_initializeBasketData
Internal function to initialize basket data.
function _initializeBasketData(
BasketManagerStorage storage self,
EulerRouter eulerRouter,
address[] calldata baskets,
address[][] calldata basketAssets,
BasketContext memory slot
)
private
view;
Parameters
| Name | Type | Description |
|---|---|---|
self | BasketManagerStorage | BasketManagerStorage struct containing strategy data. |
eulerRouter | EulerRouter | |
baskets | address[] | Array of basket addresses currently being rebalanced. |
basketAssets | address[][] | An array of arrays of basket assets. |
slot | BasketContext | A Slot struct containing the basket balances and total values. |
_processInternalTrades
Internal function to settle internal trades.
If the result of an internal trade is not within the provided minAmount or maxAmount, this function will revert.
function _processInternalTrades(
BasketManagerStorage storage self,
EulerRouter eulerRouter,
InternalTrade[] calldata internalTrades,
address[] calldata baskets,
BasketContext memory slot
)
private;
Parameters
| Name | Type | Description |
|---|---|---|
self | BasketManagerStorage | BasketManagerStorage struct containing strategy data. |
eulerRouter | EulerRouter | |
internalTrades | InternalTrade[] | Array of internal trades to execute. |
baskets | address[] | Array of basket addresses currently being rebalanced. |
slot | BasketContext | A Slot struct containing the basket balances and total values. |
_validateExternalTrades
Internal function to validate the results of external trades.
If the result of an external trade is not within the slippageLimit threshold of the minAmount, this function will revert. If the sum of the trade ownerships is not equal to _WEIGHT_PRECISION, this function will revert.
function _validateExternalTrades(
BasketManagerStorage storage self,
EulerRouter eulerRouter,
ExternalTrade[] calldata externalTrades,
address[] calldata baskets,
BasketContext memory slot
)
private
view;
Parameters
| Name | Type | Description |
|---|---|---|
self | BasketManagerStorage | BasketManagerStorage struct containing strategy data. |
eulerRouter | EulerRouter | |
externalTrades | ExternalTrade[] | Array of external trades to be validated. |
baskets | address[] | Array of basket addresses currently being rebalanced. |
slot | BasketContext | A Slot struct containing the basket balances and total values. |
_validateBasketHash
Validate the basket hash based on the given baskets and target weights.
function _validateBasketHash(
BasketManagerStorage storage self,
address[] calldata baskets,
uint64[][] calldata basketsTargetWeights,
address[][] calldata basketAssets
)
private
view;
_isTargetWeightMet
Checks if weight deviations after trades are within the acceptable weightDeviationLimit threshold. Returns true if all deviations are within bounds for each asset in every basket.
function _isTargetWeightMet(
BasketManagerStorage storage self,
EulerRouter eulerRouter,
address[] calldata baskets,
uint64[][] calldata basketsTargetWeights,
address[][] calldata basketAssets,
BasketContext memory slot
)
private
view
returns (bool);
Parameters
| Name | Type | Description |
|---|---|---|
self | BasketManagerStorage | BasketManagerStorage struct containing strategy data. |
eulerRouter | EulerRouter | |
baskets | address[] | Array of basket addresses currently being rebalanced. |
basketsTargetWeights | uint64[][] | Array of target weights for each basket. |
basketAssets | address[][] | Array of assets in each basket. |
slot | BasketContext | A Slot struct containing the basket balances and total values. |
_processPendingDeposits
Internal function to process pending deposits and fulfill them.
Assumes pendingDeposit is not 0.
function _processPendingDeposits(
BasketManagerStorage storage self,
EulerRouter eulerRouter,
address basket,
uint256 totalSupply,
uint256 basketValue,
uint256 baseAssetBalance,
uint256 pendingDeposit,
address baseAssetAddress
)
private
returns (uint256 newShares, uint256 pendingDepositValue);
Parameters
| Name | Type | Description |
|---|---|---|
self | BasketManagerStorage | BasketManagerStorage struct containing strategy data. |
eulerRouter | EulerRouter | |
basket | address | Basket token address. |
totalSupply | uint256 | |
basketValue | uint256 | Current value of the basket in USD. |
baseAssetBalance | uint256 | Current balance of the base asset in the basket. |
pendingDeposit | uint256 | Current assets pending deposit in the given basket. |
baseAssetAddress | address |
Returns
| Name | Type | Description |
|---|---|---|
newShares | uint256 | Amount of new shares minted. |
pendingDepositValue | uint256 | Value of the pending deposits in USD. |
_calculateBasketValue
Internal function to calculate the current value of all assets in a given basket.
function _calculateBasketValue(
BasketManagerStorage storage self,
EulerRouter eulerRouter,
address basket,
address[] memory assets
)
private
view
returns (uint256[] memory balances, uint256 basketValue);
Parameters
| Name | Type | Description |
|---|---|---|
self | BasketManagerStorage | BasketManagerStorage struct containing strategy data. |
eulerRouter | EulerRouter | |
basket | address | Basket token address. |
assets | address[] | Array of asset addresses in the basket. |
Returns
| Name | Type | Description |
|---|---|---|
balances | uint256[] | Array of balances of each asset in the basket. |
basketValue | uint256 | Current value of the basket in USD. |
_setBaseAssetIndex
Internal function to store the index of the base asset for a given basket. Reverts if the base asset is not present in the basket's assets.
If the base asset is not present in the basket, this function will revert.
function _setBaseAssetIndex(
BasketManagerStorage storage self,
address basket,
address[] memory assets,
address baseAsset
)
private;
Parameters
| Name | Type | Description |
|---|---|---|
self | BasketManagerStorage | BasketManagerStorage struct containing strategy data. |
basket | address | Basket token address. |
assets | address[] | Array of asset addresses in the basket. |
baseAsset | address | Base asset address. |
_createRebalanceBitMask
Internal function to create a bitmask for baskets being rebalanced.
A bitmask like 00000011 indicates that the first two baskets are being rebalanced.
function _createRebalanceBitMask(
BasketManagerStorage storage self,
address[] memory baskets
)
private
view
returns (uint256 basketMask);
Parameters
| Name | Type | Description |
|---|---|---|
self | BasketManagerStorage | BasketManagerStorage struct containing strategy data. |
baskets | address[] | Array of basket addresses currently being rebalanced. |
Returns
| Name | Type | Description |
|---|---|---|
basketMask | uint256 | Bitmask for baskets being rebalanced. |
Events
InternalTradeSettled
EVENTS ///
Emitted when an internal trade is settled.
event InternalTradeSettled(InternalTrade internalTrade, uint256 buyAmount);
Parameters
| Name | Type | Description |
|---|---|---|
internalTrade | InternalTrade | Internal trade that was settled. |
buyAmount | uint256 | Amount of the the from token that is traded. |
SwapFeeCharged
Emitted when swap fees are charged on an internal trade.
event SwapFeeCharged(address indexed asset, uint256 amount);
Parameters
| Name | Type | Description |
|---|---|---|
asset | address | Asset that the swap fee was charged in. |
amount | uint256 | Amount of the asset that was charged. |
RebalanceProposed
Emitted when a rebalance is proposed for a set of baskets
event RebalanceProposed(
uint40 indexed epoch,
address[] baskets,
uint64[][] proposedTargetWeights,
address[][] basketAssets,
bytes32 basketHash
);
Parameters
| Name | Type | Description |
|---|---|---|
epoch | uint40 | Unique identifier for the rebalance, incremented each time a rebalance is proposed |
baskets | address[] | Array of basket addresses to rebalance |
proposedTargetWeights | uint64[][] | Array of target weights for each basket |
basketAssets | address[][] | Array of assets in each basket |
basketHash | bytes32 | Hash of the basket addresses and target weights for the rebalance |
RebalanceCompleted
Emitted when a rebalance is completed.
event RebalanceCompleted(uint40 indexed epoch);
Parameters
| Name | Type | Description |
|---|---|---|
epoch | uint40 | Unique identifier for the rebalance, incremented each time a rebalance is completed |
RebalanceRetried
Emitted when a rebalance is retried.
event RebalanceRetried(uint40 indexed epoch, uint256 retryCount);
Parameters
| Name | Type | Description |
|---|---|---|
epoch | uint40 | Unique identifier for the rebalance, incremented each time a rebalance is completed |
retryCount | uint256 | Number of retries for the current rebalance epoch. On the first retry, this will be 1. |
Errors
ZeroAddress
ERRORS ///
Reverts when the address is zero.
error ZeroAddress();
ZeroAmount
Reverts when the amount is zero.
error ZeroAmount();
ZeroTotalSupply
Reverts when the total supply of a basket token is zero.
error ZeroTotalSupply();
ZeroBurnedShares
Reverts when the amount of burned shares is zero.
error ZeroBurnedShares();
CannotBurnMoreSharesThanTotalSupply
Reverts when trying to burn more shares than the total supply.
error CannotBurnMoreSharesThanTotalSupply();
BasketTokenNotFound
Reverts when the requested basket token is not found.
error BasketTokenNotFound();
AssetNotFoundInBasket
Reverts when the requested asset is not found in the basket.
error AssetNotFoundInBasket();
BasketTokenAlreadyExists
Reverts when trying to create a basket token that already exists.
error BasketTokenAlreadyExists();
BasketTokenMaxExceeded
Reverts when the maximum number of basket tokens has been reached.
error BasketTokenMaxExceeded();
ElementIndexNotFound
Reverts when the requested element index is not found.
error ElementIndexNotFound();
StrategyRegistryDoesNotSupportStrategy
Reverts when the strategy registry does not support the given strategy.
error StrategyRegistryDoesNotSupportStrategy();
BasketsMismatch
Reverts when the baskets or target weights do not match the proposed rebalance.
error BasketsMismatch();
BaseAssetMismatch
Reverts when the base asset does not match the given asset.
error BaseAssetMismatch();
AssetListEmpty
Reverts when the asset is not found in the asset registry.
error AssetListEmpty();
MustWaitForRebalanceToComplete
Reverts when a rebalance is in progress and the caller must wait for it to complete.
error MustWaitForRebalanceToComplete();
NoRebalanceInProgress
Reverts when there is no rebalance in progress.
error NoRebalanceInProgress();
TooEarlyToCompleteRebalance
Reverts when it is too early to complete the rebalance.
error TooEarlyToCompleteRebalance();
TooEarlyToProposeRebalance
Reverts when it is too early to propose a rebalance.
error TooEarlyToProposeRebalance();
RebalanceNotRequired
Reverts when a rebalance is not required.
error RebalanceNotRequired();
ExternalTradeSlippage
Reverts when the external trade slippage exceeds the allowed limit.
error ExternalTradeSlippage();
TargetWeightsNotMet
Reverts when the target weights are not met.
error TargetWeightsNotMet();
InternalTradeMinMaxAmountNotReached
Reverts when the minimum or maximum amount is not reached for an internal trade.
error InternalTradeMinMaxAmountNotReached();
IncorrectTradeTokenAmount
Reverts when the trade token amount is incorrect.
error IncorrectTradeTokenAmount();
ExternalTradeMismatch
Reverts when given external trades do not match.
error ExternalTradeMismatch();
CompleteTokenSwapFailed
Reverts when the delegatecall to the tokenswap adapter fails.
error CompleteTokenSwapFailed();
AssetNotEnabled
Reverts when an asset included in a bit flag is not enabled in the asset registry.
error AssetNotEnabled();
CannotProposeEmptyTrades
Reverts when no internal or external trades are provided for a rebalance.
error CannotProposeEmptyTrades();
OwnershipSumMismatch
Reverts when the sum of tradeOwnerships do not match the _WEIGHT_PRECISION
error OwnershipSumMismatch();
InternalTradeSellAmountZero
Reverts when the sell amount of an internal trade is zero.
error InternalTradeSellAmountZero();
ExternalTradeSellAmountZero
Reverts when the sell amount of an external trade is zero.
error ExternalTradeSellAmountZero();
Structs
InternalTradeInfo
STRUCTS ///
Struct containing data for an internal trade.
struct InternalTradeInfo {
uint256 fromBasketIndex;
uint256 toBasketIndex;
uint256 sellTokenAssetIndex;
uint256 buyTokenAssetIndex;
uint256 toBasketBuyTokenIndex;
uint256 toBasketSellTokenIndex;
uint256 netBuyAmount;
uint256 netSellAmount;
uint256 feeOnBuy;
uint256 feeOnSell;
uint256 sellValue;
uint256 feeValue;
}
BasketContext
Outsource vars to resolve stack too deep during coverage runs
struct BasketContext {
uint256[][] basketBalances;
uint256[] totalValues;
}