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) and p = R/A.
    • C adds back how price moves repriced the synth liability.
    • The averaged supply is required. Using S_prev alone 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_unit equals luvi up to rounding.
  • synth_per_pool_depth_bps: S / 2A in 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.
  • 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 = 2A and overhang, through both endpoints.

Validation

  • go test -tags mocknet ./openapi/... ./x/thorchain/... ./common/... passes.
  • gofumpt, tools/analyze (-rand -map_iteration, -float_comparison) and golangci-lint v1.63.4 are clean on the changed packages.
  • make test-regression was not run. No regression fixture captures the full pool response, so the added fields shouldn't affect it.

🤖 Generated with Claude Code

Merge request reports

Loading
Loading