aave-v4-architecture

name	Aave V4 Architecture
description	This skill should be used when the user asks about "Aave V4 architecture", "hub-and-spoke", "Hub contract", "Spoke contract", "unified liquidity layer", or needs a high-level understanding of how Aave V4 works.
version	0.1.0

Aave V4 Architecture

Aave V4 introduces a unified liquidity layer with a modular hub-and-spoke architecture that enhances capital efficiency, scalability, and risk management.

Overview

┌──────────────────────────────────────────────────────────────┐
│                    AAVE V4 HUB-AND-SPOKE                     │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│      ┌─────────────────┐     ┌─────────────────┐             │
│      │ Liquidity       │     │ Borrowers       │             │
│      │ Providers       │     │                 │             │
│      └────────┬────────┘     └────────┬────────┘             │
│               │                       │                      │
│               ▼                       ▼                      │
│      ┌─────────────┐         ┌─────────────┐                 │
│      │   Spoke 1   │         │   Spoke 2   │                 │
│      │  (crypto)   │         │   (RWA)     │                 │
│      └──────┬──────┘         └──────┬──────┘                 │
│             │                       │                        │
│             └───────────┬───────────┘                        │
│                         ▼                                    │
│               ┌─────────────────┐                            │
│               │       HUB       │                            │
│               │  (Liquidity +   │                            │
│               │   Accounting)   │                            │
│               └─────────────────┘                            │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Key Architectural Changes from V3

V3	V4
Single Pool contract	Hub + multiple Spokes
aTokens + DebtTokens	Share-based accounting
Static risk parameters	Dynamic Risk Configuration
Fixed close factor (50%)	Target Health Factor liquidation
Single interest rate	Base Rate + Risk Premium

Core Components

Hub

The Hub is the immutable central coordinator for liquidity management:

contract Hub is IHub, AccessManaged {
    // Asset management
    mapping(uint256 assetId => Asset) internal _assets;

    // Spoke management per asset
    mapping(uint256 assetId => mapping(address spoke => SpokeData)) internal _spokes;

    // Core operations (callable only by authorized Spokes)
    function add(uint256 assetId, uint256 amount) external returns (uint256 shares);
    function remove(uint256 assetId, uint256 amount, address to) external returns (uint256 shares);
    function draw(uint256 assetId, uint256 amount, address to) external returns (uint256 shares);
    function restore(uint256 assetId, uint256 drawnAmount, PremiumDelta calldata premiumDelta) external returns (uint256);
}

Hub Responsibilities:

• Maintains registry of authorized Spokes
• Manages liquidity caps for Spokes
• Enforces accounting invariants
• Provides emergency stop functionality
• Tracks drawn shares, added shares, and premium shares

Spoke

Spokes are upgradeable and handle user-facing operations:

abstract contract Spoke is ISpoke, Multicall, AccessManagedUpgradeable {
    address public immutable ORACLE;

    // Reserve management
    mapping(uint256 reserveId => Reserve) internal _reserves;

    // User positions
    mapping(address user => mapping(uint256 reserveId => UserPosition)) internal _userPositions;

    // Dynamic risk configuration
    mapping(uint256 reserveId => mapping(uint24 dynamicConfigKey => DynamicReserveConfig)) internal _dynamicConfig;

    // User operations
    function supply(uint256 reserveId, uint256 amount, address onBehalfOf) external returns (uint256, uint256);
    function withdraw(uint256 reserveId, uint256 amount, address onBehalfOf) external returns (uint256, uint256);
    function borrow(uint256 reserveId, uint256 amount, address onBehalfOf) external returns (uint256, uint256);
    function repay(uint256 reserveId, uint256 amount, address onBehalfOf) external returns (uint256, uint256);
    function liquidationCall(...) external;
}

Spoke Responsibilities:

• User-facing supply, withdraw, borrow, repay operations
• Managing user data structures and configurations
• Risk management (collateral, liquidation thresholds)
• Oracle interactions
• Position Manager authorization

Position Manager

Gateway contracts that can operate on behalf of users:

// Users authorize Position Managers
function setUserPositionManager(address manager, bool approved) external;

// Position Manager can then call user operations
spoke.supply(reserveId, amount, user);  // onBehalfOf = user

Asset vs Reserve

┌──────────────────────────────────────────────────────────────┐
│                    ASSET vs RESERVE                          │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  ASSET (Hub-level)          RESERVE (Spoke-level)            │
│  ─────────────────          ──────────────────────           │
│  • assetId: uint256         • reserveId: uint256             │
│  • One per underlying       • One per Spoke per Asset        │
│  • Hub manages liquidity    • Spoke manages risk params      │
│  • Global accounting        • User positions stored here     │
│                                                              │
│  Example:                                                    │
│  Hub has USDC (assetId=0)                                    │
│  Spoke A has USDC reserve (reserveId=0, assetId=0)           │
│  Spoke B has USDC reserve (reserveId=0, assetId=0)           │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Data Structures

Asset (Hub)

struct Asset {
    uint256 liquidity;           // Total liquidity in Hub
    uint256 deficitRay;          // Bad debt (ray precision)
    uint256 swept;               // Swept to reinvestment
    uint256 addedShares;         // Total supply shares
    uint256 drawnShares;         // Total borrow shares
    uint256 premiumShares;       // Premium interest shares
    uint256 premiumOffsetRay;    // Premium offset tracking
    uint120 drawnIndex;          // Borrow index
    address underlying;          // Underlying token
    uint40 lastUpdateTimestamp;
    uint8 decimals;
    uint96 drawnRate;            // Current borrow rate
    address irStrategy;          // Interest rate strategy
    uint256 realizedFees;        // Fees collected
    address reinvestmentController;
    address feeReceiver;
    uint16 liquidityFee;         // Fee on liquidity
}

Reserve (Spoke)

struct Reserve {
    address underlying;
    IHubBase hub;
    uint16 assetId;
    uint8 decimals;
    uint24 dynamicConfigKey;     // Current risk config
    uint24 collateralRisk;       // Risk premium factor
    ReserveFlags flags;          // paused, frozen, borrowable, etc.
}

UserPosition (Spoke)

struct UserPosition {
    uint256 suppliedShares;
    uint256 drawnShares;
    uint256 premiumSharesRay;
    uint256 premiumOffsetRay;
    uint24 dynamicConfigKey;     // Position's risk config snapshot
}

Key Concepts

Share-Based Accounting

V4 uses shares instead of tokens:

• Added Shares: Supply position (like aTokens)
• Drawn Shares: Borrow position (like debt tokens)
• Premium Shares: Risk premium interest

// Convert shares to assets
uint256 assets = hub.previewRemoveByShares(assetId, shares);

// Convert assets to shares
uint256 shares = hub.previewAddByAssets(assetId, assets);

Interest Model

V4 separates interest into:

1. Base Rate: Determined by utilization (Hub-level)
2. Risk Premium: Based on collateral quality (user-level)

Total User Rate = Base Rate × (1 + Risk Premium)

Health Factor

Health Factor = Σ(Collateral × Collateral Factor) / Total Debt

• Liquidatable when HF < 1
• Target HF after liquidation is configurable

Protocol Flow

Supply Flow

User → Spoke.supply() → Hub.add()
  1. Spoke transfers underlying to Hub
  2. Hub mints added shares to Spoke
  3. Spoke records user's supply shares

Borrow Flow

User → Spoke.borrow() → Hub.draw()
  1. Validate HF will remain >= 1
  2. Hub mints drawn shares to Spoke
  3. Hub transfers underlying to user
  4. Spoke records user's drawn shares + premium

Repay Flow

User → Spoke.repay() → Hub.restore()
  1. User transfers underlying to Hub
  2. Hub burns drawn shares and applies premium delta
  3. Spoke updates user position

Skills Reference

Skill	Description
aave-v4-hub	Hub contract operations and liquidity management
aave-v4-spoke	Spoke operations (supply, borrow, repay, withdraw)
aave-v4-risk-premium	Risk Premium system and collateral quality
aave-v4-dynamic-config	Dynamic Risk Configuration
aave-v4-liquidation	Redesigned liquidation engine
aave-v4-position-manager	Position Manager gateways

Reference Files

• src/hub/Hub.sol - Hub contract
• src/spoke/Spoke.sol - Spoke contract
• src/hub/interfaces/IHub.sol - Hub interface
• src/spoke/interfaces/ISpoke.sol - Spoke interface
• docs/overview.md - Protocol overview