tip: 30
title: Native Token Metadata JSON Schema
description: A JSON schema that describes token metadata format for native token foundries.
author: Levente Pap @lzpap 
discussions-to: https://github.com/iotaledger/tips/pull/68
status: Active
type: Standards
layer: IRC
created: 2022-03-25
requires: 18

Abstract

This TIP describes a JSON schema to store native token metadata on-chain in foundry outputs.

Motivation

By introducing a standardized token metadata schema we aim to address the following problems:

  • Storing structured token metadata on-chain,
  • Interoperability of dApps, wallets and clients handling native tokens,
  • Creating the possibility of off-chain token verification based on social consensus.

Specification

Native tokens are user defined tokens controlled by foundries, as described in TIP-18. Each native token is identified by its 38 bytes long Token ID, that also identifies the unique identifier of the foundry, Foundry ID.

Given Foundry ID, the most recent unspent foundry output controlling the supply of the native token can be fetched via the UTXO indexer API defined in draft TIP 26.

The foundry output may contain an immutable Metadata Feature that holds raw binary data. By encoding metadata in JSON format adhering to the JSON schema defined in this TIP and placing it in the immutable Metadata Feature of a foundry output, issuers can supply metadata to wallets, dApps and clients on-tangle, without the need for a metadata server.

Standardizing the JSON schema for token metadata plays an important role in establishing interoperability of decentralized applications and wallets.

JSON Schema

The proposed JSON schema is located here:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/iotaledger/tips/main/tips/TIP-0030/irc30.schema.json",
  "title": "IRC30 Native Token Metadata Schema",
  "description": "A JSON schema for IRC30 compliant native token metadata",
  "type": "object",
  "properties": {
    "standard": {
      "description": "The IRC standard of the token metadata",
      "type": "string",
      "pattern": "^IRC30$"
    },
    "name": {
      "description": "The human-readable name of the native token",
      "type": "string"
    },
    "description": {
      "description": "The human-readable description of the token",
      "type": "string"
    },
    "symbol": {
      "description": "The symbol/ticker of the token",
      "type": "string"
    },
    "decimals": {
      "description": "Number of decimals the token uses (divide the token amount by 10^decimals to get its user representation)",
      "type": "integer",
      "minimum": 0
    },
    "url": {
      "description": "URL pointing to more resources about the token",
      "type": "string"
    },
    "logoUrl": {
      "description": "URL pointing to an image resource of the token logo",
      "type": "string"
    },
    "logo": {
      "description": "The svg logo of the token encoded as a byte string",
      "type": "string"
    }
  },
  "required": [
    "standard",
    "name",
    "symbol",
    "decimals"
  ]
}

Examples

The following examples are located in the examples/ folder.

To try the schema validation in Python, install jsonschema package by running:

pip install jsonschema

Then navigate into the folder of this TIP (tips/TIP-0030/) of the cloned TIP repository and run the validation in console:

jsonschema -i examples/1-valid.json irc30.schema.json

If the validation fails, error messages are printed out to the console.

1. A minimum valid token metadata JSON

{
  "standard": "IRC30",
  "name": "FooCoin",
  "symbol": "FOO",
  "decimals": 3,
}

2. A more descriptive valid token metadata JSON

{
  "standard": "IRC30",
  "name": "FooCoin",
  "description": "FooCoin is the utility and governance token of FooLand, a revolutionary protocol in the play-to-earn crypto gaming field.",
  "symbol": "FOO",
  "decimals": 3,
  "url": "https://foocoin.io",
  "logoUrl": "https://ipfs.io/ipfs/QmR36VFfo1hH2RAwVs4zVJ5btkopGip5cW7ydY4jUQBrkR"
}

3. Invalid token metadata

{
  "standard": "IRC27",
  "name": "FooCoin",
  "description": "FooCoin is the utility and governance token of FooLand, a revolutionary protocol in the play-to-earn crypto gaming field.",
  "decimals": 0.5
}

The metadata JSON is not a valid IRC30 token metadata JSON as:

  • The standard field is not IRC30
  • symbol property is missing, although it is required, and
  • decimals is not an integer.

Rationale

The main motive of this design is to allow interoperability of applications handling native tokens while also leaving room for optional, non-required fields that might be needed for certain use-cases.

Alternatively, a non-standardized token metadata structure would lead to a fragmented application space and hence worse developer and user experiences while interacting with the network.

Backwards Compatibility

IRC30 aims to be a minimum standard that can be compatible with future token standards, as long as the few originally required fields are respected.

Copyright and related rights waived via CC0.