pallet‑commitment
Raw balance locks are blunt instruments. Commitment gives assets meaning - bonded to a reason, anchored to a digest, adjusted dynamically, and resolved with full accounting fidelity.
Polkadot SDKSubstrateFRAMEBond with Purpose. Resolve with Precision.
The only commitment primitive your runtime will ever need.
Commitment Lifecycle
A commitment travels through a well-defined lifecycle - from pre-reservation through active bonding, lazy adjustment, and final resolution with explicit imbalance handling.
Funds are moved from the proprietor's free balance into the PrepareForCommit hold - a reusable reserve shared across commitment operations. The reserved balance can be consumed by any consumer pallet using this commitment instance.
A commitment is created under a (reason, digest) pair. The digest defines how value is applied - Direct, Index, or Pool. A VirtualReceipt is issued as a claim over the committed value.
Existing commitments can be increased by adding additional value under the same (proprietor, reason, digest) scope. Each increase creates a new CommitInstance while preserving independent resolution history.
The digest state changes through lazy balance operations.Mint increases value for rewards, while Reap reduces value for penalties. Existing commitments automatically reflect the updated digest state during resolution.
A commitment is evaluated using its VirtualReceipt against the current digest state. The final resolved value includes all previous digest-level adjustments, with any difference handled through explicit imbalance reconciliation.
The proprietor receives the final settled amount after resolution. The outcome reflects every mint, reap, and redistribution applied since placement - it may be more, less, or equal to the original deposit. The VirtualReceipt is consumed and the economic position closes.
The Three Models
Choose the right commitment model for your use case. Each model represents a different level of structure, delegation, and value distribution.
Direct
- One proprietor bonded straight to a single digest under a given reason - no intermediaries, no delegation.
- Optional position variants (Long / Short, Affirmative / Contrary) per digest with independent lazy balances.
- Ideal for escrow, collateral, single-target staking, and any direct one-to-one bonding use case.
Index
- Commit once to an index - value fans out proportionally across all entries by share weight automatically.
- Fully permissionless and unmanaged. No manager required; share weights define the distribution.
- Ideal for nomination baskets, delegation spreads, and multi-target proportional bonding.
Pool
- A manager controls slot allocation and rebalances dynamically - earning commission on resolution.
- Non-custodial architecture: the manager steers the pool without ever holding user funds.
- Ideal for staking pools, yield vaults, and any managed delegation with dynamic rebalancing.
Key Features
Everything you need to build structured, adjustable, and resolvable asset bonding into your runtime - without writing the infrastructure from scratch.
Reusable Bonding Primitive
One pallet, shared across your entire runtime. Staking, escrow, governance, and pools all bond through the same infrastructure, eliminating duplicated locking logic across pallets.
Semantic Structure
Assets are bound under a reason and a digest, giving every commitment purposeful identity. No more raw opaque locks - every bond carries context.
Dynamic Value Adjustment
Digest-level rewards and penalties are applied lazily; value adjustments propagate to all committed proprietors without requiring eager recalculation on every block.
Three Commitment Models
Choose from Direct, Index, or Pool commitment models - each with progressive levels of grouping, delegation, and management built in out of the box.
Positional Variants
Long/short, affirmative/contrary, positive/negative - commitments can carry a semantic position, enabling directional staking, prediction markets, and multi-sided governance.
Fungible-Agnostic
Works with any asset implementing the Substrate fungible traits, no coupling to a specific token. Plug into your runtime's existing asset infrastructure without modification.
Lazy Balance Engine
Values stored as virtual types - materialised only at the moment of resolution. Zero per-block computation. Fully pluggable balance semantics via a runtime-supplied plugin family.
Virtual Types
"I hold state, not value. Every adjustment reaches the holder lazily - precisely at the moment of truth."
VirtualBalance
Live lazy accumulator at the digest level. Acts as the shared source of truth for every receipt bound to that digest. Never recomputed per block - queried only on demand.
VirtualReceipt
Issued at commit time. Acts like a claim ticket - it carries no concrete amount, only a reference. When redeemed at resolution, it reflects every mint and reap since deposit.
VirtualSnapshot
A point-in-time capture of the balance state. Used for proportional and time-weighted calculations - enabling fair distribution across receipts committed at different moments.
Plugin Dispatch
"The pallet does not know the math. It only speaks LazyInput - the BalanceFamily answers in LazyOutput."
BalanceFamily
The runtime-supplied plugin anchor. Defines the complete semantics of every balance operation - deposit, mint, reap, withdraw. Swappable without touching any commitment logic.
LazyInput
Tagged operation carrier. Each call is wrapped into a typed input - discriminated by a root tag - and dispatched into the plugin family for execution.
LazyOutput
Result boundary returned by the plugin. Carries computed values, issued receipts, or explicit error outcomes. No silent failures - every result is typed and handled.
Lazy Operations
"Four operations. One promise - your balance is always right when you need it, never computed when you don't."
Deposit
The entry operation. Accepts value into the VirtualBalance and returns a VirtualReceipt - the immutable claim ticket stored alongside the CommitInfo.
Mint
Grows the digest VirtualBalance - distributing rewards to all receipt holders proportionally. No per-receipt update. Every holder benefits lazily at withdrawal time.
Reap
Shrinks the digest VirtualBalance - penalising all holders proportionally. Returns an explicit imbalance to the caller. No silent burns - full accounting.
Withdraw
The exit operation. Redeems the VirtualReceipt against the current digest state. The final value is materialised here - reflecting every mint and reap since deposit.
Zero Per-Block Cost
No eager recomputation. Balances materialise only at the moment of resolution - keeping runtime overhead minimal.
Fully Pluggable
The runtime supplies a BalanceFamily plugin defining all balance semantics - swap it without touching any commitment logic.
Explicit Imbalance
Every reap returns an explicit imbalance to the caller - no silent mints or burns. Full accounting fidelity on every resolution.
Use Cases
pallet-commitment is not built for one use case. Any runtime need that requires structured, adjustable, and resolvable asset bonding fits naturally - from staking to escrow to prediction markets.
Staking
- Bond stake under a staking reason. Direct model for validators, Index for nominators.
- Era rewards lazily minted into the digest - distributed proportionally to all receipts at resolution.
Governance
- Commit voting power with Affirmative / Contrary position variants per proposal digest.
- Reward correct predictions via mint. Slash manipulation via reap on resolution.
Staking Pools
- Manager rebalances slots across validators non-custodially. Commission collected on resolution.
- Delegators commit once to the pool - rewards fan out automatically through digest adjustments.
Escrow
- Bond under a contract digest. Release on condition fulfilment. Slash on breach via reap.
- Explicit imbalance returned to the consumer pallet - no silent mint or burn ever.
Bonds
- Issue structured on-chain bonds backed by committed assets under a reason and digest.
- Adjust coupon value via mint, handle defaults via reap - all resolved with full accounting.
Prediction Markets
- Long / Short variants on market digests. Participants commit to positions against an oracle.
- Oracle settlement mints the winning side - losing side is reaped proportionally on resolve.
Ready to Build
pallet-commitment ships with full documentation, a pre-configured runtime template, and example pallets - everything you need to drop it into your Substrate runtime today.
- Reusable by designOne pallet, shared across every consumer in your runtime.
- Three commitment modelsDirect, Index, and Pool - each with progressive levels of structure.
- No std assumptions
no_std + WASMcompatible out of the box. - Lazy evaluationZero per-block recomputation - balances materialise on demand.
- Fully on-chainNo oracles, no bridges. Pure on-chain commitment logic.
Ready to build with pallet-commitment?
Pre-configured template & runtime, example pallet, and full documentation included.
- Fungible-agnosticWorks with any asset implementing Substrate fungible traits.
- Positional variantsLong/Short, Affirmative/Contrary - semantic positions per digest.
- Explicit imbalanceEvery reap returns an imbalance. No silent mint or burn, ever.
- Pluggable balance modelSwap the BalanceFamily plugin without touching commitment logic.
- Multiple instancesInstantiate independently per use case via
I: 'static.
Ready to Build
pallet-commitment ships with full documentation, a pre-configured runtime template, and example pallets - everything you need to drop it into your Substrate runtime today.
- Reusable by designOne pallet, shared across every consumer in your runtime.
- Three commitment modelsDirect, Index, and Pool - each with progressive levels of structure.
- No std assumptions
no_std + WASMcompatible out of the box. - Lazy evaluationZero per-block recomputation - balances materialise on demand.
- Fully on-chainNo oracles, no bridges. Pure on-chain commitment logic.
- Fungible-agnosticWorks with any asset implementing Substrate fungible traits.
- Positional variantsLong/Short, Affirmative/Contrary - semantic positions per digest.
- Explicit imbalanceEvery reap returns an imbalance. No silent mint or burn, ever.
- Pluggable balance modelSwap the BalanceFamily plugin without touching commitment logic.
- Multiple instancesInstantiate independently per use case via
I: 'static.
Ready to build with pallet-commitment?
Pre-configured template & runtime, example pallet, and full documentation included.
Ready to Build
pallet-commitment ships with full documentation, a pre-configured runtime template, and example pallets.
- Reusable by designOne pallet, shared across every consumer in your runtime.
- Three commitment modelsDirect, Index, and Pool - each with progressive levels of structure.
- No std assumptions
no_std + WASMcompatible out of the box. - Lazy evaluationZero per-block recomputation - balances materialise on demand.
- Fully on-chainNo oracles, no bridges. Pure on-chain commitment logic.
Ready to build with pallet-commitment?
Pre-configured template & runtime, example pallet, and full documentation included.
- Fungible-agnosticWorks with any asset implementing Substrate fungible traits.
- Positional variantsLong/Short, Affirmative/Contrary - semantic positions per digest.
- Explicit imbalanceEvery reap returns an imbalance. No silent mint or burn, ever.
- Pluggable balance modelSwap the BalanceFamily plugin without touching commitment logic.
- Multiple instancesInstantiate independently per use case via
I: 'static.
Need Help? We're here.
Ask questions, report bugs, share ideas. Pick the channel that works best for you.
GitHub Issues
Found a bug or have a feature request? Open an issue and we'll take a look.
GitHub Discussions
General questions, ideas, and RFC proposals. Start or join a conversation.
Substrate Stack Exchange
Technical Q&A for Substrate and FRAME developers. Best for specific how-to questions.
Telegram
Quick questions and community chat. Join the group and say hi.
Matrix
Decentralised chat for the Substrate ecosystem. Find us in the Auguth Labs room.
Twitter / X
Follow for updates, announcements and ecosystem news.
GitHub Issues
Found a bug or have a feature request? Open an issue and we'll take a look.
GitHub Discussions
General questions, ideas, and RFC proposals. Start or join a conversation.
Substrate Stack Exchange
Technical Q&A for Substrate and FRAME developers. Best for specific how-to questions.
Telegram
Quick questions and community chat. Join the group and say hi.
Matrix
Decentralised chat for the Substrate ecosystem. Find us in the Auguth Labs room.
Twitter / X
Follow for updates, announcements and ecosystem news.