Struct SigmoidPayout

pub struct SigmoidPayout;

The SigmoidPayout model computes rewards using a logistic (S-shaped) function, producing slow start, rapid growth, and eventual saturation.

Concept: S-Curve Reward Transformation

Formula

f(x) = L / (1 + e^(-k*(x - x0)))

where k and x0 are derived from growth_start (a) and growth_end (b):

k  = logit(b) - logit(a)    (always > 0 when b > a, both in (0, 1))
x0 = -logit(a) / k          (midpoint; > 0 when a < 0.5)

Signed Arithmetic

Even when Asset and FixedPoint are unsigned types, several intermediate values are inherently signed:

• logit(a) < 0 for any a < 0.5.
• x - x0 < 0 for any x < x0 (the entire left half of the curve).
• -k*(x - x0) < 0 for any x > x0 (the entire right half).

All of these are computed in a concrete FixedI128 workspace via FixedSignedCast, then the final result (always >= 0) is projected back. This makes the model correct for both signed and unsigned types with no Neg bound on FixedPoint.

Guard Conditions (returns zero)

• growth_start <= 0 or growth_start >= 1.
• growth_end <= 0 or growth_end >= 1.
• k == 0 (degenerate; only when growth_start == growth_end).

Precision Note

Fixed-point arithmetic accumulates small rounding errors across the ln -> k -> x0 -> exp chain. In practice the output may be one integer unit below the analytically exact value at certain inputs. This is expected and inconsequential for integer rewards.

Characteristics:

• Bounded: Reward never exceeds max_reward.
• Smooth growth: Gradual ramp-up instead of abrupt changes.
• Works with unsigned types: No Neg bound; negation in FixedI128.
• Deterministic: Same input and parameters yield identical results.
• Context-driven: Controlled via SigmoidPayoutConfig.

Applications:

• Adoption-based reward curves.
• Incentive ramp-up systems.
• Gradual onboarding rewards.
• Supply emission with saturation.

Example

let config = SigmoidPayoutConfig {
    max_reward:   100u128,
    growth_start: FixedU128::saturating_from_rational(1, 10), // 0.1
    growth_end:   FixedU128::saturating_from_rational(9, 10), // 0.9
};
// k ~= 4.394, x0 ~= 0.5
// f(0) = 10  (= growth_start * L, lower tail)
// f(1) = 89  (= growth_end * L, upper tail, rounded down)
assert_eq!(SigmoidPayout::compute(0u128, Some(config)), 10);
assert_eq!(SigmoidPayout::compute(1u128, Some(config)), 89);

Trait Implementations

impl Debug for SigmoidPayout

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SigmoidPayout

fn default() -> SigmoidPayout

Returns the “default value” for a type.

impl<FixedPoint, Asset> PurePluginModel<Asset, SigmoidPayoutConfig<Asset, FixedPoint>, Asset> for SigmoidPayout

where Asset: Copy + IntegerToFixed + FixedForInteger<FixedPoint = FixedPoint> + Zero, FixedPoint: FixedPointNumber + FixedSignedCast<Signed = FixedI128>,

fn compute( &self, x: Asset, context: &SigmoidPayoutConfig<Asset, FixedPoint>, ) -> Asset

Computes the model’s output for a given immutable input and context.