Docs
⌘ K

6 minutes

Categorize NFT Marketplaces Using Enums

Use Enums to make your code cleaner and less error-prone. Here’s a full example of using Enums on NFT marketplaces.

What are Enums?

Enums, or enumeration types, are a specific data type that allows you to define a set of specific, allowed values.

Example of Enums in Your Schema

If you’re building a Subgraph to track the ownership history of tokens on a marketplace, each token might go through different ownerships, such as OriginalOwner, SecondOwner, and ThirdOwner. By using enums, you can define these specific ownerships, ensuring only predefined values are assigned.

You can define enums in your schema, and once defined, you can use the string representation of the enum values to set an enum field on an entity.

Here’s what an enum definition might look like in your schema, based on the example above:

enum TokenStatus {  OriginalOwner  SecondOwner  ThirdOwner}

This means that when you use the TokenStatus type in your schema, you expect it to be exactly one of predefined values: OriginalOwner, SecondOwner, or ThirdOwner, ensuring consistency and validity.

To learn more about enums, check out Creating a Subgraph and GraphQL documentation⁠.

Benefits of Using Enums

  • Clarity: Enums provide meaningful names for values, making data easier to understand.
  • Validation: Enums enforce strict value definitions, preventing invalid data entries.
  • Maintainability: When you need to change or add new categories, enums allow you to do this in a focused manner.

Without Enums

If you choose to define the type as a string instead of using an Enum, your code might look like this:

type Token @entity {  id: ID!  tokenId: BigInt!  owner: Bytes! # Owner of the token  tokenStatus: String! # String field to track token status  timestamp: BigInt!}

In this schema, TokenStatus is a simple string with no specific, allowed values.

Why is this a problem?

  • There’s no restriction of TokenStatus values, so any string can be accidentally assigned. This makes it hard to ensure that only valid statuses like OriginalOwner, SecondOwner, or ThirdOwner are set.
  • It’s easy to make typos such as Orgnalowner instead of OriginalOwner, making the data and potential queries unreliable.

With Enums

Instead of assigning free-form strings, you can define an enum for TokenStatus with specific values: OriginalOwner, SecondOwner, or ThirdOwner. Using an enum ensures only allowed values are used.

Enums provide type safety, minimize typo risks, and ensure consistent and reliable results.

Defining Enums for NFT Marketplaces

Note: The following guide uses the CryptoCoven NFT smart contract.

To define enums for the various marketplaces where NFTs are traded, use the following in your Subgraph schema:

# Enum for Marketplaces that the CryptoCoven contract interacted with(likely a Trade/Mint)enum Marketplace {  OpenSeaV1 # Represents when a CryptoCoven NFT is traded on the marketplace  OpenSeaV2 # Represents when a CryptoCoven NFT is traded on the OpenSeaV2 marketplace  SeaPort # Represents when a CryptoCoven NFT is traded on the SeaPort marketplace  LooksRare # Represents when a CryptoCoven NFT is traded on the LookRare marketplace  # ...and other marketplaces}

Using Enums for NFT Marketplaces

Once defined, enums can be used throughout your Subgraph to categorize transactions or events.

For example, when logging NFT sales, you can specify the marketplace involved in the trade using the enum.

Implementing a Function for NFT Marketplaces

Here’s how you can implement a function to retrieve the marketplace name from the enum as a string:

export function getMarketplaceName(marketplace: Marketplace): string {  // Using if-else statements to map the enum value to a string  if (marketplace === Marketplace.OpenSeaV1) {    return 'OpenSeaV1' // If the marketplace is OpenSea, return its string representation  } else if (marketplace === Marketplace.OpenSeaV2) {    return 'OpenSeaV2'  } else if (marketplace === Marketplace.SeaPort) {    return 'SeaPort' // If the marketplace is SeaPort, return its string representation  } else if (marketplace === Marketplace.LooksRare) {    return 'LooksRare' // If the marketplace is LooksRare, return its string representation    // ... and other market places  }}

Best Practices for Using Enums

  • Consistent Naming: Use clear, descriptive names for enum values to improve readability.
  • Centralized Management: Keep enums in a single file for consistency. This makes enums easier to update and ensures they are the single source of truth.
  • Documentation: Add comments to enum to clarify their purpose and usage.

Using Enums in Queries

Enums in queries help you improve data quality and make your results easier to interpret. They function as filters and response elements, ensuring consistency and reducing errors in marketplace values.

Specifics

  • Filtering with Enums: Enums provide clear filters, allowing you to confidently include or exclude specific marketplaces.
  • Enums in Responses: Enums guarantee that only recognized marketplace names are returned, making the results standardized and accurate.

Sample Queries

Query 1: Account With The Highest NFT Marketplace Interactions

This query does the following:

  • It finds the account with the highest unique NFT marketplace interactions, which is great for analyzing cross-marketplace activity.
  • The marketplaces field uses the marketplace enum, ensuring consistent and validated marketplace values in the response.
{  accounts(first: 1, orderBy: uniqueMarketplacesCount, orderDirection: desc) {    id    sendCount    receiveCount    totalSpent    uniqueMarketplacesCount    marketplaces {      marketplace # This field returns the enum value representing the marketplace    }  }}

Returns

This response provides account details and a list of unique marketplace interactions with enum values for standardized clarity:

{  "data": {    "accounts": [      {        "id": "0xb3abc96cb9a61576c03c955d75b703a890a14aa0",        "sendCount": "44",        "receiveCount": "44",        "totalSpent": "1197500000000000000",        "uniqueMarketplacesCount": "7",        "marketplaces": [          {            "marketplace": "OpenSeaV1"          },          {            "marketplace": "OpenSeaV2"          },          {            "marketplace": "GenieSwap"          },          {            "marketplace": "CryptoCoven"          },          {            "marketplace": "Unknown"          },          {            "marketplace": "LooksRare"          },          {            "marketplace": "NFTX"          }        ]      }    ]  }}

Query 2: Most Active Marketplace for CryptoCoven transactions

This query does the following:

  • It identifies the marketplace with the highest volume of CryptoCoven transactions.
  • It uses the marketplace enum to ensure that only valid marketplace types appear in the response, adding reliability and consistency to your data.
{  marketplaceInteractions(first: 1, orderBy: transactionCount, orderDirection: desc) {    marketplace    transactionCount  }}

Result 2

The expected response includes the marketplace and the corresponding transaction count, using the enum to indicate the marketplace type:

{  "data": {    "marketplaceInteractions": [      {        "marketplace": "Unknown",        "transactionCount": "222"      }    ]  }}

Query 3: Marketplace Interactions with High Transaction Counts

This query does the following:

  • It retrieves the top four marketplaces with over 100 transactions, excluding “Unknown” marketplaces.
  • It uses enums as filters to ensure that only valid marketplace types are included, increasing accuracy.
{  marketplaceInteractions(    first: 4    orderBy: transactionCount    orderDirection: desc    where: { transactionCount_gt: "100", marketplace_not: "Unknown" }  ) {    marketplace    transactionCount  }}

Result 3

Expected output includes the marketplaces that meet the criteria, each represented by an enum value:

{  "data": {    "marketplaceInteractions": [      {        "marketplace": "NFTX",        "transactionCount": "201"      },      {        "marketplace": "OpenSeaV1",        "transactionCount": "148"      },      {        "marketplace": "CryptoCoven",        "transactionCount": "117"      },      {        "marketplace": "OpenSeaV1",        "transactionCount": "111"      }    ]  }}

Additional Resources

For additional information, check out this guide’s repo⁠.