TIP-30 Native Token Metadata Standard

tips/TIP-0030/examples/1-valid.json

@@ -0,0 +1,6 @@
+{
+  "standard": "IRC30",
+  "name": "FooCoin",
+  "symbol": "FOO",
+  "decimals": 3
+}

tips/TIP-0030/examples/2-valid.json

@@ -0,0 +1,9 @@
+{
+  "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"
+}

tips/TIP-0030/examples/3-invalid.json

@@ -0,0 +1,6 @@
+{
+  "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
+}

tips/TIP-0030/irc30.schema.json

@@ -0,0 +1,44 @@
+{
+  "$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 validating 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 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 logo of the token encoded as a byte string",
+      "type": "string"
+    }
+  },
+  "required": [ "standard", "name", "symbol", "decimals" ]
+}

tips/TIP-0030/tip-0030.md

@@ -0,0 +1,168 @@
+---
+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 <levente.pap@iota.org>
+discussions-to: https://github.com/iotaledger/tips/pull/68
+status: Draft
+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
+[draft TIP-18](https://github.com/iotaledger/tips/pull/38). Each native token is identified by its 38 bytes long
+<i>Token ID</i>, that also identifies the unique identifier of the foundry, <i>Foundry ID</i>.
+
+Given <i>Foundry ID</i>, 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](https://github.com/iotaledger/tips/pull/62).
+
+The foundry output may contain an immutable <i>Metadata Feature</i> 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 <i>Metadata Feature</i> 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](./irc30.schema.json):
+
+```json
+{
+  "$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/`](./examples) folder.
+
+To try the schema validation in Python, install [jsonschema](https://python-jsonschema.readthedocs.io/en/stable/)
+package by running:
+```bash
+pip install jsonschema
+```
+Then navigate into the folder of this TIP (`tips/TIP-0030/`) of the cloned
+[TIP repository](https://github.com/iotaledger/tips) and run the validation in console:
+```bash
+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
+
+```json
+{
+  "standard": "IRC30",
+  "name": "FooCoin",
+  "symbol": "FOO",
+  "decimals": 3,
+}
+```
+
+#### 2. A more descriptive valid token metadata JSON
+
+```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
+
+```json
+{
+  "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
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).