Trait CommitVariant

pub trait CommitVariant<Proprietor>: Commitment<Proprietor> {
    type Position: RuntimeEnum + Delimited;

    // Required methods
    fn get_commit_variant(
        who: &Proprietor,
        reason: &Self::Reason,
    ) -> Result<Self::Position, DispatchError>;
    fn get_digest_variant_value(
        reason: &Self::Reason,
        digest: &Self::Digest,
        variant: &Self::Position,
    ) -> Result<Self::Asset, DispatchError>;
    fn set_digest_variant_value(
        reason: &Self::Reason,
        digest: &Self::Digest,
        value: Self::Asset,
        variant: &Self::Position,
        qualifier: &Self::Intent,
    ) -> Result<Self::Asset, DispatchError>;
    fn place_commit_of_variant(
        who: &Proprietor,
        reason: &Self::Reason,
        digest: &Self::Digest,
        value: Self::Asset,
        variant: &Self::Position,
        qualifier: &Self::Intent,
    ) -> Result<Self::Asset, DispatchError>;

    // Provided methods
    fn can_set_digest_variant_value(
        reason: &Self::Reason,
        digest: &Self::Digest,
        value: Self::Asset,
        variant: &Self::Position,
        qualifier: &Self::Intent,
    ) -> DispatchResult { ... }
    fn can_place_commit_of_variant(
        who: &Proprietor,
        reason: &Self::Reason,
        digest: &Self::Digest,
        variant: &Self::Position,
        value: Self::Asset,
        qualifier: &Self::Intent,
    ) -> DispatchResult { ... }
    fn digest_mint_limits_of_variant(
        _digest: &Self::Digest,
        _reason: &Self::Reason,
        _variant: &Self::Position,
        _qualifier: &Self::Intent,
    ) -> Result<Self::Limits, DispatchError> { ... }
    fn digest_reap_limits_of_variant(
        _digest: &Self::Digest,
        _reason: &Self::Reason,
        _variant: &Self::Position,
        _qualifier: &Self::Intent,
    ) -> Result<Self::Limits, DispatchError> { ... }
    fn place_commit_limits_of_variant(
        _who: &Proprietor,
        _reason: &Self::Reason,
        _digest: &Self::Digest,
        _variant: &Self::Position,
        _qualifier: &Self::Intent,
    ) -> Result<Self::Limits, DispatchError> { ... }
    fn set_commit_variant(
        who: &Proprietor,
        reason: &Self::Reason,
        variant: &Self::Position,
        qualifier: &Self::Intent,
    ) -> DispatchResult { ... }
    fn on_place_commit_on_variant(
        _who: &Proprietor,
        _reason: &Self::Reason,
        _digest: &Self::Digest,
        _value: Self::Asset,
        _variant: &Self::Position,
    ) { ... }
    fn on_set_commit_variant(
        _who: &Proprietor,
        _reason: &Self::Reason,
        _digest: &Self::Digest,
        _value: Self::Asset,
        _variant: &Self::Position,
    ) { ... }
    fn on_set_digest_variant(
        _digest: &Self::Digest,
        _reason: &Self::Reason,
        _value: Self::Asset,
        _variant: &Self::Position,
    ) { ... }
}

CommitVariant extends Commitment by introducing variant-based commitments - allowing each commitment to represent a specific position or type, such as positive/negative, long/short, or other directional states.

This abstraction is useful in financial systems where commitments can have opposing or complementary meanings (e.g., bets, trades, or hedges), and where such variants must be consistently classified and tracked under the same digest or reason.

Purpose

In standard Commitment, each digest represents a single locked or committed value. However, many financial instruments carry a semantic variant, such as:

• Positive / Negative exposure
• Long / Short position
• Buy / Sell order
• For / Against vote

CommitVariant provides an abstract way to encode and manage such distinctions without altering the base commitment model.

Core Principles

1. Variant as classification

   • Each commitment may declare a variant indicating its nature or direction.
   • Variants are accounted for directly under the commitment’s digest.

2. Digest-level association

   • A commitment’s digest uniquely identifies both its value and variant.
   • Variants must be recorded or derivable from the digest state.

3. Financial semantics

   • Designed for use in scenarios like betting, derivatives, prediction markets, and financial trilemmas where commitments can oppose or complement each other.

Example Use Cases

• Betting systems: Represent “for” and “against” commitments.
• Trading platforms: Track “long” and “short” positions.
• Hedging mechanisms: Manage opposing commitments under one reason.
• Voting protocols: Represent affirmative and negative stake commitments.

Summary

CommitVariant offers an abstract and extensible layer over Commitment, enabling richer semantics and directionality (positive/negative or other variants) to be embedded into financial commitment logic in a consistent, trustless manner.

Generics:

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

Required Associated Types

type Position: RuntimeEnum + Delimited

The type representing a commitment’s position or variant.

Required Methods

fn get_commit_variant( who: &Proprietor, reason: &Self::Reason, ) -> Result<Self::Position, DispatchError>

Retrieves the position/variant of a proprietor’s commitment for the given reason.

Returns the active variant under which the proprietor’s commitment is currently classified. Since each proprietor can have only one commitment per reason (base trait invariant), they also have only one active variant per reason.

Returns

• Ok(Position) containing the commitment’s current variant
• Err(DispatchError) if no commitment exists for the reason

fn get_digest_variant_value( reason: &Self::Reason, digest: &Self::Digest, variant: &Self::Position, ) -> Result<Self::Asset, DispatchError>

Retrieves the aggregated value for a specific digest and variant combination.

Returns the real-time sum of all commitments to the given digest that are classified under the specified variant. This enables querying variant-specific exposure across all proprietors.

When both Commitment and CommitVariant are implemented:

• Commitment::get_digest_value returns the aggregate across all variants
• This method returns the aggregate for a specific variant

Returns

• Ok(Asset) containing the variant-specific aggregated value
• Err(DispatchError) if the digest or variant does not exist

fn set_digest_variant_value( reason: &Self::Reason, digest: &Self::Digest, value: Self::Asset, variant: &Self::Position, qualifier: &Self::Intent, ) -> Result<Self::Asset, DispatchError>

Sets or updates the aggregated value for a specific digest and variant.

Updates the value associated with a particular variant of a digest, propagating changes to all commitments tied to that digest-variant pair.

When both Commitment and CommitVariant are utilized in a system:

• Commitment::set_digest_value may set the default variant.
• This method updates the specified variant.

The qualifier defines how the update is applied (e.g., exact vs best-effort, forceful vs bounded), and may influence the final value that is actually set.

Returns

• Ok(Asset) containing the actual value applied to the specified digest-variant
• Err(DispatchError) if the digest, variant, or reason is invalid, or update fails

fn place_commit_of_variant( who: &Proprietor, reason: &Self::Reason, digest: &Self::Digest, value: Self::Asset, variant: &Self::Position, qualifier: &Self::Intent, ) -> Result<Self::Asset, DispatchError>

Places a commitment under a specific variant.

Creates a new commitment with explicit variant classification, enabling directional or positional semantics from the moment of placement.

This extends Commitment::place_commit by adding variant specification. When both traits are implemented:

• Commitment::place_commit may use a default variant
• This method allows explicit variant selection

The method must:

• Record the commitment under the specified variant
• Associate the variant with the digest at the commitment level
• Respect qualifier parameters
• Return the actual committed value after any adjustments

Returns

• Ok(Asset) containing the actual value committed under the variant
• Err(DispatchError) if placement fails.

Provided Methods

fn can_set_digest_variant_value( reason: &Self::Reason, digest: &Self::Digest, value: Self::Asset, variant: &Self::Position, qualifier: &Self::Intent, ) -> DispatchResult

Validates whether a specific digest variant’s value can be set or updated.

Ensures that:

• The variant is initialized (has a balance entry)
• The intended update respects mint/reap advisory limits

Returns

• Ok(()) if validation succeeds
• Err(DispatchError) if the digest/variant is invalid or limits are violated

fn can_place_commit_of_variant( who: &Proprietor, reason: &Self::Reason, digest: &Self::Digest, variant: &Self::Position, value: Self::Asset, qualifier: &Self::Intent, ) -> DispatchResult

Validates whether a new commitment can be placed for a specific variant.

Ensures that no existing commitment exists for the given reason (enforcing the “one digest per reason” invariant) and that the proprietor has sufficient available funds to cover the commitment value.

Additionally validates that the value satisfies variant-specific placement limits derived from the lazy balance model.

Returns

• Ok(()) if validation succeeds
• Err(DispatchError) if a commitment already exists, insufficient funds are available, or the value violates variant-specific limits

fn digest_mint_limits_of_variant( _digest: &Self::Digest, _reason: &Self::Reason, _variant: &Self::Position, _qualifier: &Self::Intent, ) -> Result<Self::Limits, DispatchError>

Provides advisory bounds for increasing (minting) a digest’s specific variant-balance.

Acts as an optional guard to prevent abrupt or excessive growth, complementing core digest update logic.

fn digest_reap_limits_of_variant( _digest: &Self::Digest, _reason: &Self::Reason, _variant: &Self::Position, _qualifier: &Self::Intent, ) -> Result<Self::Limits, DispatchError>

Provides advisory bounds for decreasing (reaping) a digest’s specific variant-balance.

Acts as an optional guard to prevent aggressive or premature reductions, complementing core invariants that ensure correctness.

fn place_commit_limits_of_variant( _who: &Proprietor, _reason: &Self::Reason, _digest: &Self::Digest, _variant: &Self::Position, _qualifier: &Self::Intent, ) -> Result<Self::Limits, DispatchError>

Provides advisory bounds for placing a new commitment under a given variant.

Acts as an optional pre-validation layer to prevent premature or undesirable commits by constraining value ranges.

fn set_commit_variant( who: &Proprietor, reason: &Self::Reason, variant: &Self::Position, qualifier: &Self::Intent, ) -> DispatchResult

Changes the variant of an existing commitment.

Transitions a commitment from its current variant to a new variant while preserving the committed value. Since commitments are immutable, this operation uses the resolve-and-replace pattern.

Ensures that variant changes maintain consistency with the underlying commitment state and respect the semantics of the commitment system.

In case if the variant already exists, the function safely returns.

Returns

• Ok(()) if the variant is successfully changed
• Err(DispatchError) if:
  • No commitment exists for the reason
  • New variant matches current variant
  • Commitment resolution or placement fails

fn on_place_commit_on_variant( _who: &Proprietor, _reason: &Self::Reason, _digest: &Self::Digest, _value: Self::Asset, _variant: &Self::Position, )

Hook called after placing a commitment under a specific variant.

Provides an extension point for triggering custom side-effects when a new variant-based commitment is placed.

Default implementation is a no-op.

fn on_set_commit_variant( _who: &Proprietor, _reason: &Self::Reason, _digest: &Self::Digest, _value: Self::Asset, _variant: &Self::Position, )

Hook called after a commitment’s variant is changed.

Provides an extension point for responding to variant transitions. Receives both the digest and value to enable comprehensive state management and analytics.

Default implementation is a no-op.

fn on_set_digest_variant( _digest: &Self::Digest, _reason: &Self::Reason, _value: Self::Asset, _variant: &Self::Position, )

Hook called after a digest’s variant value is updated.

Provides an extension point for reacting to variant-specific value changes.

Default implementation is a no-op.

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