At Blockwatch, we are constantly hustling to improve our services and deliver the fastest and most advanced Tezos API products to the community. After serious testing and integration work, we're finally ready to release v009-2021-04-16 of our main data API along with a flurry of new features and products. For a full list of API changes, see the changelog.

The new API is already live on https://api.staging.tzstats.com for testing your apps. We will be waiting for 2 weeks until Friday, June 4th 12PM UTC before changes go live across all our mainnet and testnet endpoints. We hope this will be enough time for everyone to update your code and avoid downtime to your services. For questions and upgrade help please join our Discord or send us an email.

You may also be interested in the first open-source release of TzGo, our new Golang Library for Tezos, the release of our TzStats-Go SDK, the official Golang library for working with data from the TzStats API, and our new Tezos RPC Service  for public and enterprise users.

Major API Changes

Back in December 2020 when Tezos Edo changed the way Micheline smart contract data is represented, in particular the controversial comb pair feature, we originally thought we had understood and handled the consequences properly. Oh boy, were we wrong! After a few painful months with broken contract data unfolding, we're finally ready to release a shiny new Micheline engine that's based on our new and open-source TzGo library. This does not only work consistently well with comb pair data, but it extracts more detail from annotated storage than ever before. In combination with our TzStats-Go SDK you can now decide if you like to fetch unfolded data from the API or if you like to fetch binary data in bulk and do the unfolding at the client-side.

Breaking Changes to Contract and Bigmap Data

As part of this release we also fundamentally reworked the data structures for bigmap keys/values, storage types, and entrypoint definitions. When we introduced these features back in 2019 we were the first Tezos API provider who supported bigmaps. Since then we have learned from many new use-cases and contract designs. Our new data structures will, unfortunately, break current implementations, but they have become more flexible, lean, and future proof. If you rely on the old data structures a little longer, they are still supported in our TzIndex OSS/PRO 9.0.x branches and TzGo 0.8.

Structured Metadata

TL;DR: Developers can add a meta=1 query argument to API requests to obtain embedded metadata (currently block, operation, account, and contract endpoints are supported) while we curate the metadata that's attached to accounts and assets using the system described below.

As new blockchain use-cases around Tokens, NFTs, DEXs, and Tezos Domains emerge there is an increasing need to attach on-chain and off-chain metadata to Tezos accounts and assets. On TzStats we have been using a curated set of off-chain metadata ourselves and have recently moved this dataset into the API for easier management.

However, metadata is fundamentally different from on-chain data, so we've been extremely hesitant to make it a first-class API citizen. Metadata is in general (1) much less structured than on-chain data, (2) poorly standardized and/or implemented, (3) hard to verify (especially when the source is off-chain), (4) may have a lifecycle that's disconnected from on-chain events and (5) based on all the above is a great source of security and interoperability nightmares.

Now that different apps have started to use metadata and a few draft proposals are being floated as TZIP, we've decided to add experimental metadata support to TzStats. We made our metadata system extensible so that we can evolve with use-cases and update to new standards. Hence we use JSON Schema descriptors internally and also export them for each model on the API (call GET /metadata/schemas for listing all known models and GET /metadata/schemas/:schema to get their JSON schema definition).

Metadata must adapt to different use-cases and we know from experience in other industries that there is no one size fits all solution. For this reason, the TzStats metadata system allows us to attach an extensible list of metadata models to any Tezos address, or in the case of assets to address plus asset-id. We created a few pre-defined models for generic use-cases like

  • alias for display metadata like name, logo, and description
  • asset for asset-related metadata  like symbol, decimals, standard, and homepage
  • baker for baker-related metadata like fee, status, and delegation minimums
  • payout as a back-reference to the baker which can be attached to payout addresses
  • domain for Tezos Domains metadata
  • location for generic location data like GPS coordinates, city, and country identifiers
  • media for media URIs
  • rights for licensing and rights info
  • social for social media handles
  • tz16 for the most recent TZIP-16 metadata definition
  • tz21 for the most recent TZIP-21 metadata definition

Using this structure we will be publishing metadata from different off-chain and on-chain sources going forward, but we will have an additional internal review process to ensure no offensive or illegal content gets published.

With the next version of TzIndex OSS/PRO our users will become able to define custom metadata models and upload their own metadata. Stay tuned for updates and have a great day.