feat(luvi): oracle-priced fair LP unit value on pool queries

🔎 Visual review of 5d5b7ad9: explainer, review flags and prompts to ask an AI about the change

What

Pool queries now report what an LP unit is worth at the oracle price as well as at the pool's own spot price, so an integrator or monitor can tell when the spot LP value has been pushed away from fair (for example inside a sandwich).

  • Pricing library (x/thorchain/types/type_luvi_fair.go). Deterministic big.Int math, with no floats. At an oracle price P (RUNE per asset, derived from the oracle's asset and RUNE USD prices), the fair LP-side value is 2*sqrt(A*R)*sqrt(P) - S*P, where S is the synth liability. This is reported per LP unit in RUNE and in asset terms, alongside the spot LP unit value 2R - S*R/A and the fair/spot deviation in bps. If the synth liability exceeds the fair value, the value clamps at zero and sets an overhang flag.
  • Query fields. /thorchain/pool, /thorchain/pools and the wasm-whitelisted /types.Query/Pool gain QueryPoolResponse fields 40-45: lp_unit_fair_value_rune, lp_unit_fair_value_asset, lp_unit_spot_value_rune, fair_value_oracle_price_rune, lp_fair_value_overhang and lp_fair_spot_deviation_bps. They are only set when the oracle has a current price for both the asset ticker and RUNE. The price store holds only the current block's quorum prices, so any price that is present is fresh. Synth pools never get these fields.

There is no state, handler or EndBlock change: this is read-only query output.

Relation to the other luvi-guards splits

This is one of several standalone MRs split out of odin/luvi-guards. It carries only the parent's 30cc15cfb0, unchanged. No later parent commit touched the fair-value code, and the fair-value files match the parent's tip byte for byte. It builds and passes its tests without the other MRs:

  • !5295 (merged) odin/luvi-guards-overhang: LP-unit overflow fix and LUVIOverhangGuard
  • !5296 (closed) odin/luvi-guards-migration: core LUVI guard plus the migration gate
  • !5297 odin/luvi-guards-reward: reward allocation check
  • !5298 (closed) odin/luvi-guards-fuzz: fuzz targets and invariant spec

This MR does not depend on the core guard. The guard MRs add the LUVI accumulator fields 34-38 next to these fields in query_pool.proto, openapi.yaml and queryPool/queryPools. Field numbers don't collide, but whichever MR lands second gets trivial adjacent-line conflicts there, plus regenerated *.pb.go, *.pulsar.go and openapi/gen files (take theirs, then run make generate).

Risk

Low. The change is query-only. One consensus-adjacent point: a CosmWasm contract that queries /types.Query/Pool now triggers one or two extra GetPrice KV reads, so its gas_used goes up, and the response bytes grow when prices are present. With no oracle prices the response bytes are unchanged; the new regression suite asserts the same bytes as bindings.yaml. Existing regression goldens don't change. The only new goldens belong to the new suite.

Test plan

  • go test -tags=mocknet ./x/thorchain/...
  • LuviFairSuite (7 tests in x/thorchain/types) and QuerierSuite.TestQueryPoolFairValue* (2 tests): fields absent without prices, values at and away from the oracle price, overhang clamp, a sandwich moves the spot value but not the fair value
  • make lint-ci
  • make generate, then a clean git status
  • CI green, including the new regression suite wasm/bindings-fair-value (REST and contract paths, with and without oracle prices)

🤖 Generated with Claude Code

Edited by Huginn Ai

Merge request reports

Loading
Loading