Implement overpayment review guard conditions

[edehvictor]

Summary

Add contract states for flagging suspected payroll overpayment without enabling unsafe unilateral fund clawback.

Why This Matters

Overpayment handling needs accountability, but payroll systems should avoid giving admins a dangerous hidden reversal switch.

Suggested Files

• contracts/src/reviews.rs
• contracts/src/payroll.rs
• contracts/src/events.rs
• contracts/tests/overpayment_review.rs

Tasks

• Define overpayment review records linked to a payroll run.
• Block archival while a review is open.
• Require explicit resolution reason before closing review.
• Add tests proving settlement is not silently reversed.

Acceptance Criteria

• Overpayment reviews can pause cleanup without reversing settled payments.
• Review closure requires authorized role and reason.
• Events are privacy-safe.
• Tests cover open, resolve, and unauthorized paths.

Coordination

Join the Telegram channel for proper coordination: https://t.me/zkpayroll

[Kingsilva36]

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

I would love to work on this professionally, please assign it to me

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

[TheHalalHunter]

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

Hi maintainer
I’d love to help out with this issue. I’ve checked the current codebase/documentation and know exactly what needs to be updated to make this clearer. I will ensure everything aligns perfectly with your existing contribution guidelines.08:38

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

[MRTEEworld02]

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

Hello, I can work on this if assigned to me

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

[Richardkingz2019]

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

I would love to work on this issue

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

[drips-wave]

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

🧑‍💻 @TheHalalHunter: 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 as part of the Third Campaign campaign!

@TheHalalHunter's PR #395 was approved and merged by @edehvictor.

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

👏 Great work, @TheHalalHunter! Keep contributing to zkpayroll.

[drips-wave]

This issue has been marked as completed by a Drips Wave moderator for @TheHalalHunter as part of the Stellar Wave Program's 8th Wave 🥳

Moderator's reason: [Auto-assessed] The PR was accepted and merged by the repository maintainer (@edehvictor on 2026-08-28T11:30:42Z). The code changes comprehensively implement overpayment review guards and accompanying tests in the zk-payroll-contracts repository as requested in issue #357.

😎 @TheHalalHunter: 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.

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

ℹ️ Note: This issue was marked complete via moderation. Points were issued even though the GitHub issue remains open.