As the Tezos blockchain migrates to its 8th protocol upgrade Hangzhou, we're updating our APIs and products to support its new features. We also introduce a few housekeeping changes. A complete changelog is available here.

This API version (v011-2021-11-20) will go live on TzStats Mainnet on Dec 3, 2021, and is already available as part of TzIndex PRO v11 and TzIndex OSS v11 releases. You can use api.staging.tzstats.com to test your integrations before we upgrade.

Important Upgrade Notice

During protocol activation on Dec 3, 6 PM UTC, the Tezos chain will halt for several minutes (up to hours) as all Tezos nodes will upgrade their databases to a new format. For details, see https://www.marigold.dev/post/upcoming-activation-of-hangzhou.

We suggest you take a walk outside, do sports, and spend some time with family while we handle the upgrade.

According to our measurements with a recent v11 full archive node, the upgrade took 1h 40m 27s. That's not optimal and we're looking into options to limit API downtime as much as possible. Although not everyone is running full archive nodes as we do, all bakers will have to go through the same upgrade process. It is expected that the Tezos network will be down for several hours and then catch up slowly.

New API features

Hangzhou introduces several new smart contract features like on-chain views, global constants, and timelocks which are all supported by the new TzStats API.

On-chain Views

On-chain views are synchronous function calls from one smart contract into another with the guarantee that the state of the callee is immutable (read-only). Like in regular programming languages, arguments and return values are exchanged over the stack, and in a typical Tezos manner, views define the type-safe interface plus the code that is executed.

To separate view definitions from other parts of the script, a new top-level key view is introduced (extending the current list of keys from parameter, storage, and code). In the Micheline Binary/JSON encoding, views are individually appended to the top-level code section of the script rather than as a sub-tree like other elements. This makes parsing more awkward.

"code": [{
    "prim": "parameter",
    "args": [...]
},{
    "prim": "storage",
    "args": [...]
},{
    "prim": "code",
    "args": [...]
},{
    "prim": "view",
    "args": [...]
},{
    "prim": "view",
    "args": [...]
}]
Views in Tezos script
{
    "script": {...}
    "storage_type": {...}
    "entrypoints": {
        "<name>": {
            "code": 0,
            "call": "<name>,
            "branch": "...",
            "type": {...}
        }
        ...
    }
    "views": {
        "<name>": {
            "type": {...}
            "code": [...]
        }
        ...
    }
}
Views on TzStats API (Hangzhou Testnet) https://api.hangzhou.tzstats.com/explorer/contract/KT19QWzjyByTBmGdz5RbENdkiKNXUpnSNbnN/script

Global Constants

Global constants are Micheline macros (i.e. bytecode macros replaced by the Tezos VM during runtime) that are registered on-chain. New contracts can reference global constants to effectively replace and outsource expensive parts of their code, interface, or storage type definitions. It's a nice way to build a global permissionless library of reusable code and type fragments.

Like bigmap keys, constants are content-addressable through an expression hash expr..., but other than that they are regular Micheline encoded primitive trees. It's important to know that constants can reference other constants.

We have added the following new features to the API

  • a new endpoint /tables/constant for raw constant table access
  • a new endpoint /explorer/constant/{hash} to access a constant by content hash
  • global constants are automatically replaced (recursively) in new originated contracts
{
    "address": "exprtjHnBSvTDdYbKQdc2qcUNgfLeXHzzgtWXxGpumCPGwKtW7X7ex",
    "creator": "tz2P5R77hyxYBXpfghy3cxXWWHrXvj2m4uGb",
    "height": 16596,
    "time": "2021-11-08T21:56:49Z",
    "storage_size": 80,
    "value": {
        "annots":["%1ce292"],
        "args":[{
            "prim":"nat"
        }],
        "prim":"list"
    },
    "features":[]
}
Constants on the TzStats API (Hangzhou Testnet) https://api.hangzhou.tzstats.com/explorer/constant/exprtjHnBSvTDdYbKQdc2qcUNgfLeXHzzgtWXxGpumCPGwKtW7X7ex

Timelocks

Right now there's not much to see other than new Michelson types and data structures added. We didn't attempt to decode data or otherwise add API endpoints for this feature and are exploring further support.

Stay safe and happy hacking!