Kueri State EVM Historis dalam Jendela yang Didukung

eth_call historis bergantung pada jendela state chain, bukan batas rentang blok eth_getLogs. Periksa jendela state, mode autentikasi endpoint, dan blok tujuan sebelum membaca nilai kontrak sebelumnya.

Tiga batas historis yang berbeda

Batas ini menggunakan satuan blok, bukan hari. Jendela state null atau yang tidak dinyatakan tidak memastikan cakupan arsip. Ketersediaan metode tanpa API key terpisah dari ketersediaan metode terautentikasi: rentang log saja tidak mengaktifkan eth_getLogs publik.

Bandingkan jendela state per chain

Tabel menampilkan jendela state yang dipublikasikan, riwayat tanpa API key, rentang log, dan dataset Data API yang dinyatakan dari snapshot publik. Untuk permintaan saat ini, baca kembali GET /v1/chains dan GET /v1/status.

Pengembang dan agen AI harus memeriksa jendela status dan rentang kueri log secara terpisah. Jendela status null tidak menetapkan cakupan arsip. Riwayat publik hanya berlaku untuk metode publik yang dideklarasikan.

GET /v1/chains · Diambil sampel (UTC): 2026-10-09

GET /v1/status · Diambil sampel (UTC): 2026-10-09

Pilih tag blok

Gunakan latest untuk nilai saat ini. Untuk perbandingan historis, baca eth_blockNumber sekali dan konversikan nomor blok yang dipilih ke kuantitas heksadesimal seperti 0x18efa2f. Pertahankan nomor tersebut untuk setiap panggilan dalam perbandingan; panggilan latest berulang dapat menggunakan blok berbeda.

Untuk pembacaan state, earliest, safe, dan finalized mengembalikan -32011 berdasarkan kebijakan jendela state. Pilih nomor blok eksplisit dalam jendela yang dinyatakan. Bentuk hash blok bukan cara memperoleh riwayat tambahan: pembacaan state tanpa API key menolaknya, dan permintaan terautentikasi tetap bergantung pada state yang tersedia.

Nomor blok dapat merujuk ke blok berbeda setelah reorganisasi. Catat hash blok dengan eth_getBlockByNumber jika perlu mengidentifikasi blok hasilnya. Nomor dalam jendela juga memerlukan chain yang tersinkronisasi dan kontrak yang sudah ada pada tinggi tersebut.

Pembacaan kontrak pada blok tetap

Di Ethereum, WETH pada 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 menyediakan decimals() dengan selector 0x313ce567. Panggilan tanpa API key yang diambil sampelnya pada 2026-10-08 (UTC) di blok 0x18efa2f mengembalikan HTTP 200 dengan hasil berikut:

Permintaan ke public.url chain:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "eth_call",
  "params": [
    { "to": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "data": "0x313ce567" },
    "0x18efa2f"
  ]
}

Respons:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": "0x0000000000000000000000000000000000000000000000000000000000000012"
}

Bilangan bulat yang dikodekan ABI adalah 18. Hasilnya merupakan nilai decimals, bukan saldo, dan tidak memastikan ketersediaan pada tinggi lain. Blok tetap tersebut akan keluar dari jendela berbatas seiring waktu; gunakan blok terbaru saat menjalankan contoh berikut di kemudian hari.

Simpan contoh sebagai historical-state.mjs dan jalankan node historical-state.mjs dengan Node.js 24 atau lebih baru dan variabel lingkungan BLOCKVECTRA_API_KEY diatur. Contoh menggunakan endpoint terautentikasi, mempertahankan kontrak dan calldata yang sama, serta membandingkan latest, satu blok tetap terbaru, dan blok di luar jendela terautentikasi yang dipublikasikan. Setiap keluaran menyertakan status HTTP dan body JSON-RPC nyata; HTTP 200 tetap dapat berisi error. Contoh berhenti pada respons yang tidak diharapkan alih-alih menganggapnya sebagai pembacaan berhasil.

const key = process.env.BLOCKVECTRA_API_KEY;
if (!key) throw new Error('Set BLOCKVECTRA_API_KEY');
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 === 'eth_mainnet');
const matches = (method, pattern) => pattern.endsWith('*')
  ? method.startsWith(pattern.slice(0, -1)) : method === pattern;
if (!chain?.jsonrpc || !['eth_call', 'eth_blockNumber'].every(method =>
  chain.methods?.allow?.some(pattern => matches(method, pattern)) &&
  !chain.methods?.deny?.some(pattern => matches(method, pattern)))) {
  throw new Error('Required methods are unavailable');
}
const window = chain.state_window_blocks;
if (!Number.isSafeInteger(window) || window < 10) {
  throw new Error('This example needs a declared state window of at least 10 blocks');
}
const rpcUrl = new URL('./eth_mainnet', chainsUrl).href;
let id = 0;
async function rpc(method, params) {
  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: ++id, method, params }),
  });
  return { http: response.status, body: await response.json() };
}
const headResponse = await rpc('eth_blockNumber', []);
if (headResponse.http !== 200 || headResponse.body.error ||
    !/^0x[0-9a-f]+$/i.test(headResponse.body.result ?? '')) {
  throw new Error(`Cannot read head: ${JSON.stringify(headResponse)}`);
}
const head = BigInt(headResponse.body.result);
if (head <= BigInt(window)) throw new Error('Head is too low for an out-of-window block');
const hex = value => `0x${value.toString(16)}`;
const fixedBlock = hex(head - 10n);
const outsideBlock = hex(head - BigInt(window) - 1n);
const call = { to: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', data: '0x313ce567' };
for (const block of ['latest', fixedBlock, outsideBlock]) {
  const reply = await rpc('eth_call', [call, block]);
  console.log(JSON.stringify({ head: hex(head), block, ...reply }));
  if (block === outsideBlock) {
    if (reply.http !== 200 || reply.body.error?.code !== -32011 ||
        reply.body.error?.data?.reason !== 'state_window') {
      throw new Error('Expected state_window; inspect the actual response above');
    }
  } else if (reply.http !== 200 || reply.body.error ||
      reply.body.result !== '0x0000000000000000000000000000000000000000000000000000000000000012') {
    throw new Error('Expected the WETH decimals result; inspect the actual response above');
  }
}

Respons yang dicatat di atas menggunakan public.url; skrip menggunakan API key. Untuk pembacaan tanpa API key, ambil URL langsung dari public.url, hilangkan API key, dan pilih blok dalam public.history_blocks serta jendela state. Mengubah autentikasi dapat mengubah riwayat yang diizinkan, bahkan untuk kontrak dan calldata yang sama.

Diagnosis error di luar jendela

Pada endpoint tanpa API key yang sama, panggilan yang diambil sampelnya pada 2026-10-08 (UTC) dengan hanya mengubah blok tujuan menjadi 0x18ef650 (dan ID permintaan) mengembalikan HTTP 200 dengan error.code: -32011, error.data.reason: state_window, dan error.data.retryable: false. Pesannya adalah block reference is outside the public history window. Ini kegagalan riwayat publik; endpoint terautentikasi memiliki jendela state sendiri.

Gunakan bidang berikut dari entri error state_window untuk mengenali kegagalan, alih-alih mengandalkan angka jendela tertentu dalam pesan:

Pilih blok bernomor yang lebih baru atau gunakan latest jika tugas memerlukan nilai saat ini. Mengurangi rentang eth_getLogs tidak memulihkan state eth_call historis. Alasan -32011 lain membutuhkan tindakan berbeda: range_not_indexed memerlukan rentang yang tercakup; history_not_ready mengizinkan percobaan ulang setelah pengindeksan menyusul. Periksa error.data.reason, bukan hanya kode numeriknya.

State dasar juga dapat tidak tersedia dengan -32000, atau riwayat blok yang dipangkas dengan 4444; lihat katalog error. Jangan mencoba ulang blok lama tanpa perubahan atau menganggap jendela yang dinyatakan lebih besar menjamin setiap respons.

Pilih kueri berikutnya

Untuk daftar pemeriksaan beban kerja lengkap dan pengujian mandiri, mulai dengan Cara memilih penyedia RPC.

Saat memilih penyedia untuk pembacaan kontrak berulang, bandingkan anggaran harian dan siklus untuk pembacaan EVM. Periksa blok historis yang diperlukan terlebih dahulu, lalu rencanakan distribusi harian dan throughput tugas; sesuai dengan anggaran kredit tidak memastikan cakupan state.

Saat membandingkan penyedia untuk pembacaan historis, pastikan terlebih dahulu keduanya dapat melayani blok tujuan. Perbandingan penggunaan berlebih untuk permintaan lengkap membandingkan harga RU tambahan dengan biaya berbasis metode, memisahkan kuota yang disertakan dari penggunaan tambahan, dan menjelaskan kelas penagihan full versus archive.

Untuk blok terindeks sebelumnya, transaksi, transfer, atau dataset lain, periksa dataset Data API yang dinyatakan dalam tabel dan referensi Data API. Catatan terindeks tidak menyediakan eksekusi kontrak historis sebarang atau menyiratkan bahwa setiap chain memiliki saldo historis.

• Referensi metode eth_call untuk parameter panggilan dan pengodean hasil.
• Rentang blok eth_getLogs dan kueri bertahap untuk riwayat log peristiwa.
• Konfigurasi RPC kustom dompet untuk koneksi dompet dan API key khusus.
• Chain yang didukung untuk ketersediaan jaringan dan harga CU untuk biaya metode.