TIP-836: harden exchange transaction calculations

[halibobo1205]

tip: 836
title: harden exchange transaction calculations
author: halibobo1205@gmail.com
status: Draft
type: Standards Track
category: Core
created: 2026-03-19
requires: None

Simple Summary

This proposal hardens the core calculation logic of Exchange trading pairs by replacing floating-point arithmetic with BigDecimal (except for pow operations), and introducing explicit overflow detection for all integer arithmetic and type conversions.

Motivation

The goal is to upgrade the numeric safety model for Exchange trading pair calculations from "implicitly constrained by runtime context" to "explicitly enforced by the language type," ensuring that safety guarantees are actively provided at the implementation level.

Explicit safety mechanisms offer the following engineering advantages:

• Higher readability: Code intent is unambiguous; safety assumptions can be understood without reading comments or surrounding context.
• Deterministic semantics: Overflow behaviour is guaranteed by the language mechanism rather than relying on external constraints.
• Predictable failure: Problems surface immediately as exceptions, making them easier to locate and fix.

Specification

All changes described in this section take effect when a new governance proposal parameter is activated. Until activation, all existing code paths remain completely unchanged.

1. Principles

1. No double/float arithmetic: All floating-point operations are replaced with BigDecimal, except pow (see Section 2).
2. Integer overflow detection: All integer arithmetic must use the overflow-detecting methods provided by StrictMath: addExact, subtractExact, multiplyExact, etc.
3. Type conversion overflow checks:
   • When converting BigInteger or BigDecimal to long or int, longValueExact() or intValueExact() must be called. Using longValue() / intValue(), which silently truncates, is prohibited.
   • When narrowing long to int, StrictMath.toIntExact must be used.

2. pow Operations: Hybrid StrictMath.pow + BigDecimal Approach

The Bancor pricing curve uses fractional exponents (0.0005 is the Connector Weight in the Bancor formula, which determines the steepness of the curve). BigDecimal's native pow method supports only integer exponents and cannot be used directly in this context.

This proposal adopts a hybrid approach: StrictMath.pow handles the fractional exponentiation, and the result is wrapped in a BigDecimal for all subsequent operations.

// Before (ExchangeProcessor)
double issuedSupply = -supply * (1.0
    - Maths.pow(1.0 + (double) quant / newBalance, 0.0005, this.useStrictMath));
long out = (long) issuedSupply;

// After
BigDecimal bdSupply     = BigDecimal.valueOf(supply);
BigDecimal bdNewBalance = BigDecimal.valueOf(newBalance);
BigDecimal bdQuant      = BigDecimal.valueOf(quant);

// base = 1 + quant / newBalance, computed precisely with BigDecimal.
// 18 decimal places (HALF_UP) are retained — greater than the effective precision
// of the subsequent StrictMath.pow doubleValue() input (~15–16 digits),
// so no additional rounding error is introduced.
BigDecimal base = BigDecimal.ONE.add(
    bdQuant.divide(bdNewBalance, 18, RoundingMode.HALF_UP));

// StrictMath.pow guarantees bit-for-bit identical results across all JVM
// implementations, satisfying the on-chain determinism requirement.
double powResult = StrictMath.pow(base.doubleValue(), 0.0005);

// All subsequent arithmetic is performed at the BigDecimal level,
// preventing floating-point error accumulation.
BigDecimal issuedSupply = bdSupply.negate().multiply(
    BigDecimal.ONE.subtract(BigDecimal.valueOf(powResult)));
long out = issuedSupply.setScale(0, RoundingMode.DOWN).longValueExact();

The key distinction between StrictMath.pow and Math.pow is that StrictMath requires all JVM implementations to produce bit-for-bit identical results, independent of the underlying hardware or JVM optimization behavior. This satisfies the determinism requirement for on-chain computation.

3. Non-Negative Validation Before State Write

long newFirstBalance  = StrictMathWrapper.addExact(firstTokenBalance, sellTokenQuant);
long newSecondBalance = StrictMathWrapper.subtractExact(secondTokenBalance, buyTokenQuant);

if (newFirstBalance < 0 || newSecondBalance < 0) {
    throw new ContractExeException(
        "Exchange balance must remain positive after transaction");
}

this.exchange = this.exchange.toBuilder()
    .setFirstTokenBalance(newFirstBalance)
    .setSecondTokenBalance(newSecondBalance)
    .build();

4. Unified Use of Exact-Family Methods for Integer Arithmetic

All integer addition, subtraction, multiplication, and type conversions are replaced with overflow-safe equivalents:

Original Operation	Replacement
a + b	StrictMathWrapper.addExact(a, b)
a - b	StrictMathWrapper.subtractExact(a, b)
a * b	StrictMathWrapper.multiplyExact(a, b)
(int) longVal	StrictMathWrapper.toIntExact(longVal)
bigInteger.longValue()	bigInteger.longValueExact()
bigDecimal.longValue()	bigDecimal.longValueExact()

All of the above methods throw ArithmeticException on overflow or truncation. The exception is caught by the upper-level transaction execution framework and treated as a contract execution failure, causing the transaction to be rolled back.

StrictMathWrapper is an internal utility class that provides a unified wrapper around StrictMath's Exact-family methods.

Rationale

StrictMath.pow + BigDecimal Is the Correct Implementation Path for the Bancor Algorithm

The Bancor pricing curve requires fractional exponentiation. BigDecimal does not natively support fractional powers; implementing ln/exp approximations from scratch or introducing a third-party library would increase implementation complexity and add external dependency risk.

StrictMath.pow guarantees bit-for-bit cross-platform consistency at the JVM specification level, directly satisfying the on-chain determinism requirement without introducing any additional dependencies. By wrapping the pow result in BigDecimal, all subsequent addition, subtraction, and multiplication operations are performed at the BigDecimal level, preventing the accumulation and propagation of floating-point errors.

This approach deliberately confines floating-point precision limits to the single pow step, with StrictMath guaranteeing cross-platform consistency for that step. The overall calculation path achieves both greater determinism and higher precision than the original implementation.

Backwards Compatibility

This proposal is gated behind the Proposal mechanism and is fully backwards compatible.

[jwrct]

Excellent proposal for enhancing numerical safety in exchange calculations. This TIP represents a significant and well-considered improvement to TRON’s core numerical safety model for exchange transactions. The transition from implicit runtime constraints to explicit language-level type enforcement is a mature engineering approach that will substantially improve system reliability and predictability.

[warku123]

The proposal comprehensively addresses the floating-point precision and overflow issues in exchange calculations.

One minor suggestion: the Exact-family methods table could also mention the compound assignment operators (e.g., supply += out, supply -= supplyQuant) which should likewise be replaced with addExact/subtractExact patterns to maintain consistency throughout the entire calculation chain.

Looking forward to the implementation!

[halibobo1205]

@warku123 That’s a good suggestion—it should be included in this round of optimization.

[waynercheung]

@halibobo1205 Support the direction overall.
One consensus-sensitive point that should be clarified in the TIP text is Section 3: the description says the exchange balance must remain positive, but the sample check only rejects values < 0, which still allows a zero balance. It would be better to make the post-trade invariant explicit (>= 0 vs > 0) and align the wording, code snippet, and error message.

I also suggest making the BigDecimal rounding contract consensus-explicit rather than leaving it implicit in the implementation. In particular, the intermediate division scale (18), the rounding mode for quant / newBalance (HALF_UP), and the final integer conversion rule (RoundingMode.DOWN) should be specified as part of the proposal and covered by boundary tests where the result is close to an integer cutoff. That will make deterministic replay and pre-/post-activation behavior much easier to verify.

The compound-assignment audit mentioned above should definitely be included in the implementation checklist as well.

[halibobo1205]

@waynercheung

1. Balance invariant

Good point. I'll review the current balance validation logic and confirm whether the invariant should be strictly positive (> 0). A zero balance is equivalent to a closed pool and should be consistent with the validate() semantics.

2. Rounding specification

Agreed, this should be made explicit in the proposal. Will add: intermediate division scale of 18, HALF_UP rounding mode, and truncation toward zero for final long conversion (compatible with original (long) cast semantics).

3. Boundary tests

Agreed. Will cover: overflow detection (balance near Long.MAX_VALUE), extremely small/large quant values, and result consistency between hardened and original paths.