V3 Candidate Descriptor Support with Explicit Scheduling Parent + node feature

[eskimor]

Overview

This PR introduces V3 candidate descriptors with an explicit scheduling_parent field, separating the scheduling context (which determines validator group assignment) from the execution context (which determines parachain state). This is a critical foundation for enabling lookahead scheduling and improving parachain block production flexibility in async backing.

Key Innovation: V3 candidates can be scheduled based on a different relay chain block than the one they execute against, enabling validators to assign backing responsibilities ahead of time while maintaining correct execution semantics.

Problem

In V1 and V2 candidate descriptors, the relay_parent field serves a dual purpose:

1. Execution context: Determines which relay chain state the parachain block executes against
2. Scheduling context: Determines which validator group is assigned to back the candidate

This tight coupling limits flexibility:

• Candidates must be scheduled on the exact block they execute against
• No lookahead scheduling possible
• Reduces predictability for parachains about when they can produce blocks

Solution

V3 candidates introduce an explicit scheduling_parent field that decouples these concerns:

• relay_parent: Determines execution context (parachain state root, claim queue state for core assignment)
• scheduling_parent: Determines validator group assignment (which validators back this candidate)

For backward compatibility:

• V1/V2 candidates: scheduling_parent == relay_parent (implicit, behavior unchanged)
• V3 candidates: scheduling_parent can differ from relay_parent (explicit field in descriptor)

This separation enables lookahead scheduling where parachains can be assigned to validator groups on future relay chain blocks while still executing against older state.

Key Changes

Primitives (polkadot/primitives/src/v9/mod.rs)

• CandidateDescriptorVersion::V3: New enum variant for version detection
• CandidateDescriptorV2::new_v3(): Constructor accepting explicit scheduling_parent parameter
• scheduling_parent(v3_enabled: bool) -> Hash: Accessor returning scheduling_parent for V3, relay_parent for V1/V2
• scheduling_session(v3_enabled: bool) -> Option<SessionIndex>: Accessor for scheduling session (offset-based for V3)
• Version detection: Feature-gated logic (CandidateReceiptV3 node feature) to distinguish V1 from V3 using reserved fields

PVF Extension (polkadot/parachain/src/primitives.rs)

• ValidationParamsExtension::V3: New extension type containing both relay_parent and scheduling_parent hashes
• TrailingOption<T>: Backward-compatible wrapper that decodes T from trailing bytes if present, or None if at EOF
  • V3 candidates: PVF receives extension with both hashes
  • V1/V2 candidates: PVF receives no extension bytes (TrailingOption decodes as None)
  • Old PVFs: Gracefully ignore trailing extension bytes (don't fail to decode)

Subsystem Messages (polkadot/node/subsystem-types/src/messages.rs)

• BackableCandidateRef: New struct containing candidate_hash and scheduling_parent (replaces bare CandidateHash)
• CandidateBackingMessage::Second: Now includes explicit scheduling_parent: Hash parameter
• CandidateBackingMessage::Statement: Now includes explicit scheduling_parent: Hash parameter
• CandidateBackingMessage::GetBackableCandidates: Uses Vec<BackableCandidateRef> instead of Vec<CandidateHash>
• CanSecondRequest: Includes candidate_scheduling_parent field for validator group lookup

Core Subsystems

Candidate Backing (polkadot/node/core/backing/)

• Use scheduling_parent (not relay_parent) for validator group lookups
• Track per-scheduling-parent state instead of per-relay-parent
• Validate candidates against scheduling_parent context (session, group assignment)

Candidate Validation (polkadot/node/core/candidate-validation/)

• For V3: Append ValidationParamsExtension::V3 bytes to PVF validation input
• For V1/V2: No extension bytes appended (backward compatible)
• PVF workers decode extension using TrailingOption pattern

Prospective Parachains (polkadot/node/core/prospective-parachains/)

• Track candidates with their scheduling_parent hash
• Validate scheduling_parent is in active leaves before accepting candidates
• Support fragment chains with mixed V1/V2/V3 candidates

Network Protocol

Collator Protocol (polkadot/node/network/collator-protocol/)

• Track collations per-scheduling-parent instead of per-relay-parent
• PendingCollation and FetchedCollation now include scheduling_parent field
• Validate advertised scheduling_parent matches fetched descriptor's actual scheduling_parent(v3_enabled)
• Ensure scheduling_parent is an active leaf before accepting collations

Statement Distribution (polkadot/node/network/statement-distribution/src/v2/)

• Rename PerRelayParentState → PerSchedulingParentState
• Rename per_relay_parent map → per_scheduling_parent
• Use scheduling_parent as key for state lookups (validator groups, candidate tracking)
• Add clarifying comments in tests explaining relay_parent serves dual role for V1/V2

Test Infrastructure

• Remove 114 lines of obsolete CandidateReceiptV2 node feature checks (V2 now enabled everywhere)
• Add V3-specific tests:
  • v3_descriptors_are_accepted_when_enabled: V3 with UMP signals accepted
  • v3_descriptors_without_ump_signals_are_rejected: V3 without UMP signals rejected
  • v3_descriptors_rejected_as_v1_when_disabled: V3 rejected as V1 when feature disabled
• Update all test call sites to use new descriptor version enum

Backward Compatibility

Multiple layers of protection ensure safe gradual rollout:

1. Node Feature Gating: V3 only recognized when CandidateReceiptV3 node feature enabled (requires 2/3+ validator upgrade)

2. Mandatory UMP Signals: V3 candidates MUST include UMP signals (SelectCore at minimum)

   • Prevents old nodes from mistakenly backing V3 candidates (they'd see them as invalid V1)
   • No slashing risk for validators during transition period

3. TrailingOption Pattern: PVF extension gracefully handled

   • Old PVFs: Don't decode extension, behave as before
   • New PVFs: Decode extension if present, use both hashes

4. Version Detection: Backwards compatible logic distinguishes V1 from V3

   • V3 uses version == 1 (vs V2's version == 0)
   • Reserved fields checked to prevent misidentification
   • Old nodes see V3 as invalid V1 (missing UMP signals)

5. Runtime Protection: Runtime drops candidates violating version-specific rules

   • V3 without UMP signals: Rejected
   • V3 with invalid scheduling_parent: Rejected

Review Focus

High Priority - Correctness

1. Version detection logic (polkadot/primitives/src/v9/mod.rs:CandidateDescriptorV2::version())

   • Ensures V1 and V3 are correctly distinguished
   • Verify old nodes cannot misinterpret V3 as V1

2. TrailingOption safety (polkadot/parachain/src/primitives.rs, polkadot/node/core/pvf/execute-worker/)

   • Confirm it only works as final field (documented with safety warnings)
   • Verify old PVFs don't fail when extension bytes absent

3. Scheduling_parent validation (polkadot/node/network/collator-protocol/, polkadot/node/core/backing/)

   • Must be active leaf before accepting candidates
   • Used correctly for validator group lookups

4. UMP signal enforcement (polkadot/runtime/parachains/src/paras_inherent/mod.rs)

   • Runtime rejects V3 without mandatory UMP signals
   • Prevents security issues with old nodes

Medium Priority - Architecture

5. Message flow (polkadot/node/subsystem-types/src/messages.rs)

   • scheduling_parent correctly threaded through subsystem messages
   • BackableCandidateRef used consistently

6. State tracking (polkadot/node/core/backing/, polkadot/node/network/statement-distribution/)

   • Per-scheduling-parent state management (not per-relay-parent)
   • Correct hashmap key usage

7. PVF extension encoding/decoding (polkadot/node/core/candidate-validation/)

   • Extension appended correctly for V3
   • No extension for V1/V2 (backward compatible)

Lower Priority - Cleanup

8. Obsolete V2 feature checks removed (114 lines in paras_inherent/tests.rs)
9. Naming consistency (per_relay_parent → per_scheduling_parent)
10. Test infrastructure refactoring (descriptor version enum in builder.rs)

CI Coverage

CI verifies:

• All affected packages compile successfully
• All existing tests pass (runtime, subsystems, network protocols)
• New V3-specific tests validate:
  • V3 descriptors accepted when feature enabled
  • V3 descriptors rejected without mandatory UMP signals
  • V3 descriptors rejected as V1 when feature disabled
  • Scheduling_parent validation in collator-protocol and backing

Critical Invariants

1. No slashing risk: Old validators cannot mistakenly back V3 candidates (UMP signal requirement prevents this)
2. Correct validator grouping: Always determined by scheduling_parent, never relay_parent (for V3)
3. Active leaf requirement: scheduling_parent must be in validator's active leaves
4. Core assignment correctness: UMP SelectCore signal matches claim queue assignment
5. PVF safety: V1/V2 PVFs don't fail when TrailingOption decodes as None

Related

• Base PR: Prospective parachains cleanup #10650 (rk-prospective-parachains-cleanup) - used for separate review

---

Scope: ~4,500 lines added, ~2,350 lines removed across 58 files

[paritytech-workflow-stopper]

All GitHub workflows were cancelled due to failure one of the required jobs.
Failed workflow url: https://github.com/paritytech/polkadot-sdk/actions/runs/21264051381
Failed job name: test-linux-stable

[paritytech-workflow-stopper]

All GitHub workflows were cancelled due to failure one of the required jobs.
Failed workflow url: https://github.com/paritytech/polkadot-sdk/actions/runs/21264051381
Failed job name: test-linux-stable-runtime-benchmarks

[sandreim]

What's up with Bitcoin ? :)

[sandreim]

This should be v1, not really old v1.

[sandreim]

Why do we need this flag ? The primitive is not aware of feature flags, and the versioning information is contained fully in it.

[sandreim]

Before fixing session boundaries session_index should be equal scheduling_session_offset

[sandreim]

Seems we running out of space, one more hash left to add 😢

[sandreim]

also update fn name as it now also checks v3.

[sandreim]

Also check candidate.descriptor().session_index(). For now they should still be the same.

[iulianbarbu]

Just a check in review - local zn-sdk testing is underway.

[iulianbarbu]

feels redundant to have both. Can't we assume v3 enabled if scheduling_parent.is_some()?

[iulianbarbu]

nit: not that useful, can be removed

Suggested change

// Uses default implementation: returns relay_parent()

[iulianbarbu]

We should handle a message for V3 here too. Logs during zn-sdk tests are showing the Major logic bug. Peer somehow has unsupported collation protocol version., which is not shown anymore after this fix.

diff --git a/polkadot/node/network/bridge/src/rx/mod.rs b/polkadot/node/network/bridge/src/rx/mod.rs
index 7a8f2e3133..b00956dfd9 100644
--- a/polkadot/node/network/bridge/src/rx/mod.rs
+++ b/polkadot/node/network/bridge/src/rx/mod.rs
@@ -587,6 +587,15 @@ async fn handle_collation_message<AD>(
                                                metrics,
                                        )
                                } else if expected_versions[PeerSet::Collation] == Some(CollationVersion::V2.into())
+                               {
+                                       handle_peer_messages::<protocol_v2::CollationProtocol, _>(
+                                               peer,
+                                               PeerSet::Collation,
+                                               &mut shared.0.lock().collation_peers,
+                                               vec![notification.into()],
+                                               metrics,
+                                       )
+                               } else if expected_versions[PeerSet::Collation] == Some(CollationVersion::V3.into())
                                {
                                        handle_peer_messages::<protocol_v2::CollationProtocol, _>(
                                                peer,		

[iulianbarbu]

Probably something must be handled here accordingly for V3 CollationVersion. I am seeing such logs in the local testing, while parachain finalization is not happening and collations expire. Will try tomorrow to address it.

2026-01-28 17:44:48.032 DEBUG tokio-runtime-worker parachain::collator-protocol: [Relaychain] Collation was advertised but not requested by any validator. candidate_hash=0x94b8d1bf7709355052dca13d8ca33018d46956ba2133b185e20a72d02de13f06 pov_hash=0x2766fcabaee5da227b317ff0f41222e586bd4191d7e93a3c2d658507ee258870 traceID=197685380191164009165270678908973559832