BasketToken

Git Source

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

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

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;

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

requestDeposit

ERC7540 LOGIC ///

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

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

Called by the basket manager to advance the redeem epoch, preventing any further redeem requests for the current epoch. Returns the total amount of assets pending deposit and shares pending redemption. This is called at the first step of the rebalance process regardless of the presence of any pending deposits or redemptions. When there are no pending deposits or redeems, the epoch is not advanced.

This function also records the total amount of shares pending redemption for the current epoch.

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

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

Returns the total amount of assets pending deposit.

function totalPendingDeposits() public view returns (uint256);

Returns

totalPendingRedemptions

Returns the total number of shares pending redemption.

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

fallbackRedeemTrigger

FALLBACK REDEEM LOGIC ///

In the event of a failed redemption fulfillment this function is called by the basket manager. Allows users to claim their shares back for a redemption in the future and advances the redemption epoch.

function fallbackRedeemTrigger() public;

claimFallbackShares

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

claimFallbackShares

Allows the caller to claim their own fallback shares.

function claimFallbackShares() public returns (uint256 shares);

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

proRataRedeem

Immediately redeems shares for all assets associated with this basket. This is synchronous and does not require the rebalance process to be completed.

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

Parameters

_harvestManagementFee

function _harvestManagementFee(uint16 feeBps, address feeCollector) internal;

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);

fallbackTriggered

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

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

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 use ERC4626's decimals function. See IERC20Metadata-decimals.

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

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

BitFlagUpdated

Emitted when the bitflag is updated to a new value.

event BitFlagUpdated(uint256 oldBitFlag, uint256 newBitFlag);

Parameters

Errors

ZeroPendingDeposits

ERRORS ///

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();

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();

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();

RedeemRequestAlreadyFallbacked

Thrown when the basket manager attempts to trigger the fallback for a redeem request that has already been put in fallback state.

error RedeemRequestAlreadyFallbacked();

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;
}

RedeemRequestStruct

Struct representing a redeem request.

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