Limite de plage de blocs eth_getLogs et requêtes découpées

Réponse directe

Une seule requête eth_getLogs est limitée à la valeur max_logs_block_range de la chaîne cible issue de GET /v1/chains (pour HyperEVM, 1,000 blocs), en comptant toBlock − fromBlock + 1 blocs. Tout dépassement renvoie HTTP 200, le code JSON-RPC -32602 et error.data.reason: logs_range_too_large, avec retryable: false (consultez le catalogue des erreurs). Découpez l'intervalle en [from, min(from + max − 1, end)] et avancez jusqu'à la fin du segment précédent plus un après chaque succès.

• Première étape : Exécutez curl -s "https://api.blockvectra.com/v1/chains" et lisez max_logs_block_range, methods.allow et methods.deny de la chaîne cible.
• Terminé quand : logs-minimal.mjs affiche les champs fromBlock, toBlock et le tableau result de chaque segment complété jusqu'au TO_BLOCK choisi, sans erreur HTTP ni JSON-RPC.

Paramètres de chaîne et options d'accès.

Enregistrez ceci sous le nom logs-minimal.mjs, définissez BLOCKVECTRA_API_KEY, l'adresse du contrat LOG_ADDRESS, ainsi qu'une fenêtre de blocs confirmée dans FROM_BLOCK et TO_BLOCK, puis exécutez node logs-minimal.mjs avec Node.js 24 ou une version ultérieure. Sélectionnez une chaîne avec CHAIN ; la valeur par défaut est 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;
}

Chaque ligne de sortie correspond à un segment terminé. Toute erreur HTTP ou JSON-RPC interrompt l'exemple sans ignorer le segment en échec. Consultez les conseils ci-dessous sur les requêtes groupées et la limitation de débit pour la gestion du code 429.

Limites de plage de blocs eth_getLogs

Lors de l'appel de la méthode JSON-RPC eth_getLogs, l'étendue de blocs d'une seule requête est calculée selon la formule toBlock − fromBlock + 1 et ne peut pas dépasser la valeur max_logs_block_range publiée pour la chaîne cible.

Cette limite varie selon la chaîne. Les paramètres par chaîne sont publiés via l'endpoint public GET /v1/chains (les chaînes sont répertoriées sur la page Chaînes prises en charge). Cet endpoint n'est ni authentifié ni facturé. Lors du développement d'applications clientes, interrogez cet endpoint dynamiquement au moment de l'exécution plutôt que de coder en dur les limites de plage de blocs dans votre code.

Les champs de filtre fromBlock et toBlock prennent la valeur par défaut latest lorsqu'ils sont omis ou définis sur null.

Limites eth_getLogs par chaîne

Voici les valeurs max_logs_block_range de chaque chaîne publiées par GET /v1/chains. « Non publié » ne signifie pas illimité. Vérifiez également methods.allow et methods.deny avant tout appel, le refus prévalant sur l'autorisation ; une limite d'étendue de blocs est distincte des limites portant sur le nombre de résultats ou la durée de la requête.

Messages d'erreur courants, textuels

Distinguez l'étendue de blocs, le nombre de résultats et la durée de la requête : un même code JSON-RPC peut décrire des défaillances différentes.

Dans ces modèles de message, <N> est remplacé par la limite de l'endpoint. Les messages tiers font référence à leurs propres endpoints et limites ; la formulation peut varier selon la version du client. Pour BlockVectra, utilisez /v1/chains et error.data.reason.

Dépassement de la limite d'étendue de blocs

Lorsqu'une seule requête a une étendue de blocs toBlock − fromBlock + 1 qui dépasse le max_logs_block_range de la chaîne, la requête est rejetée avec HTTP 200 et une erreur JSON-RPC :

• Code d'erreur : -32602
• Message d'erreur : eth_getLogs block range too large: max <N> blocks
• Statut de facturation : Non facturé.

Exemple de requête

Cette requête ne dépasse la limite que si son étendue de blocs est supérieure au max_logs_block_range actuel de la chaîne cible :

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

Exemple de réponse

L'exemple de réponse d'erreur correspondant :

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

Où <N> est le max_logs_block_range de la chaîne cible (publié via GET /v1/chains).

Dans une requête par lot contenant plusieurs appels, si un appel eth_getLogs dépasse la limite d'étendue de blocs, cet élément précis renvoie l'erreur -32602 ci-dessus et n'est pas facturé.

Exécution de requêtes découpées en segments

Pour interroger des logs sur un large intervalle de blocs, interrogez d'abord le max_logs_block_range de la chaîne cible, divisez l'intervalle cible en segments contigus de [from, from + max - 1], puis envoyez des requêtes séquentielles tout en agrégeant les résultats.

Les exemples suivants utilisent robinhood_mainnet pour illustrer les requêtes découpées en segments :

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"
    }]
  }'

Considérations relatives aux requêtes groupées

Si vous envisagez de regrouper plusieurs requêtes découpées dans une seule requête par lot JSON-RPC, gardez à l'esprit les règles relatives aux lots et à la capacité de burst :

• Limite de taille de lot : Les requêtes par lot acceptent de 1 à 100 appels. L'envoi de plus de 100 appels est rejeté avec HTTP 200 et le code d'erreur -32600 batch too large: max 100 calls (non facturé).
• Capacité de burst d'une requête unique : Si le total des poids en CU des appels d'une requête dépasse la capacité de burst de la clé (burst_cu), la requête est rejetée avec HTTP 429 -32022 request cost <N> CU exceeds burst capacity <M> CU (non facturé) ; découpez-la en lots plus petits.
• Capacité de bucket insuffisante : Si la somme des poids totaux ne dépasse pas la capacité de burst mais que le bucket de jetons ne dispose pas d'une capacité suffisante, le service renvoie HTTP 429 avec le code d'erreur -32005 rate limit exceeded et un en-tête Retry-After ; consultez Ce qui n'est pas facturé : codes d'erreur et règles de facturation pour les détails sur les nouvelles tentatives et la facturation.

Par conséquent, lors de l'exécution de requêtes de logs à grande échelle, des requêtes séquentielles découpées en segments sont recommandées ; si vous effectuez des regroupements par lot, conservez un nombre d'appels par lot suffisamment faible pour que la somme des poids totaux reste dans la capacité de burst.

Guides connexes et règles de facturation

• Consultez la référence de la méthode eth_getLogs pour les paramètres de filtre, les valeurs de retour et les poids en CU.
• Consultez la référence de l'erreur logs_range_too_large pour le détail des erreurs et les actions recommandées.
• Pour une comparaison entre eth_getLogs et les endpoints de transferts de la Data API (transferts d'adresses et transferts de jetons), y compris les différences de couverture et de finalité, consultez Données de nœud récentes vs historique indexé : quand utiliser eth_getLogs et quand utiliser l'API des transferts.
• Pour des détails complets sur les Compute Units (CU), le règlement horaire et les réponses d'erreur non facturées, consultez Ce qui n'est pas facturé : codes d'erreur et règles de facturation.

Prochaines étapes

• Parcourir le catalogue des jeux de données pour découvrir chaque jeu de données indexé par BlockVectra.
• Consulter le forfait gratuit et les tarifs pour vérifier ce que comprend votre compte.
• Se connecter à la console pour créer une API key.