Struct CommitHelpers

pub(crate) struct CommitHelpers<T: Config<I>, I: 'static = ()>(PhantomData<(T, I)>);

Internal helper struct for implementing low-level commitment trait operations.

This marker type serves as a namespace for trait implementations defined in crate::traits, providing internal access to commitment system low-level primitives without exposing unchecked-functions as part of the public API via Pallet.

CommitHelpers implements the commitment low-level helper traits:

• CommitBalance
• CommitDeposit
• CommitWithdraw
• CommitOps
• CommitInspect
• PoolOps
• IndexOps

Tuple Fields

0: PhantomData<(T, I)>

Trait Implementations

impl<T: Config<I>, I: 'static> CommitBalance<<T as Config>::AccountId, Pallet<T, I>> for CommitHelpers<T, I>

Implements the CommitBalance trait for the pallet.

Provides low-level balance management.

type Imbalance = AssetDelta<T, I>

The structure representing a differential between deposited and withdrawn asset values - used to determine how the balance should be compensated.

fn resolve_imbalance( who: &Proprietor<T>, imbalance: Self::Imbalance, ) -> Result<<Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, DispatchError>

Resolves an asset imbalance for a proprietor when a commitment is finalized (e.g. during withdrawal).

An imbalance may arise when a commitment’s effective value changes due to digest updates (for example via Commitment::set_digest_value). This function reconciles the difference between deposited and withdrawn amounts to preserve financial consistency.

The reconciliation is performed through the pallet’s Config::Asset fungible adapter by minting, burning, or reissuing assets as required.

This function finalizes the pallet’s internal accounting by settling AssetToIssue and AssetToReap with the underlying asset system.

Notably, this function does not rely on balanced fungible traits. Instead, the original deposit is returned to the proprietor, and any additional minting or burning is performed explicitly and independently via unbalanced low-level fungible traits.

This ensures balance adjustments occur in a controlled and safe manner without directly mutating the proprietor’s balance.

Behavior

• deposit < withdraw: The shortfall is minted as a reward (accounted via AssetToIssue).
• deposit == withdraw: The values are balanced; no action is taken.
• deposit > withdraw: The surplus is burned as a penalty (accounted via AssetToReap).

Returns

• Ok(Asset) containing the final asset value returned to the proprietor after resolving the imbalance.
• Err(DispatchError) if minting or burning fails or capacity is insufficient.

fn deduct_balance( who: &Proprietor<T>, value: <Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, qualifier: &DispatchPolicy, ) -> Result<<Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, DispatchError>

Deducts a specified asset value from the proprietor’s balance.

Held funds (under HoldReason::PrepareForCommit) are applied first, followed by liquid funds if required. The deduction behavior is governed by the provided precision and fortitude parameters:

• Precision: Determines whether an exact amount is required or a best-effort deduction is acceptable.
• Fortitude: Determines whether deduction should be polite or forceful.

When Fortitude::Polite is used, only held (commit-reserved) funds are deducted. When Fortitude::Force is used, deduction first consumes any available held funds and then continues from the liquid balance if needed.

All balance operations are performed under a preservation context and therefore never risk account closure.

Returns

• Ok(Asset) containing the actual amount deducted.
• Err(DispatchError) if funds are insufficient or the deduction fails.

fn deduct_from_imbalance( imbalance: &mut Self::Imbalance, value: <Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, ) -> Result<Self::Imbalance, DispatchError>

Deducts a specified value from an existing imbalance, mutating it in-place.

This function extracts value from that differential while preserving correct economic accounting for rewards or penalties.

Semantics

• If withdraw > deposit (reward state): the deduction first consumes the reward portion. Any excess deduction converts into a penalty, increasing AssetToReap.
• If withdraw == deposit (neutral state): the deduction is treated as a penalty and directly increases AssetToReap.
• If withdraw < deposit (penalty state): the deduction deepens the penalty, further increasing AssetToReap.

In all cases, the imbalance holder remains the sole party whose economic position is adjusted, avoiding double mint/burn effects for both parties.

Returns

Returns a neutral imbalance (deposit == withdraw == value). This allows the caller to credit the deducted value directly to the underlying fungible system without introducing additional reward or penalty logic.

• DispatchError otherwise

impl<T: Config<I>, I: 'static> CommitDeposit<<T as Config>::AccountId, Pallet<T, I>> for CommitHelpers<T, I>

Implements the CommitDeposit trait for the pallet, providing low-level deposit functionality for digests, indexes, and pools within the commitment system.

type Receipt = ProductType<T, I, <<T as Config<I>>::BalanceContext as ModelContext>::Context, ReceiptAsset, ReceiptRational, ReceiptTime, ReceiptAddon>

Represents the “Receipt” of a digest at the time of a deposit.

Reference CommitInstance’s generic alias documentation, where it holds the deposit receipt from the digest’s lazy balance (LazyBalanceOf) when the deposit occurs.

It ensures that later commitment resolution can account for the digest’s state accurately, even if the underlying digest values changes over time.

fn deposit_to( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, digest_model: &<Pallet<T, I> as DigestModel<Proprietor<T>>>::Model, value: <Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, variant: &<Pallet<T, I> as CommitVariant<Proprietor<T>>>::Position, qualifier: &DispatchPolicy, ) -> Result<(Self::Receipt, <Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset), DispatchError>

Deposits a value for a given digest model and its specified variant.

This function centralizes the dispatch logic to the appropriate handler depending on the type of the digest model (Direct, Index, or Pool).

Returns

• Ok((DerivedBalance, Asset)) containing the deposit’s receipt and the actual depositted value.
• Err(DispatchError) if the deposit fails

fn deposit_to_digest( _who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, digest: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, value: <Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, variant: &<Pallet<T, I> as CommitVariant<Proprietor<T>>>::Position, qualifier: &DispatchPolicy, ) -> Result<(Self::Receipt, <Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset), DispatchError>

Deposits a given asset value into a specific direct-digest’s variant’s balance for a reason.

This is a low-level internal function - it:

• Directly deposits value into the specified digest and its variant.
• Does not inspect or deduct balance, as argument.

Digest variants represent different commitment positions (e.g., affirmative, contrary, etc). This function ensures deposits go to the correct variant’s balance via PositionIndex, as digest-balances will be stored as a vector of variant balances.

Returns

• Ok((DerivedBalance, Asset)) containing the deposit’s receipt and the actual depositted value.
• Err(DispatchError) if the digest variant cannot be found or mutated

fn deposit_to_index( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, index_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, value: <Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, _variant: &<Pallet<T, I> as CommitVariant<Proprietor<T>>>::Position, qualifier: &DispatchPolicy, ) -> Result<(Self::Receipt, <Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset), DispatchError>

Deposits a given asset value into an index and distributes it across its entries’ digests.

This is a low-level internal function - it:

• Splits the value proportionally across each entry based on its share/capital ratio.
• Delegates deposits into each entry’s digest via Self::deposit_to_digest.
• Updates the index’s own top-level balance.

Expected invariants:

• Total capital must be non-zero (no stale or invalid indexes).
• Total index capital must be at least the share value of each entry.
• Entry shares must be non-zero (no stale or invalid entries).

The caller’s variant is ignored because each entry already defines its own variant.

If the index deposit has any remaining assets, they are refunded to the proprietor here. Other commitment types (such as direct digests or pools) do not require refunding, so the refund logic is handled exclusively at this level.

Since Index maintains entry-commit receipts in their own high-level structures the receipt returned is a placeholder receipt (default), although the depositted amount is valid.

Returns

• Ok((DerivedBalance, Asset)) containing a placeholder receipt and the actual depositted value.
• Err(DispatchError) if the deposit cannot be conducted

fn deposit_to_pool( _who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, pool_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, value: <Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, _variant: &<Pallet<T, I> as CommitVariant<Proprietor<T>>>::Position, qualifier: &DispatchPolicy, ) -> Result<(Self::Receipt, <Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset), DispatchError>

Deposits a given asset value into a pool for a reason.

This is a low-level internal function - it:

• Directly deposits value into the specified pool.
• Does not inspect or deduct balance, as argument _who is unused.

The caller’s variant is ignored because each pool’s slot already defines its own variant.

At this level the logic is straightforward: the pool itself acts as a proprietor. It receives funds and commits them to individual slot digests, while external proprietors hold shares of the pool.

As a result, every deposit into or withdrawal from the pool requires the pool to temporarily release and then re-acquire the corresponding funds. This mirrors how an index commitment is resolved and re-placed by a proprietor.

Returns

• Ok((DerivedBalance, Asset)) containing the pool’s deposit receipt and the actual depositted value of the proprietor.
• Err(DispatchError) if the deposit cannot be conducted

impl<T: Config<I>, I: 'static> CommitInspect<<T as Config>::AccountId, Pallet<T, I>> for CommitHelpers<T, I>

Implements the CommitInspect trait for the pallet, providing low-level inspection and querying capabilities for committed values across digests, indexes, and pools.

This implementation allows retrieving real-time committed values without altering state, supporting precise accounting and auditability. All functions are low-level and unchecked, meaning callers are responsible for ensuring correctness and invariants before invoking.

fn commit_value_of( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, digest_model: &<Pallet<T, I> as DigestModel<Proprietor<T>>>::Model, ) -> Result<<Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, DispatchError>

Retrieves the total committed value of a proprietor for a fully resolved digest model.

This function centralizes the dispatch logic to the appropriate handler depending on the type of the digest model.

Digest models represent different commitment structures:

• Direct: a single digest commitment.
• Index: a grouped commitment of multiple entry digests.
• Pool: a shared resource i.e., a collective single commitment.

Returns

• Ok(Asset) containing the real-time committed value
• Err(DispatchError) if the digest model is invalid or any underlying query fails

fn digest_commit_value( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, digest: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, ) -> Result<<Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, DispatchError>

Retrieves the proprietor’s committed value for a direct digest of a given reason.

Returns

• Ok(Asset) representing the real-time committed value for the digest
• Err(DispatchError) otherwise

fn index_commit_value( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, index_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, ) -> Result<<Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, DispatchError>

Computes the total committed value of a proprietor for a given index digest.

Returns

• Ok(Asset) with the total committed value for the index
• Err(DispatchError) otherwise

fn index_entry_commit_value( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, index_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, entry_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, ) -> Result<<Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, DispatchError>

Computes the total committed value of a proprietor for a specific entry within an index.

Returns

• Ok(Asset) containing the total committed value for the entry
• Err(DispatchError) otherwise

fn pool_commit_value( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, pool_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, ) -> Result<<Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, DispatchError>

Computes the total committed value of a proprietor for a given pool.

Returns

• Ok(Asset) with the total effective committed value
• Err(DispatchError) otherwise

fn pool_slot_commit_value( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, pool_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, slot_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, ) -> Result<<Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, DispatchError>

Computes the commit value of a specific slot for a given proprietor within a pool.

Returns

• Ok(Asset>) representing the slot’s effective value for the proprietor
• Err(DispatchError) if calculation fails

fn value_of( digest_model: Option<&<Pallet<T, I> as DigestModel<Proprietor<T>>>::Model>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, ) -> Result<<Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, DispatchError>

Retrieves the total value of a reason or a specific digest model.

For a specific digest model, computes the total of all dispositions (Affirmative, Contrary, Awaiting) for direct digests, or delegates to index/pool calculations as appropriate. If no model is provided, returns the stored top-level reason value.

Returns

• Ok(CommitmentAsset<T, I>) representing the total value
• Err(DispatchError) if the reason is not found or digest value calculation fails

impl<T: Config<I>, I: 'static> CommitOps<<T as Config>::AccountId, Pallet<T, I>> for CommitHelpers<T, I>

Implements the CommitOps trait for the pallet

Provides low-level (not-lowest, but still unchecked) write functionalities for digests, indexes, and pools within the commitment system. This may utilize other commit-helper trait methods

fn place_commit_of( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, digest_model: &<Pallet<T, I> as DigestModel<Proprietor<T>>>::Model, value: <Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, variant: &<Pallet<T, I> as CommitVariant<Proprietor<T>>>::Position, qualifier: &DispatchPolicy, ) -> Result<<Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, DispatchError>

Places (creates) a commitment for a given digest model with the specified variant.

This function centralizes the dispatches to the appropriate underlying handler depending on the type of the digest model (Direct, Index, or Pool).

Digest models represent different commitment structures:

• Direct: a single digest commitment.
• Index: a grouped commitment of multiple entry digests.
• Pool: a shared resource i.e., a collective single commitment.

Returns

• Ok(Asset) containing the committed amount
• Err(DispatchError) if placement fails

fn place_digest_commit( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, digest: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, value: <Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, variant: &<Pallet<T, I> as CommitVariant<Proprietor<T>>>::Position, qualifier: &DispatchPolicy, ) -> Result<<Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, DispatchError>

Places (creates) a direct commitment for a specific digest of a given variant under a reason.

This function is the base implementation for placing commitments when the digest represents a single, direct item (not an index or pool).

Allows placing a commitment even if the digest does not already exist in the system.

Returns

• Ok(Asset) containing the actual committed amount
• Err(DispatchError) if placement fails

fn place_index_commit( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, index_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, value: <Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, variant: &<Pallet<T, I> as CommitVariant<Proprietor<T>>>::Position, qualifier: &DispatchPolicy, ) -> Result<<Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, DispatchError>

Places a commitment to an index digest under the specified reason.

Distributes the committed value proportionally across index entries based on their shares, creates entry-level commitment records, and updates the index balance.

Returns

• Ok(Asset) containing the actual committed amount
• Err(DispatchError) if placement fails

fn place_pool_commit( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, pool_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, value: <Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, variant: &<Pallet<T, I> as CommitVariant<Proprietor<T>>>::Position, qualifier: &DispatchPolicy, ) -> Result<<Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, DispatchError>

Places a commitment to a pool digest under the specified reason.

Deposits to the pool’s collective balance, updates slot digests proportionally, and maintains pool-level commitment records.

Returns

• Ok(Asset) containing the actual committed amount
• Err(DispatchError) if placement fails

fn raise_commit_of( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, digest_model: &<Pallet<T, I> as DigestModel<Proprietor<T>>>::Model, value: <Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, qualifier: &DispatchPolicy, ) -> Result<<Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, DispatchError>

Raises (increases) an existing commitment for a given digest model.

This function centralizes the dispatches to the appropriate underlying handler depending on the type of the digest model (Direct, Index, or Pool).

Digest models represent different commitment structures:

• Direct: a single digest commitment.
• Index: a grouped commitment of multiple entry digests.
• Pool: a shared resource i.e., a collective single commitment.

Returns

• Ok(Asset) containing the raised amount
• Err(DispatchError) if the raise operation fails

fn raise_digest_commit( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, digest: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, value: <Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, qualifier: &DispatchPolicy, ) -> Result<<Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, DispatchError>

Raises (increases) a commitment for a direct digest under a given reason.

This function is the base implementation for raising commitments when the target is an direct digest rather than a index or pool.

Unlike Self::place_digest_commit this adds a additional commit instance to the list of commits to the same direct digest enforcing the One Reason One Digest Per Proprietor invariant.

Returns

• Ok(Asset) containing the raised amount
• Err(DispatchError) if the raise operation fails

fn raise_index_commit( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, index_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, value: <Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, qualifier: &DispatchPolicy, ) -> Result<<Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, DispatchError>

Raises (increases) an existing commitment for a specific index under a given reason.

This function is the base implementation for raising commitments when the target is an index rather than a digest or pool.

Unlike Self::place_index_commit this adds a additional commit instance to the list of commits to the same index digest enforcing the One Reason One Digest Per Proprietor invariant.

Returns

• Ok(Asset) containing the raised amount
• Err(DispatchError) if the raise operation fails

fn raise_pool_commit( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, pool_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, value: <Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, qualifier: &DispatchPolicy, ) -> Result<<Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, DispatchError>

Raises (increases) an existing commitment for a specific pool digest under a given reason.

This function is the base implementation for raising commitments when the target is an pool rather than a digest or index.

Unlike Self::place_pool_commit this adds a additional commit instance to the list of commits to the same pool digest enforcing the One Reason One Digest Per Proprietor invariant.

Returns

• Ok(Asset) containing the raised amount
• Err(DispatchError) if the raise operation fails

fn resolve_commit_of( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, digest_model: &<Pallet<T, I> as DigestModel<Proprietor<T>>>::Model, ) -> Result<<Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, DispatchError>

Resolves (withdraws) and finalizes a commitment for a given digest model.

This function centralizes the dispatches to the appropriate underlying handler depending on the type of the digest model (Direct, Index, or Pool).

Digest models represent different commitment structures:

• Direct: a single digest commitment.
• Index: a grouped commitment of multiple entry digests.
• Pool: a shared resource i.e., a collective single commitment.

Returns

• Ok(Asset) containing the resolved commitment value
• Err(DispatchError) if resolution fails

fn resolve_digest_commit( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, digest: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, ) -> Result<<Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, DispatchError>

Resolves (withdraws) and finalizes a commitment for a direct digest under a given reason.

This function is the base implementation for resolving commitments when the target is an direct digest rather than a index or pool.

It resolves all commit instances tied to a direct digest of a reason.

Returns

• Ok(Asset) containing the resolved commitment value
• Err(DispatchError) if resolution fails

fn resolve_index_commit( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, index_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, ) -> Result<<Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, DispatchError>

Resolves (withdraws) and finalizes a commitment for a index digest under a given reason.

This function is the base implementation for resolving commitments when the target is an index rather than a direct digest or pool.

It resolves all commit instances tied to a index digest of a reason.

Returns

• Ok(Asset) containing the resolved commitment value
• Err(DispatchError) if resolution fails

fn resolve_pool_commit( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, pool_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, ) -> Result<<Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, DispatchError>

Resolves (withdraws) and finalizes a commitment for a pool digest under a given reason.

This function is the base implementation for resolving commitments when the target is an pool rather than a direct digest or index.

It resolves all commit instances tied to a pool digest of a reason.

Returns

• Ok(Asset) containing the resolved commitment value
• Err(DispatchError) if resolution fails

fn set_total_value( reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, value: <Pallet<T, I> as InspectAsset<Proprietor<T>>>::Asset, )

Sets the total asset value for a given reason.

Use with caution! This is a low-level storage operation that directly updates the reason’s total value without validation.

For safe usage Self::add_to_total_value and Self::sub_from_total_value.

Used internally during deposit and withdrawal operations to maintain accurate aggregate tracking.

This value should not be treated like digest values, rewards/inflation, or penalties/deflation.

fn add_to_total_value( reason: &Pallet::Reason, value: <Pallet as InspectAsset<Proprietor>>::Asset, ) -> DispatchResult

Adds a given asset value to the total value for the specified reason.

fn sub_from_total_value( reason: &Pallet::Reason, value: <Pallet as InspectAsset<Proprietor>>::Asset, ) -> DispatchResult

Subtracts a given asset value from the total value for the specified reason.

impl<T: Config<I>, I: 'static> CommitWithdraw<<T as Config>::AccountId, Pallet<T, I>> for CommitHelpers<T, I>

Implements the CommitWithdraw trait for the pallet

Provides low-level withdraw functionality for digests, indexes, and pools within the commitment system.

fn withdraw_for( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, digest_model: &<Pallet<T, I> as DigestModel<Proprietor<T>>>::Model, variant: &<Pallet<T, I> as CommitVariant<Proprietor<T>>>::Position, ) -> Result<Self::Imbalance, DispatchError>

Withdraws the proprietor’s total committed value for a given digest model and reason.

This function centralizes the dispatches to the appropriate underlying handler depending on the type of the digest model (Direct, Index, or Pool).

Digest models represent different commitment structures:

• Direct: a single digest commitment.
• Index: a grouped commitment of multiple entry digests.
• Pool: a shared resource i.e., a collective single commitment.

Imbalance Semantics

The returned imbalance captures the difference between the original deposit made when the commitment was placed and the value withdrawn at resolution time. Since digests may accrue rewards or penalties over time, the withdrawn amount may differ from the original deposit; this difference is expected and is represented explicitly in the imbalance.

Notes

• Callers are expected to resolve this imbalance probably via CommitBalance::resolve_imbalance
• The caller’s variant is ignored because each commit already defines its own variant during deposit operation.

Returns

• Ok(Imbalance) containing:
  • deposit: the original amount deposited when the commitment was placed.
  • withdraw: the amount withdrawn at resolution time.
• Err(DispatchError) if any underlying withdrawal operation fails.

fn withdraw_from_digest( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, digest: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, _variant: &<Pallet<T, I> as CommitVariant<Proprietor<T>>>::Position, ) -> Result<Self::Imbalance, DispatchError>

Withdraws the committed value for a single direct digest and variant.

This low-level function calculates the real-time effective value for all commit instances associated with this proprietor and digest, then updates the digest’s balance accordingly.

Imbalance Semantics

The returned imbalance captures the difference between the original deposit made when the commitment was placed and the value withdrawn at resolution time. Since digests may accrue rewards or penalties over time, the withdrawn amount may differ from the original deposit; this difference is expected and is represented explicitly in the imbalance.

Notes

• Callers are expected to resolve this imbalance probably via CommitBalance::resolve_imbalance
• The caller’s variant is ignored because each commit already defines its own variant during deposit operation.

Returns

• Ok(Imbalance) containing both the deposited and the withdrawn value
• Err(DispatchError) if the digest or variant is not found

fn withdraw_from_index( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, index_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, _variant: &<Pallet<T, I> as CommitVariant<Proprietor<T>>>::Position, ) -> Result<Self::Imbalance, DispatchError>

Withdraws the committed value for a given index digest.

Iterates over all entries in the index, calculates each entry’s effective withdrawal, and updates entry digest balances while removing commitment records from storage.

Imbalance Semantics

The returned imbalance captures the difference between the original deposit made when the commitment was placed and the value withdrawn at resolution time. Since digests may accrue rewards or penalties over time, the withdrawn amount may differ from the original deposit; this difference is expected and is represented explicitly in the imbalance.

Notes

• Callers are expected to resolve this imbalance probably via CommitBalance::resolve_imbalance
• The caller’s variant is ignored because each commit belongs to an entry already defines its own variant during deposit operation.
• Since an index is an immutable structure-where entry updates result in a new index, no inconsistencies can arise.

Returns

• Ok(Imbalance) representing total withdrawn and deposited values across all entries
• Err(DispatchError) if the index or any entry is not found

fn withdraw_from_pool( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, pool_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, _variant: &<Pallet<T, I> as CommitVariant<Proprietor<T>>>::Position, ) -> Result<Self::Imbalance, DispatchError>

Withdraws the committed value for a pool digest.

The pool balance is released first, then each commitment within the pool is resolved. Withdrawn values are accumulated, pool state is recovered, and commissions are handled (provided to manager internally itself) according to the pool’s configuration.

This low-level operation ensures the proprietor receives their imbalance while also minting, burning, or reallocating tokens due to commission configuration for the manager only.

Returns

• Ok(Imbalance) containing total deposited and withdrawn amounts after commissions
• Err(DispatchError) if the pool is not found or withdrawal fails

impl<T: Config<I>, I: 'static> IndexOps<<T as Config>::AccountId, Pallet<T, I>> for CommitHelpers<T, I>

Implementation of IndexOps for the pallet, defining how index entries are queried, inserted, updated, or removed within a given index digest.

Each function operates on the index-entry composition layer - maintaining relationships between an index digest and its subordinate entry digests.

fn remove_index_entry( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, index_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, entry_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, ) -> Result<<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, DispatchError>

Removes a specific entry from an existing index.

The function retrieves the target index, searches for the specified entry, and removes it if found. The index digest is then re-generated and updated to reflect the new structure as indexes are immutable, changes may create new index digest.

Returns

• Ok(IndexDigest) containing the new index digest after entry removal
• Err(DispatchError) if the operation fails

fn set_index_entry( who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, index_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, entry_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, shares: <Pallet<T, I> as CommitIndex<Proprietor<T>>>::Shares, variant: &<Pallet<T, I> as CommitVariant<Proprietor<T>>>::Position, ) -> Result<<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, DispatchError>

Inserts or updates an entry within a given index. For removing use Self::remove_index_entry instead.

Since indexes are immutable, this operation creates a new index with the modified entry configuration and generates a new digest.

If the entry exists, its shares and variant are updated; otherwise, a new entry is appended.

Returns

• Ok(IndexDigest) containing the new index digest after entry modification
• Err(DispatchError) if the operation fails

impl<T: Config<I>, I: 'static> PoolOps<<T as Config>::AccountId, Pallet<T, I>> for CommitHelpers<T, I>

Implementation of PoolOps for the pallet, defining how pools slots are queried, inserted, updated, or removed within a given index digest.

Each function operates on the pool-slot composition layer - maintaining relationships between an pool digest and its subordinate slot digests.

type PoolBalance = ProductType<T, I, <<T as Config<I>>::BalanceContext as ModelContext>::Context, BalanceAsset, BalanceRational, BalanceTime, BalanceAddon>

Uses LazyBalanceOf to track both the real-time effective balance and the total principal deposits contributed by all proprietors of the pool.

Each proprietor’s deposit (commit) into the pool is recorded as a CommitInstance inside its storage.

fn release_pool( reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, pool_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, ) -> Result<Self::PoolBalance, DispatchError>

Releases a pool’s balance into a detached representation.

Resolves all active slot digests belonging to the pool, withdraws their values proportionally, and resets the pool’s stored balance to default. The released balance can then be modified before being recovered.

Returns

• Ok(Balance) containing the released pool balance
• Err(DispatchError) if the pool is not found or release fails

fn recover_pool( reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, pool_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, balance: &Self::PoolBalance, ) -> DispatchResult

Restores a pool’s state after a prior release.

Redistributes the recovered balance among slots proportionally based on their shares, and reconciles any dust with the pool manager. This function should only be called after release_pool.

Returns

• Ok(()) if the pool state was successfully recovered
• Err(DispatchError) with ReleasePoolToRecover if pool is not in released state, or recovery fails

fn remove_pool_slot( _who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, pool_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, slot_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, ) -> DispatchResult

Removes a specific slot from a given pool.

The function first releases the pool to safely mutate it, ensuring no lazy balance state remains. Once verified, it searches for the specified slot and removes it. The pool’s capital is then adjusted to account for the removed slot’s shares. Finally, the pool state is recovered.

Returns

• Ok(()) if the slot is successfully removed or not found
• Err(DispatchError) if pool or slot state is invalid

fn set_pool_slot( _who: &Proprietor<T>, reason: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Reason, pool_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, slot_of: &<Pallet<T, I> as Commitment<Proprietor<T>>>::Digest, shares: <Pallet<T, I> as CommitIndex<Proprietor<T>>>::Shares, variant: &<Pallet<T, I> as CommitVariant<Proprietor<T>>>::Position, ) -> DispatchResult

Inserts or updates a slot within an existing pool. For removing use Self::remove_pool_slot instead.

The pool is first released for safe modification.
If the slot already exists, it is removed and replaced with the updated one. Capital adjustments are performed based on the delta between old and new share allocations. The pool is then recovered post-mutation.

Returns

• Ok(()) if the slot is successfully set
• Err(DispatchError) if pool is not in released state, if slot capacity exceeded, or operation fails