Skip to content

Add configurable historical balance health check for finalized block#420

Open
Krish-vemula wants to merge 3 commits into
developfrom
cre/PLEX-2476-v2
Open

Add configurable historical balance health check for finalized block#420
Krish-vemula wants to merge 3 commits into
developfrom
cre/PLEX-2476-v2

Conversation

@Krish-vemula
Copy link
Copy Markdown
Contributor

@Krish-vemula Krish-vemula commented Apr 13, 2026

Re-implement the finalized state availability check (originally PR #352) on top of the updated chainlink-framework that uses optional interfaces instead of modifying core NodeConfig/RPCClient interfaces. This avoids forcing unrelated chains (e.g. Solana) to implement boilerplate methods.

Summary

Implements the EVM finalized-state availability check used by multinode.

The check verifies that an RPC can serve historical state at the latest finalized block by calling BalanceAt for a configurable probe address. The check is disabled by default and only runs when FinalizedStateCheckFailureThreshold > 0.

Changes

  • Added EVM config:
    • HistoricalBalanceCheckAddress
    • FinalizedStateCheckFailureThreshold
    • Errors.FinalizedStateUnavailable
  • Default probe address is:
    • 0x0000000000000000000000000000000000000000
  • Implements CheckFinalizedStateAvailability on the EVM RPC client.
  • Finalized block selection:
    • uses finalized tag when FinalityTagEnabled = true
    • uses latest - FinalityDepth when FinalityTagEnabled = false
  • Calls BalanceAt at the selected finalized block.
  • Maps configured historical-state errors to multinode.ErrFinalizedStateUnavailable.
  • Adds config docs/defaults/test fixtures.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Apr 13, 2026

⚠️ API Diff Results - github.com/smartcontractkit/chainlink-evm

⚠️ Breaking Changes (3)

pkg/config.ClientErrors (1)
  • FinalizedStateUnavailable — ➕ Added
pkg/config.NodePool (2)
  • FinalizedStateCheckFailureThreshold — ➕ Added

  • HistoricalBalanceCheckAddress — ➕ Added

✅ Compatible Changes (6)

pkg/client.(*RPCClient) (1)
  • CheckFinalizedStateAvailability — ➕ Added
pkg/config.(*NodePoolConfig) (2)
  • FinalizedStateCheckFailureThreshold — ➕ Added

  • HistoricalBalanceCheckAddress — ➕ Added

pkg/config/toml.ClientErrors (1)
  • FinalizedStateUnavailable — ➕ Added
pkg/config/toml.NodePool (2)
  • FinalizedStateCheckFailureThreshold — ➕ Added

  • HistoricalBalanceCheckAddress — ➕ Added


📄 View full apidiff report

@Krish-vemula Krish-vemula marked this pull request as ready for review April 30, 2026 23:34
@Krish-vemula Krish-vemula requested review from a team as code owners April 30, 2026 23:34
@Krish-vemula Krish-vemula requested a review from dhaidashenko May 12, 2026 17:10
Comment thread pkg/config/toml/config.go
return
}
if p.FinalizedBlockPollInterval.Duration() <= 0 {
} else if p.FinalizedBlockPollInterval.Duration() <= 0 {
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I understand why you've removed return. But not sure why you've added else if instead of if

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I used else if so we never call Duration() when the interval is nil. A second standalone if would need an explicit p.FinalizedBlockPollInterval != nil guard; else if encodes that same dependency without duplicating the check.

Comment thread pkg/config/toml/config.go Outdated
}
}
if p.FinalizedStateCheckFailureThreshold != nil && *p.FinalizedStateCheckFailureThreshold > 0 {
if p.Errors.FinalizedStateUnavailable == nil || *p.Errors.FinalizedStateUnavailable == "" {
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Follow the example of TooManyResults. Right now, you are not setting the default for FinalizedStateUnavailable

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added fix for this, can you verify if its good

@Krish-vemula Krish-vemula requested a review from dhaidashenko May 15, 2026 17:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants