Trait Commitment

pub trait Commitment<Proprietor>: InspectAsset<Proprietor> + CommitErrorHandler {
    type DigestSource: Elastic;
    type Digest: Keyed;
    type Reason: Elastic + Storable + RuntimeEnum;
    type Intent: Delimited + Directive + Default;
    type Limits: Extent<Scalar = Self::Asset>;

    // Required methods
    fn commit_exists(who: &Proprietor, reason: &Self::Reason) -> DispatchResult;
    fn digest_exists(
        reason: &Self::Reason,
        digest: &Self::Digest,
    ) -> DispatchResult;
    fn get_commit_digest(
        who: &Proprietor,
        reason: &Self::Reason,
    ) -> Result<Self::Digest, DispatchError>;
    fn get_total_value(reason: &Self::Reason) -> Self::Asset;
    fn get_commit_value(
        who: &Proprietor,
        reason: &Self::Reason,
    ) -> Result<Self::Asset, DispatchError>;
    fn get_digest_value(
        reason: &Self::Reason,
        digest: &Self::Digest,
    ) -> Result<Self::Asset, DispatchError>;
    fn gen_digest(
        via: &Self::DigestSource,
    ) -> Result<Self::Digest, DispatchError>;
    fn place_commit(
        who: &Proprietor,
        reason: &Self::Reason,
        digest: &Self::Digest,
        value: Self::Asset,
        qualifier: &Self::Intent,
    ) -> Result<Self::Asset, DispatchError>;
    fn resolve_commit(
        who: &Proprietor,
        reason: &Self::Reason,
    ) -> Result<Self::Asset, DispatchError>;
    fn raise_commit(
        who: &Proprietor,
        reason: &Self::Reason,
        value: Self::Asset,
        qualifier: &Self::Intent,
    ) -> Result<Self::Asset, DispatchError>;
    fn set_digest_value(
        reason: &Self::Reason,
        digest: &Self::Digest,
        value: Self::Asset,
        qualifier: &Self::Intent,
    ) -> Result<Self::Asset, DispatchError>;
    fn reap_digest(
        digest: &Self::Digest,
        reason: &Self::Reason,
    ) -> DispatchResult;

    // Provided methods
    fn can_place_commit(
        who: &Proprietor,
        reason: &Self::Reason,
        digest: &Self::Digest,
        value: Self::Asset,
        qualifier: &Self::Intent,
    ) -> DispatchResult { ... }
    fn can_raise_commit(
        who: &Proprietor,
        reason: &Self::Reason,
        value: Self::Asset,
        qualifier: &Self::Intent,
    ) -> DispatchResult { ... }
    fn can_resolve_commit(
        who: &Proprietor,
        reason: &Self::Reason,
    ) -> DispatchResult { ... }
    fn can_set_digest_value(
        reason: &Self::Reason,
        digest: &Self::Digest,
        value: Self::Asset,
        qualifier: &Self::Intent,
    ) -> DispatchResult { ... }
    fn digest_mint_limits(
        _digest: &Self::Digest,
        _reason: &Self::Reason,
        _qualifier: &Self::Intent,
    ) -> Result<Self::Limits, DispatchError> { ... }
    fn place_commit_limits(
        _who: &Proprietor,
        _reason: &Self::Reason,
        _digest: &Self::Digest,
        _qualifier: &Self::Intent,
    ) -> Result<Self::Limits, DispatchError> { ... }
    fn raise_commit_limits(
        _who: &Proprietor,
        _reason: &Self::Reason,
        _qualifier: &Self::Intent,
    ) -> Result<Self::Limits, DispatchError> { ... }
    fn digest_reap_limits(
        _digest: &Self::Digest,
        _reason: &Self::Reason,
        _qualifier: &Self::Intent,
    ) -> Result<Self::Limits, DispatchError> { ... }
    fn on_commit_place(
        _who: &Proprietor,
        _reason: &Self::Reason,
        _digest: &Self::Digest,
        _value: Self::Asset,
    ) { ... }
    fn on_commit_raise(
        _who: &Proprietor,
        _reason: &Self::Reason,
        _digest: &Self::Digest,
        _value: Self::Asset,
    ) { ... }
    fn on_commit_resolve(
        _who: &Proprietor,
        _reason: &Self::Reason,
        _digest: &Self::Digest,
        _value: Self::Asset,
    ) { ... }
    fn on_digest_update(
        _digest: &Self::Digest,
        _reason: &Self::Reason,
        _value: Self::Asset,
    ) { ... }
    fn on_reap_digest(
        _digest: &Self::Digest,
        _reason: &Self::Reason,
        _dust: Self::Asset,
    ) { ... }
}

Represents an atomic, immutable financial agreement between parties.

It is anchored in:

• a Reason (category/purpose),
• a Digest (commitment context),
• and the act of committing a value.

Key Concepts

• Commitment: Locking or assigning an asset under agreed terms.
• Reason: Purpose/category (e.g., staking, escrow, collateral, investment, betting).
• Digest: Immutable reference to the commitment’s context or terms (often a cryptographic hash or a contextual identifier).
• Proprietor: Entity responsible for holding/committing the asset.
• Asset: Value being committed.

Why Commitment?

Many financial systems - staking, escrow, lending, betting, auctions - share a common pattern: one party proposes terms (digest), another commits a value under those terms, and both agree on the purpose (reason).

Without a unifying abstraction, each system must reimplement logic for:

• Locking assets
• Ensuring immutability of terms
• Preventing double commitments
• Categorizing commitments by purpose

The Commitment trait standardizes this pattern, enabling:

• Consistency: Same behavior across different financial constructs.
• Composability: Higher-level constructs (pools, indexes, markets) reuse the same rules.
• Auditability: Commitments can be inspected and verified.

Properties

• Atomic: Commitments cannot be partially altered.
• Immutable: Digest + Reason permanently define the commitment.
• Category-driven: Reason defines interpretation.
• Value-based: Always tied to a quantifiable asset.

Real-World Analogies

Use Case	Reason	Digest	Commitment
Stake	"staking"	Conditions hash	Staked amount
Escrow	"escrow"	Contract terms hash	Locked funds
Collateral	"loan collateral"	Loan agreement hash	Pledged asset
Betting	"bet"	Bet terms	Wagered asset
Market position	"market trade"	Order terms	Locked funds
Auction	"auction bid"	Bid terms	Bid amount

Examples

• Staking: Alice stakes 100 tokens for reason "staking" with digest "ant_pool_hash".

  • Proprietor: Alice
  • Reason: "staking"
  • Digest: "ant_pool_hash"
  • Asset: 100 tokens.

• Betting: Bob places a bet of 50 tokens for reason "bet_games" with digest "nfl_betting".

  • Locks Bob’s stake until event outcome.

• Escrow: Carol commits 1000 tokens into escrow for reason "escrows" with digest "freelance".

  • Funds locked until conditions are fulfilled.

• Market Order: Dave places a buy order worth 500 tokens for reason "market_orders" with digest "cryptocurrencies".

  • Funds locked until order executes or cancels.

Invariants

• Proprietor can commit to only one digest per reason.
• Commitments are atomic and immutable.
• Commitment value may increase via Commitment::raise_commit but cannot be decreased arbitrarily.
• Commitment values are dynamic, reflecting real-time state.
• Digest values may be updated by the reason provider via Commitment::set_digest_value and must propagate to all related commitments.

Summary:
Commitment = locked asset,
Reason = purpose/category,
Digest = agreement terms hash,
Act of commitment = immutable financial agreement.

Generics:

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

Required Associated Types

type DigestSource: Elastic

The source used to generate the digest.

type Digest: Keyed

The immutable substance proposed by the first party - the “sealed deed content”. It represents the details of the deed or offer that expects a commitment.

Digest is the core of a commitment: it proves what the commitment is tied to, and ensures it is fixed and immutable.

type Reason: Elastic + Storable + RuntimeEnum

The category or type of the commitment. Provides meaning to the digest by placing it in context.

type Intent: Delimited + Directive + Default

Represents the qualitative configuration of a commit operation.

Encodes behavioral characteristics such as precision and fortitude, influencing how commitments are evaluated and executed. (e.g. exact vs approximate, polite vs forceful execution).

Default is provided if in case no preference is provided.

type Limits: Extent<Scalar = Self::Asset>

Provides optional advisory bounds for commitment and digest operations.

These limits act as an additional validation layer on top of core invariants, helping prevent premature or extreme values without affecting correctness.

Uses Extent to express minimum, maximum, or optimal values.

Required Methods

fn commit_exists(who: &Proprietor, reason: &Self::Reason) -> DispatchResult

Checks whether a commitment exists for the given proprietor and reason.

Returns

• Ok(()) if the commitment exists
• Err(DispatchError) if no commitment is found

fn digest_exists(reason: &Self::Reason, digest: &Self::Digest) -> DispatchResult

Checks whether a specific digest exists for the given reason.

Returns

• Ok(()) if the digest exists
• Err(DispatchError) if the digest is not found

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

Retrieves the digest tied to a proprietor’s commitment for the given reason.

Since the system enforces only one digest per reason, its expected to be only a single digest or none.

Returns

• Ok(Digest) containing the commitment’s digest
• Err(DispatchError) if no commitment exists for the reason

fn get_total_value(reason: &Self::Reason) -> Self::Asset

Retrieves the total aggregated value for all commitments under the given reason.

Returns

• Self::Asset containing the total value across all commitments for the reason

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

Retrieves the current real-time value of a proprietor’s commitment for the given reason.

Returns the live committed value at the moment of calling, reflecting any changes to the underlying digest value since the commitment was initially placed. This is not a historical value but the actual current state, as digest values can be updated via set_digest_value.

Returns

• Ok(Asset) containing the current commitment value
• Err(DispatchError) if the commitment does not exist

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

Retrieves the current aggregated value for the given digest under the specified reason.

Returns the real-time sum of all commitments tied to the digest. Useful for evaluating the full scope of commitments to a specific digest.

Returns

• Ok(Asset) containing the aggregated digest value
• Err(DispatchError) if the digest does not exist or lookup fails

fn gen_digest(via: &Self::DigestSource) -> Result<Self::Digest, DispatchError>

Generates a unique digest from the provided source.

Creates an immutable identifier that represents the commitment’s terms, ensuring collision-free digest generation across the system.

Returns

• Ok(Digest) containing the generated unique digest
• Err(DispatchError) if digest generation fails

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

Places an immutable commitment for the specified digest and reason.

Locks the specified value under the given digest and reason, creating an atomic commitment that cannot be reduced or partially withdrawn.

The qualifier parameter enforces exactness or best-effort semantics, while also specifying whether the system must force achieving the commitment conditions.

Returns

• Ok(Asset) containing the actual value committed to the digest
• Err(DispatchError) if placement fails due to insufficient funds or validation errors

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

Resolves and releases the commitment tied to the specified reason.

Finalizes the commitment for the given proprietor and reason, releasing the locked value.

Proprietors are enforced to commit to a single digest per reason, ensuring unambiguous resolution. Higher-level traits such as CommitIndex or CommitPool can be built to allow indexed or pooled commitments on top of this invariant.

The returned value may differ from the original deposit depending on the reason’s context and any adjustments made during the commitment’s lifetime possibly via Commitment::set_digest_value.

Returns

• Ok(Asset) containing the fully resolved commitment value
• Err(DispatchError) if the commitment does not exist or resolution fails

fn raise_commit( who: &Proprietor, reason: &Self::Reason, value: Self::Asset, qualifier: &Self::Intent, ) -> Result<Self::Asset, DispatchError>

Increases the value of an existing commitment.

Adds the specified value to an existing commitment for the given reason. This operation can only be performed if a commitment already exists.

The qualifier parameter control how the increase is applied.

Returns

• Ok(Asset) containing the increment actually added (not the total value)
• Err(DispatchError) if the commitment does not exist or if the increase fails

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

Sets or updates the aggregated value of the specified digest.

Allows the reason provider (implementer) to adjust the digest’s value, which automatically propagates to all individual commitments tied to that digest.

The qualifier defines how the update is applied (e.g., exact vs best-effort, forceful vs relaxed), and determines the execution semantics for the direction of change (increase or decrease relative to the current value).

Returns

• Ok(Asset) containing the actual value applied to the digest
• Err(DispatchError) if the digest does not exist or update fails

fn reap_digest(digest: &Self::Digest, reason: &Self::Reason) -> DispatchResult

Removes a digest if it has no associated commitments.

Permanently deletes the specified digest from the system if its aggregated value is zero, freeing resources and cleaning up unused entries. This is a maintenance operation and it should ensures no commitments exist for the digest before reaping.

Returns

• Ok(()) if the digest is successfully removed
• Err(DispatchError) if the digest does not exist or still has active commitments

Provided Methods

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

Validates whether a new commitment can be placed.

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.

Returns

• Ok(()) if validation succeeds
• Err(DispatchError) if a commitment already exists or insufficient funds are available

fn can_raise_commit( who: &Proprietor, reason: &Self::Reason, value: Self::Asset, qualifier: &Self::Intent, ) -> DispatchResult

Validates whether an existing commitment can be increased.

Ensures that a commitment for the given reason already exists and that the proprietor has sufficient available funds to increase the commitment by the specified value.

Returns

• Ok(()) if validation succeeds
• Err(DispatchError) if any of the condition fails.

fn can_resolve_commit(who: &Proprietor, reason: &Self::Reason) -> DispatchResult

Validates whether an existing commitment can be resolved.

Ensures that a commitment for the given reason exists before allowing resolution/closing.

Returns

• Ok(()) if validation succeeds
• Err(DispatchError) if no such commitment exists

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

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

Ensures that the specified digest exists under the given reason, and that the intended value update respects advisory limits (mint or reap depending on direction).

The qualifier may influence how limits are interpreted.

Returns

• Ok(()) if validation succeeds
• Err(DispatchError) if the digest does not exist or limits are violated

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

Provides advisory bounds for increasing (minting) a digest’s value.

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

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

Provides advisory bounds for placing a new commitment.

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

fn raise_commit_limits( _who: &Proprietor, _reason: &Self::Reason, _qualifier: &Self::Intent, ) -> Result<Self::Limits, DispatchError>

Provides advisory bounds for increasing an existing commitment.

Acts as an optional guard to prevent excessive or premature raises, complementing core checks like existence and available funds.

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

Provides advisory bounds for decreasing (reaping) a digest’s value.

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

fn on_commit_place( _who: &Proprietor, _reason: &Self::Reason, _digest: &Self::Digest, _value: Self::Asset, )

Hook called after a commitment is successfully placed.

Provides an extension point for triggering side-effects such as events, logging, external state updates, or notifications when a new commitment is established.

Default implementation is a no-op.

fn on_commit_raise( _who: &Proprietor, _reason: &Self::Reason, _digest: &Self::Digest, _value: Self::Asset, )

Hook called after a commitment is successfully raised (increased).

Provides an extension point for triggering side-effects such as recalculations, notifications, event emissions, or external state synchronization when an existing commitment’s value is increased.

Default implementation is a no-op.

fn on_commit_resolve( _who: &Proprietor, _reason: &Self::Reason, _digest: &Self::Digest, _value: Self::Asset, )

Hook called after a commitment is successfully resolved.

Provides an extension point for performing cleanup, distributing rewards or penalties, audit logging, or triggering any finalization logic when a commitment is released.

Default implementation is a no-op.

fn on_digest_update( _digest: &Self::Digest, _reason: &Self::Reason, _value: Self::Asset, )

Hook called after a digest’s value is updated.

Provides an extension point for triggering recalculation of dependent commitments, propagating changes to related state, or emitting events when a digest’s aggregated value changes.

Default implementation is a no-op.

fn on_reap_digest( _digest: &Self::Digest, _reason: &Self::Reason, _dust: Self::Asset, )

Hook called after a digest is reaped (removed).

Provides an extension point for cleanup tasks, logging, freeing related resources, or triggering external notifications when a digest is permanently removed from the system.

dust represents any residual value that was unclaimable and effectively considered dead.

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