From f1975da916cfd5a03a18f3ac3b7ae4f82622430d Mon Sep 17 00:00:00 2001 From: Matt Ho Date: Tue, 12 Oct 2021 06:41:57 -0500 Subject: [PATCH 1/8] initial commit --- CIP-0030/CIP-0030.md | 104 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 CIP-0030/CIP-0030.md diff --git a/CIP-0030/CIP-0030.md b/CIP-0030/CIP-0030.md new file mode 100644 index 000000000..75b74f12c --- /dev/null +++ b/CIP-0030/CIP-0030.md @@ -0,0 +1,104 @@ +--- +CIP: 30 +Title: On-Chain Token Metadata Standard +Authors: Matt Ho +Comments-URI: https://github.com/cardano-foundation/CIPs/pulls/118 +Status: Draft +Type: Standards +Created: 2020-10-12 +License: CC-BY-4.0 +--- + +# Abstract + +This specification defines a new transaction metadata label (i.e. `20`) and entry for [CIP-0030] to associate token metadata during a minting transaction. Unlike CIP-28, this +proposal is intended to define a specific schema to allow basic information about fungible tokens to be provided On-Chain. + +# Motivation + +The (Cardano Token Registry)[https://github.com/cardano-foundation/cardano-token-registry] is a centralized Off-Chain governance system to manage token +metadata. This proposal aims to provide an On-Chain solution to the same problems that will afford users a much higher degree of trust than the existing +system. + +Specifically, this proposal aims to solve for the following: + +* Provide a standardized way to associate an icon and a ticker with a token +* Provide a mechanism that allows the viewer to evaluate the trustworthiness and/or authenticity of a token + +# Specification + +Minters of tokens on the Cardano blockchain main optionally choose to associate the following transaction metadata to facilitate off-chain labeling of tokens. +When doing so, transaction metadata MUST be included in the same transaction that mints the asset id. + +> NOTE +> +> The following provides an example of the proposed on-chain metadata: +```json +{ + "20": { + "": { + "": { + "ticker": "SUNDAE", + "url": "https://dex.sundaeswap.finance/assets/{policy-id}.{asset-name}", + "desc": "SUNDAE", + "icon": "ipfs://ipfs/", + "icon-": "ipfs://ipfs/", + "decimals": 6, + "version": "1.0" + } + } + } +} +``` + +Field | | Description | +:--- | :---- | :---- | +policy-id | | token policy id | +asset-name | | hex encoded asset name | +ticker | OPTIONAL | when present, field and overrides default ticker which is the asset-name | +url | OPTIONAL | https only url that refers to metadata stored offchain. The URL SHOULD use the project domain and MUST return authenticity metadata in either html or json format (see below) | +desc | OPTIONAL | additional description that defines the usage of the token | +logo | REQUIRED | MUST be either https, ipfs, or data. logo MUST be a browser supported image format. +logo-<size> | OPTIONAL | allows teams to provide icon in different sizes. the recommended values of size are 16, 32, 64, 96, 128. logos are assumed to be square so that logo-64 would refer to a 64x64 logo +decimals | OPTIONAL | how many decimal places should the token support? For ADA, this would be 6 e.g. 1 ADA is 10^6 Lovelace +version | OPTIONAL | when not specified, version will default to `1.0` + +> NOTE +> +> The following provides an example of the alternate proposed on-chain metadata reference: + +```json +{ + "20": { + "": { + "": { + "ref": "https://assets.sundaeswap.finance", + } + } + } +} +``` + +In some cases, it is not practical or desirable to have embed the metadata on-chain. In these cases, this proposal allows the on-chain + + +Field | | Description | +:--- | :---- | :---- | +policy-id | | token policy id | +asset-name | | hex encoded asset name | +ref | REQUIRED | https only url that holds the metadata in the onchain format (see above). The URL SHOULD use the project domain and MUST return the token metadata as described above + + +### Authenticity Metadata + +To help prevent adversaries from creating fake tokens with the intent to defraud users, projects may authenticate tokens using domains they control. This +mechanism provides users a better understanding of where their tokens came from. + +The url provided in the token metadata should return content in either html or JSON format. + +* In JSON format, the url should return a JSON block of the same shape as the on-chain token metadata that includes both the policy-id and asset-name to be verified. +* In HTML format, the url should contain the a `meta` tag with `name` of `cip-30:authenticate` and a value of a comma separate list of tokens to declare as authenticate where tokens are formatted as `{policy id}{hex-encoded asset name}` with no space in between + + + + From 5cfe97d8c999197ba9356a1fc3a9abe059e9bb26 Mon Sep 17 00:00:00 2001 From: Matt Ho Date: Tue, 12 Oct 2021 06:55:27 -0500 Subject: [PATCH 2/8] added examples --- CIP-0030/CIP-0030.md | 105 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 103 insertions(+), 2 deletions(-) diff --git a/CIP-0030/CIP-0030.md b/CIP-0030/CIP-0030.md index 75b74f12c..3caa06f02 100644 --- a/CIP-0030/CIP-0030.md +++ b/CIP-0030/CIP-0030.md @@ -99,6 +99,107 @@ The url provided in the token metadata should return content in either html or J * In JSON format, the url should return a JSON block of the same shape as the on-chain token metadata that includes both the policy-id and asset-name to be verified. * In HTML format, the url should contain the a `meta` tag with `name` of `cip-30:authenticate` and a value of a comma separate list of tokens to declare as authenticate where tokens are formatted as `{policy id}{hex-encoded asset name}` with no space in between - - +## Example 1 - On-Chain Metadata + +In this example, we describe a transaction that contains the first minting of an asset, `12345678901234567890123456789012345678901234567890123456.EXAMPLE/P`. +The metadata attached to this transaction is as follows: + +```json +{ + "20": { + "12345678901234567890123456789012345678901234567890123456": { + "4558414D504C452F50": { + "ticker": "EXP", + "url": "https://example.com/", + "desc": "Example Publisher Token", + "icon": "ipfs://ipfs/1234567890123456789012345678901234567890123456", + "icon-16": "ipfs://ipfs/1234567890123456789012345678901234567890123456", + "decimals": 4 + } + } + } +} +``` + +* `4558414D504C452F50` is the hex encoded form of `EXAMPLE/P` + +When I visit, the url, `https://example.com/`, I am returned HTML which includes the following tag: + +```html + +``` + +## Example 2 - On-Chain Reference + +In this example, we use the same data, but instead construct the metadata as an off-chain reference. + +```json +{ + "20": { + "12345678901234567890123456789012345678901234567890123456": { + "4558414D504C452F50": { + "ref": "https://assets.example.com/" + } + } + } +} +``` + +In this example, the `ref` url returns the following JSON encoded content. Note that this URL also contains data for other tokens, but because we know the policy id and the hex encoded asset name of the `EXP`, we can uniquely identify from this list. + +```json +{ + "20": { + "12345678901234567890123456789012345678901234567890123456": { + "4558414D504C452F50": { + "ticker": "EXP", + "url": "https://example.com/asset.json", + "desc": "Example Publisher Token", + "icon": "ipfs://ipfs/1234567890123456789012345678901234567890123456", + "icon-16": "ipfs://ipfs/1234567890123456789012345678901234567890123456", + "decimals": 4 + } + }, + "12345678901234567890123456789012345678901234567890123456": { + "123456789012345678": { + "ticker": "OTHER-TOKEN", + "url": "https://other-token.com/", + "desc": "other token included for example purposes", + "icon": "ipfs://ipfs/1234567890123456789012345678901234567890123457", + "decimals": 2 + } + } + } +} +``` + +Unlike the previous example, this example returns a JSON encoded authenticity data as follows: + +```json +{ + "20": { + "12345678901234567890123456789012345678901234567890123456": { + "4558414D504C452F50": { + "ticker": "EXP", + "url": "https://example.com/asset.json", + "desc": "Example Publisher Token", + "icon": "ipfs://ipfs/1234567890123456789012345678901234567890123456", + "icon-16": "ipfs://ipfs/1234567890123456789012345678901234567890123456", + "decimals": 4 + } + }, + "12345678901234567890123456789012345678901234567890123456": { + "123456789012345678": { + "ticker": "OTHER-TOKEN", + "url": "https://other-token.com/", + "desc": "other token included for example purposes", + "icon": "ipfs://ipfs/1234567890123456789012345678901234567890123457", + "decimals": 2 + } + } + } +} +``` +Notice this data is the same data as returned by the `ref` for the on-chain reference. This is intentionally designed to reduce the amount of +boilerplate required to satisfy this CIP. From 15a472016cc57a4f944da722c487874579caa8c7 Mon Sep 17 00:00:00 2001 From: Matt Ho Date: Tue, 12 Oct 2021 06:58:58 -0500 Subject: [PATCH 3/8] added notes --- CIP-0030/CIP-0030.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CIP-0030/CIP-0030.md b/CIP-0030/CIP-0030.md index 3caa06f02..4751b4288 100644 --- a/CIP-0030/CIP-0030.md +++ b/CIP-0030/CIP-0030.md @@ -203,3 +203,13 @@ Unlike the previous example, this example returns a JSON encoded authenticity da Notice this data is the same data as returned by the `ref` for the on-chain reference. This is intentionally designed to reduce the amount of boilerplate required to satisfy this CIP. + +## Notes + +This CIP is intended to handle the common use faced primarily by exchanges as wallets that need to display tokens to their users. +Other standards, like `CIP-25`, the NFT metadata standard, will be more appropriate for handling specialized use cases. + +It is not expected nor desired for all tokens to contain `CIP-30` metadata. + + + From e32dcb55028ecaa3e4a3f45779541cfa9a0a0d8b Mon Sep 17 00:00:00 2001 From: Matt Ho Date: Tue, 12 Oct 2021 07:00:22 -0500 Subject: [PATCH 4/8] added additional notes --- CIP-0030/CIP-0030.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/CIP-0030/CIP-0030.md b/CIP-0030/CIP-0030.md index 4751b4288..5b3f94a0a 100644 --- a/CIP-0030/CIP-0030.md +++ b/CIP-0030/CIP-0030.md @@ -11,8 +11,11 @@ License: CC-BY-4.0 # Abstract -This specification defines a new transaction metadata label (i.e. `20`) and entry for [CIP-0030] to associate token metadata during a minting transaction. Unlike CIP-28, this -proposal is intended to define a specific schema to allow basic information about fungible tokens to be provided On-Chain. +This specification defines a new transaction metadata label (i.e. `20`) and entry for [CIP-0030] to associate token metadata +during a minting transaction. Unlike CIP-28, this proposal is intended to define a specific schema to allow basic information +about fungible tokens to be provided On-Chain. + +`20` is proposed as the metadata label in homage to the `ERC20` standard on Ethereum. # Motivation From cebec71ee7267af177979778fb836c6a1c0a3e8a Mon Sep 17 00:00:00 2001 From: Matt Ho Date: Tue, 12 Oct 2021 07:03:50 -0500 Subject: [PATCH 5/8] updated comment url --- CIP-0030/CIP-0030.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-0030/CIP-0030.md b/CIP-0030/CIP-0030.md index 5b3f94a0a..3f909c1e5 100644 --- a/CIP-0030/CIP-0030.md +++ b/CIP-0030/CIP-0030.md @@ -2,7 +2,7 @@ CIP: 30 Title: On-Chain Token Metadata Standard Authors: Matt Ho -Comments-URI: https://github.com/cardano-foundation/CIPs/pulls/118 +Comments-URI: https://github.com/cardano-foundation/CIPs/pull/137 Status: Draft Type: Standards Created: 2020-10-12 From 8b90ef5d3c03cf8660a6acdccb0b42f6755cb733 Mon Sep 17 00:00:00 2001 From: Matt Ho Date: Tue, 12 Oct 2021 09:40:44 -0500 Subject: [PATCH 6/8] renamed CIP-30 to CIP-31 --- CIP-0030/CIP-0030.md => CIP-0031/CIP-0031.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) rename CIP-0030/CIP-0030.md => CIP-0031/CIP-0031.md (96%) diff --git a/CIP-0030/CIP-0030.md b/CIP-0031/CIP-0031.md similarity index 96% rename from CIP-0030/CIP-0030.md rename to CIP-0031/CIP-0031.md index 3f909c1e5..ab68b147d 100644 --- a/CIP-0030/CIP-0030.md +++ b/CIP-0031/CIP-0031.md @@ -1,5 +1,5 @@ --- -CIP: 30 +CIP: 31 Title: On-Chain Token Metadata Standard Authors: Matt Ho Comments-URI: https://github.com/cardano-foundation/CIPs/pull/137 @@ -11,7 +11,7 @@ License: CC-BY-4.0 # Abstract -This specification defines a new transaction metadata label (i.e. `20`) and entry for [CIP-0030] to associate token metadata +This specification defines a new transaction metadata label (i.e. `20`) and entry for [CIP-0031] to associate token metadata during a minting transaction. Unlike CIP-28, this proposal is intended to define a specific schema to allow basic information about fungible tokens to be provided On-Chain. @@ -100,7 +100,7 @@ mechanism provides users a better understanding of where their tokens came from. The url provided in the token metadata should return content in either html or JSON format. * In JSON format, the url should return a JSON block of the same shape as the on-chain token metadata that includes both the policy-id and asset-name to be verified. -* In HTML format, the url should contain the a `meta` tag with `name` of `cip-30:authenticate` and a value of a comma separate list of tokens to declare as authenticate where tokens are formatted as `{policy id}{hex-encoded asset name}` with no space in between +* In HTML format, the url should contain the a `meta` tag with `name` of `cip-31:authenticate` and a value of a comma separate list of tokens to declare as authenticate where tokens are formatted as `{policy id}{hex-encoded asset name}` with no space in between ## Example 1 - On-Chain Metadata @@ -129,7 +129,7 @@ The metadata attached to this transaction is as follows: When I visit, the url, `https://example.com/`, I am returned HTML which includes the following tag: ```html - + ``` ## Example 2 - On-Chain Reference @@ -212,7 +212,7 @@ boilerplate required to satisfy this CIP. This CIP is intended to handle the common use faced primarily by exchanges as wallets that need to display tokens to their users. Other standards, like `CIP-25`, the NFT metadata standard, will be more appropriate for handling specialized use cases. -It is not expected nor desired for all tokens to contain `CIP-30` metadata. +It is not expected nor desired for all tokens to contain `CIP-31` metadata. From 508e71b8ad3f0166f676fbfa9dffc673fe297fec Mon Sep 17 00:00:00 2001 From: Matt Ho Date: Mon, 22 Nov 2021 13:34:37 -0600 Subject: [PATCH 7/8] renamed logo to icon for consistency --- CIP-0031/CIP-0031.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CIP-0031/CIP-0031.md b/CIP-0031/CIP-0031.md index ab68b147d..41ed371db 100644 --- a/CIP-0031/CIP-0031.md +++ b/CIP-0031/CIP-0031.md @@ -61,8 +61,8 @@ asset-name | | hex encoded asset name | ticker | OPTIONAL | when present, field and overrides default ticker which is the asset-name | url | OPTIONAL | https only url that refers to metadata stored offchain. The URL SHOULD use the project domain and MUST return authenticity metadata in either html or json format (see below) | desc | OPTIONAL | additional description that defines the usage of the token | -logo | REQUIRED | MUST be either https, ipfs, or data. logo MUST be a browser supported image format. -logo-<size> | OPTIONAL | allows teams to provide icon in different sizes. the recommended values of size are 16, 32, 64, 96, 128. logos are assumed to be square so that logo-64 would refer to a 64x64 logo +icon | REQUIRED | MUST be either https, ipfs, or data. icon MUST be a browser supported image format. +icon-<size> | OPTIONAL | allows teams to provide icon in different sizes. the recommended values of size are 16, 32, 64, 96, 128. icons are assumed to be square so that icon-64 would refer to a 64x64 icon decimals | OPTIONAL | how many decimal places should the token support? For ADA, this would be 6 e.g. 1 ADA is 10^6 Lovelace version | OPTIONAL | when not specified, version will default to `1.0` From 1d9fbd0e29f07b931bf1524c7aed6635d478cd75 Mon Sep 17 00:00:00 2001 From: Frederic J <58846030+crptmppt@users.noreply.github.com> Date: Thu, 16 Dec 2021 04:38:02 -0800 Subject: [PATCH 8/8] Update and rename CIP-0031/CIP-0031.md to CIP-0035/CIP-0035.md moving the numbering to 35 tentatively --- CIP-0031/CIP-0031.md => CIP-0035/CIP-0035.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename CIP-0031/CIP-0031.md => CIP-0035/CIP-0035.md (99%) diff --git a/CIP-0031/CIP-0031.md b/CIP-0035/CIP-0035.md similarity index 99% rename from CIP-0031/CIP-0031.md rename to CIP-0035/CIP-0035.md index 41ed371db..ab280f842 100644 --- a/CIP-0031/CIP-0031.md +++ b/CIP-0035/CIP-0035.md @@ -1,5 +1,5 @@ --- -CIP: 31 +CIP: 35 Title: On-Chain Token Metadata Standard Authors: Matt Ho Comments-URI: https://github.com/cardano-foundation/CIPs/pull/137