9 minutos
Construção de Subgraphs na NEAR
Este guia explica como construir subgraphs para indexar contratos inteligentes na blockchain NEAR.
O que é NEAR?
NEAR é uma plataforma de contrato inteligente para construir aplicativos descentralizados. Visite a documentação oficial para mais informações.
O que são subgraphs na NEAR?
The Graph fornece aos programadores ferramentas para processar eventos de blockchain e tornar os dados resultantes facilmente disponíveis por meio de uma API GraphQL, conhecida individualmente como subgraph. O Graph Node agora é capaz de processar eventos NEAR, o que significa que programadores da NEAR agora podem criar subgraphs para indexar seus contratos inteligentes.
Subgraphs são baseados em eventos; ou seja, eles esperam e então processam eventos on-chain. Atualmente há dois tipos de handlers que funcionam para subgraphs na NEAR:
- Handlers de blocos: executados em todos os blocos novos
- Handlers de recibos: Executados sempre que uma mensagem é executada numa conta especificada
Um Recibo é o único objeto acionável no sistema. Quando falamos de “processar uma transação” na plataforma NEAR, em algum ponto isto eventualmente significa “aplicar recibos”.
Construindo um Subgraph no NEAR
@graphprotocol/graph-cli é uma ferramenta de linha de comando para a construção e implantação de subgraphs.
@graphprotocol/graph-ts é uma biblioteca de tipos específicos a subgraphs.
A programação 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.
Construir um subgraph na NEAR é um processo muito parecido com a construção de um subgraph que indexa o Ethereum.
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 de schema que define quais dados são armazenados para o seu subgraph e como consultá-los via GraphQL. Os requisitos para subgraphs NEAR são cobertos pela documentação existente.
Mapeamentos de AssemblyScript: Código AssemblyScript que traduz dos dados do evento para as entidades definidas no seu esquema. O apoio à NEAR introduz tipos de dados específicos da NEAR e novas funções de análise JSON.
During Subgraph development there are two key commands:
1$ graph codegen # generates types from the schema file identified in the manifest2$ graph build # generates Web Assembly from the AssemblyScript files, and prepares all the Subgraph files in a /build folderDefinição de Manifest de Subgraph
O manifest do subgraph (subgraph.yaml) identifica as fontes de dados para o subgraph, os gatilhos de interesse, e as funções que devem ser executadas em resposta a tais gatilhos. Veja abaixo um exemplo de manifest para um subgraph na NEAR:
1specVersion: 1.3.02schema:3 file: ./src/schema.graphql # link to the schema file4dataSources:5 - kind: near6 network: near-mainnet7 source:8 account: app.good-morning.near # This data source will monitor this account9 startBlock: 10662188 # Required for NEAR10 mapping:11 apiVersion: 0.0.912 language: wasm/assemblyscript13 blockHandlers:14 - handler: handleNewBlock # the function name in the mapping file15 receiptHandlers:16 - handler: handleReceipt # the function name in the mapping file17 file: ./src/mapping.ts # link to the file with the Assemblyscript mappings- Subgraphs na NEAR introduzem um novo tipo (
kind) de fonte de dados (near) - O
networkdeve corresponder a uma rede no Graph Node hóspede. No Subgraph Studio, a mainnet da NEAR énear-mainnet, e a testnet da NEAR énear-testnet - Fontes de dados na NEAR introduzem um campo
source.accountopcional: uma ID legível a humanos que corresponde a uma conta na NEAR. Isto pode ser uma conta ou subconta. - As fontes de dados da NEAR introduzem um campo alternativo
source.accountsopcional, que contém sufixos e prefixos opcionais. Pelo menos prefix ou sufixo deve ser especificado, eles corresponderão a qualquer conta que comece ou termine com a lista de valores, respectivamente. O exemplo abaixo corresponderia a:[app|good].*[morning.near|morning.testnet]. Se apenas uma lista de prefixos ou sufixos for necessária, o outro campo pode ser omitido.
1accounts:2 prefixes:3 - app4 - good5 suffixes:6 - morning.near7 - morning.testnetAs fontes de dados na NEAR apoiam duas categorias de handlers:
blockHandlers: executado em cada novo bloco na NEAR. Não é necessário nenhumsource.account.receiptHandlers: executados em todo recibo onde osource.accountda fonte de dados é o recipiente. Note que só são processadas combinações exatas (subcontas devem ser adicionadas como fontes de dados independentes).
Definição de Schema
A definição de Schema descreve a estrutura do banco de dados resultado do subgraph, e os relacionamentos entre entidades. Isto é agnóstico da fonte de dados original. Para mais detalhes sobre a definição de schema de subgraph, clique aqui.
Mapeamentos em AssemblyScript
Os handlers para processamento de eventos estão escritos em AssemblyScript.
A indexação da NEAR introduz tipos de dados específicos desse ecossistema à API do AssemblyScript.
1class ExecutionOutcome {2 gasBurnt: u64,3 blockHash: Bytes,4 id: Bytes,5 logs: Array<string>,6 receiptIds: Array<Bytes>,7 tokensBurnt: BigInt,8 executorId: string,9 }1011class ActionReceipt {12 predecessorId: string,13 receiverId: string,14 id: CryptoHash,15 signerId: string,16 gasPrice: BigInt,17 outputDataReceivers: Array<DataReceiver>,18 inputDataIds: Array<CryptoHash>,19 actions: Array<ActionValue>,20 }2122class BlockHeader {23 height: u64,24 prevHeight: u64,// Always zero when version < V325 epochId: Bytes,26 nextEpochId: Bytes,27 chunksIncluded: u64,28 hash: Bytes,29 prevHash: Bytes,30 timestampNanosec: u64,31 randomValue: Bytes,32 gasPrice: BigInt,33 totalSupply: BigInt,34 latestProtocolVersion: u32,35 }3637class ChunkHeader {38 gasUsed: u64,39 gasLimit: u64,40 shardId: u64,41 chunkHash: Bytes,42 prevBlockHash: Bytes,43 balanceBurnt: BigInt,44 }4546class Block {47 author: string,48 header: BlockHeader,49 chunks: Array<ChunkHeader>,50 }5152class ReceiptWithOutcome {53 outcome: ExecutionOutcome,54 receipt: ActionReceipt,55 block: Block,56 }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 na 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 mais facilidade.
Lançando um Subgraph na NEAR
Quando tiver um subgraph pronto, chegará a hora de implantá-lo no Graph Node para indexar. Subgraphs na NEAR podem ser implantados em qualquer Graph Node >=v0.26.x (esta versão ainda não foi marcada ou liberada).
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-mainnetnear-testnet
Para saber mais sobre como criar e implantar subgraphs no Subgraph Studio, clique 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, implante o seu subgraph com o comando de CLI graph deploy:
1$ graph create --node <graph-node-url> <subgraph-name> # cria um subgraph num Graph Node local (no Subgraph Studio, isto é feito via a interface)2$ graph deploy --node <graph-node-url> --ipfs https://ipfs.thegraph.com <subgraph-name> # envia os arquivos do build a um ponto final IPFS especificado, e implanta o subgraph num Graph Node com base no hash IPFS do manifestA configuração do nódulo dependerá de onde o subgraph será implantado.
Subgraph Studio
1graph auth2graph deploy <subgraph-name>Graph Node local (baseado na configuração padrão)
1graph deploy --node http://localhost:8020/ --ipfs http://localhost:5001 <subgraph-name>Quando o seu subgraph for implantado, ele será indexado pelo Graph Node. O seu progresso pode ser conferido com um query no próprio subgraph:
1{2 _meta {3 block {4 number5 }6 }7}Como indexar a NEAR com um Graph Node local
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.
Como Consultar um Subgraph na NEAR
O endpoint do GraphQL para subgraphs na NEAR é determinado pela definição do schema, com a interface existente da API. Visite a documentação da API da GraphQL para mais informações.
Exemplos de Subgraphs
Aqui estão alguns exemplos de subgraphs para referência:
Perguntas Frequentes
Como o beta funciona?
O apoio à NEAR está em fase 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!
Um subgraph pode indexar chains da NEAR e da EVM?
No, a Subgraph can only support data sources from one chain/network.
Os subgraphs podem reagir a gatilhos mais específicos?
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.
Handlers de recibos ativarão para contas e subcontas?
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:
1accounts:2 suffixes:3 - mintbase1.nearSubgraphs na NEAR podem fazer chamadas de vistoria para contas NEAR durante os mapeamentos?
Não há apoio a isto. Estamos a avaliar se esta funcionalidade é necessária para indexação.
Posso usar modelos de fontes de dados no meu subgraph na NEAR?
Não há apoio a isto no momento. Estamos a avaliar se esta funcionalidade é necessária para indexação.
Os subgraphs na Ethereum apoiam versões “pendentes” e “atuais”. Como posso implantar uma versão “pendente” de um subgraph no NEAR?
No momento, não há apoio à funcionalidade de pendências para subgraphs na NEAR. Entretanto, é possível 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.
A minha pergunta não foi respondida. Onde posso conseguir mais ajuda sobre construir subgraphs na NEAR?
Se esta for uma pergunta geral sobre programação 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].