[BFT-A][R9] Replace curve arithmetic with 18-decimal U256 fixed-point math and deterministic integer sqrt

[umwelt]

Title

[BFT-A][R9] Replace curve arithmetic with 18-decimal U256 fixed-point math and deterministic integer sqrt

Category

• R9 Negative Spec Enforcement

Authoritative Inputs

• CBE Bonding Curve — Rust Implementation Specification sections 1, 3, and 4

Problem

The current issue understated the arithmetic requirements. The new docs fix the arithmetic contract tightly:

• all values stored as 18-decimal fixed-point u128
• U256 intermediates for widened multiplication
• floor-only division
• checked overflow rejection
• deterministic integer square root
• fixed operation order

Current Behavior

Curve-adjacent code still contains mixed scales, float usage, saturating arithmetic, and duplicate sqrt helpers. There is no single canonical U256 arithmetic layer for the documented curve engine.

Required Behavior

All consensus-reachable curve arithmetic, and any branch code that directly feeds documented curve execution, must follow the new rules exactly:

• SCALE = 10^18
• widen u128 -> U256 before multiplication
• floor division only
• overflow = reject with zero mutation
• deterministic integer_sqrt(U256) satisfying the documented invariants
• fixed evaluation order matching the spec
• flat-band special case support: delta_s = reserve_credit * SCALE / intercept

This issue no longer claims general oracle cleanup beyond code that directly feeds the documented curve path.

Safety Impact

If the arithmetic layer differs from the new spec, nodes can diverge on price, mint amount, redemption value, fee calculation, and graduation timing.

Proposed Fix

Add one canonical curve-math module and migrate all consensus-reachable curve arithmetic to it.

Dependencies

• Depends on [BFT-A][R8] Establish canonical CBE curve types and fixed-point state model #1923

Acceptance Criteria

• Canonical scaled_mul / scaled_div helpers exist on top of U256
• Canonical integer_sqrt(U256) exists and is used by curve inversion
• No float path remains reachable from consensus curve execution
• No saturating arithmetic remains reachable from consensus curve execution
• The implementation order for cost_single_band and inverse_mint matches the spec
• Flat-band special case is implemented deterministically

Test Plan

• Overflow rejection vectors
• Floor-division vectors
• integer_sqrt property tests
• Large discriminant vectors
• Operation-order regression vectors for cost_single_band and inverse_mint
• Flat-band mint vectors

Cleanup After

• Remove or isolate old Newton/float helpers from consensus curve paths
• Remove stale 1e8 pricing assumptions where they still feed documented curve behavior

[github-actions]

This GitHub issue proposes replacing the fragmented and inconsistent native economics arithmetic in the project with a unified, canonical integer math module to enhance consistency, precision, and safety. The current implementation utilizes mixed approaches, including floating-point operations, saturation math, and duplicate implementations of integer square root functions, leading to potential divergences in pricing and issuance outcomes. The proposed solution involves introducing a single canonical module using u128 for stored values, u256 for intermediates, and relying on precise operations like floor-based division and binary-search-based square root calculations. The update aims to eliminate float paths, saturation arithmetic, and reliance on the Newton method for calculations in the native economics code while ensuring robust testing for overflow, division, and square root functionalities. This migration is dependent on another issue (#1923), and cleanup tasks include isolating legacy methods from consensus-critical paths.

[umwelt]

Implemented on the bonding-curve rollout branch.

Delivered:

• 18-decimal fixed-point helpers over widened arithmetic in lib-blockchain/src/contracts/utils/math.rs
• deterministic integer sqrt for the consensus-reachable curve path
• removal of the old signed-intercept dependency in the canonical curve math
• bounded normalization fixes during review cleanup

Primary foundation commit:

• c8b8a80d Implement canonical bonding curve math foundation

This issue is complete for the current curve rollout.