Overview

Allocator Vault is a smart contract designed to manage crypto assets by interfacing with external yield-bearing strategies. It supports deposits, withdrawals, share minting and redemption, while applying configurable fees including deposit, performance, and management fees. Built using OpenZeppelin’s upgradeable patterns and role-based access control, the vault enables flexible governance and upgrades. Additionally, it supports harvesting and reinvestment of incentive tokens, so users don’t need to offramp these rewards manually.

Terminology

*Only applicable for multi-strategy vaults

Main Functionalities of a Vault

1. Initialization (initialize):

• Sets the underlying token, assigns a strategy for asset management, initializes ERC4626 details (name/symbol), and sets up administrative roles.

2. Vault Configuration (configureVault):

• Defines fee structure (deposit, performance, management fees) and other operational configurations (fee recipient, cooldown settings).

3. Deposits (deposit & mint):

• Users deposit the underlying tokens into the vault.
• Tokens are passed to the strategy, which invests them.
• Shares representing ownership are minted to users, accounting for deposit fees.

4. Withdrawals (withdraw & redeem):

• Users redeem vault shares to retrieve underlying assets.
• Assets are withdrawn from the strategy and sent to users.
• Share burning occurs based on proportional ownership.

5. Fee Management (harvest, _harvest):

• Periodically collects management and performance fees.
• Management fees accrue continuously based on elapsed time.
• Performance fees are calculated from asset appreciation (profit) since the last harvest.
• Fees are minted as new vault shares and given to the designated fee recipient.

6. Pause Functionality (setPaused):

• Admin can pause/unpause the vault, restricting deposit and mint operations.

User Fees Overview

Fees are set in configureVault():

struct AllocatorVaultConfig {
uint256 depositFee;
uint256 performanceFee;
uint256 managementFee;
address feeRecipient;
bool hasCooldown;
}

Deposit Fees

A deposit fee is charged when users deposit assets into the vault. This is a one-time fee taken immediately at the moment of deposit.

How it works:

• When a user deposits assets, the vault calculates how many shares should be minted (newShares).
• It then deducts the deposit fee (config.depositFee) from these newly minted shares.
• The user receives the shares minus the fee (userShares), and the vault separately mints the fee shares (feeShares) directly to the configured fee recipient address (config.feeRecipient).

Performance Fees

The performance fee is charged based on the vault’s gains (profits generated by the underlying strategy) since the last fee collection.

How it works:

• The vault periodically computes the profit since the last "stamp" (checkpoint).
• Fee is only charged on gains (gain) since the last harvest.
• Fees accumulate over time until harvested when collected fee is minted as new shares to the vault’s feeRecipient.

Management Fees

The management fee is an ongoing fee, continuously calculated based on total assets managed by the vault. It's charged regardless of performance (even if there's no profit).

How it works:

• Management fee (config.managementFee) continuously accrues as a percentage of the total assets managed.
• Calculated based on the total underlying asset balance (totalUnderlyingStamp) and elapsed time since last harvest.
• Fee is converted to vault shares and minted to the feeRecipient and applies even without positive returns.

Special Features

Multi-Strategy and Single-Strategy Configurations

Allocator Vaults can operate in a single-strategy mode or manage allocations across multiple strategies. Multi-strategy configurations allow diversification of user deposits while leveraging the Optimized Allocator Vault Mode (OAV) to dynamically adjust allocations based on performance metrics and market conditions.

True APY

True APY (TAPY) is an enhanced measure of APY (annual percentage yield) designed specifically for vaults that offer multiple reward streams, such as a base yield plus additional token incentives. Unlike traditional APY calculations, TAPY accounts for both the base yield and the potential compounding returns from periodically converting bonus rewards into the underlying asset, including the realistic impact of market conditions such as slippage and price impact when converting the assets.

By capturing these nuances, TAPY provides a more accurate representation of the actual returns users can expect. It integrates factors such as token conversion frequency, the market price of bonus tokens relative to underlying assets, and transaction-related slippage.

TAPY calculation:
• α0 = the APY quoted for the underlying asset.
• α1 = the APY for the bonus tokens.
• p= the quoted price between bonus tokens and underlying assets (denominated in underlying).
• σ= a measure of the price slippage that occurs in conversion (as a fraction σ= actual price/quoted price).
• N = the number of times per year that we willcollect the bonus tokens, convert them in to underlying assets, and then re-invest them.

Conditional Withdrawal Module

The allocator vaults support conditional withdrawal mechanism (config.hasCooldown) allowing the vault to optionally handle cooldown periods on withdrawals/redeems. Due to this module, our allocator vaults are able to support interactions with strategies such as Ethena’s USDe staking which are not fully ERC-4626 compliant vaults.

When a user decides to withdraw from an allocator vault with a cooldown period, the vault burns user’s share of the vault and transfers the underlying asset to the corresponding amount of the underlying asset to user. StakeKit’s backend then triggers the unstake or withdraw function from the underlying yield in the following step.

Example:

When a user initiates a withdrawal, the user sends and burns their “StakeKit Allocator Vault” tokens. The underlying strategies assets (e.g. sUSDe) is transferred to the user and unstaked. After the 7-day cooldown period, the user can claim their USDe directly from Ethena’s contract. The vault itself does not handle the unstaking process but facilitates the transfer of assets, allowing users full control over their withdrawals from Ethena.

Why it matters:

• Allows vaults to be able to interact with strategies that imposes cooldown periods on withdrawals, and handle accounting correctly
• Useful for vault implementations in cases they interact with strategies having locked or illiquid underlying assets — essentially when interacting yields which do not fully conform to the ERC-4626 standard

Token Wrapping on Deposits

This function is not part of the vault contracts, but is an additional feature which can be implemented on demand to allow users with a native asset (e.g. ETH) to deposit into a give yield opportunity that accepts only a wrapped token version (e.g. WETH). Once a user withdraws from the vault, they are able to receive the wrapped or unwrapped version.

This wrapping action is performed at deposit, requiring the user to confirm both wrap and deposit transactions within the same deposit flow.

Incentive Rewards Compounding

Additional tokens or rewards provided by underlying protocols can be claimed and reinvested or distributed to enhance overall returns. By claiming additional incentive tokens, swapping them for the underlying token and depositing the underlying back into the vault, we ensure that the vault’s earnings compound and the user earns pure yield — in the asset they deposited.

Minimally Trusted Management

Funds are strictly limited to whitelisted strategies, ensuring no direct access to user assets. The self-custodial design preserves user control while enabling transparent interactions with approved strategies.

Allocator Vault Interactions

Example User Flow:

1. User deposits USDC → Vault sends USDC to Strategy.
2. User receives vault shares proportional to their deposit (minus deposit fee).
3. Strategy generates yield over time.
4. Fees are periodically harvested, minting new shares to fee recipient.
5. User redeems shares, receiving their proportional amount of underlying assets plus any generated yield (minus applicable fees).

Deposits

• User Interaction: Users deposit ERC-20 tokens into the vault. The vault allocates these assets to one or more underlying strategies and mints vault-specific tokens to the user, representing their share of the vault.
• Ownership Representation: Vault tokens comply with ERC-20 standards, providing compatibility with wallets and dApps while tracking user ownership.

Withdrawals

• User Interaction: Users can withdraw their assets at any point of time. The vault burns the corresponding amount of their vault tokens and transfers the requested assets back to the users in the same transaction.
• Realizing Profits: When the underlying strategy earns rewards, the vault's total asset value increases, while the user's share count remains constant. As a result, the value represented by each share grows, allowing users to realize profits when redeeming their shares.

Reward Harvesting

Rewards generated by the underlying strategies are periodically harvested via a harvest function.

During harvesting:

• The vault retrieves allocation and share positions from the underlying protocol. Realized profits or losses are calculated based on the increase in the protocol’s balance or share value since the last harvest.
• Realized profits are reflected in an updated price per share, directly benefiting all vault token holders by increasing the value of their holdings.
• A percentage of realized profits is allocated as Performance Fees by minting new vault tokens and transferring them to designated fee recipients.
• Accrued Management Fees are calculated based on an annualized percentage of the total assets under management (AUM), including both principal and rewards, and the time elapsed since the last harvest. New vault tokens are minted and distributed to fee recipients, proportionally diluting all token holders.

Updating Allocations (Only applicable for multi-strategy vaults)

The primary feature of Allocator Vaults is their ability to allocate funds to underlying strategies. This process is managed by an account with the dedicated Allocation Manager role, which is authorized to reallocate funds between the vault and its whitelisted strategies. The allocation workflow ensures:

• Secure and Minimally Trusted Reallocation: Funds can only be moved between approved strategies, adhering to the vault’s minimally trusted architecture. The Allocation Manager cannot directly access or withdraw user funds.
• Optimized Allocator Vault (OAV): An operation mode that allows the Allocation Manager to adjust allocations across specific strategies based on market conditions, performance, or risk considerations, ensuring efficient use of deposited assets.

Security and Audits

The StakeKit Allocator Vault contracts have undergone a security audit conducted by Zelic. The audit assessed the contracts for potential vulnerabilities, ensuring the robustness and safety of the implementation.

The full audit report detailing the findings is available here.