LLM Notice: This documentation site supports content negotiation for AI agents. Request any page with Accept: text/markdown or Accept: text/plain header to receive Markdown instead of HTML. Alternatively, append ?format=md to any URL. All markdown files are available at /md/ prefix paths. For all content in one file, visit /llms-full.txt
Skip to main content

Architecture Overview

Flow Yield Vaults (FYV) is built on a modular architecture that separates concerns between user position management, yield strategy implementation, and automated rebalancing. This document explains the core components and how they interact to create an automated leveraged yield farming system.

System Architecture​


_27
graph TB
_27
User[User Account] -->|owns| YVM[YieldVaultManager]
_27
YVM -->|contains| YV1[YieldVault 1]
_27
YVM -->|contains| YV2[YieldVault 2]
_27
_27
YV1 -->|delegates to| Strategy[Strategy Implementation]
_27
YV1 -->|manages| AB[AutoBalancer]
_27
YV1 -->|holds capability| Pos[ALP Position]
_27
_27
Strategy -->|uses| Connectors[DeFi Connectors]
_27
Connectors -->|swap| SwapConn[SwapConnectors]
_27
Connectors -->|deposit/withdraw| SinkConn[Sink/Source Connectors]
_27
_27
AB -->|deposits to| ERC4626[ERC4626 Vaults]
_27
AB -->|schedules| Scheduler[FlowTransactionScheduler]
_27
_27
Pos -->|borrows from| ALP[ALP Pool]
_27
Pos -->|uses| MOET[MOET Token]
_27
_27
Registry[SchedulerRegistry] -->|tracks| YV1
_27
Registry -->|tracks| YV2
_27
_27
Supervisor[Supervisor] -->|recovers| Registry
_27
_27
style YV1 fill:#f9f,stroke:#333,stroke-width:4px
_27
style Strategy fill:#bfb,stroke:#333,stroke-width:4px
_27
style AB fill:#bbf,stroke:#333,stroke-width:4px

Core Components​

YieldVault Resource​

The YieldVault is the user-facing resource that represents a single yield-generating position.

What it does: Each YieldVault tracks user deposits, delegates operations to a Strategy implementation, holds capabilities to interact with AutoBalancer and ALP Position, and provides user interface for deposit, withdraw, and liquidation operations.

Key fields:

  • strategy: Reference to the Strategy implementation
  • autoBalancer: Capability to the AutoBalancer resource
  • position: Capability to the ALP Position resource
  • id: Unique identifier for this vault

User operations:


_10
// Deposit collateral to start yield farming
_10
vault.deposit(collateralVault: <-flowTokens)
_10
_10
// Withdraw accumulated value
_10
let withdrawn <- vault.withdraw(amount: 100.0)
_10
_10
// Close vault and retrieve all value
_10
let value <- vault.liquidate()

YieldVaultManager​

The YieldVaultManager is stored in the user's account and manages multiple vaults.

What it does: YieldVaultManager stores all vaults owned by a user, provides interfaces for vault creation and access, tracks vault IDs for enumeration, and enables multi-vault management from a single account.

Example structure:


_10
User Account
_10
└── YieldVaultManager
_10
├── YieldVault #42 (TracerStrategy with FLOW collateral)
_10
├── YieldVault #43 (mUSDCStrategy with USDC collateral)
_10
└── YieldVault #44 (TracerStrategy with stFLOW collateral)

Strategy Interface​

The Strategy defines how yield is generated and managed.

What it does: Strategies implement the core yield logic including deposit (convert collateral → yield tokens), withdrawal (convert yield tokens → collateral), and liquidation (close position and return all value). The Strategy interface keeps vault logic protocol-agnostic, allowing different yield approaches while maintaining consistent user experience.

Key functions:


_13
pub resource interface Strategy {
_13
// Initialize position with collateral
_13
pub fun deposit(collateralVault: @FungibleToken.Vault)
_13
_13
// Withdraw specified amount
_13
pub fun withdraw(amount: UFix64): @FungibleToken.Vault
_13
_13
// Close position and return all value
_13
pub fun liquidate(): @FungibleToken.Vault
_13
_13
// Get current position value
_13
pub fun getBalance(): UFix64
_13
}

Available implementations:

  • TracerStrategy: Leveraged yield farming using ALP + ERC4626 vaults
  • mUSDCStrategy: Cross-chain yield farming via Flow-EVM bridge

Learn more in Strategies.

StrategyComposer & StrategyFactory​

The StrategyComposer creates configured strategy instances, while the StrategyFactory maintains the registry of available composers.

What it does: StrategyComposer assembles DeFi Actions components (swap connectors, sink/source connectors) into a complete strategy. StrategyFactory provides a registry where users can discover available strategies and create instances with pre-configured connectors for their chosen yield approach.

Strategy creation flow:


_14
sequenceDiagram
_14
participant User
_14
participant Factory as StrategyFactory
_14
participant Composer as StrategyComposer
_14
participant Strategy
_14
_14
User->>Factory: getStrategyNames()
_14
Factory-->>User: ["TracerStrategy", "mUSDCStrategy"]
_14
_14
User->>Factory: createStrategy("TracerStrategy", collateral)
_14
Factory->>Composer: compose(collateral)
_14
Composer->>Composer: Configure connectors
_14
Composer->>Strategy: Create new strategy instance
_14
Strategy-->>User: Strategy capability

AutoBalancer​

The AutoBalancer monitors yield token holdings and triggers rebalancing when thresholds are exceeded.

What it does: AutoBalancer holds yield tokens in ERC4626 vaults, monitors value ratio (current holdings vs. historical deposits), triggers rebalancing when ratio exceeds 95%-105% range, withdraws excess profits or requests deficit recovery, and self-schedules next rebalancing execution.

Rebalancing thresholds:


_10
Ratio = Current Value / Historical Deposit Value
_10
_10
Upper Threshold: 105% → Excess profits, withdraw and deposit to position
_10
Lower Threshold: 95% → Deficit detected, request funds from position
_10
Target Range: 95%-105% → No action needed

Rebalancing flow:


_26
sequenceDiagram
_26
participant Scheduler
_26
participant AB as AutoBalancer
_26
participant Vault as ERC4626
_26
participant Swap as SwapConnectors
_26
participant Pos as ALP Position
_26
_26
Scheduler->>AB: rebalance()
_26
AB->>Vault: getBalance()
_26
Vault-->>AB: currentValue
_26
AB->>AB: Calculate ratio
_26
_26
alt Ratio > 105% (Excess)
_26
AB->>Vault: withdraw(excess)
_26
Vault-->>AB: yieldTokens
_26
AB->>Swap: swap(yieldTokens → FLOW)
_26
Swap-->>AB: FLOW
_26
AB->>Pos: deposit(FLOW)
_26
else Ratio < 95% (Deficit)
_26
AB->>Pos: Request deficit
_26
Pos->>Swap: swap(MOET → yieldTokens)
_26
Swap-->>AB: yieldTokens
_26
AB->>Vault: deposit(yieldTokens)
_26
end
_26
_26
AB->>Scheduler: scheduleNextRebalance()

Learn more in AutoBalancer.

ALP Position Integration​

Each FYV vault maintains a capability to an ALP Position resource for leveraged borrowing.

What it does: The Position holds collateral deposited by the strategy, borrows MOET against the collateral (up to 80% of value), maintains health factor (target: 1.3), and provides liquidity source for deficit recovery.

Health factor management:


_10
Health Factor = (Collateral Value × Collateral Factor) / Debt Value
_10
_10
Safe Range: 1.1 - 1.5
_10
Target: 1.3 (optimal leverage)
_10
Liquidation Trigger: < 1.0

Position lifecycle:

  1. Strategy deposits FLOW collateral
  2. Position borrows MOET (maintaining HF = 1.3)
  3. Strategy converts MOET to yield tokens
  4. AutoBalancer deposits yield tokens to ERC4626
  5. When rebalancing triggers:
    • Excess: Withdraw yield → swap → deposit more collateral
    • Deficit: Borrow more MOET → swap → deposit yield tokens

Learn more: ALP Documentation

DeFi Actions Connectors​

FYV uses DeFi Actions as composable building blocks for complex yield strategies.

SwapConnectors​

Handle token conversions between MOET, collateral, and yield tokens.

Available implementations:

  • UniswapV3SwapConnectors: Swap via Uniswap V3 pools
  • TeleportCustodySwapConnectors: Swap via Teleport custody connectors

Example usage:


_10
// Swap MOET → YieldToken
_10
let yieldTokens <- swapConnector.swap(
_10
vaultIn: <-moetVault,
_10
amountOutMin: 95.0 // 5% slippage tolerance
_10
)

Sink/Source Connectors​

Handle deposits and withdrawals from yield-bearing protocols.

ERC4626SinkConnectors: Deposit to and withdraw from ERC4626-compatible vaults (standard interface for yield-bearing vaults).

TopUpSource/DrawDownSink: Bridge between ALP positions and FYV strategies for automated liquidity provision.

Example usage:


_10
// Deposit to ERC4626 vault
_10
sinkConnector.deposit(vault: <-yieldTokens)
_10
_10
// Withdraw from ERC4626 vault
_10
let withdrawn <- sourceConnector.withdraw(amount: 100.0)

Learn more in DeFi Actions.

Automated Scheduling System​

FYV implements a self-scheduling mechanism for perpetual rebalancing without external coordination.

Self-Scheduling Mechanism​

Initial setup:

  1. User creates YieldVault
  2. Vault creation atomically:
    • Issues capability to AutoBalancer
    • Registers in SchedulerRegistry
    • Schedules first rebalance via FlowTransactionScheduler

Perpetual execution:

  1. Scheduler executes rebalance() at scheduled time
  2. AutoBalancer performs rebalancing logic
  3. AutoBalancer calls scheduleNextRebalance() for 60 seconds later
  4. Process repeats indefinitely

Atomic registration: If any step fails during vault creation (capability issue, registration failure, or scheduling error), the entire transaction reverts, ensuring no orphaned or incomplete vaults.

Supervisor Recovery System​

The Supervisor handles vaults that become stuck or fail to self-schedule.

What it does: Supervisor scans SchedulerRegistry for pending vaults (max 50 per batch), attempts to re-seed scheduling for stuck vaults, automatically reschedules itself if more work remains, and provides bounded processing to prevent timeout.

Recovery flow:


_10
graph TD
_10
Scheduler[Scheduler Triggers] --> Supervisor[Supervisor.recover]
_10
Supervisor --> Check{Pending<br/>vaults?}
_10
Check -->|Yes| Batch[Get up to 50 vaults]
_10
Batch --> Process[Process each vault]
_10
Process --> Reschedule[Schedule for each vault]
_10
Reschedule --> More{More<br/>pending?}
_10
More -->|Yes| SelfSchedule[Schedule next Supervisor run]
_10
More -->|No| Done[Complete]
_10
Check -->|No| Done

Learn more in Scheduling System.

Cross-Chain Architecture​

FYV supports cross-chain yield opportunities through Flow's EVM bridge.

Flow-EVM Bridge Integration​

What it does: FlowEVMBridgeConfig manages token escrow and minting, CadenceOwnedAccounts enable Cadence contracts to control EVM addresses, ERC4626 vaults provide Ethereum-compatible yield opportunities, and DeFi Connectors abstract the bridging complexity.

Token flow:


_10
Cadence (Flow) → Bridge Locks → EVM Mints → ERC4626 Deposit → Yield Accrual
_10
Yield Accrual → ERC4626 Withdraw → Bridge Burns → Cadence Unlocks → User Receives

Example: mUSDCStrategy

  1. User deposits USDC (Cadence token)
  2. Bridge locks USDC in escrow
  3. EVM contract mints bridged USDC
  4. Strategy deposits to ERC4626 vault on EVM side
  5. Yield accrues in EVM vault
  6. Rebalancing withdraws from EVM vault
  7. Bridge burns EVM tokens and unlocks Cadence tokens
  8. Strategy returns tokens to user

Learn more in Cross-Chain Integration.

Contract Deployment​

FYV consists of five primary contracts deployed on Flow:

ContractPurpose
FlowYieldVaultsMain orchestration managing user positions and strategy lifecycle
FlowYieldVaultsStrategiesImplementation of concrete strategies (TracerStrategy, mUSDCStrategy)
FlowYieldVaultsAutoBalancersRebalancing logic and balance management
FlowYieldVaultsSchedulerScheduled transaction management and recovery
FlowYieldVaultsSchedulerRegistryRegistry tracking all vaults for automated operations

Additionally, FlowYieldVaultsClosedBeta manages access control during beta phase.

Deployment addresses:

  • Testnet: 0xd27920b6384e2a78
  • Mainnet: 0xb1d63873c3cc9f79

Security Considerations​

Access Control: Vaults are owned resources stored in user accounts—only the account owner can access vault operations.

Capability Model: Strategies hold capabilities to AutoBalancers and Positions, not direct references, enabling revocability and access control.

Atomic Operations: Vault creation and registration happen atomically—if any step fails, entire transaction reverts.

Health Factor Monitoring: ALP Positions enforce minimum health factors, preventing over-leveraging.

Slippage Protection: Swap connectors include amountOutMin parameters to prevent sandwich attacks.

Bounded Processing: Supervisor processes max 50 vaults per execution to prevent timeout.

Summary​

FYV's architecture achieves automated leveraged yield farming through separation of concerns where YieldVault manages user interface and lifecycle, Strategy implements yield generation logic, AutoBalancer handles continuous optimization, Position provides leveraged borrowing, and Scheduler enables automated execution.

The modular design allows new strategies to be added without changing core vault logic, enabling composability through DeFi Actions components, supporting cross-chain yield through standardized interfaces, and maintaining security through Flow's resource-oriented programming model.

Key architectural principles:

  1. Resource ownership: Users own vaults; vaults own capabilities
  2. Capability-based security: Limited access through capabilities, not references
  3. Atomic operations: All-or-nothing transaction guarantees
  4. Self-scheduling: Perpetual automation without external dependencies
  5. Modularity: Strategies can be swapped and composed independently

Next Steps​

Key Takeaway

FYV's architecture separates user position management (YieldVault) from yield strategy (Strategy) and automated optimization (AutoBalancer). This modularity enables complex yield generation while maintaining clean separation of concerns and allowing new strategies to be added easily.

Rate this page