feat: hold inbounds on solvency-gated chains until a solvent report covers them
🔎 Visual review ofe74360cc: 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!hasFinalisedreturn, a gated inbound is written to a store keyed by chain, vault, external height and txid. The vault key is the vault's primaryPubKey, 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 intoprocessFinalisedObservedTxIn. A valid reference memo's use is recorded at park time. - Confirm (
processSolvencyAttestation): a non-stale consensus thatinsolvencyCheckfinds solvent also has to passsolventForSolvencyGate. That check requires the wallet to cover the full ledger, withinPermittedSolvencyGapUSD, 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 heightand the consensus came after it was parked. Reverted or missing voters are dropped (with asolvency_gated_inbound_droppedevent) without waiting for a confirmation. Each release runs in its ownCacheContextwith 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.HaltMemolessis 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.
refundTxnow falls back to the memo's literalDEST/REFUNDrefund 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/asgardkeeps 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/statusand/thorchain/tx/stagesreport a parked inbound as pending (swap_status.pending=true,swap_finalised.completed=false) rather than as a swap that finished with no output. SamesolvencyGatedInboundKeyas errata; querier-only, no consensus reads. - Network solvency:
calculateNetworkSolvencysubtracts 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>Chainwhile another vault with funds on the chain is flaggedSolvencyHaltVault-<pubkey>-<chain>. The vaults checked are exactly the ones/thorchain/vaults/asgardlists 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, andValidateGenesisrejects 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.mdstates 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
cleanupAsgardIndexdropped from the Asgard index; - in the keeper: per-vault ordering and heads, and confirmation monotonicity.
- Bifrost:
ShouldReportSolventVaultsunit test, and a utxoReportSolvencytest that queues both insolvent and solvent reports on a gated chain and only the insolvent one on an ungated chain. Bifrost suites pass exceptTestSolvencyCheckRunnerZeroBackoff, which fails on develop without this change. - Regression: new
solvency/solvency-gate.yaml(swap held, then released) andsolvency/solvency-gate-insolvent.yaml(chain halts, no refund, parked record in the export).solvency.yamlandmimir/solvencyhalt-setmimirs.yamlare unchanged. make generateis clean andmake lint-cipasses.