Struct CandidateDescriptorV2 

pub struct CandidateDescriptorV2<H = H256> { /* private fields */ }

A unique descriptor of the candidate receipt.

Implementations

impl<H> CandidateDescriptorV2<H>

where H: AsRef<[u8]>,

pub fn version(&self) -> CandidateDescriptorVersion

Returns the candidate descriptor version.

NOTE: The candidate descriptor versioning is subtle for as long as we need to support the unversioned V1. The issue is that by default we assume a V1 descriptor - as soon as any of the reserved bytes are non-zero. Now if we introduce any new fields, then there will exist candidates where any old node will think that descriptors of that new version are actually V1 (non-zero contents), while upgraded nodes will either see v3 or an unknown version.

We solve this by completely gating v3 behavior behind the v3 node feature, which must only be enabled once enough validators have upgraded to support it. Any backers still running on the old version are protected by the relay chain runtime, which will drop any illegally (under v3) backed candidates.

For this to work we now also require a present UMP signal for any version higher or equal than V3. This is enforced by the runtime.

Via this, if an old node was presented a v3 candidate, which it would consider a V1, it would either detect itself that it is invalid, because of present UMP signals - which is illegal on v1 or the candidate would get rejected by the runtime, because for v3 UMP signals are mandatory. In both cases the backer wont’t be slashed.

There are also candidates that would be treated as v1 by old nodes, but would result in an Unknown version on updated clients. For this scenario, also the runtime provides protection:

1. Before the feature is enabled, all nodes will behave as if no v3 would exist - all nodes would detect a V1.
2. After the upgrade, the runtime will also (in addition to upgraded nodes) detect an unknown version and no v1 and thus would drop it.

TL;DR: Yes old nodes will errorneously treat v3 candidates as v1, but we ensure via the relay chain runtime that this stays harmless for backers. V2 approval voters would get disabled, which means a super majority must have updated before enabling the v3 node feature.

Crucially for this to work: Behavior must not change before the node feature is present and enabled, together with new UMP signal requirements, the runtime can provide the necessary protection.

To ease future upgrades, we reduced the v1 check once v3 is enabled, so some actually unused bytes are available (don’t affect the v1 version check).

Always uses the relaxed (v3-capable) detection logic. This means version detection is self-contained and does not require knowing whether the V3 node feature is enabled.

The safety invariant is maintained by the runtime and backing subsystem: they reject candidates where version() and version_old_rules() disagree when V3 is not yet enabled, and reject V3 candidates outright when V3 is not enabled.

During the V3 transition, approval checkers, dispute participants, and on-chain vote scrapers must use Self::version_for_candidate_validation (and the corresponding scheduling_parent_for_candidate_validation / scheduling_session_for_candidate_validation) instead of version() directly. This ensures they match old backer semantics before the V3 node feature is confirmed enabled. See those methods for the full safety argument.

pub fn version_old_rules(&self) -> CandidateDescriptorVersion

Detect the version using the pre-V3 (stricter) rules.

Under these rules, all reserved fields, scheduling_parent, and scheduling_session_offset must be zero for a descriptor to be considered V2. Any non-zero value in those fields causes V1 detection. V3 descriptors appear as V1 under these rules.

Used together with version() in consistency checks: if the two methods disagree, the candidate is ambiguous and must be rejected when V3 is not enabled.

pub fn check_version_consistency(&self) -> bool

Returns true if the old-style and new-style version detection agree.

When V3 is not enabled, both runtime and backing must reject candidates where this returns false, preventing ambiguous candidates from landing on-chain. Once V3 is enabled, disagreement is expected for V3 candidates (old rules see V1, new rules see V3) and this check is skipped.

pub fn check_version_acceptance( &self, v3_enabled: bool, ) -> Result<(), CandidateDescriptorVersionCheckError>

Validates that the descriptor version is acceptable given whether V3 is enabled.

Used by both the runtime (check_descriptor_version_and_signals) and the backing subsystem. Serves two distinct purposes:

1. V2 ambiguity protection (long-lived): Old-style and new-style version detection must agree, unless the candidate is V3 and V3 is enabled (the expected disagreement: old rules see V1, new rules see V3). This prevents a crafted candidate from being treated as V2 (no mandatory UMP signals) by new nodes but as V1 by old nodes. Needed as long as V1 exists (maximum safety) or until we could have valiators not yet using the new rules.

2. V3 gating (transitional): V3 candidates are rejected when V3 is not enabled.

Note: Consistent Unknown versions are not our concern here — they are caught upstream by the runtime (check_descriptor_version_and_signals) and the collator protocol (descriptor_version_sanity_check).

impl<H> CandidateDescriptorV2<H>

where H: Copy + AsRef<[u8]>,

pub fn erasure_root(&self) -> H256

Returns the value of $field field.

pub fn para_head(&self) -> H256

Returns the value of $field field.

pub fn relay_parent(&self) -> H

Returns the value of $field field.

pub fn para_id(&self) -> Id

Returns the value of $field field.

pub fn persisted_validation_data_hash(&self) -> H256

Returns the value of $field field.

pub fn pov_hash(&self) -> H256

Returns the value of $field field.

pub fn validation_code_hash(&self) -> ValidationCodeHash

Returns the value of $field field.

pub fn collator(&self) -> Option<Public>

Returns the collator id if this is a v1 CandidateDescriptor

pub fn signature(&self) -> Option<Signature>

Returns the collator signature of V1 candidate descriptors, None otherwise.

pub fn core_index(&self) -> Option<CoreIndex>

Returns the core_index of V2 and V3 candidate descriptors, None for V1.

pub fn session_index(&self) -> Option<u32>

Returns the session_index of V2 and V3 candidate descriptors, None for V1.

pub fn scheduling_parent(&self) -> H

Return the scheduling parent of the descriptor.

On v1 and v2 this function will return the relay parent as under these versions the relay parent is also the scheduling parent.

pub fn scheduling_session(&self) -> Option<u32>

Return the scheduling session index of the descriptor.

On v1: Return None. On v2: Return the session index as it equals the scheduling session on v2. On v3: Return the provided scheduling session index.

pub fn version_for_candidate_validation( &self, v3_ever_seen: bool, ) -> CandidateDescriptorVersion

Version for use in candidate validation during the V3 transition period.

Before the CandidateReceiptV3 node feature is observed, uses Self::version_old_rules to match old backer behavior. After the feature is seen, trusts Self::version.

This prevents slashing honest old backers when a malicious collator crafts a pseudo-V3 descriptor that old nodes interpret as V1 but new nodes would interpret as V3 (different PVF inputs → dispute → 100% slash).

Safety argument: The node feature can only be enabled well after the runtime upgrade that adds check_version_acceptance() protection at inclusion time. Once the feature is seen, the runtime has long been upgraded and already rejecting pseudo-V3 candidates (candidates that are valid v1 under the old rules, but are v3 without UMP signals under the new rules), so no ambiguous candidates can exist on-chain.

Only needed during the V3 transition. Once V3 is universally deployed, callers can switch to Self::version directly.

pub fn scheduling_parent_for_candidate_validation( &self, v3_ever_seen: bool, ) -> H

where H: Copy,

Scheduling parent for use in candidate validation.

See Self::version_for_candidate_validation for the safety argument.

pub fn scheduling_session_for_candidate_validation( &self, v3_ever_seen: bool, ) -> Option<u32>

Scheduling session for candidate validation.

See Self::version_for_candidate_validation for the safety argument.

pub fn session_index_for_candidate_validation( &self, v3_ever_seen: bool, ) -> Option<u32>

Session index (relay parent session) for candidate validation.

See Self::version_for_candidate_validation for the safety argument.

impl<H> CandidateDescriptorV2<H>

where H: Copy + AsRef<[u8]>,

pub fn new( para_id: Id, relay_parent: H, core_index: CoreIndex, session_index: u32, persisted_validation_data_hash: H256, pov_hash: H256, erasure_root: H256, para_head: H256, validation_code_hash: ValidationCodeHash, ) -> CandidateDescriptorV2<H>

where H: Default,

Constructor for V2 candidate descriptor (scheduling_parent = zero).

pub fn new_v3( para_id: Id, relay_parent: H, core_index: CoreIndex, session_index: u32, scheduling_session_index: u32, persisted_validation_data_hash: H256, pov_hash: H256, erasure_root: H256, para_head: H256, validation_code_hash: ValidationCodeHash, scheduling_parent: H, ) -> CandidateDescriptorV2<H>

Constructor for V3 candidate descriptor with explicit scheduling_parent.

V3 descriptors are identified by version == 1 and have a non-zero scheduling_parent field, which indicates the relay chain block that was used for scheduling (may differ from relay_parent). V3 descriptors require UMP signals to be present.

pub fn new_v1( para_id: Id, relay_parent: H, persisted_validation_data_hash: H256, pov_hash: H256, erasure_root: H256, para_head: H256, validation_code_hash: ValidationCodeHash, ) -> CandidateDescriptorV2<H>

where H: Default,

Constructor for a V1-like candidate descriptor with non-zero collator fields so that version() returns CandidateDescriptorVersion::V1.

Trait Implementations

impl<H> Clone for CandidateDescriptorV2<H>

where H: Clone,

fn clone(&self) -> CandidateDescriptorV2<H>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<H> Debug for CandidateDescriptorV2<H>

where H: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<H> Decode for CandidateDescriptorV2<H>

where H: Decode,

fn decode<__CodecInputEdqy>( __codec_input_edqy: &mut __CodecInputEdqy, ) -> Result<CandidateDescriptorV2<H>, Error>

where __CodecInputEdqy: Input,

Attempt to deserialise the value from input.

fn decode_into<I>( input: &mut I, dst: &mut MaybeUninit<Self>, ) -> Result<DecodeFinished, Error>

where I: Input,

Attempt to deserialize the value from input into a pre-allocated piece of memory.

fn skip<I>(input: &mut I) -> Result<(), Error>

where I: Input,

Attempt to skip the encoded value from input.

fn encoded_fixed_size() -> Option<usize>

Returns the fixed encoded size of the type.

impl<H> Encode for CandidateDescriptorV2<H>

where H: Encode,

fn size_hint(&self) -> usize

If possible give a hint of expected size of the encoding.

fn encode_to<__CodecOutputEdqy>( &self, __codec_dest_edqy: &mut __CodecOutputEdqy, )

where __CodecOutputEdqy: Output + ?Sized,

Convert self to a slice and append it to the destination.

fn encode(&self) -> Vec<u8>

Convert self to an owned vector.

fn using_encoded<R, F>(&self, f: F) -> R

where F: FnOnce(&[u8]) -> R,

Convert self to a slice and then invoke the given closure with it.

fn encoded_size(&self) -> usize

Calculates the encoded size.

impl<H> MutateDescriptorV2<H> for CandidateDescriptorV2<H>

Available on crate feature test only.

fn set_para_id(&mut self, para_id: Id)

Set the ParaId of the descriptor.

fn set_relay_parent(&mut self, relay_parent: H)

Set the relay parent of the descriptor.

fn set_pov_hash(&mut self, pov_hash: H256)

Set the PoV hash of the descriptor.

fn set_version(&mut self, version: u8)

Set the raw version field of the descriptor.

fn set_core_index(&mut self, core_index: CoreIndex)

Set the core index of the descriptor.

fn set_session_index(&mut self, session_index: u32)

Set the session index of the descriptor.

fn set_persisted_validation_data_hash( &mut self, persisted_validation_data_hash: H256, )

Set the PVD of the descriptor.

fn set_validation_code_hash(&mut self, validation_code_hash: ValidationCodeHash)

Set the validation code hash of the descriptor.

fn set_erasure_root(&mut self, erasure_root: H256)

Set the erasure root of the descriptor.

fn set_para_head(&mut self, para_head: H256)

Set the para head of the descriptor.

fn set_reserved2(&mut self, reserved2: [u8; 32])

Set the reserved2 field of the descriptor.

fn set_scheduling_parent(&mut self, scheduling_parent: H)

Set the scheduling parent of the descriptor.

fn set_scheduling_session_offset(&mut self, offset: u8)

Set the scheduling session offset of the descriptor.

impl<H> PartialEq for CandidateDescriptorV2<H>

where H: PartialEq,

fn eq(&self, other: &CandidateDescriptorV2<H>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<H> TypeInfo for CandidateDescriptorV2<H>

where H: TypeInfo + 'static,

type Identity = CandidateDescriptorV2<H>

The type identifying for which type info is provided.

fn type_info() -> Type

Returns the static type identifier for Self.

impl<H> DecodeWithMemTracking for CandidateDescriptorV2<H>

where H: DecodeWithMemTracking,

impl<H> EncodeLike for CandidateDescriptorV2<H>

where H: Encode,

impl<H> Eq for CandidateDescriptorV2<H>

where H: Eq,

impl<H> StructuralPartialEq for CandidateDescriptorV2<H>