Skip to content

aave

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

aave

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
flows
flows
 
 
transformations
transformations
 
 
README.md
README.md
 
 

README.md

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