multiversx-defi-math_skill

Overview

This skill provides reusable financial math patterns tailored for MultiversX smart contracts. It documents precision constants, half-up and away-from-zero rounding, safe rescaling, and percentage helpers to avoid value leakage and rounding attacks. Use it to standardize fee, rate, and token math across DeFi modules.

How this skill works

The skill defines common precision levels (BPS, PPM, WAD, RAY) and implements half-up rounding for unsigned operations and away-from-zero rounding for signed values. It includes safe rescaling that rounds correctly when downscaling, and idiomatic percentage helpers using the frameworks proportion method. Templates show how to wrap these primitives in a shared math module for reuse.

When to use it

• Any contract handling fees, rates, interest indices, or token-to-share conversions
• When performing intermediate calculations that risk precision loss
• When converting between different decimal precisions (rescaling)
• When implementing fee or percentage logic to avoid truncation loss
• When computing signed PnL or price deltas that must avoid bias

Best practices

• Choose the lowest precision that still avoids rounding errors; use higher precision for intermediate math
• Multiply before dividing to preserve precision (avoid early division)
• Round half-up for unsigned operations and away-from-zero for signed values to prevent systematic bias
• Always rescale values before mixing different precision levels
• Prefer the frameworks proportion() for percentage math; validate bases (BPS/PPM) and clamp inputs

Example use cases

• Lending: compute utilization and compound interest at RAY precision with mul_half_up/div_half_up
• DEX/AMM: price impact and LP shares using WAD precision and half-up rounding
• Staking: reward index math using RAY and safe rescaling to distribute shares
• Vaults: apply BPS or proportion-based fees and round fees up to favor the protocol
• Fee modules: implement apply_bps/apply_ppm helpers with bounds checks