Skip to content

Commit

Permalink
Automatically merged updates to draft EIP(s) 2477 (ethereum#2529)
Browse files Browse the repository at this point in the history 
Hi, I'm a bot! This change was automatically merged because:

 - It only modifies existing Draft or Last Call EIP(s)
 - The PR was approved or written by at least one author of each modified EIP
 - The build is passing
  • Loading branch information
@fulldecent @tkstanczak
fulldecent authored and tkstanczak committed Nov 7, 2020
1 parent d1ac906 commit 2bb2cb2
Showing 1 changed file with 113 additions and 6 deletions.
119 changes: 113 additions & 6 deletions EIPS/eip-2477.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,10 +32,74 @@ Several token standards allow attaching metadata to specific tokens using a 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.

## Design

**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:

```
┌───────────────────────┐ ┌────────┐ ┌────────┐
│ TokenID │──────▶│Metadata│─────▶│ Schema │
└───────────────────────┘ └────────┘ └────────┘
```

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`:

```
┌───────────────────────┐ ┌────────┐ ┌ ─ ─ ─ ─
│ TokenID │──────▶│Metadata│─ ─ ─▶ Schema │
└───────────────────────┘ └────────┘ └ ─ ─ ─ ─
┌───────────────────────┐ ▲
│ 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`:

```
┌───────────────────────┐ ┌────────┐ ┌────────┐
│ TokenID │──────▶│Metadata│═════▶│ Schema │
└───────────────────────┘ └────────┘ └────────┘
┌───────────────────────┐ ▲
│ tokenURIIntegrity │════════════╝
└───────────────────────┘
```

**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`:

```
┌───────────────────────┐ ┌────────┐ ┌────────┐
│ TokenID │──────▶│Metadata│─────▶│ Schema │
└───────────────────────┘ └────────┘ └────────┘
┌───────────────────────┐ ▲ ▲
│ tokenURIIntegrity │════════════╝ ║
└───────────────────────┘ ║
┌───────────────────────┐ ║
│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`:

```
┌───────────────────────┐ ┌────────┐ ┌────────┐
│ TokenID │──────▶│Metadata│═════▶│ Schema │
└───────────────────────┘ └────────┘ └────────┘
┌───────────────────────┐ ▲ ▲
│ tokenURIIntegrity │════════════╝ ║
└───────────────────────┘ ║
┌───────────────────────┐ ║
│tokenURISchemaIntegrity│════════════════════════════╝
└───────────────────────┘
```

## Specification

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

**Smart contracts implementing the ERC-2477 standard MUST implement the `ERC2477` interface.**

```solidity
Expand All @@ -48,16 +112,16 @@ interface ERC2477 /* is ERC165 */ {
/**
* @notice Get the cryptographic hash of the specified tokenID's metadata
* @param tokenId Identifier for a specific token
* @return digest Bytes returned from the hash algorithm
* @return hashAlgorithm The name of the cryptographic hash algorithm
* @return digest Bytes returned from the hash algorithm, or "" if not available
* @return hashAlgorithm The name of the cryptographic hash algorithm, or "" if not available
*/
function tokenURIIntegrity(uint256 tokenId) external view returns(bytes memory digest, string memory hashAlgorithm);
/**
* @notice Get the cryptographic hash for the specified tokenID's metadata schema
* @param tokenId Id of the Xcert.
* @return digest Bytes returned from the hash algorithm or "" if there is no schema
* @return hashAlgorithm The name of the cryptographic hash algorithm or "" if there is no schema
* @return digest Bytes returned from the hash algorithm, or "" if not available
* @return hashAlgorithm The name of the cryptographic hash algorithm, or "" if not available
*/
function tokenURISchemaIntegrity(uint256 tokenId) external view returns(bytes memory digest, string memory hashAlgorithm);
}
Expand All @@ -67,15 +131,53 @@ The returned cryptographic hashes correspond to the token's metadata document an

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 identifier above.**
**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 client implementing the ERC-2477 standard MUST support at least the `sha256` hash algorithm and MAY support other algorithm.
### Metadata

A metadata document MAY use this schema to provide referential integrity to its schema document.

```json
{
"title": "EIP-2477 JSON Object With Refererential Integrity to Schema",
"type": "object",
"properties": {
"$schema": {
"type": "string",
"format": "uri"
},
"$schemaIntegrity": {
"type": "object",
"properties": {
"digest": {
"type": "string"
},
"hashAlgorithm": {
"type": "string"
}
},
"required": [
"digest",
"hashAlgorithm"
]
}
},
"required": [
"$schema",
"$schemaIntegrity"
]
}
```

### Clients

A client implementing the ERC-2477 standard MUST support at least the `sha256` hash algorithm and MAY support other algorithms.

### Caveats

Expand Down Expand Up @@ -210,6 +312,11 @@ Other standards
6. Uniform Resource Identifier (URI): Generic Syntax. https://tools.ietf.org/html/rfc3986
7. CID [Specification] (DRAFT). https://github.com/multiformats/cid

Discussion

1. JSON-LD discussion of referential integrity. https://lists.w3.org/Archives/Public/public-json-ld-wg/2020Feb/0003.html
2. JSON Schema use of `$schema` key for documents. https://github.com/json-schema-org/json-schema-spec/issues/647#issuecomment-417362877

Other

1. [Shattered] The first collision for full SHA-1. http://shattered.io/static/shattered.pdf
Expand Down

0 comments on commit 2bb2cb2

Please sign in to comment.