Representation of Monetary Amounts in Mojaloop as Integers Instead of Decimals

[vijayg10]

Request Summary:

Should Mojaloop represent monetary amounts and position fields as integers (minor units per ISO 4217) instead of decimals, to improve accuracy and performance?

Request Details:

• Deadline: -
• Impact (Teams): Core Mojaloop developers, QA/testing, deployment/infra teams, API integrators (DFSPs, Hub Operators).
• Impact (Components):
  • Mojaloop APIs (amount fields in schemas and position field in admin apis)
  • Central Ledger DB schema (amount, position fields)
  • ML-Number usage in services
  • API documentation & developer guides

Background:

Currently, Mojaloop represents monetary amounts as strings with decimal values (e.g., "10.99"). This requires string parsing and arithmetic through the ML-Number library.

However, handling decimals in software introduces precision issues and performance overhead. For example, in many languages:

print(0.1 + 0.2)  
# Output: 0.30000000000000004

This is not a bug, but a fundamental limitation of binary floating-point representation (IEEE 754) in computers.

• Humans can represent 1/3 in base-10 decimals only as an approximation (e.g., 0.3333…). It’s a repeating decimal that cannot be expressed with finite precision in base-10.
• Computers use base-2 (binary) floating-point. In the same way many decimal fractions (e.g., 0.1, 0.2) cannot be represented exactly in binary, leading to rounding errors.

While Mojaloop avoids direct floating-point usage by relying on ML-Number and string representations, this pushes the burden into software-emulated decimal operations, which are slower and less efficient than native CPU integer operations.

Industry Best Practice:

Financial systems commonly store amounts in integers (e.g., cents instead of dollars). This avoids floating-point pitfalls and simplifies comparisons, summations, and validations.

The ISO 4217 specification defines minor units for each currency (e.g., 2 decimal places for USD, 0 for JPY). By multiplying the amount by 10^minorUnits, we can store amounts as whole integers.

Proposed Change

• Store all amounts (including position fields) as integers, scaled by ISO 4217 minor units.
  • Example: 10.99 USD → 1099 (cents).
• Update API specifications to expect integer values.
• Remove reliance on ML-Number for basic amount operations.
• Update Mojaloop documentation to reflect this change.

Benefits

• Accuracy: Removes rounding errors.
• Performance: Leverages native CPU integer arithmetic.
• Simplicity: Easier for developers to handle values consistently.
• Consistency: Aligns Mojaloop with financial services industry best practices.

Risks & Considerations

• Backward compatibility: Integrations expect string decimals. We may need API versioning or string conversions.
• Currency variations: Some currencies have unusual minor units (e.g., 3 decimals for TND). Must ensure ISO 4217 mapping is consistently applied.
• Migration effort: DB schema changes, API refactor, and integration testing required.

Next Steps

1. Run a PoC refactor for one service to integer-based amounts.
2. Benchmark performance: throughput, latency, CPU utilization (with vs. without ML-Number).
3. Develop a migration strategy (DB, APIs, integration impacts).
4. Present results for DA decision.

Artifacts:

• Benchmark PoC results

Dependencies:

• API versioning strategy
• Migration path for existing integrations

Accountability:

• Owner:
• Raised By: Vijaya Kumar Guthi

Decision(s):

• Approved By:

Details

[vijayg10]

https://docs.tigerbeetle.com/coding/data-modeling/#fractional-amounts-and-asset-scale

[bushjames]

Discussed on DA call 2025-10-15 0900UTC.

JB raised this question on the monthly TGB call yesterday. TGB was not at quorum so no decision was made, however discussion was had that raised a few issues with the proposed change e.g. ISO-4217 minor units are not always applicable in a territory, e.g. Kenyan Shillings do have a minor unit according to ISO-4217 but it is not used in the market.

JB suggests that more research is required before making assumptions about performence benefits of using plan js numbers as integers - due to JS spec for numbers being floating point. BigInts are possibly optimised in v8 (node runtime) for integer math.

PB raises that DB operations e.g. summing string values are costly!

MR raises that TigerBeetle uses bigints (64bit) and at some point we will have to convert from API string representations. Most arithmetic ops happen in the DB....be careful we are not solving for JS in the switch when ops are all done in the DB layer. VK says most usage is in position handler e.g. summing total of batch and sending updated position to mysql. MR says this will likely change in TigerBeetle ledger.

MR: if our intention is to use TigerBeetle internal batching then we need to assess how much perf improvement will be gained from pre-batching (it appears to be an anti-pattern from previous experience and consultation with TigerBeetle experts). TigerBeetle docs etc.. suggest pre-batching is not desirable as the official client does this internally.

Discussion about changes to position handler in TigerBeetle ledger implementation ensue; most transfer state machine logic is offloaded to TigerBeetle so our "application" level logic will be reduced, especially as we will not be needing/using a SQL DBMS as a state machine store.

MR raises questions around transformations from currency representations that include fractions...e.g. at the participant? in the integration layer? in the hub?

Reconciliation problems may occur if different representations exist across the entire scheme.

It appears that TigerBeetle will make most of the problems here go away, given that it deals exclusively with bigint currency values. Also, given that this represents a significant amount of work, the group are in agreement that we will shelve this issue until we have the TigerBeetle ledger implementation, at which point further discussion on related points such as API representations can continue.