From 5a221777def70bf5b73d9e121508ab808b8ba644 Mon Sep 17 00:00:00 2001 From: Idalith <126833353+idalithb@users.noreply.github.com> Date: Fri, 15 Nov 2024 12:08:51 -0800 Subject: [PATCH] Cookbook-Enums (#798) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Enums * enums2 * updating edits * one minor edit * updating branch with code and context * applying feedback * Adding page to all lang * Update website/pages/en/cookbook/_meta.js --------- Co-authored-by: Benoît Rouleau --- website/pages/ar/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ website/pages/cs/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ website/pages/de/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ website/pages/en/cookbook/_meta.js | 1 + website/pages/en/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ website/pages/es/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ website/pages/fr/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ website/pages/ha/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ website/pages/hi/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ website/pages/it/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ website/pages/ja/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ website/pages/ko/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ website/pages/mr/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ website/pages/nl/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ website/pages/pl/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ website/pages/pt/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ website/pages/ro/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ website/pages/ru/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ website/pages/sv/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ website/pages/tr/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ website/pages/uk/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ website/pages/ur/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ website/pages/vi/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ website/pages/yo/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ website/pages/zh/cookbook/enums.mdx | 274 ++++++++++++++++++++++++++++ 25 files changed, 6577 insertions(+) create mode 100644 website/pages/ar/cookbook/enums.mdx create mode 100644 website/pages/cs/cookbook/enums.mdx create mode 100644 website/pages/de/cookbook/enums.mdx create mode 100644 website/pages/en/cookbook/enums.mdx create mode 100644 website/pages/es/cookbook/enums.mdx create mode 100644 website/pages/fr/cookbook/enums.mdx create mode 100644 website/pages/ha/cookbook/enums.mdx create mode 100644 website/pages/hi/cookbook/enums.mdx create mode 100644 website/pages/it/cookbook/enums.mdx create mode 100644 website/pages/ja/cookbook/enums.mdx create mode 100644 website/pages/ko/cookbook/enums.mdx create mode 100644 website/pages/mr/cookbook/enums.mdx create mode 100644 website/pages/nl/cookbook/enums.mdx create mode 100644 website/pages/pl/cookbook/enums.mdx create mode 100644 website/pages/pt/cookbook/enums.mdx create mode 100644 website/pages/ro/cookbook/enums.mdx create mode 100644 website/pages/ru/cookbook/enums.mdx create mode 100644 website/pages/sv/cookbook/enums.mdx create mode 100644 website/pages/tr/cookbook/enums.mdx create mode 100644 website/pages/uk/cookbook/enums.mdx create mode 100644 website/pages/ur/cookbook/enums.mdx create mode 100644 website/pages/vi/cookbook/enums.mdx create mode 100644 website/pages/yo/cookbook/enums.mdx create mode 100644 website/pages/zh/cookbook/enums.mdx diff --git a/website/pages/ar/cookbook/enums.mdx b/website/pages/ar/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/ar/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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). diff --git a/website/pages/cs/cookbook/enums.mdx b/website/pages/cs/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/cs/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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). diff --git a/website/pages/de/cookbook/enums.mdx b/website/pages/de/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/de/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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). diff --git a/website/pages/en/cookbook/_meta.js b/website/pages/en/cookbook/_meta.js index 4deedfffd880..f8b5035ddb55 100644 --- a/website/pages/en/cookbook/_meta.js +++ b/website/pages/en/cookbook/_meta.js @@ -11,4 +11,5 @@ export default { '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', 'transfer-to-the-graph': '', + enums: '', } diff --git a/website/pages/en/cookbook/enums.mdx b/website/pages/en/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/en/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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). diff --git a/website/pages/es/cookbook/enums.mdx b/website/pages/es/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/es/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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). diff --git a/website/pages/fr/cookbook/enums.mdx b/website/pages/fr/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/fr/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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). diff --git a/website/pages/ha/cookbook/enums.mdx b/website/pages/ha/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/ha/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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). diff --git a/website/pages/hi/cookbook/enums.mdx b/website/pages/hi/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/hi/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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). diff --git a/website/pages/it/cookbook/enums.mdx b/website/pages/it/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/it/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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). diff --git a/website/pages/ja/cookbook/enums.mdx b/website/pages/ja/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/ja/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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). diff --git a/website/pages/ko/cookbook/enums.mdx b/website/pages/ko/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/ko/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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). diff --git a/website/pages/mr/cookbook/enums.mdx b/website/pages/mr/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/mr/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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). diff --git a/website/pages/nl/cookbook/enums.mdx b/website/pages/nl/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/nl/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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). diff --git a/website/pages/pl/cookbook/enums.mdx b/website/pages/pl/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/pl/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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). diff --git a/website/pages/pt/cookbook/enums.mdx b/website/pages/pt/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/pt/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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). diff --git a/website/pages/ro/cookbook/enums.mdx b/website/pages/ro/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/ro/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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). diff --git a/website/pages/ru/cookbook/enums.mdx b/website/pages/ru/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/ru/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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). diff --git a/website/pages/sv/cookbook/enums.mdx b/website/pages/sv/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/sv/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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). diff --git a/website/pages/tr/cookbook/enums.mdx b/website/pages/tr/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/tr/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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). diff --git a/website/pages/uk/cookbook/enums.mdx b/website/pages/uk/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/uk/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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). diff --git a/website/pages/ur/cookbook/enums.mdx b/website/pages/ur/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/ur/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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). diff --git a/website/pages/vi/cookbook/enums.mdx b/website/pages/vi/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/vi/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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). diff --git a/website/pages/yo/cookbook/enums.mdx b/website/pages/yo/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/yo/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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). diff --git a/website/pages/zh/cookbook/enums.mdx b/website/pages/zh/cookbook/enums.mdx new file mode 100644 index 000000000000..a10970c1539f --- /dev/null +++ b/website/pages/zh/cookbook/enums.mdx @@ -0,0 +1,274 @@ +--- +title: 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: + +```graphql +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](/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. + +### Without Enums + +If you choose to define the type as a string instead of using an Enum, your code might look like this: + +```graphql +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: + +```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 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: + +```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).