Struct Archive 

pub struct Archive { /* private fields */ }

The store. One file, one process, any number of readers alongside the syncing writer.

Implementations

impl Archive

pub async fn backfill<S: BalSource + ?Sized>( &self, source: &S, addr: Address, opts: BackfillOpts, ) -> Result<BackfillReport>

Extend addr’s history backwards from its watch start. Takes the sync slot (a concurrent sync is refused and vice versa); reads stay available throughout. Every block is verified: header chained to the one above it, BAL hashed against the header.

The archive must have synced to at least the watch start, so that the block above the first one read is one the archive holds.

pub async fn backfill_many<S: BalSource + ?Sized>( &self, source: &S, addrs: &[Address], opts: BackfillOpts, ) -> Result<Vec<BackfillReport>>

Archive::backfill for several addresses in one backward walk: every block is fetched and verified once and applied to each address whose history has not reached it yet, so a protocol of N contracts costs the same RPC traffic as one. Each address keeps its own start, target, creation and report; the reports come back in input order. max_blocks bounds the blocks read by the walk as a whole.

impl Archive

pub fn storage_at( &self, addr: Address, slot: B256, block: u64, ) -> Result<StorageValue, NotAvailable>

Value of slot at the end of block. One ordered seek.

pub fn history( &self, addr: Address, slot: B256, range: Range<u64>, ) -> Result<Vec<HistoryEntry>, NotAvailable>

All recorded changes of slot in range (half-open), ascending. Bootstrap records live at start - 1 and are therefore never inside a valid range; what comes back is BAL data only.

pub fn changed_slots( &self, addr: Address, block: u64, ) -> Result<Vec<B256>, NotAvailable>

Slots of addr written in block, from the block index.

pub fn boot_state(&self, addr: Address, slot: B256) -> Result<Option<BootState>>

Bootstrap state of a slot, if it has ever been seen or proven.

impl Archive

pub async fn sync<S: BalSource + ?Sized>( &self, source: &S, state: Option<&dyn StateSource>, ) -> Result<SyncReport>

Sync from the archive head (or the earliest watch start) to the source head. state enables early bootstrap; without it, first-seen slots are left Pending and will be picked up by a later sync that has a state source — if the window has not passed by then.

A block the source reports as missing near its head ends the pass quietly (pooled gateways lag); the next pass picks it up.

pub async fn sync_step<S: BalSource + ?Sized>( &self, source: &S, state: Option<&dyn StateSource>, max_blocks: Option<u64>, ) -> Result<SyncReport>

Archive::sync that applies at most max_blocks and returns, so a caller can show progress and keep reading between steps. The pass is complete when blocks_applied is 0 or to == source_head.

pub async fn bootstrap_slot( &self, state: &dyn StateSource, addr: Address, slot: B256, ) -> Result<()>

Lazy bootstrap for a slot that never changed since watch start: prove its value at the archive head (which equals its value at start, by BAL completeness) and store it as the pre-value.

The head is read before the slot’s state is checked, and the write is skipped if a change at or before that head has been recorded, if the watch changed, or if the head block was replaced in the meantime — a sync running concurrently cannot turn a post-value into a stored pre-value.

impl Archive

pub fn rollback_to(&self, block: u64) -> Result<()>

Delete everything above block and reset head to it. Walks the block index per watched address, so the cost is proportional to the records being removed, not to the size of the archive.

If the fork is below an address’s start - 1, every proven pre-value of that address is dropped too: those proofs were taken on a branch that may have written the slot before start, so they no longer describe the canonical chain. They are re-proven when needed.

impl Archive

pub fn open(path: impl AsRef<Path>) -> Result<Self>

Open or create path with default configuration.

pub fn open_with(path: impl AsRef<Path>, config: ArchiveConfig) -> Result<Self>

Open or create path. Refuses files written with another SCHEMA_VERSION.

pub fn config(&self) -> &ArchiveConfig

Configuration this archive was opened with.

pub fn watch(&self, addr: Address, from_block: u64) -> Result<()>

Start accumulating addr from from_block (inclusive). from_block must be above the current head and above any block the sync loop is currently applying: history before now is Archive::backfill, an explicit call. An address can be watched once; change its start with Archive::unwatch first (which drops its data).

pub fn unwatch(&self, addr: Address) -> Result<()>

Stop watching and delete everything stored for addr. Taken under the watch gate; a block being applied concurrently re-checks the watchlist inside its transaction, so nothing is written for addr after this returns.

pub fn compact_file(path: impl AsRef<Path>) -> Result<bool>

Rewrite the file without free pages. redb frees pages as records are overwritten and transactions retire, but never shrinks the file on its own; after a long backfill the difference is large. Needs the file to itself: call with no Archive open on it. Returns whether anything changed.

pub fn created_at(&self, addr: Address) -> Result<Option<u64>>

Block in which addr was created, if a verified BAL showed it.

pub fn watchlist(&self) -> Result<Vec<(Address, u64)>>

Watched addresses with their start blocks.

pub fn stats(&self) -> Result<ArchiveStats>

Counts and sizes for status-style reporting. Scans the bootstrap table, so it is proportional to the number of distinct slots seen — fine for a command, not for a hot path.

pub fn head(&self) -> Result<Option<(u64, B256)>>

Last applied block and its hash, if any block was applied.