Skip to content

Document the basis-points fee-rounding convention in the README fee section #159

Description

@Jagadeeshftw

📌 Description

quote_fee and open_settlement's fee calculation both use amount * bps / BPS_DENOMINATOR (i128 floor division against a denominator of 10_000), meaning the computed fee always rounds down and can round to 0 for small amounts at low rates — behavior confirmed by quote_fee's own doc comment ("never exceeds the input amount") but not spelled out anywhere in the README for integrators who only read the interface table.

🧩 Requirements and context

  • Add a short paragraph to the README's fee-related section explaining the basis-points convention (1 bps = 0.01%), the 10_000 denominator, and the floor-rounding behavior including the zero-fee-at-small-amounts edge case.
  • Cross-reference max_fee_bps() as the authoritative source for the current fee cap, avoiding a hardcoded '10%' claim that could drift from MAX_FEE_BPS in src/lib.rs.
  • Link to the fee-truncation regression tests (tracked separately in this backlog) as the executable specification of this behavior.

🛠️ Suggested execution

  • Add the paragraph to README.md near the existing set_fee/quote_fee/asset_fee table rows.
  • No code changes — this is a pure documentation task.
  • Keep wording consistent with the doc comments already present in src/lib.rs for quote_fee and set_fee.

✅ Acceptance criteria

  • The README explains the basis-points convention, denominator, and floor-rounding behavior in plain language.
  • The fee cap is referenced via max_fee_bps() rather than a hardcoded number.
  • No functional changes.

🔒 Security notes

Integrators who assume fees round up, or who don't realize a fee can legitimately be zero for a tiny settlement, could build off-chain accounting that mismatches on-chain accrual by a rounding difference that compounds across many small settlements.

📋 Guidelines

  • Minimum 95% test coverage
  • Clear documentation
  • Timeframe: 96 hours

Metadata

Metadata

Assignees

Labels

Type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions