eth_getLogs-Blockbereichslimit und segmentierte Abfragen

Direkte Antwort

Eine einzelne eth_getLogs-Anfrage ist auf max_logs_block_range der Ziel-Chain aus GET /v1/chains begrenzt (für HyperEVM, 1,000 Blöcke), gezählt als toBlock − fromBlock + 1 Blöcke. Ein Überschreiten gibt HTTP 200, JSON-RPC -32602 und error.data.reason: logs_range_too_large mit retryable: false zurück (siehe den Fehlerkatalog). Teilen Sie das Intervall in [from, min(from + max − 1, end)] auf und rücken Sie nach erfolgreichem Abschluss auf das Ende des vorherigen Segments plus eins vor.

• Erster Schritt: Führen Sie curl -s "https://api.blockvectra.com/v1/chains" aus und lesen Sie max_logs_block_range, methods.allow und methods.deny der Ziel-Chain aus.
• Abgeschlossen, wenn: logs-minimal.mjs für jedes abgeschlossene Segment fromBlock, toBlock und das result-Array bis zu Ihrem gewählten TO_BLOCK ohne HTTP- oder JSON-RPC-Fehler ausgibt.

Chain-Parameter und Zugriffsoptionen.

Speichern Sie dies als logs-minimal.mjs, setzen Sie BLOCKVECTRA_API_KEY, die Contract-Adresse LOG_ADDRESS und ein bestätigtes Blockfenster in FROM_BLOCK und TO_BLOCK, und führen Sie dann node logs-minimal.mjs mit Node.js 24 oder höher aus. Wählen Sie eine Chain über CHAIN; Standard ist 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;
}

Jede Ausgabezeile entspricht einem abgeschlossenen Segment (Chunk). Jeder HTTP- oder JSON-RPC-Fehler stoppt das Beispiel, ohne das fehlgeschlagene Segment zu überspringen. Hinweise zum Umgang mit 429 finden Sie unten im Abschnitt zu Batches und Ratenbegrenzungen.

eth_getLogs-Blockbereichslimits

Beim Aufruf der JSON-RPC-Methode eth_getLogs wird die Blockspanne einer einzelnen Anfrage als toBlock − fromBlock + 1 berechnet und darf den veröffentlichten max_logs_block_range der Ziel-Chain nicht überschreiten.

Dieses Limit variiert je nach Chain. Parameter pro Chain werden über den öffentlichen Endpunkt GET /v1/chains veröffentlicht (Chains sind unter Unterstützte Chains aufgeführt). Dieser Endpunkt erfordert keine Authentifizierung und wird nicht abgerechnet. Fragen Sie diesen Endpunkt bei der Entwicklung von Client-Anwendungen dynamisch zur Laufzeit ab, anstatt Blockbereichslimits fest im Code zu hinterlegen.

Die Filterfelder fromBlock und toBlock fallen standardmäßig auf latest zurück, wenn sie weggelassen werden oder null sind.

eth_getLogs-Limits nach Chain

Dies sind die von GET /v1/chains veröffentlichten max_logs_block_range-Werte der einzelnen Chains. „Nicht veröffentlicht“ bedeutet nicht unbegrenzt. Prüfen Sie vor dem Aufruf auch methods.allow und methods.deny, wobei deny Vorrang hat; ein Blockspannenlimit ist unabhängig von Limits für die Ergebnisanzahl oder Abfragedauer.

Häufige Fehlermeldungen im Wortlaut

Unterscheiden Sie Blockspanne, Ergebnisanzahl und Abfragedauer: Derselbe JSON-RPC-Code kann unterschiedliche Fehler beschreiben.

In diesen Nachrichtenvorlagen wird <N> durch das Limit des Endpunkts ersetzt. Meldungen von Drittanbietern beziehen sich auf deren eigene Endpunkte und Limits; die Formulierung kann je nach Client-Version variieren. Verwenden Sie für BlockVectra /v1/chains und error.data.reason.

Überschreiten des Blockspannenlimits

Wenn die Blockspanne toBlock − fromBlock + 1 einer einzelnen Anfrage den max_logs_block_range der Chain überschreitet, wird die Anfrage mit HTTP 200 und einem JSON-RPC-Fehler abgelehnt:

• Fehlercode: -32602
• Fehlermeldung: eth_getLogs block range too large: max <N> blocks
• Abrechnungsstatus: Nicht abgerechnet.

Beispielanfrage

Diese Anfrage überschreitet das Limit nur, wenn ihre Blockspanne größer als der aktuelle max_logs_block_range der Ziel-Chain ist:

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

Beispielantwort

Das entsprechende Beispiel einer Fehlerantwort:

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

Wobei <N> dem max_logs_block_range der Ziel-Chain entspricht (veröffentlicht über GET /v1/chains).

In einer Batch-Anfrage, die mehrere Aufrufe enthält, gibt ein eth_getLogs-Aufruf, der das Blockspannenlimit überschreitet, den obigen Fehler -32602 zurück und wird nicht abgerechnet.

Segmentierte Abfragen durchführen

Um Logs über ein großes Blockintervall abzufragen, ermitteln Sie zunächst den max_logs_block_range der Ziel-Chain, unterteilen Sie das Zielintervall in zusammenhängende Segmente von [from, from + max - 1] und senden Sie sequenzielle Anfragen, während Sie die Ergebnisse aggregieren.

Die folgenden Beispiele verwenden robinhood_mainnet, um segmentierte Abfragen zu demonstrieren:

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

Überlegungen zu Batch-Anfragen

Falls Sie erwägen, mehrere segmentierte Abfragen in einer einzigen JSON-RPC-Batch-Anfrage zusammenzufassen, beachten Sie die Regeln für Batch- und Burst-Kapazität:

• Batch-Größenlimit: Batch-Anfragen akzeptieren 1 bis 100 Aufrufe. Das Einreichen von mehr als 100 Aufrufen wird mit HTTP 200 und Fehlercode -32600 batch too large: max 100 calls abgewiesen (nicht abgerechnet).
• Burst-Kapazität einer einzelnen Anfrage: Wenn das summierte CU-Gewicht der Aufrufe in einer Anfrage die Burst-Kapazität des Keys (burst_cu) überschreitet, wird die Anfrage mit HTTP 429 -32022 request cost <N> CU exceeds burst capacity <M> CU abgelehnt (nicht abgerechnet); teilen Sie sie in kleinere Batches auf.
• Unzureichende Bucket-Kapazität: Wenn die Summe der vollen Gewichte die Burst-Kapazität nicht überschreitet, der Token-Bucket jedoch nicht über genügend freie Kapazität verfügt, gibt der Dienst HTTP 429 mit Fehlercode -32005 rate limit exceeded und Retry-After zurück; siehe Was nicht abgerechnet wird: Fehlercodes und Abrechnungsregeln für Details zu Wiederholungen und Abrechnung.

Daher werden bei umfangreichen Log-Abfragen sequenzielle segmentierte Abfragen empfohlen; falls Sie Batches nutzen, halten Sie die Anzahl der Aufrufe pro Batch so klein, dass die Summe der vollen Gewichte innerhalb der Burst-Kapazität bleibt.

Verwandte Leitfäden und Abrechnungsregeln

• Siehe die eth_getLogs-Methodenreferenz für Filterparameter, Rückgabewerte und CU-Gewichte.
• Siehe die logs_range_too_large-Fehlerreferenz für Fehlerdetails und empfohlene Maßnahmen.
• Für einen Vergleich zwischen eth_getLogs und den Transfers-Endpunkten der Data API (Adresstransfers und Token-Transfers), einschließlich Unterschieden bei Abdeckung und Finalität, siehe Aktuelle Node-Daten vs. indexierter Verlauf: Wann eth_getLogs und wann die Transfers-API verwendet werden sollte.
• Ausführliche Informationen zu Compute Units (CU), stündlicher Abrechnung und nicht berechneten Fehlerantworten finden Sie unter Was nicht abgerechnet wird: Fehlercodes und Abrechnungsregeln.

Nächste Schritte

• Datensatzverzeichnis durchsuchen, um alle von BlockVectra indexierten Datensätze zu sehen.
• Kostenlosen Tarif und Preise ansehen, um zu prüfen, was Ihr Konto beinhaltet.
• In der Konsole anmelden, um einen API key zu erstellen.