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

[mpizenberg]

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
• Ordering /pool_list on active_stake sorts lexicographically, so the list is not in stake order cardano-community/koios-artifacts#412
• Horizontal Filtering on UTxO Lovelace Value 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.