Protocol Fee Engine with Multi-Party Payout Splits & Treasury Accounting

[meshackyaro]

Description

This issue aims to address the implementation of Protocol Fee Engine with Multi-Party Payout Splits & Treasury Accounting.

The core objective is to: Add a configurable, governance-bounded fee engine to the escrow contract that splits every payout across worker, protocol treasury, and optional referrer in exact integer arithmetic, with per-token treasury accounting and provable no-dust/no-loss invariants.

By completing this feature, we will ensure that the GuildWorkman protocol maintains its high standards for security, usability, and decentralized logic. This issue requires careful attention to the Smart Contract architecture and adherence to the existing project conventions.

When picking up this issue, please ensure you document any new dependencies or architectural decisions made during development.

Component

Smart Contracts (Soroban)

Difficulty

⚫ Very Hard

Current state

escrow::confirm_completion, cancel_appointment, and resolve_dispute all transfer the entire appointment.amount to exactly one recipient. There is no protocol revenue path, no treasury, and no notion of a referrer or guild cut — so the protocol currently cannot sustain itself, and every future fee change would be a breaking rewrite of the payout paths.

The hard part here is not the split; it is the arithmetic and the invariants. Payouts are i128 token units, fee rates are basis points, and every rounding decision must be deliberate and provable: no path may ever pay out more than was escrowed, and no path may leave stranded dust in the contract.

Tasks

• Review the existing Soroban workspace under soroban-contracts/contracts/
• Implement the contract logic for: Protocol Fee Engine with Multi-Party Payout Splits & Treasury Accounting
• Define fee configuration in basis points with a hard-coded maximum the governance/admin path cannot exceed
• Apply the split consistently across confirm_completion, resolve_dispute, and the cancel/refund path (a cancellation must define whether fees are charged at all — document the choice)
• Implement per-token treasury accounting with an explicit withdrawal path and its own authorization
• Use checked integer arithmetic throughout; pick and document a deterministic rounding policy, assigning the remainder to a single named party so totals always reconcile exactly
• Support an optional referrer/guild share that is absent for most appointments without changing the settlement path
• Write comprehensive unit and integration tests, including adversarial edge cases — 1-unit amounts, i128::MAX-adjacent amounts, zero-fee and max-fee configs, and a property/invariant test asserting sum(payouts) == amount for randomized inputs
• Add caching for cargo dependencies in CI
• Run cargo fmt --check and cargo clippy -- -D warnings
• Run cargo test and soroban contract build to verify the optimized WASM build

Acceptance Criteria

• Feature accurately implements the objective: Add a configurable, governance-bounded fee engine to the escrow contract that splits every payout across worker, protocol treasury, and optional referrer in exact integer arithmetic, with per-token treasury accounting and provable no-dust/no-loss invariants.
• For every payout path, the sum of all transferred amounts equals the escrowed amount exactly — no overpayment, no stranded dust
• Fee rates cannot be set above the documented protocol maximum, by admin or by anyone else
• Treasury balances are tracked per token and are withdrawable only through the authorized path
• Fee behaviour on cancellation and on dispute resolution is documented and tested, not incidental
• Any PR that introduces compiler or clippy warnings is automatically blocked
• Contract logic is covered by tests exercising success, failure, and attack paths
• Storage layout and authorization are documented and reviewed for safety
• Code is properly reviewed and approved by codeowners

Estimated Time

4-5 days

[Chigybillionz]

Hi, I’m interested in this task and can handle the implementation. Assign it to me and I’ll get started.

[smartalee]

I would like to take this pls 🙌

[Meet-hybrid]

I would like to contribute to this issue. I have experience with JavaScript/TypeScript, React, backend APIs, testing, Git, and software architecture. I will follow the acceptance criteria, add tests, and provide a focused pull request.