Skip to content

Improve Felt division and field arithmetic documentation across builder docs #232

@Keinberger

Description

@Keinberger

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:

  1. 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 like 20 / 3 the Felt result is 6148914689804861447 while u64 gives 6. Seeing the actual numbers makes the difference click.

  2. 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.

  3. 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 that as_u64() conversion is zero-cost.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions