contributor-rewards, solana-cli, validator-debt: fix the hardcoded 400ms slot times

[nikw9944]

Summary of Changes

Five call sites divided wall clock by a hardcoded 400ms slot duration. They get three independent fixes rather than one shared helper, because they want different answers: the two accuracy-critical sites stop depending on a slot-duration constant at all, and the two that keep one now share a single value.

• contributor-rewards — find_epoch_at_timestamp verifies its estimate against real block times. The old estimate drifted ~30k slots per day of lookback and no fixed constant survives the SIMD-0525 rollout. That epoch picks the leader schedule rewards are computed against, so the search errors rather than guessing.
• solana-cli — the duplicate constants in shreds pay and prepare-offchain-message collapse into one 350ms NOMINAL_SLOT_DURATION, deliberately cluster-independent: a ~ prefixed estimate and a deadline slot the CLI and operator must both compute want reproducibility over accuracy.
• validator-debt — deletes two dead timestamp-to-epoch paths and both constants. rpc.rs already does this mapping correctly for production; the deleted code had no callers and contained an unsigned subtraction that panicked in debug and wrapped in release.

Fixes malbeclabs/infra#2317

Before merging

• --valid-for windows lengthen. --valid-for 1h is now 10,285 slots, not 9,000. Mainnet reaches 350ms at epoch 1020 (2026-08-21); until then the flag grants ~68 minutes. Testnet runs at 200ms, so ~34 minutes. The help text states the conversion rate.
• The demand path can now fail where it used to be wrong. ingestor/demand.rs propagates a leader-schedule error, so a backfill older than the endpoint's ledger retention errors instead of silently mis-estimating. The snapshot paths warn and continue, but snapshot now validates before writing rather than leaving an unusable file behind.
• 350ms needs one more bump when SIMD-0525 finishes stepping mainnet to 200ms. Nothing enforces it; the constants' comments record the schedule.

Follow-ups to file

• Extract the shared block-time epoch search into doublezero-solana-client-tools. Two now exist and each names the other in a comment. Unify once the new one has run a few epochs in production.
• estimate_block_time_for_skipped_slot in validator-debt/src/rpc.rs still assumes 0.4s per slot implicitly — the last live 400ms assumption in the repo.
• SolanaClientError is logged with {:?} in five places in ingestor/epoch.rs; a Reqwest variant renders the request URL, which usually carries an ?api-key=. Pre-existing at four, so it wants one pass over all five.

Testing Verification

• Pure-function tests for the search's per-step decision (both bounds, the unbounded current-epoch case, the unstarted-epoch case), the absent-block classifier (each of the three shapes getBlockTime uses, plus a pruned ledger failing closed), and the epoch-boundary skip budget (exclusive edge, a history gap, and a short-epoch cluster). No RPC mock, and no new dependency.
• CLI assertions recomputed by hand from the 350ms derivation, with the arithmetic in each test comment. The deletions are checked by clippy -Dwarnings, which catches every orphaned import and unused constant.
• Not verified locally: prepare-offchain-message --valid-for 1h --json reporting a deadline_slot exactly 10,285 above current, and a snapshot near an epoch boundary resolving to the epoch its boundary block times imply. Both need mainnet after epoch 1020.

[ben-dz]

Mostly good, three things worth fixing, none blocking. The 350ms seed points the first probe older than the target, so a timestamp inside the endpoint's retention can still hard-fail; the 128-slot boundary walk hand-rolls getBlocksWithLimit and turns a long skip run into a permanent failure; and create_snapshot writes a schedule-less snapshot to the canonical filename and exits 0. Plus a repetition nit.

[nikw9944]

All four addressed in 3c94525. Replies are on the individual threads; the short version:

• Seed direction. SEED_SLOT_DURATION_US moves to 500_000, deliberately slower than any real cluster rate, so the seed lands at or after the answer and the walk runs backward only. The oldest slot probed is now inside the answer's own epoch. Added const _: () = assert!(SEED_SLOT_DURATION_US > 400_000); so the inequality the argument depends on cannot rot with the comment. Kept the forward step: the local clock, not the chain, decides where the seed lands, so overshoot the other way is still possible.
• Boundary lookup. getBlocksWithLimit(first_slot, 1) replaces the forward walk, dropping the 128-slot cap and the unrecoverable bail. Bounds now carry across search steps, so only the far-side bound is fetched per step.
• Snapshot validation. snapshot.validate()? before the export branch.
• Repetition nit. Trimmed the duplicated pruned-ledger explanation across the two error classifiers.

Two things I did not change, both flagged in the thread replies rather than silently skipped:

• try_chain_tip_block_time still walks backward with getBlockTime rather than a getBlocks range query. It resolves on the first probe normally and its bound is a stall check, not a skip tolerance, so converting it is churn without a win. Happy to make it match if you would rather.
• The pre-loop upper-bound fetch stays eager. Making it lazy means splitting decide_epoch_search_step across the call site, and that pure function is what the boundary tests actually exercise, so I would rather spend the one round trip than lose the test surface.

One consequence of the getBlocksWithLimit swap worth a second look, since it changes a meaning rather than just an implementation: Ok(None) from try_epoch_start_block_time is now reachable only from the first_slot > current_slot pre-check. An endpoint reporting no block for an epoch already in the past errors instead, because that is missing history rather than an empty epoch, and returning None there would walk the search backward past the right answer.

just fmt-check, whole-workspace clippy -Dwarnings, and cargo test --workspace all pass locally. Base branch was already current, so no rebase was needed this round.

[ben-dz]

Two new issues in the rewritten try_epoch_start_block_time: the ensure! bounds the returned block only at the epoch boundary, so an interior block-history gap silently dates the epoch late (round 1's walk failed closed after 128 slots); and an epoch that has started but has no finalized block yet now errors rather than bounding nothing. Neither blocks, but the first turns on whether the production endpoint can have interior gaps.

[nikw9944]

All three addressed in c67728d. Individual replies are on the threads.

The interior-gap one was a regression I introduced last round, not a pre-existing gap, and it is worth naming precisely because the fix is not "put the cap back". Your round-1 point stands: a work cap is wrong, since a settled skip run past it is unrecoverable on a readable boundary. My mistake was treating that as the only bound in play. The distance from the boundary is also a trust bound, and dropping the sequential walk did not remove the need for it — it just made keeping it free, since getBlocksWithLimit costs one round trip regardless. So can_date_epoch_start bounds the result at MAX_BOUNDARY_SKIP_SLOTS (432, 0.1% of a mainnet epoch, ~2.5 min), min'd with the next epoch's first slot so a short-epoch cluster cannot accept a block from a later epoch. The number is a tradeoff pick, not a derivation; say so if you would place it elsewhere, since nothing structural depends on the value.

The blockless-tip one was an internal inconsistency: I wrote try_chain_tip_block_time because getSlot can name a blockless slot, then used the raw getSlot value as the started/not-started boundary. It now returns the slot alongside the time, and the epoch lookup measures against that. This also makes the empty-result branch provable rather than plausible — the tip slot has a block, so an epoch starting at or before it must too, meaning an empty answer can only be missing history. The error text cites the tip slot instead of claiming "already in the past".

The retry predicate is now shared as is_settled_block_error across both call sites, so the two-part condition cannot drift. Took this one despite the Optional tag, since a pruned range on that path sleeps the full backoff schedule and demand.rs propagates it.

New pure-function tests cover the budget edge (exclusive), a short skip run, a 100k-slot history gap, and the short-epoch case where the min binds. just fmt-check, whole-workspace clippy -Dwarnings, and cargo test --workspace pass locally; base was already current, so no rebase this round.

Nothing else changed, and I am not aware of any finding from either round still outstanding.

[ben-dz]

lgtm — I don't love having anywhere that the 350ms is hard coded, but it seems to be only left in solana-cli's NOMINAL_SLOT_DURATION (command/shreds/mod.rs:33), with two consumers, so its pretty narrow.

[bgm-malbeclabs]

looks good - thanks for getting rid of some of the old cruft