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.
TL;DR: Developers can add a
meta=1query 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
aliasfor display metadata like name, logo, and description
assetfor asset-related metadata like symbol, decimals, standard, and homepage
bakerfor baker-related metadata like fee, status, and delegation minimums
payoutas a back-reference to the baker which can be attached to payout addresses
domainfor Tezos Domains metadata
locationfor generic location data like GPS coordinates, city, and country identifiers
mediafor media URIs
rightsfor licensing and rights info
socialfor social media handles
tz16for the most recent TZIP-16 metadata definition
tz21for 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.