Tezos blockchain is constantly growing and more and more people discover it and come into the ecosystem. Tezos stands out for its unique features which no one has successfully repeated so far, and the most exciting of them is on-chain governance (aka self-amending) that allows to flawlessly upgrade the Tezos protocol.

This great feature results in continuous protocol updates, so that we as developers of the Tezos blockchain indexer and the Tezos explorer have to reflect these updates and improvements and keep all our products up to date to let people use it without a hitch.

Last week, after the quorum for testing the latest Edo proposal had been reached, we released v1.3.1 of the TzKT indexer with Edo support and some new features added to the TzKT explorer and API. In this article we will highlight the changes.

Breaking bad changes in the API

First of all, please note, there are a few breaking changes in the TzKT API:

• in ballot and proposal operations:
  • ballot.period.id is deprecated and will be removed in the next major release. Use ballot.period.index instead;
  • ballot.period.startLevel is deprecated and will be removed in the next major release. Use ballot.period.firstLevel instead;
  • ballot.period.endLevel is deprecated and will be removed in the next major release. Use ballot.period.lastLevel instead.
• in proposals:
  • proposal.period is deprecated and will be removed in the next major release. Use proposal.firstPeriod instead;
  • proposal.upvotes now returns a number of upvotes rather than rolls. If you need the number of rolls, look at proposal.rolls.

There is nothing to worry about as these fields are only deprecated for now, not removed, so nothing should break actually. However, if you rely on anything of that, please, consider updating your code as soon as possible.

The most relevant API documentation is always available on api.tzkt.io. Feel free to reach us in our telegram chat or in Tezos dev slack with any questions.

Edo support

Starting from v1.3.1 TzKT indexer completely supports Edo protocol.

Edo brings a lot of significant improvements in Michelson such as Sapling, enabling privacy-preserving transactions on Tezos, and Tickets, enabling authenticating data with respect to a Tezos address.

In addition, it brings a new voting period called "adoption" that provides sufficient lead time for existing projects to prepare for the protocol upgrade, after the actual voting ended and the proposal was finally accepted by bakers.

Also, we have launched an explorer for the Edonet network: edonet.tzkt.io.

Introducing voting epochs

As we know Tezos on-chain governance process consists of 4 (5, in Edo) phases (or voting periods): proposal, exploration, testing, promotion (and adoption, in Edo). Read more about it here. So, looking at the voting process, we realized that it would be better to group these voting periods into so-called voting epochs, to make the exploration of the Tezos on-chain governance more comfortable.

In fact, voting epochs have been implemented in the TzKT indexer since the very beginning, and in v1.3.1 we finally added API endpoints to access it:

• /v1/voting/epochs - get all epochs (example);
• /v1/voting/epochs/{index} - get epoch by index (example);
• /v1/voting/epochs/current - get current epoch (example);
• /v1/voting/epochs/latest_voting - get the latest epoch where at least one proposal was injected (example).

Each voting epoch may have various statuses, depending on the epoch's state/result:

• no_proposals - there were no proposals proposed;
• voting - there was at least one proposal and the voting is still in progress;
• completed - the voting successfully ended and the proposal was accepted;
• failed - the voting process was interrupted due to either quorum or supermajority wasn't reached.

NOTE

By the way, ballot and proposal operations can now be selected/filtered by epoch, not only by period, so that you can get more data in a single request rather than making several requests followed by merging.

Voting period statistics

Voting period models have been reworked so that each period kind has some statistics and contains only appropriate fields.

Here are some statistics of the proposal period:

{
  "totalBakers": 422,       // total number of listed voters
  "totalRolls": 84961,      // total number of voters' rolls
  "upvotesQuorum": 5,       // percentage of the total rolls needed to start the voting process
  "proposalsCount": 1,      // number of proposals injected during the period
  "topUpvotes": 66,         // number of upvotes (proposal operations) of the most upvoted proposal
  "topRolls": 9685,         // number of rolls upvoting the most upvoted proposal
  "status": "success"       // active | no_proposals | no_quorum | success
}

Here are some statistics of the exploration and promotion periods:

{
  "totalBakers": 413,       // total number of listed voters
  "totalRolls": 84105,      // total number of voters' rolls
  "ballotsQuorum": 57.64,   // quorum percentage
  "supermajority": 80,      // supermajority percentage
  "yayBallots": 159,        // number of "yay" ballots
  "yayRolls": 30220,        // number of rolls from the "yay" ballots
  "nayBallots": 0,          // =||=
  "nayRolls": 0,            // =||=
  "passBallots": 11,        // =||=
  "passRolls": 22454,       // =||=
  "status": "success"       // active | no_quorum | no_supermajority | success
}

As for testing and adoption periods, they don't (and actually shouldn't) have any of these statistics as they are non-interactive and no on-chain actions are required from the voters during these periods.

NOTE

All data models in TzKT indexer and API are designed to be minimalistic and provide only relevant data. That's why the same entities (e.g. voting periods) may have different models, depending on entity's kind (e.g. testing periods vs promotion periods). For example, quorums in testing periods are omitted as it would be rather redundant information.

This helps to save a lot of network traffic and resource usage in general.

Voters listings

We have added API endpoints to access a list of all voters for each voting period:

• /v1/voting/periods/{index}/voters - get voters at the specified voting period;
• /v1/voting/periods/current/voters - get voters at the current voting period.

Here is what a listing consists of:

{
  "delegate": {
    "alias": "Bake’n’Rolls",
    "address": "tz1NortRftucvAkD1J58L32EhSVrQEWJCEnB"
  },
  "rolls": 639,
  "status": "voted_yay"     // none | upvoted | voted_yay | voted_nay | voted_pass
}

As you can see, TzKT returns not just a snapshot of all bakers with their voting power, but also their status, showing how they acted in a particular voting period.

NOTE

By the way, you can use query filters to get, for example, only those voters who still haven't voted: .../voters?status=none, etc.

AnyOf query parameter

Another cool feature in TzKT v1.3.1, is the anyof query parameter in the operations API endpoints, allowing to do more complex data selection/filtering. So, without further ado, let's look how it works on a pretty common use case.

Imagine, you are fetching transactions of a particular account.

NOTE

As we know, there are 3 fields in a transaction object where a particular account can be met: initiator, sender and target.

So, imagine you are needing only those transactions where a particular account is either a sender or a target. What would you do?

Before v1.3.1 you would have to:

1. Request transactions with specific sender: /transactions?sender={account}.
2. Request transactions with specific target, excluding possible duplicates: /transactions?target={account}&sender.ne={account}.
3. Merge two responses.

After v1.3.1 you can do it in a more efficient way by using the anyof parameter:

1. Request transactions where either sender or target (any of them) matches the specified account: /transactions?anyof.sender.target={account}.

That's it and that's cool, isn't that? =)

Protocol parameters

The new version of the TzKT indexer comes with the better handling of the protocol parameters such as ramp_up_cycles and no_reward_cycles, so the indexer can be safely used in private chains even with absolutely weird custom protocol parameters.

In addition, we have added rampUpCycles and noRewardCycles fields to the protocol constants model, for more convenience.

Public bakers page

We have added Public Tezos Bakers page with the most relevant information about known Tezos bakers recommended for staking XTZ. So, if you are looking for a baker to delegate your tez to, this is the best place to check.

Yes, as you can see, that is an improved version of the Baking Bad Rating with full baker details. In confidence, just between us, this is a part of a larger plan for merging TzKT and BB. 🤫

Dexter trading history and statistics

Also, we have been experimenting with customization of popular Tezos smart contract accounts and added DEX trading history for Dexter contracts as well as some statistics like average trade, number of unique users, etc.

That is still an experimental feature so the chart is rather limited. Anyway, let us know if you like it so we can decide to continue working on it and add some more similar features.

Behind the scenes

We have discussed only the "visible" changes in the new version of the TzKT indexer, API and explorer, but that is actually a small part of what has been done. There was actually a lot of code refactoring and architectural optimization which is a very important part of the "long-term" development.

Conclusion

Today TzKT is the most reliable and accurate feature-rich Tezos blockchain indexer behind the unique Tezos explorer tzkt.io. TzKT is not a commercial product, but a community-driven project. It's truly open-source and free for everyone and for any use.

Every day we work hard on adding more features and that would be hardly possible without huge support from the Tezos Foundation. We are also eternally grateful to all our friends and the whole Tezos community for providing useful feedback and for helping with adoption of TzKT. You are awesome! ❤️

For the Tezos!

Cheers 🍺