!4991odin-churnless-chain-add → develop5f33ec463c

Churnless chain activation

AI-generatedEverything on this page was written by an AI agent from the diff: the summaries, the narration, the diagrams, the flags and the glossary. It can be wrong or incomplete, so check it against the code before you rely on it.

41commits
33files
8.3klines changed
1.2klines to read
v21→22consensus version
G0–G7activation gates
0proto changes

Where the diff is

6-minute explainer

What changed

Why

A new chain went live only at the next churn's keygen.

Bookkeepingvault.Chains, Routers+Readiness proof2/3 can observe itkeep the proof, drop the churn

Mimir + hook

Enable<CHAIN>Chain; runs in EndBlock between routers and migrateFunds.

router upgradeactivateEnabledChainsPOLmigrateFunds

Readiness proof

Latest 2/3 network-fee voter, signers filtered to today's active set.

MsgNetworkFee ×nvoter ≥ 2/3pointer per chainsigners ∩ active validatorsG6b: still ≥ ceil(2n/3)

Gate ladder

G0 defers silently; G1–G7 log the first failing gate.

G0 no init vault / pending keygenG1–G5 eligible, fee, height, unhalted, routerG6b attester supermajority nowG6a not dropped after proofG7 every vault: address + quorum

Per-vault quorum

Each Asgard's own keysign party must clear (2n+2)/3.

Asgard A6 of 6 ✓Asgard B3 of 6, need 4 ✗one short vault blocks the whole chain

Stamping

Active all-or-nothing in a CacheContext; retiring best-effort.

active: all or noneretiring: skip if unablerouters: fill, never replacechains: sorted

Keygen drops

A drop newer than the proof vetoes, unless funds are stranded.

fee proofkeygen dropnewer proofvetoedallowedrecorded at RotateVault + Migrate21to22

Inbound gating

Inbound on a chain the vault lacks is no-oped, not refunded.

dust to derived addressno-op + EventSecurityno credit, no stamp
legacy migrate: coins credited, chain not appended · errata on a no-op leaves the pool

Churn side effects

Migration fallback removed; halts block churn only with funds.

migrateFunds: stall, not misroutehalt + funds → no churnhalt, no funds → churnHaltTHORChain → always blocks

Tests

Two regtest suites plus ~2,300 lines of unit tests.

mimir alone: nothinginbound no-opedfee 2/3DOT stampedinbound credited

State + upgrade

Migration

v21→v22

Migrate21to22 records keygen chain drops still visible on retiring vaults (recordVaultChainDrops), raise-only.

Mimirs

  • newEnable<CHAIN>Chainunset (0 = off; v>0 live from height v)

Store records added

chain_dropped_height/<chain>
+ int64 keygen height of the drop
latest_network_fee_voter/<chain>
+ ObservedNetworkFeeVoter ID of the latest consensus
Vault.Chains (semantics)
+ mutated by activation; no longer appended by unsupported inbounds

Line by line · every changed logic line, narrated

18:31runtime
26code chapters
100%logic lines narrated (900/900)
12flagged spots
speed

Chapters

What to check

Ask an AI about this change

Chat assistantClaude, ChatGPT, … (reads a link)

Coding agentClaude Code, Cursor, … (reads the repo)

The context file is context.md. Use Copy with context for an AI that can't open links; it pastes the whole file in.

Glossary

Asgard vault
A TSS-controlled vault held by a subset of active nodes. Its Chains list decides which inbound addresses are advertised. types/type_vault.go ↗
Bifrost
The per-node observer/signer. It derives each vault's address per chain from the pubkey alone, so it needs no change here.
Churn
Periodic validator rotation: new TSS keygen creates new Asgard vaults and funds migrate out of the retiring ones. manager_validator_current.go ↗
Keygen drop
A churn whose new vault omits a chain its predecessor served. Recorded as chain_dropped_height; a fee proof must be newer to re-enable. chain_activation.go ↗
Keysign quorum
TSS signing needs ceil(2n/3) of a vault's own members; G7 checks it per vault using the keysign party bifrost will use. chain_activation.go ↗
Mimir
On-chain key/value overrides voted by nodes or set by admin. Enable<CHAIN>Chain is a new economic mimir, so it needs a node supermajority. constants/mimir_strings.go ↗
Network fee voter
ObservedNetworkFeeVoter: nodes' votes on a chain's fee rate. Its 2/3 consensus is reused here as proof the network can observe the chain. handler_network_fee_helpers.go ↗
New chain process
The operator runbook; step 5 is now the Enable<Chain>Chain vote, with notes on refreshing the proof and drops. docs/new-chains/new-chain-process.md ↗
No-op inbound
An inbound with quorum that changes no state: not credited, not refunded, voter marked done, with an EventSecurity for operators. handler_observed_tx_helpers.go ↗
vault.Chains
The chains a vault serves. Written at keygen from ConsensusChains; now also converged by activation and no longer appended by unsupported inbounds. handler_tss.go ↗
XMR monovault
The FROST-keyed vault pinned to THOR and XMR. Exempt from activation, and never a migration target for other chains.