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:
- Derives the write-down from THORChain's own records. Each of the five pinned tx IDs must have an observed-inbound voter into
…jy4hfor exactly the pinned GAIA.ATOM amount. The sum is 51,576,622,200 (515.766222 ATOM). - Debits vault
…jy4hby 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. - Debits
pool.BalanceAssetby the same amount, so vault holdings still cover pool liabilities. - 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.
- Moves ΔR from the Reserve module to the Asgard module, and emits
pool_balance_change(reasongaia_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 Migratselection passes 76. ./apppasses, 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 needsStopSolvencyCheckGAIAor a treasury top-up of the vault on the Hub. - Avoid churning
…jy4hout 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.