Add protocol fee treasury withdrawal with admin authorization

[mikewheeleer]

Description

Once DataKey::AccumulatedProtocolFees is populated by milestone releases, there is no entrypoint to withdraw collected protocol fees. Add an admin-gated withdraw_protocol_fees that zeroes the accumulator and emits an auditable event, completing the fee lifecycle referenced in docs/escrow/FUNDING_ACCOUNTING.md.

Requirements and context

• Scoped to TalentTrust escrow Soroban contract (contracts/escrow).
• Implement withdraw_protocol_fees(admin, recipient) requiring require_admin and admin.require_auth(); reject when the accumulator is zero.
• Reset DataKey::AccumulatedProtocolFees to 0 atomically and publish a fee_wd event with (recipient, amount, timestamp).
• Invariant: total withdrawn over the contract lifetime equals total fees accrued; no withdrawal possible while paused/emergency.
• Must be secure, tested, and documented.

Suggested execution

• Fork the repo and create a branch:
  • git checkout -b feature/fee-treasury-withdrawal
• Implement changes:
  • contracts/escrow/src/protocol_fees.rs
  • Tests: contracts/escrow/src/test/protocol_fees.rs
  • Docs: docs/escrow/FUNDING_ACCOUNTING.md
  • Include rustdoc/NatSpec-style doc comments on public functions
  • Validate security assumptions (auth, overflow, fail-closed state machine, storage TTL, fee accounting)

Test and commit

• Run tests: cargo test
• Cover edge cases (unauthorized callers, double release/refund, expired approvals, fee rounding, paused state)
• Include test output and security notes in the PR

Example commit message

feat(escrow): add admin protocol fee withdrawal

Guidelines

• Minimum 95% test coverage on new/changed code
• Clear documentation
• Timeframe: 96 hours from assignment

[barnabasolutayo-lgtm]

@barnabasolutayo-lgtm has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

"I would love to implement this withdrawal entrypoint to complete TalentTrust's fee lifecycle, bringing my deep experience with Soroban smart contract development, strict require_auth admin enforcement, and atomic state mutations to securely zero out the accumulator, publish the auditable events, and guarantee your financial invariants pass all edge-case testing."

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

[drips-wave]

Congratulations, @barnabasolutayo-lgtm! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 2, 2026.

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