frame_plugins/lib.rs
1// SPDX-License-Identifier: MPL-2.0
2//
3// Part of Auguth Labs open-source softwares.
4// Built for the Substrate framework.
5//
6// This Source Code Form is subject to the terms of the Mozilla Public
7// License, v. 2.0. If a copy of the MPL was not distributed with this
8// file, You can obtain one at https://mozilla.org/MPL/2.0/.
9//
10// Copyright (c) 2026 Auguth Labs (OPC) Pvt Ltd, India
11
12#![cfg_attr(not(feature = "std"), no_std)]
13// ===============================================================================
14// ````````````````````````````````` FRAME PLUGINS `````````````````````````````````
15// ===============================================================================
16
17//! A plugin registry system built on top of [`frame_suite`], providing
18//! concrete, reusable implementations of plugin-driven behavior.
19//!
20//! This crate does not define new abstractions. Instead, it **realizes**
21//! the semantics defined in `frame_suite` by supplying **ready-to-use
22//! plugin models and families** that can be anchored into Substrate runtime systems.
23//!
24//! Where `frame_suite` defines *what is possible*, this crate provides
25//! examples of *how those possibilities can be instantiated*.
26//!
27//! ## Design
28//!
29//! The crate follows the same design principles as `frame_suite` and is
30//! implemented using the [`frame_suite::plugins`] macro system:
31//!
32//! - **Plugins are units of behavior**
33//! Each model represents a single, well-defined transformation or operation,
34//! defined via [`plugin_model!`](frame_suite::plugin_model).
35//!
36//! - **Families compose behavior**
37//! Related operations are grouped into plugin families using
38//! [`define_family!`](frame_suite::define_family), forming cohesive execution
39//! surfaces for higher-level systems.
40//!
41//! - **Context drives execution**
42//! Models may depend on external configuration or environment via context,
43//! enabling flexible and runtime-specific behavior.
44//!
45//! - **No assumptions beyond the contract**
46//! All implementations adhere strictly to the trait contracts defined in
47//! `frame_suite`, without introducing hidden coupling.
48//!
49//! ## Module Overview
50//!
51//! The crate is organized into **domain categories of plugin sets**, each targeting
52//! a specific class of abstractions from `frame_suite`.
53//!
54//! ### Value & Accounting
55//!
56//! - [`balances`] : Lazy balance plugin families and models
57//!
58//! ### Coordination & Selection
59//!
60//! - [`elections`] : Election algorithms (flat, fair, and beyond)
61//!
62//! ### Influence & Weighting
63//!
64//! - [`influence`] : Influence (Quantifiable Power) transformation models
65//!
66//! ### Rewards & Distribution
67//!
68//! - [`rewards`] : Reward computation (`payout`) and distribution (`payee`) models
69//!
70//! ### Penalty & Normalization
71//!
72//! - [`penalty`] : Penalty normalization and bounding models
73//!
74//! ## Design Intent
75//!
76//! This crate acts as a **behavior layer** over `frame_suite`:
77//!
78//! - it demonstrates how abstractions can be implemented
79//! - it provides reusable building blocks for common patterns
80//! - it avoids locking systems into a single interpretation
81//!
82//! New models can be added freely as long as they:
83//!
84//! - respect the underlying trait contracts
85//! - remain composable and independent
86//! - do not introduce unnecessary coupling
87//!
88//! ## Hygiene
89//!
90//! All public symbols are **re-exported at the crate root**.
91//!
92//! This ensures:
93//!
94//! - a flat and ergonomic import surface
95//! - no need to depend on internal module paths
96//! - consistent and predictable naming across the crate
97
98// ===============================================================================
99// ``````````````````````````````````` MODULES ```````````````````````````````````
100// ===============================================================================
101
102pub mod balances;
103pub mod elections;
104pub mod influence;
105pub mod penalty;
106pub mod rewards;
107
108// ===============================================================================
109// `````````````````````````````````` RE-EXPORTS `````````````````````````````````
110// ===============================================================================
111
112pub use balances::*;
113pub use elections::*;
114pub use influence::*;
115pub use penalty::*;
116pub use rewards::*;