Spark TVL - HackMD

Spark TVL **- What metric do we want to obtain?** The Total Value Locked (TVL) expressed in USD for each star and/or partner. **- Do we understand what this metric is?** In simple terms, every user-supplied token that remains locked inside its contracts, whether the depositor’s goal was yield, collateral, or both. **- What information do we need? contracts, wallets, etc.** - PoolAddressesProvider (`0x02C3eA4e34C0cBd694D2adFa2c690EECbC1793eE`): Single source of truth; points to the live Pool, Data-Provider and Price-Oracle proxies - ProtocolDataProvider (Aave v3 fork): Exposes reserve list, scaled supply, debt totals, and liquidity index using the ABIs `getAllReservesTokens()`, and `getReserveData(asset)`. - AaveOracle (`0x8105f69D9C41644c6A0803fDA7D03Aa70996cFD9`): On-chain USD price for every underlying asset using the ABI getAssetPrice(asset). **- How do we calculate this metric?** - Discover active components (per chain): ``` provider = IPoolAddressesProvider(PROVIDER_ADDR) dataProv = provider.getPoolDataProvider() oracle = provider.getPriceOracle() ``` - Enumerate every reserve in Spark Lend: Call getAllReservesTokens() once; loop through the returned list of underlying tokens. - Convert each reserve’s scaled supply into real token units: ``` scaledSupply, liquidityIndex = getReserveData(token).supply, .liquidityIndex underlyingAmount = scaledSupply × liquidityIndex ÷ 1e27 ``` - Mark to USD ``` USD value = underlyingAmount × oracle.getAssetPrice(token) ÷ 1e18. (Spark follows the Aave-v3 convention: oracle prices are “price in ETH-wei where 1 ETH = $1”.) ``` - Sum across all reserves to get the Spark Lend TVL for that chain. Borrowed coins are not counted: they left the Pool contract and therefore have zero balance. - Add the Savings-vault layer: ``` assets = IERC4626(V).totalAssets() // underlying token units usdValue = assets × oracle.getAssetPrice(underlying) ÷ 1e18 TVL += usdValue ``` These vault balances are the deposits that earn the Sky/Spark Savings Rate [see docs](https://docs.spark.fi/user-guides/spark-liquidity-layer) - Repeat steps 1-6 for every supported network (Ethereum, Base, Gnosis, Arbitrum) and add the subtotals. - Return / display the grand total. **- What will be the cron job endpoint to update this metric in database and with which frequency?** - `/api/cron/update-tvl?protocol=[protocol]` `protocol` can be a star, a partner, or any protocol we want to calculate TVL. - This cron job should be executed as frequently as possible, every 10 minutes is a good start. **- What will be the endpoint/s to consume this metric in the clients?** - `/api/tvl/[protocol]` `protocol` can be a star, a partner, or any protocol we want to calculate TVL.