Visão Geral sobre a Indexação

Indexadores são operadores de nodes na Graph Network que fazem staking em Graph Tokens (GRT) para prover serviços de indexação e processamento de consultas em query (queries). Os indexadores ganham taxas de consulta e recompensas de indexação pelos seus serviços. Eles também ganham taxas de query que são rebatadas de acordo com uma função de rebate exponencial.

O GRT em staking no protocolo é sujeito a um período de degelo, e pode passar por slashing (recolhimento de fundos) se algum Indexador maliciosamente servir dados incorretos para aplicativos ou indexar incorretamente. Os Indexadores também recebem recompensas dos Delegantes por stake delegado, para contribuir à rede.

Indexadores selecionam subgraphs para indexar com base no sinal de curadoria do subgraph, onde Curadores depositam GRT em staking para indicar quais subgraphs são de qualidade alta e devem ser priorizados. Consumidores (por ex., aplicativos) também podem configurar parâmetros para os quais Indexadores processam queries para seus subgraphs, além de configurar preferências para o preço das taxas de query.

Perguntas Frequentes

Qual o stake mínimo exigido para ser um Indexador na rede?

O stake mínimo atual para um Indexador é de 100 mil GRT.

Quais são as fontes de renda para um Indexador?

Rebates de taxas de query — Pagamentos por serviço de queries na rede. Estes pagamentos são mediados por canais de estado entre um Indexador e um gateway. Cada pedido de query de um gateway contém um pagamento e a resposta correspondente: uma prova de validade de resultado de query.

Recompensas de indexação — são distribuídas a Indexadores que indexam lançamentos de subgraph para a rede. São geradas através de uma inflação de 3% para todo o protocolo.

Como são distribuídas as recompensas de indexação?

As recompensas de indexação vêm da inflação do protocolo, que é configurada em 3% da emissão anual. Elas são distribuídas em subgraphs, com base na proporção de todos os sinais de curadoria em cada um, e depois distribuídos proporcionalmente a Indexadores baseado no stake que alocaram naquele subgraph. Para ter direito a recompensas, uma alocação deve ser fechada com uma prova de indexação válida (POI) que atende aos padrões determinados pela carta de arbitragem.

A comunidade criou várias ferramentas para calcular recompensas, organizadas na coleção de guias da comunidade⁠. Há também uma lista atualizada de ferramentas nos canais #Delegators e #Indexers no servidor do Discord⁠. No próximo link, temos um otimizador de alocações recomendadas⁠ integrado com o stack de software de indexador.

O que é uma prova de indexação (POI)?

POIs (Provas de indexação) são usadas na rede para verificar que um Indexador está a indexar os subgraphs nos quais eles alocaram. Uma POI para o primeiro bloco da epoch atual deve ser enviada ao fechar uma alocação, para que aquela alocação seja elegível a recompensas de indexação. Uma POI para um bloco serve como resumo para todas as transações de armazenamento de entidade para uma implantação específica de subgraph, até, e incluindo, aquele bloco.

Quando são distribuídas as recompensas de indexação?

As alocações acumulam recompensas continuamente, enquanto permanecerem ativas e alocadas dentro de 28 epochs. As recompensas são coletadas pelos Indexadores, e distribuídas sempre que suas alocações são fechadas. Isto acontece ou manualmente, quando o Indexador quer fechá-las à força; ou após 28 epochs, quando um Delegante pode fechar a alocação para o Indexador, mas isto não rende recompensas. A vida máxima de uma alocação é de 28 epochs (no momento, um epoch dura cerca de 24 horas).

É possível monitorar recompensas de indexação pendentes?

O contrato RewardsManager tem uma função de apenas-leitura — getRewards⁠ — que pode ser usada para verificar as recompensas pendentes para uma alocação específica.

Muitos dos painéis feitos pela comunidade incluem valores pendentes de recompensas, que podem facilmente ser conferidos de forma manual ao seguir os seguintes passos:

1. Faça um query do subgraph da mainnet para buscar as IDs de todas as alocações ativas:

1query indexerAllocations {2  indexer(id: "<INDEXER_ADDRESS>") {3    allocations {4      activeForIndexer {5        allocations {6          id7        }8      }9    }10  }11}

Use o Etherscan para chamar o getRewards():

• Navegue, na interface do Etherscan, para o contrato Rewards⁠
• Para chamar o getRewards():
  • Abra o dropdown 9. getRewards.
  • Preencha o campo da allocationID.
  • Clique no botão Query.

O que são disputas e onde posso visualizá-las?

As consultas em query e alocações de Indexadores podem ser disputadas no The Graph durante o período de disputa. O período de disputa varia a depender do tipo de disputa. Consultas/atestações têm uma janela de disputa de 7 epochs, enquanto alocações duram até 56 epochs. Após o vencimento destes períodos, não se pode abrir disputas contra alocações ou consultas. Quando uma disputa é aberta, um depósito mínimo de 10.000 GRT é exigido pelos Pescadores, que será trancado até ser finalizada a disputa e servida uma resolução. Pescadores são quaisquer participantes de rede que abrem disputas.

Há três possíveis resultados para disputas, assim como para o depósito dos Pescadores.

• Se a disputa for rejeitada, o GRT depositado pelo Pescador será queimado, e o Indexador disputado não será penalizado.
• Se a disputa terminar em empate, o depósito do Pescador será retornado, e o Indexador disputado não será penalizado.
• Se a disputa for aceite, o GRT depositado pelo Pescador será retornado, o Indexador disputado será penalizado, e o(s) Pescador(es) ganhará(ão) 50% do GRT cortado.

As disputas podem ser visualizadas na interface na página de perfil de um Indexador, sob a aba Disputes (Disputas).

O que são rebates de taxas de consulta e quando eles são distribuídos?

As taxas de query são coletadas pelo gateway e distribuídas aos Indexadores de acordo com a função de rebate exponencial (veja o GIP aqui⁠). A tal função é proposta como uma maneira de garantir que indexadores alcancem o melhor resultado ao servir queries fieis. Ela funciona com o incentivo de Indexadores para alocarem uma grande quantia de stake (que pode ser cortada por errar ao servir um query) relativa à quantidade de taxas de query que possam colecionar.

Quando uma alocação é fechada, os rebates podem ser reivindicados pelo Indexador. Após serem resgatados, os rebates de taxa de consulta são distribuídos ao Indexador e os seus Delegantes com base na porção de taxas de query e na função de rebate exponencial.

O que são porção de taxa de query e porção de recompensa de indexação?

Os valores queryFeeCut e indexingRewardCut são parâmetros de delegação que o Indexador pode configurar junto com o cooldownBlocks para controlar a distribuição de GRT entre o Indexador e os seus Delegantes. Veja os últimos passos no Staking no Protocolo para instruções sobre como configurar os parâmetros de delegação.

• queryFeeCut — a % de rebates de taxas de query a ser distribuída ao Indexador. Se isto for configurado em 95%, o Indexador receberá 95% das taxas de query ganhas quando uma alocação for fechada, com os outros 5% destinados aos Delegantes.

• indexingRewardCut — a % de recompensas de indexação a ser distribuída ao Indexador. Se isto for configurado em 95%, o Indexador receberá 95% do pool de recompensas de indexação ao fechamento de uma alocação e os Delegantes dividirão os outros 5%.

Como os Indexadores podem saber quais subgraphs indexar?

Os Indexadores podem se diferenciar ao aplicar técnicas avançadas para decidir indexações de subgraph, mas para dar uma ideia geral, vamos discutir várias métricas importantes usadas para avaliar subgraphs na rede:

• Sinal de curadoria — A proporção do sinal de curadoria na rede aplicado a um subgraph particular mede bem o interesse nesse subgraph; especialmente durante a fase de inicialização, quando o volume de queries começa a subir.

• Taxas de query coletadas — Os dados históricos para o volume de taxas de query coletadas para um subgraph específico indicam bem a demanda futura.

• Quantidade em staking - Ao monitorar o comportamento de outros Indexadores ou inspecionar proporções de stake total alocado a subgraphs específicos, um Indexador pode monitorar a reserva para queries nos subgraphs, para assim identificar subgraphs nos quais a rede mostra confiança ou subgraphs que podem necessitar de mais reservas.

• Subgraphs sem recompensas de indexação - Alguns subgraphs não geram recompensas de indexação, principalmente porque eles usam recursos não apoiados, como o IPFS, ou porque consultam outra rede fora da mainnet. Se um subgraph não estiver a gerar recompensas de indexação, o Indexador será notificado a respeito.

Quais são os requisitos de hardware?

• Pequeno — O suficiente para começar a indexar vários subgraphs. Provavelmente precisará de expansões.
• Normal — Setup normal. Este é o usado nos exemplos de manifests de implantação de k8s/terraform.
• Médio — Indexador de Produção. Apoia 100 subgraphs e de 200 a 500 solicitações por segundo.
• Grande — Preparado para indexar todos os subgraphs usados atualmente e servir solicitações para o tráfego relacionado.

Há alguma precaução básica de segurança que um Indexador deve tomar?

• Carteira de operador — Configurar uma carteira de operador é importante, pois permite a um Indexador manter a separação entre as suas chaves que controlam o stake e aquelas no controlo das operações diárias. Mais informações em Staking no Protocolo.

• Firewall - O serviço de Indexadores é o único que precisa ser exposto publicamente, e o trancamento de portas de admin e acesso ao banco de dados exigem muito mais atenção: o endpoint JSON-RPC do Graph Node (porta padrão: 8030), o endpoint da API de gerenciamento do Indexador (porta padrão: 18000), e o endpoint do banco de dados Postgres (porta padrão: 5432) não devem ser expostos.

Infraestrutura

O núcleo da infraestrutura de um Indexador é o Graph Node, que monitora as redes indexadas, extrai e carrega dados por uma definição de um subgraph, e o serve como uma API da GraphQL. O Graph Node deve estar conectado a endpoints que expõem dados de cada rede indexada; um node IPFS para abastecer os dados; um banco de dados PostgreSQL para o seu armazenamento; e componentes de Indexador que facilitem as suas interações com a rede.

• Banco de dados PostgreSQL — O armazenamento principal para o Graph Node, onde dados de subgraph são armazenados. O serviço e o agente indexador também usam o banco de dados para armazenar dados de canal de estado, modelos de custo, regras de indexação, e ações de alocação.

• Endpoint de dados — Para redes compatíveis com EVMs, o Graph Node deve estar conectado a um endpoint que expõe uma API JSON-RPC compatível com EVMs. Isto pode ser um único cliente, ou um setup mais complexo que carrega saldos em várias redes. É importante saber que certos subgraphs exigirão capabilidades particulares de clientes, como um modo de arquivo e/ou uma API de rastreamento.

• Node IPFS (versão abaixo de 5) — Os metadados de lançamento de subgraph são armazenados na rede IPFS. O Graph Node acessa primariamente o node IPFS durante o lançamento do subgraph, para retirar o manifest e todos os arquivos ligados. Indexadores de rede não precisam hospedar seu próprio node IPFS, pois já há um hospedado para a rede em https://ipfs.thegraph.com⁠.

• Serviço de Indexador — Cuida de todas as comunicações externas com a rede requeridas. Divide modelos de custo e estados de indexação, passa pedidos de query de gateways para um Graph Node, e monitora os pagamentos de query através de canais de estado com o gateway.

• Agente Indexador — Facilita as interações de Indexadores on-chain, que incluem cadastros na rede, gestão de lançamentos de Subgraph ao(s) seu(s) Graph Node(s), e gestão de alocações.

• Servidor de métricas Prometheus — O Graph Node e os componentes de Indexador registam as suas métricas ao servidor de métricas.

Observe: Para apoiar o escalamento ágil, recomendamos que assuntos de query e de indexação sejam separados entre conjuntos diferentes de nodes: nodes de query e nodes de indexação.

Visão geral das portas

Graph Node

Serviço Indexador

Agente Indexador

Como preparar uma infraestrutura de servidor com o Terraform no Google Cloud

Pré-requisitos para a instalação

• Google Cloud SDK
• Ferramenta de linha de comando Kubectl
• Terraform

Como criar um projeto no Google Cloud

• Clone ou navegue ao repositório de Indexador⁠.

• Navegue ao diretório ./terraform, é aqui onde todos os comandos devem ser executados.

1cd terraform

• Autentique com o Google Cloud e crie um projeto novo.

1gcloud auth login2project=<PROJECT_NAME>3gcloud projects create --enable-cloud-apis $project

• Use a página de cobrança do Google Cloud Console para ativar cobranças para o novo projeto.

• Crie uma configuração no Google Cloud.

1proj_id=$(gcloud projects list --format='get(project_id)' --filter="name=$project")2gcloud config configurations create $project3gcloud config set project "$proj_id"4gcloud config set compute/region us-central15gcloud config set compute/zone us-central1-a

• Ative as APIs necessárias do Google Cloud.

1gcloud services enable compute.googleapis.com2gcloud services enable container.googleapis.com3gcloud services enable servicenetworking.googleapis.com4gcloud services enable sqladmin.googleapis.com

• Crie uma conta de serviço.

1svc_name=<SERVICE_ACCOUNT_NAME>2gcloud iam service-accounts create $svc_name \3  --description="Service account for Terraform" \4  --display-name="$svc_name"5gcloud iam service-accounts list6# Pegue o email da conta de serviço da lista7svc=$(gcloud iam service-accounts list --format='get(email)'8--filter="displayName=$svc_name")9gcloud iam service-accounts keys create .gcloud-credentials.json \10  --iam-account="$svc"11gcloud projects add-iam-policy-binding $proj_id \12  --member serviceAccount:$svc \13  --role roles/editor

• Ative o peering entre o banco de dados e o cluster Kubernetes, que será criado no próximo passo.

1gcloud compute addresses create google-managed-services-default \2  --prefix-length=20 \3  --purpose=VPC_PEERING \4  --network default \5  --global \6  --description 'IP Range for peer networks.'7gcloud services vpc-peerings connect \8  --network=default \9  --ranges=google-managed-services-default

• Crie o arquivo de configuração mínimo no terraform (atualize quando necessário).

1indexer=<INDEXER_NAME>2cat > terraform.tfvars <<EOF3project = "$proj_id"4indexer = "$indexer"5database_password = "<senha do banco de dados>"6EOF

Usando o Terraform para criar infraestrutura

Antes de executar quaisquer comandos, leia o variables.tf⁠ e crie um arquivo terraform.tfvars neste diretório (ou modifique o que criamos no último passo). Para cada variável onde queira substituir o padrão, ou onde precisar configurar um valor, insira uma configuração no terraform.tfvars.

• Execute os seguintes comandos para criar a infraestrutura.

1# Instalar os plugins necessários2terraform init34# Ver o plano para recursos a ser criados5terraform plan67# Criar os recursos (isto deve levar até 30 minutos)8terraform apply

Baixe as credenciais do novo cluster para o ~/.kube/config e configure como o seu contexto padrão.

1gcloud container clusters get-credentials $indexer2kubectl config use-context $(kubectl config get-contexts --output='name'3| grep $indexer)

Como criar os componentes do Kubernetes para o Indexador

• Copie o diretório k8s/overlays a um novo diretório $dir, e ajuste a entrada bases no $dir/kustomization.yaml para apontar para o k8s/base.

• Leia todos os arquivos no $dir e ajuste quaisquer valores como indicado nos comentários.

Lance todos os recursos com o kubectl apply -k $dir.

Graph Node

O Graph Node⁠ é uma implementação de código aberto em Rust que faz event sources na blockchain Ethereum, para atualizar deterministicamente um armazenamento de dados que pode ser consultado através do endpoint GraphQL. Os programadores usam subgraphs para definir o seu schema e um conjunto de mapeamentos para transformar os dados da blockchain; e o Graph Node sincroniza toda a chain, monitora blocos novos, e serve-a através de um endpoint GraphQL.

Começando da fonte

Pré-requisitos para a instalação

• Rust

• PostgreSQL

• IPFS

• Requisitos Adicionais para utilizadores de Ubuntu — A execução de um Graph Node no Ubuntu pode exigir pacotes adicionais.

1sudo apt-get install -y clang libpg-dev libssl-dev pkg-config

Configuração

1. Inicie um servidor de banco de dados PostgreSQL

1initdb -D .postgres2pg_ctl -D .postgres -l logfile start3createdb graph-node

2. Clone o repositório do Graph Node⁠ e execute cargo build para construir a fonte

3. Agora que todas as dependências estão configuradas, inicialize o Graph Node:

1cargo run -p graph-node --release -- \2  --postgres-url postgresql://[USERNAME]:[PASSWORD]@localhost:5432/graph-node \3  --ethereum-rpc [NETWORK_NAME]:[URL] \4  --ipfs https://ipfs.thegraph.com

Como começar a usar o Docker

Pré-requisitos

• Node Ethereum - Por padrão, o setup do docker utilizará a mainnet: http://host.docker.internal:8545⁠ para se conectar ao node Ethereum na sua máquina de hospedagem. Você pode substituir este nome e url ao atualizar o docker-compose.yaml.

Configuração

1. Clone o Graph Node e navegue ao diretório do Docker:

1git clone https://github.com/graphprotocol/graph-node2cd graph-node/docker

2. Para utilizadores de Linux — use o endereço de IP do servidor em vez do host.docker.internal no docker-compose.yaml, usando o script incluído:

1./setup.sh

3. Inicie um Graph Node local que conectará ao seu endpoint na Ethereum:

1docker-compose up

Componentes de Indexador

Para participar com êxito na rede, são necessárias monitorizações e interações quase constantes, portanto, construímos um conjunto de aplicativos Typescript para facilitar a participação de um Indexador na rede. Há três componentes de Indexador:

• Agente indexador — O agente monitora a rede e a própria infraestrutura do Indexador, e administra quais lançamentos de subgraph são indexados e alocados on-chain; e a quantia a ser alocada para cada um.

• Serviço indexador — O único componente que deve ser exposto externamente, o serviço passa queries de subgraph ao graph node, cuida de canais de estado para pagamentos de query, e compartilha informações importantes de decisões para clientes, como os gateways.

• Indexer CLI — A interface de comando de linha para lidar com o agente indexador. Ela permite que Indexadores cuidem de modelos de custo, alocações manuais, ações em fila, e regras de indexação.

Primeiros passos

O agente indexador e o serviço de indexador devem ser co-localizados com a sua infraestrutura de Graph Node. Há várias maneiras de preparar ambientes de execução virtual para os seus componentes de Indexador. Aqui, veja como executá-los em um bare-metal (servidor dedicado) com pacotes NPM ou código fonte, ou através do Kubernetes e o docker no Engine Kubernetes do Google Cloud. Se estes exemplos de setup não batem bem com a sua infraestrutura, provavelmente deverá consultar um guia de comunidade no nosso Discord⁠. Lembre-se de fazer staking no protocolo antes de iniciar os seus componentes de Indexador!

De pacotes NPM

1npm install -g @graphprotocol/indexer-service2npm install -g @graphprotocol/indexer-agent34# O Indexer CLI é um plugin para o Graph CLI, então ambos devem ser instalados:5npm install -g @graphprotocol/graph-cli6npm install -g @graphprotocol/indexer-cli78# Serviço Indexador9graph-indexer-service start ...1011# Agente Indexador12graph-indexer-agent start ...1314# Indexer CLI15#Redirecione a porta do seu agent pod se estiver usando o Kubernetes16kubectl port-forward pod/POD_ID 18000:800017graph indexer connect http://localhost:18000/18graph indexer ...

Da fonte

1# Do diretório raiz do Repositório2yarn34# Serviço Indexador5cd packages/indexer-service6./bin/graph-indexer-service start ...78# Agente Indexador9cd packages/indexer-agent10./bin/graph-indexer-service start ...1112# Indexer CLI13cd packages/indexer-cli14./bin/graph-indexer-cli indexer connect http://localhost:18000/15./bin/graph-indexer-cli indexer ...

Usando o docker

• Puxe as imagens do registo

1docker pull ghcr.io/graphprotocol/indexer-service:latest2docker pull ghcr.io/graphprotocol/indexer-agent:latest

Ou construa imagens localmente da fonte

1# Serviço Indexador2docker build \3  --build-arg NPM_TOKEN=<npm-token> \4  -f Dockerfile.indexer-service \5  -t indexer-service:latest \6# Agente indexador7docker build \8  --build-arg NPM_TOKEN=<npm-token> \9  -f Dockerfile.indexer-agent \10  -t indexer-agent:latest \

• Execute os componentes

1docker run -p 7600:7600 -it indexer-service:latest ...2docker run -p 18000:8000 -it indexer-agent:latest ...

NOTA: Após iniciar os containers, o serviço Indexador deve ser acessível no http://localhost:7600⁠ e o agente indexador deve expor a API de gestão de Indexador no http://localhost:18000/⁠.

Usando K8s e Terraform

Veja a seção sobre preparar infraestruturas de servidor com o Terraform no Google Cloud

Uso

Agente Indexador

1graph-indexer-agent start \2  --ethereum <MAINNET_ETH_ENDPOINT> \3  --ethereum-network mainnet \4  --mnemonic <MNEMONIC> \5  --indexer-address <INDEXER_ADDRESS> \6  --graph-node-query-endpoint http://localhost:8000/ \7  --graph-node-status-endpoint http://localhost:8030/graphql \8  --graph-node-admin-endpoint http://localhost:8020/ \9  --public-indexer-url http://localhost:7600/ \10  --indexer-geo-coordinates <YOUR_COORDINATES> \11  --index-node-ids default \12  --indexer-management-port 18000 \13  --metrics-port 7040 \14  --network-subgraph-endpoint http://query-node-0:8000/subgraphs/id/QmUzRg2HHMpbgf6Q4VHKNDbtBEJnyp5JWCh2gUX9AV6jXv \15  --default-allocation-amount 100 \16  --register true \17  --inject-dai true \18  --postgres-host localhost \19  --postgres-port 5432 \20  --postgres-username <DB_USERNAME> \21  --postgres-password <DB_PASSWORD> \22  --postgres-database indexer \23  --allocation-management auto \24  | pino-pretty

Serviço Indexador

1SERVER_HOST=localhost \2SERVER_PORT=5432 \3SERVER_DB_NAME=is_staging \4SERVER_DB_USER=<DB_USERNAME> \5SERVER_DB_PASSWORD=<DB_PASSWORD> \6graph-indexer-service start \7  --ethereum <MAINNET_ETH_ENDPOINT> \8  --ethereum-network mainnet \9  --mnemonic <MNEMONIC> \10  --indexer-address <INDEXER_ADDRESS> \11  --port 7600 \12  --metrics-port 7300 \13  --graph-node-query-endpoint http://localhost:8000/ \14  --graph-node-status-endpoint http://localhost:8030/graphql \15  --postgres-host localhost \16  --postgres-port 5432 \17  --postgres-username <DB_USERNAME> \18  --postgres-password <DB_PASSWORD> \19  --postgres-database is_staging \20  --network-subgraph-endpoint http://query-node-0:8000/subgraphs/id/QmUzRg2HHMpbgf6Q4VHKNDbtBEJnyp5JWCh2gUX9AV6jXv \21  | pino-pretty

Indexer CLI

O Indexer CLI é um plugin para o @graphprotocol/graph-cli⁠, acessível no terminal em graph indexer.

1graph indexer connect http://localhost:180002graph indexer status

Gestão de Indexador com o Indexer CLI

O programa recomendado para interagir com a API de Gestão de Indexador é o Indexer CLI, uma extensão ao Graph CLI. O agente precisa de comandos de um Indexador para poder interagir de forma autônoma com a rede em nome do Indexador. Os mecanismos que definem o comportamento de um agente indexador são gestão de alocações e regras de indexamento. No modo automático, um Indexador pode usar regras de indexamento para aplicar estratégias específicas para a escolha de subgraphs para indexar e servir consultas. Regras são administradas através de uma API GraphQL servida pelo agente, e conhecida como a API de Gestão de Indexador. No modo manual, um Indexador pode criar ações de alocação usando a fila de ações, além de aprová-las explicitamente antes de serem executadas. Sob o modo de supervisão, as regras de indexação são usadas para popular a fila de ações e também exigem aprovação explícita para executar.

Uso

O Indexer CLI se conecta ao agente indexador, normalmente através do redirecionamento de portas, para que a CLI não precise ser executada no mesmo servidor ou cluster. Para facilitar o seu começo, e para fins de contexto, a CLI será descrita brevemente aqui.

• graph indexer connect <url> — Conecta à API de gestão de Indexador. Tipicamente, a conexão ao servidor é aberta através do redirecionamento de portas, para que a CLI possa ser operada remotamente com facilidade. (Exemplo: kubectl port-forward pod/<indexer-agent-pod> 8000:8000)

• graph indexer rules get [options] <deployment-id> [<key1> ...] — Mostra uma ou mais regras de indexação usando all como o <deployment-id> para mostrar todas as regras, ou global para exibir os padrões globais. Um argumento adicional --merged pode ser usado para especificar que regras, específicas à implantação, estão fundidas com a regra global. É assim que elas são aplicadas no agente de Indexador.

• graph indexer rules set [options] <deployment-id> <key1> <value1> ... — Configura uma ou mais regras de indexação.

• graph indexer rules start [options] <deployment-id> - Começa a indexar uma implantação de subgraph, se disponível, e configura a sua decisionBasis para always, para que o agente indexador sempre escolha indexá-lo. Caso a regra global seja configurada para always, todos os subgraphs disponíveis na rede serão indexados.

• graph indexer rules stop [options] <deployment-id> — Pára de indexar uma implantação e configura a sua decisionBasis em never, com o fim de pular esta implantação ao decidir quais implantações indexar.

• graph indexer rules maybe [options] <deployment-id> — Configura a decisionBasis de uma implantação para obedecer o rules, para que o agente Indexador use regras de indexação para decidir se esta implantação será ou não indexada.

• graph indexer actions get [options] <action-id> — Retira uma ou mais ações usando o all, ou deixa o action-id vazio para mostrar todas as ações. Um argumento adicional — --status — pode ser usado para imprimir todas as ações de um certo estado.

• graph indexer action queue allocate <deployment-id> <allocation-amount> — Programa a ação de alocação

• graph indexer action queue reallocate <deployment-id> <allocation-id> <allocationAmount> — Programa uma ação de realocação

• graph indexer action queue unallocate <deployment-id> <allocation-id> — Programa uma retirada de alocação

• graph indexer actions cancel [<action-id> ...] — Cancela todas as ações na fila se a id não for especificada; caso contrário, cancela o arranjo do id com espaço como separador

• graph indexer actions approve [<action-id> ...] — Aprova múltiplas ações para execução

• graph indexer actions execute approve — Força a execução imediata de ações aprovadas

Todos os comandos que mostram regras no resultado podem escolher entre os formatos de resultado (table, yaml, e json) com o argumento -output.

Regras de indexação

As regras de indexação podem ser aplicadas como padrões globais ou para implantações específicas de subgraph com o uso das suas IDs. Os campos deployment e decisionBasis são obrigatórios, enquanto todos os outros campos são opcionais. Quando uma regra de indexação tem rules como a decisionBasis, então o agente de Indexador comparará valores de limiar não-nulos naquela regra com valores retirados da rede para a implantação correspondente. Se a implantação do subgraph tiver valores acima (ou abaixo) de todos os limiares, ela será escolhida para a indexação.

Por exemplo: se a regra global tem um minStake de 5 (GRT), qualquer implantação de subgraph que tiver mais de 5 (GRT) de stake alocado nele será indexada. Regras de limiar incluem maxAllocationPercentage, minSignal, maxSignal, minStake, e minAverageQueryFees.

Modelo de dados:

1type IndexingRule {2    identifier: string3    identifierType: IdentifierType4    decisionBasis: IndexingDecisionBasis!5    allocationAmount: number | null6    allocationLifetime: number | null7    autoRenewal: boolean8    parallelAllocations: number | null9    maxAllocationPercentage: number | null10    minSignal: string | null11    maxSignal: string | null12    minStake: string | null13    minAverageQueryFees: string | null14    custom: string | null15    requireSupported: boolean | null16  }1718IdentifierType {19  deployment20  subgraph21  group22}2324IndexingDecisionBasis {25  rules26  never27  always28  offchain29}

Exemplos de uso de regra de indexação:

1graph indexer rules offchain QmZfeJYR86UARzp9HiXbURWunYgC9ywvPvoePNbuaATrEK23graph indexer rules set QmZfeJYR86UARzp9HiXbURWunYgC9ywvPvoePNbuaATrEK decisionBasis always allocationAmount 123321 allocationLifetime 14 autoRenewal false requireSupported false45graph indexer rules stop QmZfeJYR86UARzp9HiXbURWunYgC9ywvPvoePNbuaATrEK67graph indexer rules delete QmZfeJYR86UARzp9HiXbURWunYgC9ywvPvoePNbuaATrEK

CLI de fila de ações

O indexer-cli fornece um módulo actions para trabalhar manualmente com a fila de ações. Ele interage com a fila de ações através do API GraphQL hospedado pelo servidor de gestão de indexador.

O programa de execução de ações só retirará itens da fila para execução se esses tiverem o ActionStatus = approved. No local recomendado, as ações são adicionadas à fila com ActionStatus = queued; depois, serão aprovadas para serem executadas on-chain. O fluxo geral ficará assim:

• Ação adicionada à fila por ferramenta de otimização de terceiros ou utilizador do indexer-cli
• O Indexador pode usar o indexer-cli para visualizar todas as ações enfileiradas
• O Indexador (ou outro software) pode aprovar ou cancelar ações na fila usando o indexer-cli. Os comandos de aprovação e cancelamento aceitam um arranjo de ids de ação como comando.
• O programa de execução consulta a fila regularmente para verificar as ações aprovadas. Ele tomará as ações approved da fila, tentará executá-las, e atualizará os valores no banco de dados a depender do estado da execução, sendo success ou failed.
• Se uma ação tiver êxito, o programa garantirá a presença de uma regra de indexação que diz ao agente como administrar a alocação dali em diante. Isto será mais conveniente para executar ações manuais enquanto o agente está no modo auto ou oversight.
• O indexador pode monitorizar a fila de ações para ver um histórico de execuções de ação, e se necessário, aprovar novamente e atualizar itens de ação caso a sua execução falhe. A fila de ações provém um histórico de todas as ações agendadas e tomadas.

Modelo de dados:

1Type ActionInput {2    status: ActionStatus3    type: ActionType4    deploymentID: string | null5    allocationID: string | null6    amount: string | null7    poi: string | null8    force: boolean | null9    source: string10    reason: string | null11    priority: number | null12}1314ActionStatus {15  queued16  approved17  pending18  success19  failed20  canceled21}2223ActionType {24  allocate25  unallocate26  reallocate27  collect28}

Exemplo de uso da fonte:

1graph indexer actions get all23graph indexer actions get --status queued45graph indexer actions queue allocate QmeqJ6hsdyk9dVbo1tvRgAxWrVS3rkERiEMsxzPShKLco6 500067graph indexer actions queue reallocate QmeqJ6hsdyk9dVbo1tvRgAxWrVS3rkERiEMsxzPShKLco6 0x4a58d33e27d3acbaecc92c15101fbc82f47c2ae5 5500089graph indexer actions queue unallocate QmeqJ6hsdyk9dVbo1tvRgAxWrVS3rkERiEMsxzPShKLco6 0x4a58d33e27d3acbaecc92c15101fbc82f47c2ae1011graph indexer actions cancel1213graph indexer actions approve 1 3 51415graph indexer actions execute approve

Observe que os tipos apoiados de ações para gestão de alocação têm requisitos diferentes de entrada:

• Allocate — aloca stakes a uma implantação de subgraph específica

  • parâmetros de ação exigidos:
    • deploymentID
    • amount

• Unallocate — fecha uma alocação, que libera o stake para ser redistribuído em outro lugar

  • parâmetros de ação exigidos:
    • allocationID
    • deploymentID
  • parâmetros de ação opcionais:
    • poi
    • force (força o uso do POI providenciado, mesmo se ele não corresponder ao providenciado pelo graph-node)

• Reallocate — fecha a alocação automaticamente e abre uma alocação nova para a mesma implantação de subgraph

  • parâmetros de ação exigidos:
    • allocationID
    • deploymentID
    • amount
  • parâmetros de ação opcionais:
    • poi
    • force (força o uso do POI providenciado, mesmo se ele não corresponder ao providenciado pelo graph-node)

Modelos de custo

Modelos de custo servem preços dinâmicos para queries, com base em atributos de mercado e query. O Serviço de Indexador compartilha um modelo de custo com os gateways para cada subgraph, aos quais ele pretende responder a consultas. Os gateways, por sua vez, usam o modelo de custo para decidir seleções de Indexador por query e para negociar pagamentos com Indexadores escolhidos.

Agora

A linguagem Agora providencia um formato flexível para a declaração de modelos de custo para queries. Um modelo de preço do Agora é uma sequência de declarações, executadas em ordem, para cada query de alto-nível em um query no GraphQL. Para cada query de nível máximo, a primeira declaração correspondente determina o preço para o tal query.

Uma declaração consiste de um predicado, que é usado para corresponder a buscas GraphQL; e uma expressão de custo que, quando avaliada, mostra um custo em GRT decimal. Valores na posição de argumento nomeada em um query podem ser capturados no predicado e usados na expressão. Valores globais também podem ser configurados e substituídos por valores temporários em uma expressão.

Exemplo de modelo de custo:

1# Esta declaração captura o valor de pulo,2# usa uma expressão boolean no predicado para corresponder a consultas específicas que usam 'skip'3# e uma expressão de custo para calcular o custo baseado no valor 'skip' e no global SYSTEM_LOAD4SYSTEM_LOAD global5query { pairs(skip: $skip) { id } } when $skip > 2000 => 0.0001 * $skip * $SYSTEM_LOAD;67# Este padrão corresponderá a qualquer expressão GraphQL.8# Ele usa um Global substituído na expressão para calcular o custo9default => 0.1 * $SYSTEM_LOAD;

Exemplo de custo de query usando o modelo acima:

Aplicação do modelo de custo

Os modelos de custo são aplicados através do Indexer CLI, que os repassa à API de Gestão do agente de Indexador para armazenamento no banco de dados. O Serviço de Indexador depois irá localizar e servir os modelos de custo para gateways, sempre que eles forem requisitados.

1indexer cost set variables '{ "SYSTEM_LOAD": 1.4 }'2indexer cost set model my_model.agora

Interações com a rede

Stake no protocolo

Os primeiros passos para participar na rede como Indexador consistem em aprovar o protocolo, fazer staking de fundos, e (opcionalmente) preparar um endereço de operador para interações ordinárias do protocolo.

Quando um Indexador faz stake de GRT no protocolo, será possível iniciar os seus componentes e começar as suas interações com a rede.

Aprovação de tokens

1. Abra o app Remix⁠ em um navegador

2. No File Explorer, crie um arquivo chamado GraphToken.abi com a Token ABI⁠.

3. Com GraphToken.abi selecionado e aberto no editor, abra a seção Deploy and Run Transactions (Implantar e Executar Transações) na interface do Remix.

4. Na opção Environment (ambiente), selecione Injected Web3, e sob Account (conta), selecione o seu endereço de Indexador.

5. Configure o endereço de contrato de GraphToken — cole o endereço de contrato do GraphToken (0xc944E90C64B2c07662A292be6244BDf05Cda44a7) próximo ao At Address e clique no botão At address para aplicar.

6. Chame a função approve(spender, amount) para aprovar o contrato de Staking. Preencha a lacuna spender, que tem o endereço de contrato de Staking (0xF55041E37E12cD407ad00CE2910B8269B01263b9), e a amount com os tokens a serem colocados (em wei).

Staking de tokens

1. Abra o app Remix⁠ em um navegador

2. No File Explorer, crie um arquivo chamado Staking.abi com a ABI de staking.

3. Com o Staking.abi selecionado e aberto no editor, entre na seção com Deploy and Run Transactions na interface do Remix.

4. Na opção Environment (ambiente), selecione Injected Web3, e sob Account (conta), selecione o seu endereço de Indexador.

5. Configure o endereço de contrato de Staking — cole o endereço de contrato do Staking (0xF55041E37E12cD407ad00CE2910B8269B01263b9) próximo ao At Address e clique no botão At address para aplicar.

6. Chame o stake() para fazer stake de GRT no protocolo.

7. (Opcional) Os Indexadores podem aprovar outro endereço para operar sua infraestrutura de Indexador, a fim de poder separar as chaves que controlam os fundos daquelas que realizam ações rotineiras, como alocar em subgraphs e servir queries (pagos). Para configurar o operador, chame o setOperator() com o endereço do operador.

8. (Opcional) Para controlar a distribuição de recompensas e atrair Delegantes estrategicamente, os Indexadores podem atualizar os seus parâmetros de delegação ao atualizar o seu indexingRewardCut (partes por milhão); queryFeeCut (partes por milhão); e cooldownBlocks (número de blocos). Para fazer isto, chame o setDelegationParameters(). O seguinte exemplo configura o queryFeeCut para distribuir 95% de rebates de query ao Indexador e 5% aos Delegantes; configura o indexingRewardCutto para distribuir 60% de recompensas de indexação ao Indexador e 40% aos Delegantes; e configura o período do thecooldownBlocks para 500 blocos.

1setDelegationParameters(950000, 600000, 500)

Configuração de parâmetros de delegação

A função setDelegationParameters() no contrato de staking⁠ é essencial para Indexadores; esta permite configurar parâmetros que definem as suas interações com Delegantes, o que influencia a sua capacidade de delegação e divisa de recompensas.

Como configurar parâmetros de delegação

Para configurar os parâmetros de delegação com a interface do Graph Explorer, siga os seguintes passos:

1. Navegue para o Graph Explorer.
2. Conecte a sua carteira. Escolha a multisig (por ex., Gnosis Safe), e depois, a mainnet. Observe que será necessário repetir este processo para o Arbitrum One.
3. Conecte a carteira que possui como signatário.
4. Navegue até a seção ‘Settings’ (Configurações) e selecione ‘Delegation Parameters’ (Parâmetros de Delegação). Estes parâmetros devem ser configurados para alcançar uma parte efetiva dentro do alcance desejado. Após preencher os campos com valores, a interface calculará automaticamente a parte efetiva. Ajuste estes valores como necessário para obter a percentagem de parte efetiva desejada.
5. Envie a transação à rede.

A vida de uma alocação

Após criada por um Indexador, uma alocação sadia passa por dois estados.

• Ativa - Quando uma alocação é criada on-chain (allocateFrom()⁠), ela é considerada ativa. Uma porção do stake próprio e/ou delegado do Indexador é alocada a uma implantação de subgraph, que lhe permite resgatar recompensas de indexação e servir queries para aquela implantação de subgraph. O agente indexador cria alocações baseadas nas regras do Indexador.

• Fechada - Um Indexador pode fechar uma alocação após a passagem de um epoch (closeAllocation()⁠), ou o seu agente indexador a fechará automaticamente após o maxAllocationEpochs (atualmente, 28 dias). Quando uma alocação é fechada com uma prova de indexação válida (POI), as suas recompensas de indexação são distribuídas ao Indexador e aos seus Delegantes (aprenda mais).

É ideal que os Indexadores utilizem a funcionalidade de sincronização off-chain para sincronizar implantações de subgraph à chainhead antes de criar a alocação on-chain. Esta ferramenta é mais útil para subgraphs que demorem mais de 28 epochs para sincronizar, ou que têm chances de falhar não-deterministicamente.