docs(flashblocks): clarify fallback behavior

[skyc1e]

Adds fallback guidance for apps that use Flashblocks through public RPCs or third-party node providers.

• treats Flashblocks updates and pending reads as optimistic UX state
• lists stall, lag, and reconnect conditions where apps should fall back
• keeps receipt polling and latest reads as the source of truth for final UI state

Addresses base/base#3616

Checked:

• git diff --check
• npx mint validate (fails on an existing docs.json navigation reference to missing get-started/build-app)

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 0 Sum 1

[schoolkamsergj]

Thanks for picking this up, @skye1e — this is exactly the gap I raised in base/base#3616, and the optimistic-vs-canonical split here reads really well. As the author of that issue, big +1 to landing this.

A few small, additive suggestions that came out of the discussion on #3616 — all optional and non-blocking:

1. Concrete stall-detection thresholds. It helps app devs a lot to have suggested defaults rather than just "if the stream stalls." Something like:

• No newFlashblocks event for 3–5s, OR
• pendingBlockNumber does not advance for 3–5s, OR
• latestBlockNumber - pendingBlockNumber > 2–5 blocks

Framing these as suggested defaults (not hard requirements) keeps it practical without over-prescribing.

2. Manual escape hatch for public RPC. Worth calling out explicitly: always surface the tx hash immediately after eth_sendRawTransaction and offer a "View on BaseScan" link, so a stalled pending stream never leaves users on an infinite spinner (this is the failure mode that drives double-submits).

3. Second RPC in the fallback path. As @Metavcl noted in the issue thread, teams on public RPC can keep a second Base RPC (e.g. a third-party provider) on the latest + eth_getTransactionReceipt safety path while Flashblocks powers the optimistic UI. Might be a nice one-liner in the "public RPC" context.

4. One-liner worth making prominent. The rule that resonated most in the thread: "pending is for speed, receipt is the source of truth." Could work well as a callout at the top of the section.

None of these should block merge — happy to see it go in as-is and iterate after. Thanks again for driving this.