Trait IndexVariant

pub trait IndexVariant<Proprietor>: CommitVariant<Proprietor> + CommitIndex<Proprietor> {
    // Required methods
    fn prepare_index_of_variants(
        who: &Proprietor,
        reason: &Self::Reason,
        entries: Vec<(Self::Digest, Self::Shares, Self::Position)>,
    ) -> Result<Self::Index, DispatchError>;
    fn get_entry_variant(
        reason: &Self::Reason,
        index_of: &Self::Digest,
        entry_of: &Self::Digest,
    ) -> Result<Self::Position, DispatchError>;
    fn set_entry_of_variant(
        who: &Proprietor,
        reason: &Self::Reason,
        index_of: &Self::Digest,
        entry_of: &Self::Digest,
        variant: Self::Position,
        shares: Option<Self::Shares>,
    ) -> Result<Self::Digest, DispatchError>;
}

A trait for managing and querying variants of index entries and its commitments.

Extends CommitVariant and CommitIndex, allowing indexed commitments to carry additional positional/variant metadata.

This trait enables tracking, setting, and preparing variant entries in an index context.

Generics:

• Proprietor - the entity that owns the asset and can make commitments.

Required Methods

fn prepare_index_of_variants( who: &Proprietor, reason: &Self::Reason, entries: Vec<(Self::Digest, Self::Shares, Self::Position)>, ) -> Result<Self::Index, DispatchError>

Prepares an index from entry data with explicit variant classification.

Constructs a variant-aware index structure from a list of (Digest, Shares, Position) tuples, where each tuple represents:

• Digest: The unique identifier of an entry within the index
• Shares: The proportional weight or ownership of that entry
• Position: The variant classification for that entry

This extends CommitIndex::prepare_index by adding variant specification for each entry. When both traits are implemented:

• CommitIndex::prepare_index may assign a default variant to all entries
• This method allows explicit variant specification per entry

Returns

• Ok(Index) containing the prepared variant-aware index structure
• Err(DispatchError) if preparation fails

fn get_entry_variant( reason: &Self::Reason, index_of: &Self::Digest, entry_of: &Self::Digest, ) -> Result<Self::Position, DispatchError>

Retrieves the variant associated with a specific entry within an index.

Returns the position classification for the given entry digest under the specified reason and index digest. This enables querying the directional or positional semantics of individual entries within a mixed-variant index.

Returns

• Ok(Position) containing the entry’s variant
• Err(DispatchError) if the index or entry does not exist

fn set_entry_of_variant( who: &Proprietor, reason: &Self::Reason, index_of: &Self::Digest, entry_of: &Self::Digest, variant: Self::Position, shares: Option<Self::Shares>, ) -> Result<Self::Digest, DispatchError>

Associates or updates a variant for a specific entry within an index.

Records a position (variant) for an entry digest within the context of a given index digest and reason. If shares are provided, they are updated alongside the variant.

Since indexes are immutable once created, this method internally generates a new digest for the modified index and returns the new index digest.

For updating multiple entry variants simultaneously, use IndexVariant::prepare_index_of_variants to construct a completely new index structure.

This behavior partly mirrors CommitIndex::set_index, and can be considered a higher-level wrapper around index reconstruction and binding.

As such, it is assumed that any side-effects or lifecycle handling are delegated through the underlying CommitIndex::set_index call, and therefore this method does not introduce a separate hook.

Returns

• Ok(Digest) containing the new index digest after variant update
• Err(DispatchError) if the index or entry does not exist, or update fails

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors