Module commitment

A composable framework for expressing financial intent as immutable commitments.

Overview

This module defines a comprehensive set of traits for building financial commitment systems that are semantic, composable, transparent, and consistent.

At its core, a commitment represents bonding value to a specific digest under a reason.

Instead of treating value as passive balance, this framework models value as something actively bound with purpose and context.

Every commitment binds an asset to:

• a Reason - why the value is committed
• a Digest - the exact terms or context the value is bonded to

Together, they form a verifiable, immutable agreement.

Commitments can carry meaning through variants (e.g., long/short, for/against, positive/negative), support grouping via indexes and pools, and allow real-time inspection of state.

The reason provider (runtime logic) governs how committed value evolves: it can update digest-level values, effectively managing all bonded funds under that reason. Individual commitments are resolved lazily, meaning adjustments are realized only when commitments are settled.

Mental Model

A commitment can be understood as:

“Bond this value, for this purpose, to this exact context.”

• Reason provides intent (staking, escrow, trade, vote)
• Digest defines the binding target (hash, identifier, agreement)
• Asset represents the value being bonded

This abstraction unifies patterns across financial systems such as staking, escrow, betting, trading, and governance.

Trait Architecture

The framework is layered:

Foundation

• Commitment - atomic bonding and lifecycle of commitments
• InspectAsset - available funds introspection
• DigestModel - digest classification

Grouping

• CommitIndex - a single commitment distributed across multiple digests under a reason, as if placed individually

• CommitPool - manager-controlled allocation of bonded funds across multiple digests under a reason, without custodial ownership

Semantics

• CommitVariant - directional meaning (long/short, for/against)
• IndexVariant - variants applied to indexed commitments
• PoolVariant - variants applied to pooled commitments

These traits compose into a layered system:

• Base layer: Commitment, InspectAsset, DigestModel
• Grouping layer: CommitIndex, CommitPool
• Variant layer: CommitVariant, IndexVariant, PoolVariant

Core Properties

• Atomic - bonded commitments cannot be partially altered
• Immutable - Commitment::Digest and reason define permanent binding
• Value-bound - always tied to quantifiable assets
• Composable - higher-level abstractions reuse the same rules
• Inspectable - real-time bonded state is always queryable

Why This Exists

Many financial systems repeatedly implement the same primitives:

• locking or bonding funds
• enforcing rules
• tracking intent
• preventing duplication

This framework provides a unified abstraction to express all of them consistently and safely.

Invariants

• One commitment per (proprietor, reason)
• Commitments are immutable (value may only increase via Commitment::raise_commit)
• Commitment::Digest defines the binding target and scope
• State reflects current values via Commitment::get_digest_value, not historical deposits

Use Cases

This framework is applicable across domains such as:

• Financial systems (bets, trades, hedges)
• Prediction markets (affirmative/negative stakes)
• Voting protocols (for/against commitments)
• Portfolio management (indexed and pooled commitments)
• Escrow and contract systems

Summary

Commitment = bonding value to a digest under a reason

This module transforms raw assets into structured, meaningful agreements that can be composed into complex financial systems.

Enums

CommitError

Commitment-related error type used in trait defaults.

Traits

CommitErrorHandler

A trait for mapping domain-level Commitment errors into caller- or pallet-specific error types.

CommitIndex

CommitIndex extends Commitment by providing a higher-level financial abstraction that groups multiple commitments under a single “index”.

CommitPool

CommitPool extends Commitment and CommitIndex to provide a managed, dynamic commitment abstraction.

CommitVariant

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.

Commitment

Represents an atomic, immutable financial agreement between parties.

DigestModel

A trait for determining the model variant of a digest.

IndexVariant

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

InspectAsset

A trait for inspecting the total available funds of an proprietor.

PoolVariant

A trait for managing and querying variants of pool slots and their commitments.