IntersectMBO / IntersectMBO/evolution-sdk

Koios provider: lovelace fields will change from strings to numbers in Koios v1.5

Open
#539 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.