Limite de intervalo de blocos do eth_getLogs e consultas em partes

Resposta direta

Uma requisição eth_getLogs é limitada pelo max_logs_block_range da rede de destino em GET /v1/chains (para HyperEVM, 1,000 blocos), contando toBlock − fromBlock + 1 blocos. Ultrapassar esse limite retorna HTTP 200, JSON-RPC -32602 e error.data.reason: logs_range_too_large, com retryable: false (consulte o catálogo de erros). Divida o intervalo em [from, min(from + max − 1, end)] e avance para o fim da parte anterior mais um após o sucesso.

Salve como logs-minimal.mjs, defina BLOCKVECTRA_API_KEY, o endereço do contrato LOG_ADDRESS e uma janela de blocos confirmados em FROM_BLOCK e TO_BLOCK, depois execute node logs-minimal.mjs com Node.js 24 ou posterior. Selecione uma rede com CHAIN; o padrão é robinhood_mainnet.

const { BLOCKVECTRA_API_KEY: key, LOG_ADDRESS: address, FROM_BLOCK, TO_BLOCK } = process.env;
if (!key || !/^0x[0-9a-f]{40}$/i.test(address ?? '')) throw new Error('Set BLOCKVECTRA_API_KEY and LOG_ADDRESS');
if (![FROM_BLOCK, TO_BLOCK].every(value => /^(0x[0-9a-f]+|[0-9]+)$/i.test(value ?? ''))) {
  throw new Error('Set FROM_BLOCK and TO_BLOCK to nonnegative block numbers');
}
const start = BigInt(FROM_BLOCK), end = BigInt(TO_BLOCK);
if (start > end) throw new Error('FROM_BLOCK must not exceed TO_BLOCK');
const chainSlug = process.env.CHAIN ?? 'robinhood_mainnet';
const chainsUrl = 'https://api.blockvectra.com/v1/chains';
const catalogResponse = await fetch(chainsUrl, { signal: AbortSignal.timeout(15_000) });
if (!catalogResponse.ok) throw new Error(`Chains HTTP ${catalogResponse.status}`);
const catalog = await catalogResponse.json();
const chain = catalog.chains.find(item => item.chain === chainSlug);
if (!chain || !Number.isSafeInteger(chain.max_logs_block_range) || chain.max_logs_block_range <= 0) {
  throw new Error('Missing or invalid max_logs_block_range');
}
const matches = pattern => pattern.endsWith('*') ? 'eth_getLogs'.startsWith(pattern.slice(0, -1)) : pattern === 'eth_getLogs';
if (!chain.methods?.allow?.some(matches) || chain.methods?.deny?.some(matches)) {
  throw new Error('eth_getLogs is unavailable on this chain');
}
const max = BigInt(chain.max_logs_block_range);
const rpcUrl = new URL(`./${chainSlug}`, chainsUrl).href;
const hex = value => `0x${value.toString(16)}`;
for (let from = start; from <= end;) {
  const to = from + max - 1n < end ? from + max - 1n : end;
  const response = await fetch(rpcUrl, {
    method: 'POST', redirect: 'error', signal: AbortSignal.timeout(15_000),
    headers: { 'Content-Type': 'application/json', 'x-api-key': key },
    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'eth_getLogs',
      params: [{ address, fromBlock: hex(from), toBlock: hex(to) }] }),
  });
  const body = await response.json();
  if (!response.ok || body.error || !Array.isArray(body.result)) {
    throw new Error(`RPC HTTP ${response.status}: ${JSON.stringify(body.error ?? 'Invalid result')}`);
  }
  console.log(JSON.stringify({ fromBlock: hex(from), toBlock: hex(to), result: body.result }));
  from = to + 1n;
}

Cada linha de saída é uma parte concluída. Qualquer erro HTTP ou JSON-RPC interrompe o exemplo sem pular a parte com falha. Consulte abaixo as orientações de lotes e limites de taxa para tratar 429.

Limites de intervalo de blocos do eth_getLogs

Ao chamar o método JSON-RPC eth_getLogs, o intervalo de blocos de uma requisição é calculado como toBlock − fromBlock + 1 e não pode ultrapassar o max_logs_block_range publicado da rede de destino.

Esse limite varia por rede. Os parâmetros por rede são publicados pelo endpoint público GET /v1/chains (as redes estão listadas em Redes compatíveis). Esse endpoint não exige autenticação e não é cobrado. Ao desenvolver aplicações cliente, consulte esse endpoint dinamicamente em tempo de execução, em vez de fixar os limites de intervalo de blocos no código.

Os campos de filtro fromBlock e toBlock usam latest como padrão quando omitidos ou null.

Limites do eth_getLogs por rede

Estes são os valores max_logs_block_range de cada rede publicados por GET /v1/chains. "Não publicado" não significa ilimitado. Verifique também methods.allow e methods.deny antes de chamar, com deny tendo precedência; o limite de intervalo de blocos é separado dos limites de quantidade de resultados ou duração da consulta.

Mensagens de erro comuns, na íntegra

Diferencie intervalo de blocos, quantidade de resultados e duração da consulta: o mesmo código JSON-RPC pode descrever falhas diferentes.

Nesses templates de mensagem, <N> é substituído pelo limite do endpoint. Mensagens de terceiros se referem aos próprios endpoints e limites; o texto pode variar conforme a versão do cliente. Para BlockVectra, use /v1/chains e error.data.reason.

Ultrapassar o limite de intervalo de blocos

Quando o intervalo de blocos toBlock − fromBlock + 1 de uma requisição ultrapassa o max_logs_block_range da rede, a requisição é rejeitada com HTTP 200 e um erro JSON-RPC:

• Código de erro: -32602
• Mensagem de erro: eth_getLogs block range too large: max <N> blocks
• Status de cobrança: sem cobrança.

Exemplo de requisição

Esta requisição ultrapassa o limite apenas se seu intervalo de blocos for maior que o max_logs_block_range atual da rede de destino:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getLogs",
  "params": [
    {
      "fromBlock": "0x45a2409",
      "toBlock": "0x45a27f1"
    }
  ]
}

Exemplo de resposta

Exemplo da resposta de erro correspondente:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "eth_getLogs block range too large: max <N> blocks"
  }
}

Onde <N> é o max_logs_block_range da rede de destino (publicado por GET /v1/chains).

Em uma requisição em lote com várias chamadas, se uma chamada eth_getLogs ultrapassar o limite de intervalo de blocos, esse item específico retorna o erro -32602 acima e não é cobrado.

Fazer consultas em partes

Para consultar logs em um intervalo amplo de blocos, primeiro consulte o max_logs_block_range da rede de destino, divida o intervalo em partes contíguas de [from, from + max - 1] e envie requisições sequenciais agregando os resultados.

Os exemplos abaixo usam robinhood_mainnet para demonstrar consultas em partes:

export BLOCKVECTRA_API_KEY="rgw_your_api_key"

# 1. Read max_logs_block_range from the public chains endpoint (unauthenticated, unbilled)
curl -s "https://api.blockvectra.com/v1/chains"

# 2. Make a single compliant request within the chain's max_logs_block_range (toBlock - fromBlock + 1)
curl -s "https://api.blockvectra.com/v1/robinhood_mainnet" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_getLogs",
    "params": [{
      "address": "0x1111111111111111111111111111111111111111",
      "fromBlock": "0x45a2409",
      "toBlock": "0x45a246c"
    }]
  }'

Considerações sobre requisições em lote

Se considerar agrupar várias consultas em partes em uma única requisição JSON-RPC em lote, observe as regras de lote e capacidade de burst:

• Limite de tamanho do lote: requisições em lote aceitam de 1 a 100 chamadas. Enviar mais de 100 chamadas é rejeitado com HTTP 200 e código de erro -32600 batch too large: max 100 calls (sem cobrança).
• Capacidade de burst por requisição: se a soma dos pesos de CU das chamadas em uma requisição ultrapassar a capacidade de burst da API key (burst_cu), a requisição é rejeitada com HTTP 429 -32022 request cost <N> CU exceeds burst capacity <M> CU (sem cobrança); divida-a em lotes menores.
• Capacidade insuficiente no bucket: se a soma dos pesos completos não ultrapassar a capacidade de burst, mas o token bucket não tiver capacidade disponível suficiente, o serviço retorna HTTP 429 com código de erro -32005 rate limit exceeded e Retry-After; consulte O que não é cobrado: códigos de erro e regras de cobrança para detalhes de novas tentativas e cobrança.

Portanto, para consultas de logs em grande escala, recomenda-se consultar as partes sequencialmente; se usar lotes, mantenha a quantidade de chamadas por lote pequena o suficiente para que a soma dos pesos completos permaneça dentro da capacidade de burst.

Guias relacionados e regras de cobrança

• Consulte a referência do método eth_getLogs para parâmetros de filtro, valores de retorno e pesos de CU.
• Consulte a referência do erro logs_range_too_large para detalhes do erro e ações recomendadas.
• Para comparar eth_getLogs com os endpoints de transferências da Data API (transferências de endereços e de tokens), incluindo diferenças de cobertura e finalidade, consulte Dados recentes do nó e histórico indexado: quando usar eth_getLogs e quando usar a API de transferências.
• Para detalhes completos sobre unidades de computação (CU), liquidação por hora e respostas de erro sem cobrança, consulte O que não é cobrado: códigos de erro e regras de cobrança.

Próximos passos

• Explore o diretório de conjuntos de dados para ver todos os conjuntos de dados indexados pela BlockVectra.
• Consulte o plano gratuito e os preços para verificar o que sua conta inclui.
• Entre no console para criar uma API key.