KIP-0031: Fungible token Metadata

[CryptoPascal31]

The goal of this KIP is

• to propose a standard way for token issuers to include meta-data in their token modules codes.
• a way to allow wallets, frontends ... to retrieve and use these data

This KIP is an early draft. I'm not sure that all needs are covered.
Reviews, pros, cons, comments, improvements, and suggestions are welcome and desired

GH Formatted Markdown document link:
https://github.com/CryptoPascal31/KIPs/blob/kip-031/kip-0031.md

GH formatted interface code:
https://github.com/CryptoPascal31/KIPs/blob/kip-031/kip-0031/fungible-meta-v1.pact

And example:
https://github.com/CryptoPascal31/KIPs/blob/kip-031/kip-0031/example-token.pact

EDIT: Added 3 new paragraph to address questions

---

• To see the specific tasks where the Asana app for GitHub is being used, see below:
  • https://app.asana.com/0/0/1208668844268908

[daplcor]

I am not sure 100% about circulating supply, it might be easier/better to have a trusted ecosystem project run a daily or weekly update service for this but max supply is definitely good to capture. Worth a wider discussion at the very minimum. I'd love to hear from wallets, dexs, and other services that pull in token information.

[CryptoPascal31]

I am not sure 100% about circulating supply, it might be easier/better to have a trusted ecosystem project run a daily or weekly update service for this but max supply is definitely good to capture. Worth a wider discussion at the very minimum. I'd love to hear from wallets, dexs, and other services that pull in token information.

The idea behind this is to have "Best effort approach". Nothing is mandatory, and based of good faith and interpretation of tokens issuers. It let the responsibility for tokens to report the information themselves. Several cases could happen:

• Some tokens may have always total-supply = circulating-supply => They just return the same value
• Some tokens may decide that circulating-supply is not relevant, or impossible to estimate => They return 0.0
• Some tokens contracts may have appropriate counters and/or special internals to account the supply => They can use (circulating-supply) to return the exact value to users. (eg $BRO token, or future Linx wrapped tokens)

=> But in all cases, it's at least better than nothing.

Note that this is not incompatible with third party scripts, that could provide this information too, and spot scammers. Anyway 3rd party projects may have some limitations for exacting data if they are not aware of the internals of the token. Think for example about $BRO, whose the "non-circulating" supply is kept on a special account... and a dumb script won't be aware of that.

[daplcor]

I believe that's fine as we are talking best case for circulating supply and something is better than nothing. I would however like to consider removing the color field, as I don't feel like it adds anything.

[LindaOrtega]

Hi, in general this KIP has received positive internal feedback from the Kadena team. I'll re-post some of the feedback one of the team members gave that summarizes the main points:

After reading the KIP, my understanding is that the current metadata fields include:

• symbol: Token Ticker symbol
• name: Token name
• description: Longer description (optional)
• img: URL of graphical representation (optional)
• logo: URL of small graphical representation (optional)
• color: CSSv4 compatible color (optional)
• socials: List of social media links (optional)

I would propose adding a mandatory 'decimals' field to specify the number of decimal places a token supports.

• Critical for wallets and interfaces to properly display token amounts
• Essential for calculating and handling token precision accurately
• Consistent with other token standards (like ERC20) where decimals is standard metadata
• Prevents display errors and would reduce user confusion

Considerations:

• How chainweb upgrades would affect metadata implementation
• Field standardization needs, including:
• Maximum lengths for text fields (symbol, name, description)
• Format requirements for social media URLs

Other relevant constraints

• Migration path for existing tokens created before this standard, including:
• How to handle legacy tokens
• Process for upgrading to the new standard

Some additional feedback and notes:

1. This interface needs to be versioned in case we want to upgrade it in the future.
2. The migration strategy should provide examples of how token issuers can upgrade their contract to implement this interface. And how they would migrate if we put out future versions of it.
3. The migration strategy should provide guidance to governance-bound tokens (aka tokens whose smart contract cannot be upgraded) as well.
4. The current fungible-v2 interface has a precision constant, should we duplicate this field in this interface as well?
5. We should also discuss if we want to upgrade the coin contract to implement this interface. Though it's not a blocker for this KIP.

Logistical planning (open for discussion):

1. If we think this interface is a good idea, we should deploy it to the kip interface.
2. We should have a Testnet period for this KIP where users can try out this interface before we launch to Mainnet.

[alber70g]

I have some reservations on this kip

\1. if this is a KIP (which I think is too intrusive given that it's a Kadena improvement proposal, not a community standard (on separate note, should we have something that represent community standards? Like KIP-0017, or KIP-0026 draft)), should we make this for coin as well? If we do, how will (circulating-supply) be calculated? Is it as simple as height * reward? Do we have this information at pact-runtime level?
2. Is there something relatable outside Kadena ecosystem that we can refer to?
3. If not 2, why should this be something we want to do as an optional thing. Wouldn't it be better to enforce this and have a new fungible-v3 include this metadata

Practical considerations
4. both img and logo?
5. There's socials, but not website? Is that also a social?
6. How do we prevent users from creating fake symbols? Do we want to guard it with the guard that guards the fungible?
7. what determines the "main-chain" for a token to provide this information from?
8. Should (supported-chains) be a boolean, isChainSupported on the chain where the query is executed?

[CryptoPascal31]

Hi, in general this KIP has received positive internal feedback from the Kadena team. I'll re-post some of the feedback one of the team members gave that summarizes the main points:

After reading the KIP, my understanding is that the current metadata fields include:

• symbol: Token Ticker symbol
• name: Token name
• description: Longer description (optional)
• img: URL of graphical representation (optional)
• logo: URL of small graphical representation (optional)
• color: CSSv4 compatible color (optional)
• socials: List of social media links (optional)

I would propose adding a mandatory 'decimals' field to specify the number of decimal places a token supports.

• Critical for wallets and interfaces to properly display token amounts
• Essential for calculating and handling token precision accurately
• Consistent with other token standards (like ERC20) where decimals is standard metadata
• Prevents display errors and would reduce user confusion

The fungible-v2 already has a (decimals) function. IMO. It shouldn't be duplicated.

Note: Decimals in Kadena have a different meaning and usage than in ERC-20.

• The EVM doesn'r have the decimal type, and all balances are stored in retrieved in Integers. So the DECIMALS variables is critical to display and handle amounts properly, from a user point of view. But for SC, decimals are transparent.
• In Kadena, (decimals) is mainly used by SC to round properly amounts, before calling transfer functions.

Considerations:

• How chainweb upgrades would affect metadata implementation

Smoothly, as soon chainweb preserves general backward compatibility for Smart Contracts.

• Field standardization needs, including:
• Maximum lengths for text fields (symbol, name, description)

Yes.

• Format requirements for social media URLs

Yes

Other relevant constraints

• Migration path for existing tokens created before this standard, including:
• How to handle legacy tokens
• Process for upgrading to the new standard

Some additional feedback and notes:

1. This interface needs to be versioned in case we want to upgrade it in the future.

Yes it is... That's why the proposed interface is called fungible-meta-v1

2. The migration strategy should provide examples of how token issuers can upgrade their contract to implement this interface. And how they would migrate if we put out future versions of it.

Yes, I can add this in the KIP Markdown document, but I'm not sure that the right place for such guidance is in the Standard itself.. Maybe in an annexed document ?

3. The migration strategy should provide guidance to governance-bound tokens (aka tokens whose smart contract cannot be upgraded) as well.

In this case there are 2 possibilities: either:

• Don't upgrade: Keep as is.
• Create a new "proxy" module that calls old fungible module + add meta-data.

4. The current fungible-v2 interface has a `precision` constant, should we duplicate this field in this interface as well?

As I wrote above: IMO no.

5. We should also discuss if we want to upgrade the coin contract to implement this interface. Though it's not a blocker for this KIP.

Nothing mandatory. But IMO this is not necessary, as the coin contract should be kept at a minimum... And the coin contract is already well known by all wallets and Dapp..

Logistical planning (open for discussion):

1. If we think this interface is a good idea, we should deploy it to the `kip` interface.

Yes

2. We should have a Testnet period for this KIP where users can try out this interface before we launch to Mainnet.

Of course

Important note: The philosophy of this KIP is not to enforce a mandatory upgrade... From a “technical” point of-view, fungible-v2 will be the only mandatory and minimal interface for tokens to work and interact with 3rd party SC. The objective of this KIP is to only propose a better user-experience through wallets and Dapp, by providing informative (ie meta) "data"...

[CryptoPascal31]

I have some reservations on this kip

\1. if this is a KIP (which I think is too intrusive given that it's a Kadena improvement proposal, not a community standard (on separate note, should we have something that represent community standards? Like KIP-0017, or KIP-0026 draft)),

I don't know... It depends on the internal policy of Kadena.

should we make this for coin as well?

IMO No. The coin contract should be kept at a minimum... And the coin contract is already well known by all wallets and Dapp..

If we do, how will (circulating-supply) be calculated? Is it as simple as height * reward? Do we have this information at pact-runtime level?

2. Is there something relatable outside Kadena ecosystem that we can refer to?

ERC-20 provides only 2 optional fields for meta-data: name and symbol.. But this doesn't mean, that we can't do better in Kadena.
FYI: I was inspired by the meta-data used by the Ecko-DEX frontend.

3. If not 2, why should this be something we want to do as an optional thing. Wouldn't it be better to enforce this and have a new fungible-v3 include this metadata

Because IMO, we should separate two things:

• fungible-v2 which is the “technical interface”, which is the minimum and mandatory interface to be able to interact with 3rd party SC and Wallets.
• fungible-meta-v1 (this KIP): Nothing technical, just informative... Improve the Used-Experience and helps to make easier the maintenance of Wallets and Dapp frontends.

Practical considerations 4. both img and logo?

img is supposed a general purpose (maybe high resolution image). While logo is supposed to be a low-res image that can be fetched quickly.. when (most of the time) only a small image is needed.

5. There's socials, but not website? Is that also a social?

Yes... It's included in socials (read the KIP carefully) but maybe we should add another speific field for this, or maybe rename socials to a more general term (like external-links) ?

6. How do we prevent users from creating fake symbols? Do we want to guard it with the guard that guards the fungible?

Nothing we can do on a public blockchain. Trademark enforcement is not in the scope of a blockchain. It's up to the user to enter trusted tokens modules refs in his wallet.. Or it's up to the wallet's maintainers to list safe tokens.

7. what determines the "main-chain" for a token to provide this information from?

It's up to the token issuer to decide wether the token has a main-chain, and what is the main-chain. For dynamically minted token (eg token related to a bridge), this will be the chain where tokens are minted: the "chain who knows the supply information"

8. Should (supported-chains) be a boolean, isChainSupported on the chain where the query is executed?

The idea behind (supported-chains), is to allow wallets to be quickly aware of the list of supported (btw probably synonym to deployed ) chains, by doing a single query on a single chain (eg chain 0). Imagine if Kadena increases the number of chains to 10.000, querying every chain to see whether the token is deployed won't be possible.

[openaccess-id]

- Data Overhead: Data only needs to be written to a single chain's contract (e.g. register on one of the first 20 chains)
= Enforces data is on certain chains, this reduces the number of network requests required to locate the main chain (e.g., searching the first 20 chains rather than later 1000 chains).

An interface seems to be to unpredictable, a simple 2-step dApp (e.g kadena tools) without added cost, with a copy paste guide into your contract main chain, (for dynamic supplies) at step 2 would be sufficient. However, aside from the potential network requests/duplicated data, I don’t mind either way.

• Deploy multisig to prevent the introduction of costs after years of use (common trust issues — we’ll include a signature). (1.) (2.)
• Unless kadena prefer to ensure that the interface stops deploying after, for example, 50 chains (while remaining adaptable).
• Also unsure if it’s possible to communicate that the interface should only be used on certain chains when there are large crowds.

---

- Supported Chain Ranges: Chains should support configurable ranges, on input, e.g., chains: 0-4, 9-19
- Data Saved as String in Fixed Order: Cheaper e.g "meta1, meta2, meta3" + a few unassigned additional fields, just in case?

---

(1.) Possible example: Open sig tool/contract:/interface, public registration period per contract (e.g., a month), with a namespace created and contract 'deployed'/signed using keys-all. This would likely require a special form of pre-signature capability to sign for the contract deployment after principal namespace got created, or so.. to make it more feasible and resilient to off-chain manipulation on the signing date, in case some participants don’t show up to sign, @kadena_io
(would also allow to deploy a trusted common coin contract, with tables for individual coins, instead of seperate contract per coin, reducing overhead and cost / in the sense of coin.mycoin.. as standard, unified liq pool etc)

• or create, sign and throwaway a complete keyset inside contract and have voting incl. highlighted designated project sigs in support or against with comment.

(2.) For this specific case, in combination with a minimal open-source metadata registration tool (HTML, vanilla JS).

[hswopeams]

2. Is there something relatable outside Kadena ecosystem that we can refer to?

We could refer to the Ethereum (ERC-721) metadata standard. Search in the browser on "metadata". ERC-721 is a standard for non-fungible tokens, but it could be applied to fungiibles.

It is also an optional standard. It uses a JSON schema that has most of the metadata properties in a properties object that doesn't have specific property names. This makes it flexible so that properties can be added without having to modify the schema.

[emilypi]

Looks thank you @CryptoPascal31. Adding some comments here.

[emilypi]

Suggested change

	Define and implement a new way for tokens creators to export their Meta-Data to Wallets, Frontends, and Other services.
	Define and implement a new way for tokens creators to export their Metadata to Wallets, Frontends, and Other services.

[emilypi]

Suggested change

	While `fungible-v2` provides technical functions to allow "technical on-chain" interoperability between tokens, meta-data and information about fungible tokens are missing.
	While `fungible-v2` provides technical functions to allow "technical on-chain" interoperability between tokens, metadata and information about fungible tokens are missing.

[emilypi]

Suggested change

	And finally, since Kadena is multichains, wallets need to be informed on how to use the token, regarding chains deployment:
	And finally, since Kadena is consists of multiple chains, wallets need to be informed on how to use the token, regarding chain deployment:

[emilypi]

Suggested change

	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.
	The proposal is **to create an optional interface that can be implemented by token modules** to automatically inform third parties about token metadata and displayable information to users. Wallets, frontends, ... are expected to make local calls to the `kip.fungible-meta` implemented functions.

[emilypi]

Supply will be accurate on individual chains if there as a chain-level supply noted in the interface for a token's metadata, just not a "total supply" across all the network. I think here, we need to separate the idea of what is autonomous metadata, as in facts that a ledger can keep about itself, vs dependent metadata - facts that require some kind of oracle to contribute. A main chain being an example of this oracle, but not the only valid kind out there.

[emilypi]

proposing a maxchar cap on this to avoid spamability

[emilypi]

which ones are optional? Is this the same as "not mandatory"? Why are socials mandatory?

[emilypi]

Now, considering what I wrote above, is this something that implementors are expected to update with market data on a day to day? What's the good faith expectation here?

[emilypi]

I think that the level of relevance here is why i'm advocating not having main-chain here, and letting individual ledgers track their own burns and creates without attempting a Kadena-wide supply.