Roles Definition

This page describes how NFT Creators can define how Borrowers use their rented NFTs.

What are Roles?

Each NFT has a specific set of utilities. These utilities can be access to a game, community benefits, or even smart contract access rights. To enable a more granular approach to NFT utility, ERC-7432 introduced Roles.

Roles comprise a set of access rights defined by the NFT Creator, enabling the NFT Owner to delegate its utility to another user. Roles can also include inputs the user is required to provide. The most common role input is profit share, which allows the NFT Owner to share token earnings with the user who received the role.

Most NFTs will contain a single role that, when granted, allows the borrower to use all benefits of the NFT. Multiple roles are helpful for more complex use cases.

Examples

Here are some examples of use cases for roles:

Simple Game

Assume an NFT Project created a token-gated game that only NFT holders can access. To enable NFT Rentals, the Project's Creator defined the following role:

• Role Name: Player

• Role Description: Allow a user to play the token-gated game.

• Role Inputs:

  • Owner Profit Share.

  • Borrower Profit Share.

With this role definition, any NFT holder can "rent" their NFT by grating roles. The Orium Marketplace does nothing more than grant roles on behalf of the Owner, given that the Borrower pays an upfront fee.

Digital Real Estate

Assume an NFT Project created a digital real estate NFT. Owners of this NFT can manage the properties and access them on a game. To enable NFT Rentals, the Project's Creator defined the following roles:

Role 1

• Role Name: Tenant

• Role Description: Allow a user to access the digital property.

• Role Inputs: None.

Role 2

• Role Name: Farmer

• Role Description: Allow a user to farm tokens on the digital property.

• Role Inputs:

  • Owner Profit Share.

  • Borrower Profit Share.

This case is more complex because it empowers the Owner to grant two roles simultaneously, which can be assigned to the same user (or not). It's also important to note that since the Farmer role allows the user to earn tokens with the NFT, the Owner is required to set a profit share when granting the role, which is not true for the Tenant.

---

Creating a Role Definition with JSON

The Role Definition JSON is a simple data format that enables NFT Creators to specify all the roles associated with an NFT and their respective inputs.

To learn more about the JSON data type, read this article.

Here is an example of a role definition according to the Simple Game

{
    "roles": [
        {
            "id": "0x3d926b0dd5f4880fb18c9a49c890c7d76c2a97e0d4b4c20f1bb3fe6e5f89f0f4",
            "name": "Player",
            "description": "Allow a user to play the token-gated game.",
            "isUniqueRole": true,
            "inputs": [
                {
                    "name": "Owner Profit Share",
                    "type": "uint256"
                    "default": "10000"
                },
                {
                    "name": "Borrower Profit Share",
                    "type": "uint256"
                    "default": "0"
                }
            ]
        }
    ]
}

As seen above, all the role information defined at Simple Game is available in the role definition, with the addition of id and isUniqueRole. id is a hexadecimal representation of the role, usually calculated as the keccak256 of the role's name, which in this case is keccak256("Player"), and IsUniqueRole refers to whether the role can be assigned to multiple users simultaneously. Read Unique and Non-Unique Roles to learn more.

The role definition specification is described more deeply in the ERC-7432 Metadata section.

We can also represent the role definition of theDigital Real Estate example as the following:

{
    "roles": [
        {
            "id": "0x52f071952c73e31c6894ce0a6f5f13ac2d52bdb517a0f2686ad01ca7a32315bb",
            "name": "Tenant",
            "description": "Allow a user to access the digital property.",
            "isUniqueRole": false,
            "inputs": []
        },
        {
            "id": "0x4473bc4cca227a6bb6678e826347a766442caaa5b58eb00db63d083b4a882e69",
            "name": "Farmer",
            "description": "Allow a user to farm tokens on the digital property.",
            "isUniqueRole": true,
            "inputs": [
                {
                    "name": "Owner Profit Share",
                    "type": "uint256"
                    "default": "10000"
                },
                {
                    "name": "Borrower Profit Share",
                    "type": "uint256"
                    "default": "0"
                }
            ]
        }
    ]
}

In this example, we have two roles: One unique and another non-unique. The Tenant role is not unique because a property can have more than one Tenant, but Farmer is unique because only one user can earn tokens in the property.

---

Conclusion

As mentioned above, most use cases only require a single role with one or two parameters. However, the ERC-7432 metadata was designed to be generic and cater to complex use cases.

If you need help to create the role definition of your NFT, don't hesitate to get in touch via Contact