diff --git a/tips/TIP-0030/examples/1-valid.json b/tips/TIP-0030/examples/1-valid.json new file mode 100644 index 000000000..e3fba3138 --- /dev/null +++ b/tips/TIP-0030/examples/1-valid.json @@ -0,0 +1,6 @@ +{ + "standard": "IRC30", + "name": "FooCoin", + "symbol": "FOO", + "decimals": 3 +} diff --git a/tips/TIP-0030/examples/2-valid.json b/tips/TIP-0030/examples/2-valid.json new file mode 100644 index 000000000..c46f92c9a --- /dev/null +++ b/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" +} diff --git a/tips/TIP-0030/examples/3-invalid.json b/tips/TIP-0030/examples/3-invalid.json new file mode 100644 index 000000000..045aecf39 --- /dev/null +++ b/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 +} diff --git a/tips/TIP-0030/irc30.schema.json b/tips/TIP-0030/irc30.schema.json new file mode 100644 index 000000000..d0d9f870f --- /dev/null +++ b/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" ] +} diff --git a/tips/TIP-0030/tip-0030.md b/tips/TIP-0030/tip-0030.md new file mode 100644 index 000000000..34110ac3f --- /dev/null +++ b/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 +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 +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](https://github.com/iotaledger/tips/pull/62). + +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](./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/).