IntersectMBO / IntersectMBO/evolution-sdk
Koios provider: lovelace fields will change from strings to numbers in Koios v1.5
- Dominant language
- TypeScript
- Stars
- 22
- Forks
- 30
- Avg merge
- 5h 29m
- Merged PRs (30d)
- 12
Description
Koios plans to change how it sends lovelace amounts. Today they come as strings (`"2000000"`). From Koios v1.5.0 they will come as JSON numbers (`2000000`). This is a breaking change on their side, with no date yet:
- the caution note in the [v1.4.2 release](https://github.com/cardano-community/koios-artifacts/releases/tag/v1.4.2)
- cardano-community/koios-artifacts#412
- cardano-community/koios-artifacts#296
**Why it matters for evolution-sdk**
The Koios provider schemas expect strings for these fields. Some examples in `sdk/provider/internal/Koios.ts`:
- protocol parameters: `key_deposit`, `pool_deposit`, `coins_per_utxo_size`, `drep_deposit`, `gov_action_deposit`, `min_utxo_value`, `min_pool_cost`
- UTxOs: `value` and asset `quantity`
- address balance, account `rewards_available`, and tx `fee` / `deposit`
I took today's mainnet `/epoch_params` response and turned those seven fields into numbers. Decoding it with `ProtocolParametersSchema` then fails:
```
gov_action_deposit: NumberFromString — Encoded side transformation failure
```
So once Koios v1.5 is live, `getProtocolParameters()` will fail. So will building a transaction that relies on it. I expect the other calls above to fail the same way.
Accepting numbers is not enough on its own. Some lovelace values are bigger than 2^53, like the stake totals. `JSON.parse` rounds those without any error.
**Possible directions**
- Ask Koios for text directly: adding `::text` in `select` works today and should keep working after v1.5. For example, `?select=epoch_no,key_deposit::text`. Koios suggests this in their release note. I checked on mainnet: with their preview flag `_lovelace_numeric=true`, `active_stake` comes back as a number, and `active_stake::text` turns it back into a string.
- Or read the JSON in a way that keeps big numbers exact.
- Tests with numbers in these fields would catch the change before Koios ships it.
Contributor guide
Research direction
Start in sdk/provider/internal/Koios.ts and trace ProtocolParametersSchema through getProtocolParameters(), then inspect the schemas for UTxOs, balances, rewards, fees, and deposits. Reproduce the failure with numeric lovelace fields, compare the payload-preserving approaches described in the issue, and add tests using numbers in all affected fields. Done means these responses decode without precision loss.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, testing
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100