Indexação

Reading time: 28 min

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.

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

Rebates de taxas de consulta - Pagamentos por serviço de consultas na rede. Estes pagamentos são mediados através de 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.

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 ser elegível 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.

POIs são usadas na rede, para verificar que um Indexador está indexando 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 um lançamento específico de subgraph, até, e incluindo, aquele bloco.

As alocações continuamente acumulam recompensas 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 Indexer 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).

O contrato RewardsManager tem uma função getRewards de apenas-leitura que pode ser usada para conferir 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. Consulte a subgraph da mainnet para conseguir as IDs de todas as alocações ativas:

query indexerAllocations {
  indexer(id: "<ENDEREÇO_INDEXER>") {
    allocations {
      activeForIndexer {
        allocations {
          id
        }
      }
    }
  }
}

Use o Etherscan para chamar o getRewards():

• Navegue à interface do Etherscan para o contrato de Recompensas

• Para chamar o getRewards():
  • Abra o dropdown 9. getRewards.
  • Insira a allocationID.
  • Clique no botão Query.

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 dependendo 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 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.
• Caso aceita a disputa, 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).

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. Ao reivindicar, os rebates de taxa de consulta são distribuídos ao Indexador e os seus Delegantes com base na porção de taxas de consulta e na função de rebate exponencial.

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 - o % de rebates de taxas de query a ser distribuído 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 - o % de recompensas de indexação a ser distribuído 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%.

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 naquele subgraph; especialmente durante a fase de inicialização, quando o volume de consultas 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 alocados a subgraphs específicos, um Indexador pode monitorar a reserva para queries nos subgraphs, para 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.

• 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 lançamento k8s/terraform.
• Médio — Indexador de Produção. Apoia 100 subgraphs e 200 – 500 pedidos por segundo.
• Grande — Preparado para indexar todos os subgraphs usados atualmente e servir pedidos para o tráfego relacionado.

• 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.

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 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 uma API de rastreamento.

• Node IPFS (versão menor que 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.network.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 consulta de gateways para um Graph Node, e monitora os pagamentos de consulta através de canais de estado com o gateway.

• Agente Indexador — Facilita as interações de Indexadores on-chain, incluindo 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 logam suas métricas ao servidor de métricas.

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

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

• Clone ou navegue ao repositório de Indexador.

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

cd terraform

• Autentique como Google Cloud e crie um novo projeto.

gcloud auth login
project=<PROJECT_NAME>
gcloud projects create --enable-cloud-apis $project

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

• Crie uma configuração no Google Cloud.

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

• Ligue as APIs requeridas do Google Cloud.

gcloud services enable compute.googleapis.com
gcloud services enable container.googleapis.com
gcloud services enable servicenetworking.googleapis.com
gcloud services enable sqladmin.googleapis.com

• Crie uma conta de serviço.

svc_name=<SERVICE_ACCOUNT_NAME>
gcloud iam service-accounts create $svc_name \
  --description="Service account for Terraform" \
  --display-name="$svc_name"
gcloud iam service-accounts list
# Get the email of the service account from the list
svc=$(gcloud iam service-accounts list --format='get(email)'
--filter="displayName=$svc_name")
gcloud iam service-accounts keys create .gcloud-credentials.json \
  --iam-account="$svc"
gcloud projects add-iam-policy-binding $proj_id \
  --member serviceAccount:$svc \
  --role roles/editor

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

gcloud compute addresses create google-managed-services-default \
  --prefix-length=20 \
  --purpose=VPC_PEERING \
  --network default \
  --global \
  --description 'IP Range for peer networks.'
gcloud services vpc-peerings connect \
  --network=default \
  --ranges=google-managed-services-default

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

indexer=<INDEXER_NAME>
cat > terraform.tfvars <<EOF
project = "$proj_id"
indexer = "$indexer"
database_password = "<database passowrd>"
EOF

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.

# Instalar os plugins requeridos
terraform init

# Ver o plano para recursos a ser criados
terraform plan

# Criar os recursos (isto deve levar até 30 minutos)
terraform apply

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

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

• Copie o diretório k8s/overlays a um novo diretório $dir, e ajuste a entrada bases no $dir/kustomization.yaml para que ele aponte ao diretório 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.

O Graph Node é uma implementação em Rust de código aberto 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.

• Rust

• PostgreSQL

• IPFS

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

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

1. Comece um servidor de banco de dados PostgreSQL

initdb -D .postgres
pg_ctl -D .postgres -l logfile start
createdb graph-node

2. Clone a repo do Graph Node e construa a fonte executando o cargo build

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

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

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

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

git clone https://github.com/graphprotocol/graph-node
cd 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:

./setup.sh

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

docker-compose up

Para participar com êxito na rede, são necessários monitorados e interações quase constantes, portanto, construímos uma suite 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 consultas de subgraph ao graph node, cuida de canais de estado para pagamentos de consulta, 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, filas de ações e regras de indexação.

O agente indexador e o serviço 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!

npm install -g @graphprotocol/indexer-service
npm install -g @graphprotocol/indexer-agent

# O Indexer CLI é um plugin para o Graph CLI, então ambos devem ser instalados:
npm install -g @graphprotocol/graph-cli
npm install -g @graphprotocol/indexer-cli

# Serviço Indexador
graph-indexer-service start ...

# Agente Indexador
graph-indexer-agent start ...

# Indexer CLI
#Redirecione a porta do seu agent pod se estiver usando o Kubernetes
kubectl port-forward pod/POD_ID 18000:8000
graph indexer connect http://localhost:18000/
graph indexer ...

# Do diretório raiz do Repo
yarn

# Serviço Indexador
cd packages/indexer-service
./bin/graph-indexer-service start ...

# Agente Indexador
cd packages/indexer-agent
./bin/graph-indexer-service start ...

# Indexer CLI
cd packages/indexer-cli
./bin/graph-indexer-cli indexer connect http://localhost:18000/
./bin/graph-indexer-cli indexer ...

• Puxe as imagens do registo

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

Ou construa imagens localmente da fonte

# Serviço Indexador
docker build \
  --build-arg NPM_TOKEN=<npm-token> \
  -f Dockerfile.indexer-service \
  -t indexer-service:latest \
# Agente indexador
docker build \
  --build-arg NPM_TOKEN=<npm-token> \
  -f Dockerfile.indexer-agent \
  -t indexer-agent:latest \

• Execute os componentes

docker run -p 7600:7600 -it indexer-service:latest ...
docker 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/.

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

graph-indexer-agent start \
  --ethereum <MAINNET_ETH_ENDPOINT> \
  --ethereum-network mainnet \
  --mnemonic <MNEMONIC> \
  --indexer-address <INDEXER_ADDRESS> \
  --graph-node-query-endpoint http://localhost:8000/ \
  --graph-node-status-endpoint http://localhost:8030/graphql \
  --graph-node-admin-endpoint http://localhost:8020/ \
  --public-indexer-url http://localhost:7600/ \
  --indexer-geo-coordinates <YOUR_COORDINATES> \
  --index-node-ids default \
  --indexer-management-port 18000 \
  --metrics-port 7040 \
  --network-subgraph-endpoint https://gateway.network.thegraph.com/network \
  --default-allocation-amount 100 \
  --register true \
  --inject-dai true \
  --postgres-host localhost \
  --postgres-port 5432 \
  --postgres-username <DB_USERNAME> \
  --postgres-password <DB_PASSWORD> \
  --postgres-database indexer \
  --allocation-management auto \
  | pino-pretty

SERVER_HOST=localhost \
SERVER_PORT=5432 \
SERVER_DB_NAME=is_staging \
SERVER_DB_USER=<DB_USERNAME> \
SERVER_DB_PASSWORD=<DB_PASSWORD> \
graph-indexer-service start \
  --ethereum <MAINNET_ETH_ENDPOINT> \
  --ethereum-network mainnet \
  --mnemonic <MNEMONIC> \
  --indexer-address <INDEXER_ADDRESS> \
  --port 7600 \
  --metrics-port 7300 \
  --graph-node-query-endpoint http://localhost:8000/ \
  --graph-node-status-endpoint http://localhost:8030/graphql \
  --postgres-host localhost \
  --postgres-port 5432 \
  --postgres-username <DB_USERNAME> \
  --postgres-password <DB_PASSWORD> \
  --postgres-database is_staging \
  --network-subgraph-endpoint https://gateway.network.thegraph.com/network \
  | pino-pretty

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

graph indexer connect http://localhost:18000
graph indexer status

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 Indexer. 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 gerenciadas 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.

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 começar mais facilmente, 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 exibit os padrões globais. Um argumento adicional --merged pode ser usado para especificar que regras, específicas ao lançamento, 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 um lançamento 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> — Para de indexar um lançamento e configura a sua decisionBasis em never, com o fim de pular este lançamento ao decidir quais lançamentos indexar.

• graph indexer rules maybe [options] <deployment-id> — Configura a decisionBasis de um lançamento para obedecer o rules, comandando o agente indexador a usar regras de indexação para decidir se este lançamento será ou não indexado.

• 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 no console todas as ações de um certo status.

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

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

• graph indexer action queue unallocate <deployment-id> <allocation-id> - Desaloca ação na fila

• 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 de 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 o trabalhador a executar ações aprovadas imediatamente

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

As regras de indexação podem ser aplicadas como padrões globais ou para lançamentos de subgraph específicos 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 o lançamento correspondente. Se o lançamento do subgraph tiver valores acima (ou abaixo) de todos os limiares, ele será escolhido para a indexação.

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

Modelo de dados:

type IndexingRule {
    identifier: string
    identifierType: IdentifierType
    decisionBasis: IndexingDecisionBasis!
    allocationAmount: number | null
    allocationLifetime: number | null
    autoRenewal: boolean
    parallelAllocations: number | null
    maxAllocationPercentage: number | null
    minSignal: string | null
    maxSignal: string | null
    minStake: string | null
    minAverageQueryFees: string | null
    custom: string | null
    requireSupported: boolean | null
  }

IdentifierType {
  deployment
  subgraph
  group
}

IndexingDecisionBasis {
  rules
  never
  always
  offchain
}

Exemplos de uso de regra de indexação:

graph indexer rules offchain QmZfeJYR86UARzp9HiXbURWunYgC9ywvPvoePNbuaATrEK

graph indexer rules set QmZfeJYR86UARzp9HiXbURWunYgC9ywvPvoePNbuaATrEK decisionBasis always allocationAmount 123321 allocationLifetime 14 autoRenewal false requireSupported false

graph indexer rules stop QmZfeJYR86UARzp9HiXbURWunYgC9ywvPvoePNbuaATrEK

graph indexer rules delete QmZfeJYR86UARzp9HiXbURWunYgC9ywvPvoePNbuaATrEK

O indexer-cli providencia 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 trabalhador de execução de ações só retirará itens da fila para execução se eles tiverem o ActionStatus = approved. No caminho recomendado, as ações são adicionadas à fila com ActionStatus = queued, para que sejam depois aprovadas para serem executadas on-chain. O fluxo geral parecerá com isto:

• 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 trabalhador de execução consulta a fila regularmente para 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 trabalhador garantirá a presença de uma regra de indexação que diga ao agente como administrar a alocação dali em diante, por mais conveniência ao tomar 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:

Type ActionInput {
    status: ActionStatus
    type: ActionType
    deploymentID: string | null
    allocationID: string | null
    amount: string | null
    poi: string | null
    force: boolean | null
    source: string
    reason: string | null
    priority: number | null
}

ActionStatus {
  queued
  approved
  pending
  success
  failed
  canceled
}

ActionType {
  allocate
  unallocate
  reallocate
  collect
}

Exemplo de uso da fonte:

graph indexer actions get all

graph indexer actions get --status queued

graph indexer actions queue allocate QmeqJ6hsdyk9dVbo1tvRgAxWrVS3rkERiEMsxzPShKLco6 5000

graph indexer actions queue reallocate QmeqJ6hsdyk9dVbo1tvRgAxWrVS3rkERiEMsxzPShKLco6 0x4a58d33e27d3acbaecc92c15101fbc82f47c2ae5 55000

graph indexer actions queue unallocate QmeqJ6hsdyk9dVbo1tvRgAxWrVS3rkERiEMsxzPShKLco6 0x4a58d33e27d3acbaecc92c15101fbc82f47c2ae

graph indexer actions cancel

graph indexer actions approve 1 3 5

graph indexer actions execute approve

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

• Allocate — aloca stakes a um lançamento de subgraph específico

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

• Unallocate — fecha uma alocação, liberando o stake para ser realocado 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 o mesmo lançamento 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 que o graph-node providencia)

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.

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. Globais também podem ser configurados e substituídos por valores temporários em uma expressão.

Exemplo de modelo de custo:

# Esta declaração captura o valor de pulo,
# usa uma expressão boolean no predicado para corresponder a consultas específicas que usam 'skip'
# e uma expressão de custo para calcular o custo baseado no valor 'skip' e no global SYSTEM_LOAD
SYSTEM_LOAD global
query { pairs(skip: $skip) { id } } when $skip > 2000 => 0.0001 * $skip * $SYSTEM_LOAD;

# Este padrão corresponderá a qualquer expressão GraphQL.
# Ele usa um Global substituído na expressão para calcular o custo
default => 0.1 * $SYSTEM_LOAD;

Exemplo de custo de query usando o modelo acima:

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.

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

Os primeiros passos para participar 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.

1. Abra o app Remix em um navegador

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

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 de ambiente Injected Web3, e sob Account, 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).

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 de ambiente Injected Web3, e sob Account, 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) 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 atualizando 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.

setDelegationParameters(950000, 600000, 500)

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.

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 selecione a mainnet. Nota: Será necessário repetir este processo para o Arbitrum One.
3. Conecte a sua carteira 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.

Após criada por um Indexador, uma alocação sadia passa por quatro 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 um lançamento de subgraph, que lhe permite resgatar recompensas de indexação e servir queries para aquele lançamento de subgraph. O agente indexador cria alocações baseada 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 lançamentos 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.