kmp-money

Money in KMP (commonMain)

Cardinal rule

• Never use Double/Float for money. Binary floating point cannot represent 0.10; sums drift and rounding is undefined. This applies to storage, arithmetic, serialization, and equality.
• java.math.BigDecimal is JVM-only — unavailable in commonMain. That is why KMP needs either integer minor units or a multiplatform bignum.
• Pick one representation and keep it at the boundary:
  • Minor units (Long cents) — simplest, exact, fast. Good default for a fintech ledger where every currency has a fixed exponent. Watch for overflow on very large aggregates and awkward sub-cent intermediate math (interest, FX).
  • Arbitrary-precision decimal — use com.ionspin.kotlin:bignum when you need sub-minor-unit precision, FX rates, or percentages. Pure-Kotlin BigDecimal, works on Android + iOS + JS/Wasm.

Dependencies

// shared/build.gradle.kts
plugins {
    kotlin("multiplatform")
    kotlin("plugin.serialization") version "2.4.0"
}
sourceSets {
    commonMain.dependencies {
        implementation("com.ionspin.kotlin:bignum:0.3.10")            // multiplatform BigDecimal/BigInteger
        // optional ready-made serializers (BigDecimal/BigInteger):
        // implementation("com.ionspin.kotlin:bignum-serialization-kotlinx:0.3.10")
        implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.11.0")
    }
}

ionspin BigDecimal essentials

import com.ionspin.kotlin.bignum.decimal.BigDecimal
import com.ionspin.kotlin.bignum.decimal.DecimalMode
import com.ionspin.kotlin.bignum.decimal.RoundingMode
import com.ionspin.kotlin.bignum.decimal.toBigDecimal

// Construct from String only (never fromDouble — reintroduces binary error):
val a = BigDecimal.parseString("19.99")
val b = "0.07".toBigDecimal()

// + - * are exact and need no mode.
val sum = a + b            // 20.06

// Division / non-terminating results REQUIRE a DecimalMode or they throw:
val mode = DecimalMode(decimalPrecision = 20, roundingMode = RoundingMode.ROUND_HALF_TO_EVEN, scale = 2)
val share = a.divide(3.toBigDecimal(), mode)   // 6.66

// Round to a fixed number of fraction digits (money):
val rounded = a.roundToDigitPositionAfterDecimalPoint(2, RoundingMode.ROUND_HALF_TO_EVEN)

// toStringExpanded() gives plain decimal ("20.06"); toString() may use E-notation.