Loading
feat(thorchain): synth-aware LUVI math and pool query fields
Summary
Classic LUVI, sqrt(A*R) / pool_units, is meant to rise with pool yield and fall only when value leaves the pool. It stops working once a pool has synths. Synths are a liability the LPs owe, and every swap reprices it. So the index swings with price, and in overhang (synth supply ≥ 2 × asset depth) the synth-unit clamp pins it near zero.
This MR adds a read-only, deterministic library for synth-aware versions of the index. It also exposes the values that need no stored state on /pool and /pools. There are no consensus or state changes.
The math (x/thorchain/types/type_luvi.go)
- LP equity:
Q = sqrt(A*R) * (2A - S) / (2A). This is pool value minus the synth liability, and it is negative in overhang. - LUVI*:
LUVI* = Q/L + C, whereΔC = ((S_prev + S_new)/2) * (sqrt(p_new) - sqrt(p_prev)) / (2 * L_new)andp = R/A.- C adds back how price moves repriced the synth liability.
- The averaged supply is required. Using
S_prevalone gets the LP result wrong at virtual depth above 1×.
- G: raw running total of
ΔG = ΔQ + ((S_prev + S_new)/4) * Δsqrt(p) − ΔL * LUVI_chain_prev.- LP-unit changes are credited at the chain's own per-unit value (the clamp included). That keeps G valid in overhang too.
- Below overhang,
ΔG = L_new * ΔLUVI*. With no synths,ΔG = L_new * ΔLUVI. - Alert on each step's
ΔG / sqrt(A*R).
CheckLPUnitLedger: LP-unit changes must match add/withdraw events. G can't see units minted while a pool is in overhang: they are nearly worthless until the pool leaves overhang, and then they gain value with no pool flow.
All arithmetic is big.Int fixed-point at 1e36. Nothing is stored on chain.
New /pool and /pools fields
luvi:sqrt(A*R) / pool_units, as the chain values a pool unit.lp_equity,lp_equity_per_unit: Q and Q/L. Below overhang,lp_equity_per_unitequalsluviup to rounding.synth_per_pool_depth_bps:S / 2Ain basis points.synth_overhang:S ≥ 2A.
Proto fields 29–33. The OpenAPI spec and client are regenerated.
Tests
types/type_luvi_test.go: 20 tests checked against an independent 256-bit reference across five synth regimes (none, light, heavy, overhang, deep overhang). They cover:- identities, including
ΔG = L·ΔLUVI*andΔG = L·ΔLUVI; - flat price moves and fair flows; income raises G; every loss lowers it;
- synth round trips; crossing the overhang boundary;
- the unit ledger, zero and extreme inputs, and determinism.
- identities, including
luvi_invariant_test.go: 15 tests driving the real swapper, add/withdraw handlers, gas manager, slasher, network rewards and donate handler, in four regimes. They check:- swaps at every size, including min-slip, are flat;
- synth mint/burn never lower G, and round trips at 1×, 1.5× and 2× match the LP result;
- deposits and withdrawals never lower G and match the unit ledger exactly;
- gas and bond-covered slashes cost about
(g/A)²/2, while a bond shortfall is first-order; - theft, free synths and over-minting lower G, and the overhang over-mint is caught by the ledger;
- random 300-step sessions crossing the overhang boundary never drop G.
querier_test.go: exact field values for no synths, synths,S = 2Aand overhang, through both endpoints.
Validation
go test -tags mocknet ./openapi/... ./x/thorchain/... ./common/...passes.gofumpt,tools/analyze(-rand -map_iteration,-float_comparison) andgolangci-lintv1.63.4 are clean on the changed packages.make test-regressionwas not run. No regression fixture captures the full pool response, so the added fields shouldn't affect it.