Crate pallet_commitment

Implementation crate for the Commitment family of traits.

A semantic bonding layer that binds assets to caller-defined purpose and context, with collective management of bonded value and lazy adjustments.

Used instead of direct fungible locks to enable richer control semantics and automated balance management. These are called commitments as they inherently carry a semantic reason defined by the consuming pallet.

Overview

• Config - Runtime configuration
• Call - Dispatchable extrinsics
• Pallet - Trait implementation for external modules

This pallet provides a generalized bonding (locking) mechanism for fungible (quantitative) assets, enabling other pallets to express structured financial intent.

Instead of treating balances as passive values, this system allows assets to be:

• Bonded under a reason (e.g., LockReason)
• Bound to a digest (a context-specific identifier defined by the caller pallet)

Together, this forms a Commitment:

Commitment = bond(asset) -> (reason, digest)

Key Responsibilities

This pallet acts as a shared infrastructure layer that:

• Locks assets on behalf of any fungible account
• Groups commitments under runtime-defined reasons
• Tracks and manages value at the digest level
• Allows controlled updates to aggregated digest values

The meaning and context of each digest are defined by the caller pallet (e.g., staking, escrow, trading, governance).

Core Features

• Commitment - lock assets under (reason, digest), enforcing one commitment per (proprietor, reason). Value can only increase per commitment, while aggregate digest values may be adjusted. Supports lazy resolution.

• Digest Management - track and update aggregate value at the digest level, propagating changes to all commitments.

• Digest Mint / Reap - increase or decrease the aggregate value of a digest, automatically adjusting all associated commitments proportionally.

• Indexes - group multiple digests with share-based ownership (see CommitIndex).

• Pools - manager-controlled allocation with dynamic rebalancing and fixed commissions (see CommitPool).

• Variants - semantic differentiation (e.g., long/short, positive/negative) (see CommitVariant).

• Lazy Evaluation - values reflect live digest state and are realized on query or resolution.

• Asset Agnostic - works with any fungible asset type implementing required traits.

Each commitment is scoped by a Reason and anchored to a Digest.

Design Scope

The pallet is a generic implementation of Commitment, designed to be loosely coupled with consumer pallets via their Config traits.

// Consumer pallet configuration
pub trait Config {
    /// Commitment adapter providing bonding logic
    type CommitmentAdapter: Commitment<Self::AccountId>;
}

It handles commitment accounting and lifecycle management, while consumer pallets define domain-specific logic and user interactions.

This provides a bonding abstraction over basic fungible locks, enabling rich economic behaviors without duplicating core logic.

Extrinsics Scope

This pallet exposes no user-facing extrinsics for commitments.

Commitment operations are accessed by consumer pallets through the traits, ensuring controlled and domain-specific usage.

Only minimal extrinsics for basic deposit and withdrawal for a default PrepareForCommit hold/reserve are provided and some read-only APIs (see Call).

Native Commitment Reserve

This pallet exposes only minimal extrinsics to deposit and withdraw funds into a native reserve (HoldReason::PrepareForCommit), which acts as the default funding source for all commitment operations.

Commitments consume assets from this reserve under Fortitude::Polite, allowing users to pre-fund commitments once and reuse the same reserve across all consumer pallets, ensuring efficient, directive-driven execution

When Fortitude::Force is used, operations may fallback to the liquid (free) balance if reserve funds are insufficient.

Consumer pallets utilizing commitments should account for this behavior:

• use polite semantics to operate strictly on reserved funds
• use force semantics to allow fallback to liquid balance when required

Instance and Model

The pallet supports multiple instances, each capable of handling commitments across diverse scenarios.

• Each instance may define its own configuration via Config, allowing independent behavior and specialization.

• Each instance supports multiple reasons, enabling different pallets or domains to operate within the same instance.

• A single instance can be shared across multiple consumer pallets, with separation maintained through reasons and digests.

• Instances may be separated when isolation is required.

This enables the pallet to act as a shared economic layer across use cases.

Terminology

• Proprietor - the account or entity that owns and manages commitments.
• Reason - the categorical purpose of a commitment.
• Digest - a unique identifier representing commitment context.
• Direct Commitment - a commitment to a single digest.
• Index - a collection of digests with shares (see CommitIndex).
• Pool - a managed structure with allocation and commission (see CommitPool).
• Entry - a digest component within an index.
• Slot - a digest component within a pool.
• Commission - manager’s share collected on resolution.
• Variant - semantic position (see CommitVariant).

Development Feature Gate

This pallet includes a dev feature gate for development and testing.

Core functionality is exposed via public APIs for RPC and UI usage. The dev feature provides thin wrapper extrinsics and extended events for direct inspection.

This feature must be disabled in production runtimes due to additional debugging overhead.

Re-exports

pub use pallet::*;

Modules

balance 🔒

Pallet implementation of LazyBalance using virtual structs and plugins.

commitment 🔒

Implementation module of the Commitment Family traits, where we utilize indexes, pools, and variants to create a flexible and semantic commitment system.

helpers 🔒

Implementation of low-level commit-helpers traits for the internal CommitHelpers Type.

pallet

The pallet module in each FRAME pallet hosts the most important items needed to construct this pallet.

traits

Defines helper traits for implementing a concrete Commitment system. All operations are low-level and unchecked - callers must ensure validity, equilibrium, and invariants before invoking these functions.

types

Core types and aliases for the Commitment system.

weights

Autogenerated weights for pallet_commitment