feat: set THORChain block time with a BLOCKTIMEMS mimir and scale block-denominated settings
🔎 Visual review of12ca12af: explainer, review flags and prompts to ask an AI about the change
This MR carries two parts: the commit-wait hook that sets the block time (part 1), and the scaling that keeps every block-denominated setting at its wall-clock meaning (part 2, merged in from !5266 (merged)). Neither should ship without the other: without part 2, a nonzero BLOCKTIMEMS on mainnet would shorten every block-count duration in wall-clock time (emission per year, churn, jail, keygen retry, bifrost margins).
Part 1: commit-wait hook
What it does
Sets CometBFT's commit wait (TimeoutCommit) at runtime from a new BLOCKTIMEMS mimir, so the network's mean block interval tracks a governance-set target instead of timeout_commit plus consensus overhead.
- CometBFT runs in-process and shares one
*ConsensusConfigwith the server context.cmd/thornodeattaches that pointer inPostSetup. - A BaseApp Precommiter (
app/app.go) runs insideCommiton the consensus goroutine, right before CometBFT'supdateToStatereadsTimeoutCommitfor the next height. The write is synchronous, so there's no data race. - Steers to the latched block time. While
BLOCKTIMEMSis set, the hook's target is the block time that part 2'sUpdateBlockTimelatched (GetBlockTimeMs), not the raw mimir. The durations are scaled to that latched value, so while the rate limit (part 2) steps toward a target, the commit wait follows each step instead of jumping ahead of the scaling. - A local controller (
app/blocktime) measures intervals between BFT header times (ctx.BlockHeader().Time, not wall clock) and adjusts the wait:wait -= 0.1·error + 0.002·integral, clamped to[min(200ms, target), target]. It starts attarget − 1.1s, and on a negative interval or one over 10× target it falls back to config.toml'stimeout_commit. The controller is node-local and never touches state. It only reads state (the mimir and the latched block time). - Precommit-collection floor. The commit wait is also when the next proposer collects precommits that arrive after +2/3. A wait driven to 0 drops them from
LastCommit, and each missing signature costs an honest validator MissBlockSign slash points. So the wait never goes below 200 ms (or the whole target, if that is shorter). In the mainnet overhead model, 200 ms keeps the 1500 ms minimum within 1%. A target below overhead + 200 ms runs slow. - Economic (2/3) mimir.
BLOCKTIMEMSis pinned inIsOperationalMimir'sexactUnmatches, so no future partial-match rule can make it operational. Block time changes emission and every timeout. - Inert until the mimir is set. While
BLOCKTIMEMSis unset or0,TimeoutCommitis never touched. Voting0after a target restores config.toml's value. A mimir vote can't delete the key, so0means "unset". - Hard limits: 1500–10000 ms on mainnet/stagenet/chainnet (mocknet's floor is 200 ms so tests can run sub-second targets);
0= off. They're enforced twice.MsgMimirvalidation rejects anything else, and the hook clamps any positive target to the bounds at read time (logged once at Error), in case a value reaches the store without passing validation (an old vote reaching supermajority, a migration, a direct store write). The wait itself stays in[min(200ms, target), target]. It is not an operational mimir, so it needs the normal 2/3 vote. - Regtest is unchanged:
regtestStartnever runsPostSetup, soREGTEST_TIMEOUT_COMMITstands.
Why not CometBFT's next_block_delay
FinalizeBlockResponse.next_block_delay is absent from CometBFT 0.38 (we're on v0.38.21) and from 0.39, and development of v1/v2, which have it, has stopped.
Context
Supersedes !4078 (fixed 2s blocks, !4078) and !3993 (merged). Design doc: https://claude.ai/artifact/UfNNXFX4G6H7iZVHsYtVsR (section "Driving the commit wait from the mimir").
Scope of part 1: the commit-wait hook. Part 2 covers scaling block-count durations, the block-time history and bifrost.
Status
-
BlockTimeMsconstant + mimir validation + docs/mimir.md -
app/blocktimecontroller + hook, Precommiter, PostSetup wiring (default, mocknet, regtest builds compile) -
Unit tests: convergence against simulated mainnet overhead (p50 1.08s, p90 1.59s, 1% +3s round-1). Mean interval equals the target at 6000/3000/2000 ms and is 1501 ms at a 1500 target; p90 is about target + 0.48s
-
Unset mimir leaves
TimeoutCommituntouched; hook race test;go test -tags=mocknet -racefor app/..., cmd/thornode/..., constants, x/thorchain -
Hard limits: handler cases 1499/1500/10000/10001/0/-1; read-side clamp (stored 500 → 1500, 60000 → 10000); wait ≤ target; mainnet bounds pinned in a
!mocknettest -
Mainnet-tag coverage: handler bounds (1499/10001 rejected, 0/1500/10000 accepted) and the hook engaging and clamping (stored 500 → 1500, 60000 → 10000);
IsOperationalMimir("BLOCKTIMEMS")is false in any casing, under both tags -
CI: the mainnet-tag tests run in
test-network-specific(./app/blocktime+-check.f …|BlockTimeMsBoundsOnMainnet, mirrored inscripts/test-quality-inventory.py);--check-selectionpasses -
CI:
.govulncheck-ignoreallowlists GO-2026-6859 (a net/http stdlib race, fixed in go1.26.11) against the pinned go1.26.10. The toolchain bump has its own MR (chore/go-1.26.11), and the entry can be deleted once that merges -
make lintclean -
Anti-windup: live mocknet runs exposed two windup cases. Startup sat at 3027 ms for a 3000 target, and a 3000 → 2000 change sat at 2024 ms. The integral now starts only after 3 consecutive intervals within 5% of the target. Both cases have regression tests
-
Live one-node mocknet (race-built binary,
timeout_commit1s, ~210 blocks per step, 0 data races). These runs predate the latch: the hook steered to the raw mimir. With part 2, a 1000 → 3000 step on mocknet goes through 2000 first, oneChurnIntervalapart:BLOCKTIMEMS mean (last 100 blocks) p10 / p50 / p90 blocks to settle unset (baseline) 1028 ms 1015 / 1033 / 1035 n/a 3000 3001 ms 2989 / 3004 / 3010 ~20 2000 (changed from 3000) 2001 ms 1989 / 2003 / 2010 ~20 0 (restores config) 1032 ms 1017 / 1035 / 1039 immediate -
Multi-validator check with real consensus overhead (a one-node mocknet has ~25 ms). A 5-validator mocknet ran 780 heights through 1000 → 2500 → unset → 500. Every node agreed on every app hash, results hash and block ID, and every height committed in round 0 (evidence in the validation thread)
-
Precommit-collection floor (
7fc66b9887, 200 ms).TestControllerMinWaitfails without the floor. The A/B ran two 5-validator mocknets side by side, without and with the floor. At a 500 ms target, below what the host can reach, partial (4/5) commits fell from 290/481 (60%) to 3/444 (1%), and the mean interval went from 641 to 713 ms. At a reachable 1000 ms target the floor never binds: both nets averaged 999 ms with 0/200 partial commits. Neither net had a mismatch or a non-zero round (900 and 840 heights × 5 nodes). In the mainnet overhead model, the 1500 ms target's mean is 1501/1506/1525/1585 ms at floors of 0/200/300/400 ms
Part 2: scale block-denominated settings (from !5266 (merged))
The BLOCKTIMEMS mimir changes the real block interval. Part 2 keeps every block-denominated setting at its wall-clock meaning at any block time. Values are converted once, when they are read. No governance value is rewritten, there is no store migration, and unsetting BLOCKTIMEMS undoes everything. Part 2 also fixes the places where a change of block time would skip work or measure time in blocks, and lets bifrost follow the block time. While the mimir is unset, nothing changes.
How it works
- Reference unit: the network's default
ThorchainBlockTime(6000 ms mainnet, 1000 ms mocknet).r = ThorchainBlockTime / BLOCKTIMEMS.r = 1exactly while the mimir is unset or 0, and every conversion is then the identity. Integer math only. - Unit tags (
constants/units.go): everyConstantNamehas one. A unit test fails for any untagged name.- Duration:
ceil(v·r); values ≤ 0 (off/unset) pass through. - PerBlockRate:
v/r, rounded half up. - Count, Height, WallClock: unchanged.
- Non-constant mimir keys are tagged too (
SignatureRefreshBlocks= Duration; halt keys = Height).
- Duration:
- The block time is latched per block. At the start of BeginBlock,
UpdateBlockTimetakes theBLOCKTIMEMStarget (clamped to the hard limits and rate limited, see below) as the effective block time. It stores it with the change height and the previous value (blocktime/keys, registered inapp/divergence/prefixes.go), writing only when the value changes, so nothing is stored while the mimir is unset. A mimir set in block H therefore applies from H+1, and every read within a block sees one block time. The commit wait (part 1) steers to this latched value, so it switches with it. Keeper.GetConfigInt64applies the tag to both mimir and constant values. New keeper methods:GetBlockTimeMs(ctx): the effective (latched) block time.GetBlockTimeChange(ctx): the height and previous value of the last change.GetConfigInt64Ref(ctx, key): the value in reference blocks, before scaling.UpdateBlockTime(ctx): the latch, called from module BeginBlock.ScaleConfigInt64(ctx, key, v): for reads that bypassGetConfigInt64.RefBlocks(ctx, n): for hardcoded counts.
- Gas:
BLOCKTIMEMSis read on a throwaway gas meter, so the conversion never changes a tx'sgas_used(unit testTestGetConfigInt64ScalingChargesNoGas). - Bypassing reads: every direct
GetInt64Value/GetMimirread of a Duration or Rate key inx/now goes throughGetConfigInt64orScaleConfigInt64. The original fallback semantics are kept, e.g.<= 0versus< 0. Reads converted:SigningTransactionPeriod(×9)BlocksPerYear(emission, THORName)DoubleSignMaxAgeJailTimeKeygen/JailTimeKeysignFailKeygenSlashPoints- the
ChurnRetryIntervalfallback BondLockupPeriod(leave/unbond)TxOutDelayMax/MaxTxOutOffset(queue metrics, queriers)
- Outbound delay (
CalcTxOutHeight): the delay is computed and capped in reference blocks (MinTxOutVolumeThreshold,TxOutDelayRate,MaxTxOutOffsetread withGetConfigInt64Ref) and converted once withRefBlocks. The scaled threshold is used only as the per-block capacity. Scaling the threshold and rate first scaled the backlog's rate reduction by the square of the block time ratio: 10 s blocks under-delayed a 10M RUNE backlog (730 s instead of 1200 s), and 2 s blocks over-delayed small outbounds. - Streaming credit against the outbound delay (
cachedTryAddTxOutItem): a streaming swap is credited with the wall-clock time since inbound consensus, in whole blocks at the current block time, instead of its block count. Counting blocks, a stream that ran over fast blocks and finished after the blocks slowed got far too much credit and its outbound went out early. Without a change this isctx.BlockHeight() − voter.Height, as before. - Analyzer:
tools/analyze -unscaled_config, wired intoscripts/lint.sh. It flags aGetInt64Value(constants.X)orGetMimir(ctx, constants.X.String() | "X")of a Duration or Rate key when the enclosing function never passesconstants.XtoScaleConfigInt64. The opt-out is// analyze-ignore(unscaled-config), used where a value is deliberately read in reference blocks: the THORName reference fee and free year, and the wall-clock windows and ages below (RefWindowStart,RefBlocksSince,SortBySecurity). /thorchain/constantsshows constants at the current block time./thorchain/mimirstill shows the stored (reference) values./thorchain/networkhas a newblock_time_msfield: the block time in force for this block (the latchedBLOCKTIMEMS), or the network default while it is unset./thorchain/constantsstill shows the defaultBlockTimeMs, so integrators and bifrost should read this field instead.- THORName fee: expiry is priced in reference blocks,
(free year + paid / fee-per-reference-block), and converted once. This way the per-block fee doesn't lose ~1/3 to integer rounding at 2s.GetTHORNamePerBlockFee(for/thorchain/network) shows the rate at the current block time.
Unit table: decisions for review
The defaults follow the design doc's inventory, checked against each key's usage.
| Unit | Keys |
|---|---|
| Duration | BlocksPerYear, PoolCycle, PendingLiquidityAgeLimit, MaxAnchorBlocks, DynamicMaxAnchorSlipBlocks, DynamicMaxAnchorCalcInterval, FundMigrationInterval, ChurnInterval, ChurnRetryInterval, MissingBlockChurnOut, MaxTrackMissingBlock, SigningTransactionPeriod, DoubleSignMaxAge, FailKeygenSlashPoints, LiquidityLockUpBlocks, ObservationDelayFlexibility, JailTimeKeygen, JailTimeKeysign, NodePauseChainBlocks, TxOutDelayMax, MaxTxOutOffset, StreamingSwapMaxLength(Native), StreamingLimitSwapMaxAge, ChurnOutForLowVersionBlocks, SynthYieldCycle, CloutReset, KeygenRetryInterval, SaversStreamingSwapsInterval, RescheduleCoalesceBlocks, RUNEPoolDepositMaturityBlocks, SaversEjectInterval, OverSolvencyCheckInterval, BondLockupPeriod, MemolessTxnTTL, L1DynamicFeeEpochBlocks, MissingObservationHalfLife, MissingObservationGuardMaxBlocks; mimir SignatureRefreshBlocks |
| PerBlockRate | TxOutDelayRate, MinTxOutVolumeThreshold, TNSFeePerBlock, TNSFeePerBlockUSD, POLMaxPoolMovement, POLReserveMaxDeployment (both cycles run every block) |
| Height | ArtificialRagnarokBlockHeight, PauseBond/Unbond, StreamingSwapPause, RUNEPoolHalt*, TCYHalt, HaltRebond, HaltOperatorRotate, HaltMemoless, HaltOracle; mimirs Halt, NodePauseChainGlobal, ScheduledMigration, HaltMonovaultKeygen |
| WallClock | OracleUpdateInterval (already ms), BlockTimeMs |
| Count | everything else: amounts, bps, flags (including develop's LUVIGuard and LUVIOverhangGuard), node counts (MaxMissingBlockChurnOut, DesiredValidatorSet, …), MinSwapsPerBlock/MaxSwapsPerBlock and AdvSwapQueueRapidSwapMax (more throughput is the point), RagnarokProcessNumOfLPPerIteration, ChurnMigrateRounds, L1DynamicFeeWindowEpochs (epochs, whose length scales), StagedPoolCost / MinimumPoolLiquidityFee (per PoolCycle, which scales) |
Policy items for review:
- Slash points stay Counts. ObserveSlashPoints and LackOfObservationPenalty are charged per observation (L1 activity), not per block. MissBlockSignSlashPoints does accrue per block, but integer points can't be divided, so it accrues faster at shorter block times.
- Open question: whether MinSlashPointsForBadValidator should scale to compensate. It is left as a Count.
- FailKeygenSlashPoints is a Duration ("720 blocks of slash ≈ 1h of rewards").
- POLMaxPoolMovement as a Rate rounds small values down. At 2s, a value of 1 becomes 0.
- MemolessTxnTTL is a Duration. Lowering the block time raises it in blocks, and per
docs/mimir.mdraising it revives already-expired references until one TTL has passed. - Memo and quote block counts stay raw THORChain blocks: streaming interval, custom TTL, THORName expiry height. Their bounds (StreamingSwapMaxLength, StreamingLimitSwapMaxAge) are in reference time.
Hardcoded block counts
Converted:
keeper_refund.gorefund-cleanup retention 432000 →RefBlocks, and the stored expiry is converted at a changekeeper_xmr_spent_refs.gospent-ref retention 432000 → wall-clock cutoff (HeightAgo)manager_slasher_current.goSOL sibling scan 14400 → wall-clock floor (HeightAgo)handler_sol_nonce_attest.gore-attest minimum age 600 →RefBlocksSincexmr_genesis_delay*.goXMR monovault genesis delay 128 →RefBlocksat use- ebifrost
cachedBlocks10: the app wiresGetBlockTimeMsinto ebifrost (proposer-local) common/chain.goTRON solvency-voter quota window 10 → windows of wall-clock time since genesis, so the window index never goes back. Counting blocks, it went back after the block time went down, and every signer that had used its quota got "quota is ahead of current window" until the index caught up.querier.go/queue/scheduledscan 17280, the/queuescheduled value and the queue telemetry →txOutScanEnd:TxOutDelayMax + MaxTxOutOffsetat the current block time (maxTxOutWindow), but never less thanconstants.TxOutQueueScanBlocks(17280) reference blocks of wall-clock time, since lowering those settings (orTxOutDelayMax = 0) leaves queued outbounds in place.genesis.goexport scan 17200 →maxTxOutWindow, with the same kind of floorcommon.THORChain.ApproximateBlockMilliseconds()in queriers (quote*_seconds, order expiry, tx-stages ETAs) →thorchainBlockMs: the 6s approximation scaled byBLOCKTIMEMS/default. It is unchanged while the mimir is unset (on mocknet too).handler_tss.godurationToBlocks(6 min)for the XMR keygen window → uses the effective block time- node config
vault_pubkeys_cutoff_blocks→ wall-clock cutoff (HeightAgo). Bifrost uses/vaults/pubkeysto choose which vault addresses to watch, so a block-count cutoff dropped vaults early after a slowdown.
Left as they are:
- x/scheduler
MaxAfter = 100_000: a bound on a user-input block count (After, raw blocks like memo intervals), enforced in statelessValidateBasic. WithMaxMsgsPerHeightit also caps pending storage. common.Chain.ApproximateBlockMilliseconds()itself: it has no ctx. Callers with a ctx convert as above; bifrost andtools/eventscallers are out of scope.- Telemetry only:
IsPeriodLastBlock(ctx, blocksPerDay)for daily metrics, which follows the scaled BlocksPerYear.
Windows keyed to a block count
- Swap-slip rollups (
keeper_swap_slip.go) reset when the window shrinks and extend cleanly when it grows: blocks below the old window were already subtracted and deleted, so none is subtracted twice. Theheight % targetsnapshot changes phase once, which is acceptable for a rolling metric. A reset leaves the old window's per-block keys behind (as loweringMaxAnchorBlocksalready does on develop). Deleting them in the reset block could mean ~170k deletes in one EndBlock after a 500 ms → 6 s revert, so they are left. The anchor-slip snapshots are now pruned by wall-clock age (DynamicMaxAnchorSlipBlocks), so a slowdown no longer drops snapshots still in the window. - Dynamic-fee epochs already re-base
LastActiveEpochwhenL1DynamicFeeEpochBlockschanges (rebaseOnEpochBlocksChange). - Swap-queue, pool-cycle and churn alignments (
height % N) change phase once at a change.
Work a change would skip: fixed here
- Churn schedule. The churn now follows wall-clock time since the last churn. The regular churn fires in the block whose age (
RefBlocksSince(lastChurnHeight)) reachesChurnIntervalreference blocks, and retries fire each time it passes anotherChurnRetryInterval. Without a change these arelastChurnHeight + ChurnIntervaland everyChurnRetryIntervalblocks after it. Counting blocks, a change mid-cycle fired the churn early after a slowdown (a deadline already "passed" in blocks) and late after a speedup.TestChurnSurvivesBlockTimeChange: last churn at 30, interval 30 reference blocks, 20 of them at 1000 ms. At 2000 ms the churn fires at 55 (5 more blocks), with or without retries; at 500 ms it fires at 70 (20 more blocks). - LackSigning is covered below. With the block time history it reschedules each outbound once it is a full period old in wall-clock time, so no height is skipped or checked early.
- Ragnarok.
MsgRagnarokwalks the heights LackSigning rescheduled the outbound to. It steps by that outbound's own period (3× for XMR, EVM aggregator and EVM token outbounds), with or without a history, applied to theSigningTransactionPeriodLackSigning reads (GetConfigInt64Ref, mimir included). A mimir at or below zero keeps the walk to the constant's period, since a zero step would never leave the first height. Three rounded standard steps can overshoot the 3× height at a block time, or a coalesce interval, that doesn't divide the period, which would slash a valid retry. Each step lands on the height LackSigning actually queues the retry at (BlockTimeHistory.RescheduleHeight): the due block rounded up toRescheduleCoalesceBlocksat its block time, then moved by later changes. Each retry is searched once it is due, even while it is still queued ahead of the current block. Walking due blocks only missed the coalesced retry (due 10551, retried 10560 after a halving) and slashed the vault. Develop's fixed 300-block stride missed it whenever the outbound was queued off the interval. The computed heights assume the currentRescheduleCoalesceBlocks, but a retry keeps the value of the block LackSigning ran in. LackSigning can also leave a copy live for good (no vault or pool, retired-vault recovery exhausted, a SOL durable hold, a failed treasury recovery or queue add), and a SOL durable nonce reissue moves a copy off the schedule. So when the computed height holds no copy of the outbound (blankInHash, same chain, destination, asset andRAGNAROKmemo), the walk scans up from the last copy to the next: to one signing period past the due block, and, for SOL before the next due block, torescheduleReach. After a scan finds none it keeps to the computed heights. When the computed height holds a copy, it reads nothing extra. DiscoverOutbounds can split a payout across vaults into parts that share that identity and are retried on their own, so the copy at a computed height can be another part's. Once a record on the walk holds more than one copy, the walk skips that jump and visits every copy in height order. LackSigning also places a retry with theSigningTransactionPeriodof the block it runs in, while the walk computes the next due block from the current period. So before the next due block the walk also scans when the record holds a replaced copy (OutHashblank, set when LackSigning or the SOL reissue queues the replacement), since the replacement may have been queued under an earlier, shorter period. Without that, after a raise from 300 to 600 the walk put the next due block of a payout queued at 10000 at 10600, stopped when the payment of its 10300 retry was observed at 10302, and slashed the vault. SOL, whose reissue can queue a copy before it is due, always scans (common.Chain.QueuesOutboundCopyBeforeDue). Without a replaced copy the reads are unchanged. - SOL durable-nonce reissue (
reissueSolDurableAt) clamps its scan withRefWindowStartand counts attempts withoutboundAttempts, as LackSigning does. Counting blocks at the current period, the scan skipped siblings LackSigning had not reached yet after a slowdown, and after a speedup its attempt budget disagreed with LackSigning's.
Outbound windows in wall-clock time
A fixed block count is the wrong window for an outbound across a change. When the block time goes up (including an emergency revert), outbounds scheduled at the faster rate sit more blocks back and more blocks ahead than the new period and offset reach. Without this section:
- LackSigning would reschedule them as soon as they fell outside the shorter window, while they were still in flight (broadcast, not yet observed). That is a double spend.
- Outbound matching would miss them, so their observations would not close the item. The result is a double spend plus a false slash.
GetPendingOutbounds,migrateFunds, the over-solvency check andCalcTxOutHeightwould stop their scans short. Owed funds would count as free, and the over-solvency treasury sweep is live on mainnet.- Bifrost would keep its old constants for up to a churn interval, so it could sign after THORChain rescheduled.
The fix:
- History.
UpdateBlockTimeappends each change to a block time history (blocktime/history, aBlockTimeHistoryproto).constants.BlockTimeHistorymeasures wall-clock time over it:HeightAgo(now, ms): the newest height that is at leastmsold atnow.Reach(now, refBlocks): the furthest height a window could have scheduled to from any block so far.
- Keeper helpers.
RefWindowStartandRefWindowEndwrap these. Without a change they reduce exactly tonow − periodandnow + offset. A non-positive window passes through as plainnow − refBlocks/now + refBlocks, as on develop. History reads use an infinite gas meter, and every caller reads the same mimirs as before, sogas_usedis unchanged. - LackSigning. Once a history exists, each block checks the heights that became a full period old (per class: standard, XMR, EVM aggregator, EVM token) since the previous block. That is several per block after the block time went up, none in some blocks after it went down, and each height exactly once. This replaces the change-block catch-up.
- Rescheduled-outbound scans. LackSigning rounds a retry up to the next multiple of
RescheduleCoalesceBlocks, and a later block time change moves the retry so it keeps its wall-clock time left. After a speed-up the retry can then sit past the next multiple of the newly scaled interval: a retry at 10120 moves to 10129, while scans from 10113 stopped at 10120. A late observation from the same vault missed the retry and slashed the vault.BlockTimeHistory.CoalesceReachreplays the round-up and every conversion since (ConvertHeight, whichconvertStoredHeightsalso uses) to find the furthest height such a retry can sit at.rescheduleReachis the upper bound forCommonOutboundTxHandler,findOriginalMemoForOutbound, the SOL sibling scan and/queue/outboundpending. Without a change it is the old round-up, read the same way. - Same windows everywhere. These now use the same windows:
GetPendingOutbounds,migrateFunds, the over-solvency backward and forward scans,CalcTxOutHeight,ExportGenesis,maxTxOutWindow, outbound matching (handler_common_outbound.go,findOriginalMemoForOutbound), the SOL durable-nonce reissue scan, and the/queue,/queue/outboundand/queue/scheduledqueries. - API.
/thorchain/constantsreturnsblock_time_msandblock_time_history(the latter omitted while empty) in the same response as the scaled constants. - Bifrost:
ConstantsProviderrefreshes as soon asblock_time_msor the history changes. The history's length plus its last segment identify a revision, so a change and its revert between two lookups still refresh. It pairs the constants with the block time and history read before and after them, retrying if either moved in between. That before/after read is nowsigning.ReadConstantsin the shared signing package, so the EVM and ETH unstuck paths use it too.- The signer's stale check (
signingWindowExpired) measures an outbound's age in wall-clock time over the same history, as THORChain does. Without a change it is the old block comparison. reschedule_buffer_blocksis read as reference blocks of time: scaled in the EVM and ETH unstuck paths, and in milliseconds in the signer.
Stored deadlines and lockups
- Deadlines stored as a future height are converted once, in the block where the block time changes (
convertStoredHeights, called fromUpdateBlockTime). Each keeps the wall-clock time it had left: a deadline at D after a change at H becomesH−1 + ceil((D−H+1)·prev/new). Deadlines at or before H are left alone. Converted:- jail release heights
- the outbound delay queue: the whole queue, out to
TxOutDelayMax + MaxTxOutOffsetas every earlier block time could have scheduled it (never less thanTxOutQueueScanBlocks, the same span astxOutScanEnd). FutureTxOutheights are moved and merged, and their voters'OutboundHeightfollows. Past the offset the queue stays contiguous: a converted height there directly follows the previous queued height (or the offset), because scans stop at the first empty height past the offset. Those outbounds go out a little sooner, never later. Converting only out toTxOutDelayMaxleft the tail unconverted past a gap after a slowdown, so solvency scans missed those unpaid outbounds and read them as surplus. - THORName expiries
- the limit-swap TTL index. The moved hashes are grouped by destination height, so each destination bucket is read and written once, with the same store bytes as moving them one by one (the destination's own hashes first, then each source's in key order, deduplicated under
TxID.Equals). Users can point any number of limit swaps at one expiry height, and moving them one at a time cost K reads and writes of a growing list per bucket: 4096 orders in one bucket took about 1.8e10 gas in the change block, and now take about 1e7. - the
NodePauseChainGlobalpause height - the observation tally queue (keyed by due height). Each tally is re-keyed to
RefHeightAfterfrom its consensus height over the history that includes the change, the height its refund window closes at (see observation scoring below), rather than converted withConvertHeight, which rounds up once per change. A record whose consensus height can't be read keeps the converted height. - the missing-observation guard's refill height (
ObservationGuardFullAt) - refund-cleanup marker expiries (marker and its expiry index)
- Lockups are now measured in wall-clock time since the stored height (
RefBlocksSince,RefHeightAfter):BondLockupPeriod(unbond),LiquidityLockUpBlocks(withdraw),RUNEPoolDepositMaturityBlocks, and the bond lockup onLEAVEfor a node that already churned out (handler_leave.go, which had its own copy of the unbond check). Their error heights and block counts come from the same history. A limit swap's age check (IsDone) reads its TTL in blocks of the block time it was placed at, so it agrees with its converted TTL entry. - Cost: without a change, every one of these is the old arithmetic. The conversion runs once per change and iterates every jail, every THORName, the TTL index, and the delay queue window. On mainnet that is tens of thousands of writes in the change block.
Ages and attempt counts in wall-clock time
Code that measured an age as now − height against a block count now uses RefBlocksSince against the value in reference blocks. Code that scanned a window back from now uses RefWindowStart/HeightAgo. Without a change each is the old arithmetic, and each reads the same mimirs, so gas_used is unchanged.
- Funds-risk:
- Outbound attempt counts (
outboundAttempts):MaxRetiredVaultRecoveryAttempts(100, live on mainnet),MaxOutboundAttempts(treasury recovery and the SOL durable-nonce reissue budget) and the durable-nonce stuck alert. Counting blocks at the current period, 9999 blocks at 1500 ms followed by a change to 6000 ms counted as 199 attempts instead of 49, so a retired-vault outbound was dropped from the queue after ~12.5 h instead of ~50 h. - Solvency report exclusion (
excludePendingOutboundFromVault): an outbound scheduled under the faster block time and still in flight dropped out of the deduction after a slowdown. The vault then looked short and the chain could be halted for solvency. - Bond lockup on leave (above).
- Streaming-swap credit against the outbound delay (above).
- Outbound attempt counts (
- Signer and slasher:
- Stale outbound observation (
staleNonFinalOutboundObservation, 3 periods) and the reassignment waiting window (needsNewVault) DoubleSignMaxAge- Round-7 retry attempts in bifrost (
round7Attempts), matching THORNode's count - Ragnarok outbounds:
handler_ragnarok.gofollows the heights LackSigning reschedules to (one period of wall-clock time apart, by the outbound's own period class) instead of a fixed block stride FailKeygenSlashPointsrestored to a late keygen signer is now scaled to the block time at consensus, when it was charged, so a change in between no longer leaves a difference
- Stale outbound observation (
- Churn and vaults:
- Churn schedule (above), migration rounds (
nthand the round tick inmigrateFunds), stale pending migrates (migrateFundsandGetPendingOutbounds, kept identical), and the churn's pending-outbound count (getPendingTxOut) - Keygen result validity (
handler_tss.govalidate andhasPendingKeygen): a result for a keygen scheduled under the faster block time was rejected after a slowdown, stalling the churn until the next retry.hasPendingKeygenscans from the oldest height the validity check can still accept (RefBlocksSincerounds down). - Low-version churn-out grace (
ChurnOutForLowVersionBlocks) - Vault security ordering (
SortBySecurity,GetMostSecure,GetLeastSecurenow take the period in reference blocks)
- Churn schedule (above), migration rounds (
- Observation scoring: the
ObservationDelayFlexibilitywindow for late observers (inbound, outbound, network fee, solvency, TSS, errata). The tally scores a voter atRefHeightAfter(consensus height, flex), andwithinObservationFlexrefunds a late signer whilenow <= RefHeightAfter(consensus height, flex), so the refund window closes in the block where the tally scores. A refund check ofRefBlocksSince(height) <= flexrounds down and stayed open past the tally: at half the reference block time the tally scored at H+20 while a signature at H+21 was still refunded, so the node was counted missed for a voter it had been refunded for, which feeds churn-out. A negative flex refunds nothing, as on develop. Also the missing-observation guard grace (MissingObservationGuardMaxBlocks), which ran out up to 4× early after a slowdown. - Other ages:
MemolessTxnTTL(reference memo expiry, register, preflight, genesis),CloutReset,PendingLiquidityAgeLimit. - Queries and telemetry:
/queuescheduled value, the queue metrics and stuck-outbound telemetry, and/vaults/pubkeys.
Genesis export
The export scans the outbound queue up to max(now + TxOutDelayMax + MaxTxOutOffset, RefWindowEnd(17200)), so it never covers less than the fixed span it used before. Lowering those settings does not move outbounds that are already queued.
GenesisState carries the latched block time and its history (block_time_ms = 51, block_time_history = 52, both omitted while unset, so no export fixture changes). InitGenesis restores them first, before the ages above are used.
Without this, an export/import at a non-default block time reset the latched value to the default. The first BeginBlock then re-latched BLOCKTIMEMS as a new change and converted every stored deadline as if it had been set at the default block time. ValidateGenesis checks that the two are set together, that heights ascend, and that the last segment matches the latched value.
Rate limit
UpdateBlockTime latches the target in steps:
- A step back toward the default
ThorchainBlockTime, without going past it, applies at once, so a bad change can always be undone in one block. - Any other step waits until
ChurnIntervalof wall-clock time has passed since the previous change, and moves at most half or double the current block time. On mainnet, 6000 ms → 1500 ms takes two steps one churn apart (3000, then 1500).
The commit wait (part 1) steers to each latched step, not to the final target, so the real block interval and the scaled durations stay in step throughout.
TestBlockTimeRateLimit walks the steps in both directions. Tests that need a larger jump seed the history with SetBlockTimeHistory, the genesis restore path.
Deliberately left in blocks
- Governance heights (
Halt*, upgrade heights,ScheduledMigration): absolute heights set by people, not derived from a duration. Operators must re-plan them after a change.NodePauseChainGlobalis converted because the protocol computes it fromNodePauseChainBlocks. - Leave score, churn-out score and node rewards (
(now − StatusSince)/slash points,earnedBlocks/totalActiveBlocks): ratios of per-block quantities. Slash points likeMissBlockSignSlashPointsaccrue per block, so measuring the age in blocks keeps the ratio consistent across a change. Measuring it in time would bias against nodes during fast periods.MissingBlocksversusMissingBlockChurnOutis the same kind of comparison. - Modulo cadences (
PoolCycle, epochs, the pending-liquidity cleanup rotation, theheight % FundMigrationIntervalpool check,IsPeriodLastBlock): change phase once. - User-specified block counts (x/scheduler
After, streaming interval, custom TTL). - The XMR monovault bootstrap delay: a one-off keygen scheduled a few minutes ahead. A change in between moves it by at most that.
- Bifrost blockscanner flex (
blockscanner.go): it looks upc["6s"], gets 0, and always uses 1 block (a bug already on develop). It does not depend on the block time, so fixing it belongs in its own MR.
Bifrost timing
- One block time for the whole process. New leaf package
bifrost/blocktimeholds THORChain's block time as Bifrost last read it. The bridge sets it whenever it readsblock_time_ms(GetBlockTime, which the signer'sConstantsProvidercalls every block). Before the first read, and whileBLOCKTIMEMSis unset,blocktime.Get()is the defaultThorchainBlockTime, so every timer below is unchanged. - Follows the block time (work done about once per THORChain block):
- the bridge's one-block HTTP response cache and the pool cache
- the chain-halt mimir check intervals (block scanner, SOL scanner)
- the pubkey manager's per-block fetch and the EVM unstuck loop
- the halted-chain solvency runners: callers pass 0, and the runner waits one block at the current block time on each pass
- the per-block caches for asgard addresses (UTXO, XMR), XMR consolidation config, and the TSS version checks
- tickers in the XMR errata maintenance and retry, keygen retry and XMR keygen workers, and XMR consolidation:
blocktime.NewTickerre-reads the block time before each tick
- Left on the default 6 s, because they are timeouts, error backoffs or retry budgets (an interval times a maximum number of attempts), and shrinking them would cut the time allowed: the HTTP request timeout, queue-send timeouts, persistence and attestation waits, the mempool and catching-up backoffs, and the XMR recovery and spent-ref retry intervals.
- Raw mimir reads. The duration mimirs Bifrost reads raw are in reference blocks, and most were already converted with the reference 6 s, so they are wall-clock correct:
KeygenRetryInterval(× 6 s),SignatureRefreshBlocks(× the SOL slots in one 6 s reference block, from develop's SOL slot-time mimir),OracleUpdateInterval(ms). The rest are flags, counts or heights. The exception was the keygen acceptance window and retry grid. They now measure wall-clock time since the keygen over the block time history (keygenRefElapsed), matching THORNode'sRefBlocksSincecheck. A prepared retry stores its boundary in reference blocks and fires once fresh history reaches it, so nodes that prepared before and after a change fire together. - Signer safety:
- EVM and ETH unstuck measure a signed outbound's age and its period phase in wall-clock time over the history (
signing.UnstuckWindow), as the signer does. Unstuck therefore never clears the signer cache while the signer could still re-sign before THORChain reschedules. - EVM and ETH unstuck read the constants together with their block time and history (
signing.ReadConstants). They used to read them in two requests, so a bridge cache refresh in between could pair an old signing period with a new block time and open the unstuck window early. - The constants provider fails closed when the block time can't be read, instead of serving cached constants whose history could miss a change.
- EVM and ETH unstuck measure a signed outbound's age and its period phase in wall-clock time over the history (
Tests
- Unit tests:
constants: unit coverage, scaling math, overflowkeeper/v1: scaling, clamping, identity, gas neutrality, THORName fees; mainnet tag: 6s reference and the 1500 ms floor- churn and LackSigning across a block-time change
- the latch: no write while unset, effective from the next block
- the analyzer's testdata
app/divergence:TestThorchainPrefixesMatchKeepercovers the newblocktime/prefix
- Full mocknet unit run plus
-raceon the touched packages. - Regtest
suites/blocktime/duration-scaling.yaml:- sets
BLOCKTIMEMSto 500 (half of mocknet's 1000) - asserts the scaled
/thorchain/constantsvalues (durations ×2, rates ÷2, counts unchanged) - checks a keysign-failure jail releases after 20 blocks instead of 10
- checks a change takes effect from the next block, and that unsetting restores everything
- asserts
/thorchain/networkblock_time_msis 1000, then 500, and 1000 again once unset
- sets
- History and windows:
constants: brute-force checks ofHeightAgoandReachagainst a block-by-block sum over several histories, including that each height is checked exactly oncekeeper/v1: history recording,RefWindowStart/RefWindowEnd(including non-positive windows, which keep develop'snow − periodgas parity), gas neutrality, andGetPendingOutboundsacross a 500 → default revert- slasher: no early reschedule after the block time goes up, and the exact due block in both directions
- bifrost:
signingWindowExpiredin both directions, the refresh on a block time change and on a history-only change (a change and its revert between lookups), and parsingblock_time_ms/block_time_history
- Stored heights:
keeper/v1: one change converts jails, THORNames, the delay queue (two heights merging into one, with their voters), the TTL index and the pause height, and leaves past deadlines alone; alsoRefBlocksSince/RefHeightAfterwith and without a change- adv swap queue: a limit swap placed under 500 ms expires after the same wall-clock time, at the height its converted TTL entry fires
constants:ElapsedMsandHeightAfterchecked against a block-by-block sum
- Regtest
suites/blocktime/stored-heights.yaml:BLOCKTIMEMS500 → 0 with a jailed node and a pending THORName. The jail release moves 25 → 17 and the expiry 60 → 35. The name is live through 35 and expired at 36. - Ages, attempts and the rate limit:
- slasher:
outboundAttemptsover a 1500 → 6000 ms change against a real keeper (49 attempts where counting blocks gives 199; 99 and 100 at the exact boundary), a retired-vault outbound rescheduled at 51 periods and abandoned at 100 through LackSigning, and stale-observation boundaries. Both attempt tests fail against the old block count. - solvency:
excludePendingOutboundFromVaultkeeps an outbound 70 blocks back (195 reference blocks) after 1500 → 6000 ms, at the exact window edge withinObservationFlex,referenceMemoExpiredandrestoreCloutacross 1500 → 6000 ms- keeper: one change moves the observation tally queue and refund-cleanup expiries (
TestBlockTimeChangeConvertsTalliesAndRefundCleanups, with the flex that gives its due height);TestBlockTimeRateLimit - churn:
TestChurnSurvivesBlockTimeChangenow expects the wall-clock schedule - genesis: the block time round-trips, a re-latch after import is not a new change, and invalid histories are rejected
- slasher:
- Review fixes:
- The queue stays contiguous past the offset after the block time halves (
GetPendingOutboundsfinds all 8, against 5 under a plain mapping). hasPendingKeygenat 500 ms at the rounding edge.- The export keeps an outbound at now+800 after
TxOutDelayMaxis lowered. /queue/scheduledstill lists queued outbounds afterTxOutDelayMax/MaxTxOutOffsetare lowered.- Ragnarok after a change lands on the extended (3×) retry height without slashing.
- A keygen retry prepared before a change fires with one prepared after.
UnstuckWindowacross a doubling, and the constants provider failing closed.- The queue and keygen tests fail against the previous code.
TestLateObservationFindsRetryMovedByBlockTimeChange: LackSigning at 10111, a 2x speed-up at 10112, then a late observation at 10113 is matched to the retry moved to 10129. Before the fix it slashed the vault.TestCoalesceReachMatchesBlockByBlockMaxcompares the reach with a block-by-block replay.TestRagnarokFindsCoalescedRetry: a retry made by real LackSigning, after a halving and off the interval without one, observed after its height and late before it; it is matched without a slash.TestRescheduleHeightMatchesBlockByBlockcompares the retry height with a block-by-block replay.- These all fail against the walk that follows only the computed heights:
TestRagnarokFindsRetryAfterCoalesceChange(huginn's PoC: coalescing off at the 10305 retry, 10 when observed; and 20 → 10, observed after the 10320 retry and late before it)TestRagnarokFindsRetryAfterCoalesceChangeBetweenRetries(0, then 10, then 20)TestRagnarokFindsCopyLeftLiveBySkippedReschedule(a no-pool skip leaves the 10310 copy live, observed several periods later)TestRagnarokFindsSolCopyMovedOffSchedule
- These fail against the previous walk:
TestRagnarokFindsXMRRetryWithOverriddenSigningPeriod(huginn: the mimir at 100, so real LackSigning retries XMR at 10300, observed at 10301 and 10650; a zero mimir still ends and slashes an unmatched payment)TestRagnarokFindsSplitPayoutPartMovedIndependently(huginn: SOL parts A and B reissued independently, A live at 10600 below B's computed retries; paying A, B, or another destination)
TestRagnarokFindsRetryAfterSigningPeriodChange: real LackSigning at period 300, then observed after a raise to 600 (at 10302, at 10599, coalesced, and once due again at 10650) and after a cut to 100. The three raised cases observed before 10600 fail before.TestObservationFlexWindowMatchesTally{AtReference,AtHalfBlockTime,AcrossBlockTimeChange}: a signature in the last refunded block is refunded and not missed, and one a block later is neither, at the reference block time, at half of it, and across a halving from the reference and from 0.7 of it. The half and across-change cases fail before, and the 0.7 case fails with only the refund boundary changed.TestConvertLimitSwapTTLsMatchesOneByOnecompares the store bytes with the per-hash conversion across duplicates, a lower-case copy, a destination that is also moved, and 4× slowdowns and speed-ups.TestConvertLimitSwapTTLsLargeBucketIsLinearbounds the gas for a 4096-order bucket and fails against the per-hash conversion.
- The queue stays contiguous past the offset after the block time halves (
- Outbound delay, outbound queue and SOL reissue:
TestCalcTxOutHeightKeepsWallClockDelay: a 258 RUNE backlog delays 8 blocks at the default block time, 16 at 500 ms and 4 at 2000 ms. The old code hit the 1440 offset cap at 500 ms and gave 2 at 2000 ms.TestAddOutTxItemCreditsStreamingWallClockTime: a stream from inbound consensus at 10 that ran 399 blocks at 250 ms and 11 at 1000 ms is credited 110 blocks at 420 (110.75 s), not 410.TestCalculateNetworkSolvencyAfterBlockTimeIncrease: 20 unpaid outbounds queued pastTxOutDelayMaxat 500 ms stay contiguous after the revert to 1000 ms (heights 105–114), and solvency counts all of them (150 held − 100 owed − 20 = 30).TestReissueAfterBlockTimeChange: after quarter-length blocks, the reissue still reaches a waiter more than 300 blocks back that LackSigning has not seen yet, and an outbound finalised 300 blocks ago (about 82 reference blocks) is still within a one-attempt budget.signing.ReadConstantsretries when the block time or history moves during the read, and the EVM and ETH unstuck tests check that a refresh between the reads doesn't open the window early.
- Bifrost:
blocktimeget/set and the ticker following a change (40 → 400 → 20 ms); the bridge response cache going stale at three quarters of the old block onceblock_time_mshalves; the keygen window and retry grid across a change (target 2851 where counting blocks gives 2900);SignatureRefreshBlocksunchanged by the block time (TestKeepAliveDueIgnoresBlockTime, reading slots per THORChain block through the SOL slot-time mimir);go test -tags=mocknet ./bifrost/...passes. - Regtest
suites/blocktime/solvency.yaml:BLOCKTIMEMS500 → 0 with an in-flight outbound (0.0826 BTC from the dog vault at 4). At 18 the outbound is 14 blocks old but 8.5 s, and a solvency report of the vault's balance less the outbound is solvent: BTC is not halted, the vault is unchanged, and the outbound is rescheduled at 20. With the block-count check put back, the same suite halts BTC (negative control run locally). - Regtest
suites/blocktime/revert.yaml:BLOCKTIMEMS500 → 0 with an in-flight outbound and a queued (scheduled) one.- The in-flight outbound is past the new period in blocks but not in time. It is not rescheduled in the change block, and is rescheduled at exactly the block where it becomes 10 s old.
- The queued outbound, scheduled 40 half-length blocks ahead, is moved at the revert to keep its time (48 → 32) and goes out at 32.
- Identity check: a full
make test-regression CI=1 EXPORT=1 DEBUG=1(196 suites, 0 failed) leaves every export and block fixture outsideblocktime/unchanged. The blocktime suites' exports gain the newblock_time_msandblock_time_historygenesis fields, and the new suite's fixtures are added.