mvx_defi_math_skill

Overview

This skill provides practical financial-math patterns for MultiversX DeFi, focused on precision management, safe rescaling, and predictable rounding. It codifies recommended decimal levels (BPS, PPM, WAD, RAY), half-up rounding for arithmetic, and safe percentage helpers to avoid truncation losses and rounding attacks. The goal is reliable on-chain arithmetic that preserves value and reduces exploit risk.

How this skill works

It inspects numeric operations and prescribes using the lowest precision that still prevents rounding errors, while performing intermediate calculations at higher precision (RAY) when needed. Multiplication, division, and rescaling use half-up rounding on scaled integers to avoid systematic truncation. Percentage helpers use built-in proportion utilities or explicit BPS/PPM formulas, and fee logic favors rounding that protects the protocol against dust attacks.

When to use it

• Use BPS (4 decimals) for simple fees and coarse percentages.
• Use PPM (6 decimals) for finer-grained percentage parameters.
• Use WAD (18 decimals) for token amounts and price arithmetic.
• Use RAY (27 decimals) for interest indices, compounding, and intermediate math.
• Apply half-up rounding when multiplying/dividing scaled integers or downscaling precision.

Best practices

• Always rescale explicitly before mixing numbers of different precisions; avoid implicit mixing.
• Compute intermediate results at RAY precision for stability, then downscale with half-up rounding.
• Use framework proportion helpers when available; fallback to BPS/PPM formulas with safe rounding.
• Round fees in favor of the protocol (ceiling for fees) and apply minimum amounts to deter dust attacks.
• Avoid repeated low-precision operations; accumulate at high precision and finalize once.

Example use cases

• Lending: calculate interest indices and compounded balances at RAY precision to prevent accrual drift.
• DEX: compute prices and LP shares in WAD and rescale with half-up to avoid systematic slippage.
• Staking: maintain reward indices and share ratios using RAY to preserve tiny rewards across epochs.
• Vaults: apply BPS-based fees with ceiling or half-up rounding to ensure protocol capture of fee dust.
• Fee modules: use proportion() helpers or apply_bps/apply_ppm patterns to compute fee transfers safely.