Skip to content

Commit

Permalink
Add EIP-5678: Add new utilities extension for ERC-721 (#5678)
Browse files Browse the repository at this point in the history
  • Loading branch information
@OT-kraftchain
OT-kraftchain committed Mar 27, 2023
1 parent 3aed162 commit 09ff15c
Show file tree
Hide file tree
Showing 12 changed files with 1,099 additions and 0 deletions.
202 changes: 202 additions & 0 deletions EIPS/eip-5678.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,202 @@
---
title: ERC-5678 - ERC-721 Utilities Extension
description: Easy access to utility information via functions and the NFT's metadata
author: Otniel Nicola (@OT-kthd), Bogdan Popa (@BogdanKTHD)
discussions-to: https://ethereum-magicians.org/t/eip-5678-erc-721-utilities-extension/13568
status: Draft
type: Standards Track
category: ERC
created: 2023-03-27
requires: 165, 721
---

## Abstract

This specification defines standard functions that outline what a utility entails for a specific NFT and how it may be
used. This specification is an optional extension of [EIP-721](./eip-721.md).

## Motivation

This specification aims to bring clarity what the utility associated with an NFT is and how to access this utility.
Relying on third-party platforms to obtain information regarding the utility of the NFT that one owns can lead to scams,
phishing or other forms of fraud.

## Specification

The keywords “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.

Every contract compliant with EIP-5678 MUST implement the IERC5678 interface defined as follows:

### Contract Interface

```solidity
// @title NFT Utility description
/// Note: the EIP-165 identifier for this interface is 0xbcc08bd0
interface IERC5678 {
// Logged when the utility description URL of an NFT is changed
/// @notice Emitted when the utilityURL of an NFT is changed
/// The empty string for `utilityUri` indicates that there is no utility associated
event UpdateUtility(uint256 indexed tokenId, string utilityUri);
/// @notice set the new utilityUri - remember the date it was set on
/// @dev The empty string indicates there is no utility
/// Throws if `tokenId` is not valid NFT
/// @param utilityUri The new utility description of the NFT
/// 324a28b4
function setUtilityUri(uint256 tokenId, string utilityUri) external;
/// @notice Get the utilityUri of an NFT
/// @dev The empty string for `utilityUri` indicates that there is no utility associated
/// @param tokenId The NFT to get the user address for
/// @return The utility uri for this NFT
/// 438b8582
function getUtilityUri(uint256 tokenId) external view returns (string memory);
/// @notice Get the changes made to utilityUri
/// @param tokenId The NFT to get the user address for
/// @return The history of changes to `utilityUri` for this NFT
/// af5a3ae2
function getUtilityHistory(uint256 tokenId) external view returns (string[] memory);
}
```

All functions defined as view MAY be implemented as pure or view

Function `setUtilityUri` MAY be implemented as public or external

The event `UpdateUtility` MUST be emitted when the setUtilityUri function is called

The supportsInterface method MUST return true when called with `0xbcc08bd0`

The original metadata SHOULD conform to the “ERC-5678 Metadata with utilities JSON Schema” which is a compatible
extension of the “ERC-721 Metadata JSON Schema” defined in `ERC-721`.

“ERC-5678 Metadata with utilities JSON Schema” :

```json
{
"title": "Asset Metadata",
"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."
},
"utilities": {
"type": "object",
"required": [
"type",
"description",
"t&c"
],
"properties": {
"type": {
"type": "string",
"description": "Describes what type of utility this is"
},
"description": {
"type": "string",
"description": "A brief description of the utility"
},
"properties": {
"type": "array",
"description": "An array of possible properties describing the utility, defined as key-value pairs",
"items": {
"type": "object"
}
},
"expiry": {
"type": "number",
"description": "The period of time for the validity of the utility, since the minting of the NFT. Expressed in seconds"
},
"t&c": {
"type": "string",
"description": ""
}
}
}
}
}
```

## Rationale

Currently, utilities that are offered with NFTs, are not captured on-chain. We want the utility of an NFT to be part of
the metadata of an NFT, and thus immutable. The metadata information would include: a) type of utility, b) description
of utility, c) frequency and duration of utility, and d) expiration of utility. This will provide transparency as to the
utility terms, and greater accountability on the creator to honor these utilities.

Instructions on how to access the utility should be available to the owner of an NFT, as it reduces the dependency on
third-party platforms and the possibility for fraud because the `utilityUri` containing the instructions can only come
from the entity that provides or facilitates the utility. Thus, the ability to set the `utilityUri` should be restricted
to the creator who's offering the utility. Since the `utilityUri` contains information that could be restricted to some
level and is dependent on a third party platform, the creator needs the ability to modify it in the event the platform
becomes unavailable or inaccessible.

As the instructions on how to access a given utility may change over time, there should be a historical record of these
changes for transparency.

For example, if a creator sells an NFT that gives holders a right to a video call with the creator, the metadata for
this utility NFT would read as follows:

```json
{
"name": "...",
"description": "...",
"image": "...",
"utilities": {
"type": "Video call",
"description": "I will enter a private video call with whoever owns the NFT",
"properties": [
{
"sessions": 2
},
{
"duration": 30
},
{
"time_unit": "minutes"
}
],
"expiry": 1.577e+7,
"t&c": "https://...."
}
}
```

In order to get access to the details needed to enter the video call, the owner would access the URI returned by
the `getUtilityUri` method for the NFT that they own. Additionally, access to the details could be conditioned by the
authentication with the wallet that owns the NFT.
The current status of the utility would also be included in the URI (eg: how many sessions are still available, etc.)

## Backwards Compatibility

This standard is compatible with current EIP-721 standard. There are no other standards that define similar methods for
NFTs and the method names are not used by other EIP-721 related standards.

## Test Cases

Test cases are available [here](../assets/eip-5678/test/ERC5678.test.js)

## Reference Implementation

The reference implementation can be found [here](../assets/eip-5678/contracts/ERC5678.sol).

## Security Considerations

There are no security considerations related directly to the implementation of this standard.

## Copyright

Copyright and related rights waived via [CC0](../assets/eip-5678/LICENSE).
6 changes: 6 additions & 0 deletions assets/eip-5678/.gitignore
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
node_modules
package-lock.json

#Hardhat files
cache
artifacts
121 changes: 121 additions & 0 deletions assets/eip-5678/LICENSE
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
Creative Commons Legal Code

CC0 1.0 Universal

CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
HEREUNDER.

Statement of Purpose

The laws of most jurisdictions throughout the world automatically confer
exclusive Copyright and Related Rights (defined below) upon the creator
and subsequent owner(s) (each and all, an "owner") of an original work of
authorship and/or a database (each, a "Work").

Certain owners wish to permanently relinquish those rights to a Work for
the purpose of contributing to a commons of creative, cultural and
scientific works ("Commons") that the public can reliably and without fear
of later claims of infringement build upon, modify, incorporate in other
works, reuse and redistribute as freely as possible in any form whatsoever
and for any purposes, including without limitation commercial purposes.
These owners may contribute to the Commons to promote the ideal of a free
culture and the further production of creative, cultural and scientific
works, or to gain reputation or greater distribution for their Work in
part through the use and efforts of others.

For these and/or other purposes and motivations, and without any
expectation of additional consideration or compensation, the person
associating CC0 with a Work (the "Affirmer"), to the extent that he or she
is an owner of Copyright and Related Rights in the Work, voluntarily
elects to apply CC0 to the Work and publicly distribute the Work under its
terms, with knowledge of his or her Copyright and Related Rights in the
Work and the meaning and intended legal effect of CC0 on those rights.

1. Copyright and Related Rights. A Work made available under CC0 may be
protected by copyright and related or neighboring rights ("Copyright and
Related Rights"). Copyright and Related Rights include, but are not
limited to, the following:

i. the right to reproduce, adapt, distribute, perform, display,
communicate, and translate a Work;
ii. moral rights retained by the original author(s) and/or performer(s);
iii. publicity and privacy rights pertaining to a person's image or
likeness depicted in a Work;
iv. rights protecting against unfair competition in regards to a Work,
subject to the limitations in paragraph 4(a), below;
v. rights protecting the extraction, dissemination, use and reuse of data
in a Work;
vi. database rights (such as those arising under Directive 96/9/EC of the
European Parliament and of the Council of 11 March 1996 on the legal
protection of databases, and under any national implementation
thereof, including any amended or successor version of such
directive); and
vii. other similar, equivalent or corresponding rights throughout the
world based on applicable law or treaty, and any national
implementations thereof.

2. Waiver. To the greatest extent permitted by, but not in contravention
of, applicable law, Affirmer hereby overtly, fully, permanently,
irrevocably and unconditionally waives, abandons, and surrenders all of
Affirmer's Copyright and Related Rights and associated claims and causes
of action, whether now known or unknown (including existing as well as
future claims and causes of action), in the Work (i) in all territories
worldwide, (ii) for the maximum duration provided by applicable law or
treaty (including future time extensions), (iii) in any current or future
medium and for any number of copies, and (iv) for any purpose whatsoever,
including without limitation commercial, advertising or promotional
purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
member of the public at large and to the detriment of Affirmer's heirs and
successors, fully intending that such Waiver shall not be subject to
revocation, rescission, cancellation, termination, or any other legal or
equitable action to disrupt the quiet enjoyment of the Work by the public
as contemplated by Affirmer's express Statement of Purpose.

3. Public License Fallback. Should any part of the Waiver for any reason
be judged legally invalid or ineffective under applicable law, then the
Waiver shall be preserved to the maximum extent permitted taking into
account Affirmer's express Statement of Purpose. In addition, to the
extent the Waiver is so judged Affirmer hereby grants to each affected
person a royalty-free, non transferable, non sublicensable, non exclusive,
irrevocable and unconditional license to exercise Affirmer's Copyright and
Related Rights in the Work (i) in all territories worldwide, (ii) for the
maximum duration provided by applicable law or treaty (including future
time extensions), (iii) in any current or future medium and for any number
of copies, and (iv) for any purpose whatsoever, including without
limitation commercial, advertising or promotional purposes (the
"License"). The License shall be deemed effective as of the date CC0 was
applied by Affirmer to the Work. Should any part of the License for any
reason be judged legally invalid or ineffective under applicable law, such
partial invalidity or ineffectiveness shall not invalidate the remainder
of the License, and in such case Affirmer hereby affirms that he or she
will not (i) exercise any of his or her remaining Copyright and Related
Rights in the Work or (ii) assert any associated claims and causes of
action with respect to the Work, in either case contrary to Affirmer's
express Statement of Purpose.

4. Limitations and Disclaimers.

a. No trademark or patent rights held by Affirmer are waived, abandoned,
surrendered, licensed or otherwise affected by this document.
b. Affirmer offers the Work as-is and makes no representations or
warranties of any kind concerning the Work, express, implied,
statutory or otherwise, including without limitation warranties of
title, merchantability, fitness for a particular purpose, non
infringement, or the absence of latent or other defects, accuracy, or
the present or absence of errors, whether or not discoverable, all to
the greatest extent permissible under applicable law.
c. Affirmer disclaims responsibility for clearing rights of other persons
that may apply to the Work or any use thereof, including without
limitation any person's Copyright and Related Rights in the Work.
Further, Affirmer disclaims responsibility for obtaining any necessary
consents, permissions or other rights required for any use of the
Work.
d. Affirmer understands and acknowledges that Creative Commons is not a
party to this document and has no duty or obligation with respect to
this CC0 or use of the Work.
30 changes: 30 additions & 0 deletions assets/eip-5678/README.MD
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
<div align="center">

# ERC-721 Utilities Extension


[![License: CC0-1.0](https://img.shields.io/badge/License-CC0-yellow.svg)](https://creativecommons.org/publicdomain/zero/1.0/)

</div>

This project provides a reference implementation of the proposed `ERC-721 Utilities Extenstion` OPTIONAL extension.

## Install

In order to install the required dependencies you need to execute:
```shell
npm install
```

## Compile

In order to compile the solidity contracts you need to execute:
```shell
npx hardhat compile
```

## Tests

```shell
npx hardhat test
```
Loading

0 comments on commit 09ff15c

Please sign in to comment.