Balances doc-sync and test/comment fixes

Author: dronbas

crates/application/src/lib.rs

@@ -5108,8 +5108,9 @@ mod get_market_balances_use_case_tests {
     // holding of 12.5 NACKL is `12_500_000_000` atoms and must render as ~12.5,
     // not 125_000_000. Scaling atoms by `quantity_precision` (2) instead of the
     // full `decimals` over-reports by 10^(9-2).
-    // `happy_path_sums_three_pools_per_outcome` can't catch that — its small
-    // synthetic inputs sit far below atom scale — so this feeds realistic ones.
+    // A small-synthetic-input happy path can't catch that — its inputs sit far
+    // below atom scale, where the 10^(9-2) error is invisible — so this feeds
+    // realistic atom-scale values.
     #[tokio::test]
     async fn market_balances_free_not_overscaled_for_real_atoms() {
         let stake = PnStake {
@@ -5131,12 +5132,8 @@ mod get_market_balances_use_case_tests {
             })
             .await
             .expect("ok");
-        let free = &out.balances[0].free;
-        let val: f64 = free.parse().expect("free parses as a number");
-        assert!(
-            (val - 12.5).abs() < 1e-6,
-            "outcome free over-scaled: got {free} (expected ~12.5 tokens for 12.5e9 atoms at decimals=9)"
-        );
+        // Exact: 12_500_000_000 atoms / 10^9 → "12.500000000" (not 125_000_000).
+        assert_eq!(out.balances[0].free, "12.500000000");
     }
 
     // Same over-scale on the `locked_in_orders` column, which is summed from
@@ -5162,17 +5159,13 @@ mod get_market_balances_use_case_tests {
             })
             .await
             .expect("ok");
-        let locked = &out.balances[0].locked_in_orders;
-        let val: f64 = locked.parse().expect("locked parses as a number");
-        assert!(
-            (val - 20.0).abs() < 1e-6,
-            "outcome locked over-scaled: got {locked} (expected ~20 tokens for 20e9 atoms at decimals=9)"
-        );
+        // Exact: 20_000_000_000 atoms / 10^9 → "20.000000000" (not 200_000_000).
+        assert_eq!(out.balances[0].locked_in_orders, "20.000000000");
     }
 
     // Golden-fixture regression (captured live on the local stack): a
     // `buyFullSet` at the market price splits collateral into outcome amounts
-    // of full-`decimals` precision, OFF the quantity_precision grid — 25 NACKL
+    // of full-`decimals` precision, OFF the quantity_precision grid — ~25 NACKL
     // → 11_567_164_168 / 13_432_835_808 atoms. Scaling by `quantity_precision`
     // would over-report (→ "115671641.68"); a grid-strict descale to the qp
     // lattice would have to drop non-zero low digits. Scaling by the full

crates/chain/src/client.rs

@@ -104,8 +104,8 @@ impl Dex {
     /// Buy a full set of outcome tokens by depositing `collateral` of
     /// the market's quote asset into the PMP. On a market sitting in
     /// `AWAITING_FREEZE`, the first successful call also activates the
-    /// OrderBook for everyone else. See
-    /// `docs/tech-specs/write-api.md §POST /api/v1/buyFullSet`.
+    /// OrderBook, after which it stays active for all subsequent callers.
+    /// See `docs/tech-specs/write-api.md §POST /api/v1/buyFullSet`.
     pub async fn split_full_set(
         &self,
         pn_address: &str,

crates/infrastructure/src/postgres_repo.rs

@@ -1064,8 +1064,17 @@ impl MarketReadRepository for PostgresReadModelRepository {
             );
             anyhow!(DomainError::MarketInconsistent)
         })?;
-        // <= MAX_DECIMAL_PRECISION (38) always fits u8.
-        let decimals = decimals_scale as u8;
+        // Total conversion: validate_decimal_scale already capped this at
+        // MAX_DECIMAL_PRECISION (38). Checked rather than `as u8` so a future
+        // cap raised above 255 can't silently truncate.
+        let decimals = u8::try_from(decimals_scale).map_err(|_| {
+            tracing::warn!(
+                pmp = %market_address.0,
+                raw = decimals_scale,
+                "decimals exceeds u8 after scale validation — read-model corruption"
+            );
+            anyhow!(DomainError::MarketInconsistent)
+        })?;
 
         // `oracle_list_hash` is nullable at the schema level (pre-reconcile),
         // but we already gated on last_reconciled_at IS NOT NULL — a NULL here

crates/infrastructure/tests/balances.rs

@@ -451,6 +451,55 @@ async fn resolve_market_for_balances_negative_token_type_fails_closed() {
     assert!(matches!(dom, dodex_domain::DomainError::MarketInconsistent));
 }
 
+#[tokio::test]
+async fn resolve_market_for_balances_decimals_above_max_fails_closed() {
+    // The resolve path validates the joined `ref_tokens.decimals` via
+    // validate_decimal_scale (cap MAX_DECIMAL_PRECISION = 38), NOT a bare
+    // u8::try_from (which would admit up to 255). 39 sits in that gap, so it
+    // distinguishes the two validators: it must lift to MarketInconsistent
+    // rather than be handed to scale_decimal, where the over-cap scale would
+    // blow up the allocation.
+    let Some(pool) = setup().await else { return };
+    let pmp = "0:dec-overmax-bal-pmp";
+    let ob = "0:dec-overmax-bal-ob";
+    sqlx::query("delete from markets where pmp_address = $1")
+        .bind(pmp)
+        .execute(&pool)
+        .await
+        .unwrap();
+    // Sentinel ref_tokens row with an out-of-cap decimals (39). All `not null`
+    // columns filled; only `decimals` is read by the code under test.
+    sqlx::query(
+        r#"insert into ref_tokens (
+              token_type, token_code, decimals,
+              min_notional, lot_size, tick_size_bps,
+              price_precision, quantity_precision)
+                values (39039, '__DEC39__', 39,
+                        0::numeric, 0::numeric, 0::numeric, 0, 0)
+           on conflict (token_type) do nothing"#,
+    )
+    .execute(&pool)
+    .await
+    .unwrap();
+    sqlx::query(
+        r#"insert into markets (
+              pmp_address, name, token_type, token_code, event_id, oracle_list_hash,
+              orderbook_address, num_outcomes, last_reconciled_at)
+           values ($1, 'dec-overmax', 39039, '__DEC39__', 42::numeric, 24::numeric,
+                   $2, 1, now())"#,
+    )
+    .bind(pmp)
+    .bind(ob)
+    .execute(&pool)
+    .await
+    .unwrap();
+
+    let repo = PostgresReadModelRepository::new(pool.clone());
+    let err = repo.resolve_market_for_balances(&MarketAddress(pmp.to_string())).await.unwrap_err();
+    let dom = err.downcast_ref::<dodex_domain::DomainError>().expect("DomainError");
+    assert!(matches!(dom, dodex_domain::DomainError::MarketInconsistent));
+}
+
 #[tokio::test]
 async fn resolve_for_new_order_negative_outcome_id_fails_closed() {
     // market_outcomes.outcome_id has no CHECK constraint enforcing non-negative.

docs/api-spec.md

@@ -628,14 +628,14 @@ Response:
     {
       "outcomeId": 0,
       "symbol": "PM-2026-ELECTION-NO",
-      "free": "10.00",
-      "lockedInOrders": "0.00"
+      "free": "10.000000000",
+      "lockedInOrders": "0.000000000"
     },
     {
       "outcomeId": 1,
       "symbol": "PM-2026-ELECTION-YES",
-      "free": "5.50",
-      "lockedInOrders": "1000.00"
+      "free": "5.500000000",
+      "lockedInOrders": "1000.000000000"
     }
   ]
 }
@@ -650,8 +650,8 @@ Response fields:
 | `balances` | ARRAY | One entry per outcome of the market, sorted by `outcomeId` ascending. Length equals the market's `outcomes[]` length in `/api/v1/markets`. |
 | `balances[].outcomeId` | INT | Stable outcome id; matches `outcomes[].outcomeId` from `/api/v1/markets`. |
 | `balances[].symbol` | STRING | Outcome-token symbol; matches `outcomes[].symbol` from `/api/v1/markets`. |
-| `balances[].free` | DECIMAL | Outcome tokens currently held by the trading PrivateNote across clean, debt, and coupon stake pools, scaled by the outcome's `quantityPrecision`. |
-| `balances[].lockedInOrders` | DECIMAL | Outcome tokens locked in resting SELL orders on this outcome, scaled by the outcome's `quantityPrecision`. |
+| `balances[].free` | DECIMAL | Outcome tokens currently held by the trading PrivateNote across clean, debt, and coupon stake pools, scaled by the quote asset's on-chain `decimals` (same scaling as `/api/v1/account`). |
+| `balances[].lockedInOrders` | DECIMAL | Outcome tokens locked in resting SELL orders on this outcome, scaled by the quote asset's on-chain `decimals`. |
 
 Errors:
 

docs/tech-specs/read-api.md

@@ -414,7 +414,7 @@ Returns the caller's outcome-token holdings for one market. `free` comes from a
 
 Three inputs feed one response:
 
-1. **Market resolution.** Two SELECTs (one on [`markets`](data-schema.md#markets), one on [`market_outcomes`](data-schema.md#market_outcomes)) return `(event_id, oracle_list_hash, token_type, orderbook_address, num_outcomes, [(outcome_id, symbol, quantity_precision) …])`. The first is gated on `last_reconciled_at IS NOT NULL`; pre-reconcile markets are hidden symmetrically with `/api/v1/markets`. The market lifecycle status is NOT a gate — terminal markets still serve balances so holders can see what they own until they claim or settle. Splitting into two SELECTs keeps the row types simple at the cost of one extra round trip; the per-request volume is low enough that the JOIN form is not worth the type-erasure pain.
+1. **Market resolution.** Two SELECTs (one on [`markets`](data-schema.md#markets) INNER-joined to [`ref_tokens`](data-schema.md#ref_tokens) for the quote-asset `decimals`, one on [`market_outcomes`](data-schema.md#market_outcomes)) return `(event_id, oracle_list_hash, token_type, orderbook_address, num_outcomes, decimals, [(outcome_id, symbol, quantity_precision) …])`. The first is gated on `last_reconciled_at IS NOT NULL`; pre-reconcile markets are hidden symmetrically with `/api/v1/markets`. The `ref_tokens` join cannot hide a market: `markets.token_type` is `NOT NULL` and FK-references the statically seeded `ref_tokens` PK, so it is a strict 1:1. The market lifecycle status is NOT a gate — terminal markets still serve balances so holders can see what they own until they claim or settle. Keeping the per-outcome rows in a separate SELECT keeps the row types simple at the cost of one extra round trip.
 2. **PN stake state.** The chain-side accessor is the auto-generated getter for the public mapping `PrivateNote._stakes`. TVM Solidity auto-getters for public mappings take no arguments and return the entire `map(uint256 → StakeInfo)` — see the PN ABI under `contracts/abi/dex/PrivateNote.abi.json`. The API computes the per-market key `stake_hash = tvm.hash(abi.encode(event_id, oracle_list_hash, token_type))` — the same hash the PN itself uses internally — and looks it up on the returned map. The hash is built off-chain in Rust via a thin wrapper around `tvm_types`. Each `StakeInfo` value carries three parallel `uint128[]` arrays (`amount`, `debtAmount`, `couponsAmount`) indexed by `outcome_id`, plus housekeeping fields the API ignores. A missing key on the returned map (caller never staked on this market) is treated as "all outcomes at zero", not as an error.
 
    Returning the whole mapping in one call costs the same as one keyed lookup would on EVM (the ABI shape is fixed by TVM Solidity), so this is an opportunity, not a tax: a future "all my outcomes" view across markets needs no additional chain calls.
@@ -442,8 +442,8 @@ Three inputs feed one response:
    - Fetch the PN BOC and run the `_stakes` getter through `tvm_runner` (returns the full `map(uint256 → StakeInfo)`); the API then looks up `map[stake_hash]`.
    - Run the `live_orders` aggregation SELECT.
 6. Build `balances[]` in `outcome_id` ASC order. For each outcome:
-   - `free = scale(amount[outcome_id] + debtAmount[outcome_id] + couponsAmount[outcome_id], quantity_precision)`. The three pools are summed because the public surface is "what the user owns" — clean, debt-bound, and coupon-bound stakes are all the user's tokens; the distinction is internal accounting that the UI does not need at this layer.
-   - `lockedInOrders = scale(coalesce(SUM, 0), quantity_precision)` from the aggregation map; outcomes without a row default to 0.
+   - `free = scale(amount[outcome_id] + debtAmount[outcome_id] + couponsAmount[outcome_id], decimals)`. Scaled by the quote asset's on-chain `decimals` (not `quantity_precision`) — the `_stakes` amounts are chain atoms, the same scale `/api/v1/account` uses; scaling by `quantity_precision` would over-report by `10^(decimals − quantity_precision)`. The three pools are summed because the public surface is "what the user owns" — clean, debt-bound, and coupon-bound stakes are all the user's tokens; the distinction is internal accounting that the UI does not need at this layer.
+   - `lockedInOrders = scale(coalesce(SUM, 0), decimals)` from the aggregation map (the `live_orders` amounts are chain atoms too); outcomes without a row default to 0.
 7. Capture `now_ms` once in the handler before executing the use case — surfaces as `updateTime`.
 
 ### Locked source split

docs/tech-specs/write-api.md

@@ -681,7 +681,7 @@ _Implementation tech spec to be filled in._
 
 ## `POST /api/v1/buyFullSet`
 
-Buys a full set of outcome tokens for one market by depositing `collateral` of the market's quote asset into the PMP. The chain entry point is `PrivateNote.splitFullSet`; on a market sitting in `AWAITING_FREEZE` the first successful call also activates the OrderBook for everyone else. From the caller's standpoint the request and response are identical to any later call against the same market.
+Buys a full set of outcome tokens for one market by depositing `collateral` of the market's quote asset into the PMP. The chain entry point is `PrivateNote.splitFullSet`; on a market sitting in `AWAITING_FREEZE` the first successful call also activates the OrderBook, after which it stays active for all subsequent callers. From the caller's standpoint the request and response are identical to any later call against the same market.
 
 The handler runs three phases: request parsing → market resolution + status gate → collateral validation + chain submission. Each phase fails closed with its own error code (see [Error mapping](#error-mapping-3)).