Add dividend accrual ledger so unclaimed revenue compounds per-holder until claim

[Jagadeeshftw]

Summary

Add dividend accrual ledger so unclaimed revenue compounds per-holder until claim

Why this matters

Today, unclaimed revenue sits in the contract without per-holder accrual state. Introduce an accrual ledger that records pending dividend per holder after each report_revenue so partial claims and re-claims compute against an immutable accrual baseline rather than rederiving from periods every time.

Scope

Implement the requested behavior across Revora-Contracts/src/lib.rs. The solution must preserve existing compatibility, authorization, and production safeguards.

Priority

High

Acceptance criteria

• The requested behavior is implemented across Revora-Contracts/src/lib.rs with a clear, reviewable contract.
• Security, authorization, validation, and data-integrity requirements in the repository context are enforced and covered by tests.
• Failure, retry, timeout, concurrency, and boundary behavior is explicit and produces safe, diagnosable outcomes where applicable.
• Regression coverage includes empty, invalid, duplicate, and boundary inputs relevant to this flow.
• Existing API, storage, and deployment compatibility is preserved unless a migration is explicitly documented.

Validation

Include focused tests for:

• happy paths;
• invalid input and authorization boundaries;
• concurrency, retries, or failure recovery;
• backward compatibility;
• relevant integration or contract behavior.

The implementation must pass the repository’s existing build, lint, test, and formatting checks (use cargo test --all where applicable).

Non-goals

• Typo-only, formatting-only, or documentation-only changes.
• Unrelated refactors or dependency upgrades.
• Weakening security, authorization, CI, or production safeguards.
• Changing public behavior outside this issue’s scope.

Contributor application

Before implementation, comment with:

1. relevant experience;
2. a concise implementation approach;
3. expected files or modules affected;
4. an estimate for opening the first PR.

Wait for maintainer assignment before coding.

PR requirements

Use a feature branch and include Closes #.

The PR must:

• address every acceptance criterion;
• link each criterion to code and tests;
• explain security and failure-mode handling;
• include meaningful regression coverage;
• document compatibility or migration considerations;
• pass the repository checks.

Reward-readiness

This is a substantive quality issue. Merge status does not guarantee reward eligibility; final evaluation is determined separately.

Implementation context

Description

Today, unclaimed revenue sits in the contract without per-holder accrual state. Introduce an accrual ledger that records pending dividend per holder after each report_revenue so partial claims and re-claims compute against an immutable accrual baseline rather than rederiving from periods every time.

Requirements and context

• Must be secure, tested, and documented
• Should be efficient and easy to review
• Relevant code: Revora-Contracts/src/lib.rs
• Accrual updates must be O(1) per holder at report time using a global index pattern

Suggested execution

• Fork the repo and create a branch
• git checkout -b feat/dividend-accrual-ledger
• Implement changes
  • Track global_acc_per_share_e18: i128 updated on each report_revenue
  • Store per-holder (last_acc_per_share, accrued_owed) and settle on claim
  • Emit acc_upd events for indexer reconciliation
• Validate security and correctness assumptions

Test and commit

• Run tests
  • cargo test --all
• Cover edge cases
  • Holder share changes mid-period: claim must reflect pre-change accrual only
• Include test output and security notes

Example commit message

feat: add per-holder dividend accrual ledger with global index

Guidelines

• Minimum 95 percent test coverage
• Clear documentation
• Timeframe: 96 hours

[praizeD10]

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

Hi, I’d love to take on this issue! With my expertise in Rust, Stellar, and smart contract development, I can implement a clean and efficient solution.

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

[drips-wave]

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

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

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox!

@praizeD10's PR #864 was approved and merged by @thlpkee20-wq.

🏆 @praizeD10: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (939 total points). Track your full progress on GrantFox.

👏 Great work, @praizeD10! Keep contributing to RevoraOrg.