Contract staking-rewards: add reward projection preview and epoch summary accessor

[CMI-James]

Background

Contributors working on staking and loyalty reward flows need lightweight read endpoints that expose reward math context without requiring clients to rebuild epoch-level accounting off-chain.

Feature Focus

Add reward projection and epoch summary accessors to the staking rewards contract.

Where to Implement (Exact Targets)

• contracts/staking-rewards/src/lib.rs
• contracts/staking-rewards/src/storage.rs
• contracts/staking-rewards/src/types.rs
• contracts/staking-rewards/src/test.rs

What to Implement

• Add a view that returns the current reward projection for a staker based on stake amount, epoch state, and accrued but unclaimed rewards.
• Add a summary accessor for active epoch metadata, total distributed rewards, and pending carry-over.
• Ensure returned values are deterministic and safe for frontend polling.
• Keep accessor behavior resilient when no epoch has started yet.

Interface / Endpoint / Method Details

• Expose read-only methods with explicit return types for projection and epoch summary payloads.
• Reuse existing storage keys where possible instead of duplicating aggregate state.
• Document any rounding behavior or zero-value fallback conventions in contract comments and generated docs.

Acceptance Criteria

• Staking UI can fetch both reward preview and epoch summary in one round-trip pattern.
• Accessors do not mutate contract state.
• Empty-state responses are well-defined and tested.

Required Tests

• Unit tests covering active epoch, empty epoch, and partially claimed reward scenarios.
• Assertions for deterministic output ordering and expected numeric conversions.

Definition of Done

• New accessors are implemented, documented, and covered by tests.
• Generated contract docs reflect the new public interface.

[codewithzubair07]

@codewithzubair07 has applied to work on this issue as part of the Stellar Wave Program's 3rd wave.

please assign me this issue

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

[devJaja]

@devJaja has applied to work on this issue as part of the Stellar Wave Program's 3rd wave.

Hello, I am a smart contract and full-stack developer with experience across 30+ blockchain projects, including development within the Stellar ecosystem. I am interested in contributing to this issue and bringing my expertise to support its completion.

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