DEV Community: BlockVectra

Resumable eth_getLogs scans: fixed chunks, saved checkpoints, safe restarts

BlockVectra — Wed, 21 Oct 2026 10:25:58 +0000

A rate limit, malformed response, or process restart can interrupt a log scan after successful chunks. The useful question then is not "how do I re-run the query?" but "which blocks are already saved, and where does the next request begin?"

The first response is not a saved checkpoint

A returned eth_getLogs result is only candidate data. The client advances to the next block only after two things happen in order: the HTTP status and JSON-RPC envelope pass validation (jsonrpc, id, no error, and result is an array), and a new checkpoint containing that chunk has been committed to disk. A successful empty array is valid. If either validation or the commit fails, the run stops at that chunk. It does not shrink the range, retry, skip ahead, swap checkpoint files, or open a new task.

Run a fixed window

Use Node.js 24 or later. Download the client example first.

Pick a chain, address, and inclusive fromBlock/toBlock that you have confirmed and that the node currently serves.

# Supply BLOCKVECTRA_API_KEY through your secret manager/environment.
export CHAIN="<confirmed-chain-slug>"
export LOG_ADDRESS="<confirmed-address>"
export FROM_BLOCK="<confirmed-start-block>"
export TO_BLOCK="<confirmed-end-block>"
export CHECKPOINT_FILE="./getlogs-checkpoint.json"
# optional: export CHUNK_BLOCKS=100
node getlogs-resumable.mjs

Replace every placeholder with your own confirmed values. BLOCKVECTRA_API_KEY is read from your own environment; the client does not create accounts. CHUNK_BLOCKS is optional and must be a positive decimal integer. Each request spans min(CHUNK_BLOCKS, max_logs_block_range) blocks, where the limit is read live from GET /v1/chains; without CHUNK_BLOCKS, the catalog value is used. Block span, result count, and the 2 MiB response/checkpoint caps are separate limits. The task allows 20 saved chunks, including restored ones.

Stop, then continue the same task

Change nothing in the task identity: same chain, address, and complete window. Keep the same checkpoint file and run again. The client re-validates the checkpoint's task binding, contiguous chunk order, and nextBlock, then requests only blocks not yet saved. You may change CHUNK_BLOCKS on resume; it only affects how the remaining range is split and never re-fetches saved chunks.

One process holds the checkpoint at a time through CHECKPOINT_FILE.lock; if a crash leaves the lock behind, confirm that no process owns it, then remove it manually. Checkpoints are written through a 0600 temporary file, fsync, and an atomic rename. The client does not claim exactly-once behavior across power loss or database commits.

A final complete status means the client read every block in that fixed window successfully. It does not prove that upstream data has no missing logs, that archive data covers the range, or that finality and reorgs are handled. Persist idempotently and verify chain hashes on the consumer side.

The full walkthrough, limits, and recovery rules are in the resumable eth_getLogs guide. You can also download the public client example and check its 35 synthetic response fixtures with a mock transport.

Gasless transactions: separate the signer, gas payer, and token owner

BlockVectra — Wed, 21 Oct 2026 01:28:57 +0000

AI-generated engineering note from BlockVectra.

"Gasless" describes an experience, not a protocol. Before writing any test, name four roles. In a demo they are often one address; in production they usually are not.

Signer: the key that authorizes an action off-chain.
Gas payer: in the direct EOA-relaying model used for this discussion, the transaction-sending EOA that pays native gas. Other sponsorship architectures can separate these roles.
Token owner: the account whose tokens are spent or whose allowance is authorized.
Contract caller: the address the target contract sees as msg.sender.

Many bugs come from treating two of these as one. A contract that reads the caller as the owner works when the owner sends the transaction and breaks when a relayer does.

Two token authorization patterns are useful to distinguish. A signed approval, as in ERC-2612, only changes an allowance; a transfer must still follow. A signed transfer, as in ERC-3009, binds sender, recipient, amount, validity window and nonce into one authorization that a third party can submit. Both need a token or wrapper that implements them, since plain ERC-20 does not. The official ERC-3009 page currently marks it Draft.

Assert roles, not just outcomes

A passing "transfer succeeded" check hides which account paid for what. Assert each role's balance and allowance separately, before and after, and use distinct token-owner/signer, relayer, and recipient addresses so a mix-up cannot pass by accident.

A proposed test matrix

This is a suggested plan, not a record of executed results.

Scenario	Setup	Assert
Zero-native user	Owner holds tokens and no native coin; relayer pays gas	Call succeeds; owner token balance drops by the exact amount
Zero-token sponsor	Relayer holds gas funds but zero tokens	Relayer token balance is zero before and after
Actor binding	Token-owner/signer, relayer, and recipient are distinct	A signed transfer debits the authorized owner and credits the authorized recipient; a permit updates the authorized owner-to-spender allowance without transferring tokens
Authorization lifecycle	Valid, expired, then replayed signature	Valid works once; the others revert and leave state unchanged
Vault accounting	Tokens credited directly to a vault	Deposit counters match what the design says they should mean

One public case

The 16ane repository test, pinned to one commit, has a relayer holding zero mock tANE submit a signed ERC-3009 transfer. The owner's balance falls from 10000 to 8400, the vault holds 1600, and owner principal stays 0, an accepted accounting gap because the deposit method never ran. A second test has the owner sign a permit while the relayer calls the vault's fundWithPermit wrapper. The second test expects an insufficient-allowance revert, because that wrapper treats the caller as the permit owner. That limits the wrapper, not ERC-2612 relaying in general. The tests do not assert that the owner holds zero native coin.

Verifying for real

Read balanceOf and allowance for the caller and the owner separately, and compare receipts and state deltas, one branch at a time. A simulation or a log status is not end-to-end proof. Also scope "atomic" carefully: a reverted transaction can still cost the sponsor gas, so atomicity here means application state is unchanged, not that fees come back.

If you are wiring agents to onchain actions, the BlockVectra agent integration documentation covers the integration side.

Block heights are not a clock: RPC polling on fast EVM chains

BlockVectra — Tue, 20 Oct 2026 21:40:28 +0000

A block count is not a duration. The same block count does not preserve the same elapsed time across chains: a 20-block cooldown that equals roughly 40 seconds at a 2,000 ms nominal block time equals about 2 seconds where nominal block time is 100 ms. Code that stores retry, backoff, or cooldown windows only in blocks therefore changes behavior when block times differ. The morpho-org/morpho-bots issue #4 reports block-denominated backoff and settled cooldown values on a fast chain with roughly 103 ms blocks; that report is the motivation here, not an independent verification.

The table is a hypothetical conversion for a 40-second intent, not a measurement or a promise about any chain's real block rate.

Nominal block time	Blocks = ceil(40,000 ms / block time)	Result
2,000 ms	ceil(20.0)	20
100 ms	ceil(400.0)	400
103 ms	ceil(388.35)	389

Ceiling means rounding up: 389 blocks at 103 ms represent 40,067 ms, not exactly 40,000 ms. At 2,000 ms and 100 ms the division happens to be exact.

Three practical checks:

Poll against an elapsed clock. Keep retry decisions in milliseconds from a monotonic elapsed-time source, then convert only for display or where a block boundary is genuinely required. This does not replace chain-state checks and does not by itself address reorgs, nonces, or finality.
Separate backoff from head and cooldown responsibilities. Backoff answers "when should this attempt run again?" Head lag and settled cooldown answer "what chain state do we trust?" Do not let one block counter own both questions; changing a timer cannot repair a stale read.
Exercise fast, slow, paused, and jumpy clocks. Test with nominal block times below and above the default, with head progression halted, and with irregular jumps. Keep an explicit manual environment override so an operator can pin behavior during an incident instead of editing defaults.

Even with those checks, block conversion remains an approximation. A chain pause, a change in block time, or bursty production makes a block-denominated duration an estimate, not a real-time guarantee. Rounding up reduces undershoot but cannot enforce a deadline.

For provider-selection context, see the BlockVectra RPC provider guide. This is a BlockVectra engineering note and an AI-assisted draft. A different provider does not correct a unit error in application timers.

JSON-RPC batch responses: match by id, not array position

BlockVectra — Tue, 20 Oct 2026 19:48:26 +0000

By BlockVectra, with AI-assisted drafting.

A JSON-RPC batch puts several calls in one request. The reply array is not a positional mirror of the request array. Treating payload[i] as the answer to requests[i] can bind every result to the wrong call while the transport still reports success. Here is a three-response mismatch:

const requests = [
  { jsonrpc: "2.0", id: 7, method: "eth_blockNumber", params: [] },
  { jsonrpc: "2.0", id: 8, method: "eth_getBalance", params: ["0x0000000000000000000000000000000000000000", "latest"] },
  { jsonrpc: "2.0", id: 9, method: "eth_chainId", params: [] },
];

const payload = [
  { jsonrpc: "2.0", id: 9, result: "0x1" },
  { jsonrpc: "2.0", id: 7, error: { code: -32000, message: "busy" } },
  { jsonrpc: "2.0", id: 8, result: "0x0" },
];

requests.forEach((request, index) => {
  const response = payload[index];
  console.log(request.id, response.id);
});
// 7 9
// 8 7
// 9 8

Every request is paired with another request's id. Request 7 is now "answered" by id 9's chain id, request 8 by id 7's error, and request 9 by id 8's balance. If the caller only checks that three responses arrived, the batch looks complete. A downstream parser may then apply an eth_chainId result where an eth_blockNumber result was expected. These are offline synthetic fixtures, not real calls, results, or balances.

The specification permits this: response objects "MAY be returned in any order within the Array." The stable join key is the id carried by both the request and its response. A response's position carries no contract.

HTTP 200 is not batch success

A batch can return HTTP 200 while containing an item-level error. In the example above, the middle entry is an error for id 7; id 9 still has a result. A status-code check sees only transport success. Code that scans for the first non-error entry, or that assumes every array entry is a result, can silently skip the failed call.

The same rule applies to completeness. A missing response, a duplicate response id, or a response id that was never sent means the client cannot confirm a complete batch. A malformed whole batch may be returned as one error object instead of an array. That object cannot be paired with any request, so it should be reported as uncorrelated rather than attached to the first request or copied to all of them.

Each response must carry exactly one of result or error, and an error must be a non-null object with an integer code and a string message. A result is allowed to be false, 0, or null; checking truthiness is not a valid presence test.

A strict correlator

The complete implementation follows. It is dependency-free and can be copied as one module.

const hasOwn = (value, key) => Object.prototype.hasOwnProperty.call(value, key);

const isPositiveSafeInt = (value) => Number.isSafeInteger(value) && value > 0;

function fail(message) {
  throw new Error(`correlateBatch: ${message}`);
}

function assertErrorShape(error, id) {
  if (error === null || typeof error !== "object" || Array.isArray(error)) {
    fail(`request ${id} returned a non-object error`);
  }
  if (!Number.isInteger(error.code) || typeof error.message !== "string") {
    fail(`request ${id} returned a malformed error`);
  }
}

/**
 * Correlate a JSON-RPC 2.0 batch response array with its requests by id.
 * This checks envelope, id, and error shape only, not result semantics.
 */
export function correlateBatch(requests, payload) {
  if (!Array.isArray(requests) || requests.length === 0) {
    fail("requests must be a non-empty array");
  }
  const expected = new Set();
  for (const request of requests) {
    if (request === null || typeof request !== "object" || !hasOwn(request, "id")) {
      fail("every request must be an object with its own id");
    }
    if (!isPositiveSafeInt(request.id) || expected.has(request.id)) {
      fail("request ids must be unique positive safe integers");
    }
    expected.add(request.id);
  }
  if (!Array.isArray(payload) || payload.length === 0) {
    fail("uncorrelated: response payload must be a non-empty array");
  }
  const responses = new Map();
  for (const row of payload) {
    if (row === null || typeof row !== "object" || Array.isArray(row)) {
      fail("every response row must be a non-null object");
    }
    if (row.jsonrpc !== "2.0") {
      fail("every response row must declare jsonrpc 2.0");
    }
    if (!hasOwn(row, "id")) {
      fail("every response row must carry its own id");
    }
    if (!expected.has(row.id)) {
      fail(`unknown response id ${String(row.id)}`);
    }
    if (responses.has(row.id)) {
      fail(`duplicate response id ${row.id}`);
    }
    const hasResult = hasOwn(row, "result");
    const hasError = hasOwn(row, "error");
    if (hasResult === hasError) {
      fail(`request ${row.id} must carry exactly one of result or error`);
    }
    if (hasError) {
      assertErrorShape(row.error, row.id);
    }
    responses.set(row.id, row);
  }
  for (const id of expected) {
    if (!responses.has(id)) {
      fail(`missing response id ${id}`);
    }
  }
  return responses;
}

It first validates the expected ids. It then rejects non-object rows, a wrong jsonrpc version, a missing row id, an unknown id, a duplicate id, and a result/error pair that is not exactly one present. Finally, it checks that every expected id was seen. The returned Map keeps the original response object for each id, so a result or error is not rewritten.

Consume successes, fail on errors

The snippet is application pseudocode. validateForMethod and consume are application-provided; only the correlator above is a complete, copyable module.

import { correlateBatch } from "./batch-response.mjs";

const byId = correlateBatch(requests, payload);

const values = requests.map((request) => {
  const response = byId.get(request.id);
  if (Object.hasOwn(response, "error")) {
    throw new Error(`RPC ${response.error.code}: ${response.error.message}`);
  }
  return validateForMethod(request.method, response.result);
});

for (const value of values) {
  consume(value);
}

Callers should iterate over the requests they sent, look up each response by id, and handle the two branches explicitly. Error entries remain errors. This helper does not turn an RPC error into a successful value, retry it, or advance a checkpoint. The map step validates the whole batch before any consume call, so later errors block earlier consumptions. This is application ordering, not a database transaction or all-or-nothing guarantee; persistence and checkpoint advancement stay with the application. A job that needs retries should make that decision outside the correlator and should only advance a checkpoint after every required call has a validated success.

Do not skip the method-specific step. A syntactically valid result can still be the wrong shape for eth_getLogs, eth_getBalance, or any other method. Envelope validation is not result validation.

Scope and limits

This example is deliberately stricter than the full protocol. It expects non-empty read-only requests whose ids are unique positive safe integers. It does not cover notifications, null ids, string ids, or fractional ids. Those are constraints chosen for this example, not claims that JSON-RPC forbids other id forms. The function checks envelope, id, and error shape only. It does not validate method result semantics, chain or finality, checkpoints, or the whole protocol.

Batch size and concurrency are different budgets. Batch size is how many calls go into one request; concurrency is how many requests are in flight. Lowering one does not automatically lower the other. Joining responses by id fixes correlation; it does not remove a provider's batch limit or concurrency limit.

If you are querying logs over a block range, the BlockVectra getLogs guide is a natural next step: Get logs over a block range.

By BlockVectra, with AI-assisted drafting. The code was run locally with Node's built-in test runner; independent review is not claimed.

Runnable MIT companion and 14 offline checks: code and tests. Download both .mjs files and run node --test batch-response.test.mjs.

Wallet balance APIs: null decimals, pagination, and snapshot time

BlockVectra — Tue, 20 Oct 2026 07:19:14 +0000

Prepared by the BlockVectra AI assistant. This is a contract-based integration note with an offline JavaScript reproduction; it does not report a live wallet integration.

A wallet can receive HTTP 200 and still display the wrong portfolio. Two particularly quiet mistakes are treating unknown token decimals as zero and feeding a paginated response object into a parser that expects an array.

Unknown decimals are different from zero

In BlockVectra’s documented address-balance schema, balance is a decimal integer string. decimals is an integer from 0 through 255, or null; symbol can also be null.

Zero decimals is a known scale. Null means the scale is unknown. JavaScript coercion erases that distinction:

import assert from 'node:assert/strict';

assert.equal(Number(null), 0);
assert.equal(Number('9007199254740993').toString(), '9007199254740992');

const row = { balance: '9007199254740993', decimals: null, symbol: null };
assert.equal(BigInt(row.balance), 9007199254740993n);
assert.equal(row.decimals, null);
assert.notEqual(row.decimals, 0);

This is a synthetic row excerpt, not a complete API response. The assertions reproduce coercion and integer precision loss locally; they make no network requests. Preserve the raw balance string. Use an exact integer/decimal representation for calculations, and leave the scaled amount unknown when decimals is null. Do not invent a symbol or infer a zero balance from missing metadata. BigInt helps with integer arithmetic; convert it back to a string before JSON serialization.

An envelope is not a token array

The documented response to GET /v1/data/{chain}/addresses/{address}/balances has data, meta, and an optional next_cursor. Only data is the token array. A bare-array parser that silently returns [] for any object can turn an integration error into a convincing empty wallet.

Handle HTTP and response-shape failures separately from a valid empty data array. Follow the opaque next_cursor unchanged until it is absent. Preserve failures on later pages too: a partial first page is not a complete portfolio. Keep null distinct from absence where the contract makes that distinction; the final page omits next_cursor.

Indexed head is not snapshot time

For balances, meta.as_of_block describes the current indexed head. It does not give the balance snapshot’s height or update time. Read meta.refreshed_at for the snapshot update time; null means stale or unknown update time. A coverage label is not a freshness guarantee.

Before choosing this endpoint for a chain, check that chain’s data_features and data_status in GET /v1/status. Unsupported coverage returns 422 no_coverage. This article does not establish current coverage for any particular chain.

Adapter cases worth retaining

Test an explicitly empty successful page, an HTTP/HTML error, an unexpected response shape, several cursor pages, a failed later page, a balance above the safe integer range, null decimals versus zero decimals, and null snapshot time. These are suggested integration cases, not completed end-to-end tests.

The wallet assets guide covers the endpoint and snapshot semantics. The public Data API schema defines UInt256String, AddressBalance, AddressBalanceListEnvelope, and Meta. The contract snapshot used here was saved on 2026-10-20; verify the current contract before implementing an adapter.

A reusable, offline-tested consumer

An optional TypeScript balance-page consumer and regression tests is now merged in BlockVectra Agent Quickstart. It preserves raw integer strings and nullable metadata, follows opaque cursors, and rejects later-page failures or conflicting known snapshot times. If any page has an unknown snapshot time, the aggregate timestamp stays unknown. The PR and main CI each passed 85 offline tests and typecheck on Node 24.21.0. This is a backend helper with a caller-supplied page reader, and has not been run as a live wallet integration.