TVL (Total Value Locked) Monitoring
TVL is an operational metric for DeFi protocol, not marketing. Sharp 30% drop in an hour — either a hack or a large LP "rug". 500% growth in a day without matching transaction increase — suspicious manipulation for DeFiLlama listing. Both cases need a system that sees changes in real-time and interprets them.
How to count TVL properly
Multi-currency accounting problem
Naive approach: sum balanceOf of all tokens in protocol contracts in USD at current prices. Fails when:
- Protocol accepts Uniswap V2 LP tokens as collateral.
balanceOf(LP_token)is count of LP tokens, not USD. Must compute underlying assets viagetReserves()pool. - Synthetic tokens (sUSD, stETH): price ≠ base asset price on depeg. Need separate price feed, not always available.
- Concentrated liquidity positions (Uniswap V3 NFT): value depends on current price and position range — needs off-chain math of tick/sqrtPrice.
Right architecture: each asset type has own adapter with resolveToUSD(address asset, uint256 amount) → uint256 logic. This is pattern DeFiLlama uses in its adapters.
Chainlink vs AMM prices
Chainlink Data Feeds — standard for major assets (ETH, BTC, USDC, major ERC-20s). Heartbeat 1 hour for stablecoins, 1 hour for major assets. Problem: for long-tail tokens no Chainlink feed exists.
Fallback: Uniswap V3 TWAP via IUniswapV3Pool.observe() with periodSeconds = 1800 (30 minutes). TWAP protects from flash loan manipulation, but at low liquidity imprecise.
Important: Chainlink feed can return stale data. Always check answeredInRound >= roundId and updatedAt > block.timestamp - staleness_threshold.
Monitoring system architecture
On-chain vs off-chain calculation
Computing TVL fully on-chain via getTVL() smart contract is appealing for transparency, but:
- Expensive in gas with complex calculations
- Limited by call stack size
- LP tokens need external calls, gas grows exponentially
Better approach: off-chain service with archive node access. Algorithm:
- Fetch balances via
eth_callin batches (Multicall3 for efficiency) - Request prices from Chainlink + DeFiLlama API + CoinGecko Pro
- Calculate TVL with decimals normalization
- Record snapshot in database with block number and timestamp
- Serve via API and dashboard
Frequency: every block for critical alerts (~12 sec on Ethereum), every 5 minutes for historical data.
The Graph subgraph for TVL
The Graph lets you subscribe to smart contract events and aggregate in GraphQL. For TVL monitoring subgraph handles events:
-
Deposit(address user, address asset, uint256 amount)— TVL increase -
Withdraw(address user, address asset, uint256 amount)— TVL decrease -
Liquidation(...)— collateral change
Subgraph problem: prices not stored on-chain, need oracle integration via @priceOracle handler. Slows indexing and adds dependency.
Faster deploy alternative: Dune Analytics with SQL queries over indexed Ethereum data. Works without dev, but latency higher (5-15 minutes).
Alerts on sharp changes
Anomaly detection pattern:
currentTVL < previousTVL * (1 - threshold) → CRITICAL alert
currentTVL > previousTVL * (1 + spike_threshold) → WARNING (possible manipulation)
Critical threshold: 10% in one block — obvious anomaly. 30% in 5 minutes — critical incident.
Alert channels: Telegram Bot API for quick notification, PagerDuty for on-call rotation, Slack webhooks for team notification. For DeFi protocols with TVL > $1M — mandatory 24/7 monitoring.
Dashboard integration
Grafana + InfluxDB — standard stack for TVL time series. Metrics: tvl_total, tvl_by_asset, tvl_by_chain, tvl_change_1h, tvl_change_24h.
DeFiLlama adapter: if protocol wants DeFiLlama listing — need PR with adapter in their repo. Adapter is JavaScript function tvl(api) using their api.add(token, balance) interface. We write and maintain these adapters.
Custom dashboard: React + recharts or Dune Analytics embedded charts for public protocol page. Data from own API endpoint or directly from subgraph via Apollo Client.
| Method | Latency | Cost | Complexity |
|---|---|---|---|
| Own off-chain service | ~block (12s) | High (node) | High |
| The Graph subgraph | 1-5 min | Medium (hosting) | Medium |
| Dune Analytics | 5-15 min | Low (SQL) | Low |
| DeFiLlama API | 5-15 min | Zero | Low |
Working process
Analytics (1 day). Inventory of protocol contracts, types of accepted assets, events to track, alert latency requirements.
Development (1-3 days). Choose stack based on requirements → implementation → alert setup → deploy dashboard.
Support. On adding new pools or assets — update adapters. On network fork or contract migration — update addresses.
Timeline estimates
Basic monitoring via The Graph + Telegram alerts — 1-2 days. Full system with own service, Grafana dashboard and DeFiLlama integration — 3-5 days.
Cost depends on number of contracts, asset types and latency requirements.