!5302odin/luvi-guards → develop1398c5d412

LUVI guard, G accumulator, migration gate, reward check, fair LP pricing

AI-generatedEverything on this page was written by an AI agent from the diff: the summaries, the narration, the diagrams, the flags and the glossary. It can be wrong or incomplete, so check it against the code before you rely on it.

21commits
64files
15.9klines changed
2.2klines to read
1new Mimir, on by default
v21consensus version (unchanged)
11new /pool fields

Where the diff is

Where the LUVI checks sit

3-minute explainer

What changed

G, the LP equity

Swaps leave √(A·R) alone; only rewards, flows, gas and slashes move it

swap: G =reward/add: G ↑gas/slash: G ↓ allowedelse: G ↓ loss

Per-tx guard

User flows refunded on an excess G drop; protocol steps only report

user flows: rejectprotocol / EndBlock: reportLP units ↔ events

Migration gate

Store migrations report LP-value drops; CI fails on undeclared ones

SOL slash reversal −0.53%TRON slash reversal −0.16 bp

G accumulator

PoolLuvi advances each EndBlock; /pool gains five luvi_ fields

luvi_gluvi_cluvi_starluvi_last_normalized_delta_gluvi_height

Reward check

dG must equal √(A(R+r)) − √(AR); report-only

dG matches rewardevent = paidAsgard got the RUNE

Fair LP pricing

Oracle-priced LP value a sandwich can't move, beside spot

fair 2√(A·R·P) − S·Pspot 2R − S·R/Adeviation bps

Risk

On by default, ungated; allowance model decides refunds

State + upgrade

Mimirs

  • newLUVIGuard— → 1

Store and query fields added

PoolLuvi (new store prefix pool_luvi/)
+ asset+ height+ balance_rune+ balance_asset+ lp_units+ synth_supply+ pool_units+ raw_c+ raw_g+ last_normalized_delta_g
QueryPoolResponse (34-38, 40-45)
+ luvi_g+ luvi_c+ luvi_star+ luvi_last_normalized_delta_g+ luvi_height+ lp_unit_fair_value_rune+ lp_unit_fair_value_asset+ lp_unit_spot_value_rune+ lp_fair_spot_deviation_bps+ fair_value_oracle_price_rune+ lp_fair_value_overhang
Events
+ EventLuviLoss (luvi_loss)+ EventLuviReward

Line by line · every changed logic line, narrated

17:34runtime
49code chapters
100%logic lines narrated (1726/1726)
11flagged spots
speed

Chapters

What to check

Ask an AI about this change

Chat assistantClaude, ChatGPT, … (reads a link)

Coding agentClaude Code, Cursor, … (reads the repo)

The context file is context.md. Use Copy with context for an AI that can't open links; it pastes the whole file in.

Glossary

Allowance
The G drop a scope may cause without being a loss: gas and slash reimbursement, rounding per swap leg, synth mints and LP unit changes. type_luvi.go ↗
Fair LP value
LP value priced from √(A·R) and an oracle price P rather than pool depths, so a swap or sandwich cannot move it. type_luvi_fair.go ↗
LUVI
LP unit value index. Here G = √(A·R), with synths accounted for: the pool's hedged LP equity, which swaps leave unchanged. docs/concepts/luvi-invariant.md ↗ type_luvi.go ↗
luvi_loss
Event (EventLuviLoss) for an excess G drop or LP-unit ledger mismatch, naming the pool, scope, inbound tx, dG and allowance. luvi_forensics.py ↗
Mimir
THORChain's on-chain parameter overrides set by node votes or admin. LUVIGuard and LUVIOverhangGuard are new ones, both 1 by default. docs/mimir.md ↗
POL
Protocol-owned liquidity: the Reserve adds and withdraws liquidity in POLCycle. It now skips overhang pools. manager_network_current.go ↗
PoolLuvi
New per-pool store record holding the G accumulator, advanced at the end of every EndBlock and exposed as luvi_* on /pool. type_pool_luvi.proto ↗
Scope
One guarded unit of execution: a handler run, an advanced-queue swap, an EndBlock step or a store migration. Its journal holds each touched pool's pre-state. luvi_guard.go ↗
Synth overhang
A pool whose synth supply S is at least twice its asset depth A; LP equity is then non-positive, so adds are refused. handler_add_liquidity.go ↗