defi-conventions

name	defi-conventions
description	DeFi conventions, decimal handling, and protocol integration patterns used in this project. Load when working with token amounts, price conversions, or protocol interactions.
user-invokable	false

Decimal Conventions

Value	Decimals	Example
USDC amounts	6	1000e6 = $1000
WETH amounts	18	1e18 = 1 ETH
Chainlink prices	8	3000e8 = $3000
Aave ray (rates + indices)	27	1e27 = 1.0 in getReserveNormalizedIncome
Internal calculations	18	Always normalize
Basis points	0	500 = 5%, 10000 = 100%
sqrtPriceX96	Q64.96	Fixed-point, NOT a regular price

Conversion Rules

• Chainlink → Internal: price * 10^(18-8) = price * 1e10
• USDC → Internal: amount * 10^(18-6) = amount * 1e12
• Aave ray → BPS: ray * 10_000 / 1e27
• Aave ray → Fractional: ray / 1e27
• BPS → Fraction: bps / 10000
• sqrtPriceX96 → Price: (sqrtPriceX96 / 2^96)^2 adjusted for token decimals

Protocol Integration

Aerodrome (Uniswap V3 on Base)

• Pool: concentrated liquidity WETH/USDC (0.05% fee tier)
• Positions tracked by NFT token ID
• slot0() returns (sqrtPriceX96, tick, ...)
• positions(tokenId) returns (token0, token1, tickLower, tickUpper, liquidity, ...)
• Tick spacing: 1 (for 0.01% pools) or 100 (for 1% pools)

Aave V3 (money-market hedge)

• Hedge = USDC supply + WETH variable-rate borrow, looped via flashLoanSimple
• getUserAccountData(user) returns (totalCollateralBase, totalDebtBase, availableBorrowsBase, currentLiquidationThreshold, ltv, healthFactor) — all in base unit (8 decimals on Base)
• getReserveData(asset) returns the full reserve struct including liquidityRate / variableBorrowRate (ray), liquidityIndex / variableBorrowIndex (ray)
• getReserveConfigurationData(asset) returns LT / LTV / liquidationBonus (bps) — refresh per ~50 blocks to detect governance drift
• Position grows / shrinks in place via flashloan-driven borrow or partial repay — no close-and-reopen
• Flashloan premium (Aave default 9bps; Balancer V2 0bps) — strategy aborts if premium > flashloan_premium_bps_max
• Use scaledBalanceOf × getReserveNormalizedIncome / getReserveNormalizedVariableDebt for windowed PnL math (balanceOf is the live, index-scaled value)

Chainlink

• latestRoundData() returns (roundId, answer, startedAt, updatedAt, answeredInRound)
• decimals() returns 8 for ETH/USD
• Staleness: reject if updatedAt older than 3600 seconds

Risk Parameters

• deltaDriftThresholdBps: Trigger delta rebalance (default: 225-500 bps)
• oracleDeviationThresholdBps: Trigger pause (default: 200 bps)
• maxLeverageX100: Emergency deleverage trigger (default: 300-400)
• targetLpAllocationBps: Capital to LP (default: 7500-8300 bps)

Common Gotchas

1. Aave flashloans settle atomically — supply / borrow / swap all happen in executeOperation; revert any time
2. sqrtPriceX96 is NOT a price — it's sqrt(price) in Q64.96 format
3. RiskEngine is a pure library — no state reads, all params passed in
4. WASM components cannot use native async — use block_on()
5. Hedge resizes in place; no buffer needed because there's no close-and-reopen tax
6. Token0/Token1 ordering matters — check which is WETH vs USDC
7. Aave ray scaling — rates and indices are 1e27, not 1e18