Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Move ERCs to separate repository #7206

Merged
merged 1 commit into from Oct 25, 2023
+365 −183,578
Merged

Move ERCs to separate repository #7206

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
223 changes: 1 addition & 222 deletions EIPS/eip-1046.md
View file
Open in desktop
@@ -1,222 +1 @@
---
eip: 1046
title: tokenURI Interoperability
description: Extends ERC-20 with an ERC-721-like tokenURI, and extends ERC-721 and ERC-1155 with interoperability
author: Tommy Nicholas (@tomasienrbc), Matt Russo (@mateosu), John Zettler (@JohnZettler), Matt Condon (@shrugs), Gavin John (@Pandapip1)
discussions-to: https://ethereum-magicians.org/t/eip-1046-erc-20-metadata-extension/13036
status: Final
type: Standards Track
category: ERC
created: 2018-04-13
requires: 20, 721, 1155
---

## Abstract

[ERC-721](./eip-721.md) introduced a `tokenURI` function for non-fungible tokens to handle miscellaneous metadata such as:

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

This ERC adds a `tokenURI` function to [ERC-20](./eip-20.md), and extends [ERC-721](./eip-721.md) and [ERC-1155](./eip-1155.md) to enable interoperability between all three types of token URI.

## Motivation

See the note about the metadata extension in [ERC-721](./eip-721.md#rationale). The same arguments apply to ERC-20.

Being able to use similar mechanisms to extract metadata for ERC-20, ERC-721, ERC-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:

```typescript
/**
* 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 ERC-1046 Token Metadata, otherwise, this MUST be omitted.
* Setting this to true indicates to wallets that the address should be treated as an ERC-20 token.
**/
erc1046?: boolean | undefined;

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

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

### ERC-20 Extension

#### ERC-20 Interface Extension

Compliant contracts MUST implement the following Solidity interface:

```solidity
pragma solidity ^0.8.0;

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

#### ERC-20 Token Metadata Schema

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

```typescript
/**
* Asset Metadata
*/
interface ERC20TokenMetadata {
/**
* Interoperabiliy, to differentiate between different types of tokens and their corresponding URIs.
**/
interop: InteroperabilityMetadata;

/**
* The name of the ERC-20 token.
* If the `name()` function is present in the ERC-20 token and returns a nonempty string, these MUST be the same value.
*/
name?: string;

/**
* The symbol of the ERC-20 token.
* If the `symbol()` function is present in the ERC-20 token and returns a nonempty string, these MUST be the same value.
*/
symbol?: string;

/**
* The decimals of the ERC-20 token.
* If the `decimals()` function is present in the ERC-20 token, these MUST be the same value.
* Defaults to 18 if neither this parameter nor the ERC-20 `decimals()` function are present.
*/
decimals?: number;

/**
* Provides a short one-paragraph description of the ERC-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[];
}
```

### ERC-721 Extension

#### Extension to the ERC-721 Metadata Schema

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

```typescript
interface ERC721TokenMetadataInterop extends ERC721TokenMetadata {
/**
* Interoperabiliy, to avoid confusion between different token URIs
**/
interop: InteroperabilityMetadata;
}
```

### ERC-1155 Extension

#### ERC-1155 Interface Extension

[ERC-1155](./eip-1155.md)-compliant contracts using the metadata extension SHOULD implement the following Solidity interface:

```solidity
pragma solidity ^0.8.0;

/// @title ERC-1155 Metadata URI Interoperability Extension
interface ERC1155TokenMetadataInterop /* is ERC1155 */ {
/// @notice Gets an ERC-1046-compliant ERC-1155 token URI
/// @param tokenId The token ID to get the URI of
/// @dev The resolved data MUST be in JSON format and support ERC-1046's Extension to the ERC-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 ERC-1155 Metadata Schema

Contracts that implement ERC-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 ERC-1155 Interface Extension section MUST use the following TypeScript extension:

```typescript
interface ERC1155TokenMetadataInterop extends ERC1155TokenMetadata {
/**
* Interoperabiliy, 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 ERC-20 tokens, if the decimals is `18`, then it is NOT RECOMMENDED to include the `decimals` field in the metadata.

## Rationale

This ERC makes adding metadata to ERC-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 ERC-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 [ERC-165](./eip-165.md), 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 EIP is fully backwards compatible as its implementation simply extends the functionality of ERC-20 tokens and is optional. Additionally, it makes backward compatible recommendations for ERC-721 and ERC-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](../LICENSE.md).
This file was moved to https://github.com/ethereum/ercs/blob/master/ercs/erc-1046.md