Como Lançar um Subgraph no Serviço Hospedado

Reading time: 9 min

Esta página explica como lançar um subgraph no Serviço Hospedado. Para lançar um subgraph, instale a Graph CLI. Se ainda não criou um subgraph, veja a secção Como Criar um Subgraph.

Antes de usar o Serviço Hospedado, crie uma conta nele. Para este fim, faça uma conta no Github; se não tiver, crie uma primeiro, e depois, navegue ao Serviço Hospedado, clique no botão 'Sign up with Github' (cadastrar com Github) e complete o fluxo de autorização do Github.

Após criar uma conta, navegue até o seu painel de controle. Copie o token de acesso (access token) exibido no painel e execute graph auth --product hosted-service <ACCESS_TOKEN> para armazenar o token de acesso no seu computador. Isto só precisa ser feito uma vez, a não ser que tenha que gerar o token de acesso novamente.

Antes de lançar o subgraph, ele tem que ser criado no The Graph Explorer. Vá até o painel de controle, clique no botão 'Add Subgraph' (Adicionar Subgraph) e preencha os campos abaixo com as informações adequadas:

Image (Imagem) — Selecione uma imagem para ser usada como foto de prévia e thumbnail (miniatura) para o subgraph.

Subgraph Name (Nome do Subgraph) — Defina o nome em account-name/subgraph-name a ser usado para lançamentos e pontos finais do GraphQL, além de nomear a conta sob a qual será criada o subgraph. Este campo não pode ser alterado depois de pronto.

Account (Conta) — A conta sob a qual foi criado o subgraph. Pode ser uma conta de indivíduo ou organização. Depois disto, não é possível movimentar subgraphs entre contas.

Subtitle (Subtítulo) — Texto que aparecerá em cards de subgraphs.

Description (Descrição) — Descrição do subgraph, visível na página de detalhes do mesmo.

GitHub URL — Atalho ao repositório do subgraph no GitHub.

Hide (Esconder) — Opção alternável que oculta o subgraph no Graph Explorer.

Após salvar o novo subgraph, aparecerão instruções sobre como instalar o Graph CLI; como gerar estruturas para um novo subgraph; e como lançar o seu subgraph. Os primeiros dois passos foram abordados na seção Como Definir um Subgraph.

O lançamento do seu subgraph enviará os arquivos do subgraph construído com yarn build ao IPFS, e mandará que o Graph Explorer comece a indexar o seu subgraph com estes arquivos.

Lance o subgraph com o comando yarn deploy

Após lançar o subgraph, o Graph Explorer mostrará o estado da sincronização deste. Dependendo da quantia de dados e eventos que devem ser extraídos de blocos históricos, a começar do bloco-génese, a sincronização pode levar de alguns minutos a várias horas.

O estado do subgraph é mostrado como Synced (sincronizado) quando o Graph Node extrai todos os dados de blocos históricos. O Graph Node continuará a inspecionar blocos para o seu subgraph enquanto estes blocos são minerados.

Ao fazer mudanças à definição do seu subgraph — por exemplo, para resolver um problema nos mapeamentos de entidade — execute o comando yarn deploy novamente para lançar a versão atualizada do seu subgraph. Para atualizar um subgraph, o Graph Node sempre deve reindexá-lo por inteiro, novamente começando pelo bloco-gênese.

Se seu subgraph já lançado ainda estiver no estado Syncing (Sincronizando), ele será imediatamente substituído com a versão recém-lançada. Se o mesmo subgraph já estiver totalmente sincronizado, o Graph Node marcará a versão recém-lançada como a Pending Version (Versão Pendente), sincronizá-la no fundo, e substituir a versão atual com a nova apenas quando terminar a sincronização da versão nova. Isto garante que você tenha um subgraph para trabalhos enquanto a nova versão sincroniza.

Em alguns casos, irá querer lançar o mesmo subgraph a várias redes sem duplicar o seu código completo. O grande desafio nisto é que os endereços de contrato nestas redes são diferentes.

Tanto o graph build (desde a v0.29.0) quanto o graph deploy (desde a v0.32.0) aceitam duas novas opções:

Options:

      ...
      --network <name>          Configuração de rede para usar no arquivo de config de redes
      --network-file <path>     Local do arquivo de config de redes (padrão: "./networks.json")

A opção --network serve para especificar uma configuração de rede a partir de um arquivo json (o comum é networks.json), para facilmente atualizar o seu subgraph durante a programação.

Nota: O comando init agora irá gerar um networks.json automaticamente, com base na informação fornecida. Daí, será possível atualizar redes existentes ou adicionar redes novas.

Caso não tenha um arquivo networks.json, precisará criar o mesmo manualmente, com a seguinte estrutura:

{
    "network1": { // nome da rede
        "dataSource1": { // nome do dataSource
            "address": "0xabc...", // endereço do contrato (opcional)
            "startBlock": 123456 // bloco inicial (opcional)
        },
        "dataSource2": {
            "address": "0x123...",
            "startBlock": 123444
        }
    },
    "network2": {
        "dataSource1": {
            "address": "0x987...",
            "startBlock": 123
        },
        "dataSource2": {
            "address": "0xxyz..",
            "startBlock": 456
        }
    },
    ...
}

Nota: Não precisa especificar quaisquer dos templates (se tiver) no arquivo de configuração, apenas as dataSources. Se houver alguns templates declarados no arquivo subgraph.yaml, sua rede será automaticamente atualizada à especificada na opção --network.

Agora, vamos supor que quer lançar o seu subgraph às redes mainnet e sepolia, e este é o seu subgraph.yaml:

# ...
dataSources:
  - kind: ethereum/contract
    name: Gravity
    network: mainnet
    source:
      address: '0x123...'
      abi: Gravity
    mapping:
      kind: ethereum/events

O seu arquivo de config de redes deve ficar assim:

{
  "mainnet": {
    "Gravity": {
      "address": "0x123..."
    }
  },
  "sepolia": {
    "Gravity": {
      "address": "0xabc..."
    }
  }
}

Agora podemos executar um dos seguintes comandos:

# Usar o arquivo networks.json padrão
yarn build --network sepolia

# Usar arquivo com nome personalizado
yarn build --network sepolia --network-file local/do/config

O comando build atualizará o seu subgraph.yaml com a configuração sepolia e depois recompilará o subgraph. O seu arquivo subgraph.yaml agora deve parecer com isto:

# ...
dataSources:
  - kind: ethereum/contract
    name: Gravity
    network: sepolia
    source:
      address: '0xabc...'
      abi: Gravity
    mapping:
      kind: ethereum/events

Agora está tudo pronto para executar o yarn deploy.

Nota: Como já levantado, desde o graph-cli 0.32.0, dá para executar diretamente o yarn deploy com a opção --network:

# Usar o arquivo networks.json padrão
yarn deploy --network sepolia

# Usar arquivo com nome personalizado
yarn deploy --network sepolia --network-file local/do/config

Uma solução para versões mais antigas do graph-cli, que permite a parametrização de aspetos como endereços de contratos, é gerar partes dele com um sistema de templating como o Mustache ou o Handlebars.

Por exemplo, vamos supor que um subgraph deve ser lançado à mainnet e à Sepolia, através de diferentes endereços de contratos. Então, seria possível definir dois arquivos de config ao fornecer os endereços para cada rede:

{
  "network": "mainnet",
  "address": "0x123..."
}

e

{
  "network": "sepolia",
  "address": "0xabc..."
}

Além disso, substituiria o nome da rede e os endereços no manifest com variáveis temporários {{network}} and {{address}} e renomearia o manifest a, por exemplo, subgraph.template.yaml:

# ...
dataSources:
  - kind: ethereum/contract
    name: Gravity
    network: mainnet
    network: {{network}}
    source:
      address: '0x2E645469f354BB4F5c8a05B3b30A929361cf77eC'
      address: '{{address}}'
      abi: Gravity
    mapping:
      kind: ethereum/events

Para poder gerar um manifest para uma rede, pode adicionar mais dois comandos ao package.json com uma dependência no mustache:

{
  ...
  "scripts": {
    ...
    "prepare:mainnet": "mustache config/mainnet.json subgraph.template.yaml > subgraph.yaml",
    "prepare:sepolia": "mustache config/sepolia.json subgraph.template.yaml > subgraph.yaml"
  },
  "devDependencies": {
    ...
    "mustache": "^3.1.0"
  }
}

Para lançar este subgraph à mainnet ou à Sepolia, apenas um dos seguintes comandos precisaria ser executado:

# Mainnet:
yarn prepare:mainnet && yarn deploy

# Sepolia:
yarn prepare:sepolia && yarn deploy

Veja um exemplo funcional disto aqui.

Nota: Este método também pode ser aplicado a situações mais complexas, onde é necessário substituir mais que endereços de contratos e nomes de redes, ou gerar mapeamentos e ABIs de templates também.

Se um subgraph for sincronizado com sucesso, isto indica que ele continuará a rodar bem para sempre. Porém, novos gatilhos na rede podem revelar uma condição de erro não testada, ou ele pode começar a se atrasar por problemas de desempenho ou com os operadores de nodes.

O Graph Node expõe um endpoint do GraphQL que pode ser consultado em query, para conferir o status do seu subgraph. No Serviço Hospedado, ele está disponível no https://api.thegraph.com/index-node/graphql; em um node local, no port 8030/graphql. Encontre o schema completo para este endpoint aqui. Veja um exemplo de query sobre o estado da versão atual de um subgraph:

{
  indexingStatusForCurrentVersion(subgraphName: "org/subgraph") {
    synced
    health
    fatalError {
      message
      block {
        number
        hash
      }
      handler
    }
    chains {
      chainHeadBlock {
        number
      }
      latestBlock {
        number
      }
    }
  }
}

Isto rendará o chainHeadBlock, que pode ser comparado com o latestBlock no seu subgraph para conferir se está atrasado. synced informa se o subgraph conseguiu alcançar a chain. health pode atualmente resgatar os valores de healthy, se não houver erros; ou failed, se algum erro tiver impedido o progresso do subgraph. Neste caso, verifique o campo fatalError para mais detalhes.

O Serviço Hospedado é um Indexador gratuito de Graph Nodes. Os programadores podem lançar subgraphs e indexar uma gama de redes, que serão indexadas e disponibilizadas para consulta via graphQL.

Para melhorar o desempenho do serviço para subgraphs ativos, o Serviço Hospedado arquivará subgraphs inativos.

Um subgraph é definido como "inativo" se tiver sido lançado ao Serviço Hospedado há mais de 45 dias e tiver recebido 0 queries nos últimos 45 dias.

Os desenvolvedores serão avisados por email se um dos seus subgraphs for marcado como inativo, e será removido após 7 dias. Caso queiram "ativar" o seu subgraph, podem fazê-lo com um query no playground graphQL, no Serviço Hospedado do seu subgraph. Os programadores sempre podem relançar um subgraph arquivado caso o necessitem novamente.

Uma versão de subgraph no Studio é arquivada se, e apenas se, atender aos seguintes critérios:

• A versão não foi publicada na rede (ou tem a publicação pendente)
• A versão foi criada há 45 dias ou mais
• O subgraph não foi consultado em 30 dias

Além disto, quando uma nova versão é editada, se o subgraph ainda não foi publicado, então a versão N-2 do subgraph é arquivada.

Todos os subgraphs afetados por esta política têm a opção de trazer de volta a versão em questão.