1. Ingest the chain tip
A chain-specific data service reads a configured upstream source. For EVM data, the current service reads an RPC endpoint. It exposes blocks, fork signals, and finality signals to HotblocksDB. A HotblocksDB dataset can use more than one data service as a redundant source. HotblocksDB checks structural consistency such as block ordering, parent-hash linkage, finality monotonicity, and agreement between configured sources. It does not validate chain consensus rules or independently decide which fork is canonical. Block contents, canonical-fork selection, and finality ultimately come from the configured sources.2. Maintain one recent chain window
For each dataset, HotblocksDB stores a bounded and contiguous window near the chain head. A normal update extends the window. When a source reports a fork, HotblocksDB replaces the affected suffix as one committed transition. It exposes one canonical chain at a time, not several competing forks. Finality and retention are separate. Finality prevents later fork processing from altering the finalized prefix that remains in the window. Retention can still remove old finalized blocks because HotblocksDB is not the archive.3. Choose one source for a request
Portal uses the request’s first block and the archival head from its current Network view:- if the first block is at or below the archival head, Portal sends the request through the archival worker path;
- if the first block is above the archival head and the dataset has a real-time attachment, Portal forwards the request to HotblocksDB;
- if neither source can cover the requested start, Portal returns no data or the relevant source error.
4. Continue across forks
The client resumes from the block after the last block it accepted and can include that block’s hash asparentBlockHash. HotblocksDB checks the anchor against its
current chain. If a reorganization changed the parent, the request returns a
conflict with recent canonical-chain information so the client can find a shared
ancestor and resume.
The server does not keep a cursor between requests. The block number and parent
hash supplied by the client are the continuation state.
5. Advance retention from scheduler status
With API-controlled retention, Hotblocks-retain reads each dataset’s last indexed block from Network scheduler status. After the assignment’s effective time plus a configured delay, it sends that height to HotblocksDB as the new retention lower bound. This moves the HotblocksDB window forward after the archival path reports the data in its indexed chunks. The scheduler height shows that the chunk has been indexed for assignment. It is not proof that every assigned worker has finished downloading that chunk. The two paths can still have a temporary gap. If the requested block is above the archival head but below HotblocksDB’s first retained block, Portal treats it as no data rather than skipping ahead.6. Stream failures without changing sources
Portal forwards a successful HotblocksDB response as a stream instead of buffering the complete response. It can replay the upstream request once when a connection fails before any response headers arrive. It does not replay after response data has started because that could duplicate a prefix. A later failure therefore ends the response, and the client resumes from its last accepted block. A HotblocksDB failure affects requests routed to the real-time path. It does not move those requests to archival workers when their first block is above the archival head.Implementation sources
- Portal source-selection and forwarding code
- Portal Hotblocks client and replay behavior
- HotblocksDB ingestion and dataset configuration
- HotblocksDB query implementation
- Hotblocks-retain implementation
- Scheduler dataset-height calculation