Skip to content

Cookbook-Enums #798

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Nov 15, 2024
Merged

Cookbook-Enums #798

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
9f3935c
Enums
idalithb Oct 17, 2024
1ca3527
enums2
idalithb Oct 17, 2024
87f2bb8
updating edits
idalithb Oct 24, 2024
344904b
one minor edit
idalithb Oct 25, 2024
519559b
updating branch with code and context
idalithb Oct 29, 2024
05e08f4
applying feedback
idalithb Nov 13, 2024
ebc554a
Adding page to all lang
idalithb Nov 14, 2024
6552140
Merge branch 'main' into cookbook-enums
benface Nov 15, 2024
dedebe3
Update website/pages/en/cookbook/_meta.js
idalithb Nov 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions website/pages/en/cookbook/_meta.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,4 +10,5 @@ export default {
derivedfrom: 'Subgraph Best Practice 2: Manage Arrays with @derivedFrom',
'immutable-entities-bytes-as-ids': 'Subgraph Best Practice 3: Using Immutable Entities and Bytes as IDs',
'avoid-eth-calls': 'Subgraph Best Practice 4: Avoid eth_calls',
enums: 'Categorizing NFT Marketplaces Using Enums',
}
389 changes: 389 additions & 0 deletions website/pages/en/cookbook/enums.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,389 @@
---
title: Categorize NFT Marketplaces Using Enums
---

Learn how to effectively organize information from transactions and marketplace interactions using Enums.

> Note: This guide uses the CryptoCoven NFT smart contract.
## What are Enums?

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

### Enums Syntax

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

Here's what an enum definition might look like in your schema:

```graphql
enum TokenStatus {
OriginalOwner
SecondOwner
ThirdOwner
}
```

This means that when you use the type `TokenStatus` in your schema, you expect it to be exactly one of `OriginalOwner`, `SecondOwner`, or `ThirdOwner`.

To learn more about enums, check out [Creating a Subgraph](/developing/creating-a-subgraph/#enums) and [GraphQL documentation](https://graphql.org/learn/schema/#enumeration-types).

## Benefits of Using Enums

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

## Defining Enums

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

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

## Using Enums

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

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

### Implementing a Function

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

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

## Best Practices for Using Enums

- **Consistent Naming:** Use clear, descriptive names for enum values to improve readability.
- **Centralized Management:** Keep enums in a single file for easier updates and management.
- **Documentation:** Add comments to enum definitions for better context.

## Sample Queries

### Query 1: Account With The Highest NFT Marketplace Interactions

The goal of this query is to:

- Find the account that has interacted with the most unique marketplaces
- Obtain detailed information about the marketplace interactions
- Determine total spending amount and NFT transactions

This query can be valuable for assessing an account's activity and involvement in the NFT marketplace ecosystem.

```gql
{
accounts(first: 1, orderBy: uniqueMarketplacesCount, orderDirection: desc) {
id
sendCount
receiveCount
totalSpent
uniqueMarketplacesCount
marketplaces {
marketplace
}
sent(first: 5) {
...id
tokenId
value
txHash
}
received(first: 5) {
id
tokenId
value
txHash
}
}
}
```

### Return

```gql
{
"data": {
"accounts": [
{
"id": "0xb3abc96cb9a61576c03c955d75b703a890a14aa0",
"sendCount": "44",
"receiveCount": "42",
"totalSpent": "917500000000000000",
"uniqueMarketplacesCount": "7",
"marketplaces": [
{
"marketplace": "OpenSeaV1"
},
{
"marketplace": "OpenSeaV2"
},
{
"marketplace": "GenieSwap"
},
{
"marketplace": "CryptoCoven"
},
{
"marketplace": "Unknown"
},
{
"marketplace": "LooksRare"
},
{
"marketplace": "NFTX"
}
],
"sent": [
{
"id": "0x0008e69a698db8da6c4118ab44c140f0e19d553359a3ee2e5c294f55d94fc235-0xc4",
"tokenId": "7702",
"value": "1800000000000000000",
"txHash": "0x0008e69a698db8da6c4118ab44c140f0e19d553359a3ee2e5c294f55d94fc235"
},
{
"id": "0x2d0bcb70a84672c6ae96940721e8b421c223d5e48999d1d5ae2e2dbb9e24f812-0xab",
"tokenId": "3848",
"value": "550000000000000000",
"txHash": "0x2d0bcb70a84672c6ae96940721e8b421c223d5e48999d1d5ae2e2dbb9e24f812"
},
{
"id": "0x16b9f7234e254ce19804fb0bc3c8a66a0531a9c4a2655db808eec9960c057e81-0x207",
"tokenId": "9670",
"value": "1500000000000000000",
"txHash": "0x16b9f7234e254ce19804fb0bc3c8a66a0531a9c4a2655db808eec9960c057e81"
},
{
"id": "0x1a091ab78f78c96513f53d2fab670da37f9d8815f9a5807a2117ac1221210a6b-0x142",
"tokenId": "8935",
"value": "3273900000000000000",
"txHash": "0x1a091ab78f78c96513f53d2fab670da37f9d8815f9a5807a2117ac1221210a6b"
},
{
"id": "0x22e5331383c441c6083230f22795ae467024bff001055ede835d11ebbb8a0d30-0x134",
"tokenId": "8555",
"value": "2000000000000000000",
"txHash": "0x22e5331383c441c6083230f22795ae467024bff001055ede835d11ebbb8a0d30"
}
],
"received": [
{
"id": "0x018613dc9de37f2af7c7be354aa05820c841ce043d50631f716729d4dc4525bc-0x3e",
"tokenId": "8555",
"value": "98000000000000000",
"txHash": "0x018613dc9de37f2af7c7be354aa05820c841ce043d50631f716729d4dc4525bc"
},
{
"id": "0x6404355c5fd3514dac25cb72e8f041eb39bf325f8c895369b0c8b6f1e42d00cb-0x7",
"tokenId": "9670",
"value": "95000000000000000",
"txHash": "0x6404355c5fd3514dac25cb72e8f041eb39bf325f8c895369b0c8b6f1e42d00cb"
},
{
"id": "0x787fa58c36e234ab78aa551faedb61d0e9f8433d068a1d6575ff45bbd97af74e-0x3c",
"tokenId": "8935",
"value": "90000000000000000",
"txHash": "0x787fa58c36e234ab78aa551faedb61d0e9f8433d068a1d6575ff45bbd97af74e"
},
{
"id": "0xd618817c15aa703a97b98eabea17e4b37a4d7e509665eafd18814bc3d5675c1b-0x1c4",
"tokenId": "7702",
"value": "95000000000000000",
"txHash": "0xd618817c15aa703a97b98eabea17e4b37a4d7e509665eafd18814bc3d5675c1b"
},
{
"id": "0xffe41bb24b8882a9883f5d5aae710f606f854772af1dd2171b7729d8c953c358-0x115",
"tokenId": "3848",
"value": "0",
"txHash": "0xffe41bb24b8882a9883f5d5aae710f606f854772af1dd2171b7729d8c953c358"
}
]
}
]
}
}
```

### Query 2: Accounts That Engaged with the Most Unique Marketplaces

This query retrieves the top 5 accounts that have interacted with the most unique marketplaces. The marketplace field retrieves a list of interactions for each account.

```graphql
{
accounts(first: 5, orderBy: uniqueMarketplacesCount, orderDirection: desc) {
id
uniqueMarketplacesCount
marketplaces {
marketplace
}
}
}
```

### Return

```gql
{
"data": {
"accounts": [
{
"id": "0xb3abc96cb9a61576c03c955d75b703a890a14aa0",
"uniqueMarketplacesCount": "7",
"marketplaces": [
{
"marketplace": "OpenSeaV1"
},
{
"marketplace": "OpenSeaV2"
},
{
"marketplace": "GenieSwap"
},
{
"marketplace": "CryptoCoven"
},
{
"marketplace": "Unknown"
},
{
"marketplace": "LooksRare"
},
{
"marketplace": "NFTX"
}
]
},
{
"id": "0x77bb41b3a80982e19daae2cfe94403afcc613489",
"uniqueMarketplacesCount": "7",
"marketplaces": [
{
"marketplace": "OpenSeaV1"
},
{
"marketplace": "OpenSeaV2"
},
{
"marketplace": "GenieSwap"
},
{
"marketplace": "CryptoCoven"
},
{
"marketplace": "Unknown"
},
{
"marketplace": "LooksRare"
},
{
"marketplace": "OxProtocolV2"
}
]
},
{
"id": "0x66349e79e99ae4d661a5ebb5474759508d392da4",
"uniqueMarketplacesCount": "7",
"marketplaces": [
{
"marketplace": "OpenSeaV1"
},
{
"marketplace": "OpenSeaV2"
},
{
"marketplace": "GenieSwap"
},
{
"marketplace": "CryptoCoven"
},
{
"marketplace": "Unknown"
},
{
"marketplace": "SeaPort"
},
{
"marketplace": "LooksRare"
}
]
},
{
"id": "0x2d0a51e142bf3f156a978175c05ec74a25bb4e4f",
"uniqueMarketplacesCount": "7",
"marketplaces": [
{
"marketplace": "OpenSeaV1"
},
{
"marketplace": "OpenSeaV2"
},
{
"marketplace": "GenieSwap"
},
{
"marketplace": "CryptoCoven"
},
{
"marketplace": "Unknown"
},
{
"marketplace": "SeaPort"
},
{
"marketplace": "LooksRare"
}
]
},
{
"id": "0xfb29cc23d5d7b705a0ab93d7a7cad6a01e52be94",
"uniqueMarketplacesCount": "6",
"marketplaces": [
{
"marketplace": "OpenSeaV1"
},
{
"marketplace": "OpenSeaV2"
},
{
"marketplace": "CryptoCoven"
},
{
"marketplace": "Unknown"
},
{
"marketplace": "LooksRare"
},
{
"marketplace": "NFTX"
}
]
}
]
}
}
```

## Additional Resources

For additional information, check out this guide's [repo](https://github.com/chidubemokeke/Subgraph-Tutorial-Enums).
Loading