Skip to content

Commit

Permalink
Clean up points (ethereum#3979)
Browse files Browse the repository at this point in the history
  • Loading branch information
@fulldecent @PhABC
fulldecent authored and PhABC committed Jan 25, 2022
1 parent 527e4d4 commit e52e071
Showing 1 changed file with 64 additions and 72 deletions.
136 changes: 64 additions & 72 deletions EIPS/eip-2477.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -103,26 +103,24 @@ The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL
**Smart contracts implementing the ERC-2477 standard MUST implement the `ERC2477` interface.**

```solidity
pragma solidity ^0.6.0;
// SPDX-License-Identifier: CC0-1.0
pragma solidity ^0.8.7;
/// @title ERC-2477 Token Metadata Integrity
/// @dev See https://eips.ethereum.org/EIPS/eip-2477
/// @dev The ERC-165 identifier for this interface is 0x#######. //TODO: FIX THIS
/// @dev The ERC-165 identifier for this interface is 0x832a7e0e
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, or "" if not available
* @return hashAlgorithm The name of the cryptographic hash algorithm, or "" if not available
*/
/// @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, 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 not available
* @return hashAlgorithm The name of the cryptographic hash algorithm, or "" if not available
*/
/// @notice Get the cryptographic hash for the specified tokenID's metadata schema
/// @param tokenId Identifier for a specific token
/// @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 @@ -141,37 +139,31 @@ Smart contracts implementing the ERC-2477 standard MAY use any mechanism to prov

### Metadata

A metadata document MAY use this schema to provide referential integrity to its schema document.
A metadata document MAY conform to 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"
"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"
},
"$schemaIntegrity": {
"type": "object",
"properties": {
"digest": {
"type": "string"
},
"hashAlgorithm": {
"type": "string"
}
},
"required": [
"digest",
"hashAlgorithm"
]
"hashAlgorithm": {
"type": "string"
}
},
"required": [
"$schema",
"$schemaIntegrity"
]
},
"required": ["digest", "hashAlgorithm"]
}
},
"required": ["$schema", "$schemaIntegrity"]
}
```

Expand Down Expand Up @@ -201,8 +193,6 @@ The digest return value is first, this is an optimization because we expect on-c

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.

:warning: TODO: WE NEED TO SPECIFY ENDIANNESS ABOVE AND PROVIDE TEST CASES BELOW. AND JUSTIFY THAT HERE.

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**
Expand All @@ -223,9 +213,9 @@ One possible way to achieve strong content integrity with the existing token sta

Other supplementary reasons are:

* For on-chain consumers of data, it is easier to parse a direct hash field than to perform string operations
* 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
* 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.

Expand All @@ -245,10 +235,10 @@ Following is a token metadata document which is simultaneously compatible with E

```json
{
"$schema": "https://URL_TO_SCHEMA_DOCUMENT",
"name": "Asset Name",
"description": "Lorem ipsum...",
"image": "https:\/\/s3.amazonaws.com\/your-bucket\/images\/{id}.png",
"$schema": "https://URL_TO_SCHEMA_DOCUMENT",
"name": "Asset Name",
"description": "Lorem ipsum...",
"image": "https://s3.amazonaws.com/your-bucket/images/{id}.png"
}
```

Expand All @@ -258,21 +248,21 @@ Following is a corresponding schema document which is accessible using the URI `

```json
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Identifies the asset to which this NFT represents"
},
"description": {
"type": "string",
"description": "Describes the asset to which this NFT represents"
},
"image": {
"type": "string",
"description": "A URI pointing to a resource with mime type image/* representing the asset to which this NFT represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive."
}
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Identifies the asset to which this NFT represents"
},
"description": {
"type": "string",
"description": "Describes the asset to which this NFT represents"
},
"image": {
"type": "string",
"description": "A URI pointing to a resource with mime type image/* representing the asset to which this NFT represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive."
}
}
}
```

Expand All @@ -289,7 +279,7 @@ To avoid doubt: the previous paragraph specifies "MAY" have that output because

## Implementation

TODO: ADD IMPLEMENTATIONS WITH 0XCERT ENJIN, NIKE, AZURE/MICROSOFT
0xcert Framework supports ERC-2477.

## Reference

Expand Down Expand Up @@ -319,15 +309,17 @@ Discussion

Other

1. [Shattered] The first collision for full SHA-1. https://shattered.io/static/shattered.pdf
2. [320 byte file] The second SHA Collision. https://privacylog.blogspot.com/2019/12/the-second-sha-collision.html
3. [Chosen prefix] https://sha-mbles.github.io
4. Transitions: Recommendation for Transitioning the Use of Cryptographic Algorithms and Key Lengths. (Rev. 1. Superseded.) https://csrc.nist.gov/publications/detail/sp/800-131a/rev-1/archive/2015-11-06
5. Commercial National Security Algorithm (CNSA) Suite Factsheet. https://apps.nsa.gov/iaarchive/library/ia-guidance/ia-solutions-for-classified/algorithm-guidance/commercial-national-security-algorithm-suite-factsheet.cfm
6. ETSI Assigned ASN.1 Object Identifiers. https://portal.etsi.org/pnns/oidlist
7. Computer Security Objects Register. https://csrc.nist.gov/projects/computer-security-objects-register/algorithm-registration
8. The Sandbox implementation. https://github.com/pixowl/sandbox-smart-contracts/blob/7022ce38f81363b8b75a64e6457f6923d91960d6/src/Asset/ERC1155ERC721.sol
1. [0xcert Framework supports ERC-2477]. https://github.com/0xcert/framework/pull/717
2. [Shattered] The first collision for full SHA-1. https://shattered.io/static/shattered.pdf
3. [320 byte file] The second SHA Collision. https://privacylog.blogspot.com/2019/12/the-second-sha-collision.html
4. [Chosen prefix] https://sha-mbles.github.io
5. Transitions: Recommendation for Transitioning the Use of Cryptographic Algorithms and Key Lengths. (Rev. 1. Superseded.) https://csrc.nist.gov/publications/detail/sp/800-131a/rev-1/archive/2015-11-06
6. Commercial National Security Algorithm (CNSA) Suite Factsheet. https://apps.nsa.gov/iaarchive/library/ia-guidance/ia-solutions-for-classified/algorithm-guidance/commercial-national-security-algorithm-suite-factsheet.cfm
7. ETSI Assigned ASN.1 Object Identifiers. https://portal.etsi.org/pnns/oidlist
8. Computer Security Objects Register. https://csrc.nist.gov/projects/computer-security-objects-register/algorithm-registration
9. The Sandbox implementation. https://github.com/pixowl/sandbox-smart-contracts/blob/7022ce38f81363b8b75a64e6457f6923d91960d6/src/Asset/ERC1155ERC721.sol

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

0 comments on commit e52e071

Please sign in to comment.