Struct ethcore::state::State

pub struct State<B: Backend> { /* fields omitted */ }

Representation of the entire state of all accounts in the system.

State can work together with StateDB to share account cache.

Local cache contains changes made locally and changes accumulated locally from previous commits. Global cache reflects the database state and never contains any changes.

Cache items contains account data, or the flag that account does not exist and modification state (see AccountState)

Account data can be in the following cache states:

• In global but not local - something that was queried from the database, but never modified
• In local but not global - something that was just added (e.g. new account)
• In both with the same value - something that was changed to a new value, but changed back to a previous block in the same block (same State instance)
• In both with different values - something that was overwritten with a new value.

All read-only state queries check local cache/modifications first, then global state cache. If data is not found in any of the caches it is loaded from the DB to the local cache.

**** IMPORTANT ************************************************************* All the modifications to the account data must set the Dirty state in the AccountEntry. This is done in require and require_or_from. So just use that.

---

Upon destruction all the local cache data propagated into the global cache. Propagated items might be rejected if current state is non-canonical.

State checkpointing.

A new checkpoint can be created with checkpoint(). checkpoints can be created in a hierarchy. When a checkpoint is active all changes are applied directly into cache and the original value is copied into an active checkpoint. Reverting a checkpoint with revert_to_checkpoint involves copying original values from the latest checkpoint back into cache. The code takes care not to overwrite cached storage while doing that. checkpoint can be discarded with discard_checkpoint. All of the orignal backed-up values are moved into a parent checkpoint (if any).

Methods

impl<B: Backend> State<B>

pub fn new(db: B, account_start_nonce: U256, factories: Factories) -> State<B>

Creates new state with empty state root Used for tests.

pub fn from_existing(     db: B,     root: H256,     account_start_nonce: U256,     factories: Factories ) -> Result<State<B>, TrieError>

Creates new state with existing state root

pub fn vm_factory(&self) -> VmFactory

Get a VM factory that can execute on this state.

pub fn checkpoint(&mut self)

Create a recoverable checkpoint of this state.

pub fn discard_checkpoint(&mut self)

Merge last checkpoint with previous.

pub fn revert_to_checkpoint(&mut self)

Revert to the last checkpoint and discard it.

pub fn drop(self) -> (H256, B)

Destroy the current object and return root and database.

pub fn into_account(     self,     account: &Address ) -> Result<(Option<Arc<Bytes>>, HashMap<H256, H256>)>

Destroy the current object and return single account data.

pub fn root(&self) -> &H256

Return reference to root

pub fn new_contract(     &mut self,     contract: &Address,     balance: U256,     nonce_offset: U256 )

Create a new contract at address contract. If there is already an account at the address it will have its code reset, ready for init_code().

pub fn kill_account(&mut self, account: &Address)

Remove an existing account.

pub fn exists(&self, a: &Address) -> Result<bool>

Determine whether an account exists.

pub fn exists_and_not_null(&self, a: &Address) -> Result<bool>

Determine whether an account exists and if not empty.

pub fn exists_and_has_code_or_nonce(&self, a: &Address) -> Result<bool>

Determine whether an account exists and has code or non-zero nonce.

pub fn balance(&self, a: &Address) -> Result<U256>

Get the balance of account a.

pub fn nonce(&self, a: &Address) -> Result<U256>

Get the nonce of account a.

pub fn storage_root(&self, a: &Address) -> Result<Option<H256>>

Get the storage root of account a.

pub fn storage_at(&self, address: &Address, key: &H256) -> Result<H256>

Mutate storage of account address so that it is value for key.

pub fn code(&self, a: &Address) -> Result<Option<Arc<Bytes>>>

Get accounts' code.

pub fn code_hash(&self, a: &Address) -> Result<H256>

Get an account's code hash.

pub fn code_size(&self, a: &Address) -> Result<Option<usize>>

Get accounts' code size.

pub fn add_balance(     &mut self,     a: &Address,     incr: &U256,     cleanup_mode: CleanupMode ) -> Result<()>

Add incr to the balance of account a.

pub fn sub_balance(     &mut self,     a: &Address,     decr: &U256,     cleanup_mode: &mut CleanupMode ) -> Result<()>

Subtract decr from the balance of account a.

pub fn transfer_balance(     &mut self,     from: &Address,     to: &Address,     by: &U256,     cleanup_mode: CleanupMode ) -> Result<()>

Subtracts by from the balance of from and adds it to that of to.

pub fn inc_nonce(&mut self, a: &Address) -> Result<()>

Increment the nonce of account a by 1.

pub fn set_storage(&mut self, a: &Address, key: H256, value: H256) -> Result<()>

Mutate storage of account a so that it is value for key.

pub fn init_code(&mut self, a: &Address, code: Bytes) -> Result<()>

Initialise the code of account a so that it is code. NOTE: Account should have been created with new_contract.

pub fn reset_code(&mut self, a: &Address, code: Bytes) -> Result<()>

Reset the code of account a so that it is code.

pub fn apply(     &mut self,     env_info: &EnvInfo,     machine: &Machine,     t: &SignedTransaction,     tracing: bool ) -> ApplyResult<FlatTrace, VMTrace>

Execute a given transaction, producing a receipt and an optional trace. This will change the state accordingly.

pub fn apply_with_tracing<V, T>(     &mut self,     env_info: &EnvInfo,     machine: &Machine,     t: &SignedTransaction,     tracer: T,     vm_tracer: V ) -> ApplyResult<T::Output, V::Output> where     T: Tracer,     V: VMTracer,

Execute a given transaction with given tracer and VM tracer producing a receipt and an optional trace. This will change the state accordingly.

pub fn commit(&mut self) -> Result<(), Error>

Commits our cached account changes into the trie.

pub fn clear(&mut self)

Clear state cache

pub fn kill_garbage(     &mut self,     touched: &HashSet<Address>,     remove_empty_touched: bool,     min_balance: &Option<U256>,     kill_contracts: bool ) -> Result<()>

Remove any touched empty or dust accounts.

pub fn populate_from(&mut self, accounts: PodState)

Populate the state from accounts. Used for tests.

pub fn to_pod(&self) -> PodState

Populate a PodAccount map from this state.

pub fn to_pod_diff<X: Backend>(&mut self, query: &State<X>) -> Result<PodState>

Populate a PodAccount map from this state, with another state as the account and storage query.

pub fn diff_from<X: Backend>(&self, orig: State<X>) -> Result<StateDiff>

Returns a StateDiff describing the difference from orig to self. Consumes self.

pub fn patch_account(     &self,     a: &Address,     code: Arc<Bytes>,     storage: HashMap<H256, H256> ) -> Result<()>

Replace account code and storage. Creates account if it does not exist.

impl<B: Backend> State<B>

pub fn prove_account(     &self,     account_key: H256 ) -> Result<(Vec<Bytes>, BasicAccount)>

Prove an account's existence or nonexistence in the state trie. Returns a merkle proof of the account's trie node omitted or an encountered trie error. If the account doesn't exist in the trie, prove that and return defaults. Requires a secure trie to be used for accurate results. account_key == keccak(address)

pub fn prove_storage(     &self,     account_key: H256,     storage_key: H256 ) -> Result<(Vec<Bytes>, H256)>

Prove an account's storage key's existence or nonexistence in the state. Returns a merkle proof of the account's storage trie. Requires a secure trie to be used for correctness. account_key == keccak(address) storage_key == keccak(key)

Trait Implementations

impl<B: Backend> StateInfo for State<B>

fn nonce(&self, a: &Address) -> Result<U256>

Get the nonce of account a.

fn balance(&self, a: &Address) -> Result<U256>

Get the balance of account a.

fn storage_at(&self, address: &Address, key: &H256) -> Result<H256>

Mutate storage of account address so that it is value for key.

fn code(&self, address: &Address) -> Result<Option<Arc<Bytes>>>

Get accounts' code.

impl<B: Backend> Debug for State<B>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Clone for State<StateDB>

fn clone(&self) -> State<StateDB>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.