Module penalty

Provides a suite of pluggable penalty models used to transform, normalize, and constrain penalty values associated with entities.

These models are designed to operate as post-processing layers in governance, reputation, and scoring systems, ensuring that penalties remain bounded, fair, and resistant to extreme values.

Design Philosophy

Raw penalty values (e.g., slashing amounts, negative scores, or risk weights) can often be:

• Unbounded: leading to disproportionate punishment
• Noisy: zero or insignificant values
• Inconsistent: varying widely across participants

Penalty models provide a structured way to:

• Cap excessive penalties to prevent extreme outcomes
• Enforce minimum penalties to avoid negligible punishments
• Normalize distributions for fair comparison across entities
• Filter irrelevant values (e.g., zero penalties)

By transforming raw penalties into controlled and comparable values, these plugins ensure stable and predictable behavior in downstream systems.

Core Concepts

• Input (p): A penalty value associated with an entity.
• Output (f(p)): The transformed penalty after applying constraints.
• Penalty List: A collection of (Id, Penalty) pairs.
• Context: Optional configuration defining bounds (e.g., threshold, floor, cap).

Applications

• Governance systems: Slashing, penalties, or reputation decay
• Reputation engines: Penalizing malicious or low-quality behavior
• Scoring systems: Normalizing negative contributions
• Risk models: Bounding downside exposure

Structs

CappedPenalty

Applies a bounded range constraint to penalties.

CappedPenaltyConfig

Configuration for CappedPenalty plugin.

ThresholdPenalty

Applies an upper threshold cap to penalties.

ThresholdPenaltyConfig

Configuration for ThresholdPenalty plugin.