Docs
⌘ K

6 minutos

Categorize Marketplaces de NFT com Enums

Use Enums para deixar o seu código mais limpo e menos vulnerável a erros. Veja um exemplo do uso deste em marketplaces de NFT.

O que são Enums?

Enums, ou tipos de enumeração, são um tipo de dados específico que permite definir um conjunto de valores específicos permitidos.

Exemplo de Enums no seu Schema

Se estiver a construir um subgraph para rastrear o histórico de posse de tokens em um mercado, cada token pode passar por posses diferentes, como OriginalOwner, SecondOwner, e ThirdOwner. Ao usar enums, é possível definir essas posses específicas, o que garante que só são nomeados valores predefinidos.

É possível definir enums no seu schema; assim definidos, a representação de string dos valores de enum podem ser usados para configurar um campo de enum numa entidade.

Com base no exemplo acima, uma definição de enum no seu schema pode ficar assim:

enum TokenStatus {  OriginalOwner  SecondOwner  ThirdOwner}

Ou seja, quando usar o tipo TokenStatus no seu schema, a expectativa é de que seja exatamente um dos valores predefinidos: OriginalOwner, SecondOwner, ou ThirdOwner, assim garantindo a consistência e validez.

Para saber mais sobre enums, veja Como Criar um Subgraph e a documentação da GraphQL⁠.

Vantagens de Usar Enums

  • Clareza: Enums dão nomes significativos a valores, facilitando a navegação de dados.
  • Validação: Enums aplicam definições rígidas de valor, assim evitando entradas inválidas de dados.
  • Manutenibilidade: Enums permitem mudar ou adicionar novas categorias de maneira concentrada.

Sem Enums

Se escolher definir o tipo como um string em vez de usar um Enum, seu código poderá ficar assim:

type Token @entity {  id: ID!  tokenId: BigInt!  owner: Bytes! # Proprietário do token  tokenStatus: String! # Campo de string para rastrear o estado do token  timestamp: BigInt!}

Neste schema, TokenStatus é um string simples sem valores permitidos específicos.

Por que isto é um problema?

  • Não há restrições sobre valores TokenStatus, então qualquer string pode ser nomeado por acidente. Assim, fica difícil garantir que só estados válidos — como OriginalOwner, SecondOwner, ou ThirdOwner — serão configurados.
  • É fácil fazer erros de digitação, como Orgnalowner em vez de OriginalOwner, o que faria os dados, e queries em potencial, não confiáveis.

Com Enums

Em vez de nomear strings livres, é possível definir um enum para TokenStatus com valores específicos: OriginalOwner, SecondOwner, ou ThirdOwner. Usar um enum garante o uso de valores permitidos, e mais nenhum.

Enums provém segurança de dados, minimizam os riscos de erros de digitação, e garantem resultados consistentes e confiáveis.

Como Definir Enums para Marketplaces de NFT

Nota: o guia a seguir usa o contrato inteligente de NFTs CryptoCoven.

Para definir enums para os vários mercados com apoio a troca de NFTs, use o seguinte no seu schema de subgraph:

# Enum para Marketplaces com que o contrato CryptoCoven interagiu(provavelmente Troca/Mint)enum Marketplace {  OpenSeaV1 # Representa o comércio de um NFT CryptoCoven no marketplace  OpenSeaV2 # Representa o comércio de um NFT CryptoCoven no marketplace OpenSeaV2  SeaPort # Representa o comércio de um NFT CryptoCoven no marketplace SeaPort  LooksRare # Representa o comércio de um NFT CryptoCoven no marketplace LookRare  # ...e outros marketplaces}

Como Usar Enums para Marketplaces de NFT

Quando definidos, os enums podem ser usados no seu subgraph para categorizar transações ou eventos.

Por exemplo: ao registrar vendas de NFT, é possível usar o enum para especificar o marketplace envolvido na ação.

Como Implementar uma Função para Marketplaces de NFT

Veja como implementar uma função para resgatar o nome de um marketplace do enum, como string:

export function getMarketplaceName(marketplace: Marketplace): string {  // Usando comandos if-else para mapear o valor do enum para um string  if (marketplace === Marketplace.OpenSeaV1) {    return 'OpenSeaV1' // Se o marketplace for OpenSea, retornar sua representação de string  } else if (marketplace === Marketplace.OpenSeaV2) {    return 'OpenSeaV2'  } else if (marketplace === Marketplace.SeaPort) {    return 'SeaPort' // Se o marketplace for SeaPort, retornar sua representação de string  } else if (marketplace === Marketplace.LooksRare) {    return 'LooksRare' // Se o marketplace for LooksRare, retornar sua representação de string    // ... e outros marketplaces  }}

Melhores Práticas para o Uso de Enums

  • Nomes Consistentes: Deixe o seu código mais legível; use nomes mais claros e descritivos para valores de enum.
  • Gestão Centralizada: Mantenha enums num único arquivo para ficar mais consistente. Assim, os enums ficam mais fáceis de atualizar, garantindo uma fonte única e verdadeira de dados.
  • Documentação: Adicione comentários a enums para esclarecer o seu propósito e uso.

Como Usar Enums em Queries

Enums em queries ajudam a melhorar a qualidade de dados e deixam os seus resultados mais fáceis de interpretar. Eles funcionam como filtros e elementos de resposta, assim garantindo a consistência e reduzindo erros em valores de marketplace.

Detalhes

  • Filtros com Enums: Enums fornecem filtros claros, permitindo a inclusão ou exclusão clara de marketplaces específicos.
  • Enums em Respostas: Enums garantem que só marketplaces reconhecidos sejam retornados, trazendo resultados consistentes e precisos.

Exemplos de Query

Query 1: Conta com Mais Interações de Marketplace em NFT

Este query faz o seguinte:

  • Encontra a conta com mais interações únicas com marketplaces de NFT, ótimo para analisar atividade entre marketplaces.
  • O campo de marketplaces usa o enum de marketplace, garantindo valores consistentes e validados na resposta.
{  accounts(first: 1, orderBy: uniqueMarketplacesCount, orderDirection: desc) {    id    sendCount    receiveCount    totalSpent    uniqueMarketplacesCount    marketplaces {      marketplace # Este campo retorna o valor de enum representando o marketplace    }  }}

Respostas

Esta resposta fornece detalhes de conta e uma lista de interações singulares de marketplace com valores de enum, para mais clareza:

{  "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: Marketplace mais ativo para transações do CryptoCoven

Este query faz o seguinte:

  • Identifica o marketplace com maior volume de transações do CryptoCoven.
  • Usa o enum de marketplace para garantir que só tipos válidos de marketplace apareçam na resposta, deixando os seus dados mais confiáveis e consistentes.
{  marketplaceInteractions(first: 1, orderBy: transactionCount, orderDirection: desc) {    marketplace    transactionCount  }}

Resultado 2

A resposta esperada inclui o marketplace e a contagem correspondente de transações, usando o enum para indicar o tipo de marketplace:

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

Query 3: Interações de Marketplace com Altos Números de Transação

Este query faz o seguinte:

  • Resgata os quatro marketplaces com maior número de transações acima de 100, excluindo marketplaces “desconhecidos”.
  • Usa enums como filtros para garantir que só tipos válidos de marketplace sejam incluídos, deixando a resposta mais precisa.
{  marketplaceInteractions(    first: 4    orderBy: transactionCount    orderDirection: desc    where: { transactionCount_gt: "100", marketplace_not: "Unknown" }  ) {    marketplace    transactionCount  }}

Resultado 3

O retorno esperado inclui os marketplaces que cumprem os critérios, cada um representado por um valor enum:

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

Outros Recursos

Para mais informações, veja o repositório⁠ deste guia.