SRC-1046: tokenURI Interoperability

Extends SRC-20 with an SRC-721-like tokenURI, and extends SRC-721 and SRC-1155 with interoperability

Abstract

SRC-721 introduced a tokenURI function for non-fungible tokens to handle miscellaneous metadata such as:

• thumbnail image
• title
• description
• special asset properties
• etc.

This SRC adds a tokenURI function to SRC-20, and extends SRC-721 and SRC-1155 to enable interoperability between all three types of token URI.

Motivation

See the note about the metadata extension in SRC-721. The same arguments apply to SRC-20.

Being able to use similar mechanisms to extract metadata for SRC-20, SRC-721, SRC-1155, and future standards is useful for determining:

• What type of token a contract is (if any);
• How to display a token to a user, either in an asset listing page or on a dedicated token page; and
• Determining the capabilities of the token

Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 and RFC 8174.

Interoperability Metadata

The following TypeScript interface is used in later sections:

/**
 * Interoperability metadata.
 * This can be extended by other proposals.
 * 
 * All fields MUST be optional.
 * **Not every field has to be a boolean.** Any optional JSON-serializable object can be used by extensions.
 */
interface InteroperabilityMetadata {
    /**
     * This MUST be true if this is SRC-1046 Token Metadata, otherwise, this MUST be omitted.
     * Setting this to true indicates to wallets that the address should be treated as an SRC-20 token.
     **/
    src1046?: boolean | undefined;

    /**
     * This MUST be true if this is SRC-721 Token Metadata, otherwise, this MUST be omitted.
     * Setting this to true indicates to wallets that the address should be treated as an SRC-721 token.
     **/
    src721?: boolean | undefined;

    /**
     * This MUST be true if this is SRC-1155 Token Metadata, otherwise, this MUST be omitted.
     * Setting this to true indicates to wallets that the address should be treated as an SRC-1155 token.
     **/
    src1155?: boolean | undefined;
}

SRC-20 Extension

SRC-20 Interface Extension

Compliant contracts MUST implement the following Solidity interface:

pragma solidity ^0.8.0;

/// @title  SRC-20 Metadata Extension
interface SRC20TokenMetadata /* is SRC20 */ {
    /// @notice     Gets an SRC-721-like token URI
    /// @dev        The resolved data MUST be in JSON format and support SRC-1046's SRC-20 Token Metadata Schema
    function tokenURI() external view returns (string);
}

SRC-20 Token Metadata Schema

The resolved JSON of the tokenURI described in the SRC-20 Interface Extension section MUST conform to the following TypeScript interface:

/**
 * Asset Metadata
 */
interface SRC20TokenMetadata {
    /**
     * Interoperability, to differentiate between different types of tokens and their corresponding URIs.
     **/
    interop: InteroperabilityMetadata;
    
    /**
     * The name of the SRC-20 token. 
     * If the `name()` function is present in the SRC-20 token and returns a nonempty string, these MUST be the same value.
     */
    name?: string;
    
    /**
     * The symbol of the SRC-20 token. 
     * If the `symbol()` function is present in the SRC-20 token and returns a nonempty string, these MUST be the same value.
     */
    symbol?: string;
    
    /**
     * The decimals of the SRC-20 token. 
     * If the `decimals()` function is present in the SRC-20 token, these MUST be the same value.
     * Defaults to 18 if neither this parameter nor the SRC-20 `decimals()` function are present.
     */
    decimals?: number;
    
    /**
     * Provides a short one-paragraph description of the SRC-20 token, without any markup or newlines.
     */
    description?: string;
    
    /**
     * A URI pointing to a resource with mime type `image/*` that represents this token.
     * If the image is a bitmap, it SHOULD have a width between 320 and 1080 pixels
     * The image SHOULD have an aspect ratio between 1.91:1 and 4:5 inclusive.
     */
    image?: string;
    
    /**
     * One or more URIs each pointing to a resource with mime type `image/*` that represents this token.
     * If an image is a bitmap, it SHOULD have a width between 320 and 1080 pixels
     * Images SHOULD have an aspect ratio between 1.91:1 and 4:5 inclusive.
     */
    images?: string[];
    
    /**
     * One or more URIs each pointing to a resource with mime type `image/*` that represent an icon for this token.
     * If an image is a bitmap, it SHOULD have a width between 320 and 1080 pixels, and MUST have a height equal to its width
     * Images MUST have an aspect ratio of 1:1, and use a transparent background
     */
    icons?: string[];
}

SRC-721 Extension

Extension to the SRC-721 Metadata Schema

Contracts that implement SRC-721 and use its token metadata URI SHOULD to use the following TypeScript extension to the metadata URI:

interface SRC721TokenMetadataInterop extends SRC721TokenMetadata {
    /**
     * Interoperability, to avoid confusion between different token URIs
     **/
    interop: InteroperabilityMetadata;
}

SRC-1155 Extension

SRC-1155 Interface Extension

SRC-1155-compliant contracts using the metadata extension SHOULD implement the following Solidity interface:

pragma solidity ^0.8.0;

/// @title  SRC-1155 Metadata URI Interoperability Extension
interface SRC1155TokenMetadataInterop /* is SRC1155 */ {
    /// @notice         Gets an SRC-1046-compliant SRC-1155 token URI
    /// @param  tokenId The token ID to get the URI of
    /// @dev            The resolved data MUST be in JSON format and support SRC-1046's Extension to the SRC-1155 Token Metadata Schema
    ///                 This MUST be the same URI as the `uri(tokenId)` function, if present.
    function tokenURI(uint256 tokenId) external view returns (string);
}

Extension to the SRC-1155 Metadata Schema

Contracts that implement SRC-1155 and use its token metadata URI are RECOMMENDED to use the following extension to the metadata URI. Contracts that implement the interface described in the SRC-1155 Interface Extension section MUST use the following TypeScript extension:

interface SRC1155TokenMetadataInterop extends SRC1155TokenMetadata {
    /**
     * Interoperability, to avoid confusion between different token URIs
     **/
    interop: InteroperabilityMetadata;
}

Miscellaneous Recommendations

To save gas, it is RECOMMENDED for compliant contracts not to implement the name(), symbol(), or decimals() functions, and instead to only include them in the metadata URI. Additionally, for SRC-20 tokens, if the decimals is 18, then it is NOT RECOMMENDED to include the decimals field in the metadata.

Rationale

This SRC makes adding metadata to SRC-20 tokens more straightforward for developers, with minimal to no disruption to the overall ecosystem. Using the same parameter name makes it easier to reuse code.

Additionally, the recommendations not to use SRC-20’s name, symbol, and decimals functions save gas.

Built-in interoperability is useful as otherwise it might not be easy to differentiate the type of the token. Interoperability could be done using SRC-165, but static calls are time-inefficient for wallets and websites, and is generally inflexible. Instead, including interoperability data in the token URI increases flexibility while also giving a performance increase.

Backwards Compatibility

This SIP is fully backwards compatible as its implementation simply extends the functionality of SRC-20 tokens and is optional. Additionally, it makes backward compatible recommendations for SRC-721 and SRC-1155 tokens.

Security Considerations

Server-Side Request Forgery (SSRF)

Wallets should be careful about making arbitrary requests to URLs. As such, it is recommended for wallets to sanitize the URI by whitelisting specific schemes and ports. A vulnerable wallet could be tricked into, for example, modifying data on a locally-hosted redis database.

Copyright

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

Tommy Nicholas (@tomasienrbc), Matt Russo (@mateosu), John Zettler (@JohnZettler), Matt Condon (@shrugs), Gavin John (@Pandapip1), "SRC-1046: tokenURI Interoperability," Sila Improvement Proposals, no. 1046, April 2018. Available: https://sips.sila.org/SIPS/sip-1046.