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

Add EIP: Privileged Non-Fungible Tokens Tied To RWA #8862

Closed
wants to merge 1 commit into from
Closed

Add EIP: Privileged Non-Fungible Tokens Tied To RWA #8862

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.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
166 changes: 166 additions & 0 deletions EIPS/eip-7766.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,166 @@
---
eip: 7766
title: Privileged Non-Fungible Tokens Tied To RWA
description: An interface extending ERC-721 representing real world assets that users can exercise privileges with NFTs.
author: frank (@frankmint2024) <[email protected]>
discussions-to: https://ethereum-magicians.org/t/eip-7432-non-fungible-token-roles/15298
status: Draft
type: Standards Track
category: Interface
created: 2024-08-20
requires: 165, 721
---

## Abstract

This EIP defines an interface to carry a real world asset with some privileges that can be exercised by the holder of the corresponding NFT. The EIP standardizes the interface for non-fungible tokens representing real world assets with privileges to be exercised, such as products sold onchain which can be redeemed in the real world.

## Motivation

NFTs bound to real-world assets sometimes need to carry certain privileges that can be exercised by the holder. Users can initiate transactions onchain to specify the exercise of a certain privilege, thereby achieving real-world privileges that directly map the onchain privilege through subsequent operations. For example, if a certain product such as a pair of shoes is sold onchain in the representation of NFT, the NFT holder can exercise the privilege of exchanging physical shoes offchain, to achieve the purpose of interoperability between the blockchain and the real world.

Having a standard interface enables interoperability for services, clients, UI, and inter-contract functionalities on top of this use-case.

## 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.

This standard inherits the [ERC-721](./eip-721.md) NFT token standard for all transfer and approval logic. All transfer and approval functions are inherited from this token standard without changes. Additionally, this standard also inherits the ERC-721 Metadata standards for name, symbol, and metadata URI lookup.

Any compliant contract following this EIP **MUST** implement the following interface:

```
pragma solidity >=0.7.0 <0.9.0;

/// @title ERC-7766 Privileged Non-Fungible Tokens Tied To Real World Assets
/// @dev See https://eips.ethereum.org/EIPS/eip-7766
interface IERC7766 /* is IERC721, IERC165 */ {

/// @notice This event emitted when a specific privilege of a token is successfully exercised.
/// @param _operator the address who exercised the privilege.
/// @param _to the address to benefit from the privilege.
/// @param _tokenId the NFT tokenID.
/// @param _privilegeId the ID of the privileges.
event PrivilegeExercised(
address indexed _operator,
address indexed _to,
uint256 indexed _tokenId,
uint256 _privilegeId
);

/// @notice This function exercise a specific privilege of a token.
/// @dev Throws if `_privilegeId` is not a valid privilegeId.
/// @param _to the address to benefit from the privilege.
/// @param _tokenId the NFT tokenID.
/// @param _privilegeId the ID of the privileges.
/// @param _data extra data passed in for extra message or future extension.
function exercisePrivilege(
address _to,
uint256 _tokenId,
uint256 _privilegeId,
bytes calldata _data
) external;

/// @notice This function is to check whether a specific privilege of a token can be exercised.
/// @dev Throws if `_privilegeId` is not a valid privilegeId.
/// @param _to the address to benefit from the privilege.
/// @param _tokenId the NFT tokenID.
/// @param _privilegeId the ID of the privileges.
function isExercisable(
address _to,
uint256 _tokenId,
uint256 _privilegeId
) external view returns (bool _exercisable);

/// @notice This function is to check whether a specific privilege of a token has been exercised.
/// @dev Throws if `_privilegeId` is not a valid privilegeId.
/// @param _to the address to benefit from the privilege.
/// @param _tokenId the NFT tokenID.
/// @param _privilegeId the ID of the privileges.
function isExercised(
address _to,
uint256 _tokenId,
uint256 _privilegeId
) external view returns (bool _exercised);

/// @notice This function is to list all privilegeIds of a token.
/// @param _tokenId the NFT tokenID.
function getPrivilegeIds(
uint256 _tokenId
) external view returns (uint256[] memory privilegeIds);

}
```

The **metadata extension** is OPTIONAL for [EIP-7766](./eip-7766.md) smart contracts. This allows your smart contract to be interrogated for its details about the privileges which your NFTs carry.

```
pragma solidity >=0.7.0 <0.9.0;

/// @title ERC-7766 Privileged Non-Fungible Tokens Tied To Real World Assets, optional metadata extension
/// @dev See https://eips.ethereum.org/EIPS/eip-7766
interface IERC7766Metadata /* is IERC7766 */ {

/// @notice A distinct Uniform Resource Identifier (URI) for a given privilegeId.
/// @dev Throws if `_privilegeId` is not a valid privilegeId. URIs are defined in RFC
/// 3986. The URI may point to a JSON file that conforms to the "ERC-7766
/// Metadata JSON Schema".
function privilegeURI(uint256 _privilegeId) external view returns (string memory);

}
```

This is the “EIP-7766 Metadata JSON Schema” referenced above.

```
{
"title": "Privilege Metadata",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Identifies the specific privilege."
},
"description": {
"type": "string",
"description": "Describes the specific privilege."
},
"resource": {
"type": "string",
"description": "A URI pointing to a resource representing the specific privilege."
}
}
}
```

## Rationale

1. The function `exercisePrivilege` performs the exercise action to a specific privilege of a token. If succeeds, it is expected to emit a PrivilegeExercised event. With this event emitted onchain, we can determine that the user has confirmed the exercise of this privilege, so as to implement the privilege in the real world.

2. We choose to include an address `_to` for functions `exercisePrivilege`, `isExercisable` and `isExercised` so that a specific privilege of an NFT MAY be exercised for someone who will benefit from it other than the NFT holder nor the transaction initiator. And This EIP doesn't assume who has the power to perform this action, it's totally decided by the developers who are using this standard.

3. We choose to include an extra `_data` field to function `exercisePrivilege` for extra message or future extension. For example, developers can use `_data` to exercise a privilege that takes effect directly onchain such as direct distribution of cryptocurrency assets.

4. The boolean view functions of `isExercisable` and `isExercised` can be used to check whether a specific privilege of an NFT can be exercisable or has been exercised to the `_to` address.

5. The function `getPrivilegeIds` provides a way to manage the binding relationship between NFTs and privilegeIds.

6. EIP-7766Metadata provides specifications for obtaining metadata information of privileges. A contract that implements EIP-7766Metadata **SHALL** also implement EIP-7766.

## Backwards Compatibility

This standard is an extension of ERC-721. It is fully compatible with both of the commonly used optional extensions (ERC-721Metadata and ERC-721Enumerable) mentioned in the ERC-721 standard.

## Reference Implementation

The reference implementation of Privileged NFTs can be found at the repository named EIP-7766-example under the organization of Mint-Blockchain on github.

## Security Considerations

Compliant contracts should pay attention to the storage to the states of the privileges. The contract should properly handle the state transition of each privilege of each NFT, clearly showing that each privilege is exercisable or has been exercised.

Compliant contracts should also carefully define access control, particularly whether any EOA or contract account may or may not call `exercisePrivilege` function in any use case. Security audits and tests should be used to verify that the access control to the `exercisePrivilege` function behaves as expected.

## Copyright

Copyright and related rights waived via [CC0](../LICENSE.md).
Loading