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.

Smart Routing

Optimized Allocator Vaults (OAVs) feature a Smart Routing mechanism that automatically converts and transfers deposit assets to match the vault’s required asset and network. This system is blockchain-agnostic – it works across multiple networks (Ethereum, Base, Arbitrum, Optimism, Polygon, Avalanche, BNB Chain, etc.), unlocking cross-chain yield opportunities without burdening the user with manual conversions. In practice, when a user initiates a deposit, the vault’s token-handling subsystem will seamlessly perform any necessary asset wrapping, token swapping, or cross-chain bridging so that the funds arrive in the correct form for the target yield opportunity. All of these conversions happen during the deposit flow, abstracting away complexity while optimizing for minimal slippage, fees, and transaction steps.

Wrapping Native Assets

If a user deposits a native blockchain coin (like ETH on Ethereum or POL on Polygon), the system will automatically wrap it into its ERC-20 equivalent (e.g. WETH, WPOL) so that it can interact with DeFi protocols on that network. This wrapping occurs seamlessly during the deposit process – the user will simply confirm an additional wrap transaction in the flow, after which the wrapped token is deposited into the vault.

On withdrawal, the process can be reversed: the vault can return either the wrapped token or unwrap it to the native coin according to the user’s preference. This ensures that users can deposit with convenient native assets while the vault internally uses the proper token standard required by the yield strategies.

Token Swaps

If the vault or its strategies require a different token than the one a user deposits, the Smart Routing subsystem will perform an on-chain swap to convert the asset. The system leverages DEX liquidity and aggregators ( 0x API) to get the best conversion rate with minimal slippage. In the deposit flow, the user may be prompted to approve and swap the tokens, after which the converted asset is deposited into the vault.

For instance, if a vault’s base asset is USDC but a whitelisted strategy accepts DAI, the infrastructure can swap the necessary portion of USDC into DAI when allocating funds to that strategy, then swap back to USDC upon exit. These swaps are executed optimally – the router can compare rates across multiple DEXs (Uniswap, 1inch, 0x, SushiSwap, etc.) to find the best price for the required token conversion.

By handling token swaps automatically, the vault ensures that users can deposit any supported asset and still participate in strategies that might use a different currency, all without manual trading on the user’s part.

Example:

A user deposits USDT, but the vault operates in DAI. The system will route a swap from USDT → DAI via the best source of liquidity, e.g., Uniswap or Curve, using 0x API.

Cross-Chain Bridging

Smart Routing also enables cross-chain bridging of assets so that vaults can deploy capital on other networks when it’s advantageous. If a yield strategy resides on a different blockchain than the deposit, the system will bridge the funds to the target chain behind the scenes.

If the vault or target strategy operates on a different chain than the user's deposit, Smart Routing triggers an automatic bridge transaction once Smart Routing engine evaluates available bridge routes (e.g. Across, Hop, Stargate via an aggregator like LI.FI).

Technical Flow:

• Pre-Swap (if needed): Convert deposit token to bridge-compatible token (e.g., stablecoin or native gas token).
• Bridge Selection: Based on supported routes, fees, slippage tolerance, and asset availability.
  • Routing engine uses LiFi SDK or a custom bridge aggregator to get available routes.
  • Bridge metadata includes chain IDs, estimated gas, arrival time, and bridge fee.
• Bridge Execution:
  • Lock or burn token on source chain (via bridge contract).
  • Mint or release corresponding token on target chain to a vault adapter or vault proxy.
  • Cross-chain messaging (e.g., LayerZero or Axelar) can optionally be used for proof-of-deposit and vault state sync.
• Final Allocation: On the destination chain, the bridged asset is deposited into the local vault.

All bridge transactions are non-custodial and routed through reputable, audited protocols. Bridging failures are monitored and retry logic is in place.

Atomicity and Transaction Arching

To ensure safe and seamless execution of complex deposit flows, Smart Routing employs a transaction arching mechanism that sequences wrapping, swapping, and bridging steps into a logically atomic flow. While full atomicity (i.e., all-or-nothing execution) is guaranteed for single-chain actions, cross-chain operations — due to asynchronicity — are carefully orchestrated to maintain deterministic outcomes and user fund safety.

Atomicity on an Individual Chain

When all routing steps (e.g., wrapping and swapping) occur on the same chain, the system can bundle them into a single or batched transaction using smart contracts or relayers. These transactions revert entirely on failure (e.g., slippage, routing error, or contract failure), ensuring the user never ends up in an unintended or partial state.

Example:

• wrapETH();
• approve(tokenA);
• swap(tokenA → tokenB via 0x);
• deposit(tokenB);

If any step fails, the entire flow reverts.

Transaction Arching Across Chains

For multi-chain flows (e.g., ETH on Arbitrum → DAI strategy on Polygon), true atomicity is not feasible due to differing finality and consensus models. Instead, we use arched transactions — a coordinated sequence where each step emits verifiable events and state transitions that the next step depends on.

Fault Tolerance & Recovery

If a swap or bridge fails mid-flow, the system retains ownership of the intermediary token (e.g., stablecoin) and exposes retry or refund functionality.

Failed transactions are logged with trace IDs and optionally surfaced in the frontend for user transparency. Withdrawals also respect arching logic—if funds were bridged, the system bridges them back automatically, ensuring the user receives the correct token on their origin chain.

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 will collect 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. Yield.xyz’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 “Yield.xyz 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

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.

Learn more about the automatic and manual off-ramping of incentive tokens.

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 Yield.xyz Allocator Vault contracts have undergone a security audit conducted by Cantina. 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.