Struct StateManager 

pub struct StateManager<DB> {
    cs: Arc<ChainStore<DB>>,
    cache: TipsetStateCache<StateOutputValue>,
    beacon: Arc<BeaconSchedule>,
    engine: Arc<MultiEngine>,
    receipt_event_cache_handler: Box<dyn TipsetReceiptEventCacheHandler>,
}

State manager handles all interactions with the internal Filecoin actors state. This encapsulates the ChainStore functionality, which only handles chain data, to allow for interactions with the underlying state of the chain. The state manager not only allows interfacing with state, but also is used when performing state transitions.

Fields

cs: Arc<ChainStore<DB>>

Chain store

cache: TipsetStateCache<StateOutputValue>

This is a cache which indexes tipsets to their calculated state output (state root, receipt root).

beacon: Arc<BeaconSchedule>

engine: Arc<MultiEngine>

receipt_event_cache_handler: Box<dyn TipsetReceiptEventCacheHandler>

Handler for caching/retrieving tipset events and receipts.

Implementations

impl<DB> StateManager<DB>

where DB: Blockstore,

pub fn get_sectors_for_winning_post( &self, st: &Cid, nv: NetworkVersion, miner_address: &Address, rand: Randomness, ) -> Result<Vec<ExtendedSectorInfo>, Error>

Retrieves and generates a vector of sector info for the winning PoSt verification.

impl<DB> StateManager<DB>

where DB: Blockstore,

pub fn new(cs: Arc<ChainStore<DB>>) -> Result<Self, Error>

pub fn new_with_engine( cs: Arc<ChainStore<DB>>, engine: Arc<MultiEngine>, ) -> Result<Self, Error>

pub fn heaviest_tipset(&self) -> Arc<Tipset>

Returns the currently tracked heaviest tipset.

pub fn maybe_rewind_heaviest_tipset(&self) -> Result<()>

Returns the currently tracked heaviest tipset and rewind to a most recent valid one if necessary. A valid head has - state tree in the blockstore - actor bundle version in the state tree that matches chain configuration

fn maybe_rewind_heaviest_tipset_once(&self) -> Result<bool>

pub fn populate_cache(&self)

pub fn beacon_schedule(&self) -> &Arc<BeaconSchedule>

pub fn get_network_version(&self, epoch: i64) -> NetworkVersion

Returns network version for the given epoch.

pub fn get_state_tree(&self, state_cid: &Cid) -> Result<StateTree<DB>>

Gets the state tree

pub fn get_actor( &self, addr: &Address, state_cid: Cid, ) -> Result<Option<ActorState>>

Gets actor from given Cid, if it exists.

pub fn get_actor_state<S: LoadActorStateFromBlockstore>( &self, ts: &Tipset, ) -> Result<S>

Gets actor state from implicit actor address

pub fn get_actor_state_from_address<S: LoadActorStateFromBlockstore>( &self, ts: &Tipset, actor_address: &Address, ) -> Result<S>

Gets actor state from explicit actor address

pub fn get_required_actor( &self, addr: &Address, state_cid: Cid, ) -> Result<ActorState>

Gets required actor from given Cid.

pub fn blockstore(&self) -> &Arc<DB>

Returns a reference to the state manager’s Blockstore.

pub fn blockstore_owned(&self) -> Arc<DB>

pub fn chain_store(&self) -> &Arc<ChainStore<DB>>

Returns reference to the state manager’s ChainStore.

pub fn chain_index(&self) -> &Arc<ChainIndex<Arc<DB>>>

Returns reference to the state manager’s ChainIndex.

pub fn chain_config(&self) -> &Arc<ChainConfig>

Returns reference to the state manager’s ChainConfig.

pub fn chain_rand(&self, tipset: Arc<Tipset>) -> ChainRand<DB>

pub fn get_network_state_name(&self, state_cid: Cid) -> Result<StateNetworkName>

Returns the internal, protocol-level network chain from the state.

pub fn is_miner_slashed( &self, addr: &Address, state_cid: &Cid, ) -> Result<bool, Error>

Returns true if miner has been slashed or is considered invalid.

pub fn get_miner_work_addr( &self, state_cid: Cid, addr: &Address, ) -> Result<Address, Error>

Returns raw work address of a miner given the state root.

pub fn get_power( &self, state_cid: &Cid, addr: Option<&Address>, ) -> Result<Option<(Claim, Claim)>, Error>

Returns specified actor’s claimed power and total network power as a tuple.

pub fn get_all_sectors( self: &Arc<Self>, addr: &Address, ts: &Tipset, ) -> Result<Vec<SectorOnChainInfo>>

impl<DB> StateManager<DB>

where DB: Blockstore + Send + Sync + 'static,

pub async fn tipset_state( self: &Arc<Self>, tipset: &Arc<Tipset>, ) -> Result<(Cid, Cid)>

Returns the pair of (state root, message receipt root). This will either be cached or will be calculated and fill the cache. Tipset state for a given tipset is guaranteed not to be computed twice.

pub async fn tipset_state_output( self: &Arc<Self>, tipset: &Arc<Tipset>, ) -> Result<StateOutput>

fn update_cache_with_state_output( &self, key: &TipsetKey, state_output: &StateOutput, )

update the receipt and events caches

pub async fn tipset_message_receipts( self: &Arc<Self>, tipset: &Arc<Tipset>, ) -> Result<Vec<Receipt>>

pub async fn tipset_state_events( self: &Arc<Self>, tipset: &Arc<Tipset>, events_root: Option<&Cid>, ) -> Result<StateEvents>

fn call_raw( self: &Arc<Self>, msg: &Message, rand: ChainRand<DB>, tipset: &Arc<Tipset>, ) -> Result<ApiInvocResult, Error>

pub fn call( self: &Arc<Self>, message: &Message, tipset: Option<Arc<Tipset>>, ) -> Result<ApiInvocResult, Error>

runs the given message and returns its result without any persisted changes.

pub async fn apply_on_state_with_gas( self: &Arc<Self>, tipset: Option<Arc<Tipset>>, msg: Message, ) -> Result<ApiInvocResult>

pub async fn call_with_gas( self: &Arc<Self>, message: &mut ChainMessage, prior_messages: &[ChainMessage], tipset: Option<Arc<Tipset>>, trace_config: VMTrace, ) -> Result<(InvocResult, ApplyRet, Duration), Error>

Computes message on the given Tipset state, after applying other messages and returns the values computed in the VM.

pub async fn replay( self: &Arc<Self>, ts: Arc<Tipset>, mcid: Cid, ) -> Result<ApiInvocResult, Error>

Replays the given message and returns the result of executing the indicated message, assuming it was executed in the indicated tipset.

pub fn replay_blocking( self: &Arc<Self>, ts: Arc<Tipset>, mcid: Cid, ) -> Result<ApiInvocResult, Error>

Blocking version of replay

pub fn eligible_to_mine( &self, address: &Address, base_tipset: &Tipset, lookback_tipset: &Tipset, ) -> Result<bool, Error>

Checks the eligibility of the miner. This is used in the validation that a block’s miner has the requirements to mine a block.

pub async fn compute_tipset_state( self: &Arc<Self>, tipset: Arc<Tipset>, callback: Option<impl FnMut(MessageCallbackCtx<'_>) -> Result<()> + Send + 'static>, enable_tracing: VMTrace, ) -> Result<StateOutput, Error>

Conceptually, a Tipset consists of blocks which share an epoch. Each block contains messages, which are executed by the Filecoin Virtual Machine.

VM message execution essentially looks like this:

state[N-900..N] * message = state[N+1]

The states above are stored in the IPLD Blockstore, and can be referred to by a Cid - the state root. The previous 900 states (configurable, see https://docs.filecoin.io/reference/general/glossary/#finality) can be queried when executing a message, so a store needs at least that many. (a snapshot typically contains 2000, for example).

Each message costs FIL to execute - this is gas. After execution, the message has a receipt, showing how much gas was spent. This is similarly a Cid into the block store.

For details, see the documentation for apply_block_messages.

pub fn compute_tipset_state_blocking( &self, tipset: Arc<Tipset>, callback: Option<impl FnMut(MessageCallbackCtx<'_>) -> Result<()>>, enable_tracing: VMTrace, ) -> Result<StateOutput, Error>

Blocking version of compute_tipset_state

pub async fn compute_state( self: &Arc<Self>, height: i64, messages: Vec<Message>, tipset: Arc<Tipset>, callback: Option<impl FnMut(MessageCallbackCtx<'_>) -> Result<()> + Send + 'static>, enable_tracing: VMTrace, ) -> Result<StateOutput, Error>

pub fn compute_state_blocking( &self, height: i64, messages: Vec<Message>, tipset: Arc<Tipset>, callback: Option<impl FnMut(MessageCallbackCtx<'_>) -> Result<()>>, enable_tracing: VMTrace, ) -> Result<StateOutput, Error>

Blocking version of compute_state

fn tipset_executed_message( &self, tipset: &Tipset, message: &ChainMessage, allow_replaced: bool, ) -> Result<Option<Receipt>, Error>

Check if tipset had executed the message, by loading the receipt based on the index of the message in the block.

fn check_search( &self, current: Arc<Tipset>, message: &ChainMessage, look_back_limit: Option<i64>, allow_replaced: Option<bool>, ) -> Result<Option<(Arc<Tipset>, Receipt)>, Error>

fn search_back_for_message( &self, current: Arc<Tipset>, message: &ChainMessage, look_back_limit: Option<i64>, allow_replaced: Option<bool>, ) -> Result<Option<(Arc<Tipset>, Receipt)>, Error>

pub fn get_receipt( &self, tipset: Arc<Tipset>, msg: Cid, ) -> Result<Receipt, Error>

Returns a message receipt from a given tipset and message CID.

pub async fn wait_for_message( self: &Arc<Self>, msg_cid: Cid, confidence: i64, look_back_limit: Option<i64>, allow_replaced: Option<bool>, ) -> Result<(Option<Arc<Tipset>>, Option<Receipt>), Error>

WaitForMessage blocks until a message appears on chain. It looks backwards in the chain to see if this has already happened. It guarantees that the message has been on chain for at least confidence epochs without being reverted before returning.

pub async fn search_for_message( self: &Arc<Self>, from: Option<Arc<Tipset>>, msg_cid: Cid, look_back_limit: Option<i64>, allow_replaced: Option<bool>, ) -> Result<Option<(Arc<Tipset>, Receipt)>, Error>

pub fn get_bls_public_key( db: &Arc<DB>, addr: &Address, state_cid: Cid, ) -> Result<BlsPublicKey, Error>

Returns a BLS public key from provided address

pub fn lookup_id( &self, addr: &Address, ts: &Tipset, ) -> Result<Option<Address>, Error>

Looks up ID Address from the state at the given Tipset.

pub fn lookup_required_id( &self, addr: &Address, ts: &Tipset, ) -> Result<Address, Error>

Looks up required ID Address from the state at the given Tipset.

pub fn market_state(&self, ts: &Tipset) -> Result<State, Error>

Retrieves market state

pub fn market_balance( &self, addr: &Address, ts: &Tipset, ) -> Result<MarketBalance, Error>

Retrieves market balance in escrow and locked tables.

pub fn miner_info( &self, addr: &Address, ts: &Tipset, ) -> Result<MinerInfo, Error>

Retrieves miner info.

pub fn miner_faults( &self, addr: &Address, ts: &Tipset, ) -> Result<BitField, Error>

Retrieves miner faults.

pub fn miner_recoveries( &self, addr: &Address, ts: &Tipset, ) -> Result<BitField, Error>

Retrieves miner recoveries.

fn all_partition_sectors( &self, addr: &Address, ts: &Tipset, get_sector: impl Fn(Partition<'_>) -> BitField, ) -> Result<BitField, Error>

pub fn miner_power( &self, addr: &Address, ts: &Tipset, ) -> Result<MinerPower, Error>

Retrieves miner power.

pub async fn resolve_to_key_addr( self: &Arc<Self>, addr: &Address, ts: &Arc<Tipset>, ) -> Result<Address, Error>

Similar to resolve_to_key_addr in the forest_vm crate::state_manager but does not allow Actor type of addresses. Uses ts to generate the VM state.

pub async fn miner_get_base_info( self: &Arc<Self>, beacon_schedule: &BeaconSchedule, tipset: Arc<Tipset>, addr: Address, epoch: i64, ) -> Result<Option<MiningBaseInfo>>

pub fn miner_has_min_power( &self, policy: &Policy, addr: &Address, ts: &Tipset, ) -> Result<bool>

Checks power actor state for if miner meets consensus minimum requirements.

pub fn validate_range( self: &Arc<Self>, epochs: RangeInclusive<i64>, ) -> Result<()>

Validates all tipsets at epoch start..=end behind the heaviest tipset.

This spawns rayon::current_num_threads threads to do the compute-heavy work of tipset validation.

What is validation?

Every state transition returns a new state root, which is typically retained in, e.g., snapshots. For “full” snapshots, all state roots are retained. For standard snapshots, the last 2000 or so state roots are retained.

receipts meanwhile, are typically ephemeral, but each tipset knows the receipt root (hash) of the previous tipset.

This function takes advantage of that fact to validate tipsets:

• tipset[N] claims that receipt_root[N-1] should be 0xDEADBEEF
• find tipset[N-1], and perform its state transition to get the actual receipt_root
• assert that they match

See Self::compute_tipset_state_blocking for an explanation of state transitions.

Known issues

This function is blocking, but we do observe threads waiting and synchronizing. This is suspected to be due something in the VM or its WASM runtime.

pub fn validate_tipsets<T>(self: &Arc<Self>, tipsets: T) -> Result<()>

where T: Iterator<Item = Arc<Tipset>> + Send,

pub fn get_verified_registry_actor_state(&self, ts: &Tipset) -> Result<State>

pub fn get_claim( &self, addr: &Address, ts: &Tipset, claim_id: ClaimID, ) -> Result<Option<Claim>>

pub fn get_all_claims(&self, ts: &Tipset) -> Result<HashMap<ClaimID, Claim>>

pub fn get_allocation( &self, addr: &Address, ts: &Tipset, allocation_id: u64, ) -> Result<Option<Allocation>>

pub fn get_all_allocations( &self, ts: &Tipset, ) -> Result<HashMap<u64, Allocation>>

pub fn verified_client_status( &self, addr: &Address, ts: &Tipset, ) -> Result<Option<DataCap>>

pub async fn resolve_to_deterministic_address( self: &Arc<Self>, address: Address, ts: Arc<Tipset>, ) -> Result<Address>

pub fn execution_trace( &self, tipset: &Tipset, ) -> Result<(Cid, Vec<ApiInvocResult>)>

fn try_lookup_state_from_next_tipset( &self, tipset: &Tipset, ) -> Option<StateOutputValue>

Attempts to lookup the state and receipt root of the next tipset. This is a performance optimization to avoid recomputing the state and receipt root by checking the blockstore. It only checks the immediate next epoch, as this is the most likely place to find a child.