A treasury instruction can contain the right digits and still represent the wrong amount. If one system treats an integer as whole tokens and another treats it as base units, the error is a scaling failure. Token decimals and rounding should therefore be controlled as reference data and calculation policy, rather than left to display formatting.
The control applies to payments, valuation, fee calculation, fund administration and client allocations. Each process may use a different output precision. The institution should know where conversion happens, which scale it uses and what happens to the part that cannot be represented in the destination system.
Preserve the integer and its meaning together
The ERC-20 specification makes decimals optional metadata and describes its role in user representation. The base-unit integer is the quantity returned by the token balance interface. An institution should not assume every token supplies the metadata or that a familiar symbol implies a particular scale.
Suppose a hypothetical token uses six decimals. A raw balance of 1,234,567 represents 1.234567 tokens. With eighteen decimals, the same integer represents a much smaller amount. The arithmetic is elementary; the operating risk is that the integer can move through several systems without carrying the scale that gives it meaning.
Store the network, contract address, raw quantity and verified decimals together. Retain the source and date of the metadata observation. If an asset cannot provide usable metadata, establish an approved alternative rather than silently applying a default. An unknown scale should produce an exception visible to the operator.
Display precision is not settlement precision
OpenZeppelin's ERC20 documentation states that decimals affects display rather than the contract's integer arithmetic. Its default of eighteen is a feature of that implementation, not a universal instruction to institutions integrating other tokens.
A wallet might display two decimal places while the account still holds smaller units. A fund statement might use another reporting precision. Neither should overwrite the raw settled quantity. The system should retain enough information to reproduce the display and the underlying balance independently.
For a payment, show the proposed human amount and the resulting base-unit amount before signing. A reviewer should be able to compare both with the approved asset metadata. Where the requested amount exceeds the token's precision, the workflow should reject it or apply an explicitly approved adjustment. It should not let a library choose the policy invisibly.
The identification rule connects to token reference data. A decimal value belongs to a particular deployed instrument on a particular network. Reusing a symbol-based scale across different contract records can turn an otherwise accurate instruction into a different quantity.
Use arithmetic that preserves the required units
Offchain systems should use integer or decimal arithmetic capable of retaining the quantities they handle. A numeric representation that rounds large integers during parsing can corrupt a balance before any deliberate business rounding occurs. Exports should preserve base-unit quantities in an exact representation through ingestion and processing.
The test is a round trip: can the receiving system ingest the value, convert it for display and recover the original base-unit integer without loss? If not, identify the step that changed it. A format that looks readable in a spreadsheet may not be safe as the interchange format for settlement instructions.
Solidity's types reference states that integer division rounds toward zero. An offchain model intended to reproduce a contract calculation should match the relevant operations and their order. Applying one final rounding operation to a mathematically similar formula can produce a different integer result.
That matters when a model calculates fees, shares or allocations in several stages. Preserve the units at each stage and document the rounding direction. A calculation should identify whether it produces token base units, share base units, a price or reporting currency. The word amount is too ambiguous for an integration contract.
Rounding should name who bears the residual
When a quantity is divided among clients, the sum of individually rounded amounts may differ from the original total. The difference requires a policy: retain a residual, allocate it through an approved method or carry it into a later period. The policy should be reproducible and applied consistently.
Consider ten base units allocated equally among three accounts. The exact fraction cannot be represented as an integer base-unit amount. Allocating three units to each leaves one unit. An institution should record that remaining unit and its treatment, rather than hide it in an unexplained reconciliation adjustment.
Separate rounding residuals from fees and market movement. A difference caused by truncation should not appear as price slippage. Conversely, a genuine fee should not be dismissed as rounding merely because it is small. Each category needs its own evidence and explanation.
The allocation rule should also address repeated small operations. A residual that is negligible in one transaction can accumulate across many distributions. The appropriate review threshold depends on aggregate quantity, value and the fairness of the allocation method, not only the largest single difference.
Keep prices and token scales separate
Valuation combines a token quantity with a price expressed in a stated currency and unit. The price feed may use its own scale. Record that scale separately from the token's decimals. The institution should be able to explain each conversion without relying on a field named decimals that changes meaning between services.
A valuation example should state whether the price is per whole token or per another unit, which currency it uses and the observation time. The final reporting amount can then be rounded according to the reporting policy. Rounding the token quantity prematurely may alter the result unnecessarily.
For cross-currency valuation, retain the intermediate amount and exchange-rate basis. If the final total differs from another system, the reconciliation should determine whether the difference came from quantity scale, price scale, exchange-rate selection or reporting rounding. A single tolerance field makes those causes difficult to distinguish.
Reference-data changes should trigger a controlled review
If a metadata observation differs from the approved asset record, quarantine the discrepancy. Check the contract identity, queried network, provider response and any relevant implementation change. Do not automatically update the scale for every historical quantity based on a new read.
The correct treatment depends on what changed. A bad initial entry requires correction of affected records. A migrated instrument may require a new identifier and conversion procedure. A changed endpoint might have returned another asset entirely. The team should establish the cause before rewriting payment templates or reports.
Keep metadata versions with the calculations they produced. A reviewer reconstructing last month's payment should be able to see which scale was used then and whether it was approved. Reprocessing historical transactions with today's reference data can conceal the origin of an error.
The broader wallet reconciliation process should compare raw quantities before presenting rounded balances. Otherwise two displays can agree while their underlying amounts differ, or disagree only because they use different display conventions.
Vendor handoffs should specify units in the field contract. A field carrying a decimal string for whole tokens should not share a name with a field carrying an integer string for base units. Require the receiving service to validate the representation and reject unexpected formats. This prevents a correct quantity becoming ambiguous at the boundary between otherwise well-controlled systems.
Document export conventions as well as API conventions. A manual file is still an integration when someone uses it to create the next payment batch.
Test the awkward values, not just whole tokens
Include the smallest transferable unit, quantities just below and above a display boundary, large raw integers and values not representable at the token's scale. Test deposits, withdrawals, exports and signed instructions through the entire path. A test using one whole token will miss many unit-conversion failures.
Allocation tests should include a total that does not divide evenly, a large number of small recipients and reversal of a previously rounded entry. Reversing a display amount without the original raw quantity can leave a residual. The process should retain the original settlement units needed to unwind the record accurately.
When a reconciliation tolerance is used, define its unit and purpose. A tolerance in whole tokens has a different meaning from one in reporting currency or base units. Require explanations for recurring differences below the threshold so that the control does not turn a small systematic error into an accepted feature.
The operating objective is traceability: every displayed amount should lead back to an exact quantity, an approved scale and a stated rounding decision. Decimals makes a token readable. The institution's controls make its quantities usable across systems without losing their meaning.