-
Notifications
You must be signed in to change notification settings - Fork 29
Improve Felt division and field arithmetic documentation across builder docs #232
Description
The docs already mention that Felt division computes the multiplicative inverse in types.md, pitfalls.md, and patterns.md, but the coverage is fragmented and external developers are still getting tripped up by it. Vaibhav from the Inicio team ran into this during PSWAP development, and it required a back-and-forth with Dennis on Slack to clarify.
I think we should improve this in three places:
-
types.md: Add a dedicated "Division" subsection with a side-by-side comparison showing the dramatic difference. For evenly divisible numbers (10 / 2) the result is the same, but for something like20 / 3the Felt result is6148914689804861447while u64 gives6. Seeing the actual numbers makes the difference click. -
pitfalls.md: Add a Felt division entry with the same Problem/Why/Solution structure as the existing overflow entry. This is arguably a more common pitfall than overflow. -
patterns.md: Expand the one-liner about Felt division into a "When to use Felt vs u64" section. Developers building DeFi need clear guidance on when Felt arithmetic is correct (hashing, commitments) vs when u64 is required (token amounts, proportional calculations). Worth mentioning thatas_u64()conversion is zero-cost.