Implement on-chain payer blacklist with appeal period

[Kingsman-99]

Description

Contract admins have no mechanism to block bad actors (sanctioned addresses, fraudulent payers) from interacting with any invoice. This issue adds an admin-managed payer blacklist with a built-in appeal window during which a blacklisted address can submit an appeal hash and admins can review before the ban is finalised.

Technical Context

Add blacklist_key(payer: Address) -> Symbol storing BlacklistEntry { banned_at: u64, appeal_hash: Option<BytesN<32>>, finalised: bool } in types.rs and lib.rs. Admin calls blacklist_payer(env, admin, payer, reason_hash: BytesN<32>). Payer calls submit_appeal(env, payer, invoice_id, appeal_hash: BytesN<32>) within APPEAL_WINDOW_LEDGERS. Admin calls finalise_blacklist(env, admin, payer, uphold: bool). pay_invoice checks finalised && !uphold → panic PayerBlacklisted.

Acceptance Criteria

• blacklist_payer records entry with finalised: false; only admin can call it
• pay_invoice blocks finalised-blacklisted payers with PayerBlacklisted
• Payer can submit one appeal during the APPEAL_WINDOW_LEDGERS window
• Admin finalises with uphold: true (ban stands) or false (payer reinstated)
• PayerBlacklisted, AppealSubmitted, BlacklistFinalised events emitted from events.rs
• Tests: blacklist blocks, appeal window, appeal accepted reinstates, appeal rejected keeps ban, non-admin blacklist fails
• All CI checks (cargo test, cargo clippy, cargo fmt) pass and the branch has no merge conflicts

---

[dev-shierly]

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

Hi maintainer! I would love to help you with this issue. Given my theoretical knowledge and background, I am quite sure that I am well-equipped to tackle it. Please kindly assign it to me.

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

[Joshua13-stack]

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

hello maintainer i would love to work on this issue please assign me

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

[beulah7717108-eng]

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

Hi maintainer,

I would like to request assignment for this smart contract security and governance ticket in split-contracts.

I will implement the on-chain payer blacklist feature with an appeal window:

Storage & Types: Add BlacklistEntry struct and storage keys in types.rs and lib.rs tracking ban status, timestamps, appeal hashes, and finalization flags.

Admin & Payer Functions: Implement admin-only blacklist_payer with reason hashing, payer-driven submit_appeal within APPEAL_WINDOW_LEDGERS, and admin finalise_blacklist supporting uphold decisions (uphold or reinstate).

Enforcement & Events: Update pay_invoice to block finalized blacklisted payers with a PayerBlacklisted panic and emit proper structured events (PayerBlacklisted, AppealSubmitted, BlacklistFinalised) from events.rs.

Testing & QA: Add comprehensive unit tests covering blacklist blocks, the appeal window constraints, reinstatement on accepted appeals, ban enforcement on rejected appeals, and non-admin authorization failures, ensuring all CI checks pass cleanly.

ℹ️ 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 July 30, 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 🌊

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@beulah7717108-eng's PR #554 was approved and merged by @Kingsman-99.

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

👏 Great work, @beulah7717108-eng! Keep contributing to Stellar-split.

[drips-wave]

This issue has been completed by @beulah7717108-eng as part of the Stellar Wave Program's 7th Wave 🥳

😎 @beulah7717108-eng: 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. You can also Leave a review to share your experience working on this issue.

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