Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Kupmios/Kupo: 64-bit UTxO amounts decoded as JS number, rounding values above 2^53

Closed
  • Is something wrong?
#454 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
58/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Quiet
Tech stack
typescript
Domain
api, backend

Research direction

Start in packages/evolution/src/sdk/provider/internal/Kupo.ts and trace Kupo responses through HttpUtils.get and the schemas before reading KupmiosEffects.ts. Reproduce the issue with the specified large lovelace and asset quantities, then verify the regression path through CoreAssets. Done means both values remain exact bigint values when the Kupo response is decoded and consumed.

Written by the indexing model from the issue text.

Description

bug external-review

Summary

The Kupo provider decodes on-chain lovelace and asset quantities as JS numbers, but a JS
number is exact only to 2^53-1. Cardano amounts are uint64, so any value above 2^53 is
silently rounded. Kupo returns these amounts as unquoted JSON integers, so the rounding
happens at JSON.parse time — before the schema — and the later BigInt(...) conversion just
preserves the already-corrupted value. Blockfrost and Koios avoid this on decode by typing the
same fields as strings. Fail closed: no fund loss; a consumer can display a wrong balance, and a
corrupted UTxO fed into evaluation produces a tx that is rejected on-chain.

Affected

packages/evolution/src/sdk/provider/internal/Kupo.ts

  • L4 ValueSchema coins: S.Number
  • L5 ValueSchema assets value: S.Number
  • L49-50 Delegation rewards/deposit lovelace: S.Number

packages/evolution/src/sdk/provider/internal/KupmiosEffects.ts

  • L79 BigInt(value.coins) // wraps an already-rounded number
  • L85 BigInt(value.assets[unit]) // wraps an already-rounded number

transport: HttpUtils.get -> response.json -> JSON.parse truncates above 2^53 before the schema runs.
Kupo API: value.coins and asset quantities are type: integer (unquoted JSON numbers), per the Kupo OpenAPI spec.
contrast (correct): Blockfrost.ts inbound quantity: Schema.String -> BigInt; Koios.ts value/quantity: Schema.String -> BigInt.

Fix

Because JSON.parse rounds before the schema, changing S.Number to a bigint schema is not
enough — the inbound amount fields need a big-int-aware JSON parser on the Kupo response
(json-bigint style, or parse coins/assets from the raw text), then carry them as bigint into
CoreAssets.fromLovelace / addByHex (drop the intermediate JS number entirely).

Regression test

  • given: a Kupo matches response with coins = 2^53+1 and an asset quantity = 2^64-1 as raw JSON integers
  • before fix: decoded amounts are corrupted (2^53+1 -> 2^53, 2^64-1 -> 18446744073709552000)
  • after fix: CoreAssets holds the exact bigint values, round-tripping unchanged
    Must FAIL on main today and PASS after the fix.

Reference

Reported informally (large-value UTxO precision loss). Related: #406 (same bug class, Ogmios outbound path).
Correction to the original triage: the report also named Blockfrost, and that is partly right —
Blockfrost is safe on decode (amounts are strings) but IS affected on its OUTBOUND evaluate
serialization (BlockfrostEffect.ts toBlockfrostValue, Number() at L89/L98). That Blockfrost
outbound path is a separate finding, tracked in its own issue.

Dominant language
TypeScript
Stars
22
Forks
31
Avg merge
3d 4h
Merged PRs (30d)
27

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from IntersectMBO/evolution-sdk

All issues in IntersectMBO/evolution-sdk

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.