Aave V4 Dynamic Config

Config Key System

// Each reserve tracks current and historical configs
struct Reserve {
    // ...
    uint24 dynamicConfigKey;  // Current active config key
}

// Mapping of configs per reserve
mapping(uint256 reserveId => mapping(uint24 configKey => DynamicReserveConfig)) internal _dynamicConfig;

// User positions store their bound config key
struct UserPosition {
    // ...
    uint24 dynamicConfigKey;  // Position's config snapshot
}

Dynamic Reserve Config

struct DynamicReserveConfig {
    uint16 collateralFactor;    // CF: max borrow power (BPS, e.g., 82_50 = 82.5%)
    uint16 maxLiquidationBonus; // Max LB (e.g., 105_00 = 5% bonus)
    uint16 liquidationFee;      // Protocol fee on liquidation (BPS)
}

Config Keys

┌──────────────────────────────────────────────────────────────┐
│                     CONFIG KEYS                              │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  Time →                                                      │
│  ┌─────────┬─────────┬─────────┬─────────┐                   │
│  │ Key 0   │ Key 1   │ Key 2   │ Key 3   │ ← Reserve keys    │
│  │ CF=85%  │ CF=82%  │ CF=80%  │ CF=78%  │                   │
│  └────┬────┴────┬────┴────┬────┴────┬────┘                   │
│       │         │         │         │                        │
│  User A binds   │    User B binds   │                        │
│  to Key 0       │    to Key 2       │                        │
│                 │                   │                        │
│  User A still   │              User C binds                  │
│  uses CF=85%    │              to Key 3                      │
│                                                              │
│  Max keys: 2^24 = 16M                                        │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Adding New Configurations

/// @notice Add a new dynamic config (increments key)
function addDynamicReserveConfig(
    uint256 reserveId,
    DynamicReserveConfig calldata config
) external restricted returns (uint24 newKey) {
    Reserve storage reserve = _getReserve(reserveId);
    _validateDynamicReserveConfig(config);

    newKey = reserve.dynamicConfigKey + 1;
    require(newKey <= MAX_ALLOWED_DYNAMIC_CONFIG_KEY, MaxConfigKeysReached());

    reserve.dynamicConfigKey = newKey;
    _dynamicConfig[reserveId][newKey] = config;

    emit AddDynamicReserveConfig(reserveId, newKey, config);
}

/// @notice Update an existing config (affects bound positions)
function updateDynamicReserveConfig(
    uint256 reserveId,
    uint24 configKey,
    DynamicReserveConfig calldata config
) external restricted {
    require(configKey <= _reserves[reserveId].dynamicConfigKey, InvalidConfigKey());
    _validateDynamicReserveConfig(config);

    _dynamicConfig[reserveId][configKey] = config;

    emit UpdateDynamicReserveConfig(reserveId, configKey, config);
}

Position Binding

When Config Key Updates

The position's configKey snapshot updates on risk-increasing actions:

Automatic Rebinding

function _refreshUserDynamicConfig(address user) internal {
    PositionStatus storage status = _positionStatus[user];

    // Check if position can use latest config
    uint256 collateralBitmap = status.usingAsCollateralBitmap;
    while (collateralBitmap != 0) {
        uint256 reserveId = _getNextReserveId(collateralBitmap);
        collateralBitmap = _clearBit(collateralBitmap, reserveId);

        uint24 latestKey = _reserves[reserveId].dynamicConfigKey;
        UserPosition storage position = _userPositions[user][reserveId];

        // Rebind to latest key
        position.dynamicConfigKey = latestKey;
    }
}

Safety Guard

If latest config would make position unhealthy, the action reverts:

function _validateAndRebind(address user) internal {
    // Temporarily bind to latest config
    _refreshUserDynamicConfig(user);

    // Check health with latest config
    uint256 hf = getUserHealthFactor(user);

    if (hf < HEALTH_FACTOR_LIQUIDATION_THRESHOLD) {
        // Latest config would make position unhealthy
        revert UnhealthyPosition();
    }

    // Position is healthy with latest config - keep it bound
}

User-Initiated Updates

Users can voluntarily update their config:

/// @notice Update user's config keys to latest
function updateUserDynamicConfig() external {
    _refreshUserDynamicConfig(msg.sender);

    // Validate health factor
    require(
        getUserHealthFactor(msg.sender) >= HEALTH_FACTOR_LIQUIDATION_THRESHOLD,
        UnhealthyPosition()
    );

    emit UpdateUserDynamicConfig(msg.sender);
}

Governance Operations

Creating New Config

// Scenario: Governance wants to lower CF from 85% to 80%

// Step 1: Add new config with lower CF
uint24 newKey = spoke.addDynamicReserveConfig(
    reserveId,
    DynamicReserveConfig({
        collateralFactor: 80_00,      // 80% (was 85%)
        maxLiquidationBonus: 105_00,
        liquidationFee: 10_00
    })
);

// Step 2: Existing positions keep using old CF
// Step 3: New positions use new CF
// Step 4: Existing users rebind on their next risk-increasing action

Force-Updating Positions

In exceptional cases, governance can force-update specific positions:

/// @notice Force update a user's config to latest
function forceUpdateUserDynamicConfig(address user) external restricted {
    _refreshUserDynamicConfig(user);

    // Note: This might make the position liquidatable
    // Use only when necessary for protocol safety
}

Updating Old Configs

Governance can modify historical configs (affects bound positions):

// Scenario: Security issue found, need to lower CF on all configs

for (uint24 key = 0; key <= latestKey; key++) {
    spoke.updateDynamicReserveConfig(
        reserveId,
        key,
        DynamicReserveConfig({
            collateralFactor: 70_00,  // Emergency reduction
            maxLiquidationBonus: 110_00,
            liquidationFee: 10_00
        })
    );
}

Health Factor Calculation

Health factor uses the position's bound configKey:

function getUserHealthFactor(address user) public view returns (uint256) {
    uint256 totalCollateralValue = 0;
    uint256 totalDebtValue = 0;

    // For each collateral reserve
    uint256 collateralBitmap = _positionStatus[user].usingAsCollateralBitmap;
    while (collateralBitmap != 0) {
        uint256 reserveId = _getNextReserveId(collateralBitmap);
        collateralBitmap = _clearBit(collateralBitmap, reserveId);

        UserPosition storage position = _userPositions[user][reserveId];

        // Use position's bound config, not latest
        DynamicReserveConfig storage config = _dynamicConfig[reserveId][position.dynamicConfigKey];

        uint256 supplyValue = _getPositionSupplyValue(user, reserveId);
        uint256 adjustedValue = supplyValue.percentMul(config.collateralFactor);
        totalCollateralValue += adjustedValue;
    }

    // ... calculate debt and return HF
}

Query Functions

/// @notice Get current active config key for reserve
function getReserveDynamicConfigKey(uint256 reserveId) external view returns (uint24) {
    return _reserves[reserveId].dynamicConfigKey;
}

/// @notice Get config for a specific key
function getDynamicReserveConfig(
    uint256 reserveId,
    uint24 configKey
) external view returns (DynamicReserveConfig memory) {
    return _dynamicConfig[reserveId][configKey];
}

/// @notice Get user's bound config key for a reserve
function getUserDynamicConfigKey(
    address user,
    uint256 reserveId
) external view returns (uint24) {
    return _userPositions[user][reserveId].dynamicConfigKey;
}

Events

event AddDynamicReserveConfig(
    uint256 indexed reserveId,
    uint24 indexed configKey,
    DynamicReserveConfig config
);

event UpdateDynamicReserveConfig(
    uint256 indexed reserveId,
    uint24 indexed configKey,
    DynamicReserveConfig config
);

event UpdateUserDynamicConfig(address indexed user);

Benefits

┌──────────────────────────────────────────────────────────────┐
│           DYNAMIC CONFIG BENEFITS                            │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  For Governance:                                             │
│  • Adjust parameters without harming existing users          │
│  • Gradual migration to new risk settings                    │
│  • Emergency changes when needed (via update)                │
│                                                              │
│  For Users:                                                  │
│  • No surprise liquidations from parameter changes           │
│  • Old positions maintain their terms                        │
│  • Voluntary upgrade to new configs                          │
│                                                              │
│  For Protocol:                                               │
│  • More agile risk management                                │
│  • Better user experience                                    │
│  • Reduced governance friction                               │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Reference Files

• src/spoke/Spoke.sol - Dynamic config implementation
• src/spoke/interfaces/ISpoke.sol - DynamicReserveConfig struct
• docs/overview.md - Dynamic configuration design