Add tax-bucket per-holder statement summarizing amounts across each fiscal year

[greatest0fallt1me]

Description

Holders and their accountants need a year-end summary broken down by tax bucket. Expose get_holder_tax_year(offering_id, holder, year) returning the totals per bucket.

Requirements and context

• Must be secure, tested, and documented
• Should be efficient and easy to review
• Relevant code: src/lib.rs
• Statement must be deterministic across reruns

Suggested execution

• Fork the repo and create a branch
• git checkout -b feat/tax-year-statement
• Implement changes
  • Define fiscal-year boundaries as configurable per offering
  • Walk emitted tax_bucket events and aggregate
  • Return structured record with ordinary, capital, and return-of-capital totals
• Validate security and correctness assumptions

Test and commit

• Run tests
  • cargo test --all
• Cover edge cases
  • Year boundary at exact epoch second and multi-year holder
• Include test output and security notes

Example commit message

feat: add per-holder tax-year statement

Guidelines

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

[Glam26]

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

Hi! I'm interested in working on this.

I'll begin by reviewing the affected modules to understand the existing control flow, state transitions, and any external dependencies involved. After identifying the appropriate integration point, I'll implement the requested functionality while preserving existing contracts and minimizing behavioral regressions. I'll also expand the test coverage to include success paths, failure scenarios, and relevant edge cases, then validate the implementation against the project's linting, testing, and build pipeline before submitting a PR.

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

[grantfox-oss]

🦊 GrantFox — @Glam26 has been assigned to this issue!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #534)
2. Your PR will be reviewed by the RevoraOrg maintainers

Good luck! Track your progress on GrantFox.

[drips-wave]

Congratulations, @Glam26! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on July 30, 2026.

🧑‍💻 @Glam26: 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!

@Glam26's PR #719 was approved and merged by @thlpkee20-wq.

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

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