This specification defines a mechanism by which clients may verify that a fetched token metadata document has been delivered without unexpected manipulation.
This is the Web3 counterpart of the W3C Subresource Integrity (SRI) specification.
An interface ERC2477 with two functions tokenURIIntegrity and tokenURISchemaIntegrity are specified for smart contracts and a narrative is provided to explain how this improves the integrity of the token metadata documents.
Tokens are being used in many applications to represent, trace and provide access to assets off-chain. These assets include in-game digital items in mobile apps, luxury watches and products in our global supply chain, among many other creative uses.
Several token standards allow attaching metadata to specific tokens using a URI (RFC 3986) and these are supported by the applications mentioned above. These metadata standards are:
ERC721Metadata)ERC1155Metadata_URI)Although all these standards allow storing the metadata entirely on-chain (using the "data" URI, RFC 2397), or using a content-addressable system (e.g. IPFS's Content IDentifiers [sic]), nearly every implementation we have found is using Uniform Resource Locators (the exception is The Sandbox which uses IPFS URIs). These URLs provide no guarantees of content correctness or immutability. This standard adds such guarantees.
Approach A: A token contract may reference metadata by using its URL. This provides no integrity protection because the referenced metadata and/or schema could change at any time if the hosted content is mutable. This is the world before EIP-2477:
Note: according to the JSON Schema project, a metadata document referencing a schema using a URI in the $schema key is a known approach, but it is not standardized.
Approach B: EIP-2477 provides mechanisms to establish integrity for these references. In one approach, there is integrity for the metadata document. Here, the on-chain data includes a hash of the metadata document. The metadata may or may not reference a schema. In this approach, changing the metadata document will require updating on-chain tokenURIIntegrity:
Approach C: In a stronger approach, the schema is referenced by the metadata using an extension to JSON Schema, providing integrity. In this approach, changing the metadata document or the schema will require updating on-chain tokenURIIntegrity and the metadata document, additionally changing the schema requires updating the on-chain tokenURISchemaIntegrity:
Approach D: Equally strong, the metadata can make a normal reference (no integrity protection) to the schema and on-chain data also includes a hash of the schema document. In this approach, changing the metadata document will require updating on-chain tokenURIIntegrity and updating the schema document will require updating the tokenURISchemaIntegrity:
Approach E: Lastly, the schema can be referenced with integrity from the metadata and also using on-chain data. In this approach, changing the metadata document or the schema will require updating on-chain tokenURIIntegrity and the metadata document, additionally changing the schema requires updating the on-chain tokenURISchemaIntegrity:
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 ERC-2477 standard MUST implement the ERC2477 interface.
The returned cryptographic hashes correspond to the token's metadata document and that metadata document's schema, respectively.
For example, with ERC-721 tokenURIIntegrity(21) would correspond to tokenURI(21). With ERC-1155, tokenURIIntegrity(16) would correspond to uri(16). In both cases, tokenURISchemaIntegrity(32) would correspond to the schema of the document matched by tokenURIIntegrity(32).
Smart contracts implementing the ERC-2477 standard MUST implement the ERC-165 standard, including the interface identifiers above.
Smart contracts implementing the ERC-2477 standard MAY use any hashing or content integrity scheme.
Smart contracts implementing the ERC-2477 standard MAY use or omit a mechanism to notify when the integrity is updated (e.g. an Ethereum logging operation).
Smart contracts implementing the ERC-2477 standard MAY use any mechanism to provide schemas for metadata documents and SHOULD use JSON-LD on the metadata document for this purpose (i.e. "@schema":...).
A metadata document MAY conform to this schema to provide referential integrity to its schema document.
A client implementing the ERC-2477 standard MUST support at least the sha256 hash algorithm and MAY support other algorithms.
tokenURI(uint id) or similar function.Function and parameter naming
The W3C Subresource Integrity (SRI) specification uses the attribute "integrity" to perform integrity verification. This ERC-2477 standard provides a similar mechanism and reuses the integrity name so as to be familiar to people that have seen SRI before.
Function return tuple
The SRI integrity attribute encodes elements of the tuple $$(cryptographic\ hash\ function, digest, options)$$. This ERC-2477 standard returns a digest and hash function name and omits forward-compatibility options.
Currently, the SRI specification does not make use of options. So we cannot know what format they might be when implemented. This is the motivation to exclude this parameter.
The digest return value is first, this is an optimization because we expect on-chain implementations will be more likely to use this return value if they will only be using one of the two.
Function return types
The digest is a byte array and supports various hash lengths. This is consistent with SRI. Whereas SRI uses base64 encoding to target an HTML document, we use a byte array because Ethereum already allows this encoding.
The hash function name is a string. Currently there is no universal taxonomy of hash function names. SRI recognizes the names sha256, sha384 and sha512 with case-insensitive matching. We are aware of two authorities which provide taxonomies and canonical names for hash functions: ETSI Object Identifiers and NIST Computer Security Objects Register. However, SRI's approach is easier to follow and we have adopted this here.
Function return type — hash length
Clients must support the SHA-256 algorithm and may optionally support others. This is a departure from the SRI specification where SHA-256, SHA-384 and SHA-512 are all required. The rationale for this less-secure requirement is because we expect some clients to be on-chain. Currently SHA-256 is simple and cheap to do on Ethereum whereas SHA-384 and SHA-512 are more expensive and cumbersome.
The most popular hash function size below 256 bits in current use is SHA-1 at 160 bits. Multiple collisions (the "Shattered" PDF file, the 320 byte file, the chosen prefix) have been published and a recipe is given to generate infinitely more collisions. SHA-1 is broken. The United States National Institute of Standards and Technology (NIST) has first deprecated SHA-1 for certain use cases in November 2015 and has later further expanded this deprecation.
The most popular hash function size above 256 bits in current use is SHA-384 as specified by NIST.
The United States National Security Agency requires a hash length of 384 or more bits for the SHA-2 (CNSA Suite Factsheet) algorithm suite for use on TOP SECRET networks. (No unclassified documents are currently available to specify use cases at higher classification networks.)
We suspect that SHA-256 and the 0xcert Asset Certification will be popular choices to secure token metadata for the foreseeable future.
In-band signaling
One possible way to achieve strong content integrity with the existing token standards would be to include, for example, a ?integrity=XXXXX at the end of all URLs. This approach is not used by any existing implementations we know about. There are a few reasons we have not chosen this approach. The strongest reason is that the World Wide Web has the same problem and they chose to use the Sub-Resource Integrity approach, which is a separate data field than the URL.
Other supplementary reasons are:
For on-chain consumers of data, it is easier to parse a direct hash field than to perform string operations.
Maybe there are some URIs which are not amenable to being modified in that way, therefore limiting the generalizability of that approach.
This design justification also applies to tokenURISchemaIntegrity. The current JSON-LD specification allows a JSON document to link to a schema document. But it does not provide integrity. Rather than changing how JSON-LD works, or changing JSON Schemas, we have the tokenURISchemaIntegrity property to just provide the integrity.
Both ERC-721 and ERC-1155 provide compatible token metadata specifications that use URIs and JSON schemas. The ERC-2477 standard is compatible with both, and all specifications are additive. Therefore, there are no backward compatibility regressions.
ERC-1523 Standard for Insurance Policies as ERC-721 Non Fungible Tokens (DRAFT) proposes an extension to ERC-721 which also tightens the requirements on metadata. Because it is wholly an extension of ERC-721, ERC-1523 is automatically supported by ERC-2477 (since this standard already supports ERC-721).
ERC-1046 (DRAFT) ERC-20 Metadata Extension proposes a comparate extension for ERC-20. Such a concept is outside the scope of this ERC-2477 standard. Should ERC-1046 (DRAFT) be finalized, we will welcome a new ERC which copies ERC-2477 and removes the tokenId parameter.
Similarly, ERC-918 (DRAFT) Mineable Token Standard proposes an extension for ERC-20 and also includes metadata. The same comment applies here as ERC-1046.
Following is a token metadata document which is simultaneously compatible with ERC-721, ERC-1155 and ERC-2477 standards.
This above example shows how JSON-LD is employed to reference the schema document ($schema).
Following is a corresponding schema document which is accessible using the URI "https://URL_TO_SCHEMA_DOCUMENT" above.
Assume that the metadata and schema above apply to a token with identifier 1234. (In ERC-721 this would be a specific token, in ERC-1155 this would be a token type.) Then these two function calls MAY have the following output:
function tokenURIIntegrity(1234)
bytes digest : 3fc58b72faff20684f1925fd379907e22e96b660string hashAlgorithm: sha256function tokenURISchemaIntegrity(1234)
bytes digest : ddb61583d82e87502d5ee94e3f2237f864eeff72string hashAlgorithm: sha256To avoid doubt: the previous paragraph specifies "MAY" have that output because other hash functions are also acceptable.
0xcert Framework supports ERC-2477.
Normative standard references
Other standards
Discussion
$schema key for documents. https://github.com/json-schema-org/json-schema-spec/issues/647#issuecomment-417362877Other
Copyright and related rights waived via CC0.