Draft: feat(thorchain): LUVI gate on store migrations

I'm checking which of the sibling luvi-guards MRs have already landed on develop, so the relation section stays accurate.

What

Every registered x/thorchain store migration now runs inside a report-only LUVI scope named migration/<from>to<to>. A CI gate also fails on undeclared LP-value losses in migrations.

  • Runtime (report-only). luviGuardMigration snapshots every pool before the migration runs, so it also catches raw store writes that bypass SetPool. A drop in a pool's hedged LP equity G emits luvi_loss. A pool whose LPs lose everything emits kind removed, or ledger when LP units vanish without withdraw events. Each changed pool gets a log line. The scope never fails an upgrade, and the LUVIGuard Mimir turns it off. Migrations are now registered through Migrator.luviMigrations() in luvi_migration.go, not one by one in module.go (see docs/release.md).
  • CI gate. LuviMigrateGateSuite runs every registered migration against a fixture of mainnet-shaped pools (LPs, POL, synths). LuviMigrateMainnetGateSuite runs the mainnet steps that move pools at mainnet depths: the 19to20 slash refunds (BTC, ZEC, TRON, SOL), the ETH.THOR restore and the low-synth burn, plus the 20to21 GAIA write-down. Both fail on any normalized G drop that luviDeclaredWriteDowns does not declare. That list starts with 17to18 DOGE/GAIA (ADR-028) and 19to20 SOL/TRX (slash reversals).

The migration gate depends on the core LUVI guard (journal, luviScope, luvi_loss event, per-pool G accumulator and its luvi_* fields on the pool queries, LUVIGuard Mimir). This MR carries that guard too, with the parent branch's fixes and tests:

  • c9a69f6824: core guard, G accumulator and luvi_loss events
  • guard, journal, accumulator and allowance tests, plus LUVIGuard docs; luvi_star is reported as of luvi_height
  • the rounding allowance scales with swap legs (RoundingOps)
  • accumulators advance at the end of EndBlock
  • EndBlock scopes skip losses that an inner handler scope already reported
  • the allowance now covers the virtual synth depth subsidy (LuviSynthSubsidyAllowance). When VirtualMultSynthsBasisPoints is above 1x, each synth swap leg gets an allowance estimated from its slip, and the 1e-6 report threshold applies only past that subsidy. Synth swaps on mocknet (2x) therefore no longer report a configured transfer as a loss. At 1x, the mainnet default, both are zero. While the multiplier is above 1x, flows that change synth supply still only report and are not rejected.
  • the docs/mimir.md LUVIGuard entry now lists the covered EndBlock steps, the ledger check and the synth-subsidy exception
  • lint fixes and a test helper rename (luviMigrationLossEvents)

Relation to the other luvi-guards splits

This is one of several standalone MRs split out of odin/luvi-guards. It builds and passes its tests without the others:

  • odin/luvi-guards-overhang (!5295 (merged)): LP-unit overflow fix and LUVIOverhangGuard. Already on develop, and this branch sits on top of it.
  • odin/luvi-guards-reward: reward allocation check. It also carries the core guard commit, but not the later guard fixes listed above.
  • odin/luvi-guards-fairprice: oracle-priced fair LP unit value on pool queries
  • odin/luvi-guards-fuzz: fuzz targets and invariant spec

Whichever of this MR and the reward MR lands second drops the shared core commit at rebase. If the reward MR lands first, this MR's guard fixes still apply on top of it. Expect trivial adjacent-line conflicts in the /pool querier and query_pool.proto (the fair-value fields next to the luvi_* fields).

Left out on purpose: the parent's tc-debug luvi_forensics.py skill.

Regression fixtures

Fixtures were regenerated with EXPORT=1. Only two kinds of change remain:

  • 14 added luvi_loss events (kind drop, excess: false) in 9 fixtures under gas/, slash/, security/, tor/ and vault-deficit/. These are gas and slash reimbursements on MsgOutboundTx, MsgRefundTx and endblock/gas that the allowance covers but that exceed the 1e-6 report threshold. No fixture has an excess event.
  • wasm/bindings asserts the raw QueryPoolResponse bytes, which now carry the luvi_* fields 34–38.

An earlier regeneration also added report-only events on mocknet synth swaps. The synth-subsidy allowance removed all of them.

Risk

Consensus-visible through the core guard:

  • user value flows that lower a pool's G beyond the allowance are rejected and refunded
  • a new per-pool accumulator KV record is written in EndBlock
  • there are new luvi_loss events
  • there are new luvi_* fields on the pool queries

LUVIGuard (default 1) gates the guard and the events; the accumulator always runs. The synth-subsidy allowance only widens the allowance when VirtualMultSynthsBasisPoints is above 1x, so it has no effect on mainnet defaults. The migration scope itself only reports: it adds KV reads and events at upgrade time and never changes migration results.

Test plan

  • go test -tags=mocknet ./x/thorchain/... ./constants/... ./app/...
  • LUVI suites (-check.f Luvi): LuviGuardSuite, LuviMigrateGateSuite, LuviMigrateMainnetGateSuite, LuviInvariantSuite and LuviOverhangGuardSuite, plus LuviAllowanceSuite in x/thorchain/types (including the synth-subsidy allowance tests)
  • make lint-ci
  • make generate, then a clean git status
  • Regression fixtures regenerated with EXPORT=1
  • CI green (test-regression matches the regenerated fixtures)

🤖 Generated with Claude Code

Edited by Huginn Ai

Merge request reports

Loading
Loading