Aave V3 Protocol Documentation

Comprehensive control flow diagrams and amount transformations for debugging Aave V3 Market operations.

Quick Navigation

Core Operation Flows

Operation

Entry Point

Key Transformation

Supply

Pool.supply(asset, amount, onBehalfOf, referralCode)

amount → scaledBalance

Withdraw

Pool.withdraw(asset, amount, to)

scaledBalance → amount

Borrow

Pool.borrow(asset, amount, interestRateMode, referralCode, onBehalfOf)

amount → scaledDebt

Repay

Pool.repay(asset, amount, interestRateMode, onBehalfOf)

scaledDebt → amount

Liquidation

Pool.liquidationCall(collateralAsset, debtAsset, user, debtToCover, receiveAToken)

debtValue → collateralAmount

Amount Transformations Reference

For Automated Agents

Debugging Workflow

  1. Identify the operation being investigated (supply, borrow, liquidation, etc.)

  2. Load the flow file for that operation to see the execution path

  3. Follow the transformations - refer to the transformations/index.md for detailed math

  4. Check validation - each flow shows all validation checks and error conditions

  5. Verify state changes - see exactly what storage is modified

Common Debugging Patterns

**Investigating balance discrepancy:**
1. Check [Collateral Transformations](./transformations/index.md#collateral-token-transformations)
2. Verify rounding mode (v1-3 vs v4+)
3. Check index at specific block height
4. Look for treasury accruals

**Investigating liquidation:**
1. Check [Liquidation Flow](./flows/liquidation.md)
2. Verify health factor calculation in [E-Mode](./transformations/index.md#e-mode-calculations)
3. Check collateral conversion math
4. Verify close factor logic

**Investigating failed transaction:**
1. Find the operation flow
2. Check "Error Conditions" section
3. Match error to validation check
4. See validation logic in Solidity

Solidity Source Mapping

Each flow file includes:

  • File paths to actual contract source

  • Function names with line-level references

  • Complete code snippets showing actual implementation

  • Transformation markers linking to detailed math

Example:

// File: contracts/protocol/libraries/logic/SupplyLogic.sol
// Function: executeSupply()

uint256 scaledAmount = amount.rayDiv(index);  // [TRANSFORMATION]
// Refer to transformations/index.md for:
// - Exact formula
// - Solidity implementation
// - Version differences
// - Edge cases

Document Structure

docs/aave/
├── README.md                          # This file - navigation hub
├── AGENTS.md                          # Instructions for automated agents
├── flows/                             # Individual operation flows
│   ├── supply.md                      # Supply execution flow
│   ├── supply_with_permit.md           # Supply with permit
│   ├── withdraw.md                    # Withdraw execution flow
│   ├── borrow.md                      # Borrow execution flow
│   ├── repay.md                       # Repay execution flow
│   ├── repay_with_atokens.md          # Repay with aTokens
│   ├── repay_with_permit.md           # Repay with permit
│   ├── liquidation.md                 # Liquidation execution flow
│   ├── collateral_management.md       # Collateral enable/disable
│   ├── emode_management.md            # E-Mode category management
│   ├── flash_loan.md                  # Flash loan (with callback)
│   ├── flash_loan_simple.md           # Simple flash loan
│   ├── gho_borrowing.md               # GHO borrowing
│   ├── gho_discount.md                # GHO discount mechanism
│   ├── rewards_claiming.md            # Rewards claiming
│   ├── position_manager.md            # Position manager operations
│   ├── eliminate_deficit.md           # Umbrella deficit elimination
│   ├── stk_aave_staking.md           # stkAAVE staking
│   ├── stk_aave_unstaking.md          # stkAAVE unstaking
│   └── stk_aave_slashing.md           # stkAAVE slashing
└── transformations/                   # Amount transformation reference
    └── index.md                       # All math operations

Key Concepts

Scaled Balances vs. Unscaled Amounts

Collateral (aTokens):

  • Storage: Scaled balance (_scaledBalance[user])

  • Precision: RAY (27 decimals)

  • Conversion: unscaled = scaled.rayMul(liquidityIndex)

  • Interest: Automatic via index growth

Variable Debt:

  • Storage: Scaled balance (_scaledBalance[user])

  • Precision: RAY (27 decimals)

  • Conversion: unscaled = scaled.rayMul(borrowIndex)

  • Interest: Automatic via index growth

Stable Debt:

  • Storage: Principal + timestamp

  • Precision: WAD (18 decimals)

  • Conversion: Calculate interest on-demand

  • Interest: Compounded at borrow/repay time

Index Updates

// Liquidity Index (for collateral)
liquidityIndex[t] = liquidityIndex[t-1].rayMul(1 + rate * timeDelta / YEAR)

// Borrow Index (for variable debt)
borrowIndex[t] = borrowIndex[t-1].rayMul(compoundInterest(rate, timeDelta))

See Interest Accrual for full details.

Rounding Modes

Operation

v1-3

v4+

Reason

aToken Mint

rayDiv (half-up)

rayDivFloor

Prevent rounding up debt

aToken Burn

rayDiv (half-up)

rayDivCeil

Ensure full repayment

vToken Mint

rayDiv (half-up)

rayDivCeil

Round up debt issued

vToken Burn

rayDiv (half-up)

rayDivFloor

Round down debt reduction

See Version Differences.

Aave V3 Contract Addresses (Mainnet)

Pool Proxy:           0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2
PoolAddressesProvider: 0x2f39d218133AFaB8F2B819B1066c7E434Ad94E9e
Oracle:               0x54586bE62E3c3580375aE3723C145253060Ca0C2

Validation

All Mermaid diagrams in this documentation are validated using Maid:

# Validate all diagrams
npx maid .

# Auto-fix issues
npx maid --fix .

Contributing

When adding new flows or transformations:

  1. Include complete Solidity code snippets

  2. Add links between flows and transformations

  3. Document all error conditions

  4. Show version differences where applicable

  5. Run npx maid --fix before committing