Resolve a cursor the hub declined without waiting on files

[sduchesneau]

Problem

NewCursorResolver asks the hub first and falls back to bstream.NewFileSourceFromCursor when it returns nil. The hub returns nil for two different reasons, and one of them is not "this cursor is historical": it also declines a cursor whose block number it covers but whose ID it has never seen — a corrupted or forged cursor, or one carried over from a chain this process never served.

That file source cannot start before the merged-blocks bundle covering the cursor's block number is written. Near chain head it is not, so the request sits silent for a whole bundle — measured at ~16 minutes against mainnet.eth.streamingfast.io with a cursor whose block hash had its last 4 hex rewritten — and the files cannot resolve it when they arrive either.

Reproduced locally on firehose-core/devel/standard with the merger stopped, so the bundle never lands: develop returns nothing at all in 90s, no undo, no error.

Change

Before the file-source fallback, ask whether anything can still produce that block (bstream.CheckCursorResolvable, added in bstream#63):

• the hub is authoritative over [LowestBlockNum, HeadNum], so a cursor block in that range whose ID it does not know is on no chain it ever saw;
• the forked-blocks store is consulted before giving up, since a hub restarted after a fork no longer holds it while the store does;
• both empty resolves to cursor.LIB, the existing "resolver failed" outcome, which resolveStartBlockNum turns into a BlockUndoSignal to LIB plus a start block of LIB+1.

The client gets the undo immediately instead of after the merger catches up — the same outcome, minus the twenty minutes.

A cursor above the hub's head is deliberately not that case: the block exists, this instance has not reached it, which is what a client reconnecting to an instance a few blocks behind the one that served it looks like. bstream waits it out briefly and reports ErrCursorAboveHead; this PR propagates that as connect.CodeUnavailable (retryable) instead of the usual CodeInvalidArgument, so a lagging tier1 neither kills a sink nor reverts one that is ahead of it.

Measured, local stack with the merger stopped

	result
develop	0 blocks in 90s, no undo
this branch, unknown hash inside the hub's range	UNDO … number:2910 then blocks, immediate
this branch, unknown hash 500 blocks above head	5s wait, then code = Unavailable, which the sink logs as a retryable error

Verified against the real thing too: the same forged-cursor scenario on mainnet.eth.streamingfast.io is what surfaced this.

[sduchesneau]

🔍 Vulnerabilities of ghcr.io/streamingfast/substreams:15ee822

📦 Image Reference ghcr.io/streamingfast/substreams:15ee822

digest	sha256:7941a3088149abd9dd7e774038458f8c2c8cd59851f8c2843c88e77b0bec0db8
vulnerabilities
platform	linux/amd64
size	123 MB
packages	382

📦 Base Image oisupport/staging-amd64:24.04

also known as	a215e986b44aae6f10795ded1e39ce93d9c236d8163d21a522ffd0ab3659f546 noble noble-20260730.1
digest	sha256:019e8eb29a85e74d64925745884f2ec79aa27e3feab36353d24656f4d6b89467
vulnerabilities

[maoueh]

So are we double doing the CheckCursorResolvable now? Isn't NewFileSourceFromCursor doing the same?

[sduchesneau]

The FileSourceFromCursor just determines that the file is in the future, so it waits for the merged block to appear...
Also, it cannot return an error, only a filesource or nil.

So that's 20 minutes on eth-mainnet !

CheckCursorResolvable checks if we are in the HEAD section, if so: if a forked-block contains it. If we are older than the LIB, we return nil (not our concern) so it goes back to the fileSourceFromCursor.

This prevents waiting for merged-blocks to be produced.