From 5481a2480a00b35c8c762a5261a66f5daa1832db Mon Sep 17 00:00:00 2001 From: hanabi1224 Date: Wed, 8 Apr 2026 07:18:24 +0800 Subject: [PATCH 1/3] doc: explain const FINALITY_CHAIN_EXTRA_EPOCHS --- src/rpc/methods/chain.rs | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/rpc/methods/chain.rs b/src/rpc/methods/chain.rs index 0e619d06c6d..4adea1cc24b 100644 --- a/src/rpc/methods/chain.rs +++ b/src/rpc/methods/chain.rs @@ -1196,6 +1196,16 @@ impl ChainGetTipSetFinalityStatus { find_threshold_depth, }; + /// Number of extra epochs to fetch beyond [`chain_finality`] when + /// building the chain sample for [`find_threshold_depth`]. + /// + /// [`find_threshold_depth`] probes epoch depths up to `chain_finality` + /// using a bisect search over the sampled chain slice. The extra epochs + /// provide a small tail buffer so that the bisect can safely evaluate + /// entries at the very edge of the finality window without reading past + /// the end of the slice — particularly important when null rounds (epochs + /// with zero blocks) are present, since they consume slots in the vector + /// without advancing the meaningful epoch count. const FINALITY_CHAIN_EXTRA_EPOCHS: usize = 5; let finality = ctx.chain_config().policy.chain_finality; From 0b695061c0e12735f3ebe6314208b6d511013702 Mon Sep 17 00:00:00 2001 From: hanabi1224 Date: Wed, 8 Apr 2026 08:53:12 +0800 Subject: [PATCH 2/3] apply coderabbitai suggestion --- src/rpc/methods/chain.rs | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/src/rpc/methods/chain.rs b/src/rpc/methods/chain.rs index 4adea1cc24b..9da13aeca78 100644 --- a/src/rpc/methods/chain.rs +++ b/src/rpc/methods/chain.rs @@ -1199,13 +1199,18 @@ impl ChainGetTipSetFinalityStatus { /// Number of extra epochs to fetch beyond [`chain_finality`] when /// building the chain sample for [`find_threshold_depth`]. /// - /// [`find_threshold_depth`] probes epoch depths up to `chain_finality` - /// using a bisect search over the sampled chain slice. The extra epochs - /// provide a small tail buffer so that the bisect can safely evaluate - /// entries at the very edge of the finality window without reading past - /// the end of the slice — particularly important when null rounds (epochs - /// with zero blocks) are present, since they consume slots in the vector - /// without advancing the meaningful epoch count. + /// The chain sample is sized to `chain_finality + FINALITY_CHAIN_EXTRA_EPOCHS` + /// entries. Inside [`find_threshold_depth`], the bisect search probes depths in + /// `[BISECT_LOW, BISECT_HIGH]` (currently [3, 450]). At each probe point, + /// [`calc_validator_prob`] requires a lookback window of up to `chain_finality` + /// epochs of historical data — so the sample must be at least `chain_finality` + /// entries long. This matches the Lotus reference implementation, where + /// `chain/ecfinality/cache.go` documents this window size as + /// "finality + 5 (the lookback the calculator needs)". + /// + /// The extra 5 epochs act as a tail buffer to prevent out-of-bounds access, + /// particularly when null rounds (epochs with zero blocks) are present, since + /// they consume array slots without advancing the meaningful epoch count. const FINALITY_CHAIN_EXTRA_EPOCHS: usize = 5; let finality = ctx.chain_config().policy.chain_finality; From a99dfa1150be11dd11115a6154eee51fc114d9ff Mon Sep 17 00:00:00 2001 From: hanabi1224 Date: Wed, 8 Apr 2026 17:14:32 +0800 Subject: [PATCH 3/3] Apply suggestion from @LesnyRumcajs Co-authored-by: Hubert --- src/rpc/methods/chain.rs | 9 --------- 1 file changed, 9 deletions(-) diff --git a/src/rpc/methods/chain.rs b/src/rpc/methods/chain.rs index 9da13aeca78..6f64ad8a34b 100644 --- a/src/rpc/methods/chain.rs +++ b/src/rpc/methods/chain.rs @@ -1199,15 +1199,6 @@ impl ChainGetTipSetFinalityStatus { /// Number of extra epochs to fetch beyond [`chain_finality`] when /// building the chain sample for [`find_threshold_depth`]. /// - /// The chain sample is sized to `chain_finality + FINALITY_CHAIN_EXTRA_EPOCHS` - /// entries. Inside [`find_threshold_depth`], the bisect search probes depths in - /// `[BISECT_LOW, BISECT_HIGH]` (currently [3, 450]). At each probe point, - /// [`calc_validator_prob`] requires a lookback window of up to `chain_finality` - /// epochs of historical data — so the sample must be at least `chain_finality` - /// entries long. This matches the Lotus reference implementation, where - /// `chain/ecfinality/cache.go` documents this window size as - /// "finality + 5 (the lookback the calculator needs)". - /// /// The extra 5 epochs act as a tail buffer to prevent out-of-bounds access, /// particularly when null rounds (epochs with zero blocks) are present, since /// they consume array slots without advancing the meaningful epoch count.