Architecture

System Overview

Kana runs two parallel vault pipelines — one for USDC and one for WSEI — sharing the same architecture, permission model, and keeper infrastructure. Yei Finance and Takara serve both vaults; Morpho is USDC-only and Feather is WSEI-only.

Design Principles

Shared Vault Architecture

Kana uses shared ERC-4626 vaults where all user funds for a given asset are pooled together and managed by a single strategy. Both the USDC vault and WSEI vault follow this identical design.

Benefits of shared vault:

• ⚡ Lower gas costs — one harvest transaction benefits all users instead of one per user
• 🔗 Better composability — vault share tokens (kUSDC, kSEI) are fungible and can be used in other DeFi protocols
• 🛠️ Simpler architecture — fewer contracts to deploy and maintain
• 💰 Efficient rebalancing — rebalance once for the entire pool

Trade-offs:

• All users share the same strategy and allocation
• Withdrawals must be processed proportionally from all protocols

One Strategy Per Asset

Each vault has exactly one active strategy at a time. The strategy manages a single asset across multiple protocols. This keeps the vault simple and the strategy focused.

Swappable Strategies

The vault owner can migrate to a new strategy:

Vault → Strategy A (active)
Vault → Strategy B (new) ← migrate here

Migration withdraws all funds from Strategy A and deposits into Strategy B. This allows upgrading strategy logic without redeploying the vault or requiring users to withdraw.

Proportional Withdrawal

When a user withdraws, funds are pulled from all protocols proportionally to the current allocation. This prevents:

• Draining liquidity from a single protocol
• Creating imbalanced positions
• Forced rebalancing after large withdrawals

Dynamic Yield Sources

Both strategies use a dynamic yield sources system instead of hardcoded protocol allocations:

Key features:

• Support for up to 10 protocols (MAX_YIELD_SOURCES)
• Add/remove yield sources on the fly
• Enable/disable individual sources
• Update allocation splits dynamically (subject to cooldown)

Allocation splits:

• Set in basis points (1 bp = 0.01%)
• Total must equal 10,000 (100%)
• Subject to 1-hour cooldown between changes

Dynamic DEX Router Registry

Each strategy maintains a registry of DEX routers for reward token swaps:

Key features:

• Add/remove routers on the fly
• Switch active router without redeploying
• Support for both V2 and V3 style routers
• Currently supports: DragonSwap (V2), Sailor (V3)

Permission Model

Role	Vault Permissions	Strategy Permissions
Owner	Set strategy, keeper, guardian, fee recipient, pause/unpause	Manage yield sources, splits, routers, cooldowns, pause/unpause
Keeper	Trigger harvest	Trigger harvest, rebalance, claim rewards
Guardian	Pause	Pause

Security hierarchy:

• Owner has full control (should be multisig in production)
• Keeper can only trigger operations, not change configuration
• Guardian can only pause, cannot access funds or change settings

Component Interaction

Component	Role	Owner
KanaVault	USDC deposit/withdraw, share accounting, performance fee	Protocol admin (multisig)
USDCStrategy	USDC allocation across protocols (Yei, Takara, Morpho), reward harvesting	Protocol admin (multisig)
SEIVault	WSEI deposit/withdraw, share accounting, performance fee	Protocol admin (multisig)
SEIStrategy	WSEI allocation across protocols (Yei, Takara, Feather), reward harvesting	Protocol admin (multisig)
Keeper Bot	Off-chain automation (harvest, rebalance) for both vaults	Operator
Frontend	User interface	—

Contract Relationships

Both vaults are functionally identical — SEIVault is the same contract as KanaVault instantiated with WSEI as the underlying asset. Both strategy contracts share the same logic; they differ only in the configured yield sources (Morpho for USDC, Feather for WSEI).

Data Flow

All flows below apply identically to both the USDC vault/strategy and the WSEI vault/strategy.

Deposit Flow

User → Vault.deposit()
  → Vault mints vault shares (kUSDC or kSEI)
  → Vault transfers underlying asset to Strategy
  → Strategy.deposit()
    → Strategy splits asset per allocation
    → Protocols (Yei, Takara, Morpho/Feather)

Withdrawal Flow

User → Vault.withdraw()
  → Vault burns vault shares
  → Vault calls Strategy.withdraw()
    → Strategy withdraws proportionally from protocols
    → Strategy returns underlying asset to Vault
  → Vault transfers underlying asset to User

Harvest Flow

Keeper → Strategy.harvest(minAmountsOut[])
  → Claim rewards from all enabled protocols
  → Swap rewards to underlying asset (with slippage protection)
  → Report profit to Vault
  → Vault takes 10% performance fee
  → Strategy redeploys asset to protocols

Rebalance Flow

Keeper → Strategy.rebalance()
  → Withdraw all funds from protocols
  → Redeploy per current splits
  → (Subject to 1-hour cooldown)

Upgrade Strategy

The architecture allows for non-disruptive upgrades:

1. New strategy deployment: Deploy improved strategy contract
2. Strategy migration: Owner calls vault.setStrategy(newStrategy)
3. Automatic transfer: Vault withdraws from old strategy, deposits to new
4. No user action: Existing vault shares continue to work seamlessly

This allows fixing bugs, adding features, or optimizing logic without requiring users to withdraw and redeposit.