TZIP-16 Contract Metadata and Views

The @taquito/tzip16 package allows retrieving metadata associated with a smart contract. These metadata can be stored on-chain (tezos-storage) or off-chain (HTTP(S) or IPFS). The package also provides a way to execute the MichelsonStorageView found in the metadata. More information about the TZIP-16 standard can be found here.

How to use the tzip16 package#

The package can be used as an extension to the well known Taquito contract abstraction.

  1. We first need to create an instance of Tzip16Module and add it as an extension to our TezosToolkit

The constructor of the Tzip16Module takes an optional MetadataProvider as a parameter. When none is passed, the default MetadataProvider of Taquito is instantiated and the default handlers (HttpHandler, IpfsHandler, and TezosStorageHandler) are used.

import { TezosToolkit } from '@taquito/taquito';
import { Tzip16Module } from '@taquito/tzip16';
const Tezos = new TezosToolkit('rpcUrl');
Tezos.addExtension(new Tzip16Module());
  1. Use the tzip16 function to extend a contract abstraction
const contract = await Tezos.contract.at("contractAddress", tzip16)
  1. Call the methods of the Tzip16ContractAbstraction class

The namespace tzip16() need to be specified when calling a method of the Tzip16ContractAbstraction class:

const metadata = await contract.tzip16().getMetadata();
const views = await contract.tzip16().metadataViews();

All other methods of the ContractAbstraction class can be called as usual on the contract object.

Get the metadata#

The getMetadata method returns an object which contains the URI, the metadata in JSON format, an optional SHA256 hash of the metadata and an optional integrity check result.

A sequence diagram can be found here.

Tezos-storage example#

Live Editor
Result

HTTPS examples#

Live Editor
Result

An example having a SHA256 hash:

Live Editor
Result

IPFS example#

Live Editor
Result

Execute off-chain views#

A sequence diagram can be found here.

In the next example, we will run a view named someJson that can be found in the metadata of the contract KT1LhUqpUGfxZaJFMrxAZ6WNAuM8FPjDLBcE. When we inspect those metadata, we can see that this view takes no parameter, has a returnType of bytes and has the following code:

"code":
[
{
"prim": "DROP",
"args": [],
"annots": []
},
{
"prim": "PUSH",
"args": [
{
"prim": "bytes",
"args": [],
"annots": []
},
{
"bytes": "7b2268656c6c6f223a22776f726c64222c226d6f7265223a7b226c6f72656d223a34322c22697073756d223a5b22222c226f6e65222c2232225d7d7d"
}
],
"annots": []
}
]

Try to run the view:

Live Editor
Result

In the next example, we will run a view named multiply-the-nat-in-storage that can be found in the metadata of the contract KT1GqWXHeeJHEHVPcqJYfKDuHkdpkJevjeAc. When we inspect those metadata, we can see that this view takes a nat has a parameter, has a returnType of nat and has the following instructions: DUP, CDR, CAR, SWAP, CAR, MUL.

Try to run the view:

Live Editor
Result

Execute a custom view#

In the next example we execute the view multiply-the-nat-in-storage in a custom way:

Live Editor
Result