Document the protocol fee model from accrual through treasury withdrawal
Description
Protocol fees touch several files — set_protocol_fee_bps/set_governed_params set the rate, calculate_protocol_fee computes it, release_milestone accrues it into AccumulatedProtocolFees, and an admin withdrawal drains it — yet there is no single document that explains the basis-point model, the rounding rule, where fees are stored, and who can withdraw. New contributors must reverse-engineer the flow from contracts/escrow/src/lib.rs and contracts/escrow/src/governance.rs.
This issue writes an authoritative protocol-fee document covering the full lifecycle.
Requirements and context
- Repository scope: Talenttrust/Talenttrust-Contracts only.
- Document: the basis-point unit (10_000 = 100%), the
amount * bps / 10_000 formula, floor rounding, and the 10_000 cap.
- Document where fees accrue (
AccumulatedProtocolFees), when (on each release), and the admin-only withdrawal with InsufficientAccumulatedFees.
- Include a worked numeric example and a sequence diagram from release to withdrawal.
- Cross-link the relevant entrypoints.
Suggested execution
- Fork the repo and create a branch
git checkout -b docs/contracts-protocol-fee-model- Implement changes
- Write code in: no production change; documentation only (reference
contracts/escrow/src/lib.rs).
- Write comprehensive tests in: not applicable; if a doctest-style example is added, place it in
contracts/escrow/src/test/protocol_fees.rs.
- Add documentation: create
docs/escrow/protocol-fees.md under docs/escrow.
- Include NatSpec-style doc comments (
///) cross-referencing the doc from the fee functions.
- Validate security: document the admin-only withdrawal authorization.
- Test and commit
Test and commit
- Run
cargo fmt --all -- --check, cargo build, and cargo test.
- Verify any embedded example matches actual behavior.
- Include the full
cargo test output in the PR description.
Example commit message
docs: document the protocol fee model from accrual to withdrawal
Guidelines
- Minimum 95 percent test coverage for impacted modules.
- Clear, reviewer-focused documentation.
- Timeframe: 96 hours.
Community & contribution rewards
- 💬 Join the TalentTrust community on Discord for questions, reviews, and faster merges: https://discord.gg/WqnGpcPx
- ⭐ This is a GrantFox OSS / Official Campaign task and may be rewarded. When your PR is merged you'll be prompted to rate the project — if this issue and the maintainers helped you ship, we'd be grateful for a 5-star rating. Clear questions in Discord and tidy, well-tested PRs are the fastest path to a merge and a reward.
Document the protocol fee model from accrual through treasury withdrawal
Description
Protocol fees touch several files —
set_protocol_fee_bps/set_governed_paramsset the rate,calculate_protocol_feecomputes it,release_milestoneaccrues it intoAccumulatedProtocolFees, and an admin withdrawal drains it — yet there is no single document that explains the basis-point model, the rounding rule, where fees are stored, and who can withdraw. New contributors must reverse-engineer the flow fromcontracts/escrow/src/lib.rsandcontracts/escrow/src/governance.rs.This issue writes an authoritative protocol-fee document covering the full lifecycle.
Requirements and context
amount * bps / 10_000formula, floor rounding, and the 10_000 cap.AccumulatedProtocolFees), when (on each release), and the admin-only withdrawal withInsufficientAccumulatedFees.Suggested execution
git checkout -b docs/contracts-protocol-fee-modelcontracts/escrow/src/lib.rs).contracts/escrow/src/test/protocol_fees.rs.docs/escrow/protocol-fees.mdunderdocs/escrow.///) cross-referencing the doc from the fee functions.Test and commit
cargo fmt --all -- --check,cargo build, andcargo test.cargo testoutput in the PR description.Example commit message
docs: document the protocol fee model from accrual to withdrawalGuidelines
Community & contribution rewards