NormalizedSnapshot is orphaned: the dashboard aggregate documented in history_snapshot.rs is never exposed or used

[usmanimamu17-create]

Problem

src/history_snapshot.rs documents normalize_history() as the way to summarize history "for dashboard telemetry":

/// Summarised view of SLA calculation history.
/// Provides a lightweight aggregate of the full history without exposing
/// individual record details. Suitable for dashboard telemetry.
pub struct NormalizedSnapshot { pub count: u32, pub has_violations: bool, pub has_rewards: bool }

Grep shows normalize_history is called only by its own tests. No contract method returns a NormalizedSnapshot, and the type is not #[contracttype], so it cannot cross the contract boundary at all.

Consequences:

• The documented dashboard path doesn't exist: the module's usage example (let snapshot = normalize_history(&history);) is library-only; a backend dashboard cannot obtain this aggregate from the contract and must re-implement the scan over get_history (which is the expensive full read — companion issue).
• The type is unusable as documented: even if a method were added, NormalizedSnapshot lacks #[contracttype], so it would fail at the host boundary — the same trap ConfigBundle's issue fix: config_bundle.rs type mismatch causes runtime deserialization failure #1 hit.
• The module duplicates knowledge with get_stats: SLAStats already carries cumulative totals; NormalizedSnapshot's booleans (any violations/rewards) overlap with stats but with different semantics (windowed vs. cumulative), and nothing reconciles the two views.

Root cause

The module was authored as a utility alongside the history work and never wired to a contract endpoint or marked #[contracttype].

Why this is architecturally hard

1. Exposing it requires a decision: a #[contracttype] aggregate type + a view method (an ABI addition, stability-guarded) that internally does the full-history scan — reintroducing the read-cost problem — or dropping the module in favor of SLAStats (which the contract already exposes).
2. The "any violation/reward in window" semantics are only meaningful if the window is defined; the module takes the full history with no window parameter, so its dashboard value is unclear.
3. The fix should reconcile this with get_severity_telemetry (which covers per-severity windows) so the dashboard story is one coherent surface.

Acceptance criteria

• NormalizedSnapshot/normalize_history is either exposed as a #[contracttype] view with defined window semantics, or removed with its documentation relocated.
• No docs present a dashboard aggregate that the contract cannot return.
• The relationship to SLAStats/get_severity_telemetry is documented.

Out of scope

The full-history read cost (companion issue) and new telemetry counters.

Getting started

just test

Good first files to read: apexchainx_calculator/src/history_snapshot.rs, apexchainx_calculator/src/lib.rs (get_stats, get_severity_telemetry).

[Muyideen-js]

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

Hi, I can fix this

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

[Oluwasuyi-Oluwatimilehin-Daniel]

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

Hello @maintainer, I’d like to work on this issue. I have experience handling similar tasks and can start immediately. And I will deliver at the shortest possible time.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Oluwasuyi-Oluwatimilehin-Daniel to this issue.

[Ghostcecode]

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

Hi, I've taken the time to go through the requirements and I'm confident I can put together a solution that satisfies the acceptance criteria. I'd be grateful if this could be assigned to me.

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

[doncross03]

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

Assign to me ......I can deliver before stipulated and deadline

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

[divinemike019]

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

Hi! I'd like to contribute to this issue.

I have experience working with Rust/Soroban smart contracts, contract APIs, storage-aware design, and documentation. I'd like to investigate the intended role of NormalizedSnapshot and resolve the current mismatch between the documented dashboard flow and the contract's actual public interface.

My approach will be to:

• Review history_snapshot.rs, SLAStats, get_stats, and get_severity_telemetry to understand the existing semantics and avoid introducing overlapping APIs.
• Trace all current usages of NormalizedSnapshot and normalize_history.
• Determine whether the snapshot provides meaningful information that is not already covered by the existing contract views.
• If it should remain part of the public API, make NormalizedSnapshot a valid #[contracttype], define explicit window semantics, and expose it through an appropriate read-only contract method with focused tests.
• If the existing SLAStats/telemetry surfaces already provide the required functionality, remove the orphaned abstraction and relocate/update its documentation instead.
• Clearly document the relationship between the resulting dashboard surface, SLAStats, and get_severity_telemetry.
• Ensure no documentation claims that an unavailable dashboard aggregate can be retrieved from the contract.
• Add regression tests covering the selected behavior and run the existing Rust/Soroban test and build checks.

I'll keep the change focused on resolving the API/design inconsistency and avoid introducing an unnecessary full-history contract read if the existing telemetry interfaces already provide the appropriate dashboard data.

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

[beulah7717108-eng]

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

HI MAINTAINER
I would love to take on this issue
please assign me

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

[drips-wave]

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

🧑‍💻 @beulah7717108-eng: 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 🌊