Fungible Token Metadata Standard

[robert-zaremba]

Rationale

Many smart-contracts need to carry extra information data. Notably, token smart contract should provide minimum information to a user about it's usage.

Previous Fungible Token interfaces (NEP-21, NEP-122) miss standard way to describe crucial information to correctly implement user interfaces and wallets. Most importantly, tokens should have name, description (either directly stored in smart contract or available in a remote service), information for correct token arithmetic.
For example, the following applications maintain their incompatible lists just to get a token icon visible in the wallet: MyEtherWallet, TrustWallet, MetaMask, Parity. Then the services maintain their own lists: Uniswap, Loopring, IDEX.

Decision

We propose a Token Metadata standard, inspired by NEP-136 and NEP-110.
Metadata should be as minimal as possible. We propose to store metadata in a separate structure.

Token Metadata

struct Metadata {
  name: String,  
  reference: String, 
  reference_hash: vec[u8],
  decimals: uint8,
}

• name: canonical token name.
• reference: a URL to addtional resources about the token.
• reference_hash: a blake2b hash of the resource pointed by ref. It's used to validation that the reference content didn't change.
• decimals: returns the number of decimals the token uses - e.g. 8, means to divide the token amount by 100000000 to get its user representation.

Decimal management

For interactions with tools and assure good UX, we need to know the base of token arithmetic.
ERC-20 has an optional decimals contract attribute, other Ethereum standards makes this attribute obligatory. We follow the ERC-777 proposal, and fix the decimals once and for all:

• Each fungible token should have 24 digits precision (decimals), 1000000 times more than most of the existing Ethereum tokens. If a token contract returns a balance of 500,000,000,000,000,000,000,000 (0.5e24) for a user, the user interface MUST show 0.5 tokens to the user.
• We port the granularity concept from ERC-777: the smallest part of the token that’s (denominated in e24) not divisible. The following rules MUST be applied regarding the granularity:
• The granularity value MUST be set at creation time.
• The granularity value MUST NOT be changed, ever.
• The granularity value MUST be greater than or equal to 1.
• All balances MUST be a multiple of the granularity.
• Any amount of tokens (in the internal denomination) minted, sent or burned MUST be a multiple of the granularity value.
• Any operation that would result in a balance that’s not a multiple of the granularity value MUST be considered invalid, and the transaction MUST revert.

For non fungible tokens:

• both granularit and decimals MUST be 1

Functions

Only one function is necessary to assure solid interactions with dapps and other smart contracts: to access metadata. Management functions are optional and user can change them.

metadata

fn metadata(&self) -> Metadata

Returns Metadata structure or any extension of it.

Recommended functions:

metadata_update

fn metadata_update(&mut self, ref: String, ref_hash: String)

Arguments:

• ref: new URL to a reference resource.
• ref_hash: blake2b hash of the resource at ref URL.

[robert-zaremba]

Note: I was thinking about designing a generic Metadata standard, but then I realized that it is not possible to have a non trivila Metadata structure applicable for all smart contracts. Eg: tokens need information for doing correct arithmetic. DID contracts don't need that.

[oysterpack]

Note: I was thinking about designing a generic Metadata standard, but then I realized that it is not possible to have a non trivila Metadata structure applicable for all smart contracts. Eg: tokens need information for doing correct arithmetic. DID contracts don't need that.

I don't think we should give up on a generic metadata API just yet ... I have some ideas, but my brain is too exhausted right now. I'll sleep on it and follow up tomorrow ...

[mikedotexe]

Sure:

• wBTC: decimals=24, granularity=9 -> smallest trade-able value is 1e16
• wETH: decimals=24, granularity=18 -> smallest trade-able value is 1e6
• wUSDT: decimals=24, granularity=6 -> smallest trade-able value is 1e18
• wNEAR: decimals=24, granularity=24 -> smallest trade-able value is 1

Strange, I feel like the decimals might be vestigial. I'm looking at OpenZeppelin here:
https://docs.openzeppelin.com/contracts/2.x/api/token/erc777#ERC777-decimals--

Always returns 18…

and then links to a section on backwards compatibility stating:

The token MAY implement decimals() for backward compatibility with ERC-20. If implemented, it MUST always return 18.

It feels like decimals will always be 24 for yocto, yes?

[robert-zaremba]

Yes, for fungible tokens decimals will always be 24. Initially I wanted 18 (I continue to claim that 24 is too big and we just waist some resources), but then we would have problem of creating wrapped NEAR.

[mikedotexe]

I guess my question is, do we even need decimals if it's always the same value?

[robert-zaremba]

Good point - we don't. If we agree on constant decimals for fungible tokens, then we can skip it.

[robert-zaremba]

Decimal size

Following Luccio proposal, I've changed granularity from 18 to 24 to be able to support wNEAR.

[oysterpack]

WITHDRAWN: PROPOSAL: Generic Metadata API

@evgenykuzyakov is already working on separate generic me - this standard will be focused on FT metadata

I did a little POC using the following API (defined in Rust)

API

pub trait MetaData {
    /// returns None if the contract does not support the requested metadata
    fn metadata(uri: String) -> Option<Value>;

    /// returns the metadata that this contract exposes
    fn metadata_uris() -> Vec<String>;
}

• the metadata API is generic and can return any object that can be serialized to JSON
• there would be a uri for each type of metadata, e.g FT metadata, NFT metadata, Account Registraction metadata

The idea is that the metadata schemas are decoupled from the API. The metadata API simply enables you to query the contract to find out what metadata it exposes.

EXAMPLE: contract metadata API implementation supporting FT metadata

use crate::interface::metadata::MetaData;
use crate::*;
use near_sdk::{
    near_bindgen,
    serde::{Deserialize, Serialize},
    serde_json::{self, Value},
};

const METADATA_FT: &str = "http://near.org/contract/metadata/fungible-token";

#[near_bindgen]
impl MetaData for StakeTokenContract {
    fn metadata(uri: String) -> Option<Value> {
        match uri.as_str() {
            METADATA_FT => {
                let md = TokenMetadata {
                    name: "OysterPack STAKE Token",
                    symbol: "STAKE",
                    ref_url: "https://github.com/oysterpack/oysterpack-near-stake-token",
                    ref_hash: "base64-ecoded-hash".to_string(),
                    granularity: 1,
                    decimals: 24,
                };
                Some(serde_json::to_value(md).unwrap())
            }
            _ => None,
        }
    }

    fn metadata_uris() -> Vec<String> {
        vec![METADATA_FT.to_string()]
    }
}

#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(crate = "near_sdk::serde")]
pub struct TokenMetadata {
    name: &'static str,
    symbol: &'static str,
    ref_url: &'static str,
    ref_hash: String,
    granularity: u8,
    decimals: u8,
}

I added this to the STAKE contract as a POC:

export CONTRACT=stake-1.oysterpack.testnet

near view $CONTRACT metadata --args '{"uri":"http://near.org/contract/metadata/fungible-token"}'

near view $CONTRACT metadata_uris

[robert-zaremba]

I don't think it makes sense in standard to have a function returning some serialized blob. Instead of receiving a structure, we get a string.I think each smart contract type should specify it's own metadata. I can be used by the same function name. So it makes more sense for me if we return a structure rather than a string.

So I see this standard is in fact a generic function:

fn metadata<Metadata>(&self, uri: String) -> Metadata;

[evgenykuzyakov]

Let's focus this standard on token specific metadata. We plan to introduce generic contract metadata later and it requires more thought than just generic object.

[robert-zaremba]

Totally - this is my original intention.

[oysterpack]

Let's focus this standard on token specific metadata. We plan to introduce generic contract metadata later and it requires more thought than just generic object.

That's fine then we need to change the API to align it with token metadata

fn md_token(&self) -> TokenMetadata;

fn md_token_update_ref(&mut self, ref: String, ref_hash: String)

pub struct TokenMetadata {
    name: &'static str,
    symbol: &'static str,
    ref_url: &'static str,
    ref_hash: String,
    granularity: u8,
    decimals: u8,
}

[evgenykuzyakov]

Question: How contract should react if a transfer receives an amount for a smaller granularity, e.g. 1e12 for wBTC which expects 1e16?

While I understand the desire to standardize the decimals, it's unclear to me how this benefits tools. Assuming decimals are fixed to 24, but granularity is higher, e.g. 16.

Now the contract should operate on numbers of 1e16 and round them appropriately to support it.

Alternative: Use number of digits after decimal

Example:

• wBTC: 8
• wETH: 18
• wNEAR: 24
• wUSDT: 6

Does it create some issues either on the contracts or on the front-end?

[robert-zaremba]

how this benefits tools
How contract should react if a transfer receives an amount for a smaller granularity,

It should panic. This way we don't have any problems with errors and rounding.

Much easier to parse and manage numbers: all numbers are denominated in 1e-24.

BTW, for "Alternative: Use number of digits after decimal" -- this is the approach of ERC20 - decimals (without granularity).

[oysterpack]

@robert-zaremba I assume there must be some real world examples where granularity > 1. Can you please provide some examples to put it into context.

[robert-zaremba]

It's here: #148 (reply in thread)

[mikedotexe]

The last thing I'm having trouble wrapping my head around is the ref_hash here:

ref: new URL to a reference resource.
ref_hash: blake2b hash of the resource at ref URL.

First, Eugene has mentioned that we don't have blake2b hashing. Second, I imagine that the ref will quite frequently be a link to decentralized storage, where the address is content-address, so the hash is baked into it.
Perhaps I'm misunderstanding the purpose of the ref_hash so I'll state my understanding: it's meant to make sure that the ref that points to https://example.com/mike-spec.md hasn't been tampered with, as users can download the md file, hash it themselves and check. Is that correct?

[robert-zaremba]

we don't have blake2b hashing

We can update to sha256. But this is for the off-chain usage, so I think blake2b can stay.

where the address is content-address, so the hash is baked into it.

But we don't make that assertion. It's not to have it blockchain verifiable, but to have it off-chain verifiable. Use-case is simple: a dapp want's to get more information about a token and show it to a user. It's at the best interest of the user and dapp to be able to verify that content. So, it can be empty, but we recommend to always put a hash we will specify here.

[mikedotexe]

(EDIT: WITHDRAWN) CHANGE PROPOSAL: Add array of used extension standards

I think it makes sense to have an array of standards used. For instance, if a fungible token wants to use escrows (in addition to the improved transfer functionality)

struct Metadata {
  name: String,  
  symbol: String, // token symbol
  ref: String, 
  ref_hash: vec[u8],
  decimals: uint8,
  extensions: vec[String]
}

I think this makes sense to have in storage on-chain, rather than in the ref. Smart contracts might want to know what standards (and hence methods) are available, and having them only in a ref would require an oracle solution.

[robert-zaremba]

For storage optimization we should use extensions: vec[uint32] instead of strings.

[mikedotexe]

Talked with Eugene about this yesterday, with an incoming idea of generalized contract metadata, I thinK i'll withdraw this suggestion.

[evgenykuzyakov]

Change proposal:

Rename ref to reference. ref is reserved keyword in Rust

[robert-zaremba]

I like reference. Just to brain storm a little more, other ideas: resource, url...

[oysterpack]

I like url

[robert-zaremba]

Someone may decide to put the reference as a string, instead of URL, that's why I was thinking more about something more general.

[oysterpack]

Summary of Discussion

Fungible Token Metadata API

Out of Scope

• How to update metadata URLs is out of scope because to update the metadata would require access control.

class FungibleTokenMetadata {
  name: string,  
  symbol: string,
  decimals: number,
  icon_url: string,
  icon_hash: string, // base64 encoded hash bytes
  url: string, 
  url_hash: string, // base64 encoded hash bytes
}

---

Function

function ft_metadata(): FungibleTokenMetadata;

view method

---

Open Questions:

1. Are hashes needed?

[robert-zaremba]

Hashes are needed to check the validity of the resource under url.

[oysterpack]

@robert-zaremba please rename the discussion to "Fungible Token Metadata Standard"

[robert-zaremba]

done

[luciotato]

I propose to use icon: string,
and remove icon_hash: string
The security problem is a contract mimicking a known token, not the data at the URL being changed.
icon:string could be an inline SVG (best option, in-chain, no secondary access needed, smaller), a URL or IPFS
https://vecta.io/blog/comparing-svg-and-png-file-sizes

[oysterpack]

I just realized that FT token metadata discussion was being discussed on the account storage discussion ... linking it here

#145 (comment)

[luciotato]

I think that's not needed. The NEP-141 is the version number. If the API is changed, it will be another number.
On the security problem with function-call access keys, I prefer to keep the "attach 1 yocto" as a "recommendation until a new core version fixes the problem"

[oysterpack]

I think that's not needed. The NEP-141 is the version number. If the API is changed, it will be another number.

version is needed to be able to programatically discover what is supported by the FT contract and how to use it ... otherwise you are back to square one and rely on hard coding assumptions or require inspecting the contract code.

Building in support for API versioning is a best practice. Change is inevitable and we must plan for it. If we don't, then the downstream effects and legacy costs will be substantial, which will have a negative impact on growth.

On the security problem with function-call access keys, I prefer to keep the "attach 1 yocto" as a "recommendation until a new core version fixes the problem"

FT Core v1.0.0 will require the payable methods. Once we have a proper solution for the FCAK issue, we can remove the hack and publish a new FT Core v2.0.0 (because it is a breaking change)

[luciotato]

I mean FT v1.0.0 is NEP-142, FT v2.0.0 will be NEP-456
To discern between the two i'm using NEP-129: #129

[robert-zaremba]

I'm thinking towards @luciotato direction. Each new token standard, will have a new NEP.
I think the best way to inform about token interfaces is to use interface registers. This should be a new standard. I started a discussion about this: #154

[oysterpack]

It sounds like we can all agree there is a need to identify on-chain what interfaces are supported by a contract.

However, there is no agreement or consensus on a standard solution (@luciotato has proposed #129, @robert-zaremba #154, etc).

I view this as falling under the contract metadata umbrella ... we need to take a step back and first agree on requirements before proposing a solution. I have started a new discussion for Contract Metadata Requirements

[luciotato]

I will insist on removing the "decimal" field and force all NEP-141 standard tokens on NEAR to be decimals=24 and u128 Balances.

Choosing a fixed decimal=24 is a very good trade-off, and I think that's the reason why 1 NEAR=1e24 Yoctos and Balances are u128

Besides being a good trade-off, removing the field reduces complexity for hundreds of developers that now can forget about it.

With decimals=24, your max amount on a u128 is 340_282_366_920_938, that's 340 trillions, and of course you get 24 digit precision, meaning you can divide 1 by 1 trillion w/o rounding and you still have 12 more digits to continue dividing. (1/1e24 =1e-12)

Having fixed decimals=24 on the standards will help a lot on DEFI composability. Smart contracts composing on several tokens become way more simpler if all tokens have the same precision.

[luciotato]

Balance=u128 & decimals=24 it's more like a custom Decimal type in NEAR. We should treat it like that. We need a Decimal type for DEFI, either customary or native to the programming language.

[robert-zaremba]

I agree with you, @luciotato . My original idea was to fix decimals and use granularity. If we fix decimals we need that one more variable to validate the minimum transfers. Look at the comment above for examples.

[mikedotexe]

CHANGE PROPOSAL: Bring back symbol, add version

pub struct FungibleTokenMetadata {
    pub version: String,
    pub name: String,
    pub symbol: String,
    pub reference: String,
    pub reference_hash: vec<u8>,
    pub decimals: u8,
}

version to follow semantic versioning.

I think particularly with the Bridge, we'd like to keep the symbol and it's more useful than it is a storage concern.
https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/token/ERC20/ERC20.sol#L39-L54

[robert-zaremba]

Fair enough - ERC20 portability is good enough use-case for symbol.

However, what's your motivation for version? Why not using a registry pattern? #154

[robert-zaremba]

BTW, The Zepplin library is using a fixed decimals ;)