fix(thorchain): write down phantom GAIA.ATOM and replenish the pool from the Reserve

Summary

On 2026-10-18, five GAIA inbounds (THOR h28,296,457–28,296,522) were observed into vault …jy4h and refunded with real ATOM, but the vault never received them on the Cosmos Hub. The vault's books carry 515.766222 ATOM it does not hold. That solvency-halted GAIA (SolvencyHaltGAIAChain, SolvencyHaltVault-…jy4h-GAIA).

This adds Migrate20to21 (consensus version 20 → 21, mainnet only). It writes the phantom ATOM off the vault and the GAIA.ATOM pool, and replenishes the pool with Reserve RUNE so LPs and savers are made whole.

The bifrost-side fix is tracked separately, and IBC deposit observation is removed in !5243 (merged).

What the migration does

applyGaiaWritedown20to21 runs in a cache context and commits only if every step succeeds:

  1. Derives the write-down from THORChain's own records. Each of the five pinned tx IDs must have an observed-inbound voter into …jy4h for exactly the pinned GAIA.ATOM amount. The sum is 51,576,622,200 (515.766222 ATOM).
  2. Debits vault …jy4h by that amount. This is a ledger correction only. The vault's Hub balance at h28,297,751 was 515.766217 ATOM below its books, so the vault ends up 5 uatom over-collateralized.
  3. Debits pool.BalanceAsset by the same amount, so vault holdings still cover pool liabilities.
  4. Pairs Reserve RUNE into the pool so the constant product is unchanged: ΔR = R·ΔA/(A−ΔA), so (R+ΔR)(A−ΔA) = R·A.
    • Once arbitrage brings the price back to market, the pool returns to its pre-loss depth. LPs and savers hold what they held before the loss, and the Reserve bears it.
    • At the h28,297,751 depths (78,997.32 ATOM / 212,205.55 RUNE) this is 1,394.57555508 RUNE, against a Reserve of about 25.36M RUNE.
    • The outlay is hard-capped at 2,800 RUNE (about 2×). A pool pushed toward RUNE before the upgrade pulls at most the cap; above it the pairing is clamped, not aborted.
  5. Moves ΔR from the Reserve module to the Asgard module, and emits pool_balance_change (reason gaia_atom_writedown_20to21) so Midgard tracks the depth change.

Soft-skip. The step logs and skips, leaving state untouched, if any of the following holds. It never fails the upgrade.

  • A voter is missing or differs in vault, chain, asset or amount.
  • The vault holds less than the write-down.
  • The pool is not Available, or is too shallow.
  • The Reserve can't cover the pairing.

The solvency halt then clears on its own: the first solvency consensus after the upgrade sees the vault solvent and resets SolvencyHaltGAIAChain and the vault's insolvency flag. The manual HaltGAIAChain is unaffected.

Before / after (mainnet values pinned in the tests)

Before After
Vault …jy4h GAIA.ATOM (books) 3,213.34823200 2,697.58201000 (Hub: 2,697.582015)
Pool asset 78,997.31887692 ATOM 78,481.55265492 ATOM
Pool RUNE 212,205.55008924 213,600.12564432
Reserve RUNE — −1,394.57555508

Tests

x/thorchain/migration_20to21_gaia_test.go (mainnet tag). It is picked up by the existing Migrate filter in make test-quality (network-mainnet-migration):

  • Happy path at mainnet values: vault, pool, Reserve and Asgard deltas; k preserved to within one unit of depth; the event is emitted.
  • Soft-skip on drift: a mismatched amount, a different vault, and a missing voter each leave every balance unchanged, and no event leaks.
  • Soft-skip when the vault holds less than the write-down, and when the Reserve is short.
  • Clamp at the RUNE cap for a RUNE-heavy pool.
  • Pinned inbound total equals the documented write-down.

Results:

  • go test -tags mainnet ./x/thorchain -run TestPackage -check.f 'Migrate|Migration19to20Suite|EthThorRestoreSuite' passes 122.
  • The mocknet -check.f Migrat selection passes 76.
  • ./app passes, including the consensus-version determinism check.
  • The builds for mocknet, mainnet, stagenet and chainnet all succeed.
  • The pinned golangci-lint is clean, and the inventory selection tests pass.

Operational notes

  • GAIA stays solvency-halted until this upgrade. The gap (≈$860) exceeds PermittedSolvencyGapUSD. Unhalting earlier needs StopSolvencyCheckGAIA or a treasury top-up of the vault on the Hub.
  • Avoid churning …jy4h out before the upgrade. A retiring vault whose books exceed its Hub balance cannot complete its final migration outbound. If it does churn, the step still applies as long as the vault keeps at least 515.766222 ATOM on its books.
  • No re-pin is needed at the cut. The write-down is fixed by the five observed inbounds, and the RUNE pairing is computed live and bounded by the cap.

🤖 Generated with Claude Code

Merge request reports

Loading
Loading