fix(core): render token uiAmount through the account decoder

[pucedoteth]

The bug

format_ui_amount_string in crates/core/src/surfnet/locker.rs divided through f64 before formatting:

let divisor = 10u64.pow(decimals as u32);
format!("{:.decimals$}", amount as f64 / divisor as f64, decimals = decimals as usize)

An f64 mantissa holds 53 bits; a token amount holds 64. Every amount above 2^53 was rounded before it reached the client:

amount	decimals	rendered	correct
18446744073709551615	6	18446744073709.550781	18446744073709.551615
12345678901234567	6	12345678901.234568	12345678901.234567
9007199254740993	2	90071992547409.92	90071992547409.93

This is not a theoretical range. 2^53 raw units is only ~9B tokens on a 6-decimal mint, so an agent reading a supply-scale balance gets a wrong number back — the same class of defect #758 fixed for getTokenSupply, in the helpers that path didn't touch.

Both helpers additionally built their divisor with 10u64.pow(decimals), which overflows from decimals >= 20. Mint::decimals is a plain u8 with no cap in the token program, so a mint declaring 20+ decimals made this a panic in debug and a silently wrong divisor in release:

format_ui_amount_string(1, 20) -> panicked: attempt to multiply with overflow
format_ui_amount(1, 20)        -> panicked: attempt to multiply with overflow

Reachability

All four call sites pass real mint decimals, so both defects are live on RPC output:

• locker.rs:3040 — getTokenLargestAccounts
• types.rs:516, :538, :732 — pre/post token balances on getTransaction and getBlock

The fix

Defer the string to real_number_string_trimmed — the helper getTokenSupply already uses since a4acb1e (#758) — and give format_ui_amount the Option<f64> return that UiTokenAmount::ui_amount is already typed for. That mirrors solana_account_decoder::parse_token::token_amount_to_ui_amount_v3 exactly:

let ui_amount = 10_usize
    .checked_pow(decimals as u32)
    .map(|dividend| amount as f64 / dividend as f64);
(ui_amount, real_number_string_trimmed(amount, decimals))

The three types.rs call sites drop their now-redundant Some(...) wrapper.

One deliberate behaviour change: trailing zeros are no longer padded, so 1 USDC renders as "1" rather than "1.000000". That is what real_number_string_trimmed does, so it is what agave returns on mainnet and what getTokenSupply already returned here after #758 — this brings the remaining paths into line rather than away from it.

Verification

Four tests added to the existing locker.rs test module. Reverting only the production helper body — tests untouched — turns three of them red with exactly the values above:

test_format_ui_amount_string_is_exact_above_2_pow_53 ... FAILED
  left: "18446744073709.550781"   right: "18446744073709.551615"
test_format_ui_amount_string_matches_account_decoder ... FAILED
  left: "1.000000"                right: "1"
test_format_ui_amount_survives_decimals_that_cannot_form_a_divisor ... FAILED
  panicked at core/src/num/mod.rs:1274 (pow overflow)

All four pass with the fix. Full cargo test -p surfpool-core --lib: 716 passed. The test_simulate_add_alt_entries_fetching variants fail identically on a clean main at this commit (loaded_accounts_data_size 6090 vs 140134 — it fetches from mainnet), so they are pre-existing and unrelated. cargo fmt and cargo clippy clean on the changed lines.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

The PR replaces precision-losing and overflow-prone token amount formatting with the Solana account decoder’s exact string formatter and checked optional floating-point conversion.

• Uses real_number_string_trimmed for token balance strings.
• Returns None for ui_amount when the decimal divisor cannot fit in usize.
• Applies the formatting consistently to largest-account and transaction token balances.
• Adds focused tests for scaling and unsupported decimal divisors.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
crates/core/src/surfnet/locker.rs	Replaces local token string formatting with the account decoder helper and makes floating-point scaling overflow-safe.
crates/core/src/types.rs	Updates successful and failed transaction token balances to use exact decoder formatting and optional UI amounts.

_{Reviews (3): Last reviewed commit: "fix(core): render token uiAmount through..." | Re-trigger Greptile}

[MicaiahReid]

Thanks for the PR, @pucedoteth. Foundation PRs can't be merged without commit signature verification. If you can get that set up and re-push these commits, I'll review!

[MicaiahReid]

I appreciate the PR, but in future PRs please do more to distill the AI output.

[MicaiahReid]

The doc comments on these are classic over-described AI generated comments. Please distill this down to what's important. What does the function do? If you had no context, what comment would help you know what the function does, when to use it, and what to pass in?

The comment doesn't need super technical details of what's happening under the hood (the code itself explains what the code is doing). We don't need references to other PRs and how past behavior worked

[MicaiahReid]

If this function is just directly calling another - why does the function need to exist at all?

[MicaiahReid]

These tests don't seem particularly valuable, they're essentially asserting the one function has the same output as another... when the first function is just calling the other

[pucedoteth]

Fair thanks, that was too much. Addressed all three:

• Dropped format_ui_amount_string. It was a pure delegation, so the four call sites now call real_number_string_trimmed directly.
• Cut the doc comment on format_ui_amount to what it does and what None means. No PR references or history.
• Removed the tests that compared the wrapper to the function it wrapped. Kept one covering format_ui_amount itself, including the None case.

Diff is now +28/-31 instead of +125.

One thing I left alone: token_amount_to_ui_amount_v3 in solana_account_decoder builds the whole UiTokenAmount and also handles interest-bearing and scaled-UI-amount mints, which the manual construction here does not. Replacing the struct literal with that call looks like the real simplification, but it changes behaviour beyond this fix so I did not fold it in. Happy to do it here or separately if you want it.

[MicaiahReid]

thanks, @pucedoteth!