Construindo Subgraphs no Arweave

Reading time: 7 min

Neste guia, você aprenderá como construir e lançar Subgraphs para indexar a blockchain Arweave.

O protocolo Arweave permite que programadores armazenem dados permanentemente. Esta é a grande diferença entre o Arweave e o IPFS, considerando que o IPFS não tem esta característica; a permanência, e os arquivos armazenados no Arweave, não podem ser mudados ou apagados.

O Arweave já construiu várias bibliotecas para integrar o protocolo num número de línguas de programação diferentes. Para mais informações, pode-se conferir:

• Arwiki
• Arweave Resources

The Graph lhe permite construir APIs abertas e customizadas chamadas "Subgraphs". Subgraphs são usados para contar aos indexadores (operadores de servidor) quais dados devem ser indexados em uma blockchain e salvar em seus servidores para que você possa consultá-la a qualquer hora usando o GraphQL.

O Graph Node é atualmente capaz de indexar dados no protocolo Arweave. A integração atual indexa apenas o Arweave como uma blockchain (blocos e transações), mas não indexa os arquivos armazenados no momento.

Para construir e lançar Subgraphs no Arweave, são necessários dois pacotes:

1. @graphprotocol/graph-cli acima da versão 0.30.2 — Esta é uma ferramenta de linha de comandos para a construção e lançamento de subgraphs. Clique aqui para baixá-la usando o npm.
2. @graphprotocol/graph-ts acima da versão 0.07.2 — Esta é uma biblioteca de tipos específicos a subgraphs. Clique aqui para baixar usando o npm.

Um subgraph tem três componentes:

Define as fontes de dados de interesse, e como elas devem ser processadas. O Arweave é uma nova categoria de fontes de dados.

Aqui é possível definir quais dados queres consultar após indexar o seu subgraph utilizando o GraphQL. Isto é como um modelo para uma API, onde o modelo define a estrutura de um órgão de requisito.

Os requerimentos para subgraphs no Arweave são cobertos pela documentação existente.

Esta é a lógica que determina como os dados devem ser retirados e armazenados quando alguém interage com as fontes de dados que estás a escutar. Os dados são traduzidos e armazenados baseados no schema que listaste.

Durante o desenvolvimento de um subgraph, existem dois comandos importantes:

$ 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 um manifest de subgraph para um subgraph no Arweave:

specVersion: 0.0.5
description: Arweave Blocks Indexing
schema:
  file: ./schema.graphql # link ao arquivo schema
dataSources:
  - kind: arweave
    name: arweave-blocks
    network: arweave-mainnet # The Graph apoia apenas a Mainnet do Arweave
    source:
      owner: 'ID-OF-AN-OWNER' # A chave pública de uma carteira no Arweave
      startBlock: 0 # coloque isto como 0 para começar a indexar da gênese da chain
    mapping:
      apiVersion: 0.0.5
      language: wasm/assemblyscript
      file: ./src/blocks.ts # link ao arquivo com os mapeamentos no Assemblyscript
      entities:
        - Block
        - Transaction
      blockHandlers:
        - handler: handleBlock # o nome da função no arquivo de mapeamento
      transactionHandlers:
        - handler: handleTx # o nome da função no arquivo de mapeamento

• Subgraphs no Arweave introduzem uma nova categoria de fonte de dados (arweave)
• A rede deve corresponder a uma rede no Graph Node que a hospeda. No Subgraph Studio, a mainnet do Arweave é arweave-mainnet
• Fontes de dados no Arweave introduzem um campo source.owner opcional, a chave pública de uma carteira no Arweave

Fontes de dados no Arweave apoiam duas categorias de handlers:

• blockHandlers - Executar em cada bloco novo no Arweave. Nenhum source.owner é exigido.
• transactionHandlers — Executar em todas as transações onde o source.owner da fonte de dados é o dono. Atualmente, um dono é exigido para o transactionHandlers; caso utilizadores queiram processar todas as transações, eles devem providenciar "" como o source.owner

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. Há mais detalhes na definição de schema de subgraph aqui.

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

O indexing do Arweave introduz categorias de dados específicas ao Arweave ao API do AssemblyScript.

class Block {
  timestamp: u64
  lastRetarget: u64
  height: u64
  indepHash: Bytes
  nonce: Bytes
  previousBlock: Bytes
  diff: Bytes
  hash: Bytes
  txRoot: Bytes
  txs: Bytes[]
  walletList: Bytes
  rewardAddr: Bytes
  tags: Tag[]
  rewardPool: Bytes
  weaveSize: Bytes
  blockSize: Bytes
  cumulativeDiff: Bytes
  hashListMerkle: Bytes
  poa: ProofOfAccess
}

class Transaction {
  format: u32
  id: Bytes
  lastTx: Bytes
  owner: Bytes
  tags: Tag[]
  target: Bytes
  quantity: Bytes
  data: Bytes
  dataSize: Bytes
  dataRoot: Bytes
  signature: Bytes
  reward: Bytes
}

Handlers de bloco recebem um Block, enquanto transações recebem uma Transaction.

Escrever os mapeamentos de um Subgraph no Arweave é muito similar à escrita dos mapeamentos de um Subgraph no Ethereum. Para mais informações, clique aqui.

Após criar o seu Subgraph no painel de controlo do Subraph Studio, você pode lançá-lo com o código de linha de comando graph deploy.

graph deploy --studio --access-token <your-access-token>

O ponto final do GraphQL para subgraphs no Arweave é determinado pela definição do schema, com a interface existente da API. Visite a documentação da API da GraphQL para mais informações.

Aqui está um exemplo de subgraph para referência:

• Exemplo de Subgraph para o Arweave

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

Atualmente, The Graph apenas indexa o Arweave como uma blockchain (seus blocos e transações).

Isto não é apoiado no momento.

O source.owner pode ser a chave pública ou o endereço da conta do utilizador.

Os dados são geralmente passados aos mapeamentos como Bytes, que se armazenados diretamente, são retornados ao subgraph em um formato hex (por ex. hashes de transações e blocos). Você pode querer convertê-lo a um formato seguro em base64 ou base64 URL em seus mapeamentos, para combinar com o que é exibido em exploradores de blocos, como o Arweave Explorer.

A seguinte função bytesToBase64(bytes: Uint8Array, urlSafe: boolean): string pode ser usada, e será adicionada ao graph-ts:

const base64Alphabet = [
    "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M",
    "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z",
    "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m",
    "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z",
    "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "+", "/"
];

const base64UrlAlphabet = [
    "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M",
    "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z",
    "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m",
    "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z",
    "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "-", "_"
];

function bytesToBase64(bytes: Uint8Array, urlSafe: boolean): string {
    let alphabet = urlSafe? base64UrlAlphabet : base64Alphabet;

    let result = '', i: i32, l = bytes.length;
    for (i = 2; i < l; i += 3) {
        result += alphabet[bytes[i - 2] >> 2];
        result += alphabet[((bytes[i - 2] & 0x03) << 4) | (bytes[i - 1] >> 4)];
        result += alphabet[((bytes[i - 1] & 0x0F) << 2) | (bytes[i] >> 6)];
        result += alphabet[bytes[i] & 0x3F];
    }
    if (i === l + 1) { // 1 octet yet to write
        result += alphabet[bytes[i - 2] >> 2];
        result += alphabet[(bytes[i - 2] & 0x03) << 4];
        if (!urlSafe) {
            result += "==";
        }
    }
    if (!urlSafe && i === l) { // 2 octets yet to write
        result += alphabet[bytes[i - 2] >> 2];
        result += alphabet[((bytes[i - 2] & 0x03) << 4) | (bytes[i - 1] >> 4)];
        result += alphabet[(bytes[i - 1] & 0x0F) << 2];
        if (!urlSafe) {
            result += "=";
        }
    }
    return result;
}