KIP-0031: Fungible token Metadata

kip-0031.md

@@ -0,0 +1,107 @@
+---
+KIP: "0031"
+Title: fungible-meta-v1
+Author: CryptoPascal  
+Status: Early Draft
+Type: Standard
+Category: Chainweb / Fungible
+Created: 2024-09-28
+---
+
+## Abstract
+
+Define and implement a new way for tokens creators to export their Meta-Data to Wallets, Frontends, and Other services.
+While this is currently handled off-chain, this proposal is intended to take a an "on-chain" approach.
+
+
+## Rationale
+
+While `fungible-v2` provides technical functions to allow "technical on-chain" interoperability between tokens, meta-data and information about fungible tokens are missing.
+
+Currently, listing tokens for Wallet, Frontends, Exchanges, and other third parties is a cumbersome process. Maintainers have to manually contact tokens issuers to retrieve logos, names, and other useful information to display to users. This ends up with disparities between different wallets or frontends. Users complain that they don't have reliable information about their investment.
+
+Moreover, token issuers have no clean and defined way to inform wallets when some changes happen with their token (Rebrand, new issuance, ...)
+
+And finally, since Kadena is multichains, wallets need to be informed on how to use the token, regarding chains deployment:
+  - Some tokens may not be available on all chains.
+  - Some tokens may have a single issuance chain where supply is accounted
+
+The proposal is **to create an optional interface that can be implemented by token modules** to automatically inform third parties about their meta-data, and displayable information to users. Wallets, frontends, ... are expected to make local calls to the `kip.fungible-meta` implemented functions.
+
+#### Trustability
+
+Information (especially supply) relies **only** on token issuers and module writers good faith. Clients should not blindly trust them. Sorting legitimate tokens from illegitimate ones is not in the scope of this KIP.
+
+#### Non-Obligability
+For being compliant with this KIP, token issuers have no obligation to provide all data.
+And clients (Wallets, Frontends), have no obligation to show everything.
+
+#### Supply considerations
+
+One important piece of information required by investors is the total and circulating supply.
+Kadena being multichain, when dynamic minting/burning tokens are considered, a new issue arises:
+  - Usually, minting / burning / emission happens on a single chain.
+  - **But other chains are not aware**: they just receive X-chain transfers.
+
+As a consequence, it's highly probable that supply information won't be accurate on most chains. That's why this KIP proposes the concept of **main-chain** => The module itself informs the client where an accurate value of supply amounts can be found.
+
+
+### API
+
+The interface `kip.fungible-meta`, which should be implemented by token modules, provides the following functions.
+
+##### (general-info)
+ -> *object:{kip.fungible-meta.info-schema}*
+
+Return general information about a token:
+  - `symbol` *string*: Token Ticker symbol. Usually a short name in uppercase.
+  - `name` *string*: Token name. Usually a relative short name composed of 1 or 2 words.
+  - `description` *string*: Longer description of the token. Not mandatory
+  - `img` *string* : URL of the graphical representation of the token. Not mandatory
+  - `logo` *string* : URL of a small (res max of 192x192) graphical representation of the token. Not mandatory. Can be the same as `img`
+  - `color` *string*: A CSSv4 compatible color (https://www.w3.org/TR/css-color-4/#typedef-color). Not mandatory. Can be used by wallets or frontends for some graphical displays (charts ...)
+  - `socials` *[object:{kip.fungible-social-schema}]*: A list of tuples (`type` *string*, `url` *string*). The list of allowed types (non limitative): "discord", "twitter", "website", "telegram", "reddit", "github"  
+
+**Note:** All optional fields must use an empty string if the information is not provided.
+
+##### (main-chain)
+  -> *string*
+
+Return the main chain (if any) of the token. Usually, it's the issuance chain. This chain is expected to have the most reliable information about total and circulating supply. All compliant wallets should request this chain before displaying supply information to the user.
+
+##### (supported-chains)
+  -> *[string]*
+
+Return the list of chains supported by the token. This is important for wallets, for retrieving balances, and correctly managing available X-chain transfers.
+
+
+##### (total-supply)
+  -> *decimal*
+
+Return the total Supply of the token. If unknown 0.0 can be returned.
+
+##### (circulating-supply)
+  -> *decimal*
+
+Return the total circulating supply. If unknown, 0.0 can be returned. This information might be relevant only on the main chain.
+
+**Important note:** All those functions implementations must be "Read-Only pure". They are not allowed to write data or have any side effects.
+
+
+## Backwards Compatibility
+
+Since this interface may be implemented in addition to `fungible-v2`, "non compliant" tokens will continue to work as usual.
+Hence, no backward compatibility issues are expected.
+
+
+## Specification
+
+See [fungible-meta-v1.pact](kip-0031/fungible-meta-v1.pact)
+
+## Example
+
+Implementation example:
+  See [example-token.pact](kip-0031/example-token.pact)
+
+## References
+* KIP-0005: Fungible v2

kip-0031/example-token.pact

@@ -0,0 +1,47 @@
+(load "fungible-meta-v1.pact")
+
+(module bro-token G
+  (defcap G ()
+    (enforce false "No"))
+
+  (implements kip.fungible-v2)
+  (implements kip.fungible-meta-v1)
+
+
+  (defconst _SUPPORTED_CHAINS ["0", "1", "2" ])
+  (defconst _MAIN_CHAIN "2")
+
+  (defun general-info:object{info-schema} ()
+    {'symbol: "BRO",
+     'name: "$BRO",
+     'description: "Token of Kadena Brothers DAO",
+     'img: "https://raw.githubusercontent.com/brothers-DAO/bro-token/refs/heads/main/graphic-assets/basic/BRO_3000_3000.png",
+     'logo: "https://raw.githubusercontent.com/brothers-DAO/bro-token/refs/heads/main/graphic-assets/basic/BRO_192_192.png",
+     'color: "#eec2a1",
+     'socials:[{'type:"website", 'url:"https://bro.pink"},
+               {'type:"github",  'url:"https://github.com/brothers-DAO"}]}
+  )
+
+  (defun main-chain:string ()
+    _MAIN_CHAIN)
+
+  (defun supported-chains:[string] ()
+    _SUPPORTED_CHAINS)
+
+  (defun total-supply:decimal ()
+    100.0)
+
+  (defun circulating-supply:decimal ()
+    (if (= _MAIN_CHAIN (at 'chain-id (chain-data)))
+        (- (total-supply) (get-balance "issuance-account"))
+        0.0)
+  )
+
+  ; Usual fungible-v2 functions ===>
+
+  ; ...
+
+  ; ...
+
+  ; ....
+)

kip-0031/fungible-meta-v1.pact

@@ -0,0 +1,34 @@
+(interface fungible-meta-v1
+  @doc "Provides several meta-data informations for the token"
+
+  (defschema social-schema
+    type:string
+    url:string
+  )
+
+  (defschema info-schema
+    symbol:string
+    name:string
+    description:string
+    img:string
+    logo:string
+    color:string
+    socials:[object{social-schema}]
+  )
+
+  (defun general-info:object{info-schema} ()
+    @doc "Return general information about a token")
+
+  (defun main-chain:string ()
+    @doc "Return the main chain (if any) of the token")
+
+  (defun supported-chains:[string] ()
+    @doc "Return the list of chains supported by the token")
+
+  (defun total-supply:decimal ()
+    @doc "Return the total supply of the token")
+
+  (defun circulating-supply:decimal ()
+    @doc "Returns the circulating supply of the token")
+
+)