| VIP | Title | Author | Category | Status | CreatedAt |
|---|---|---|---|---|---|
210 |
Semi-Fungible Token(SFT) Standard |
Vechain Foundation |
Application |
Superseded |
2021-05-11 |
This standard (VIP-210) has been superseded in favour of the ERC1155 standard on Ethereum. Development and usage of VIP-210 are strongly discouraged, and existing implementations are advised to migrate to ERC1155.
For detailed guidelines on utilizing ERC1155 for multi-token standard on the VechainThor Network, please refer to the documentation here.
The VIP-210 is equivalent to ERC1155 in the Vechain ecosystem.
The VIP-210 token standard provides a way to make one smart contract govern almost an unlimited number of tokens — technically, 2^256 token types with up to 2^256 copies of each. Additionally, each token is semi-fungible. Unlike VIP-181 non-fungible tokens (NFTs), which can only be owned by one address each, semi-fungible means:
- Each token type can be owned by multiple addresses.
- One address can own multiple copies of each token.
Tokens standards like VIP-180 and VIP-181 require a separate contract to be deployed for each token type or collection. This places a lot of redundant bytecode on the blockchain and limits certain functionality by the nature of separating each token contract into its own permissioned address.
New functionality is possible with this design such as transferring multiple token types at once, saving on transaction costs. Trading (escrow / atomic swaps) of multiple tokens can be built on top of this standard. It is also easy to describe and mix multiple fungible or non-fungible token types in a single contract.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
Smart contracts implementing the VIP-210 standard MUST implement all of the functions in the VIP210 interface.
pragma solidity >=0.5.0 <0.6.0;
/**
@title VIP-210 Semi-Fungible Token Standard
@dev See https://github.com/vechain/VIPs/vip-210
*/
interface IVIP210 {
/**
@dev Either `TransferSingle` or `TransferBatch` MUST emit when tokens are transferred, including zero value transfers as well as minting or burning (see "Safe Transfer Rules" section of the standard).
The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender).
The `_from` argument MUST be the address of the holder whose balance is decreased.
The `_to` argument MUST be the address of the recipient whose balance is increased.
The `_id` argument MUST be the token type being transferred.
The `_value` argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by.
The `_data` argument MUST be the list of transfering note
When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address).
When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address).
*/
event TransferSingle(address indexed _operator, address indexed _from, address indexed _to, uint256 _id, uint256 _value, string _data);
/**
@dev Either `TransferSingle` or `TransferBatch` MUST emit when tokens are transferred, including zero value transfers as well as minting or burning (see "Safe Transfer Rules" section of the standard).
The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender).
The `_from` argument MUST be the address of the holder whose balance is decreased.
The `_to` argument MUST be the address of the recipient whose balance is increased.
The `_ids` argument MUST be the list of tokens being transferred.
The `_values` argument MUST be the list of number of tokens (matching the list and order of tokens specified in _ids) the holder balance is decreased by and match what the recipient balance is increased by.
The `_data` argument MUST be the list of transfering note
When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address).
When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address).
*/
event TransferBatch(address indexed _operator, address indexed _from, address indexed _to, uint256[] _ids, uint256[] _values, string _data);
/**
@dev MUST emit when approval for a second party/operator address to manage all tokens for an owner address is enabled or disabled (absence of an event assumes disabled).
*/
event ApprovalForAll(address indexed _owner, address indexed _operator, bool _approved);
/**
@dev MUST emit when the URI is updated for a token ID.
URIs are defined in RFC 3986.
The URI MUST point to a JSON file that conforms to the "VIP210 Metadata URI JSON Schema".
*/
event URI(string _value, uint256 indexed _id);
/**
@notice Transfers `_value` amount of an `_id` from the `_from` address to the `_to` address specified (with safety call).
@dev Caller must be approved to manage the tokens being transferred out of the `_from` account (see "Approval" section of the standard).
MUST revert if `_to` is the zero address.
MUST revert if balance of holder for token `_id` is lower than the `_value` sent.
MUST revert on any other error.
MUST emit the `TransferSingle` event to reflect the balance change (see "Safe Transfer Rules" section of the standard).
After the above conditions are met, this function MUST check if `_to` is a smart contract (e.g. code size > 0). If so, it MUST call `onVIP210Received` on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard).
@param _from Source address
@param _to Target address
@param _id ID of the token type
@param _value Transfer amount
@param _data Additional data with no specified format, MUST be sent unaltered in call to `onVIP210Received` on `_to`
*/
function safeTransferFrom(address _from, address _to, uint256 _id, uint256 _value, string calldata _data) external;
/**
@notice Transfers `_values` amount(s) of `_ids` from the `_from` address to the `_to` address specified (with safety call).
@dev Caller must be approved to manage the tokens being transferred out of the `_from` account (see "Approval" section of the standard).
MUST revert if `_to` is the zero address.
MUST revert if length of `_ids` is not the same as length of `_values`.
MUST revert if any of the balance(s) of the holder(s) for token(s) in `_ids` is lower than the respective amount(s) in `_values` sent to the recipient.
MUST revert on any other error.
MUST emit `TransferSingle` or `TransferBatch` event(s) such that all the balance changes are reflected (see "Safe Transfer Rules" section of the standard).
Balance changes and events MUST follow the ordering of the arrays (_ids[0]/_values[0] before _ids[1]/_values[1], etc).
After the above conditions for the transfer(s) in the batch are met, this function MUST check if `_to` is a smart contract (e.g. code size > 0). If so, it MUST call the relevant `VIP210TokenReceiver` hook(s) on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard).
@param _from Source address
@param _to Target address
@param _ids IDs of each token type (order and length must match _values array)
@param _values Transfer amounts per token type (order and length must match _ids array)
@param _data Additional data with no specified format, MUST be sent unaltered in call to the `VIP210TokenReceiver` hook(s) on `_to`
*/
function safeBatchTransferFrom(address _from, address _to, uint256[] calldata _ids, uint256[] calldata _values, string calldata _data) external;
/**
@notice Get the balance of an account's tokens.
@param _owner The address of the token holder
@param _id ID of the token
@return The _owner's balance of the token type requested
*/
function balanceOf(address _owner, uint256 _id) external view returns (uint256);
/**
@notice Get the balance of multiple account/token pairs
@param _owners The addresses of the token holders
@param _ids ID of the tokens
@return The _owner's balance of the token types requested (i.e. balance for each (owner, id) pair)
*/
function balanceOfBatch(address[] calldata _owners, uint256[] calldata _ids) external view returns (uint256[] memory);
/**
@notice Enable or disable approval for a third party ("operator") to manage all of the caller's tokens.
@dev MUST emit the ApprovalForAll event on success.
@param _operator Address to add to the set of authorized operators
@param _approved True if the operator is approved, false to revoke approval
*/
function setApprovalForAll(address _operator, bool _approved) external;
/**
@notice Queries the approval status of an operator for a given owner.
@param _owner The owner of the tokens
@param _operator Address of authorized operator
@return True if the operator is approved, false if not
*/
function isApprovedForAll(address _owner, address _operator) external view returns (bool);
/**
* @notice A distinct Uniform Resource Identifier (URI) for a given token.
* @dev URIs are defined in RFC 3986.
* URIs are assumed to be deterministically generated based on token ID
* Token IDs are assumed to be represented in their hex format in URIs
* @return URI string
*/
function uri(uint256 _id) external view returns (string memory);
}
Smart contracts MUST implement all of the functions in the VIP210TokenReceiver interface to accept transfers. See Safe Transfer Rules for further detail.
pragma solidity >=0.5.0 <0.6.0;
interface IVIP210TokenReceiver {
/**
@notice Handle the receipt of a single VIP210 token type.
@dev An VIP210-compliant smart contract MUST call this function on the token recipient contract, at the end of a `safeTransferFrom` after the balance has been updated.
This function MUST return `bytes4(keccak256("onVIP210Received(address,address,uint256,uint256,string)"))` (i.e. 0xeae23ab4) if it accepts the transfer.
This function MUST revert if it rejects the transfer.
Return of any other value than the prescribed keccak256 generated value MUST result in the transaction being reverted by the caller.
@param _operator The address which initiated the transfer (i.e. msg.sender)
@param _from The address which previously owned the token
@param _id The ID of the token being transferred
@param _value The amount of tokens being transferred
@param _data Additional data with no specified format
@return `bytes4(keccak256("onVIP210Received(address,address,uint256,uint256,string)"))`
*/
function onVIP210Received(address _operator, address _from, uint256 _id, uint256 _value, string calldata _data) external returns(bytes4);
/**
@notice Handle the receipt of multiple VIP210 token types.
@dev An VIP210-compliant smart contract MUST call this function on the token recipient contract, at the end of a `safeBatchTransferFrom` after the balances have been updated.
This function MUST return `bytes4(keccak256("onVIP210BatchReceived(address,address,uint256[],uint256[],string)"))` (i.e. 0x004ac0e7) if it accepts the transfer(s).
This function MUST revert if it rejects the transfer(s).
Return of any other value than the prescribed keccak256 generated value MUST result in the transaction being reverted by the caller.
@param _operator The address which initiated the batch transfer (i.e. msg.sender)
@param _from The address which previously owned the token
@param _ids An array containing ids of each token being transferred (order and length must match _values array)
@param _values An array containing amounts of each token being transferred (order and length must match _ids array)
@param _data Additional data with no specified format
@return `bytes4(keccak256("onVIP210BatchReceived(address,address,uint256[],uint256[],string)"))`
*/
function onVIP210BatchReceived(address _operator, address _from, uint256[] calldata _ids, uint256[] calldata _values, string calldata _data) external returns(bytes4);
}
To be more explicit about how the standard safeTransferFrom and safeBatchTransferFrom functions MUST operate with respect to the VIP210TokenReceiver hook functions.
The URI value allows for ID substitution by clients. For VIP210 assets, your contract will need to return a URI where we can find the metadata. To find this URI, we use the uri method in VIP210.
function uri(uint256 _id) public view returns (string memory) {
return Strings.strConcat(baseMetadataURI, Strings.uint2str(_id));
}
The uri function in your VIP210 contract should return an HTTP or IPFS URL. When queried, this URL should in turn return a JSON blob of data with the metadata for your token.
This JSON schema is loosely based on the "VIP181 Metadata JSON Schema", but includes optional formatting to allow for ID substitution by clients.
{
"title": "Token Metadata",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of this token"
},
"symbol": {
"type": "string",
"description": "The symbol of this token"
},
"decimals": {
"type": "integer",
"description": "The number of decimal places that the token amount should display - e.g. 18, means to divide the token amount by 1000000000000000000 to get its user representation."
},
"description": {
"type": "string",
"description": "Describes the asset to which this token represents"
},
"image": {
"type": "string",
"description": "A URI pointing to a resource with mime type image/* representing the asset to which this token represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive."
},
"properties": {
"type": "object",
"description": "Arbitrary properties. Values may be strings, numbers, object or arrays."
}
}
}
An example of an VIP210 Metadata JSON file follows. The properties array proposes some SUGGESTED formatting for token-specific display properties and metadata.
{
"name": "Asset Name",
"description": "Some descriptions",
"image": "https://token-cdn-domain/images/1.png",
"properties": {
"simple_property": "example value",
"array_property": {
"name": "Name",
"value": [1,2,3,4],
"class": "emphasis"
}
}
}
Metadata localization should be standardized to increase presentation uniformity across all languages. As such, a simple overlay method is proposed to enable localization. If the metadata JSON file contains a localization attribute, its content MAY be used to provide localized values for fields that need it. The localization attribute should be a sub-object with three attributes: uri, default and locales. If the locale exists in any URI query parameter, it MUST be replaced with the chosen locale by all client software, such as https://token-cdn-domain/tokens/1?locale=en
{
"title": "Token Metadata",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of this token"
},
"symbol": {
"type": "string",
"description": "The symbol of this token"
},
"decimals": {
"type": "integer",
"description": "The number of decimal places that the token amount should display - e.g. 18, means to divide the token amount by 1000000000000000000 to get its user representation."
},
"description": {
"type": "string",
"description": "Describes the asset to which this token represents"
},
"image": {
"type": "string",
"description": "A URI pointing to a resource with mime type image/* representing the asset to which this token represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive."
},
"properties": {
"type": "object",
"description": "Arbitrary properties. Values may be strings, numbers, object or arrays.",
},
"localization": {
"type": "object",
"required": ["uri", "default", "locales"],
"properties": {
"default": {
"type": "string",
"description": "The locale of the default data within the base JSON"
},
"locales": {
"type": "array",
"description": "The list of locales for which data is available. These locales should conform to those defined in the Unicode Common Locale Data Repository (http://cldr.unicode.org/)."
}
}
}
}
}
Base URI:
{
"name": "Sample Token",
"symbol": "ST",
"decimals": 18,
"description": "This is a sample token description.",
"localization": {
"default": "en",
"locales": ["en", "zh"]
}
}
zh.json:
{
"name": "示例代币",
"symbol": "ST",
"decimals": 18,
"description": "这是一个示例代币的描述信息."
}