Epic: exact (float-free) monetary amounts — wei-exact on-chain, source-exact everywhere

[TaprootFreak]

Goal

Make every monetary amount in the system exact (float-free) end-to-end, so the bookkeeping is truly native-first exact rather than exact-to-8-dp-of-a-float. Concretely:

• Wei-exact where an on-chain integer truth exists (crypto deposits, withdrawals, DEX swaps, bridges) — carry the raw base-unit integer from the chain.
• Source-exact everywhere else — preserve the value exactly as the source reports it (exchange decimal strings, bank amounts) with no IEEE-754 drift, even when that precision is ≤ 8 dp.

This continues the ledger work in #4280 / PR #4282, which added exact-integer ledger_leg.amountBaseUnits storage but is currently capped at 8 dp because its input is already a rounded float.

Why this is needed (measured)

• Monetary amounts are stored as @Column({ type: 'float' }) (PostgreSQL double precision) across the app — 237 float columns in 48 entity files (~200 genuinely monetary; ~25 are dimensionless ratios such as refFactor/percentFee/leverage that must not convert).
• The full on-chain precision is captured nowhere today — it is discarded at ingestion, before anything is persisted:
  • EVM: src/integration/blockchain/shared/evm/evm.util.ts:82 — fromWeiAmount builds the exact decimal string via formatUnits(rawValue, decimals) then parseFloat(...) collapses it to a double; the raw hex value is not retained.
  • Bitcoin/UTXO: node-client.ts returns BTC as a JSON decimal parsed straight to float; no satoshi integer is ever constructed. Same for the other chains.
  • The unified PayInEntry.amount is typed number, so no adapter can carry an integer through even where one exists.
• PR feat(ledger): native-first exactness — exact integer base units end-to-end (#4280) #4282's amountBaseUnits is derived by toBaseUnits(leg.amount, decimals) from the already-lossy float and capped at Math.min(decimals, 8) — exact-integer storage of an 8-dp float, not source-wei-exactness.

Scope & blast radius (measured)

• ~200 monetary float columns; biggest carriers: buy-crypto.entity (27), buy-fiat.entity (26), user/user-data (27), bank-tx (13), trading-order (12), plus every payin/payout/dex/pricing/fee/transaction-request entity.
• Contract surface: ~104 DTO files with ~427 number-typed monetary fields and ~38 mappers.
• Arithmetic surface: 105+ files using Util.round/amountToChf/CryptoAmount helpers, plus 60+ service files doing money arithmetic — each moves to exact (bigint / decimal) math.

Why staged, not one PR (professional standard on a live financial system)

A single atomic PR of this size cannot be reviewed, tested, or rolled back safely on live money; it also carries a breaking API wire-format change (number → string/decimal) and an unsolved historical backfill (legacy rows have no raw value; re-querying millions of legacy tx across chains is infeasible and some chains are pruned). The professional, no-shortcut delivery is a sequenced series of additive, individually reviewed, fail-open PRs.

Decisions / defaults (documented; revisit per stage)

1. Legacy backfill = fail-open. New rows carry the exact value; legacy rows keep the existing 8-dp-derived value (nullable exact column). No mass chain re-query.
2. API compatibility preserved. External wire format stays backward-compatible (exact values serialized as strings / additive fields / versioned), so the frontend is not broken by a stage.
3. Dimensionless ratios stay float (factors, percentages, leverage) — they are not monetary and have no base unit.
4. No invented precision. Where a source reports ≤ 8 dp (exchanges, fiat), the target is "exact as reported, no float drift" — not fabricated sub-units.

Stages (each = its own reviewed PR)

• Stage 1 — On-chain wei-exact ingestion → ledger (deposits & withdrawals). Add nullable exact amountBaseUnits (numeric ↔ bigint) to crypto_input and payout_order; widen the ingestion path to capture the raw integer as a string before parseFloat (EVM rawValue, UTXO satoshis via string scaling, other register strategies); book the persisted raw integer straight into ledger_leg.amountBaseUnits instead of deriving from the float. Additive, fail-open on legacy rows, no wire-format change. ← in progress.
• Stage 2 — On-chain swaps & bridges. trading_order, liquidity_order (DEX), liquidity_management on-chain legs — same pattern.
• Stage 3 — Exchange legs source-exact. Preserve the exact exchange-reported decimal (ccxt / Scrypt) as a string, no float rounding, into exchange_tx and its ledger legs.
• Stage 4 — Supporting/payment amount columns → exact. Subdomain by subdomain (buy_crypto, buy_fiat, sell, bank_tx, refReward, …): exact monetary columns + DTO/mapper serialization (backward-compatible).
• Stage 5 — Derived/valuation columns. CHF valuations, fees, prices → exact decimals to eliminate float drift in computed values.
• Stage 6 — Retire float shadows. Once all readers use the exact columns, deprecate/remove the float columns.

Non-goals

• Dimensionless ratios; fabricating precision the source does not have; a single atomic mega-PR.

Relation to existing work

Builds on #4280 and PR #4282 (exact-integer ledger storage). Interacts with the enforced CHF-first per-tx invariant (ledger_tx.amountChfSum = 0 DB CHECK): CHF remains the universal per-tx balance; native exactness is enforced via exact base-unit storage + §7 per-asset reconciliation against custody, per the analysis in #4280.

[TaprootFreak]

Stage 1 withdrawal capture — investigation outcome (PR #4288)

The withdrawal capture point is the on-chain broadcast, not payout_order creation (where the amount is a DFX-computed float with no independent integer).

Result: exact on-chain integer IS available at broadcast (Case A) for >8-decimal assets. At EVM broadcast the tx value is EvmUtil.toWeiAmount(order.amount, asset.decimals) (evm-client.ts coin :853/:873, token :885) — the same string/BigNumber conversion the client uses, at the asset's full base-unit resolution. Since toBaseUnits caps precision at min(decimals, 8) (base-units.transformer.ts), for every EVM 18-dp coin/token the on-chain integer differs from toBaseUnits(float(amount)) — e.g. 0.1234567891 ETH → on-chain 123456789100000000 wei vs derived 123456790000000000. Captured into payout_order.amountBaseUnits in the EVM base payout strategy (strategies/payout/impl/base/evm.strategy.ts, after pendingPayout); the ledger books it verbatim on the withdrawal wallet leg (when no payout-asset fee is folded in).

≤8-decimal assets need no capture (already exact): BTC and other ≤8-dp assets (UTXO coins, 6-dp stablecoins, ADA/TRX/ICP) — toBaseUnits keeps all their decimals, so the derived base units already equal the on-chain integer. Column stays null; the derived path is exact.

Deferred (documented, additive-only): non-EVM >8-dp assets (Solana 9, Monero 12, Zano 12) each need their own send-path scaling → left fail-open (follow-up); and the on-chain network-fee leg would need a separate exact-fee column + fee-wei plumbing through getPayoutCompletionData (payout_order has a single amountBaseUnits for the main amount) → deferred, fee legs continue to derive.

All additive / fail-open. Verified on the build host (tsc, eslint, prettier, affected accounting/payin/payout/blockchain suites, migration on PG16, DI boot Node 20).

[TaprootFreak]

Stage 2 — on-chain SWAP & BRIDGE legs wei-exact

Extends the Stage-1 wei-exact pattern (deposits/withdrawals) to the on-chain swap and bridge legs. Strictly additive + fail-open throughout; no existing float behaviour changes.

Exact-available (captured and booked verbatim into the Stage-1 amountBaseUnits override):

• trading_order (§4.9 arbitrage swap, EVM): amountOut = raw on-chain swap-output transfer wei (EvmClient.getSwapResultBaseUnits); amountIn = broadcast-exact (EvmUtil.toBroadcastBaseUnits).
• liquidity_order (§4.8a DfxDex purchase, EVM): targetAmount = raw swap wei (kept only when purchased() booked the on-chain output, not the reference==target override); swapAmount = broadcast-exact.
• liquidity_management_order bridge (§4.8): LayerZero deposit = raw arrival transfer wei; dEURO bridge-in = 1:1 broadcast wei in the booked-target decimals. Booked on BOTH bridge legs (wallet +X / TRANSIT −X) so the same-currency ASSET+TRANSIT pair nets to 0n and passes assertNativeBalance (overriding only the wallet leg would leave the TRANSIT counter float-derived → a >8-dp mismatch would fail-closed-throw).

Honest deferrals (fail-open → the ledger derives from the ≤8-dp float; no precision faked):

• EVM L2 bridges (Base/Arbitrum/Optimism/Polygon): outputAmount is floored to 8 dp before broadcast (evm-l2-bridge.adapter Util.floor(..., 8)) → the float derivation is already wei-exact, nothing finer to capture.
• Clementine bridge / Boltz (BTC, ≤8 dp): derived value already exact.
• LayerZero withdraw completion: only the deposit side is captured (transfer asset == booked target); the withdraw release is on Ethereum while the booked target is the rule target → decimals alignment not guaranteed → deferred.
• Fee/gas legs (trading & DEX network-fee): no finer on-chain truth used; booked from float.
• Non-EVM DEX & DfxDex SELL: PurchaseStrategy is EVM-only (non-EVM uses NoPurchaseStrategy); the SELL path has no active caller → fail-open.

Verified on m5me (Node 20): tsc/eslint/prettier clean; affected suites green (evm.util, evm-client, ledger-booking, trading/liquidity-order-dex/liquidity-mgmt consumers — 10 suites / 304 tests); migration up/down on a throwaway Postgres 16 (5 nullable numeric columns, 18-dp wei round-trips exactly); DI boot reaches the JwtStrategy env wall. CI on PR #4288 green (Build and test + migration-check + CodeQL).

[TaprootFreak]

Stage 3 (exchange-sourced amounts): investigated → no code change (honest source ceiling)

Goal: make EXCHANGE-sourced amounts (exchange_tx: ccxt Kraken/Binance/MEXC + Scrypt) source-exact, matching the wei-exact on-chain stages.

Finding: exchange amounts are already source-exact at the existing ≤8-dp-derived base units. No finer source exists, so no plumbing was built — building it would be fake precision.

Evidence chain:

1. ccxt hands DFX a JS float, not an exact string. Trade.amount, Trade.cost, Transaction.amount are all typed Num = number | undefined (a JS float) — node_modules/ccxt/js/src/base/types.d.ts:1-5,92. The mapper reads exactly those float fields: src/integration/exchange/mappers/exchange-tx.mapper.ts:24,42,66-67 (amount: d.amount / t.amount, cost: t.cost), and they land in float columns on the entity (src/integration/exchange/entities/exchange-tx.entity.ts:37,83). ccxt is not configured with number: String; its default number handler is Number (verified exchange.number === Number on m5me), so ccxt collapses even a 15-dp raw response string to a float before DFX ever reads .amount.

2. The raw exchange string (ccxt info, or Scrypt Quantity) is at market precision ≤8 dp for every asset DFX trades (Kraken EUR/CHF/USD/BTC/USDT/USDC/ETH/DAI; Binance BTC/USDT; MEXC ZCHF/XMR/USDT/ZANO/fUSD; + fiat) — the earlier stage-1/2 finding, unchanged. There is no >8-dp reported quantity to preserve.

3. The existing float→base-unit derivation is already exact for a ≤8-dp source. Exchange legs never set an amountBaseUnits override (exchange-tx.consumer.ts sets only account/amount/priceChf/amountChf/needsMark), so they take the float path toBaseUnits(leg.amount, decimals) capped at min(decimals, 8) (src/subdomains/core/accounting/services/ledger-booking.service.ts:399, src/shared/models/base-units.transformer.ts:29). toBaseUnits uses amount.toFixed(8), which recovers the exact ≤8-dp decimal regardless of float binary error (error ≪ 1e-8 at realistic magnitudes) — verified on m5me: 0.12345678, 1234.87654321, 0.00000001 all round-trip exactly. Capturing the raw info string via fromDecimalString would therefore yield identical base units.

4. The exchange amount is always the definitive value for its own leg (Q3). An exchange leg is the exchange custody balance (ASSET/{exchange}/{ccy}), whose source of truth is the exchange own ≤8-dp report — there is no finer on-chain sibling for that leg. A withdrawal to a DFX wallet books a separate on-chain payin leg on a different account, already wei-exact via Stage 1; the two never share a leg.

Decision: exchange-sourced amounts are ≤8 dp at the source (ccxt delivers ≤8 dp / float), so the existing 8-dp-derived base units are already source-exact — no code change. This is the honest source ceiling for exchange legs; only the on-chain side (Stages 1–2) had a finer source (18-dp wei) that the float would lose.