docs(builder): clarify Felt division across builder docs#284
docs(builder): clarify Felt division across builder docs#284alimmaster wants to merge 4 commits into
Conversation
BrianSeong99
left a comment
There was a problem hiding this comment.
Thanks for this — the core is solid: the math checks out (20/3 → 6148914689804861447, 10/2 → 5), the field-division explanation is accurate, and the u64 vs Felt guidance is genuinely useful. A few changes before merge:
1. Bug — Word has no inner field (pitfalls.md)
In the Solution snippet:
let total_amount: u64 = total.inner[0].as_u64();Word is accessed via its .a/.b/.c/.d fields (or Index), not .inner — every other Word example in the docs uses field syntax. This won't compile as written. Please change to:
let total_amount: u64 = total.a.as_u64();2. Trim the over-warning (pitfalls.md)
The entry is a bit heavy: Problem → "especially dangerous" → Why → Solution → plus a :::warning box that largely restates the Solution. Suggest:
- Drop the
:::warning Do not use Felt division…callout — Problem/Why/Solution already covers it, and it duplicates the paragraph right above it. - Soften "especially dangerous" to something like "a common source of bugs." It's well-defined arithmetic, just not what integer-minded code expects.
3. Optional polish
- Keep the divide example consistent:
types.mdusesfelt!(20) / felt!(3),pitfalls.mdusesFelt::new(20) / Felt::new(3). Preferfelt!()in both. - "
as_u64()… is zero-cost" (patterns.md) — "inexpensive" is safer; the conversion can involve a canonical reduction.
With #1 fixed and #2 trimmed this is good to merge. Nice addition overall.
|
Addressed the review feedback: fixed the |
Current behavior
The builder docs mention that Felt division uses the multiplicative inverse, but the explanation is fragmented and easy to miss.
As a result, developers can misread Felt division as standard integer division, especially in business-logic scenarios like token amounts, fee calculations, and proportional splits.
New behavior
This change improves Felt division guidance in three places:
Divisionsubsection totypes.mdwith side-by-sideu64vsFeltexamplesWhen to use Felt vs u64section topatterns.mdpitfalls.mdBreaking changes
None.
Other info
Documentation-only update.
Closes #232.