Cookbook-Enums

website/next-env.d.ts

@@ -2,4 +2,4 @@
 /// <reference types="next/image-types/global" />
 
 // NOTE: This file should not be edited
-// see https://nextjs.org/docs/basic-features/typescript for more information.
+// see https://nextjs.org/docs/pages/building-your-application/configuring/typescript for more information.

website/pages/en/cookbook/_meta.js

@@ -10,4 +10,5 @@ export default {
   derivedfrom: 'Subgraph Best Practice 2: Manage Arrays with @derivedFrom',
   'immutable-entities-bytes-as-ids': 'Subgraph Best Practice 3: Using Immutable Entities and Bytes as IDs',
   'avoid-eth-calls': 'Subgraph Best Practice 4: Avoid eth_calls',
+  enums: 'Categorizing NFT Marketplaces Using Enums',
 }

website/pages/en/cookbook/enums.mdx

@@ -0,0 +1,245 @@
+---
+title: Categorize NFT Marketplaces Using Enums
+---
+
+Learn how to effectively organize information from transactions and marketplace interactions using Enums.
+
+> Note: This guide uses the CryptoCoven NFT smart contract.
+
+## What are Enums?
+
+Enums, or enumeration types, are a specific data type that allows you to define a set of allowed values.
+
+### Enums Syntax
+
+You can define enums in your schema, and once defined, you can use the string representation of the enum value to set an enum field on an entity.
+
+Here's what an enum definition might look like in your schema:
+
+```graphql
+enum TokenStatus {
+  OriginalOwner
+  SecondOwner
+  ThirdOwner
+}
+```
+
+This means that when you use the type `TokenStatus` in your schema, you expect it to be exactly one of `OriginalOwner`, `SecondOwner`, or `ThirdOwner`.
+
+To learn more about enums, check out [Creating a Subgraph](/developing/creating-a-subgraph/#enums) and [GraphQL documentation](https://graphql.org/learn/schema/#enumeration-types).
+
+## 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.
+
+## Defining Enums
+
+To define enums for the various marketplaces where NFTs are traded, use the following in your subgraph schema:
+
+```gql
+# 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
+
+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
+
+Here's how you can implement a function to retrieve the marketplace name from the enum as a string:
+
+```ts
+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.
+
+```gql
+{
+  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:
+
+```gql
+{
+  "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.
+
+```gql
+{
+  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:
+
+```gql
+{
+  "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.
+
+```gql
+{
+  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:
+
+```gql
+{
+  "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](https://github.com/chidubemokeke/Subgraph-Tutorial-Enums).