Struct account_state::state::State

pub struct State<B> { /* 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. A checkpoint can be discarded with discard_checkpoint. All of the original backed-up values are moved into a parent checkpoint (if any).

Implementations

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
) -> TrieResult<State<B>>

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) -> usize

Create a recoverable checkpoint of this state. Return the checkpoint index.

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
) -> TrieResult<(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,
    version: U256
) -> TrieResult<()>

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) -> TrieResult<bool>

Determine whether an account exists.

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

Determine whether an account exists and if not empty.

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

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

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

Get the balance of account a.

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

Get the nonce of account a.

pub fn is_base_storage_root_unchanged(&self, a: &Address) -> TrieResult<bool>

Whether the base storage root of an account remains unchanged.

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

Get the storage root of account a.

pub fn original_storage_root(&self, a: &Address) -> TrieResult<H256>

Get the original storage root since last commit of account a.

pub fn checkpoint_storage_at(
    &self,
    start_checkpoint_index: usize,
    address: &Address,
    key: &H256
) -> TrieResult<Option<H256>>

Get the value of storage at a specific checkpoint.

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

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

pub fn original_storage_at(
    &self,
    address: &Address,
    key: &H256
) -> TrieResult<H256>

Get the value of storage after last state commitment.

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

Get accounts’ code.

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

Get an account’s code hash.

pub fn code_version(&self, a: &Address) -> TrieResult<U256>

Get an account’s code version.

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

Get accounts’ code size.

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

Add incr to the balance of account a.

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

Subtract decr from the balance of account a.

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

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

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

Increment the nonce of account a by 1.

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

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

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

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) -> TrieResult<()>

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

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
) -> TrieResult<()>

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_full(&self) -> Result<PodState, Error>

Populate a PodAccount map from this state. Warning this is not for real time use. Use of this method requires FatDB mode to be able to iterate on accounts.

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

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

pub fn require<'a>(
    &'a self,
    a: &Address,
    require_code: bool
) -> TrieResult<RefMut<'a, Account>>

Pull account a in our cache from the trie DB. require_code requires that the code be cached, too.

pub fn require_or_from<'a, F, G>(
    &'a self,
    a: &Address,
    require_code: bool,
    default: F,
    not_default: G
) -> TrieResult<RefMut<'a, Account>> where
    F: FnOnce() -> Account,
    G: FnOnce(&mut Account), 

Pull account a in our cache from the trie DB. require_code requires that the code be cached, too. If it doesn’t exist, make account equal the evaluation of default.

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

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
) -> TrieResult<(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
) -> TrieResult<(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)

impl<B: Backend> State<B>

pub fn db(&self) -> &B

Get a reference to the underlying state DB.

Trait Implementations

impl<B: Backend + Clone> Clone for State<B>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

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

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

Get the nonce of account a.

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

Get the balance of account a.

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

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

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

Get accounts’ code.