Use token decimals for display amounts

[krsnak]

Closes #181

Summary

• format token amounts using each token's cached decimals
• preserve the existing 7-decimal output when metadata is unavailable
• use a synchronous cache-only decimals lookup so read paths never trigger DB/RPC work
• cover REST, GraphQL, WebSocket, account summaries/balances, popular assets, CSV and Parquet exports
• add regression tests for 6-decimal tokens, default 7-decimal formatting, and cache-miss behavior

Validation

• npm run typecheck
• npm run build
• full Jest suite: 447/447 tests passing
• git diff --check

Note: the repository's issue description states the existing integration/load CI failures predate this issue.

[drips-wave]

@krsnak Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[krsnak]

Hi, just a quick note as Wave 9 is close to ending: this PR is ready for review. Local validation is green (typecheck, build, 447/447 Jest tests, diff check), and GitHub reports the PR as mergeable. The CI/Chaos workflows are currently in action_required, which looks like they need maintainer approval to run for this fork PR. Thanks!

[Miracle656]

Good shape overall, and the most important thing is right: nothing rounds before storage. TokenTransfer.amount stays the raw i128 decimal string (prisma/schema.prisma:43), src/amount.ts is pure BigInt string arithmetic with no float anywhere, and displayAmount is a derived field computed at the response edge. Extracting the four copy-pasted STROOPS helpers (api.ts, db.ts, routes/accounts/transfers.ts) into one src/amount.ts is the right call, and adding contractId to prismaSelect when displayAmount is requested was a sharp catch.

Verified locally: npx tsc --noEmit and tsc -p tsconfig.test.json clean, full jest suite 43 suites / 508 tests, all passing on the merge of this branch with main.

Two things to fix before I merge, both about where the decimals come from.

1. In API-only mode there are no decimals at all — the feature is a silent no-op

getCachedTokenDecimals reads the in-memory cache in src/tokenCache.ts. That cache is populated by initTokenCache, and initTokenCache has exactly one non-test caller: src/indexer.ts:438, inside startIndexer. src/index.ts:69 skips startAllIndexers() entirely when SKIP_INDEXER=true.

So on an API-only deployment the cache is empty for every contract, getCachedTokenDecimals returns undefined for every row, and every single displayAmount falls back to DEFAULT_TOKEN_DECIMALS = 7 — i.e. exactly main's behaviour, with none of the new machinery doing anything. A 6-decimal token renders 10× off and nothing in the response says so. That is the failure mode the schema comment on TokenMetadata warns about in so many words: "a wrong decimals silently rescales every amount rendered from it by orders of magnitude."

Either seed the cache in API-only mode (call initTokenCache for each enabled network from src/index.ts regardless of SKIP_INDEXER, it is a single findMany), or have the API read decimals from TokenMetadata rather than from a cache only the indexer fills. The first is much cheaper. Either way, please add a test that exercises the path with the cache populated and asserts a 6-decimal token renders with 6 decimals through an actual route, not just through toDisplayAmount directly — src/__tests__/amount.test.ts only tests the formatter in isolation, so it would still pass with the whole wiring disconnected.

2. src/api.ts withDisplay clobbers the value db.ts just computed correctly

queryTransfers/queryAllTransfers now compute displayAmount with the right decimals via the tokenDecimals callback. But every route then re-maps the result:

transfers: result.transfers.map((transfer) => {
  if (transfer && typeof (transfer as { amount?: unknown }).amount === "string") {
    return withDisplay(transfer as { amount: string; contractId?: string }, network);
  }
  return transfer;
}),

and withDisplay overwrites displayAmount unconditionally, reading transfer.contractId. With ?$select=amount,displayAmount, projectRecord (src/lib/odata.ts:216) only copies the selected fields, so contractId — which you correctly made Prisma fetch — is projected out before this map runs. withDisplay therefore sees no contractId, falls back to 7, and replaces the correct value. Not a regression against main, but it silently defeats this PR for $select callers. Easiest fix is to not overwrite a displayAmount the query layer already produced, or to carry the resolved decimals alongside the row instead of re-deriving from contractId.

Minor, no action needed unless you want to: the fallback to 7 is completely silent. It may be worth a debug log or a counter the first time a contract's decimals are missed, so "my amounts look 10× wrong" is diagnosable from the outside.

Nice refactor — it just needs the data to actually be there.

https://claude.ai/code/session_01USgemLt4Rnz4SGB1Srf3GB

[krsnak]

Addressed both requested changes in commit 2bf3046.
API-only mode now seeds token decimals correctly, and displayAmount is no longer overwritten after $select projection. Added route-level regression coverage as well. Full Jest suite passes: 448/448 tests.

[Miracle656]

Both requested changes are done. Checking each against the new commit (2bf3046):

1. API-only mode had no decimals — fixed, and fixed the cheap way I hoped for.

src/index.ts now calls initTokenCache for every enabledNetworks() before the indexer dispatch, so the cache is seeded whether or not SKIP_INDEXER is set. getCachedTokenDecimals therefore has real data on an API-only deployment, and the feature is no longer a silent no-op.

One thing I want to flag because it looks alarming in the diff and isn't: this commit deletes the SKIP_INDEXER early return. That is correct. main carried two guards — an early return and, further down, an if (SKIP_INDEXER) … else startAllIndexers(). The early return made that else unreachable dead code. Removing it is what lets the seed run in API-only mode, and the surviving guard still skips startAllIndexers(), so API-only mode is intact. I checked the merged file to be sure.

Also good: initTokenCache swallows its own errors, so awaiting it at the top of main() can't turn a database hiccup into an unhandled rejection and kill boot.

On the test: the new case populates the cache through initTokenCache and asserts params.tokenDecimals?.(CONTRACT_A, "testnet") === 6 through a live route. That's exactly the link that was severed, so it would now fail if the wiring came apart — which is what I was asking for. It's fair to note db is mocked in this suite, so the "1.000000" string is handed in rather than computed; the formatter itself is covered separately in amount.test.ts. Between the two, the path is pinned. Good enough.

2. withDisplay clobbering the query layer's value — fixed. transfer.displayAmount ?? toDisplayAmount(…) preserves what db.ts computed with the right decimals, and the ?$select=amount,displayAmount case the regression test covers now round-trips correctly instead of being overwritten with a 7-decimal fallback.

Rounding, re-confirmed on the merge: still nothing before storage. src/amount.ts is pure BigInt (10n ** BigInt(d), integer division, remainder padded) — no float, no toFixed, no truncation — and it runs only at the response edge. TokenTransfer.amount stays the raw i128 string.

What I changed while merging

Your branch was cut before several things landed on main today, so I resolved this myself rather than send it back for a rebase:

• src/api.ts — import-block conflict only. #212 added httpRequestsTotal/httpRequestDurationSeconds to the ./metrics import while you added getCachedTokenDecimals and ./amount. Taken as a union; nothing overlapped.
• src/__tests__/routes/transfers.test.ts — #218 made hasMore required on the queryTransfers return type, so your new test's mocked result stopped satisfying the cast. Added hasMore: false.

queryTransfers itself auto-merged cleanly — #218's includeTotal/totalField and your prismaSelect contractId + derived displayAmount are disjoint, and I verified both survive in the merged body.

Verified on the merge result: npx tsc --noEmit and tsc -p tsconfig.test.json both clean, and jest at 47 suites / 562 tests, all passing (main's baseline is 46/557 — this adds amount.test.ts and five tests).

One note for later, no action needed: the seed runs just after server.listen, so there's a brief window at boot where a request can still get the 7-decimal fallback. Given initTokenCache degrades gracefully and blocking listen on the database would be the worse trade, I'd leave it as is — just worth knowing it exists. The silent-fallback log I mentioned last time is still worth doing someday, but not here.

Nice work, and quick. Merging.