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
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
• BPS → Fraction: bps / 10000
• sqrtPriceX96 → Price: (sqrtPriceX96 / 2^96)^2 adjusted for token decimals

Protocol Integration

Uniswap V3 (Ethereum Mainnet)

• Pool: concentrated liquidity USDC/WETH (0.05% fee tier, 500 bps)
• Positions tracked by NFT token ID
• slot0() returns (sqrtPriceX96, tick, observationIndex, observationCardinality, observationCardinalityNext, feeProtocol, unlocked) — 7 values
• positions(tokenId) returns (token0, token1, tickLower, tickUpper, liquidity, ...)
• Token ordering on Mainnet: USDC (0xA0b8...) = token0, WETH (0xC02a...) = token1
• Tick spacing: 10 for 0.05% pool

Panoptic (Options Hedge)

• Option mints/burns are SYNCHRONOUS via mintOptions() / burnOptions() — no pending orders
• Positions tracked by TokenId (uint256) encoding option parameters
• Long put = long-gamma hedge against ETH price drops
• Cannot increase option size in-place; must burn and remint to resize
• Panoptic uses Uniswap V3 TWAP for settlement pricing (not Chainlink)

Chainlink

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

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)
• rebalanceCooldownBlocks: Min blocks between rebalances (default: 10-25)

Common Gotchas

1. Panoptic is synchronous — no pending order execution needed (unlike legacy perp protocols)
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 buffer intentionally overshoots to avoid close+reopen thrash
6. WETH is token1 on Ethereum Mainnet (USDC < WETH by address) — use amount1 for ETH