feat: set THORChain block time with a BLOCKTIMEMS mimir and scale block-denominated settings

🔎 Visual review of 12ca12af: 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 *ConsensusConfig with the server context. cmd/thornode attaches that pointer in PostSetup.
  • A BaseApp Precommiter (app/app.go) runs inside Commit on the consensus goroutine, right before CometBFT's updateToState reads TimeoutCommit for the next height. The write is synchronous, so there's no data race.
  • Steers to the latched block time. While BLOCKTIMEMS is set, the hook's target is the block time that part 2's UpdateBlockTime latched (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 at target − 1.1s, and on a negative interval or one over 10× target it falls back to config.toml's timeout_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. BLOCKTIMEMS is pinned in IsOperationalMimir's exactUnmatches, so no future partial-match rule can make it operational. Block time changes emission and every timeout.
  • Inert until the mimir is set. While BLOCKTIMEMS is unset or 0, TimeoutCommit is never touched. Voting 0 after a target restores config.toml's value. A mimir vote can't delete the key, so 0 means "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. MsgMimir validation 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: regtestStart never runs PostSetup, so REGTEST_TIMEOUT_COMMIT stands.

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

  • BlockTimeMs constant + mimir validation + docs/mimir.md

  • app/blocktime controller + 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 TimeoutCommit untouched; hook race test; go test -tags=mocknet -race for 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 !mocknet test

  • 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 in scripts/test-quality-inventory.py); --check-selection passes

  • CI: .govulncheck-ignore allowlists 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 lint clean

  • 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_commit 1s, ~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, one ChurnInterval apart:

    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). TestControllerMinWait fails 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 = 1 exactly while the mimir is unset or 0, and every conversion is then the identity. Integer math only.
  • Unit tags (constants/units.go): every ConstantName has 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).
  • The block time is latched per block. At the start of BeginBlock, UpdateBlockTime takes the BLOCKTIMEMS target (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 in app/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.GetConfigInt64 applies 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 bypass GetConfigInt64.
    • RefBlocks(ctx, n): for hardcoded counts.
  • Gas: BLOCKTIMEMS is read on a throwaway gas meter, so the conversion never changes a tx's gas_used (unit test TestGetConfigInt64ScalingChargesNoGas).
  • Bypassing reads: every direct GetInt64Value/GetMimir read of a Duration or Rate key in x/ now goes through GetConfigInt64 or ScaleConfigInt64. The original fallback semantics are kept, e.g. <= 0 versus < 0. Reads converted:
    • SigningTransactionPeriod (×9)
    • BlocksPerYear (emission, THORName)
    • DoubleSignMaxAge
    • JailTimeKeygen / JailTimeKeysign
    • FailKeygenSlashPoints
    • the ChurnRetryInterval fallback
    • BondLockupPeriod (leave/unbond)
    • TxOutDelayMax / MaxTxOutOffset (queue metrics, queriers)
  • Outbound delay (CalcTxOutHeight): the delay is computed and capped in reference blocks (MinTxOutVolumeThreshold, TxOutDelayRate, MaxTxOutOffset read with GetConfigInt64Ref) and converted once with RefBlocks. 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 is ctx.BlockHeight() − voter.Height, as before.
  • Analyzer: tools/analyze -unscaled_config, wired into scripts/lint.sh. It flags a GetInt64Value(constants.X) or GetMimir(ctx, constants.X.String() | "X") of a Duration or Rate key when the enclosing function never passes constants.X to ScaleConfigInt64. 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/constants shows constants at the current block time. /thorchain/mimir still shows the stored (reference) values.
  • /thorchain/network has a new block_time_ms field: the block time in force for this block (the latched BLOCKTIMEMS), or the network default while it is unset. /thorchain/constants still shows the default BlockTimeMs, 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:

  1. 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").
  2. POLMaxPoolMovement as a Rate rounds small values down. At 2s, a value of 1 becomes 0.
  3. MemolessTxnTTL is a Duration. Lowering the block time raises it in blocks, and per docs/mimir.md raising it revives already-expired references until one TTL has passed.
  4. 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.go refund-cleanup retention 432000 → RefBlocks, and the stored expiry is converted at a change
  • keeper_xmr_spent_refs.go spent-ref retention 432000 → wall-clock cutoff (HeightAgo)
  • manager_slasher_current.go SOL sibling scan 14400 → wall-clock floor (HeightAgo)
  • handler_sol_nonce_attest.go re-attest minimum age 600 → RefBlocksSince
  • xmr_genesis_delay*.go XMR monovault genesis delay 128 → RefBlocks at use
  • ebifrost cachedBlocks 10: the app wires GetBlockTimeMs into ebifrost (proposer-local)
  • common/chain.go TRON 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/scheduled scan 17280, the /queue scheduled value and the queue telemetry → txOutScanEnd: TxOutDelayMax + MaxTxOutOffset at the current block time (maxTxOutWindow), but never less than constants.TxOutQueueScanBlocks (17280) reference blocks of wall-clock time, since lowering those settings (or TxOutDelayMax = 0) leaves queued outbounds in place. genesis.go export scan 17200 → maxTxOutWindow, with the same kind of floor
  • common.THORChain.ApproximateBlockMilliseconds() in queriers (quote *_seconds, order expiry, tx-stages ETAs) → thorchainBlockMs: the 6s approximation scaled by BLOCKTIMEMS/default. It is unchanged while the mimir is unset (on mocknet too).
  • handler_tss.go durationToBlocks(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/pubkeys to 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 stateless ValidateBasic. With MaxMsgsPerHeight it also caps pending storage.
  • common.Chain.ApproximateBlockMilliseconds() itself: it has no ctx. Callers with a ctx convert as above; bifrost and tools/events callers 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. The height % target snapshot changes phase once, which is acceptable for a rolling metric. A reset leaves the old window's per-block keys behind (as lowering MaxAnchorBlocks already 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 LastActiveEpoch when L1DynamicFeeEpochBlocks changes (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)) reaches ChurnInterval reference blocks, and retries fire each time it passes another ChurnRetryInterval. Without a change these are lastChurnHeight + ChurnInterval and every ChurnRetryInterval blocks 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. MsgRagnarok walks 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 the SigningTransactionPeriod LackSigning 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 to RescheduleCoalesceBlocks at 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 current RescheduleCoalesceBlocks, 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 (blank InHash, same chain, destination, asset and RAGNAROK memo), 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, to rescheduleReach. 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 the SigningTransactionPeriod of 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 (OutHash blank, 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 with RefWindowStart and counts attempts with outboundAttempts, 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 and CalcTxOutHeight would 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. UpdateBlockTime appends each change to a block time history (blocktime/history, a BlockTimeHistory proto). constants.BlockTimeHistory measures wall-clock time over it:
    • HeightAgo(now, ms): the newest height that is at least ms old at now.
    • Reach(now, refBlocks): the furthest height a window could have scheduled to from any block so far.
  • Keeper helpers. RefWindowStart and RefWindowEnd wrap these. Without a change they reduce exactly to now − period and now + offset. A non-positive window passes through as plain now − refBlocks / now + refBlocks, as on develop. History reads use an infinite gas meter, and every caller reads the same mimirs as before, so gas_used is 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.CoalesceReach replays the round-up and every conversion since (ConvertHeight, which convertStoredHeights also uses) to find the furthest height such a retry can sit at. rescheduleReach is the upper bound for CommonOutboundTxHandler, findOriginalMemoForOutbound, the SOL sibling scan and /queue/outbound pending. 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/outbound and /queue/scheduled queries.
  • API. /thorchain/constants returns block_time_ms and block_time_history (the latter omitted while empty) in the same response as the scaled constants.
  • Bifrost:
    • ConstantsProvider refreshes as soon as block_time_ms or 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 now signing.ReadConstants in 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_blocks is 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 from UpdateBlockTime). Each keeps the wall-clock time it had left: a deadline at D after a change at H becomes H−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 + MaxTxOutOffset as every earlier block time could have scheduled it (never less than TxOutQueueScanBlocks, the same span as txOutScanEnd). Future TxOut heights are moved and merged, and their voters' OutboundHeight follows. 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 to TxOutDelayMax left 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 NodePauseChainGlobal pause height
    • the observation tally queue (keyed by due height). Each tally is re-keyed to RefHeightAfter from its consensus height over the history that includes the change, the height its refund window closes at (see observation scoring below), rather than converted with ConvertHeight, 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 on LEAVE for 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).
  • 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.go follows 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
    • FailKeygenSlashPoints restored 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
  • Churn and vaults:
    • Churn schedule (above), migration rounds (nth and the round tick in migrateFunds), stale pending migrates (migrateFunds and GetPendingOutbounds, kept identical), and the churn's pending-outbound count (getPendingTxOut)
    • Keygen result validity (handler_tss.go validate and hasPendingKeygen): a result for a keygen scheduled under the faster block time was rejected after a slowdown, stalling the churn until the next retry. hasPendingKeygen scans from the oldest height the validity check can still accept (RefBlocksSince rounds down).
    • Low-version churn-out grace (ChurnOutForLowVersionBlocks)
    • Vault security ordering (SortBySecurity, GetMostSecure, GetLeastSecure now take the period in reference blocks)
  • Observation scoring: the ObservationDelayFlexibility window for late observers (inbound, outbound, network fee, solvency, TSS, errata). The tally scores a voter at RefHeightAfter(consensus height, flex), and withinObservationFlex refunds a late signer while now <= RefHeightAfter(consensus height, flex), so the refund window closes in the block where the tally scores. A refund check of RefBlocksSince(height) <= flex rounds 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: /queue scheduled 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 ChurnInterval of 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. NodePauseChainGlobal is converted because the protocol computes it from NodePauseChainBlocks.
  • Leave score, churn-out score and node rewards ((now − StatusSince)/slash points, earnedBlocks/totalActiveBlocks): ratios of per-block quantities. Slash points like MissBlockSignSlashPoints accrue 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. MissingBlocks versus MissingBlockChurnOut is the same kind of comparison.
  • Modulo cadences (PoolCycle, epochs, the pending-liquidity cleanup rotation, the height % FundMigrationInterval pool 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 up c["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/blocktime holds THORChain's block time as Bifrost last read it. The bridge sets it whenever it reads block_time_ms (GetBlockTime, which the signer's ConstantsProvider calls every block). Before the first read, and while BLOCKTIMEMS is unset, blocktime.Get() is the default ThorchainBlockTime, 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.NewTicker re-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's RefBlocksSince check. 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.

Tests

  • Unit tests:
    • constants: unit coverage, scaling math, overflow
    • keeper/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: TestThorchainPrefixesMatchKeeper covers the new blocktime/ prefix
  • Full mocknet unit run plus -race on the touched packages.
  • Regtest suites/blocktime/duration-scaling.yaml:
    • sets BLOCKTIMEMS to 500 (half of mocknet's 1000)
    • asserts the scaled /thorchain/constants values (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/network block_time_ms is 1000, then 500, and 1000 again once unset
  • History and windows:
    • constants: brute-force checks of HeightAgo and Reach against a block-by-block sum over several histories, including that each height is checked exactly once
    • keeper/v1: history recording, RefWindowStart/RefWindowEnd (including non-positive windows, which keep develop's now − period gas parity), gas neutrality, and GetPendingOutbounds across a 500 → default revert
    • slasher: no early reschedule after the block time goes up, and the exact due block in both directions
    • bifrost: signingWindowExpired in both directions, the refresh on a block time change and on a history-only change (a change and its revert between lookups), and parsing block_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; also RefBlocksSince/RefHeightAfter with 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: ElapsedMs and HeightAfter checked against a block-by-block sum
  • Regtest suites/blocktime/stored-heights.yaml: BLOCKTIMEMS 500 → 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: outboundAttempts over 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: excludePendingOutboundFromVault keeps an outbound 70 blocks back (195 reference blocks) after 1500 → 6000 ms, at the exact window edge
    • withinObservationFlex, referenceMemoExpired and restoreClout across 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: TestChurnSurvivesBlockTimeChange now 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
  • Review fixes:
    • The queue stays contiguous past the offset after the block time halves (GetPendingOutbounds finds all 8, against 5 under a plain mapping).
    • hasPendingKeygen at 500 ms at the rounding edge.
    • The export keeps an outbound at now+800 after TxOutDelayMax is lowered.
    • /queue/scheduled still lists queued outbounds after TxOutDelayMax/MaxTxOutOffset are 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.
    • UnstuckWindow across 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. TestCoalesceReachMatchesBlockByBlockMax compares 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. TestRescheduleHeightMatchesBlockByBlock compares 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.
    • TestConvertLimitSwapTTLsMatchesOneByOne compares 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. TestConvertLimitSwapTTLsLargeBucketIsLinear bounds the gas for a 4096-order bucket and fails against the per-hash conversion.
  • 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 past TxOutDelayMax at 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.ReadConstants retries 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: blocktime get/set and the ticker following a change (40 → 400 → 20 ms); the bridge response cache going stale at three quarters of the old block once block_time_ms halves; the keygen window and retry grid across a change (target 2851 where counting blocks gives 2900); SignatureRefreshBlocks unchanged 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: BLOCKTIMEMS 500 → 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: BLOCKTIMEMS 500 → 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 outside blocktime/ unchanged. The blocktime suites' exports gain the new block_time_ms and block_time_history genesis fields, and the new suite's fixtures are added.

🤖 Generated with Claude Code

Edited by Huginn Ai

Merge request reports

Loading
Loading