Struct TrieDB

pub struct TrieDB<F, H>
where
    F: TrieDBProvider,
    H: TrieHinter,
{
    pub fetcher: F,
    pub hinter: H,
    /* private fields */
}

A Trie DB that caches open state in-memory.

When accounts that don’t already exist within the cached TrieNode are queried, the database fetches the preimages of the trie nodes on the path to the account using the PreimageFetcher (F generic). This allows for data to be fetched in a verifiable manner given an initial trusted state root as it is needed during execution.

The TrieDB is intended to be wrapped by a State, which is then used by revm to capture state transitions during block execution.

Behavior:

• When an account is queried and the trie path has not already been opened by Self::basic, we fall through to the PreimageFetcher to fetch the preimages of the trie nodes on the path to the account. After it has been fetched, the path will be cached until the next call to Self::state_root.
• When querying for the code hash of an account, the TrieDBProvider is consulted to fetch the code hash of the account.
• When a BundleState changeset is committed to the parent State database, the changes are first applied to the State’s cache, then the trie hash is recomputed with Self::state_root.
• When the block hash of a block number is needed via Self::block_hash, the HeaderByHashFetcher is consulted to walk back to the desired block number by revealing the parent hash of block headers until the desired block number is reached, up to a maximum of BLOCK_HASH_HISTORY blocks back relative to the current parent block hash.

Example Construction:

use alloy_consensus::{Header, Sealable};
use alloy_evm::{EvmEnv, EvmFactory, block::BlockExecutorFactory};
use alloy_op_evm::{
    OpBlockExecutionCtx, OpBlockExecutorFactory, OpEvmFactory, block::OpAlloyReceiptBuilder,
};
use alloy_op_hardforks::OpChainHardforks;
use alloy_primitives::{B256, Bytes};
use kona_executor::{NoopTrieDBProvider, TrieDB};
use kona_mpt::NoopTrieHinter;
use revm::database::{State, states::bundle_state::BundleRetention};

let mock_parent_block_header = Header::default();
let trie_db =
    TrieDB::new(mock_parent_block_header.seal_slow(), NoopTrieDBProvider, NoopTrieHinter);
let executor_factory = OpBlockExecutorFactory::new(
    OpAlloyReceiptBuilder::default(),
    OpChainHardforks::op_mainnet(),
    OpEvmFactory::default(),
);
let mut state = State::builder().with_database(trie_db).with_bundle_update().build();
let evm = executor_factory.evm_factory().create_evm(&mut state, EvmEnv::default());
let executor = executor_factory.create_executor(evm, OpBlockExecutionCtx::default());

// Execute your block's transactions...
drop(executor);

state.merge_transitions(BundleRetention::Reverts);
let bundle = state.take_bundle();
let state_root = state.database.state_root(&bundle).expect("Failed to compute state root");

Fields

fetcher: F

The TrieDBProvider

hinter: H

The TrieHinter

Implementations

impl<F, H> TrieDB<F, H>

where F: TrieDBProvider, H: TrieHinter,

pub fn new(parent_block_header: Sealed<Header>, fetcher: F, hinter: H) -> Self

Creates a new TrieDB with the given root node.

pub fn take_root_node(self) -> TrieNode

Consumes Self and takes the current state root of the trie DB.

pub const fn root(&self) -> &TrieNode

Returns a shared reference to the root TrieNode of the trie DB.

pub const fn storage_roots(&self) -> &HashMap<Address, TrieNode>

Returns the mapping of Addresses to storage roots.

pub const fn parent_block_header(&self) -> &Sealed<Header>

Returns a reference to the current parent block header of the trie DB.

pub fn set_parent_block_header(&mut self, parent_block_header: Sealed<Header>)

Sets the parent block header of the trie DB. Should be called after a block has been executed and the Header has been created.

Takes

• parent_block_header: The parent block header of the current block.

pub fn state_root(&mut self, bundle: &BundleState) -> TrieDBResult<B256>

Applies a BundleState changeset to the TrieNode and recomputes the state root hash.

Takes

• bundle: The BundleState changeset to apply to the trie DB.

Returns

• Ok(B256): The new state root hash of the trie DB.
• Err(_): If the state root hash could not be computed.

pub fn get_trie_account( &mut self, address: &Address, block_number: u64, ) -> TrieDBResult<Option<TrieAccount>>

Fetches the TrieAccount of an account from the trie DB.

Takes

• address: The address of the account.

Returns

• Ok(Some(TrieAccount)): The TrieAccount of the account.
• Ok(None): If the account does not exist in the trie.
• Err(_): If the account could not be fetched.

Trait Implementations

impl<F, H> Clone for TrieDB<F, H>

where F: TrieDBProvider + Clone, H: TrieHinter + Clone,

fn clone(&self) -> TrieDB<F, H>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<F, H> Database for TrieDB<F, H>

where F: TrieDBProvider, H: TrieHinter,

type Error = TrieDBError

The database error type.

fn basic( &mut self, address: Address, ) -> Result<Option<AccountInfo>, Self::Error>

Gets basic account information.

fn code_by_hash(&mut self, code_hash: B256) -> Result<Bytecode, Self::Error>

Gets account code by its hash.

fn storage( &mut self, address: Address, index: U256, ) -> Result<U256, Self::Error>

Gets storage value of address at index.

fn block_hash(&mut self, block_number: u64) -> Result<B256, Self::Error>

Gets block hash by block number.

impl<F, H> Debug for TrieDB<F, H>

where F: TrieDBProvider + Debug, H: TrieHinter + Debug,

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

Formats the value using the given formatter.