Skip to content

get_economic_exposure totals use saturating_add with no signal: unlike increment_stats, exposure overflow caps silently #481

Closed
#548
Closed
get_economic_exposure totals use saturating_add with no signal: unlike increment_stats, exposure overflow caps silently#481
#548
Assignees
DevMuhdishaq
Labels
GrantFox OSSIssue tracked in GrantFox OSSMaybe RewardedIssue may be eligible for a GrantFox rewardStellar WaveIssues in the Stellar wave programThird CampaignCampaign: Third Campaignarea/apiImported campaign issue labelpriority/mediumImported campaign issue label

Description

@usmanimamu17-create
usmanimamu17-create
opened on Aug 24, 2026

Problem

get_economic_exposure (src/lib.rs) aggregates totals with silent saturation:

total_max_reward = total_max_reward.saturating_add(max_reward);
total_penalty_per_minute = total_penalty_per_minute.saturating_add(penalty_rate);

The running stats path (increment_stats) went to lengths to surface saturation — checked_add + stats_sat events (SC-W5-047) — but the exposure view caps at i128::MAX with no signal.

Consequences:

  • The exposure view can under-report with no indication: with four canonical severities plus custom entries (if the companion issue lands), sums near i128::MAX clamp silently; a dashboard reading total_max_reward == i128::MAX cannot tell whether that is a real configured total or a saturation artifact.
  • The two aggregation paths set different precedents: increment_stats treats saturation as reportable (event, capped value), get_economic_exposure treats it as invisible — a consumer that learned the stats convention will not expect the view to lie silently.
  • The view is read-only and stateless: it cannot emit events, so the fix must either avoid saturation (e.g. return an error) or expose the saturation state in the response.

Root cause

The view was written with saturating_add as a cheap overflow guard, predating the stats_sat convention; the two paths were never reconciled.

Why this is architecturally hard

  1. The response types (EconomicExposure, SeverityExposure) are #[contracttype] and stability-guarded; adding a saturated: bool field is additive but requires the guardrail update (companion issue).
  2. Returning an error on overflow changes the endpoint's contract (read-only views are expected to succeed); the design decision is signal-in-response vs. error.
  3. In practice the configured bounds (reward_base ≤ 100,000, four severities) make overflow unreachable today — so the issue is about correctness-by-construction: either document the unreachability or make the math checked so a future bound change cannot silently corrupt totals.

Acceptance criteria

  • Exposure totals cannot silently cap (checked math with a defined signal, or documented unreachability with an assertion).
  • The behavior is consistent with the stats_sat convention or explicitly divergent with rationale.
  • Tests cover the extreme-configuration case.

Out of scope

The custom-severity omission in the view (companion issue in batch 06) and the reward-tier boundary tests.

Getting started

just test

Good first files to read: apexchainx_calculator/src/lib.rs (get_economic_exposure, increment_stats).

Activity

  1. usmanimamu17-create
    added
    Maybe RewardedIssue may be eligible for a GrantFox reward
    GrantFox OSSIssue tracked in GrantFox OSS
    Third CampaignCampaign: Third Campaign
    priority/mediumImported campaign issue label
    area/apiImported campaign issue label
    on Aug 24, 2026

  2. safal207 commented on Aug 27, 2026

    @safal207
    safal207
    on Aug 27, 2026

    One API-design question before I start: would you prefer a new typed "ExposureOverflow" error, preserving the current "EconomicExposure" response shape, or an additive "saturated: bool" field, keeping the view non-failing?

    I checked the current "main": "get_economic_exposure" silently clamps at two independent layers—per-severity arithmetic via "unwrap_or(i128::MAX)", then aggregate totals via "saturating_add". A regression test should cover both paths; otherwise a per-severity overflow may already look like a valid maximum before aggregation.

    I can take this on with:

    • an extreme-configuration test reproducing both silent clamp paths;
    • checked arithmetic and the maintainers’ preferred explicit overflow signal;
    • only the required stability/error-catalog updates;
    • verification that normal bounded configurations remain unchanged, followed by the full "just test" suite.

    Relevant completed work: merged "StreamPay #161" (Streampay-Org/StreamPay-Contracts#161) and "CommitLabs #556" (Commitlabs-Org/Commitlabs-Contracts#556), both focused on deterministic invariants and failure boundaries.

    If this approach matches the intended compatibility policy, please assign me. I can open a focused PR within 24 hours after the design choice is confirmed and will wait for assignment before changing production code.

  3. drips-wave
    added
    Stellar WaveIssues in the Stellar wave program
    on Aug 30, 2026

  4. abdulquadri123 commented on Aug 30, 2026

    @abdulquadri123
    abdulquadri123
    on Aug 30, 2026 – with Drips Wave

    @abdulquadri123 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

    Hey Maintainer,
    As a blockchain developer, I will delighted to handle this issue and solve it diligently once assigned to me.
    Thanks.

    ℹ️ Repo Maintainers: To accept this application, review their application or assign @abdulquadri123 to this issue.

  5. AGWAM001 commented on Aug 30, 2026

    @AGWAM001
    AGWAM001
    on Aug 30, 2026 – with Drips Wave

    @AGWAM001 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

    I'd love to take this issue on. I'm a full-stack developer with experience across Drips Waves4-7.
    My stack include rust, Soroban, Solidity, and TypeScript. I can deliver a clean, tested, and well-documented solution within 5 hours of assignment.
    Jovial to start immediately

    ℹ️ Repo Maintainers: To accept this application, review their application or assign @AGWAM001 to this issue.

  6. Abulbayty commented on Aug 30, 2026

    @Abulbayty
    Abulbayty
    on Aug 30, 2026 – with Drips Wave

    @Abulbayty has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

    I’ve carefully reviewed the requirements and I’m confident in my ability to address this issue effectively and submit a quality PR within 24 hours.

    ℹ️ Repo Maintainers: To accept this application, review their application or assign @Abulbayty to this issue.

  7. poaspergillus commented on Aug 30, 2026

    @poaspergillus
    poaspergillus
    on Aug 30, 2026 – with Drips Wave

    @poaspergillus has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

    I can take this one I can fix the exposure overflow handling and add the extreme case test

    ℹ️ Repo Maintainers: To accept this application, review their application or assign @poaspergillus to this issue.

  8. DevMuhdishaq commented on Aug 30, 2026

    @DevMuhdishaq
    DevMuhdishaq
    on Aug 30, 2026 – with Drips Wave

    @DevMuhdishaq has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

    Hi Maintainer,

    I’m a full-stack developer, and I’d like to contribute to the task. I’ll implement it carefully and efficiently thoroughly understand requirements and edge cases
    Communicate promptly about suggestions or improvements. And I will provide regular progress updates and address blockers
    Align with project goals through feedback and clarification.

    Thank you,

    ℹ️ Repo Maintainers: To accept this application, review their application or assign @DevMuhdishaq to this issue.

  9. chainsmt commented on Aug 30, 2026

    @chainsmt
    chainsmt
    on Aug 30, 2026 – with Drips Wave

    @chainsmt has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

    Hi maintainer, can I work on this issue?

    ℹ️ Repo Maintainers: To accept this application, review their application or assign @chainsmt to this issue.

  10. usmanimamu17-create
    assigned
    DevMuhdishaq
    on Aug 30, 2026

  11. drips-wave commented on Aug 30, 2026

    @drips-wave
    drips-waveBot
    on Aug 30, 2026 – with Drips Wave

    Congratulations, @DevMuhdishaq! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

    🧑‍💻 @DevMuhdishaq: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

    Warning

    When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

    🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

    🌊 Happy Wave 🌊

  12. usmanimamu17-create
    closed this as completedin #548on Aug 31, 2026

  13. grantfox-oss commented on Aug 31, 2026

    @grantfox-oss
    grantfox-ossBot
    on Aug 31, 2026 – with GrantFox OSS

    🎉 This issue has been marked as completed on GrantFox!

    @DevMuhdishaq's PR #548 was approved and merged by @usmanimamu17-create.

    🏆 @DevMuhdishaq: You earned 40 FoxPoints for this contribution! Your current tier: Builder (1,225 total points). Track your full progress on GrantFox.

    👏 Great work, @DevMuhdishaq! Keep contributing to ApexChainx.

  14. drips-wave commented on Aug 31, 2026

    @drips-wave
    drips-waveBot
    on Aug 31, 2026 – with Drips Wave

    This issue has been completed by @DevMuhdishaq as part of the Stellar Wave Program's 8th Wave 🥳

    😎 @DevMuhdishaq: You earned 200 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

    🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

GrantFox OSSIssue tracked in GrantFox OSSMaybe RewardedIssue may be eligible for a GrantFox rewardStellar WaveIssues in the Stellar wave programThird CampaignCampaign: Third Campaignarea/apiImported campaign issue labelpriority/mediumImported campaign issue label

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions