Skip to content

docs: explain the normalization flow in math.rs (#699) - #719

Closed
ayomidearegbeshola29-dev wants to merge 1 commit into
Stellar-split:mainfrom
ayomidearegbeshola29-dev:fix/issue-699-math-doc
Closed

docs: explain the normalization flow in math.rs (#699)#719
ayomidearegbeshola29-dev wants to merge 1 commit into
Stellar-split:mainfrom
ayomidearegbeshola29-dev:fix/issue-699-math-doc

Conversation

@ayomidearegbeshola29-dev

Copy link
Copy Markdown

Explain the normalization flow in math.rs module doc

Summary

Closes #699

contracts/split/src/math.rs had a short module-level doc comment describing
why amounts are normalised, but it did not explain the normalization flow
— the three-stage pipeline that every token amount goes through. This PR
expands the //! module documentation with an explicit "Normalization flow"
section so contributors understand the contract's invariant: split math is
always performed in canonical 7-decimal units, never in native token units.

What changed

  • Added a "## Normalization flow" subsection to the math.rs module doc with
    the three stages:
    1. Ingest (native scale) — amounts arrive in the token's own smallest
      unit and are never trusted for cross-token math as-is.
    2. Normalize → canonicalnormalize_amount scales to the fixed
      CANONICAL_DECIMALS (7) representation; all share/ratio/fee/overflow
      arithmetic happens here.
    3. Denormalize → nativedenormalize_amount reverses the scaling
      before any token::Client::transfer().
  • Noted that the two helpers are exact inverses (lossless round-trip except the
    intentional integer truncation when a higher-decimal token is downscaled),
    and that negative inputs are rejected.

The existing per-function /// docs on normalize_amount / denormalize_amount
are unchanged.

Verification

Documentation-only change; no code affected. (As noted on the other split
PRs, cargo check on main currently fails for unrelated, pre-existing reasons
— unimplemented helpers/error variants from other open issues — so CI red here
is not caused by this change.)

closes #699

@ayomidearegbeshola29-dev

Copy link
Copy Markdown
Author

Re-homed: PR now opened from assignee account gabrielujelistic-collab (replacement #728-#731).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add module-level doc-comment to math.rs explaining the normalization flow

1 participant