baking-bad/tzkt v1.17.3

on GitHub

General notes

• fixed restricted unicode symbols in micheline json;
• fixed token balances for addresses with entrypoints ("{address}%{entrypoint}", see explanation below).

To update from v1.17.* to v1.17.3 you can simply update the tzkt-sync and tzkt-api binaries. DB will migrate automatically.

Note for mainnet instances: there was an issue with handling token balances for addresses with entrypoints, caused corruption of 5 token balances:

• tz1SCSfKnyQGPTRbrqFyb5qnfQBhjafEMMzX, USDT;
• tz1cr3HGB8KsAQ8sYE9vFhGWxqdXsdd8vL4K, USDT;
• tz1cHRzK7yMSvbMev7YsFB7pYJ9pW7NskLzD, USDT;
• tz1dbFkLhJuU3LFf8UdRt58hyVjd22zebFPe, USDT;
• tz2Hoa2EJoKtL9BDvNWtr62wne53SEBnNdxC, USDT.

So, if you don't care about those 5 balances, you can simply update the binaries as mentioned above. Otherwise, you will also need to restore the DB from the fresh snapshot, or re-index from scratch.

What is a token balance of an "address with entrypoint"?

First of all, what is a token balance? Token balance is usually a key-value pair in the token contract's ledger bigmap, where "key" is roughly your address and "value" is your balance. So, when someone calls transfer with parameters {"to": "tz123", "amount": "100"}, a new record tz123: 100 is added to the ledger bigmap.

However, in Tezos an address can be extended with an optional entrypoint, for example tz123%blabla - this is also valid form, and if someone calls transfer with parameters {"to": "tz123%blabla", "amount": "100"}, a new record tz123%blabla: 100 is added to the ledger bigmap. As you can see, it's a different record, because "tz123" and "tz123%blabla" are different keys with different hashes. And two different records means two different token balances.

Therefore, token balances cannot be uniquely identified by the pair (Token, Account), but by the three (Token, Account, Entrypoint) instead. In practice it means that for a single account there can be multiple different balances of the same token (example). Keep that in mind when querying token balances from TzKT.

It's worth noting that at the moment none of widely used token contracts allow spending balances from addresses with entrypoints, so funds sent to {address}%{entrypoint} most likely become inaccessible.

Changes in the API models

• field entrypoint was added to the TokenBalance model;
• fields fromEntrypoint and toEntrypoint were added to the TokenTransfer model.

Changes in the API endpoints

• query parameter ?entrypoint was added to /tokens/balances** endpoint;
• query parameters ?fromEntrypoint and ?toEntrypoint were added to /tokens/transfers** endpoint;
• query parameters ?account in /tokens/balances** and ?anyof, ?from and ?to in /tokens/transfers** now support {address}%{entrypoint} format. For example, ?account=tz123 will return all account's balances, ?account=tz123% will return all balances where entrypoint is null, and ?account=tz123%blabla will return all balances where entrypoint is %blabla.

Commits

• c6f50d7: Remove Slack notifications (dm)
• d6e8c17: Escape restricted unicode in tx params and bigmap keys (Maksim Strebkov)
• 743f34e: Support addresses with entrypoints in token balances and transfers (257Byte)
• f6aefc7: Sanitize all humanized micheline values (Maksim Strebkov)
• 86c3214: Update API docs (Maksim Strebkov)
• ec78a95: v1.17.3 (Maksim Strebkov)