Struct State 

pub struct State { /* private fields */ }

The rollup state, read-only.

Mutations go through the BlockWriter and ProofWriter capabilities returned by LoadedState::start; every holder of this type can only query and subscribe.

All tree and database reads go through a request-scoped StateView obtained from State::view; this type itself only exposes chain-tip queries, subscriptions, and block-store access.

Implementations

impl State

pub async fn bootstrap( genesis: GenesisBlock, data_directory: &Path, ) -> Result<()>

Bootstraps the store state, creating the database state and inserting the genesis block data.

impl State

pub fn spawn_disk_monitor(&self, shutdown: CancellationToken) -> JoinHandle<()>

Spawns a background task that periodically records the on-disk size of every store data path as OTel span attributes.

impl State

pub async fn load( data_path: &Path, storage_options: StorageOptions, ) -> Result<LoadedState, StateInitializationError>

Loads the state from the data directory.

The loaded state owns all store data structures and exposes subscription methods for sequencer and replica tasks. Call LoadedState::start on the result to spawn the block writer and obtain the usable State.

pub async fn load_with_database_options( data_path: &Path, storage_options: StorageOptions, database_options: DatabaseOptions, ) -> Result<LoadedState, StateInitializationError>

Loads the state from the data directory using explicit database options.

The loaded state owns all store data structures and exposes subscription methods for sequencer and replica tasks. Call LoadedState::start on the result to spawn the block writer and obtain the usable State.

impl State

pub async fn load_block( &self, block_num: BlockNumber, ) -> Result<Option<Vec<u8>>, DatabaseError>

Loads a block from the in-memory replica cache or block store. Return Ok(None) if the block is not found.

pub async fn load_proof( &self, block_num: BlockNumber, ) -> Result<Option<Vec<u8>>, DatabaseError>

Loads a block proof from the in-memory replica cache or block store. Returns Ok(None) if the proof is not found.

pub async fn load_proving_inputs( &self, block_num: BlockNumber, ) -> Result<Option<Vec<u8>>>

Loads serialized block proving inputs from the block store.

impl State

pub fn committed_tip(&self) -> BlockNumber

Returns the latest committed (but not necessarily proven) block number.

This is a live value: it advances independently of any StateView. Reads that must be consistent with data must use a view’s tip instead.

Ordering matters when combining this with a view: read the tip before creating the view. Tips are monotonic and the committed tip is published after its snapshot, so a view created afterwards can always serve a tip read earlier. Reading a live tip after creating a view is racy — the tip may have advanced past the view’s pinned snapshot.

pub fn proven_tip(&self) -> BlockNumber

Returns the latest block number proven in an unbroken sequence from genesis.

This is a live value published by the proof scheduler (sequencer mode) or the proof sync loop (full-node mode); it is always at or behind the committed tip.

Ordering matters when combining this with a view: read the tip before creating the view. Proofs are only applied to committed blocks and each committed tip is published after its snapshot, so a view created afterwards can always serve a proven tip read earlier. Reading it after creating a view is racy — a block may commit and prove concurrently, putting the proven tip past the view’s pinned snapshot.

pub fn subscribe_committed_tip(&self) -> Receiver<BlockNumber>

Returns a watch receiver that wakes every time a new block is committed.

pub fn subscribe_proven_tip(&self) -> Receiver<BlockNumber>

Returns a watch receiver that wakes every time the proven-in-sequence tip advances.

impl State

pub fn view(&self) -> StateView

Returns a read view pinned at the current chain tip (wait-free, no lock required).

The view is frozen: it is unaffected if the writer publishes a new snapshot while it is held.

Use this only for one single-expression read (state.view().get_account(..)), where the temporary view drops at the end of the statement. Two view() calls observe potentially different snapshots — a block can commit between them — so reads that must be mutually consistent (e.g. a query and the tip it was served at) must share one view via Self::with_view. Binding a view to a variable is also discouraged: it keeps the snapshot generation pinned until the end of the scope.

pub async fn with_view<R>(&self, f: impl AsyncFnOnce(&StateView) -> R) -> R

Runs a read operation over a view pinned at the current chain tip, dropping the view — and releasing its snapshot generation — as soon as the operation completes.

This is the required form whenever multiple reads must observe the same snapshot: the closure’s view is one consistent generation, whereas consecutive Self::view calls may straddle a commit. The typical case is pairing a query with StateView::tip so a response reports exactly the height it was served at.

The closure receives a shared reference, so the view cannot escape the call, and the snapshot is not pinned through unrelated work that follows (e.g. response encoding). A single read doesn’t need it — state.view().get_account(..) drops its temporary view at the end of the statement.

Work in the closure should be kept to low-complexity compute over the view, ideally with no I/O and no other .await points. Anything slower holds the pinned snapshot, and therefore its underlying RocksDB snapshot, for as long as it runs. The snapshot’s lifetime is logged as a warning if held too long, but that is a backstop, not a substitute for keeping closures short.