Construção de Subgraphs na NEAR

Reading time: 9 min

Este guia é uma introdução à construção de subgraphs a indexar contratos inteligentes na blockchain NEAR.

O NEAR é uma plataforma de contratos inteligentes para a construção de aplicativos descentralizados. Visite a documentação oficial para mais informações.

Os programadores do The Graph recebem ferramentas para processar eventos em blockchain e disponibilizar facilmente os dados resultantes através de uma API GraphQL, conhecida individualmente como um subgraph. O Graph Node agora é capaz de processar eventos no NEAR, significando que programadores na NEAR agora podem construir subgraphs para indexar seus contratos inteligentes.

Subgraphs são baseados em eventos; quer dizer, eles esperam e então processam eventos on-chain. Atualmente há dois tipos de handlers que funcionam para subgraphs no NEAR:

• Handlers de blocos: executados em todos os blocos novos
• Handlers de recibos: Executados sempre que uma mensagem é executada numa conta especificada

Da documentação do NEAR:

@graphprotocol/graph-cli é uma ferramenta de linha de comando para a construção e lançamento de subgraphs.

@graphprotocol/graph-ts é uma biblioteca de tipos específicos a subgraphs.

O desenvolvimento de subgraphs no NEAR exige o graph-cli acima da versão 0.23.0, e o graph-ts acima da versão 0.23.0.

Há três aspectos de definição de subgraph:

subgraph.yaml: o manifest do subgraph, que define as fontes de dados de interesse e como elas devem ser processadas. A NEAR é uma nova espécie (kind) de fonte de dados.

schema.graphql: um arquivo schema que define quais dados são armazenados para o seu subgraph, e como consultá-los via GraphQL. Os requerimentos para subgraphs no NEAR são cobertos pela documentação existente.

Mapeamentos do AssemblyScript: Código em AssemblyScript que traduz dos dados do evento às entidades definidas no seu schema. O apoio à NEAR introduz tipos de dados específicos ao NEAR e uma nova funcionalidade de análise de JSON.

Existem dois comandos importantes durante o desenvolvimento de um subgraph:

$ graph codegen # gera tipos do arquivo de schema identificado no manifest
$ graph build # gera Web Assembly dos arquivos AssemblyScript, e prepara todos os arquivos do subgraph em uma pasta /build

O manifest do subgraph (subgraph.yaml) identifica as fontes de dados ao subgraph, os gatilhos de interesse, e as funções que devem ser executadas em resposta a tais gatilhos. Veja abaixo um exemplo de manifest de subgraph para um subgraph na NEAR:

specVersion: 0.0.2
schema:
  file: ./src/schema.graphql # link para o arquivo de schema
dataSources:
  - kind: near
    network: near-mainnet
    source:
      account: app.good-morning.near # Esta fonte de dados monitorará esta conta
      startBlock: 10662188 # Necessário para a NEAR
    mapping:
      apiVersion: 0.0.5
      language: wasm/assemblyscript
      blockHandlers:
        - handler: handleNewBlock # nome da função no arq. de mapeamento
      receiptHandlers:
        - handler: handleReceipt # nome da função no arq. de mapeamento
      file: ./src/mapping.ts # link ao arq. com os mapeamentos de Assemblyscript

• Subgraphs na NEAR introduzem um novo tipo (kind) de fonte de dados (near)
• A rede (network) deve corresponder a uma rede no Graph Node hospedeiro. No Subgraph Studio, a mainnet do NEAR é near-mainnet, e a testnet é near-testnet
• Fontes de dados no NEAR introduzem um campo source.account opcional: um ID legível a humanos que corresponde a uma conta no NEAR. Isto pode ser uma conta ou subconta.
• Fontes de dados na NEAR introduzem um campo source.accounts opcional, que contém sufixos e prefixos opcionais. No mínimo, deve ser especificado o prefixo ou o sufixo, já que eles procurarão qualquer conta que comece ou termine com a lista respectiva de valores. Combinaria o exemplo abaixo: [app|good].*[morning.near|morning.testnet]. Se só for necessária uma lista de prefixos ou sufixos, o outro campo pode ser omitido.

accounts:
  prefixes:
    - app
    - good
  suffixes:
    - morning.near
    - morning.testnet

As fontes de dados na NEAR apoiam duas categorias de handlers:

• blockHandlers: executado em cada novo bloco na NEAR. Não é necessário nenhum source.account.
• receiptHandlers: executados em todo recibo onde o source.account da fonte de dados é o recipiente. Note que só são processadas combinações exatas (subcontas devem ser adicionadas como fontes de dados independentes).

A definição do schema descreve a estrutura do banco de dados do subgraph resultante e os relacionamentos entre entidades. Isto é agnóstico da fonte de dados original. Mais detalhes na definição do schema de subgraph aqui.

Os handlers para o processamento de eventos são escritos em AssemblyScript.

A indexação da NEAR introduz categorias de dados específicas à plataforma ao API do AssemblyScript.

class ExecutionOutcome {
      gasBurnt: u64,
      blockHash: Bytes,
      id: Bytes,
      logs: Array<string>,
      receiptIds: Array<Bytes>,
      tokensBurnt: BigInt,
      executorId: string,
  }

class ActionReceipt {
      predecessorId: string,
      receiverId: string,
      id: CryptoHash,
      signerId: string,
      gasPrice: BigInt,
      outputDataReceivers: Array<DataReceiver>,
      inputDataIds: Array<CryptoHash>,
      actions: Array<ActionValue>,
  }

class BlockHeader {
      height: u64,
      prevHeight: u64,// Always zero when version < V3
      epochId: Bytes,
      nextEpochId: Bytes,
      chunksIncluded: u64,
      hash: Bytes,
      prevHash: Bytes,
      timestampNanosec: u64,
      randomValue: Bytes,
      gasPrice: BigInt,
      totalSupply: BigInt,
      latestProtocolVersion: u32,
  }

class ChunkHeader {
      gasUsed: u64,
      gasLimit: u64,
      shardId: u64,
      chunkHash: Bytes,
      prevBlockHash: Bytes,
      balanceBurnt: BigInt,
  }

class Block {
      author: string,
      header: BlockHeader,
      chunks: Array<ChunkHeader>,
  }

class ReceiptWithOutcome {
      outcome: ExecutionOutcome,
      receipt: ActionReceipt,
      block: Block,
  }

Estes tipos são repassados para handlers de blocos e recibos:

• Handlers de blocos receberão um Block
• Handlers de recibos receberão um ReceiptWithOutcome

Caso contrário, o resto da API do AssemblyScript está à disposição dos programadores de subgraph no Near, durante a execução dos mapeamentos.

Isto inclui uma nova função de análise em JSON: logs na NEAR são frequentemente emitidos como JSONs em string. A nova função json.fromString(...) está disponível como parte da API JSON para que programadores processem estes logs com facilidade.

Quando tiver um subgraph pronto, chegará a hora de lançá-lo no Graph Node para indexar. Subgraphs na NEAR podem ser lançados em qualquer Graph Node >=v0.26.x (esta versão ainda não foi marcada ou lançada).

O Subgraph Studio e o Indexador de atualização na Graph Network apoiam atualmente a indexação da mainnet e da testnet do NEAR em beta, com os seguintes nomes de rede:

• near-mainnet
• near-testnet

Saiba mais sobre a criação e lançamento de subgraphs no Subgraph Studio aqui.

Para começo de conversa, o primeiro passo consiste em "criar" o seu subgraph - isto só precisa ser feito uma vez. No Subgraph Studio, isto pode ser feito do seu Painel: "Criar um subgraph".

Quando o seu subgraph estiver pronto, lance o seu subgraph com o comando de CLI graph deploy:

$ graph create --node <graph-node-url> <subgraph-name> # cria um subgraph num Graph Node local (no Subgraph Studio, isto é feito via a interface)
$ graph deploy --node <graph-node-url> --ipfs https://api.thegraph.com/ipfs/ <subgraph-name> # envia os arquivos de construção a um endpoint IPFS especificado, e depois edita o subgraph a um Graph Node especificado com base no hash IPFS do manifest

A configuração do nódulo dependerá de onde o subgraph será lançado.

graph auth --studio
graph deploy --studio <subgraph-name>

graph deploy --node http://localhost:8020/ --ipfs http://localhost:5001 <subgraph-name>

Quando o seu subgraph for lançado, ele será indexado pelo Graph Node. O seu progresso pode ser conferido com um query no próprio subgraph:

{
  _meta {
    block {
      number
    }
  }
}

Executar um Graph Node que indexa a NEAR exige estes requisitos opcionais:

• NEAR Indexer Framework (Estrutura de Indexer) com instrumentação Firehose
• Componente(s) de Firehose no NEAR
• Graph Node com endpoint Firehose configurado

Em breve, falaremos mais sobre como executar os componentes acima.

O endpoint da GraphQL para subgraphs na NEAR é determinado pela definição do schema, com a interface existente da API. Mais informações na documentação da API GraphQL.

Aqui estão alguns exemplos de subgraphs para referência:

NEAR Blocks

NEAR Receipts

O apoio à NEAR está em beta; podem ocorrer mais mudanças na API enquanto continuamos a melhorar a integração. Por favor, contacte-nos em [email protected] para podermos apoiar-te na construção de subgraphs no NEAR e avisar-te sobre os acontecimentos mais recentes!

Não, um subgraph só pode apoiar fontes de dados de apenas uma chain/rede.

Atualmente, só há apoio a gatilhos de Blocos e Recibos. Estamos a investigar gatilhos para chamadas de função a uma conta específica. Também temos interesse em apoiar gatilhos de eventos, quando a NEAR receber apoio nativo a eventos.

Se uma conta (account) for especificada, ela só combinará com o nome exacto da conta. É possível corresponder subcontas ao especificar um campo accounts, com sufixos (suffixes) e prefixos (prefixes) particularizados para encontrar contas e subcontas. Por exemplo, todas as subcontas mintbase1.near seriam encontradas com o seguinte:

accounts:
  suffixes:
    - mintbase1.near

Não há apoio a isto. Estamos a avaliar se esta funcionalidade é necessária para indexação.

Não há apoio a isto no momento. Estamos a avaliar se esta funcionalidade é necessária para indexação.

No momento, não há apoio à funcionalidade de pendências para subgraphs na NEAR. Entretanto, podes lançar uma nova versão para um subgraph de "nome" diferente, e quando este for sincronizado com a cabeça da chain, podes relançá-la para seu subgraph de "nome" primário, que usará o mesmo ID de lançamento subjacente — e aí, o subgraph principal sincronizará instantaneamente.

Se esta for uma pergunta geral sobre desenvolvimento de subgraphs, há mais informações no resto da documentação para programadores. Caso contrário, entre no Discord do Graph Protocol e pergunte no canal #near, ou mande a sua pergunta para [email protected].

• Documentação para programadores da NEAR