docs / walkthrough · updated 2026-08-01

Finalized heads and live views

Finalized history is monotonic. Optimistic history is not: blocks can be reorganized, blobs can disappear, and the window itself moves. BlobArchive models these as different ordering contracts instead of pretending one rule fits both.

The physical heads

The BlobArchive writer operator publishes finalized physical heads such as all, arbitrum-one, robinhood, and base. Their coverage and root may advance but do not regress during ordinary operation.

It also publishes one physical unfinalized head: a complete, bounded mutable snapshot. The initial production contract limits it to 128 slots. A higher signed publication revision can replace that snapshot, including rows and bounds.

unfinalized is global. It is not duplicated once per L2 because the entire window is small and the blob blocks are content-addressed.

“Live” describes which data the view can select, not a real-time delivery promise. The writer publishes authenticated generations in batches and public followers poll for them. With the shipped one-minute polling cadence, new blobs normally reach a local live view roughly one to two minutes after the source sees them; DHT conditions and bounded retries can occasionally extend that to several minutes. These are healthy-path expectations, not a ceiling. A publication outage can keep returning a valid but frozen generation for much longer, so alert on the age of the last accepted generation rather than on request errors. Initial synchronization and catch-up after downtime can take much longer.

A live view is local policy

live is not a fourth signed head. It is a local read view made from:

1. one selected finalized head; and
2. the authenticated unfinalized generation from the same publication document.

Below the finalized frontier, reads use the finalized head. Above it, reads use the mutable snapshot only when the publication proves a gap-free handoff.

older slots                           newest slots
|----------- selected finalized -----------|
                                      |-- unfinalized --|
                                      ^
                              proven handoff boundary

The global mutable proof is bound to the all finalized head. A filtered view such as Arbitrum One adds a retained-frontier check: its selected filtered head must reach the beginning of the mutable window. The physical proof stays true to the writer’s all handoff; chain specificity lives in the local view.

Exact-hash queries keep filtered views narrow

The shared mutable set can contain blobs from many L2s. Filtered live profiles therefore require versioned_hashes on provisional requests. Nitro already supplies those hashes.

This is not an access-control list: a caller that already knows a foreign versioned hash can retrieve it while it remains in the small shared snapshot. It does prevent a chain-specific endpoint from becoming an enumeration surface for every provisional blob.

Finalized requests remain enumerable and cacheable. Provisional responses are always Cache-Control: no-store.

Fail closed at the seam

A live view returns retryable 503, not definitive 404, when it cannot prove which side owns a slot. Causes include:

• first start before a complete mutable generation;
• a gap between the filtered finalized frontier and mutable window;
• publication quarantine or malformed handoff proof;
• a finalized rewrite or restart mismatch;
• a source-finality watermark overrun; or
• a request beyond both tips.

Do not configure a reverse proxy to convert that 503 to 404. An absence inside authenticated coverage is meaningful; an absence outside coherent coverage is not.

The response header identifies the side that answered:

• X-Bloar-Finality: finalized
• X-Bloar-Finality: provisional

Production selectors

The built-in catalog has finalized and live variants for all, Arbitrum One, Robinhood, and Base. The names are opaque keys; never parse their hyphen-separated spelling.

ethereum-mainnet-all-a
ethereum-mainnet-arb1-a
ethereum-mainnet-robinhood-a
ethereum-mainnet-base-a
ethereum-mainnet-all-live-a
ethereum-mainnet-arb1-live-a
ethereum-mainnet-robinhood-live-a
ethereum-mainnet-base-live-a

All eight select full retention and full blob verification. The -live entries add the shared mutable head and local derived view.

See follow profiles for exact selectors and the operations guide for response and rollback behavior.