XDC: Add masternode availability guards and graceful seal validation fallbacks

[Copilot]

Hardens the XDC consensus layer against edge cases where masternodes are unavailable due to penalties, missing epoch info, or null state — previously causing unguarded exceptions or null dereferences.

Changes

• SnapshotManager: Extracted EnsureMasternodesAvailable helper; CalculateNextEpochMasternodes now throws InvalidOperationException when penalties eliminate all candidates
• XdcHotStuff.GetLeaderAddress: Guards against null EpochSwitchInfo returned by GetEpochSwitchInfo (previously a silent null deref); throws descriptive InvalidOperationException
• XdcSealValidator.ValidateParams: Non-epoch-switch path now returns false + error string instead of throwing when epoch switch info is null or masternodes list is empty — consistent with the rest of the validation contract
• SnapshotManagerTests: Added CalculateNextEpochMasternodes_AllPenalized_Throws
• XdcSealValidatorTests: Added ValidateParams_MissingEpochInfo_ReturnsFalse and ValidateParams_EmptyMasternodes_ReturnsFalse

Types of changes

What types of changes does your code introduce?

• Bugfix (a non-breaking change that fixes an issue)
• New feature (a non-breaking change that adds functionality)
• Breaking change (a change that causes existing functionality not to work as expected)
• Optimization
• Refactoring
• Documentation update
• Build-related changes
• Other: Description

Testing

Requires testing

• Yes
• No

If yes, did you write tests?

• Yes
• No

Documentation

Requires documentation update

• Yes
• No

Requires explanation in Release Notes

• Yes
• No

Original prompt

Develop AI agents to test the recent changes in the Nethermind codebase. Specifically, the agents should verify new features and behaviors introduced in the referenced changes.

Objectives

1. Validate Masternode Management
   Test scenarios related to penalized or missing masternodes, ensuring the handling logic introduced in EnsureMasternodesAvailable works as expected.

2. Epoch Switch Validation
   Simulate cases tested in ValidateParams_MissingEpochInfo_ReturnsFalse and ValidateParams_EmptyMasternodes_ReturnsFalse. Ensure proper error reporting when necessary data fields are missing.

3. Dynamic Leader Selection
   Test the GetLeaderAddress method under conditions like missing masternode data or unavailable leaders.

4. Snapshot Validation
   Automate testing for snapshots, including storing, retrieving, and applying penalties as expected.

5. Error Robustness
   Verify the handling of edge cases for newly implemented exceptions, ensuring all errors are universally thrown under appropriate conditions.

Approach:

The AI agents should be designed to:

1. Utilize mocking to simulate dependent contract interactions (e.g., ISpecProvider, IEpochSwitchManager).
2. Leverage a parameterized test suite to handle diverse test cases effectively.
3. Log results for review to catch regressions or undefined behaviors.

Coding Libraries/Stack

• Integrate with the existing .NET framework (e.g., NUnit for extended tests + Mocking libraries like NSubstitute).
• Follow patterns in the existing codebase for consistency.

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: Create ai agents to test smart contracts

Assistant: The referenced pull request contains the following significant changes spread across multiple files:

1. src/Nethermind/Nethermind.Xdc.Test/SnapshotManagerTests.cs

   • Additions: 29
   • Introduces a new test CalculateNextEpochMasternodes_AllPenalized_Throws to verify that an exception is thrown when all masternodes are penalized.
   • Specifics include mocking IXdcReleaseSpec, IPenaltyHandler, saving a snapshot, and ensuring behavior under penalization.

2. src/Nethermind/Nethermind.Xdc.Test/XdcSealValidatorTests.cs

   • Additions: 64
   • Adds new tests, such as ValidateParams_MissingEpochInfo_ReturnsFalse and ValidateParams_EmptyMasternodes_ReturnsFalse.
   • Validates behavior when epoch switch information or masternode data is absent.

3. src/Nethermind/Nethermind.Xdc/SnapshotManager.cs

   • Additions: 11
   • Introduces EnsureMasternodesAvailable to throw an InvalidOperationException if no masternodes are available during penalties.

4. src/Nethermind/Nethermind.Xdc/XdcHotStuff.cs

   • Changes: 7 (Additions: 6, Deletions: 1)
   • Updates the GetLeaderAddress method to handle cases where masternodes are null or unavailable.

5. src/Nethermind/Nethermind.Xdc/XdcSealValidator.cs

   • Changes: 13 (Additions: 11, Deletions: 2)
   • Enhances validation to handle missing epoch switch information or absent masternodes gracefully.

Would you like guidance on implementing related AI agents to automate testing for these scenarios?

User: Yes

Assistant: To create AI agents for testing these smart contract-related functionalities, we can focus on automating the verification of the changes made in the pull request. The AI agents should target the following objectives:

Objectives for AI Agents

1. Validate Masternode Management:

   • Test scenarios for handling penalized masternodes.
   • Ensure masternodes are properly selected or exceptions are thrown as expected.

2. Test Epoch Switch Behavior:

   • Verify scenarios with missing epoch information.
   • Confirm that appropriate errors are generated when required data is unavailable.

3. Dynamic Leader Selection Testing:

   • Simulate leader election in various cases.
   • Test the fallback mechanism for absent masternodes.

4. Snapshot Validations:

   • Test edge cases to ensure snapshots handle penalties and epoch transitions correctly.

5. Error Handling Robustness:

   • Ensure all new InvalidOperationException cases are adequately tested.

---

Proposed Solution: AI-Powered Test Agents

These agents will use machine learning and predefined rules to verify the behaviors implemented in the updated code. Below is a step-by-step roadmap:

1. Agent for Testing Masternode Selection

• Automate tests for the EnsureMasternodesAvailable method.
• Simulate scenarios with:
  • Zero available masternodes.
  • All masternodes penalized.
  • Valid and invalid block numbers.

2. Agent for Epoch Switch Validation

• Verify behavior of ValidateParams_MissingEpochInfo_ReturnsFalse and ValidateParams_EmptyMasternodes_ReturnsFalse tests.
• Inject test data dynamically using mocking tools to simulate real-world scenarios.
• Ensure epoch switch information is ...

This pull request was created from Copilot chat.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

---

Summary by cubic

Adds automated test agents and validation guards for recent XDC consensus changes. Improves error handling when masternodes or epoch info are missing and hardens leader selection and epoch updates.

• New Features
  • Added EnsureMasternodesAvailable in SnapshotManager and call it in CalculateNextEpochMasternodes; throws InvalidOperationException when all candidates are penalized. Test: CalculateNextEpochMasternodes_AllPenalized_Throws.
  • Updated XdcSealValidator.ValidateParams to return false with clear errors when epoch switch info is missing or masternodes are empty. Tests added for both scenarios.
  • Added guard in XdcHotStuff.GetLeaderAddress to throw when epoch switch info is null or masternodes are missing/empty.
  • Expanded snapshot/epoch tests using NUnit and NSubstitute for ISpecProvider and IEpochSwitchManager.

^{Written for commit 1c1f022. Summary will update on new commits.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
express-4bpo	Error		Mar 29, 2026 7:34am

[cubic-dev-ai]

No issues found across 5 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Requires human review: This PR modifies error handling and validation logic within the XDC consensus engine (SnapshotManager and HotStuff), which are critical paths. Manual review is required for consensus changes.}