Skip to main content

Index blocks and events

Use Ethereum RPC for ordinary explorer/application indexing and native witnesses when the client needs authenticated record proofs.

For application queries, Joltzu plans its own Envio and The Graph endpoints on testnet and mainnet. URLs are TBD. The steps below cover building your own indexer from RPC.

Follow committed blocks​

Poll eth_blockNumber or subscribe to newHeads over the local WebSocket endpoint. Example request sent after opening ws://127.0.0.1:30400:

{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}

Subscriptions are connection-scoped. On disconnect, reconnect and backfill from your persisted last processed height. A bounded session can close on budget exhaustion; it does not imply a chain reorganization.

Fetch a bounded log range​

curl http://127.0.0.1:30400 \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"eth_getLogs","params":[{"fromBlock":"0x0","toBlock":"0x10"}]}'

Use committed heights that exist on your network. Local Ethereum log queries span at most 1,024 blocks and return at most 10,000 logs or 960 KiB, which keeps every response inside the 1 MiB transport limit. Split ranges on -32005. eth_getFilterChanges returns whole blocks only, and the next poll resumes at the first block it left out; it fails with -32005 only when one block alone exceeds the limits. Address/topic filters reduce work.

Persist before advancing your cursor​

For Ethereum logs, deduplicate by chain identity, Ethereum block hash and logIndex. Native logs use the certified Joltzu block hash and native ordinal. Keep those namespaces explicit. Acknowledge only after durable effects; reconnect delivery may repeat an event.

Avoid counting JOLT twice​

Native JOLT movements produce system logs. ERC-20 adapter calls may additionally produce token logs representing that same movement. Choose a primary accounting stream and reconcile adapter events. Transaction call value alone misses internal transfers. Fees are not Transfer logs.

The migration guide lists emitter identities, shared 18-decimal units and pitfalls for native/ERC-20 accounting.

Remote services and containers​

The local endpoint validates Host and rejects web-page Origins. A containerized indexer requires a carefully configured relay or the authenticated gateway; the node is not directly bound to a public interface. Public gateway allowlists and credentials can be stricter than local method support.