Crate frame_suite

A composable, type-driven foundation for building modular runtime systems on top of Substrate.

This crate is a collection of orthogonal, interoperable abstractions that capture recurring runtime patterns and execution without prescribing concrete implementations.

The focus is not on providing ready-made systems, but on defining reusable semantics and capabilities that can be composed, extended, and adapted across different contexts.

The design is guided by:

• Type-first abstractions
• Plugin-driven behavior
• Decoupled structure, storage, and execution

The crate is expected to evolve over time, growing as new reusable patterns emerge, while maintaining a consistent approach to abstraction and composition.

How Everything is Designed

The crate follows a consistent design model across all modules:

• Traits define semantics Each module exposes traits that describe what a system means, not how it is implemented.

• Types encode constraints Capabilities, invariants, and relationships are expressed through associated types and bounds, ensuring correctness at compile time.

• Behavior is externalized Logic is not embedded into core structures. Instead, it is provided through pluggable models and context-driven execution.

• Storage is not assumed Data layout and persistence are left to the implementing context, allowing the same abstraction to work across different storage strategies.

• Composition is the mechanism Larger systems emerge by combining small, orthogonal primitives, rather than extending monolithic components.

This results in abstractions that are:

• reusable across domains
• extensible without modification
• adaptable to different runtime environments

Architecture Overview

The crate is organized into domain-oriented modules, each contributing a focused set of traits and primitives. These modules are intentionally loosely coupled and can be used independently or composed together to form higher-level systems.

The crate is organized from

low-level primitives -> structural abstractions -> domain systems -> execution

Core Primitives

• base : Foundational traits for deterministic, codec-safe types
• fixedpoint : Deterministic numeric and fixed-point abstractions
• keys : Deterministic identifier derivation
• mutation : Mutation-centric abstractions over ownership
• misc : Small, reusable building blocks across semantic-boundaries

Structural & Behavioral Core

• virtuals : Type-driven virtual struct system (decoupled structure layer)
• plugins : Pluggable, type-safe execution and behavior layer

Progression & Accumulation

• accumulators : Step-based progression and accumulation models
• xp : Experience points as a pseudo-fungible progression primitive

Value & Financial Semantics

• assets : Lazy, receipt-based accounting models
• commitment : Value bonding and intent-driven primitives

Coordination & Governance

• roles : Role lifecycle, funding, and incentive semantics
• elections : Generic, plugin-based selection and weighting systems
• blockchain : Author lifecycle, rewards, and coordination abstractions

Execution Layer

• routines : Structured Best-effort offchain-workers execution model

Design Principles

Decoupled Concerns

Structure, storage, and behavior are treated as independent dimensions:

• Structure: expressed via traits and type-level schemas
• Storage: abstracted or externalized
• Behavior: injected via pluggable models

This separation allows systems to evolve without forcing redesigns across unrelated layers.

Plugin-Driven Execution

Behavior is modeled as pluggable units of computation, enabling:

• compile-time selection of logic
• context-driven customization
• interchangeable implementations without changing interfaces

Type-Level Composition

The framework encodes meaning through types:

• capabilities and constraints live in trait bounds
• composition emerges from generic relationships
• correctness is enforced at compile time

Lazy & Deferred Semantics

Several modules adopt lazy or deferred evaluation models to:

• minimize unnecessary state updates
• defer computation until it is required
• scale efficiently with system complexity

Hygiene

All public symbols are re-exported at the crate root.

This ensures:

• a flat and ergonomic import surface
• no need to depend on internal module paths
• consistent and predictable naming across the crate

Re-exports

pub use accumulators::*;

pub use assets::*;

pub use base::*;

pub use blockchain::*;

pub use commitment::*;

pub use elections::*;

pub use fixedpoint::*;

pub use forks::*;

pub use keys::*;

pub use misc::*;

pub use mutation::*;

pub use plugins::*;

pub use roles::*;

pub use routines::*;

pub use virtuals::*;

pub use xp::*;

Modules

accumulators

Defines a generic interface for step-based progression systems.

assets

A collection of composable, type-driven balance models built on virtual abstractions and plugin-based execution.

base

Defines the foundational trait system for deterministic, codec-safe, and metadata-aware types used across the runtime.

blockchain

Defines a comprehensive framework for managing authors (validators) in a decentralized network maintaining a distributed, deterministic state machine.

commitment

A composable framework for expressing financial intent as immutable commitments.

elections

Provides generic traits for election management, weight computation, and influence calculation using plugin-based models.

fixedpoint

Deterministic, no_std-compatible mathematical primitives for Substrate’s fixed-point numeric tower ([FixedU64], [FixedU128], [FixedI64], [FixedI128]).

forks

Fork-local utilities for pallet offchain workers (OCWs).

keys

Utilities for deterministic identifier derivation.

misc

Provides small, reusable building blocks that are broadly applicable across pallets and runtime components.

mutation

Mutation-focused abstractions over owned and borrowed values, treating mutability as the primary capability rather than ownership.

plugins

Pluggable, type-safe execution framework for composing runtime behavior via plugin models and families.

roles

Defines a unified abstraction layer for managing role-based logic within a runtime system.

routines

Best-effort execution framework for offchain routines with explicit logging and storage semantics.

virtuals

Virtual struct system mapping discriminants (ZSTs) to behavior via trait-driven schemas.

xp

Defines a interface for managing “Experience Points” (XP) as an abstract economic primitive or a constrained resource.

Macros

__phantom_struct

Generates a zero-sized or PhantomData-backed marker struct.

declare_family

Declares a plugin model family using marker types.

define_family

Declares a concrete plugin family implementation for a given family root.

discriminants

Defines one or more public zero-sized discriminant types.

empty_virtual_extension

Implements an empty virtual extension schema for a given extension.

impl_discriminants

Implements DiscriminantTag for one or more existing types.

plugin_context

Generates a stateless plugin context marker type for a plugin model or a plugin family.

plugin_model

Defines a plugin model in a fully generic, and type-safe way.

plugin_output

Generates a strongly-typed associated function that executes a plugin model and returns its computed output.

plugin_test

Generates table-driven unit tests for plugin models.

plugin_types

Declares associated plugin types inside a trait.