YieldBasis Technical Overview

Each market on YieldBasis provides 2× leverage exposure to a Curve Cryptoswap LP position while cancelling impermanent loss at the depositor level. Markets are deployed by a central Factory and consist of a fixed set of contracts that interact through well-defined interfaces. This page orients integrators, arb / MEV builders, and protocol-curious developers.

System architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                                FACTORY                                      │
│                    (Central Market Registry & Deployer)                     │
└─────────────────────────────────────────────────────────────────────────────┘
                          │                       │
                          ▼                       ▼
┌──────────────────────────────────────┐    ┌──────────────────────────────────────┐
│         MARKET 0 (WBTC)              │    │         MARKET 1 (cbBTC)             │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ │    │  ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│  │   LT    │ │ LEVAMM  │ │ Oracle  │ │    │  │   LT    │ │ LEVAMM  │ │ Oracle  │ │
│  └─────────┘ └─────────┘ └─────────┘ │    │  └─────────┘ └─────────┘ └─────────┘ │
│  ┌─────────┐ ┌───────────────┐       │    │  ┌─────────┐ ┌───────────────┐       │
│  │ Virtual │ │ LiquidityGauge│       │    │  │ Virtual │ │ LiquidityGauge│       │
│  │  Pool   │ │   (staker)    │       │    │  │  Pool   │ │   (staker)    │       │
│  └─────────┘ └───────────────┘       │    │  └─────────┘ └───────────────┘       │
└──────────────────────────────────────┘    └──────────────────────────────────────┘

The system supports multiple independent markets (cbBTC, WBTC, tBTC, WETH…), each with its own contract instances. Markets are fully isolated from each other. A governance layer (YB, VotingEscrow, GaugeController, FeeDistributor) sits above the markets and controls emissions and fee routing. A separate HybridVaultFactory deploys per-user HybridVault proxies for multi-market holders.

---

Core technical concepts

2× leverage mechanism

Each market maintains a constant 2× compounding leverage ratio via the AMM contract's invariant. The invariant is tied to an external oracle price; when oracle and Cryptoswap spot disagree, arbitrageurs trading through VirtualPool profit by moving state back toward $L = 2$. Rebalancing is continuous and keeper-free.

Market isolation

• Independent state. Each market maintains separate collateral, debt, and fee balances.
• Risk separation. Issues in one market do not affect others.
• Custom parameters. Each market can have tailored fee rates and debt-ceiling allocations (subject to Factory constraints).
• Implementations are set per-market at deploy. Future markets can use upgraded blueprints without retroactively changing existing markets.

Fee flow

Trading fees collected by AMM grow the AMM's internal x0 (LEVAMM trading fees) or flow into LP virtual_price growth (Cryptoswap trading fees, 50/50 split inside the pool). Borrower interest is distinct: it is swept to LT and donated back to the Cryptoswap pool as rebalance reserve (not LP yield). See Fee Mechanics.

Curve dependency

YieldBasis markets sit on Curve Cryptoswap pools (asset / crvUSD pairs). The integration touches a focused set of pool features:

• Pool state read by CryptopoolLPOracle — virtual_price and price_scale, combined into the local LP-price formula 2 · virtual_price · √price_scale. The oracle does not call POOL.lp_price().
• Pool balances accessed by LT and AMM — balances(i) for collateral valuation.
• LP token mint and burn — LT and VirtualPool add and remove liquidity via add_liquidity and remove_liquidity_one_coin. The arb path mints LP from a flash-loaned crvUSD leg, swaps inside LEVAMM, and burns LP to repay.
• Donation channel — LT.distribute_borrower_fees calls add_liquidity(amounts, min_amount, empty(address), donation=True) so borrower interest flows into the pool's rebalance reserve without minting LP shares to a user. The pool releases donations over its configured window rather than in one block.
• Pool rebalancing — the pool internally rebalances price_scale toward the external price as fees accumulate. YB does not call this; it relies on the pool's own profit-aware logic for the speed of price_scale tracking.
• Trading fees — split inside the pool: half to the pool's rebalance reserve, half to LP virtual_price growth.

YieldBasis relies on the public surface above (virtual_price, price_scale, balances, add_liquidity, remove_liquidity_one_coin, the donation flag, and the internal rebalancing being profit-aware). Integration code should rely on these interfaces, not on assumptions about pool internals.

See User: Oracle Design for the user-level oracle explainer.

---

Contract architecture

Each market consists of five core contracts. Click through for the full reference.

Factory.vy — market registry and deployment

• Deploys new markets from blueprint contracts.
• Manages contract implementations (set per-deploy; future markets only).
• Controls per-address stablecoin allocations and debt ceilings.
• Registry of all deployed markets via markets(i).
• Full reference: Core: Factory.

LT.vy — market-specific vault

• ERC-20 vault share (e.g. yb-WBTC, yb-cbBTC, yb-tBTC, yb-WETH).
• ERC-4626-like but not strict — emits ERC-4626 Deposit/Withdraw events and exposes preview_deposit / preview_withdraw, but does not implement convertToAssets / mint / redeem. Strict ERC-4626 lives on LiquidityGauge.
• Manages staked / unstaked bucket accounting (liquidity struct) and admin-fee split.
• Handles interest-to-donation refueling via distribute_borrower_fees.
• Full reference: Core: LT.

AMM.vy (LEVAMM) — constant-leverage AMM

• Holds Curve LP tokens as collateral and crvUSD as debt.
• Maintains 2× leverage via an oracle-informed invariant (x_0 quadratic).
• Fees captured in the invariant itself; no separate fee bucket.
• Interest accrues continuously via rate_mul.
• Full reference: Core: AMM.

VirtualPool.vy — flash-loan-powered arb path

• Wraps AMM + Cryptoswap + flash loan to expose direct crvUSD ↔ asset swaps.
• The arb path — LEVAMM does not trade directly against users.
• Quotes via get_dy(i, j, in_amount), executes via exchange(...).
• Full reference: Core: VirtualPool.

CryptopoolLPOracle.vy — price feed

• LP price formula: 2 × virtual_price × √price_scale × p_agg (computed locally from virtual_price and price_scale; does not call POOL.lp_price()).
• Sandwich-resistant via EMA-smoothed price_scale and a crvUSD aggregator.
• The $(0.90, 1.10)$ aggregator safety band is enforced by Factory._validate_agg at deploy and on set_agg, not by this oracle.
• Full reference: Core: CryptopoolLPOracle.

LiquidityGauge.vy — staker (ERC-4626)

• Strict ERC-4626 wrapper over yb-LP.
• Distributes YB emissions and up to 8 custom reward tokens.
• Full reference: DAO: LiquidityGauge.

---

Terminology map

User-facing docs and on-chain symbols use different names for the same concept. When reading code, map back via this table.

User doc term	On-chain symbol	Location
yb-LP	ERC-20 share of LT (ERC-4626-like but not strict)	LT.vy
LEVAMM	AMM	AMM.vy
Vault	LT	LT.vy
Virtual pool	VirtualPool	VirtualPool.vy
Watermark	ideal_staked (in LT.liquidity)	LT.vy
Recovery Mode	state: staked < ideal_staked	LT.vy
TRD	observed: preview_withdraw(1e18) / pricePerShare() − 1 (signed; negative during a discount)	no variable
PPS (fundamental value)	pricePerShare() — oracle-priced, sandwich-resistant	LT.vy
Redemption value	preview_withdraw(shares) — live Cryptoswap unwind via calc_withdraw_fixed_out	LT.vy
ERC-4626 staker	LiquidityGauge wraps LT shares with strict ERC-4626	LiquidityGauge.vy
Gauge voting	GaugeController.vote_for_gauge_weights — votes instant, 10-day cooldown per gauge	GaugeController.vy
veYB	ERC-721 NFT minted by VotingEscrow.create_lock	VotingEscrow.vy

---

Core invariants

Integration code should assume and never violate these:

1. $L = 2$ — immutable per Factory deployment. Not a DAO-mutable parameter.
2. Safe-debt bounds — MIN_SAFE_DEBT ≤ debt / collateral_value ≤ MAX_SAFE_DEBT. At $L = 2$, roughly [1/16, 8.5/16] of collateral value. Trades pushing outside the band and away from equilibrium revert.
3. Watermark monotonicity — staked ≤ ideal_staked always. ideal_staked rises on stake, does not fall on loss.
4. TRD non-negativity — preview_withdraw(shares) ≤ pricePerShare() × shares / 1e18 always.
5. Oracle clamp band — crvUSD oracle value inside $[0.90, 1.10)$. Outside the band, Factory-init and set_agg revert — never silently return stale data.

---

Mathematical foundation

The LEVAMM invariant solves a quadratic for $x_0(p_o)$:

x₀ = (coll_value + √(coll_value² − 4 × coll_value × LEV_RATIO × debt)) / (2 × LEV_RATIO)

where LEV_RATIO = L² / (2L − 1)². At $L = 2$, LEV_RATIO = 4/9. See AMM.vy::get_x0 (lines 142–157) for implementation.

Full derivation — including flash-loan sizing and the admin-fee curve — lives in Math Primer §3. Other pages (compounding-leverage, fee-mechanics, yb-LP-value-derivation) link to specific equation numbers rather than restating the math.

---

Where to start

If you want to…	Start at
Understand the math	Math Primer, Compounding Leverage
Integrate YB pools for routing	Quickstart → Quote & Route
Run arb / MEV	Arbitrage Recipe, Core: VirtualPool
Deposit / withdraw flows	Integration: Deposit & Withdraw
Enumerate deployed markets	Quickstart §1, Contract Addresses
Read all events	Event Catalog
Debug a revert	Error Codes

---

Tech stack

• Vyper 0.4.3 — all production contracts.
• Titanoboa — testing framework.
• Hypothesis — property-based stateful tests.
• Poetry / Hardhat — dependency and deployment config.

Source

yield-basis/yb-core — full contract source. Referenced by line number throughout these docs.

Related

• User: Contract Addresses — canonical mainnet address list.
• User: Glossary — full terminology reference.
• User: Risk Disclaimer — risks integrators should surface to their users.