BasketToken

Git Source

Inherits: ERC20PluginsUpgradeable, ERC4626Upgradeable, ERC165Upgradeable, IERC7540Operator, IERC7540Deposit, IERC7540Redeem, MulticallUpgradeable, ERC20PermitUpgradeable

Manages user deposits and redemptions, which are processed asynchronously by the Basket Manager.

Considerations for Integrators: When users call requestDeposit or requestRedeem, the system ensures that the controller does not have any pending or claimable deposits or redeems from the controller's lastDepositRequestId. This behavior allows for a potential griefing attack: an attacker can call requestDeposit or requestRedeem with a minimal dust amount and specify the target controller address. As a result, the target controller would then be unable to make legitimate requestDeposit or requestRedeem requests until they first claim the pending request. RECOMMENDATION FOR INTEGRATORS: When integrating BasketToken into other contracts, always check for any pending or claimable tokens before requesting a deposit or redeem. This ensures that any pending deposits or redeems are resolved, preventing such griefing attacks.

State Variables

_USD_ISO_4217_CODE

LIBRARIES /// CONSTANTS ///

ISO 4217 numeric code for USD, used as a constant address representation

address private constant _USD_ISO_4217_CODE = address(840);

_MANAGEMENT_FEE_DECIMALS

uint16 private constant _MANAGEMENT_FEE_DECIMALS = 1e4;

_MAX_MANAGEMENT_FEE

Maximum management fee (30%) in BPS denominated in 1e4.

uint16 private constant _MAX_MANAGEMENT_FEE = 3000;

_NAME_PREFIX

string private constant _NAME_PREFIX = "Cove ";

_SYMBOL_PREFIX

string private constant _SYMBOL_PREFIX = "cove";

isOperator

STATE VARIABLES ///

Operator approval status per controller.

mapping(address controller => mapping(address operator => bool)) public isOperator;

lastDepositRequestId

Last deposit request ID per controller.

mapping(address controller => uint256 requestId) public lastDepositRequestId;

lastRedeemRequestId

Last redemption request ID per controller.

mapping(address controller => uint256 requestId) public lastRedeemRequestId;

_depositRequests

Deposit requests mapped by request ID. Even IDs are for deposits.

mapping(uint256 requestId => DepositRequestStruct) internal _depositRequests;

_redeemRequests

Redemption requests mapped by request ID. Odd IDs are for redemptions.

mapping(uint256 requestId => RedeemRequestStruct) internal _redeemRequests;

basketManager

Address of the BasketManager contract handling deposits and redemptions.

address public basketManager;

nextDepositRequestId

Upcoming deposit request ID.

uint256 public nextDepositRequestId;

nextRedeemRequestId

Upcoming redemption request ID.

uint256 public nextRedeemRequestId;

assetRegistry

Address of the AssetRegistry contract for asset status checks.

address public assetRegistry;

bitFlag

Bitflag representing selected assets.

uint256 public bitFlag;

strategy

Strategy contract address associated with this basket.

address public strategy;

lastManagementFeeHarvestTimestamp

Timestamp of the last management fee harvest.

uint40 public lastManagementFeeHarvestTimestamp;

Functions

constructor

Disables initializer functions.

constructor() payable;

initialize

Initializes the contract.

function initialize(
    IERC20 asset_,
    string memory name_,
    string memory symbol_,
    uint256 bitFlag_,
    address strategy_,
    address assetRegistry_
)
    public
    initializer;

Parameters

totalAssets

Returns the value of the basket in assets. This will be an estimate as it does not account for other factors that may affect the swap rates.

function totalAssets() public view override returns (uint256);

Returns

getTargetWeights

Returns the target weights for the given epoch.

function getTargetWeights() public view returns (uint64[] memory);

Returns

getAssets

Returns all assets that are eligible to be included in this basket based on the bitFlag

*This returns the complete list of eligible assets from the AssetRegistry, filtered by this basket's bitFlag. The list includes all assets that could potentially be part of the basket, regardless of:

• Their current balance in the basket
• Their current target weight
• Whether they are paused*

function getAssets() public view returns (address[] memory);

Returns

requestDeposit

ERC7540 LOGIC ///

Transfers assets from owner and submits a request for an asynchronous deposit.

Reverts on 0 assets or if the caller is not the owner or operator of the assets being deposited.

function requestDeposit(uint256 assets, address controller, address owner) public returns (uint256 requestId);

Parameters

pendingDepositRequest

Returns the pending deposit request amount for a controller.

If the epoch has been advanced then the request has been fulfilled and is no longer pending.

function pendingDepositRequest(uint256 requestId, address controller) public view returns (uint256 assets);

Parameters

Returns

claimableDepositRequest

Returns the amount of requested assets in Claimable state for the controller with the given requestId.

function claimableDepositRequest(uint256 requestId, address controller) public view returns (uint256 assets);

Parameters

_claimableDepositRequest

function _claimableDepositRequest(
    uint256 fulfilledShares,
    uint256 depositAssets
)
    internal
    pure
    returns (uint256 assets);

requestRedeem

Requests a redemption of shares from the basket.

function requestRedeem(uint256 shares, address controller, address owner) public returns (uint256 requestId);

Parameters

pendingRedeemRequest

Returns the pending redeem request amount for a user.

function pendingRedeemRequest(uint256 requestId, address controller) public view returns (uint256 shares);

Parameters

Returns

claimableRedeemRequest

Returns the amount of requested shares in Claimable state for the controller with the given requestId.

function claimableRedeemRequest(uint256 requestId, address controller) public view returns (uint256 shares);

Parameters

Returns

_claimableRedeemRequest

function _claimableRedeemRequest(
    uint256 fulfilledAssets,
    uint256 redeemShares
)
    internal
    pure
    returns (uint256 shares);

fulfillDeposit

Fulfills all pending deposit requests. Only callable by the basket manager. Assets are held by the basket manager. Locks in the rate at which users can claim their shares for deposited assets.

function fulfillDeposit(uint256 shares) public;

Parameters

setBitFlag

Sets the new bitflag for the basket.

This can only be called by the Basket Manager therefore we assume that the new bitflag is valid.

function setBitFlag(uint256 bitFlag_) public;

Parameters

prepareForRebalance

Prepares the basket token for rebalancing by processing pending deposits and redemptions.

*This function:

• Verifies previous deposit/redeem requests were fulfilled
• Advances deposit/redeem epochs if there are pending requests
• Harvests management fees
• Can only be called by the basket manager
• Called at the start of rebalancing regardless of pending requests
• Does not advance epochs if there are no pending requests*

function prepareForRebalance(
    uint16 feeBps,
    address feeCollector
)
    external
    returns (uint256 pendingDeposits, uint256 pendingShares);

Parameters

Returns

fulfillRedeem

Fulfills all pending redeem requests. Only callable by the basket manager. Burns the shares which are pending redemption. Locks in the rate at which users can claim their assets for redeemed shares.

prepareForRebalance must be called before this function.

function fulfillRedeem(uint256 assets) public;

Parameters

totalPendingDeposits

Retrieves the total amount of assets currently pending deposit.

Once a rebalance is proposed, any pending deposits are processed and this function will return the pending deposits of the next epoch.

function totalPendingDeposits() public view returns (uint256);

Returns

totalPendingRedemptions

Returns the total number of shares pending redemption.

Once a rebalance is proposed, any pending redemptions are processed and this function will return the pending redemptions of the next epoch.

function totalPendingRedemptions() public view returns (uint256);

Returns

cancelDepositRequest

Cancels a pending deposit request.

function cancelDepositRequest() public;

cancelRedeemRequest

Cancels a pending redeem request.

function cancelRedeemRequest() public;

setOperator

Sets a status for an operator's ability to act on behalf of a controller.

function setOperator(address operator, bool approved) public returns (bool success);

Parameters

Returns

_onlySelfOrOperator

Reverts if the controller is not the caller or the operator of the caller.

function _onlySelfOrOperator(address controller) internal view;

_onlyBasketManager

Reverts if the caller is not the Basket Manager.

function _onlyBasketManager() internal view;

share

Returns the address of the share token as per ERC-7575.

For non-multi asset vaults this should always return address(this).

function share() public view returns (address shareTokenAddress);

Returns

claimFallbackShares

FALLBACK REDEEM LOGIC ///

Claims shares given for a previous redemption request in the event a redemption fulfillment for a given epoch fails.

function claimFallbackShares(address receiver, address controller) public returns (uint256 shares);

Parameters

Returns

claimFallbackAssets

Claims assets given for a previous deposit request in the event a deposit fulfillment for a given epoch fails.

function claimFallbackAssets(address receiver, address controller) public returns (uint256 assets);

Parameters

Returns

claimableFallbackShares

Returns the amount of shares claimable for a given user in the event of a failed redemption fulfillment.

function claimableFallbackShares(address controller) public view returns (uint256 shares);

Parameters

Returns

claimableFallbackAssets

Returns the amount of assets claimable for a given user in the event of a failed deposit fulfillment.

function claimableFallbackAssets(address controller) public view returns (uint256 assets);

Parameters

Returns

proRataRedeem

Synchronously redeems basket shares for underlying assets at current proportions.

Bypasses rebalance process, transferring assets immediately. Requires basket to be out of rebalance cycle. Can be used to exit baskets with paused assets. See BasketManager-proRataRedeem and {AssetRegistry-setAssetStatus}.

function proRataRedeem(uint256 shares, address to, address from) public;

Parameters

harvestManagementFee

Harvests management fees owed to the fee collector.

function harvestManagementFee() external;

_harvestManagementFee

Internal function to harvest management fees. Updates the timestamp of the last management fee harvest if a non zero fee is collected. Mints the fee to the fee collector and notifies the basket manager.

function _harvestManagementFee(uint16 feeBps, address feeCollector) internal;

Parameters

deposit

ERC4626 OVERRIDDEN LOGIC ///

Transfers a user's shares owed for a previously fulfillled deposit request.

function deposit(uint256 assets, address receiver, address controller) public returns (uint256 shares);

Parameters

Returns

deposit

Transfers a user's shares owed for a previously fulfillled deposit request.

function deposit(uint256 assets, address receiver) public override returns (uint256 shares);

Parameters

Returns

mint

Transfers a user's shares owed for a previously fulfillled deposit request.

Deposit should be used in all instances instead.

function mint(uint256 shares, address receiver, address controller) public returns (uint256 assets);

Parameters

Returns

mint

Transfers a user's shares owed for a previously fulfillled deposit request.

function mint(uint256 shares, address receiver) public override returns (uint256 assets);

Parameters

Returns

_claimDeposit

Internal function to claim deposit for a given amount of assets and shares.

function _claimDeposit(
    DepositRequestStruct storage depositRequest,
    uint256 assets,
    uint256 shares,
    address receiver,
    address controller
)
    internal;

Parameters

withdraw

Transfers a user's assets owed for a previously fulfillled redemption request.

Redeem should be used in all instances instead.

function withdraw(uint256 assets, address receiver, address controller) public override returns (uint256 shares);

Parameters

Returns

redeem

Transfers the receiver assets owed for a fulfilled redeem request.

function redeem(uint256 shares, address receiver, address controller) public override returns (uint256 assets);

Parameters

Returns

_claimRedemption

Internal function to claim redemption for a given amount of assets and shares.

function _claimRedemption(
    RedeemRequestStruct storage redeemRequest,
    uint256 assets,
    uint256 shares,
    address receiver,
    address controller
)
    internal;

Parameters

maxWithdraw

Returns an controller's amount of assets fulfilled for redemption.

For requests yet to be fulfilled, this will return 0.

function maxWithdraw(address controller) public view override returns (uint256);

Parameters

Returns

_maxWithdraw

function _maxWithdraw(
    uint256 fulfilledAssets,
    uint256 redeemShares,
    uint256 totalRedeemShares
)
    internal
    pure
    returns (uint256);

maxRedeem

Returns an controller's amount of shares fulfilled for redemption.

For requests yet to be fulfilled, this will return 0.

function maxRedeem(address controller) public view override returns (uint256);

Parameters

Returns

maxDeposit

Returns an controller's amount of assets fulfilled for deposit.

For requests yet to be fulfilled, this will return 0.

function maxDeposit(address controller) public view override returns (uint256);

Parameters

Returns

maxMint

Returns an controller's amount of shares fulfilled for deposit.

For requests yet to be fulfilled, this will return 0.

function maxMint(address controller) public view override returns (uint256);

Parameters

Returns

_maxMint

function _maxMint(
    uint256 fulfilledShares,
    uint256 depositAssets,
    uint256 totalDepositAssets
)
    internal
    pure
    returns (uint256);

previewDeposit

function previewDeposit(uint256) public pure override returns (uint256);

previewMint

function previewMint(uint256) public pure override returns (uint256);

previewWithdraw

function previewWithdraw(uint256) public pure override returns (uint256);

previewRedeem

function previewRedeem(uint256) public pure override returns (uint256);

fallbackRedeemTriggered

Returns true if the redemption request's fallback has been triggered.

function fallbackRedeemTriggered(uint256 requestId) public view returns (bool);

Parameters

Returns

fallbackDepositTriggered

Returns true if the deposit request's fallback has been triggered.

function fallbackDepositTriggered(uint256 requestId) public view returns (bool);

Parameters

Returns

getDepositRequest

Returns the deposit request data for a given requestId without the internal mapping.

function getDepositRequest(uint256 requestId) external view returns (DepositRequestView memory);

Parameters

Returns

getRedeemRequest

Returns the redeem request data for a given requestId without the internal mapping.

function getRedeemRequest(uint256 requestId) external view returns (RedeemRequestView memory);

Parameters

Returns

supportsInterface

Checks if the contract supports the given interface.

function supportsInterface(bytes4 interfaceID) public view virtual override returns (bool);

Parameters

Returns

_update

Override to call the ERC20PluginsUpgradeable's _update function.

function _update(
    address from,
    address to,
    uint256 amount
)
    internal
    override(ERC20PluginsUpgradeable, ERC20Upgradeable);

balanceOf

Override to call the ERC20PluginsUpgradeable's balanceOf function. See IERC20-balanceOf.

function balanceOf(address account)
    public
    view
    override(ERC20PluginsUpgradeable, ERC20Upgradeable, IERC20)
    returns (uint256);

decimals

Override to return 18 decimals. See IERC20Metadata-decimals.

function decimals() public pure override(ERC20Upgradeable, ERC4626Upgradeable) returns (uint8);

permit2

External wrapper around Permit2Lib's permit2 function to handle ERC20 permit signatures.

Supports both Permit2 and ERC20Permit (ERC-2612) signatures. Will try ERC-2612 first, then fall back to Permit2 if the token doesn't support ERC-2612 or if the permit call fails.

function permit2(
    IERC20 token,
    address owner,
    address spender,
    uint256 value,
    uint256 deadline,
    uint8 v,
    bytes32 r,
    bytes32 s
)
    external;

Parameters

Events

ManagementFeeHarvested

EVENTS ///

Emitted when the management fee is harvested.

event ManagementFeeHarvested(uint256 fee);

Parameters

DepositFulfilled

Emitted when a deposit request is fulfilled and assets are transferred to the user.

event DepositFulfilled(uint256 indexed requestId, uint256 assets, uint256 shares);

Parameters

RedeemFulfilled

Emitted when a redemption request is fulfilled and shares are burned.

event RedeemFulfilled(uint256 indexed requestId, uint256 shares, uint256 assets);

Parameters

DepositFallbackTriggered

Emitted when a deposit request is triggered in fallback mode.

event DepositFallbackTriggered(uint256 indexed requestId);

Parameters

RedeemFallbackTriggered

Emitted when a redemption request is triggered in fallback mode.

event RedeemFallbackTriggered(uint256 indexed requestId);

Parameters

BitFlagUpdated

Emitted when the bitflag is updated to a new value.

event BitFlagUpdated(uint256 oldBitFlag, uint256 newBitFlag);

Parameters

DepositRequestQueued

Emitted when a deposit request is queued and awaiting fulfillment.

event DepositRequestQueued(uint256 depositRequestId, uint256 pendingDeposits);

Parameters

RedeemRequestQueued

Emitted when a redeem request is queued and awaiting fulfillment.

event RedeemRequestQueued(uint256 redeemRequestId, uint256 pendingShares);

Parameters

Errors

ZeroAddress

ERRORS ///

Thrown when the asset address is zero.

error ZeroAddress();

ZeroAmount

Thrown when the amount is zero.

error ZeroAmount();

ZeroPendingDeposits

Thrown when there are no pending deposits to fulfill.

error ZeroPendingDeposits();

ZeroPendingRedeems

Thrown when there are no pending redeems to fulfill.

error ZeroPendingRedeems();

AssetPaused

Thrown when attempting to request a deposit or redeem while one or more of the basket's assets are paused in the AssetRegistry.

error AssetPaused();

MustClaimOutstandingDeposit

Thrown when attempting to request a new deposit while the user has an outstanding claimable deposit from a previous request. The user must first claim the outstanding deposit.

error MustClaimOutstandingDeposit();

MustClaimOutstandingRedeem

Thrown when attempting to request a new redeem while the user has an outstanding claimable redeem from a previous request. The user must first claim the outstanding redeem.

error MustClaimOutstandingRedeem();

MustClaimFullAmount

Thrown when attempting to claim a partial amount of an outstanding deposit or redeem. The user must claim the full claimable amount.

error MustClaimFullAmount();

CannotFulfillWithZeroShares

Thrown when the basket manager attempts to fulfill a deposit request with zero shares.

error CannotFulfillWithZeroShares();

CannotFulfillWithZeroAssets

Thrown when the basket manager attempts to fulfill a redeem request with zero assets.

error CannotFulfillWithZeroAssets();

ZeroClaimableFallbackAssets

Thrown when attempting to claim fallback assets when none are available.

error ZeroClaimableFallbackAssets();

ZeroClaimableFallbackShares

Thrown when attempting to claim fallback shares when none are available.

error ZeroClaimableFallbackShares();

NotAuthorizedOperator

Thrown when a non-authorized address attempts to request a deposit or redeem on behalf of another user who has not approved them as an operator.

error NotAuthorizedOperator();

NotBasketManager

Thrown when an address other than the basket manager attempts to call a basket manager only function.

error NotBasketManager();

NotFeeCollector

Thrown when an address other than the feeCollector attempts to harvest management fees.

error NotFeeCollector();

InvalidManagementFee

Thrown when attempting to set an invalid management fee percentage greater than the maximum allowed.

error InvalidManagementFee();

DepositRequestAlreadyFulfilled

Thrown when the basket manager attempts to fulfill a deposit request that has already been fulfilled.

error DepositRequestAlreadyFulfilled();

RedeemRequestAlreadyFulfilled

Thrown when the basket manager attempts to fulfill a redeem request that has already been fulfilled.

error RedeemRequestAlreadyFulfilled();

PreviousDepositRequestNotFulfilled

Thrown when attempting to prepare for a new rebalance before the previous epoch's deposit request has been fulfilled.

error PreviousDepositRequestNotFulfilled();

PreviousRedeemRequestNotFulfilled

Thrown when attempting to prepare for a new rebalance before the previous epoch's redeem request has been fulfilled or put in fallback state.

error PreviousRedeemRequestNotFulfilled();

Structs

DepositRequestStruct

Struct representing a deposit request.

struct DepositRequestStruct {
    mapping(address controller => uint256 assets) depositAssets;
    uint256 totalDepositAssets;
    uint256 fulfilledShares;
    bool fallbackTriggered;
}

DepositRequestView

Typed tuple for externally viewing DepositRequestStruct without the mapping.

struct DepositRequestView {
    uint256 totalDepositAssets;
    uint256 fulfilledShares;
    bool fallbackTriggered;
}

RedeemRequestStruct

Struct representing a redeem request.

struct RedeemRequestStruct {
    mapping(address controller => uint256 shares) redeemShares;
    uint256 totalRedeemShares;
    uint256 fulfilledAssets;
    bool fallbackTriggered;
}

RedeemRequestView

Typed tuple for externally viewing RedeemRequestStruct without the mapping.

struct RedeemRequestView {
    uint256 totalRedeemShares;
    uint256 fulfilledAssets;
    bool fallbackTriggered;
}