feat: hold inbounds on solvency-gated chains until a solvent report covers them

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

Summary

Adds an opt-in, per-chain solvency gate (SolvencyGateInbound-<CHAIN>, default off). On a gated chain, a finalised inbound is credited to its vault as today, but it is parked instead of executed: no swap is queued, no handler runs, and no refund (invalid memo, inactive vault, trading halt, switch asset) is scheduled. EndBlock releases it once a solvency consensus, reached in a later THORChain block, attests that the vault's wallet covers its full ledger at or above the inbound's external block height.

If an inbound is credited for funds that never reached the vault, the wallet doesn't cover the ledger, so the inbound stays parked. Once the shortfall exceeds the permitted gap, the existing solvency checker halts the chain, still before the inbound can pay anything out. Today such an inbound is swapped or refunded right away, and the halt only comes once a later report catches up.

How it works

  • Park (handleObservedTxInQuorum): right after the !hasFinalised return, a gated inbound is written to a store keyed by chain, vault, external height and txid. The vault key is the vault's primary PubKey, which is what solvency confirmations use. It is not the observed pubkey, which on SOL and XMR is the vault's EdDSA or FROST key. The memo-processing tail moved into processFinalisedObservedTxIn. A valid reference memo's use is recorded at park time.
  • Confirm (processSolvencyAttestation): a non-stale consensus that insolvencyCheck finds solvent also has to pass solventForSolvencyGate. That check requires the wallet to cover the full ledger, within PermittedSolvencyGapUSD, without deducting pending outbounds, so an outbound queue the wallet still holds can't cover a spoofed inbound. A pass records (external height, THORChain consensus height) for that vault and chain. It never moves backwards.
  • Release (EndBlock, before the swap queues): each vault is read from its lowest-height parked inbound, so a vault that can't be confirmed holds back only its own inbounds. A parked inbound runs when confirmedHeight >= inbound height and the consensus came after it was parked. Reverted or missing voters are dropped (with a solvency_gated_inbound_dropped event) without waiting for a confirmation. Each release runs in its own CacheContext with a panic guard. If execution fails, the inbound is refunded; it is dropped with the event only if the refund fails too. Releases are capped at 100 per block, across up to 200 vaults per chain per pass. Turning the gate off releases everything parked on that chain.
  • Reference memos: an inbound's r:<ref> memo is resolved and its use recorded when it is parked, and the resolved memo is stored on the parked record (memo = 6) and executed on release. A reference that expires, is reissued to another registrant, or is left out of a genesis export while the inbound waits doesn't change the instruction or its refund address, and the reissued reference's allowance isn't consumed. HaltMemoless is judged at release.
  • Refund address when a THORName expires: a parked memo is parsed again at release, and an expired THORName in its destination fails the whole parse. refundTx now falls back to the memo's literal DEST/REFUND refund address (memo.LiteralRefundAddress, same chain and validity checks) when the memo doesn't parse, and an unparseable registered reference memo stays on the in-flight copy for it, as when memoless is halted. Without this, the refund went to the sender, or on XMR the deposit was donated to the pool. This also applies to unparked swaps whose destination name expires before a refund (e.g. streaming or limit swaps).
  • Inactive vaults: /thorchain/vaults/asgard keeps an inactive vault listed while it has parked inbounds, as it already does for inactive vaults with a deficit. Bifrost then reports its solvency, and a solvent report releases the inbound into the existing inactive-vault refund. Bifrost only reports a vault while it holds funds on that chain, so once churn has migrated an inactive vault's funds out, its parked inbounds wait until the gate is turned off and are then refunded.
  • Errata: reverting a parked inbound debits the vault and unparks it, without the pool or LP unwind, since the inbound never reached a pool. The parked record is looked up under the vault's primary pubkey (solvencyGatedInboundKey).
  • Tx status: /thorchain/tx/status and /thorchain/tx/stages report a parked inbound as pending (swap_status.pending=true, swap_finalised.completed=false) rather than as a swap that finished with no output. Same solvencyGatedInboundKey as errata; querier-only, no consensus reads.
  • Network solvency: calculateNetworkSolvency subtracts parked principal so it can't be read as surplus and swept to the treasury while the inbound is still due. This applies whatever the vault's status: churn moves an inactive vault's coins, parked principal included, into an active vault that is counted. For a non-active vault, only the part of the principal that vault no longer holds is subtracted, because its own holdings aren't counted.
  • Bifrost: on gated chains that aren't halted, every chain client now also reports its solvent vaults, after any insolvent ones (runners.ShouldReportSolventVaults), so one vault reading short (an outbound in flight, a token shortfall) does not hold back the other vaults' parked inbounds. Previously only insolvent vaults, or an all-clear while halted, were reported. Positive reports go through the existing ebifrost quorum path.
  • Halt held by the flagged vault (gated chains only): because solvent and insolvent reports now arrive in the same round, a solvent report no longer lifts SolvencyHalt<Chain>Chain while another vault with funds on the chain is flagged SolvencyHaltVault-<pubkey>-<chain>. The vaults checked are exactly the ones /thorchain/vaults/asgard lists for Bifrost (getReportedAsgardVaults, now shared with that query), so an inactive vault dropped from the Asgard index that still has parked inbounds counts too. Otherwise an insolvent consensus at block N would be undone by another vault's solvent consensus at N+1. The flagged vault lifts the halt itself once it reports solvent, and a read error keeps the chain halted. Ungated chains make no extra reads.
  • Genesis: parked inbounds (new field 51, omitempty) and their voters are exported and imported. Without that, an export/import would leave them credited and never executed. An Init or Inactive Asgard vault with inbounds parked under it is exported too, like one with a deficit, and ValidateGenesis rejects a parked inbound whose vault is missing.
  • The gate fails closed: an unreadable Mimir gates the chain.

Risk: high (consensus path)

  • The new Mimir read on every finalised inbound changes gas_used, so this needs a coordinated release. With the gate off, behaviour is otherwise unchanged: existing regression goldens don't change.
  • Latency: each inbound on a gated chain waits up to one solvency interval (10 blocks on GAIA), and longer while a broadcast outbound from the vault is not yet observed.
  • Not a per-inbound proof: a spoof is still released if it's no larger than the gap plus real funds the wallet holds but the ledger doesn't yet. Those are inbounds still in confirmation counting, or deposits after the report height on chains whose balance reads aren't pinned to a height (UTXO, XMR). docs/mimir.md states this bound.
  • Recovery after a halt: revert spoofed inbounds with errata, which unparks them, before unhalting or turning the gate off. Turning the gate off releases everything still parked: inbounds on active vaults execute, those on inactive vaults are refunded, and a swap or add released while trading or its chain is halted is refunded.
  • Storage growth: always-on solvent reports create solvency voters that are never pruned (the existing retention TODO in handler_solvency_helpers.go). On GAIA that's roughly 17k voters a day. Pruning is a follow-up.
  • Don't enable on TRON: its balance reads can't be pinned to a height, so solvent reports may never reach consensus.
  • StopSolvencyCheck* also stops releases on gated chains.

Testing

  • go test -tags=mocknet ./x/...: pass. The gate suites cover:
    • parking, the same-block rule, a report below the inbound's height, the insolvent halt with no refund, a solvent release that refunds an invalid memo, gate-off release, reverted inbounds, the per-block limit and the genesis round trip;
    • added in the review round: an unconfirmable vault not blocking another vault, a reverted inbound dropped without a confirmation, an inactive vault listed for Bifrost, pending-outbound surplus not confirming the gate, errata skipping the pool unwind, network solvency excluding parked principal, commit-only-on-success with the panic guard, the refund fallback, and reference resolution and reservation;
    • added since: parked principal staying a liability after churn migrates its vault's coins, and being netted against what an inactive vault still holds; and an inbound observed under an alternate (EdDSA/FROST) key being parked under the primary pubkey, released by a solvent report, and found by errata;
    • a solvent report from one vault not lifting a halt held by another flagged, funded vault on a gated chain (it still unhalts when the flagged vault holds nothing, and on ungated chains), including a flagged inactive vault that cleanupAsgardIndex dropped from the Asgard index;
    • in the keeper: per-vault ordering and heads, and confirmation monotonicity.
  • Bifrost: ShouldReportSolventVaults unit test, and a utxo ReportSolvency test that queues both insolvent and solvent reports on a gated chain and only the insolvent one on an ungated chain. Bifrost suites pass except TestSolvencyCheckRunnerZeroBackoff, which fails on develop without this change.
  • Regression: new solvency/solvency-gate.yaml (swap held, then released) and solvency/solvency-gate-insolvent.yaml (chain halts, no refund, parked record in the export). solvency.yaml and mimir/solvencyhalt-setmimirs.yaml are unchanged.
  • make generate is clean and make lint-ci passes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AkNUVMqamwuzPsSPywMdM7

Edited by Huginn Ai

Merge request reports

Loading
Loading