feat: churnless chain activation

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

Why

Today a chain only goes live when a churn produces new Asgard vaults whose Chains list contains it. That list is written exactly once, at keygen, from TssVoter.ConsensusChains(). That is a 2/3 vote over what each bifrost self-reported it runs.

That couples two separate jobs:

  1. Bookkeeping: stamping vault.Chains and vault.Routers.
  2. Readiness proof: guaranteeing a supermajority of nodes can actually observe the chain before any address exists for it.

Only (2) is load-bearing. (1) is bookkeeping that happens to live at the keygen call site. So turning on a chain whose client already ships in the binary costs a full network churn, with all its risk and multi-day cadence.

This removes the churn dependency, not the binary-release dependency.

Three findings that shaped the design

  • No new key material is needed. Vault.GetAddress resolves secp256k1 chains from PubKey and ordinary ed25519 chains from PubKeyEddsa. Both are already on every live vault. Only FROST/XMR needs PubKeyFrost.
  • Bifrost needs no change at all. /vaults/pubkeys carries no chain list, and pubkeymanager derives each vault address per chain from the pubkey alone. A node running the client already watches the right address and already posts MsgNetworkFee for it.
  • vault.Chains was never immutable, and that was a hole. AddFunds has always appended unseen chains on credit. That contradicts the comment in handler_tss.go, which is now corrected. Because bifrost derives an inbound address for every chain client it runs, anyone could have stamped a chain onto every live Asgard with one dust transaction, bypassing every gate below. This MR closes that path (see Inbound credit gating).

How

An Enable<CHAIN>Chain mimir (MimirTemplateEnableChain) plus activateEnabledChains in NetworkMgr.EndBlock. It runs after the router upgrade controller and before migrateFunds, so routers and chain membership are settled before migration scheduling reads them.

The readiness proof reuses the network fee. SaveNetworkFee only persists after ObservedNetworkFeeVoter reaches a 2/3 supermajority, so a valid fee means 2/3 of active nodes independently scanned the chain and agreed a rate. It self-bootstraps, and the fee is needed anyway to price the first outbound. No new message type or voter. The only new state is two one-key-per-chain records: a pointer to the latest consensus fee voter, and the height of the last keygen that dropped the chain (both below).

Gates, in order:

  • G0, silent deferral: mimir set and in effect, the chain not already converged, no init vault present, and no unresolved regular keygen. hasPendingKeygen is now a free function so this path can share it. A keygen in flight could otherwise rotate in a vault set that omits the newly enabled chain.
  • G1: the chain is eligible, so not THOR and not XMR.
  • G2: a valid network fee.
  • G3: an observed chain height.
  • G4: the chain is not halted.
  • G5: an EVM chain must have a stored router.
  • G6b: the current active set has an attester supermajority.
  • G6a: the chain was not dropped by a keygen newer than the readiness proof (see Currency). It is checked after G6b, so a missing proof is reported as missing rather than as stale.
  • G7: every eligible active vault can derive an address and reach its own keysign quorum.

How vaults are handled:

  • Active vaults are all-or-nothing. A partially stamped set would publish an inbound address for a vault that cannot sign. The writes go through a CacheContext, so a failed SetVault cannot leave the set asymmetric either.
  • Retiring vaults are best-effort. They are stamped only if they can derive the address and clear the same per-vault keysign bar. Otherwise they are skipped, so a stale one cannot hold activation back forever. One that misses the bar is retried until it churns out.
  • The XMR monovault is skipped. A third chain there breaks the keygen-family discrimination in keygenMatchesVault.
  • Converge, don't append. A vault may already hold the chain in append order, so every eligible vault ends the pass on the same normalised set, sorted with ConsensusChains' key. A missing router is populated, but an existing one is never overwritten, because a vault's router is pinned for its lifetime.
  • Cheap when idle. Mimir reads come first. Already-converged chains are dropped by chainNeedsStamping / retiringNeedsStamping before any gate runs. Activation is logged only (chains activated on live vaults), with no event; failed gates log chain activation not ready with the reason.

A separate commit narrows the churn-halt gate: a halted chain now blocks rotation only while active or retiring vaults hold funds or a deficit on it (chainHasVaultFunds, which fails closed on keeper error). Otherwise halting a newly activated chain would stop churn network-wide. THORChain is exempt, so HaltTHORChain still stops churn unconditionally. Native RUNE is not in Vault.Coins, so the funds check would always read empty there. This changes churn behaviour for all chains, which is why it is its own commit.

Inbound credit gating

Without this, everything above could be bypassed with one dust transaction.

  • handleObservedTxInQuorum no-ops an inbound on a chain the receiving vault does not carry (vaultSupportsChain). It takes the same path as compromised-vault inbounds: quorum and chain height are recorded, nothing is credited, refunded or dispatched, and the voter is marked done. Each no-op emits EventSecurity (inbound for unsupported chain no-oped: vault=<pubkey>). The telemetry counter is generalised to thornode_inbound_noop{reason=...}.
  • Deposits sent before activation are not revisited. They become vault over-solvency. Operators can enumerate them from the security events and credit them case by case in a migration handler. There is no automatic refund, because that would mean signing on a chain the network has not proved it can observe.
  • The migrateFunds fallback is removed. When no active vault carried a chain, the fallback targeted any regular Asgard. That only worked because AddFunds silently appended the chain on arrival; with the gate above, those funds would be signed out and credited nowhere. Migration now stalls loudly instead. The retiring-vault funds check holds the churn until an operator brings the chain on with Enable<CHAIN>Chain. The explicit "never migrate a non-XMR chain into the XMR monovault" exclusion is kept.
  • Migrations the old fallback already scheduled are still credited (isScheduledMigrateInbound). The inbound must carry a migrate memo, come from the source vault's own address and match a txout item at the memo height addressed to this vault. Only the coins are credited: the chain is not appended to vault.Chains, so no inbound address is advertised and keygen reports are not required to carry it until Enable<CHAIN>Chain stamps it. Outbound selection, migrateFunds and chainHasVaultFunds all read vault.Coins, so the funds stay spendable. The churn halt gate likewise checks every chain an active vault holds non-zero coins or a deficit on, not only its Chains, so halting that chain still blocks churn after the retiring source drains.
  • Errata leaves the pool untouched for never-credited inbounds (!observedVoter.UpdatedVault). Unwinding a no-oped deposit would otherwise take it out of other LPs' balances.

Readiness proof: how it establishes both identity and currency

The gate has two halves, and they answer different questions.

Identity: who can observe the chain. A node cannot report a network fee for a chain it did not scan, so the signers on the chain's ObservedNetworkFeeVoter records are exactly the nodes that have run its client. The signers of the chain's latest consensus voter are filtered to the currently-active set. They must then clear ⌈2n/3⌉ in two places:

  • network-wide;
  • within every individual Asgard's keysign party. TSS keysign is per-vault, so a network-wide quorum can still leave one vault below its own threshold, holding an inbound address it cannot sign outbounds for.

Only members in the party bifrost actually signs with count (keysignPolicyForVaultMembers). Forced-to-leave members are excluded, and jailed members are excluded when enough clean members remain. Under DisableTSSSignerFiltering the whole membership counts. The threshold is always taken from the full membership.

The latest voter is found through a per-chain pointer (latest_network_fee_voter/). It is advanced on every fee consensus (advanceLatestNetworkFeeVoter), and only forward in chain height: a vote for an older height that completes late, for example when a syncing node re-reports an old block, never replaces a newer one. A same-height vote at a new rate still moves it. GetLastChainHeight cannot identify the voter behind the stored fee, because fee consensus is only one of its three writers and every observed inbound advances it too. The voter store is never pruned, so its history is never scanned. A chain with no pointer, because its last fee consensus predates the upgrade or follows a genesis export/import (fee voters are not exported), has no proof until its next fee consensus. The voter's consensus height is also returned, so G6a can date the proof.

Currency: whether they still do. The active-set filter cannot supply this. It establishes who the attesters are, not that they still run the client. No time-based window can supply it either: bifrost posts MsgNetworkFee only when the rate changes. On a stable-fee chain (XRP, Cosmos, TRON, the chains this targets) a single voter is written once and never refreshed, so any age bar would be unsatisfiable rather than merely strict.

Currency comes from the keygen vote instead (G6a). When RotateVault retires a vault that served a chain in favour of one that does not, it records the replacement's keygen height as that chain's drop (chain_dropped_height/, SetChainDroppedHeight). XMR-family vaults and THOR record nothing. That churn was told by a supermajority that the chain is no longer run, so activation will not re-stamp it from a readiness proof that reached consensus at or before the drop. A same-height proof counts as older. The log reads chain dropped by keygen at <h>, not before the readiness proof at <h>. Because the record outlives the retiring vault, the veto still holds after migration has drained that vault and marked it inactive. A retiring vault that still holds the chain next to a newer active vault without it counts as the same evidence (keygenDropHeight). Re-enabling needs a fee consensus newer than the drop.

Store migration for pre-upgrade drops. A rotation that ran before this upgrade left its drop only in the retiring vault still carrying the chain. Once migration drained that vault and marked it inactive, that evidence would be gone, and a still-set enable mimir would re-stamp the chain from the older proof. Migrate20to21 (consensus version 20 → 21; develop's 19 → 20 is the ZEC TEX clout and mainnet migration) runs recordVaultChainDrops. It persists every drop keygenDropHeight can read off the current vault set across common.AllChains, skipping THOR. It only ever raises an existing record, so it cannot weaken one RotateVault wrote.

The rule applies only to a chain that was actually dropped:

  • A first activation is not held to it. The keygen vote finalizes on the first 2/3 of reports, so one early reporter without the client is enough to leave a chain off a new vault.
  • It lapses once every active vault carries the chain again.

The signal is drawn from vault keygen heights rather than the mimir's effective height, because that value is routinely backdated to 1 to mean "now" and so cannot date the operator's intent.

Stranded-funds carve-out: the veto stands down when any retiring vault that held the chain still holds funds above dust on it (HasFundsAboveDustForChain, the per-chain slice of the churn blocker's HasFundsAboveDust). A sub-dust remainder or account reserve never holds the churn, so it does not disarm the veto. This is measured over the retiring set, not per vault. That situation is a non-orderly drop: migrateFunds has no target, the churn is held, and re-stamping is the only way out. A permanent network-wide churn halt is the worse outcome. Every other gate still applies.

Known limits:

  • A fresh proof shows the network can observe the chain, not that it wants it. OptToRetire leaves the client running and posting fees, so a chain retired that way is re-enabled by its next fee consensus while Enable<CHAIN>Chain is still set. Unset the mimir before retiring a chain.
  • The proof is dated by its consensus height, so a vote whose early signatures predate the drop but which completes after it still counts. Because the pointer never moves back to an older chain height, the gap is bounded by how long one fee vote takes to gather.
  • The attester set cannot be refreshed on demand. On stable-fee chains it is frozen at the validators active when the fee last reached consensus, and standby nodes' fee messages are rejected, so the supermajority decays across churns. docs/new-chains/new-chain-process.md describes the coordinated bifrost restart that refreshes it for period-aligned scanners (XRP, Cosmos). TRON has no operator-driven refresh.
  • If every bifrost has truly abandoned a chain but funds were stranded anyway, the carve-out lets an operator re-stamp it.

Also worth knowing: there is no admin mimir in this repo. validateMimirAuth accepts only active nodes, and Enable<CHAIN>Chain classifies as economic, so it needs 2/3 to set and to unset. The fast abort is HaltXChainTrading / HaltXChain (operational).

Docs

docs/new-chains/new-chain-process.md gains the Enable<Chain>Chain step and operational notes covering:

  • deferral behaviour;
  • EVM router ordering;
  • how to recover un-credited pre-activation deposits;
  • refreshing the readiness proof;
  • how a churn that drops the chain outranks an older proof, including drops from before the upgrade, which the upgrade records, and unsetting the mimir before retiring a chain.

Testing

  • New chain_activation_test.go (50 cases) and chain_halt_churn_test.go (9 cases). The keygen-drop rule is covered by cases including:

    • TestDropDecisionSurvivesRetiringVaultMigration;
    • TestPreUpgradeDropSurvivesRetiringVaultMigration (the Migrate20to21 path, sharing its steps with the case above);
    • TestPreUpgradeDropRecordOnlyRaises;
    • TestNoRestampFromRecordedDropAlone;
    • TestNoRestampWithProofAtDropHeight;
    • TestRestampAllowedWithProofNewerThanDrop;
    • TestFirstActivationNotHeldToNewerKeygen;
    • TestRecordedDropIgnoredOnceActiveCarriesChain;
    • TestProofBetweenKeygenAndRotationIsFresh.
  • New cases elsewhere:

    • handler_observed_txin_test.go: unsupported-chain no-op, supported chain still credits, a legacy migrate to a chainless vault debits the source and credits the destination end to end (TestLegacyChainlessMigrateIsCredited, verified to fail without the fix), and forged migrate memos are still no-oped (TestForgedMigrateToChainlessVaultIsNoOp).
    • handler_errata_tx_test.go: errata leaves the pool untouched for a no-oped inbound.
    • manager_validator_current_test.go: halted empty chain does not block churn; HaltTHORChain still does; a halted chain an active vault holds coins or a deficit on, without carrying it, blocks churn.
  • The thorchain_test.go keygen fixture now records signer chain lists. The removed migrateFunds fallback had been masking a vault created with no chains.

  • New test/regression/suites/chain-enable/. It covers:

    • a DOT inbound before activation is no-oped;
    • the mimir alone stamps nothing;
    • fee consensus stamps the chain with no churn, and the sorted chain set is checked;
    • the same inbound is credited after activation.

    It was verified to fail when the EndBlock call is removed, so it tests the feature rather than itself.

  • Full regression (EXPORT, rebased on develop): 187 of 187 passed.

  • make lint-ci (scripts, golangci-lint, trunk) is clean, and make test (mocknet plus the stagenet/chainnet/mainnet network-specific runs) passes.

  • Test quality was checked by mutation testing: 19 injected defects, 15 caught.

Why this is a draft

One thing is outstanding: the mocknet end-to-end was not completed. The attempt reached the churn trigger and was blocked by an Asgard keygen failure in the mocknet cluster (single-party join). That is a cluster p2p problem this change never reaches. Mocknet remains the only way to exercise the per-vault keysign gate against real TSS, since regtest runs a single Asgard.

The gate is covered at unit level by TestNoStampWhenOneVaultBelowKeysignThreshold. It builds two disjoint Asgards and first asserts the network-wide gate passes, so the per-vault check is provably the one rejecting. TestNoStampWhenAttesterForcedToLeave and TestNoStampWhenAttesterJailedOutOfParty cover the keysign-party filtering.

The mutation gaps that previously held this in draft are now closed:

  • chainHasVaultFunds fail-open on keeper error → TestKeeperErrorFailsClosed
  • THOR/XMR eligibility (G1), previously passing for the wrong reason → TestIneligibleChainsRejectedByEligibilityGate asserts the gate's own reason string
  • "no eligible active vaults" → TestNoEligibleActiveVaults
  • redundant per-block writes → chainNeedsStamping now short-circuits before the gates run at all, pinned by TestChainNeedsStampingBranches
  • MimirTemplateEnableChain key format → TestActivationMimirKeysAreValid, asserted against mimirValidKey, the matcher handler_mimir.go itself gates on

Preconditions for an actual chain

  • EVM chain: RouterUpgradeController cannot install an initial ChainContract. It requires current == oldRouter, which is false when there is none. A net-new EVM chain must ship its initial ChainContract in the enabling release, from processMigration or genesis, before the enable mimir. Activation enforces this (G5): an EVM chain with no stored router is refused, since it would otherwise be advertised with router: "" and a dead token deposit path.
  • SUI / ADA: both are missing from common.AllChains, so the routine never sees them. They also have no client case in loadchains.go, so bifrost log.Fatals at boot.
  • Keep the chain halted until it is ready to enable. Inbounds sent to the derivable address before activation are no-oped and not refunded.
  • Unset Enable<CHAIN>Chain before retiring the chain. While it is set, any new fee consensus re-enables it.

🤖 Generated with Claude Code

Edited by Huginn Ai

Merge request reports

Loading
Loading