Skip to main content
When an LP deposits into a Lending Pool, they receive vTokens - share tokens that track their proportional claim on the pool. The vToken is the mechanism that makes yield passive.
vToken mechanics

​
The Core Idea: Shares

A vToken does not represent a fixed quantity of the underlying asset. It represents a proportional claim on the pool’s physical balance. Two values determine the exchange rate at any moment:
ValueMeaning
pool_balanceThe asset balance physically held by the pool contract right now - what can actually be withdrawn.
vToken supplyTotal vTokens currently in circulation.
The redemption rate (assets per vToken) is: assetsPerShare=pool_balancevToken supply\text{assetsPerShare} = \frac{\text{pool\_balance}}{\text{vToken supply}} When a borrower repays their debt plus accrued interest, pool_balance rises. vToken supply does not change. So assetsPerShare rises - and every vToken holder benefits proportionally, without doing anything.

​
How vTokens Are Minted and Burned

On deposit - the pool calculates shares to issue: 
vTokens minted = amount × vToken supply / pool_balance
If the pool is empty or no vTokens have ever been minted, the first depositor receives shares 1:1. On redemption - the pool calculates assets to return: 
asset amount = vTokens redeemed × pool_balance / vToken supply
Both operations use the same ratio: pool_balance / vToken supply. A depositor who supplies, waits, and then redeems gets back more than they put in - as long as at least one repayment with interest has occurred during that period.

​
When Does the Exchange Rate Rise?

The exchange rate rises when pool_balance grows. This happens when a borrower repays their debt.
  • Borrow: XLM leaves the pool. pool_balance drops. The exchange rate drops proportionally - but the LP’s total claim is unchanged, because the same XLM now exists as an outstanding loan.
  • Repayment: XLM returns to the pool. Since borrowers owe principal plus accrued interest, the interest portion is surplus. After repayment, pool_balance ends up higher than it was before the borrow, and assetsPerShare rises above the original level.
Interest accrues in the pool’s accounting (borrows_wad grows via update_state()), but this accounting does not affect pool_balance or the vToken exchange rate. The rate only moves when tokens physically enter or leave the pool contract.

​
A Worked Example

Suppose a pool starts empty and an LP deposits 1,000 XLM:
Eventpool_balancevToken supplyExchange rateLP vTokensLP redeemable (liquid)
LP deposits 1,000 XLM1,0001,0001.0001,000 vXLM1,000 XLM
Borrower draws 500 XLM5001,0000.5001,000 vXLM500 XLM
30 days pass, interest accrues in accounting5001,0000.5001,000 vXLM500 XLM
Borrower repays 510 XLM (500 principal + 10 interest)1,0101,0001.0101,000 vXLM1,010 XLM
The LP did nothing between the borrow and repayment. Their vToken balance stayed at 1,000 vXLM throughout. Once the borrower repaid with interest, the exchange rate rose from 1.000 to 1.010. During the active borrow, the LP’s redeemable amount reflects only the liquid portion of the pool. The outstanding 500 XLM is an active loan - the LP’s full claim is restored once the borrower repays. If utilization is high, full redemptions may be temporarily limited. A second LP depositing 100 XLM at the end would receive 100 / 1.010 ≈ 99.01 vXLM - they enter at the current exchange rate, fairly priced against the original LP.

​
vToken Operations

Actionpool_balancevToken supplyExchange rate
LP depositsIncreasesIncreases (vTokens minted)Unchanged
LP redeemsDecreasesDecreases (vTokens burned)Unchanged
Borrower borrowsDecreases (XLM leaves pool)No changeDecreases
Borrower repays principal onlyReturns to pre-borrow levelNo changeReturns to pre-borrow rate
Borrower repays principal + interestRises above pre-borrow levelNo changeRises above original rate
Liquidation - full debt recoveredPool receives full repaymentNo changeRises (full recovery)
Liquidation - partial recoveryPool receives partial repaymentNo changeRises less (LPs absorb the shortfall)

​
What vTokens Are Not

A vToken is not:
  • A fixed-yield bond. Yield depends on what borrowers repay, which varies with utilization and the Rate Model.
  • Risk-free. If a borrower defaults and liquidation does not recover the full debt, pool_balance receives less than the full repayment. The shortfall reduces the exchange rate permanently - LPs absorb it proportionally.
  • Always redeemable. If pool utilization is near 100%, most assets are out as active loans. Redemptions may fail until borrowers repay. This is a liquidity constraint, not a solvency problem - the debt is still tracked and will return to the pool.
  • A governance token. vTokens carry no voting rights. They are purely economic claims on the pool.

​
Transferability

vTokens are standard fungible tokens with transfer and transfer_from functions. They can be sent to another address, which then holds the same proportional claim on the pool. Vanna does not restrict transfers.

​
Supported Assets

Vanna currently deploys two vToken contracts on Stellar:
UnderlyingvToken
XLMvXLM
USDCvUSDC